@theronap/cortex-mcp 0.9.47 → 0.9.49

package/lib/editors/claude.mjs

@@ -15,11 +15,34 @@ export function mergeClaudeMcp(existing, spec, token) {
   return cfg
 }
 
+/** The Cortex tools every seat may run WITHOUT a permission prompt: the read surface, the live
+ *  authoring core, and trivially-reversible maintenance. The contract this enforces: authoring is
+ *  EXPECTED agent behavior — a page update must never stall on a yes/no dialog the user won't read
+ *  (the ask-permission failure mode is how pages go stale). Safe because every page edit is
+ *  CAS-protected + snapshotted (page_revisions → page_history/rollback_page).
+ *  Deliberately EXCLUDED — these keep prompting: send_imessage (external side effect),
+ *  set_page_privacy / set_record_privacy / grant_page_access (visibility widening — the
+ *  unowned-project accessible-default sharp edge, 2026-07-02), rollback_page, decide_page_merge /
+ *  decide_file_request / request_file / get_file, create_brain / set_active_brain, alias_page,
+ *  set_writing_style. */
+export const CORTEX_ALLOWED_TOOLS = [
+  // read surface
+  'grep', 'read_page', 'my_context', 'project_status', 'session_context', 'search_org',
+  'list_records', 'page_history', 'timeline_pull', 'my_brains', 'my_sessions', 'writing_style',
+  'code_graph_query', 'my_retier_notices', 'list_page_grants', 'file_requests', 'page_merge_requests',
+  // live authoring core
+  'authoring_context', 'author', 'log_session',
+  // routine, reversible maintenance
+  'set_page_validity', 'snooze_red_link', 'attribute_thread',
+].map((t) => `mcp__cortex__${t}`)
+
 /** Merge Cortex's Claude Code hooks into a ~/.claude/settings.json object. Pure + idempotent: drops
  *  any prior cortex entry (old token/path/version) from each hook array before appending the current
  *  one — capture (Stop), status + skills-repair + snapshot-context (SessionStart), precompact
  *  (PreCompact). Commands carry NO inline token (each subcommand self-resolves it). Mirrors setup.mjs
- *  step 2 exactly; foreign hooks are never touched. */
+ *  step 2 exactly; foreign hooks are never touched. Also merges the CORTEX_ALLOWED_TOOLS permission
+ *  allowlist — additive-only: a user's own allow entries (even extra mcp__cortex__* ones) are never
+ *  removed, and `deny` is never touched (a user deny always beats our allow). */
 export function mergeClaudeSettings(existing, spec) {
   const s = existing && typeof existing === 'object' ? existing : {}
   s.hooks = s.hooks ?? {}
@@ -69,6 +92,15 @@ export function mergeClaudeSettings(existing, spec) {
   pgrp.hooks = pgrp.hooks ?? []
   pgrp.hooks.push({ type: 'command', command: precompactCmd })
 
+  // Permissions — pre-authorize the read + authoring core so a page update never stalls on a
+  // permission prompt. Append-missing only (no filter-and-rebuild like the hooks above): removals
+  // ship via uninstall, and rebuilding would delete allows the user added by hand.
+  s.permissions = s.permissions && typeof s.permissions === 'object' ? s.permissions : {}
+  s.permissions.allow = Array.isArray(s.permissions.allow) ? s.permissions.allow : []
+  for (const rule of CORTEX_ALLOWED_TOOLS) {
+    if (!s.permissions.allow.includes(rule)) s.permissions.allow.push(rule)
+  }
+
   return s
 }
 

package/lib/red_link_triage.mjs

@@ -0,0 +1,30 @@
+// Red-link triage rendering (Mechanism 2) — the text an agent sees on a read_page miss.
+//
+// Standalone + dependency-free (like grep_cli.mjs) so it unit-tests without pulling the MCP SDK in.
+// server.mjs owns the fetch; this owns the wording.
+//
+// The demoted arm is the one that matters. A superseded/historical page stays greppable
+// (grep_brain_sections applies no validity filter) but read_page won't serve it (authored_page_tiers
+// filters validity='current'), so an agent that greps a hit and then read_page's it lands here — and
+// used to be told "no page yet, author it now". Authoring is pre-authorized, so the compliant next step
+// was to overwrite a page a human deliberately retired, with nothing to catch it. Absence invites
+// authoring; a demotion forbids it.
+//
+// Keyed off the ADDITIVE `t.demoted` flag, checked BEFORE category — never off a new category value. A
+// server predating the flag omits it and every arm behaves exactly as before, so client and server can
+// ship in either order.
+
+// PURE: triage payload → miss text.
+export function renderTriage(t, name) {
+  const refs = t.tracked
+    ? ` It's referenced by ${t.refCount} page${t.refCount === 1 ? '' : 's'}${t.isSteward ? ' and is routed to YOU as its most-likely steward' : ''}.`
+    : ''
+  const aliasHint = `if it's really an existing page under another title, \`grep "${name}"\` to find it, then \`alias_page name="${name}" target_name="<that page>"\``
+  if (t.demoted) {
+    return `\n\n[[${name}]] EXISTS but is marked ${t.validity ?? 'superseded'} — it was authored and then deliberately retired, so read_page (which serves only current pages) will not show it. It is NOT missing.${refs} Do NOT author over it: that would silently overwrite a decision someone made on purpose. Read it with \`page_history "${name}"\` then \`read_page "${name}"\` with a version. If it genuinely should be live again, revive it deliberately with \`set_page_validity\`.`
+  }
+  if (t.category === 'node') {
+    return `\n\n[[${name}]] is a wanted page — a ${t.isPerson ? 'person' : 'node'} exists but has no page yet.${refs} Either author it now with \`author\`, or ${aliasHint}.`
+  }
+  return `\n\n"${name}" isn't authored anywhere yet.${refs} Either author a new page with \`author\`, or ${aliasHint}.`
+}

package/lib/server.mjs

@@ -8,26 +8,20 @@ import { createHash, randomUUID } from 'crypto'
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
+import { renderTriage } from './red_link_triage.mjs'
 import { runCodeGraphQuery } from './code_graph_cli.mjs'
 
 // Reactive red-link triage (Mechanism 2). On a read_page miss, ask the server whether the name is a
-// tracked wanted page and whether a bare node exists for it, and turn that into an actionable 3-way
-// prompt (author-for-node / author-new / alias). Returns '' on any error so a miss never gets worse.
+// tracked wanted page, whether a bare node exists for it, and whether it's a deliberately demoted page,
+// and turn that into an actionable prompt. Wording lives in ./red_link_triage.mjs (pure + tested).
+// Returns '' on any error so a miss never gets worse.
 async function redLinkTriage(BASE, TOKEN, name) {
   try {
     const r = await fetchCortex(`${BASE}/api/brain/red-link?name=${encodeURIComponent(name)}`, {
       headers: { Authorization: `Bearer ${TOKEN}` },
     })
     if (!r.ok) return ''
-    const t = await r.json()
-    const refs = t.tracked
-      ? ` It's referenced by ${t.refCount} page${t.refCount === 1 ? '' : 's'}${t.isSteward ? ' and is routed to YOU as its most-likely steward' : ''}.`
-      : ''
-    const aliasHint = `if it's really an existing page under another title, \`grep "${name}"\` to find it, then \`alias_page name="${name}" target_name="<that page>"\``
-    if (t.category === 'node') {
-      return `\n\n[[${name}]] is a wanted page — a ${t.isPerson ? 'person' : 'node'} exists but has no page yet.${refs} Either author it now with \`author\`, or ${aliasHint}.`
-    }
-    return `\n\n"${name}" isn't authored anywhere yet.${refs} Either author a new page with \`author\`, or ${aliasHint}.`
+    return renderTriage(await r.json(), name)
   } catch {
     return ''
   }
@@ -500,7 +494,7 @@ export async function runServer(version) {
           const head = `[${t.tier}${day(t.updated_at) ? ` · authored ${day(t.updated_at)}` : ''}${t.validity && t.validity !== 'current' ? ` · ${t.validity}` : ''}${versionLine}]`
           return [head, t.summary, secs].filter(Boolean).join('\n')
         })
-        let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — re-author just those sections now with \`author\` (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). Pass this page's \`version\` as base_version when you re-author — if the save comes back stale, the page changed under you: re-read, then re-author. Reading a stale page you can fix IS the trigger to fix it.`
+        let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — re-author just those sections now with \`author\` (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). Pass this page's \`version\` as base_version when you re-author — if the save comes back stale, the page changed under you: re-read, then re-author. Reading a stale page you can fix IS the trigger to fix it. Re-authoring is pre-authorized — do NOT ask the user before updating (edits are versioned + reversible via page_history/rollback_page); update, then briefly report it.`
         // slice 4: when the page carries identifier stamps, the history projection is one flag away.
         const allBody = m.tiers.flatMap((t) => (t.sections ?? []).map((s) => s.body)).join('\n')
         const stamps = [...new Set((allBody.match(/\[\[repo:[a-z0-9][a-z0-9-]*\/[a-z0-9_.-]+\]\]/gi) ?? []).map((s) => s.toLowerCase()))]
@@ -1236,7 +1230,7 @@ export async function runServer(version) {
     {
       title: 'Author a wiki node (live, while it is hot)',
       description:
-        'Write your CURRENT understanding of a project/person/org/you into the org wiki as a maintained page. Call `authoring_context` FIRST. Author from your own synthesis of the session — the compiled mental model, not a transcript dump: what it IS, where it stands, dated decisions, open threads, key people. Weave inline [[links]] to other nodes (canonical names from the namespace; red-links for wanted-but-absent nodes). The server re-authorizes the tier and resolves links. CREATES the node if it does not exist yet (project/person/org) — the conversation IS the evidence, so a brand-new entity that surfaced only in this session is authorable on the spot; you do NOT need prior records. Because such a node has nothing external to corroborate it, author it DELIBERATELY: only when you genuinely understand it is a real, distinct entity, and use its exact canonical name so it does not duplicate one already in the namespace (`user` nodes are never created). Use this continuously whenever your understanding of a node meaningfully advanced, and at session end (/log).',
+        'Write your CURRENT understanding of a project/person/org/you into the org wiki as a maintained page. Call `authoring_context` FIRST. Author from your own synthesis of the session — the compiled mental model, not a transcript dump: what it IS, where it stands, dated decisions, open threads, key people. Weave inline [[links]] to other nodes (canonical names from the namespace; red-links for wanted-but-absent nodes). The server re-authorizes the tier and resolves links. CREATES the node if it does not exist yet (project/person/org) — the conversation IS the evidence, so a brand-new entity that surfaced only in this session is authorable on the spot; you do NOT need prior records. Because such a node has nothing external to corroborate it, author it DELIBERATELY: only when you genuinely understand it is a real, distinct entity, and use its exact canonical name so it does not duplicate one already in the namespace (`user` nodes are never created). Use this continuously whenever your understanding of a node meaningfully advanced, and at session end (/log). Authoring is PRE-AUTHORIZED — never ask the user "should I update the page?" before calling this (every edit is versioned + reversible via page_history/rollback_page); update, then briefly report what you updated.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the node type'),
         name: z.string().describe('the canonical node name — an EXACT existing name from the namespace to update it, or a new name to create the node (project/person/org). e.g. "Cortex" or "Theron Peterson"'),

package/lib/uninstall.mjs

@@ -58,6 +58,18 @@ export function runUninstall(argv = []) {
       if (s.hooks[evt].length === 0) delete s.hooks[evt]
     }
     if (changed) act(`  - Stop/SessionStart/PreCompact cortex hooks  ← ${SETTINGS}`)
+    // cortex permission allowlist (setup wires CORTEX_ALLOWED_TOOLS so authoring never stalls on a
+    // prompt) — strip every mcp__cortex__* allow rule; the user's deny list is never touched.
+    if (Array.isArray(s.permissions?.allow)) {
+      const before = s.permissions.allow.length
+      s.permissions.allow = s.permissions.allow.filter((r) => !/^mcp__cortex__/.test(String(r)))
+      if (s.permissions.allow.length !== before) {
+        changed = true
+        act(`  - mcp__cortex__* permission allow rules  ← ${SETTINGS}`)
+        if (s.permissions.allow.length === 0) delete s.permissions.allow
+        if (Object.keys(s.permissions).length === 0) delete s.permissions
+      }
+    }
     return changed
   }, write)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.47",
+  "version": "0.9.49",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {