@rubytech/create-maxy-code 0.1.187 → 0.1.188

package/payload/platform/plugins/graph/PLUGIN.md

@@ -0,0 +1,37 @@
+---
+name: graph
+tools:
+  - name: maxy-graph-read_neo4j_cypher
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: maxy-graph-get_neo4j_schema
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: maxy-graph-write_neo4j_cypher
+    publicAllowlist: false
+    adminAllowlist: false
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/graph-mcp/dist/index.js
+  env:
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
+    NEO4J_URI: ${NEO4J_URI}
+    NEO4J_PASSWORD: ${NEO4J_PASSWORD}
+description: "Raw Neo4j Cypher proxy. Wraps the upstream `mcp-neo4j-cypher` server (spawned under uvx by `platform/lib/graph-mcp`) under the stable `maxy-graph` namespace, so its tools register as `maxy-graph-read_neo4j_cypher`, `maxy-graph-get_neo4j_schema`, and `maxy-graph-write_neo4j_cypher`. The read and schema tools are admin-allowlisted for schema checks and read-only queries; the write tool is specialist-only (database-operator / librarian execute operator-confirmed `mergeCypher` templates through it, never hand-authored Cypher). The shim validates write Cypher against the live schema, stamps provenance, and rejects unknown labels/edges. Account isolation is per-brand Neo4j; the shim adds no query-layer tenant filter."
+---
+
+# graph
+
+Cypher proxy plugin. The server is `platform/lib/graph-mcp`, which adopts the upstream
+Python `mcp-neo4j-cypher` server per brand and proxies its JSON-RPC stdio under the
+`maxy-graph` namespace. It is registered through the installed-plugin channel like every
+other platform MCP, so its tools surface as `mcp__plugin_graph_graph__maxy-graph-*`.
+
+Write Cypher is intercepted (not forwarded) so the shim can validate tokens against the
+live schema cache, stamp `createdBy` provenance, and roll back orphan-producing writes.
+Read Cypher and schema introspection forward to upstream with an envelope-warning probe
+that stitches Neo4j `gql_status` codes back into the response.

package/payload/platform/plugins/memory/PLUGIN.md

@@ -123,6 +123,8 @@ hidden:
   - session-compact
   - session-compact-status
   - image-fetch
+  - memory-typed-edge-pass
+  - session-retrospective-skip-rate
 skills:
   - skills/conversational-memory/SKILL.md
   - skills/document-ingest/SKILL.md

package/payload/platform/plugins/memory/mcp/dist/tools/conversation-archive-derive-insights.d.ts

@@ -14,7 +14,7 @@
  * Per-row dispatch (the skill executes; this tool emits the cypher):
  *   mention                → (:Section)-[:MENTIONS {contentHash}]->(:Person|:Organization)
  *   task                   → (:Task)-[:REFERENCES {contentHash}]->(:Section)
- *                            (the skill calls mcp__work__work-create first,
+ *                            (the skill calls mcp__plugin_work_work__work-create first,
  *                             then this REFERENCES edge via raw cypher.)
  *   preference             → MERGE (p:Preference {accountId, contentHash})
  *                            then (p)-[:OBSERVED_IN]->(chunk)

package/payload/platform/plugins/memory/mcp/dist/tools/conversation-archive-derive-insights.js

@@ -14,7 +14,7 @@
  * Per-row dispatch (the skill executes; this tool emits the cypher):
  *   mention                → (:Section)-[:MENTIONS {contentHash}]->(:Person|:Organization)
  *   task                   → (:Task)-[:REFERENCES {contentHash}]->(:Section)
- *                            (the skill calls mcp__work__work-create first,
+ *                            (the skill calls mcp__plugin_work_work__work-create first,
  *                             then this REFERENCES edge via raw cypher.)
  *   preference             → MERGE (p:Preference {accountId, contentHash})
  *                            then (p)-[:OBSERVED_IN]->(chunk)

package/payload/platform/plugins/memory/references/graph-primitives.md

@@ -40,31 +40,40 @@ token-limit discipline the upstream server enforces.
 
 ## When the memory tools are absent
 
-If `mcp__memory__memory-write`, `mcp__memory__memory-search`,
-`mcp__memory__memory-reindex`,
-`mcp__memory__session-compact`, `mcp__memory__session-compact-status`, or
-`mcp__memory__conversation-search` is missing from your tool list, the
-memory MCP server failed to start on this device. Reply once with
-exactly:
-
-> The memory MCP server failed to start on this device. Run the admin
+The maxy MCP tool names are bound to the live registry (Task 502): the
+canonical long name `mcp__plugin_memory_memory__<tool>` is generated from the
+memory plugin's manifest, a build gate fails when any instruction names a tool
+the registry does not serve, and a PostToolUse hook turns a missing-tool call
+into a fixed envelope. So a missing memory tool is one of two distinct states,
+not the single "failed to start" the old contract assumed:
+
+- **Server dead.** None of the `mcp__plugin_memory_memory__*` tools appear in
+  your tool list at all. The per-account memory server did not start; the
+  platform's `[mcp-init-error] server=memory` line in the per-conversation
+  stream log names it.
+- **Name not registered.** The server is up and other
+  `mcp__plugin_memory_memory__*` tools are present, but a specific call returns
+  `No such tool available`. The `mcp-tool-missing` hook has already logged
+  `[mcp-tool-missing] server=memory tool=<tool>` and returned the deterministic
+  envelope you are reading.
+
+In either state, reply once with exactly:
+
+> The memory MCP server is unavailable on this device. Run the admin
 > system-status check to diagnose — do not retry by other routes.
 
-Then stop. Do not search for a similarly-named tool via `ToolSearch`, do
-not improvise via `maxy-graph-read_neo4j_cypher` (it is read-only — every
-write goes through the schema-aware memory tools), do not paraphrase.
-A missing memory tool is a deterministic failure of the per-account
-memory server: the platform's `[mcp-init-error] server=memory` line in
-the per-conversation stream log already names it; the user-facing reply
-exists so the operator knows the session cannot proceed without an
-operator-side fix (the loud-fail contract applies equally
-to graph and memory tool initialisation).
+Then stop. Do not search for a similarly-named tool via `ToolSearch`, do not
+improvise via `mcp__plugin_graph_graph__maxy-graph-read_neo4j_cypher` (it is
+read-only — every write goes through the schema-aware memory tools), do not
+paraphrase, do not describe the server as "warming up". The reply exists so the
+operator knows the session cannot proceed without an operator-side fix (the
+loud-fail contract applies equally to graph and memory tool initialisation).
 
 ## Mutation intents
 
 The graph tools above are read-only. Every write intent has a schema-aware
 tool that already exists — match the user's prose to a tool in this table
-rather than improvising. `mcp__admin__admin-remove` is in your initial
+rather than improvising. `mcp__plugin_admin_admin__admin-remove` is in your initial
 tool list; the other tools below are deferred (they do not appear until
 you invoke `ToolSearch` by the exact name you pick from the table).
 Do not use `ToolSearch` to *discover* the tool by keyword — identify it
@@ -78,14 +87,14 @@ graph as a single action.
 
 | User intent | Tool | When to pick this, not the next row |
 |---|---|---|
-| "remove admin X", "take away their admin access", "revoke admin" | `mcp__admin__admin-remove` | Device-level admin offboarding — detaches the `(AdminUser)-[:ADMIN_OF]->(LocalBusiness)` edge and updates `platform/config/users.json`. Not for scrubbing personal data — use the GDPR contact-erase tools for that. |
-| "delete this specific node", "remove this entry by its id", "get rid of node X", "remove orphans", "prune", "clean up" | `mcp__memory__memory-delete` | Soft-deletes a single node by `elementId` (adds `:Trashed`, preserves relationships, snapshots unique keys, invisible to `memory-search` and any `notTrashed`-filtered read). For KnowledgeDocument, cascades to Sections and Chunks. Enumerate candidates first with a Cypher read, confirm with the user, then delete each by `elementId`. There is no bulk "delete everything without relationships" tool. Per the write doctrine (`.docs/neo4j.md` § Write doctrine), **new** orphans should be impossible — every writer now rejects zero-edge calls at the MCP tool-surface. Existing orphans from legacy data are legitimate backfill candidates but are not produced by any live writer; if you see a freshly-created orphan, it is a bug in a writer that bypassed `writeNodeWithEdges`, not expected state. |
-| "undo that delete", "I deleted X by mistake, bring it back", "restore the contact I just trashed" | `mcp__memory__memory-restore` | Removes `:Trashed`, restores snapshotted unique-key properties. Fails loudly when an active node already holds the unique slot (e.g. a fresh `LocalBusiness` was created while the old one was in trash) — the error names the conflicting `elementId` so you can ask the user how to resolve. |
-| "empty the trash", "purge old soft-deletes", "what's been sitting in trash and ready to clear" | `mcp__memory__memory-empty-trash` | Hard-deletes trashed nodes whose `trashedAt` is older than `graceDays` (default 30); `dryRun=true` lists candidates without mutating. Use `dryRun` first, show the list to the user, then run for real. For KnowledgeDocument candidates, the on-disk attachment directory is removed too. |
-| "scrub this conversation's memory", "remove this claim the bot picked up", "forget what we said in that thread" | `mcp__memory__conversation-memory-expunge` | Removes deny-listable content from `:Memory` nodes scoped to one conversation. Requires an explicit pattern and sessionId. Not for deleting individual nodes — use `memory-delete`. |
-| "update a property", "fix a typo in a node", "change the role field on X", "null this poisonous string" | `mcp__memory__memory-update` | Targeted property edit on an existing node, schema-validated. Use to null individual string properties matching a deny-list entry once you've identified the offender via a Cypher read. Not for creating new nodes — use `memory-write`. |
-| "update X by name, search didn't return it", "wire this Org but search came back empty", "I know it exists but I don't have the elementId" | `mcp__memory__memory-update-by-name` | Repair surface for the case where `memory-search` cannot return a row you know exists by name. Resolves the unique `(label, name, accountId)` tuple, then delegates to `memory-update`. Rejects loudly on zero or ambiguous matches (the rejection lists candidate elementIds so you can pick one). Trashed nodes excluded. Use this only after `memory-search` failed — for normal updates, get the elementId from search and call `memory-update` directly. |
-| "don't surface these substrings in future memory results", "watch for this string" | `mcp__memory__graph-prune-denylist-add` | Records a substring as operator-curated signal. Nothing auto-applies it — when a subsequent memory-search or cypher read surfaces a match, use `memory-update` or `memory-delete` with discretion to scrub it. |
+| "remove admin X", "take away their admin access", "revoke admin" | `mcp__plugin_admin_admin__admin-remove` | Device-level admin offboarding — detaches the `(AdminUser)-[:ADMIN_OF]->(LocalBusiness)` edge and updates `platform/config/users.json`. Not for scrubbing personal data — use the GDPR contact-erase tools for that. |
+| "delete this specific node", "remove this entry by its id", "get rid of node X", "remove orphans", "prune", "clean up" | `mcp__plugin_memory_memory__memory-delete` | Soft-deletes a single node by `elementId` (adds `:Trashed`, preserves relationships, snapshots unique keys, invisible to `memory-search` and any `notTrashed`-filtered read). For KnowledgeDocument, cascades to Sections and Chunks. Enumerate candidates first with a Cypher read, confirm with the user, then delete each by `elementId`. There is no bulk "delete everything without relationships" tool. Per the write doctrine (`.docs/neo4j.md` § Write doctrine), **new** orphans should be impossible — every writer now rejects zero-edge calls at the MCP tool-surface. Existing orphans from legacy data are legitimate backfill candidates but are not produced by any live writer; if you see a freshly-created orphan, it is a bug in a writer that bypassed `writeNodeWithEdges`, not expected state. |
+| "undo that delete", "I deleted X by mistake, bring it back", "restore the contact I just trashed" | `mcp__plugin_memory_memory__memory-restore` | Removes `:Trashed`, restores snapshotted unique-key properties. Fails loudly when an active node already holds the unique slot (e.g. a fresh `LocalBusiness` was created while the old one was in trash) — the error names the conflicting `elementId` so you can ask the user how to resolve. |
+| "empty the trash", "purge old soft-deletes", "what's been sitting in trash and ready to clear" | `mcp__plugin_memory_memory__memory-empty-trash` | Hard-deletes trashed nodes whose `trashedAt` is older than `graceDays` (default 30); `dryRun=true` lists candidates without mutating. Use `dryRun` first, show the list to the user, then run for real. For KnowledgeDocument candidates, the on-disk attachment directory is removed too. |
+| "scrub this conversation's memory", "remove this claim the bot picked up", "forget what we said in that thread" | `mcp__plugin_memory_memory__conversation-memory-expunge` | Removes deny-listable content from `:Memory` nodes scoped to one conversation. Requires an explicit pattern and sessionId. Not for deleting individual nodes — use `memory-delete`. |
+| "update a property", "fix a typo in a node", "change the role field on X", "null this poisonous string" | `mcp__plugin_memory_memory__memory-update` | Targeted property edit on an existing node, schema-validated. Use to null individual string properties matching a deny-list entry once you've identified the offender via a Cypher read. Not for creating new nodes — use `memory-write`. |
+| "update X by name, search didn't return it", "wire this Org but search came back empty", "I know it exists but I don't have the elementId" | `mcp__plugin_memory_memory__memory-update-by-name` | Repair surface for the case where `memory-search` cannot return a row you know exists by name. Resolves the unique `(label, name, accountId)` tuple, then delegates to `memory-update`. Rejects loudly on zero or ambiguous matches (the rejection lists candidate elementIds so you can pick one). Trashed nodes excluded. Use this only after `memory-search` failed — for normal updates, get the elementId from search and call `memory-update` directly. |
+| "don't surface these substrings in future memory results", "watch for this string" | `mcp__plugin_memory_memory__graph-prune-denylist-add` | Records a substring as operator-curated signal. Nothing auto-applies it — when a subsequent memory-search or cypher read surfaces a match, use `memory-update` or `memory-delete` with discretion to scrub it. |
 
 **Never run `cypher-shell` via `Bash` to work around the read-only tool.**
 The admin session's `Bash` surface has no path to the per-brand Neo4j
@@ -107,7 +116,7 @@ MATCH (a:AdminUser) WHERE NOT (a)--() RETURN elementId(a), a.userId, a.createdAt
 ```
 
 Show the list to the user. For each confirmed entry, call
-`mcp__memory__memory-delete` with the `elementId`. Do not batch-delete
+`mcp__plugin_memory_memory__memory-delete` with the `elementId`. Do not batch-delete
 by pattern — on 2026-04-20 an autonomous orphan-delete rule wiped 19
 nodes in one call, with no property recovery possible. Structural mass-
 deletion by shape is banned; discretion per node is the only sanctioned

package/payload/platform/plugins/obsidian-import/PLUGIN.md

@@ -18,7 +18,7 @@ The admin agent delegates to `specialists:database-operator` when the operator d
 
 ## How parsing happens
 
-The skill does not parse markdown. Vault traversal, frontmatter YAML, wikilink regex, tag scanning, daily-notes detection, and attachment resolution all happen server-side inside `mcp__memory__obsidian-vault-import` (memory plugin). The skill is the operator-facing conversation surface only: confirm owner → select filters → invoke the tool with `mode='dry-run'` → present ambiguities → invoke with `mode='commit'` and the operator's resolutions.
+The skill does not parse markdown. Vault traversal, frontmatter YAML, wikilink regex, tag scanning, daily-notes detection, and attachment resolution all happen server-side inside `mcp__plugin_memory_memory__obsidian-vault-import` (memory plugin). The skill is the operator-facing conversation surface only: confirm owner → select filters → invoke the tool with `mode='dry-run'` → present ambiguities → invoke with `mode='commit'` and the operator's resolutions.
 
 ## Intra-plugin growth
 

package/payload/platform/scripts/check-canonical-tool-names.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Strong build gate for canonical maxy MCP tool names (Task 502).
+//
+// Two checks, both must pass:
+//   1. Regenerate-and-diff: the committed generated artifact
+//      (canonical-tool-names.generated.ts) must byte-match a fresh generation
+//      from platform/plugins/*/PLUGIN.md. A stale artifact fails the build —
+//      this is what stops a PLUGIN.md tool add/remove from drifting away from
+//      the names instructions are bound to.
+//   2. Instruction-name validation: every `mcp__...` tool name in an
+//      instruction file (specialist templates, agent prompts, plugin
+//      references/skills, PLUGIN.md prose) that targets a MAXY plugin must be
+//      the canonical long prefix AND must exist in the live set. A short-prefix
+//      maxy name (mcp__<plugin>__<tool>) fails — it must be long. An unknown
+//      long-prefix maxy name fails — typo or stale. Non-maxy bridge namespaces
+//      (playwright, etc.) are ignored: their tool names are upstream-owned.
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { computeCanonicalToolNames, MAXY_CODE_ROOT } from './lib/canonical-tool-names.mjs'
+import { renderArtifact, renderPluginsList } from './generate-canonical-tool-names.mjs'
+
+const GENERATED = join(
+  MAXY_CODE_ROOT, 'platform', 'services', 'claude-session-manager', 'src',
+  'canonical-tool-names.generated.ts',
+)
+const PLUGINS_TXT = join(
+  MAXY_CODE_ROOT, 'platform', 'plugins', 'admin', 'hooks', 'lib',
+  'maxy-mcp-plugins.txt',
+)
+
+const SCAN_DIRS = [
+  join(MAXY_CODE_ROOT, 'platform', 'templates', 'specialists', 'agents'),
+  join(MAXY_CODE_ROOT, 'platform', 'plugins'),
+]
+const SCAN_EXT = new Set(['.md'])
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'payload', '__tests__'])
+// mcp__<seg>__<tool>  — seg may itself contain `_` (long prefix plugin_a_b).
+const TOOL_RE = /mcp__([A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*)__([A-Za-z0-9_-]+)/g
+
+function* walk(dir) {
+  let entries
+  try { entries = readdirSync(dir) } catch { return }
+  for (const e of entries.sort()) {
+    if (e.startsWith('.') || SKIP_DIRS.has(e)) continue
+    const p = join(dir, e)
+    let st
+    try { st = statSync(p) } catch { continue }
+    if (st.isDirectory()) { yield* walk(p); continue }
+    const ext = e.includes('.') ? '.' + e.split('.').pop() : ''
+    if (SCAN_EXT.has(ext)) yield p
+  }
+}
+
+function main() {
+  const { plugins, names } = computeCanonicalToolNames()
+  const maxyPlugins = new Set(plugins)
+  const canonical = new Set(names)
+
+  // Check 1 — regenerate-and-diff both generated outputs.
+  let driftError = null
+  const staleOutputs = []
+  if ((existsSync(GENERATED) ? readFileSync(GENERATED, 'utf8') : '') !== renderArtifact()) staleOutputs.push(GENERATED)
+  if ((existsSync(PLUGINS_TXT) ? readFileSync(PLUGINS_TXT, 'utf8') : '') !== renderPluginsList()) staleOutputs.push(PLUGINS_TXT)
+  if (staleOutputs.length > 0) {
+    driftError =
+      `[gate] canonical-tool-names: GENERATED ARTIFACT STALE.\n` +
+      staleOutputs.map((p) => `  ${p}`).join('\n') + '\n' +
+      `  Regenerate: cd platform && npm run gen:canonical-tools`
+  }
+
+  // Check 2 — instruction-name validation.
+  const violations = []
+  for (const root of SCAN_DIRS) {
+    for (const file of walk(root)) {
+      const text = readFileSync(file, 'utf8')
+      for (const m of text.matchAll(TOOL_RE)) {
+        const seg = m[1]
+        const full = m[0]
+        // Skip glob patterns in prose (`mcp__plugin_x_x__*`): the `*` is not a
+        // tool char so the match captured a partial name, not a real reference.
+        if (text[m.index + full.length] === '*') continue
+        if (seg.startsWith('plugin_')) {
+          // Long prefix mcp__plugin_<plugin>_<server>__<tool>.
+          const inner = seg.slice('plugin_'.length)
+          // plugin === server for maxy; the long prefix is `<plugin>_<plugin>`.
+          const plugin = [...maxyPlugins].find((p) => inner === `${p}_${p}`)
+          if (!plugin) continue // non-maxy bridge (playwright) — upstream-owned.
+          if (!canonical.has(full)) {
+            violations.push({ file, name: full, why: 'unknown maxy tool (typo or stale)' })
+          }
+        } else if (maxyPlugins.has(seg)) {
+          // Short prefix mcp__<maxyplugin>__<tool> — must be long now.
+          violations.push({ file, name: full, why: `short prefix for maxy plugin '${seg}' — use canonical long name` })
+        }
+      }
+    }
+  }
+
+  const failed = driftError || violations.length > 0
+  if (driftError) console.error(driftError)
+  if (violations.length > 0) {
+    console.error('[gate] canonical-tool-names: instruction files name tools outside the live set:')
+    for (const v of violations) console.error(`  ${v.file.replace(MAXY_CODE_ROOT + '/', '')}: ${v.name} — ${v.why}`)
+  }
+  if (failed) process.exit(1)
+  console.log(`[gate] check-canonical-tool-names: PASS (${names.length} canonical names, scanned instruction files)`)
+}
+
+main()

package/payload/platform/scripts/generate-canonical-tool-names.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Generator: writes the committed canonical maxy MCP tool-name artifact from
+// every platform/plugins/<dir>/PLUGIN.md. Run via `npm run gen:canonical-tools`
+// (platform). The strong build gate (check-canonical-tool-names.mjs) regenerates
+// in-memory and fails the build if the committed artifact has drifted.
+import { writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { computeCanonicalToolNames, MAXY_CODE_ROOT } from './lib/canonical-tool-names.mjs'
+
+const OUT = join(
+  MAXY_CODE_ROOT, 'platform', 'services', 'claude-session-manager', 'src',
+  'canonical-tool-names.generated.ts',
+)
+
+// Plain newline-delimited maxy plugin list the deterministic missing-tool hook
+// (bash) reads to tell a maxy server (mcp__plugin_<p>_<p>__) from a third-party
+// bridge that shares the same long-prefix shape (Playwright etc.).
+const PLUGINS_TXT = join(
+  MAXY_CODE_ROOT, 'platform', 'plugins', 'admin', 'hooks', 'lib',
+  'maxy-mcp-plugins.txt',
+)
+
+export function renderPluginsList() {
+  const { plugins } = computeCanonicalToolNames()
+  return plugins.join('\n') + '\n'
+}
+
+export function renderArtifact() {
+  const { plugins, names } = computeCanonicalToolNames()
+  const body = [
+    '// GENERATED — do not edit by hand.',
+    '// Source: platform/plugins/*/PLUGIN.md (tools: + hidden: blocks).',
+    '// Regenerate: cd platform && npm run gen:canonical-tools',
+    '// Gate: platform/scripts/check-canonical-tool-names.mjs fails the build on drift.',
+    '//',
+    '// Canonical long-prefix names every maxy MCP tool is served under by the',
+    '// installed-plugin channel: mcp__plugin_<dir>_<dir>__<tool>.',
+    '',
+    '/** Directory basenames of maxy platform plugins that expose a tool surface. */',
+    'export const MAXY_MCP_PLUGINS: readonly string[] = [',
+    ...plugins.map((p) => `  ${JSON.stringify(p)},`),
+    ']',
+    '',
+    '/** Every canonical maxy MCP tool name (long prefix), sorted. */',
+    'export const CANONICAL_MAXY_TOOL_NAMES: readonly string[] = [',
+    ...names.map((n) => `  ${JSON.stringify(n)},`),
+    ']',
+    '',
+  ].join('\n')
+  return body
+}
+
+function main() {
+  writeFileSync(OUT, renderArtifact(), 'utf8')
+  writeFileSync(PLUGINS_TXT, renderPluginsList(), 'utf8')
+  const { plugins, names } = computeCanonicalToolNames()
+  console.log(`[gen] canonical-tool-names: ${plugins.length} plugins, ${names.length} tools -> ${OUT}`)
+  console.log(`[gen] maxy-mcp-plugins.txt -> ${PLUGINS_TXT}`)
+}
+
+export { OUT, PLUGINS_TXT }
+
+if (import.meta.url === `file://${process.argv[1]}`) main()

package/payload/platform/scripts/lib/canonical-tool-names.mjs

@@ -0,0 +1,88 @@
+// Shared source of truth for canonical (long-prefix) maxy MCP tool names.
+//
+// Claude Code's installed-plugin channel serves every plugin MCP tool under
+// the long prefix `mcp__plugin_<plugin>_<server>__<tool>`. For every platform
+// plugin the marketplace name, the MCP server key, and the directory basename
+// are identical, so the canonical name is deterministically
+// `mcp__plugin_<dir>_<dir>__<tool>`. This module is the single place that
+// derives those names from each `platform/plugins/<dir>/PLUGIN.md`; the
+// generator writes the committed artifact from it, the build gate diffs
+// against it, and the session-manager cross-checks its tool surface against it.
+//
+// Scope: platform plugins only. Third-party bridge servers (playwright, etc.)
+// also render under `mcp__plugin_*` but their tool names are upstream-owned and
+// are NOT part of the maxy canonical set — the drift check treats a
+// `mcp__plugin_*` name whose plugin segment is not a maxy plugin as a bridge
+// pass, never validating it against this set.
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+export const MAXY_CODE_ROOT = resolve(__dirname, '..', '..', '..')
+const PLATFORM_PLUGINS_ROOT = join(MAXY_CODE_ROOT, 'platform', 'plugins')
+
+/** Long-prefix canonical name for a platform plugin tool. plugin === server
+ *  === directory basename for every platform MCP plugin. */
+export function canonicalToolName(plugin, tool) {
+  return `mcp__plugin_${plugin}_${plugin}__${tool}`
+}
+
+function extractFrontmatter(md) {
+  if (!md.startsWith('---')) return null
+  const end = md.indexOf('\n---', 3)
+  if (end < 0) return null
+  return md.slice(3, end)
+}
+
+// Collect `- name: <x>` entries under a bare `tools:` block and `- <x>` entries
+// under a bare `hidden:` block. Both contribute names a specialist may list in
+// its `tools:` frontmatter, so both belong to the live set.
+function parseToolNames(frontmatter) {
+  const lines = frontmatter.split('\n')
+  const names = []
+  let mode = null // 'tools' | 'hidden' | null
+  for (const line of lines) {
+    if (/^tools\s*:/.test(line)) {
+      mode = /^tools\s*:\s*$/.test(line) ? 'tools' : null
+      continue
+    }
+    if (/^hidden\s*:/.test(line)) {
+      mode = /^hidden\s*:\s*$/.test(line) ? 'hidden' : null
+      continue
+    }
+    if (/^\S/.test(line) && line.trim() !== '') { mode = null; continue }
+    if (mode === 'tools') {
+      const m = line.match(/^\s+-\s+name:\s*(.+?)\s*$/)
+      if (m) names.push(m[1])
+    } else if (mode === 'hidden') {
+      const m = line.match(/^\s+-\s+(.+?)\s*$/)
+      if (m) names.push(m[1])
+    }
+  }
+  return names
+}
+
+/** Returns { plugins, names } — `plugins` is the sorted list of maxy plugin
+ *  directory basenames that declare a tool surface; `names` is the sorted list
+ *  of canonical long-prefix tool names across all of them. */
+export function computeCanonicalToolNames(pluginsRoot = PLATFORM_PLUGINS_ROOT) {
+  const plugins = []
+  const names = new Set()
+  if (!existsSync(pluginsRoot)) return { plugins, names: [] }
+  for (const entry of readdirSync(pluginsRoot).sort()) {
+    if (entry.startsWith('.')) continue
+    const dir = join(pluginsRoot, entry)
+    try { if (!statSync(dir).isDirectory()) continue } catch { continue }
+    const manifest = join(dir, 'PLUGIN.md')
+    if (!existsSync(manifest)) continue
+    const fm = extractFrontmatter(readFileSync(manifest, 'utf-8'))
+    if (fm === null) continue
+    const toolNames = parseToolNames(fm)
+    if (toolNames.length === 0) continue
+    plugins.push(entry)
+    for (const t of toolNames) names.add(canonicalToolName(entry, t))
+  }
+  return { plugins: plugins.sort(), names: Array.from(names).sort() }
+}

package/payload/platform/scripts/setup-account.sh

@@ -127,6 +127,12 @@ cat > "$ACCOUNT_SETTINGS" << SETTINGS_EOF
           { "type": "command", "command": "bash $HOOKS_PATH/archive-ingest-surface-gate.sh" }
         ]
       },
+      {
+        "matcher": "mcp__.*",
+        "hooks": [
+          { "type": "command", "command": "bash $HOOKS_PATH/mcp-tool-missing.sh" }
+        ]
+      },
       {
         "matcher": "Write",
         "hooks": [

package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.d.ts

@@ -0,0 +1,7 @@
+/** Long-prefix name served by the installed-plugin channel (admin + specialist
+ *  spawns). plugin === server === plugin directory basename. */
+export declare function canonicalToolName(plugin: string, tool: string): string;
+/** Short-prefix name served by the per-spawn `--mcp-config` channel, retained
+ *  only for public-agent spawns. */
+export declare function qualifyShortToolName(plugin: string, tool: string): string;
+//# sourceMappingURL=canonical-tool-names.d.ts.map

package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-tool-names.d.ts","sourceRoot":"","sources":["../src/canonical-tool-names.ts"],"names":[],"mappings":"AAaA;gEACgE;AAChE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;oCACoC;AACpC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzE"}

package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.generated.d.ts

@@ -0,0 +1,5 @@
+/** Directory basenames of maxy platform plugins that expose a tool surface. */
+export declare const MAXY_MCP_PLUGINS: readonly string[];
+/** Every canonical maxy MCP tool name (long prefix), sorted. */
+export declare const CANONICAL_MAXY_TOOL_NAMES: readonly string[];
+//# sourceMappingURL=canonical-tool-names.generated.d.ts.map

package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-tool-names.generated.d.ts","sourceRoot":"","sources":["../src/canonical-tool-names.generated.ts"],"names":[],"mappings":"AAQA,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAiB7C,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EA+KtD,CAAA"}