@theronap/cortex-mcp 0.9.46 → 0.9.48

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/grep_cli.mjs

@@ -33,7 +33,14 @@ export function parseGrepArgs(argv = []) {
 // Pure: render a /api/grep payload to readable ASCII text.
 export function formatGrepHits(payload, query) {
   const hits = (payload && payload.hits) || []
-  if (!hits.length) return `No matches for "${query}".`
+  if (!hits.length) {
+    // Reactive red-link hint — ONLY when the query looks like a page NAME (short, no code/operators), so
+    // code and typo searches don't get nagged. read_page carries the full triage (node / new / alias).
+    const nameish = /^[\w .'-]{2,40}$/.test(query) && query.split(/\s+/).length <= 5
+    return nameish
+      ? `No matches for "${query}". If you expected a page here, it may be an unauthored red-link — \`read_page "${query}"\` to triage it (author it, or alias it to an existing page).`
+      : `No matches for "${query}".`
+  }
   const lines = [`${hits.length} match${hits.length === 1 ? '' : 'es'} for "${query}":`, '']
   for (const h of hits) {
     const head = h.heading ? ` > ${h.heading}` : ''

package/lib/server.mjs

@@ -10,6 +10,29 @@ import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.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.
+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}.`
+  } catch {
+    return ''
+  }
+}
+
 // The Cortex MCP server (stdio). Serves the signed-in employee's scoped org
 // context to their AI assistant. CORTEX_TOKEN identifies the user + org.
 
@@ -444,7 +467,7 @@ export async function runServer(version) {
         return { content: [{ type: 'text', text: `Could not read "${name}": ${e.message}` }] }
       }
       if (res.status === 404) {
-        return { content: [{ type: 'text', text: `No ${k} page named "${name}". If it's a person or team, pass kind (person/org). Otherwise \`grep "${name}"\` to locate it — it may be a red-link (a wanted page that isn't authored yet).` }] }
+        return { content: [{ type: 'text', text: `No ${k} page named "${name}". If it's a person or team, pass kind (person/org).${await redLinkTriage(BASE, TOKEN, name)}` }] }
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
@@ -461,7 +484,7 @@ export async function runServer(version) {
         matches = [{ brain: null, authored: true, ref: page.ref, title: page.title, tiers: page.tiers }]
       }
       if (!matches.length) {
-        return { content: [{ type: 'text', text: `No authored ${k} page named "${name}" in any of your brains. If it's a person or team, pass kind (person/org). Otherwise \`grep "${name}"\` to locate it — it may be a red-link (a wanted page that isn't authored yet).` }] }
+        return { content: [{ type: 'text', text: `No authored ${k} page named "${name}" in any of your brains. If it's a person or team, pass kind (person/org).${await redLinkTriage(BASE, TOKEN, name)}` }] }
       }
       const day = (d) => (d ? String(d).slice(0, 10) : '')
       const renderMatch = (m, tagBrain) => {
@@ -477,7 +500,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()))]
@@ -812,6 +835,63 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'alias_page',
+    {
+      title: 'Point a wanted name at an existing page',
+      description: 'Record that a red-link — a [[Name]] referenced in the wiki but never authored — actually MEANS an existing authored page under a different title. After this, read_page and [[links]] for that name resolve to the target page, and the name leaves the org\'s wanted-page backlog. Use this when read_page says a name is a wanted page but you recognize it as an existing page (e.g. [[tto]] -> "BYU TTO — Technology Transfer Office"). To CREATE a genuinely new page instead, use `author`.',
+      inputSchema: {
+        name: z.string().describe('the wanted [[Name]] to redirect (the red-link)'),
+        target_name: z.string().describe('the exact title of the existing authored page it should resolve to'),
+        target_kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('disambiguate the target if two pages share a title'),
+      },
+    },
+    async ({ name, target_name, target_kind }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/alias`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name, target_name, ...(target_kind ? { target_kind } : {}) }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not alias: ${e.message}` }] }
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return { content: [{ type: 'text', text: `Could not alias "${name}": ${out?.error ?? res.status}` }] }
+      if (!out) return { content: [{ type: 'text', text: `Aliased "${name}", but the server returned no body — re-read the page to confirm.` }] }
+      return { content: [{ type: 'text', text: `Done — [[${out.alias}]] now resolves to "${out.target}" (${out.target_kind}). It's out of the wanted-page backlog.` }] }
+    },
+  )
+
+  server.registerTool(
+    'snooze_red_link',
+    {
+      title: 'Defer a wanted page routed to you',
+      description: 'Stop a wanted page (a red-link the org routed to you as its most-likely steward) from surfacing in your context for a while. Use when you can\'t author it right now but it is genuinely yours to write. It comes back after the snooze passes. To dismiss it permanently, author it (`author`) or alias it to an existing page (`alias_page`).',
+      inputSchema: {
+        name: z.string().describe('the wanted page name to snooze (as shown in "Pages the org needs you to author")'),
+        days: z.number().int().positive().optional().describe('how many days to defer (default 7)'),
+      },
+    },
+    async ({ name, days }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/red-link/snooze`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name, ...(days ? { days } : {}) }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not snooze: ${e.message}` }] }
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return { content: [{ type: 'text', text: `Could not snooze "${name}": ${out?.error ?? res.status}` }] }
+      if (!out) return { content: [{ type: 'text', text: `Snoozed "${name}", but the server returned no body.` }] }
+      return { content: [{ type: 'text', text: `Snoozed "${out.name}" for ${out.days} day${out.days === 1 ? '' : 's'} — it won't surface until then.` }] }
+    },
+  )
+
   server.registerTool(
     'set_page_privacy',
     {
@@ -1156,7 +1236,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.46",
+  "version": "0.9.48",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {