heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/tool-catalog.mjs

@@ -0,0 +1,2813 @@
+// The MCP tool catalog: every heyspex_* tool definition (TOOLS), plus the
+// progressive-disclosure state and handler (heyspex_load_tools). Extracted from
+// cli.mjs under [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]]
+// (no behavior change).
+//
+// ─────────────────────────────────────────────────────────────
+// Tool-surface reduction ([[HS-MTSA-EPIC]] / [[HS-LCRS-TASK]], dispositions in
+// [[HS-OO5K-RES]]): the default tools/list exposes only the observed daily-loop
+// core (15 keeps + the loader = 16 ≤ the epic's ≤20 target). Everything else is
+// scope-deferred — DEFINITIONS STAY IN `TOOLS` (hidden, not deleted; tools/call
+// dispatches by name regardless of visibility) pending the spec-scoped filter
+// ([[HS-A4BY-EPIC]]). Escape hatch: HEYSPEX_TOOL_SURFACE=full lists everything
+// (automation / dev-factory). Surface state lives in the PARENT server process —
+// in MCP_SUBPROCESS_TOOLS mode the fresh subprocess returns the full list and
+// the parent filters it, and heyspex_load_tools is intercepted parent-side.
+// ─────────────────────────────────────────────────────────────
+
+import { runFrontCliHint } from './run-front.mjs';
+import { CLOSE_SESSION_THREAD_TYPES, PREFLIGHT_INTENTS } from './procedure-tools.mjs';
+import { sendNotification } from './stdio-rpc.mjs';
+import { DEFAULT_TOOL_BUDGET_BYTES } from './response-budget.mjs';
+
+// Byte budget every READ tool declares ([[HS-4H8T-8KK5-TASK-every-mcp-read-tool-declares-a-byte]]):
+// tool-dispatch.mjs enforces `budget.max_bytes` on the way out (see response-budget.mjs);
+// `list_key` names the field a trim shortens when the tool's reply is a list.
+// `tool-budget.test.mjs` walks the catalog and fails on a read-shaped tool without one.
+const READ_TOOL_BUDGET = Object.freeze({ max_bytes: DEFAULT_TOOL_BUDGET_BYTES });
+const listBudget = (list_key) => Object.freeze({ max_bytes: DEFAULT_TOOL_BUDGET_BYTES, list_key });
+
+export const TOOLS = [
+  {
+    name: 'heyspex_validate_user_skills',
+    description:
+      'Validate user-authored gateway skills under .heyspex/skills/user/<slug>/SKILL.md ([[HS-WEC3-UH11-EPIC-user-customizable-mcp-servers-and]]; design [[HS-P861-G9JR-RES-user-customizable-mcp-servers-and]]). Checks frontmatter integrity (name/description required; malformed tool_scope/requires_servers FAIL CLOSED — the skill is inert until it parses) and scope coverage (skills whose declared tool_scope no registered server provides are "orphaned" and stay inert). Scope matching is a deterministic exact-tag set operation, never semantic. Report-only: never edits, deletes, or auto-disables user content. Returns { skills, registry, orphans }; registry.available is false until HS-DCCP\'s server-registration table exists. Same core as `hs gateway validate` and `hs doctor --check-gateway`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        skill: {
+          type: 'string',
+          description: 'Optional: validate only the skill with this directory slug. If omitted, validates every user skill.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_validate_linkage',
+    description:
+      'Validate spec linkage across the vault: detect orphan specs (milestones/epics/tasks not reachable from the roadmap), broken `[[wikilinks]]`, roadmap manifest entries pointing to missing files, and parent/child links that do not point back. Returns a structured report { valid, orphan_specs, broken_wikilinks, missing_manifest_refs, parent_child_mismatches, frozen_parent_child_mismatches, warnings, summary }. Reachability follows the manifest-v3 hierarchy: roadmap → milestones → epics (`milestone:`) → tasks (`parent:`). `frozen_parent_child_mismatches` is INFORMATIONAL, not vault debt: a mismatch where either side is `status: closed`/`superseded` cannot be repaired because that spec\'s `children:`/`epics:` roster is frozen historical record accurate to what was true at close (only the close-out change-log row, `status:`, `close_reason:` and `superseded_by:` may still be touched). Do NOT "fix" these — they are excluded from `valid` and from `summary.mismatches`, and counted in `summary.frozen_mismatches`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Optional: scope the report to a single spec (by id or basename). If omitted, validates the whole vault.',
+        },
+        include_warnings: {
+          type: 'boolean',
+          default: true,
+          description: 'Include non-critical warnings (e.g. a subject spec with no related[] links).',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_suggest_pillar',
+    description:
+      'Rank the pillar taxonomy against a draft milestone/epic BEFORE filing it, so the `pillar:` is chosen from each pillar\'s written contract instead of guessed from its name ([[pillar-assignment-protocol]] §"The fit test"). Pass the draft\'s `name` (plus `summary`/`tags` when you have them). Returns { verdict, new_pillar_recommended, rationale, candidates[], other_pillars[] } where each candidate carries `belongs` / `excludes` bullets, a `score`, the charter lines that matched (`evidence`), and `excluded_by` when that pillar explicitly disclaims this work. READ the shortlisted contracts before choosing — picking by pillar name is the documented failure mode that mis-filed the command palette, the console rail and the entire scheduler into HS-PILR-architecture. `verdict: "none"` / `new_pillar_recommended: true` means no existing theme fits: draft a new-pillar proposal and present it to the OWNER with evidence and the closest existing alternative. This tool never writes, and an agent never creates a pillar without explicit owner approval.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'The draft spec\'s title — the primary scoring signal.',
+        },
+        summary: {
+          type: 'string',
+          description: 'The draft spec\'s plain-language summary. Strongly improves ranking; pass it whenever you have authored one.',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional tags to fold into the scored subject text.',
+        },
+        subject: {
+          type: 'string',
+          description: 'Optional freeform text to score instead of / in addition to name+summary (e.g. a research doc excerpt during plan ingest).',
+        },
+        shortlist: {
+          type: 'number',
+          description: 'How many ranked candidates to return with full charters (default 5, max 10). The rest come back as id+name under other_pillars.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_edit_file',
+    description:
+      'Safe file edit for parallel agents ([[HS-Y00G-EPIC]]). Acquires a file claim, writes the content, and releases the claim — all in one call. If the file is already claimed by another agent, returns CONFLICT with the claiming agent id and TTL. This is the stopgap edit primitive that prevents silent last-writer-wins data loss until the CRDT layer (Epic 2) ships. Use this INSTEAD of raw writeFileSync / edit_file when editing shared spec files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: {
+          type: 'string',
+          description: 'Absolute path of the file to write.',
+        },
+        content: {
+          type: 'string',
+          description: 'The new file content to write.',
+        },
+        agent: {
+          type: 'string',
+          description: 'Agent display name (default: detected from env)',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Session identifier (default: detected from env)',
+        },
+        working_spec_id: {
+          type: 'string',
+          description: 'The spec id the agent is working on (informational).',
+        },
+      },
+      required: ['file_path', 'content'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_register_spec',
+    description:
+      'Link a spec into the roadmap so it is reachable (the fix counterpart to heyspex_validate_linkage). What it edits depends on the spec kind, following the manifest-v3 hierarchy: a milestone is added to a roadmap\'s roadmap_manifest.milestones; an epic gets its `milestone:` field set AND is added to that milestone\'s epics[]; a task gets its `parent:` field set AND is added to that epic\'s children[]. Both sides are written, so it also repairs one-sided parent/child mismatches. Idempotent — re-running on an already-linked spec is a no-op success. Returns { success, spec_id, type, parent, already_registered, changes, validation }.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'The spec to register (id or basename), e.g. "HS-TASK-5K13".',
+        },
+        parent_id: {
+          type: 'string',
+          description:
+            'Target parent: the milestone for an epic, the epic for a task, or the roadmap for a milestone. If omitted for an epic/task, the spec\'s own `milestone:`/`parent:` field is used (repairs a missing back-reference); for a milestone it defaults to roadmap_id.',
+        },
+        roadmap_id: {
+          type: 'string',
+          default: 'HS-ROADMAP-PRODUCT',
+          description: 'Roadmap to register a milestone into (milestones only).',
+        },
+        position: {
+          type: 'string',
+          description: "Where to insert in the parent's list: 'first', 'last' (default), 'after:<ref>', or 'before:<ref>'.",
+        },
+        dry_run: {
+          type: 'boolean',
+          default: false,
+          description: 'Plan the edits and return the change list without writing files or re-validating.',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_next_on_deck',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Returns the next task "on deck" from the HeySpex roadmap — the highest priority OPEN task in manifest order. This is what the agent should work on next, not what is already in progress. Response carries `user_prompt_markdown` (print verbatim) and `agent_dispatch` (decode as structured routing per specs/schemas/agent-dispatch.schema.json — never echo). The bundled `prompt_markdown` field is @deprecated; it now mirrors `user_prompt_markdown` (no agent prose). When the claim target has no `summary:`, the `author_summary_then_claim` phase names the write for THIS session: `heyspex_author_summary` (console PUT) in cloud reliance or for a Neon-only spec, the vault file via Edit only in local reliance ([[HS-T41O-NZ8S-DIAG]]).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Specific MILESTONE/epic/task ID to fetch NEXT STEP from (e.g., "HS-IUQO", "HS-EPIC-6RKN"). The short id is all that is needed. A milestone id resolves to that milestone\'s next on-deck epic — this is the parallel-agents entry point (owner ruling 2026-08-10): each CLI session runs `/hs-next <its milestone>` to drive its own milestone, while bare `/hs-next` remains the scheduler-fed GLOBAL queue and may surface unrelated items (triage, other milestones) by design. A session hand-off that continues a specific milestone must therefore name it. Bypasses focus.yaml and manifest lookup.',
+        },
+        roadmap_id: {
+          type: 'string',
+          description: "Roadmap to query (default: env HEYSPEX_ROADMAP_ID or 'HS-ROADMAP-PRODUCT')",
+        },
+        include_horizon: {
+          type: 'boolean',
+          default: false,
+          description: 'Include horizon backlog items if no scheduled tasks remain',
+        },
+        ignore_focus: {
+          type: 'boolean',
+          default: false,
+          description: 'Skip .heyspex/focus.yaml override and use manifest traversal',
+        },
+        persist_plan_ingest: {
+          type: 'boolean',
+          default: false,
+          description:
+            'When external .plan.md files resolve but the spec lacks ## Canonical implementation plan (HeySpex), write ingested content back into the spec file',
+        },
+        summary: {
+          type: 'boolean',
+          default: false,
+          description:
+            'Lightweight mode — return only the claim-target banner + alignment state (skip prompt_markdown body, WIP block, plan hydration, conflict scan, and design context). Used by the /hs-next slash command for a fast first-response before the user authorizes the claim. Re-call without summary after claim to get the full execution payload.',
+        },
+        auto_claim: {
+          type: 'boolean',
+          default: false,
+          description:
+            'Skip the yes/proceed/confirm handshake and claim immediately. Set automatically when front is autonomous (/hs-next auto, /hs-next-auto) or when the console injects --auto-claim on launch.',
+        },
+        front: {
+          type: 'string',
+          description:
+            `What's Next run front — handheld (default: drive one on-deck task), assist/assisted (dispatcher, human on the loop), auto/autonomous (unattended dispatcher). Aliases: ${runFrontCliHint()}.`,
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_author_summary',
+    description:
+      'Write a spec\'s plain-language `summary:` frontmatter field where this session\'s source of record lives ([[HS-T41O-NZ8S-DIAG]]) — the completion step of the /hs-next `author_summary_then_claim` phase. Cloud vault-write mode (prod, or dev-mode cloud reliance): GET /api/specs/:id, set `summary`, PUT /api/specs/:id — the Neon row is updated and nothing touches this machine\'s disk. Local mode: upserts the `summary: |` block scalar into the vault file\'s frontmatter. Only `summary` changes either way; every other field and the body are preserved. Pass the PROSE only (no `summary: |` YAML wrapper) authored per spec-summary-authoring (heyspex_get_procedure({ name: "spec-summary-authoring" })); the ≤160-char opening sentence / ≤400-char total targets come back as `warnings`, never a refusal. Then re-run heyspex_next_on_deck { summary: true } to reach the claim handshake.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Spec whose `summary:` to write — use `claim_target.spec_id` from the brief (short id or full basename).',
+        },
+        summary: {
+          type: 'string',
+          description:
+            'The authored summary as plain prose: ONE standalone opening sentence (target ≤160 chars) that says what this spec delivers and the parent goal it serves, optionally followed by a sentence or two of context (target ≤400 chars total). No YAML, no `summary:` prefix.',
+        },
+      },
+      required: ['spec_id', 'summary'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_next_review',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Returns the next review-ready spec from the HeySpex review queue — parent body + HS-REV companion + reviewer prompt markdown. Mirrors heyspex_next_on_deck but filters to status: in_review specs that have an HS-REV-<suffix>-*.md companion in specs/reviews/. Honors `.heyspex/review-focus.yaml` pin when present.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description:
+            'Specific spec id to fetch review context for (e.g., "HS-TASK-RVDC"). Bypasses .heyspex/review-focus.yaml pin and manifest lookup. Errors if the spec is not in_review or has no HS-REV companion.',
+        },
+        roadmap_id: {
+          type: 'string',
+          description: "Roadmap to query (default: env HEYSPEX_ROADMAP_ID or 'HS-ROADMAP-PRODUCT')",
+        },
+        ignore_focus: {
+          type: 'boolean',
+          default: false,
+          description: 'Skip .heyspex/review-focus.yaml override and use manifest/folder-scan traversal',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_next_resolution',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Returns the top open resolution item from the HeySpex Resolution lane + a fix-brief prompt_markdown — conflicts, dangling refs, cycles, prerequisites, validation/stale-index issues, ordered with gating/errors first. The agent face of the Resolution surface; ordered consistently with GET /api/resolution/next and honors the Neon focus pin. This is the surviving /hs-resolve (it never type-checks the target, so it no longer errors "Not an Epic" on a milestone). Reads console over HTTP — start the dev server if it is unreachable.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        item_key: {
+          type: 'string',
+          description:
+            'Specific resolution item key (e.g. "dangling_ref:hs-epic-x:hs-task-y") to fetch the fix brief for. Bypasses the focus pin.',
+        },
+        ignore_focus: {
+          type: 'boolean',
+          default: false,
+          description: 'Skip the Neon resolution focus pin and lead with the top-ranked open item.',
+        },
+        scope: {
+          type: 'string',
+          description:
+            'Deck-aware: restrict detection to one spec id (e.g. the on-deck claim-target epic) so its gating prerequisite surfaces. Mirrors GET /api/resolution?scope=.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_save_research',
+      description: 'Saves research findings to specs/research/ as HS-RES-XXXX-<slug>.md (random alphanumeric ID per [[vault-id-assignment-protocol]]). Use after web search or exploration. GATED ([[HS-K0ZP]]): refuses with PREFLIGHT_NOT_RUN unless research-capture-protocol was consulted this session -- heyspex_preflight({ intent: "research" }) (or file_research / promote_research, or heyspex_get_procedure on the protocol) first. The same rule gates WebSearch / WebFetch at PreToolUse. Owner-only break-glass: HEYSPEX_RESEARCH_PROTOCOL_GATE_OFF=1.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: {
+          type: 'string',
+          description: 'Descriptive title for the research (e.g., "Agent-Human Testing Workflow Research")',
+        },
+        summary: {
+          type: 'string',
+          description: 'Executive summary of research findings (2-5 sentences)',
+        },
+        content: {
+          type: 'string',
+          description: 'Full markdown content of the research (sections, tables, findings)',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tags for categorization (e.g., ["testing", "ux", "workflow"])',
+        },
+        related: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Related spec IDs as wikilinks (e.g., ["HS-EPIC-0033", "HS-TASK-FLX9"])',
+        },
+        sources: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              title: { type: 'string' },
+              url: { type: 'string' },
+              description: { type: 'string' },
+            },
+          },
+          description: 'Source URLs with titles and descriptions',
+        },
+        research_type: {
+          type: 'string',
+          enum: ['new-feature', 'enhancement', 'diagnose', 'code-audit', 'reference'],
+          description:
+            'Declared purpose of this research doc ([[entity-model]] §research). Defaults to "reference" when omitted, with a non-blocking `warning: "RESEARCH_TYPE_MISSING"` returned on the response — the save still succeeds ([[HS-MVC1-TASK-deterministic-research-type-assist-sugge]]). This tool has no source capture to derive a kind-based suggestion from (unlike heyspex_promote_capture, see research-type-suggest.mjs) — pass the value explicitly to avoid the warning.',
+        },
+        scope: {
+          type: 'string',
+          enum: ['internal', 'codebase', 'external', 'all'],
+          description:
+            'How broad a search context this research was run at ([[entity-model]] §research). Defaults to "internal" when omitted. Not required — a consistency fix ([[HS-NGD1-TASK-consolidate-and-fix-the-research-scope-field]]) so every research-creation path writes the same enum + default.',
+        },
+      },
+      required: ['title', 'summary', 'content'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_push_plan',
+    description:
+      'Write an epic plan into the HeySpex vault (specs/epics only — `children: []`). Ingests external Cursor/proprietary .plan.md files into ## Canonical implementation plan (HeySpex) on the spec. Requires `summary` at epic filing time per spec-summary-authoring. Tasks are NOT filed here — break down just-in-time via `/hs-next` + `heyspex_file_spec`. Use hs-push / hs-push-next; on_deck: true for focus + optional NEXT STEP override.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epic_name: {
+          type: 'string',
+          description: 'Human title for the epic (required)',
+        },
+        summary: {
+          type: 'string',
+          description:
+            'Required plain-language frontmatter summary for the epic at plan-ingest time (spec-summary-authoring).',
+        },
+        plan_markdown: {
+          type: 'string',
+          description: 'Epic body markdown (goal, phases, acceptance criteria)',
+        },
+        implementation_prompt: {
+          type: 'string',
+          description:
+            'Ready-to-paste agent prompt stored in epic NEXT STEP block (required when on_deck is true)',
+        },
+        source_plan_paths: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Absolute or repo-relative paths to .plan.md files to ingest (e.g. Cursor ~/.cursor/plans/foo.plan.md). Also auto-detects references inside plan_markdown.',
+        },
+        children: {
+          type: 'array',
+          description:
+            'Rejected — heyspex_push_plan files the epic with `children: []`. File tasks via `/hs-next` breakdown + heyspex_file_spec.',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              body: { type: 'string' },
+              summary: { type: 'string' },
+            },
+            required: ['name'],
+          },
+        },
+        on_deck: {
+          type: 'boolean',
+          default: false,
+          description:
+            'hs-push-next: set epic in_progress, write .heyspex/focus.yaml, add NEXT STEP block',
+        },
+        focus_reason: {
+          type: 'string',
+          description: 'Optional reason string stored in focus.yaml',
+        },
+        kind: {
+          type: 'string',
+          enum: ['foundation', 'feature', 'polish', 'infra'],
+          description: 'Scheduler kind classification for the epic (default: feature). See [[HS-DEC-deterministic-priority-scheduler]].',
+        },
+        effort: {
+          type: 'number',
+          enum: [1, 2, 3, 5],
+          description: 'Scheduler effort estimate in t-shirt sizes (default: 3 = M).',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Epic tags (default includes epic)',
+        },
+        related: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Wikilinks to related protocols/specs for conflict detection (e.g., ["companion-orb-ui-spec", "companion-ui-design-spec"])',
+        },
+        skip_conflict_check: {
+          type: 'boolean',
+          default: false,
+          description: 'Force the push even when behavioral conflicts are detected against linked specs. When on_deck: true, conflicts block the push by default (no files written, no focus pinned) — pass true to bypass (a conflict_override row should be recorded via the console Dismiss-with-reason action after landing).',
+        },
+        milestone: {
+          type: 'string',
+          description:
+            'Wikilink to the parent HS-MIL-* milestone this epic belongs to (e.g. "[[HS-MIL-HMNJ-status-and-roadmap-surface-refactor]]" or "HS-MIL-HMNJ-..."). REQUIRED per [[HS-TASK-T5PX]]. The milestone file must exist under specs/milestones/; this tool mirror-updates its `epics:` array.',
+        },
+      },
+      required: ['epic_name', 'milestone', 'summary'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_recall_memories',
+    budget: listBudget('memories'),
+    description: 'Retrieves project-level memories (lessons, decisions, references, ui-patterns) that the AI should know about. Call this at the start of a session or when working on a specific task to get relevant context. Memories help avoid repeating mistakes and understand past decisions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        category: {
+          type: 'string',
+          enum: ['all', 'lessons', 'decisions', 'references', 'ui-patterns'],
+          default: 'all',
+          description: 'Filter by memory category (default: all)',
+        },
+        related_to: {
+          type: 'string',
+          description: 'Filter to memories related to a specific spec ID (e.g., "HS-EPIC-0033")',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter by tags (e.g., ["testing", "mcp"])',
+        },
+        limit: {
+          type: 'number',
+          default: 10,
+          description: 'Page size (default: 10, max: 30). The response is ONE page under `memories` plus `next_cursor`, fitted to an 8 KB byte budget — never the whole memory set, never a total count ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]]).',
+        },
+        after: {
+          type: 'string',
+          description: 'Opaque cursor: the `next_cursor` value of the prior page. Omit for page 1. A page whose `next_cursor` is null was the last one.',
+        },
+        compact: {
+          type: 'boolean',
+          default: true,
+          description: 'Return compact summaries only (default: true). Set false for full body preview.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_backfill_epic',
+    description:
+      'Retroactively create an epic + child tasks for completed work ("backfill this completed work into the vault"). All specs are created with status: in_review and a review doc is auto-generated. Use /hs-backfill for the full workflow. (Renamed from heyspex_ship_epic / hs-ship 2026-06-19 so the word "ship" belongs to the Shipped surface — [[HS-TASK-1ZQF]].)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epic_name: {
+          type: 'string',
+          description: 'Human title for the epic (required)',
+        },
+        summary: {
+          type: 'string',
+          description:
+            'Required plain-language frontmatter summary for the epic (spec-summary-authoring). Also used in the review doc.',
+        },
+        plan_markdown: {
+          type: 'string',
+          description: 'Epic body markdown (what was done, acceptance criteria met)',
+        },
+        children: {
+          type: 'array',
+          description: 'Child tasks that were completed — each requires summary',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              summary: { type: 'string' },
+            },
+            required: ['name', 'summary'],
+          },
+        },
+        files_changed: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'List of files that were modified (for review doc)',
+        },
+        kind: {
+          type: 'string',
+          enum: ['foundation', 'feature', 'polish', 'infra'],
+          description: 'Scheduler kind classification for the epic (default: feature). See [[HS-DEC-deterministic-priority-scheduler]].',
+        },
+        effort: {
+          type: 'number',
+          enum: [1, 2, 3, 5],
+          description: 'Scheduler effort estimate in t-shirt sizes (default: 3 = M).',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tags for the epic',
+        },
+        related: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Wikilinks to related specs',
+        },
+        pillar: {
+          type: 'string',
+          description: 'Optional `[[HS-PILR-<slug>]]` for the backfilled epic. DEFAULTS to the parent milestone\'s authored pillar, which is right for most backfills; pass it explicitly only when the epic\'s own subject belongs to a different perpetual theme than its milestone does. Choose against each pillar\'s written charter (heyspex_suggest_pillar), never by pillar name ([[pillar-assignment-protocol]]). If neither this nor the milestone resolves, the call fails PILLAR_REQUIRED instead of writing an epic that fails the vault gate.',
+        },
+        roadmap_id: {
+          type: 'string',
+          description: 'Roadmap ID to register in (default: HS-ROADMAP-PRODUCT)',
+          default: 'HS-ROADMAP-PRODUCT',
+        },
+        roadmap_phase: {
+          type: 'string',
+          description: 'Phase ID to add epic to (default: P0). NOTE: HS-ROADMAP-PRODUCT is on manifest v3, which replaced `phases:` (P0–P7) with a flat `milestones:` array — so phase registration no-ops there and returns `roadmap_registration.success: false` with "Phase P0 not found". That is expected and harmless: a backfilled epic is reachable through its parent milestone. Pass skip_roadmap_registration: true to silence it.',
+          default: 'P0',
+        },
+        skip_roadmap_registration: {
+          type: 'boolean',
+          description: 'Skip adding epic to roadmap manifest (default: false)',
+          default: false,
+        },
+        milestone: {
+          type: 'string',
+          description:
+            'Wikilink to the parent HS-MIL-* milestone this epic belongs to (e.g. "[[HS-MIL-HMNJ-status-and-roadmap-surface-refactor]]" or "HS-MIL-HMNJ-..."). REQUIRED per [[HS-TASK-T5PX]]. The milestone file must exist under specs/milestones/; this tool mirror-updates its `epics:` array.',
+        },
+      },
+      required: ['epic_name', 'milestone', 'summary'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_active_capture',
+    description:
+      'Returns the capture on deck. Auto-creates and pins a fresh HS-CAP-* when none exists (agent-first capture). Also works after console + New → Capture or heyspex_pin_capture. Use with /hs-capture.\n\nMulti-agent warning ([[HS-1C4L-9VZV-DIAG-multi-agent-capture-focus-pin-collision]]): with no spec_id, this attaches to the most-recently-active PENDING capture for the owner — which may belong to a DIFFERENT concurrent session (another agent window, the console, or the companion app), not the one you are about to start. If you are opening a brand-new topic (not resuming a capture your OWN session already opened this conversation), pass force_new: true to guarantee a fresh capture instead of risking attachment to someone else\'s in-flight one.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Optional capture ID; default is .heyspex/capture-focus.yaml pin',
+        },
+        force_new: {
+          type: 'boolean',
+          description:
+            'Bypass pending-session attach/reuse entirely and unconditionally mint a brand-new capture session, even if another pending session exists for this owner. Use this when starting a genuinely new topic in a concurrent session, to avoid colliding with another live agent/console/companion session\'s in-flight capture ([[HS-1C4L-9VZV-DIAG-multi-agent-capture-focus-pin-collision]]). Ignored when spec_id is also passed.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_update_capture',
+    description:
+      'Capture to the on-deck capture: append verbatim user_quote, optional agent_note, author core_idea + summary (the zero-confirm baseline pass). agent_expansion (the `## Expanded Concept` deep-dive) is auto-written the moment the agent grounds the idea — grounding IS expansion, so write it immediately with no user confirmation. No epics/tasks at capture stage.\n\nMulti-beat protocol: separate calls are supported on the same spec_id across the capture flow (user_quote → core_idea → summary → agent_expansion) — the materialized spec file is re-stamped from the merged buffer on each save. `concept` is a deprecated alias for `summary`.\n\nError classes (per HS-EPIC-CPMR, corrected by HS-K27H-DIAG):\n  - CONSOLE_UNREACHABLE (status 0 — genuine transport failure: ECONNREFUSED/DNS/timeout/abort): call stashes verbatim input to the offline buffer; next reachable call replays. The ONLY class that buffers.\n  - CAPTURE_CONFLICT (4xx, e.g. abandoned session, invalid body): the server ANSWERED and rejected the write — payload is `status: "refused"` with `http_status` + `server_error` + `console_error` (verbatim server message); NOT stashed, NOT retried. Fix the request or start a new capture.\n  - PATCH_FAILED (5xx): the server ANSWERED and errored applying the write — payload is `status: "failed"` with the verbatim server message; NOT stashed, NOT retried (the console is NOT down; do not tell the user their words are buffered — they are not).\n  - CONSOLE_LOCAL_URL_IN_CLOUD_MODE (status 0, sign-in — HS-9R6S-N8VP-DIAG): HeySpex is in cloud mode but this machine is pointed at a local console, so the call never had a chance to go out. Payload is `status: "blocked"` with `buffered: false` and an `action` naming the sign-in command in the form this machine can run. NOT stashed, NOT retried. Do not say the words are buffered, and do not start a local dev server — cloud is the normal mode.\n  - CONSOLE_NOT_SIGNED_IN (no bearer token on this machine, or an answered HTTP 401 — HS-9R6S-N8VP-DIAG): the machine is not signed in, so the write was refused. Same `status: "blocked"` / `buffered: false` payload with an `action` naming the sign-in command. NOT stashed, NOT retried. The server is NOT down — run the command in `action`, then call again.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: { type: 'string', description: 'Capture ID (default: pinned capture)' },
+        core_idea: {
+          type: 'string',
+          description: 'Revised core statement — prefer user phrasing, ≤500 chars',
+        },
+        summary: {
+          type: 'string',
+          description:
+            'AI brief summary — authors the `## Summary` layer (one paragraph, ≤800 chars soft). Part of the zero-confirm baseline pass alongside core_idea (HS-EPIC-OED2).',
+        },
+        concept: {
+          type: 'string',
+          description: '@deprecated alias for `summary` (renamed concept→summary, HS-EPIC-OED2).',
+        },
+        user_quote: {
+          type: 'string',
+          description: 'Verbatim excerpt from the human in this turn (appended to Notes)',
+        },
+        agent_note: {
+          type: 'string',
+          description: 'Brief agent context using user words (appended to Notes)',
+        },
+        agent_expansion: {
+          type: 'string',
+          description:
+            'Expanded capture prose — auto-written the moment the agent grounds the idea (grounding IS expansion; no user confirmation needed); written as the `## Expanded Concept` deep-dive section below Notes (writing it flips capture_status raw → expanded). Not Core/Summary/Notes.',
+        },
+        example: {
+          type: 'string',
+          description:
+            'Concrete example illustrating the idea — written as the `## Example` section between Notes and Expanded Concept. Either a real verbatim example (label it real, e.g. "Real example:") or an AI-authored illustrative one (label it as such, e.g. "Illustrative example:"). Persisted across updates (HS-PR20-EPIC).',
+        },
+        user_stories: {
+          type: 'string',
+          description:
+            'User stories — written as the `## User Stories` section between Example and Expanded Concept. Optional but highly encouraged: 2-4 "As a <role>, I want <capability>, so that <outcome>." statements (format encouraged, not enforced). Roles must be real actors from the capture (owner, agent, user, reviewer — never invented personas); ground stories ONLY in what the capture says, never invent features. Preserve a user-provided story verbatim (format-wrap, never substitute); otherwise author at expand time alongside Core Idea/Summary, prompting the user for a missing role/capability/outcome when needed. Persisted across updates.',
+        },
+        kind: {
+          type: 'string',
+          enum: ['idea', 'bug-fix', 'clip', 'reference', 'question'],
+          description:
+            'Re-classify the capture kind — ONLY after the user confirms ([[HS-RZQO-TASK]] elicitation: suggest, never auto-apply). Suggest when the content signals one: error/stacktrace/bug/broken/regression language → bug-fix (unlocks the promote-to-diagnose exit); a bare URL / link-only body → clip; a pointer to a doc/resource to remember → reference; an open question to revisit → question; otherwise leave as idea. Most captures wrongly sit at the default idea — offer the suggestion in your reply ("this reads like a bug-fix capture — reclassify?") and pass this arg only on the user\'s yes. spec-import is importer-stamped and never agent-set. Also the fix for the promote sufficiency gate\'s "kind" missing-element ([[HS-NR43-DIAG-CAIO]]): pass this instead of force_promote when the gate reports kind as missing.',
+        },
+        done_when: {
+          type: 'string',
+          description:
+            'Author the `## Done When` checklist — markdown checklist lines (e.g. "- [ ] criterion") stating how the idea will be verified done. Written between User Stories and Expanded Concept. This is the fix for the promote sufficiency gate\'s "done-criteria" missing-element ([[HS-NR43-DIAG-CAIO]]): pass this instead of force_promote when the gate reports done-criteria as missing — elicit the criteria from the user rather than inventing them.',
+        },
+        jtbd: {
+          type: 'string',
+          description:
+            'The JTBD (job-to-be-done) — the underlying job the user is trying to get done, not the mechanism they happened to describe. Written as the `## JTBD (job-to-be-done)` section between User Stories and Done When. Authored by the `/hs-capture` enhancement pass per the 2026-08-23 owner ruling; persisted across updates (same contract as `example`/`user_stories`/`done_when`). Replaces the interim `JTBD (job-to-be-done):` leading block inside `## Expanded Concept`.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_pin_capture',
+    description:
+      'Pin an HS-CAP-* spec as capture-on-deck (.heyspex/capture-focus.yaml) for /hs-capture.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: { type: 'string', description: 'Capture spec id e.g. HS-CAP-1JJF' },
+        reason: { type: 'string', description: 'Optional pin reason' },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_active_research',
+    description:
+      'Returns the research-on-deck pin (.heyspex/research-focus.yaml) written by the console doc-toolbar Promote button. Mirrors heyspex_active_capture. Use with /hs-res.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'heyspex_complete_research',
+    description:
+      'Finalize a /hs-res session: atomically write specs/research/HS-RES-<id>-<slug>.md, set source idea promoted_to: "[[HS-RES-…]]", and clear .heyspex/research-focus.yaml. source_idea_id + scope come from the pin unless explicitly overridden.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Descriptive research title (required)' },
+        executive_summary: {
+          type: 'string',
+          description: 'Executive summary, 3–5 sentences (required if `summary` not provided)',
+        },
+        summary: {
+          type: 'string',
+          description: 'Alias for executive_summary (back-compat with heyspex_save_research callers)',
+        },
+        content: {
+          type: 'string',
+          description: 'Findings body markdown (required if `findings` not provided)',
+        },
+        findings: {
+          type: 'string',
+          description: 'Alias for content',
+        },
+        sources: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              title: { type: 'string' },
+              url: { type: 'string' },
+              description: { type: 'string' },
+            },
+          },
+          description: 'Source URLs with titles + descriptions',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tags (default: ["research"])',
+        },
+        related: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Related spec wikilinks (source idea is added automatically)',
+        },
+        source_idea_id: {
+          type: 'string',
+          description: 'Override source idea id (default: read from .heyspex/research-focus.yaml)',
+        },
+        scope: {
+          type: 'string',
+          enum: ['internal', 'codebase', 'external', 'all'],
+          description: 'Override scope (default: read from pin)',
+        },
+        owner: { type: 'string', description: 'Owner (default: pwher)' },
+      },
+      required: ['title'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_ground_plan',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Pre-plan grounding (lexical wide-recall + conflict/drift detection, read-only). Use /hs-ground. PREFER report:true — returns a single bounded ≤max_tokens markdown report (report_markdown) with six sections (Scope · Relevant specs · Relevant code · Graph hints · Conflicts · Gaps) that you paste verbatim and act on WITHOUT reading more files. The legacy compact/full modes return discovery arrays + the six-phase scaffold for the Cursor skill.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        topic: {
+          type: 'string',
+          description: 'Short title of the feature or request (required)',
+        },
+        summary: {
+          type: 'string',
+          description: 'Longer description from chat or draft plan',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Explicit tags to boost discovery (e.g. ["console", "mcp"])',
+        },
+        areas: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Areas: console, companion, mcp, vault, indexer',
+        },
+        include_codebase_hints: {
+          type: 'boolean',
+          default: true,
+          description: 'Include grep_queries, path_globs',
+        },
+        limit: {
+          type: 'number',
+          default: 8,
+          description: 'Max discovered specs per bucket (default 8, max 20)',
+        },
+        check_conflicts: {
+          type: 'boolean',
+          default: true,
+          description:
+            'Run conflict/drift analysis (focused epic, draft vs protocols, cross-spec drift). Same detector as console /api/specs/:id/conflicts',
+        },
+        compact: {
+          type: 'boolean',
+          default: true,
+          description:
+            'Compact mode (~6k tokens): discovered arrays → counts+basenames only. All workflow-critical fields preserved (anchors, stress_test_prompts, enhancement_suggestions, etc). Set false for full discovered objects (~17k tokens). Ignored when report:true.',
+        },
+        report: {
+          type: 'boolean',
+          default: false,
+          description:
+            'Bounded report mode (RECOMMENDED for /hs-ground): returns a single capped report_markdown (six sections) + token_estimate, suppressing discovery arrays / codebase_hints / stress prompts / read-everything next_steps. Paste report_markdown verbatim.',
+        },
+        max_tokens: {
+          type: 'number',
+          default: 2000,
+          description: 'Hard cap on report_markdown size when report:true (clamped 500–4000; default 2000).',
+        },
+      },
+      required: ['topic'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_claim_spec',
+    description:
+      'Claim a spec for the current agent session (POSTs /api/specs/:id/claim). Flips spec status to in_progress if currently draft/open/deferred and records the claim in .heyspex/active-claims.json so the Roadmap In Progress card shows a green agent badge. Call this after the user confirms claim+begin in the /hs-next gate; release with heyspex_release_spec on hand-off.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Spec id to claim (e.g. "HS-TASK-XA40", "HS-EPIC-Y9OJ")',
+        },
+        agent: {
+          type: 'string',
+          description:
+            'Agent display name (default: detected from env — "Claude Code" / "Cursor" / HEYSPEX_AGENT)',
+        },
+        session_id: {
+          type: 'string',
+          description:
+            'Session identifier (default: detected from CLAUDE_CODE_SESSION_ID / CURSOR_TRACE_ID / HEYSPEX_SESSION_ID)',
+        },
+        agent_profile: {
+          type: 'string',
+          description:
+            'Optional agent-identity slug to operate as for this claim (e.g. "code-reviewer", "plan-grounder"). Binds the claim to a HeySpex agent identity so the Agents surface shows this session under that identity (HS-EPIC-96YK). Omit to leave unbound.',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_release_spec',
+    description:
+      'Release a previously claimed spec (DELETEs /api/specs/:id/claim). Status is left as-is. Call when handing off mid-session or when the spec moves to in_review at session close-out.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Spec id whose claim should be cleared',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_report_progress',
+    description:
+      "Report the current work-stage of a claimed spec as you work (PATCHes /api/specs/:id/claim/status with status=working). The verb shows live on the What's Next surface (hero line + workflow spine), and ac_progress drives the task acceptance-criteria checklist — so the user sees what the agent is doing right now, not just that it is claimed. Call it as you move between stages (and bump ac_progress as you complete acceptance criteria during a task). The closed verb vocabulary is defined in the execute procedure (heyspex_get_procedure({ name: 'pre-execution-alignment-gate' })). Requires an existing claim on the spec (heyspex_claim_spec first) — returns 404 otherwise.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Spec id whose claim to update (e.g. "HS-TASK-XA40")',
+        },
+        current_stage: {
+          type: 'string',
+          enum: ['Grounding', 'Breaking down', 'Drafting', 'Validating', 'Testing', 'Reviewing'],
+          description:
+            'Present-progressive work-stage verb (closed vocabulary). Maps on the spine: Grounding/Breaking down → Break down, Drafting/Validating/Testing → Build, Reviewing → Review.',
+        },
+        ac_progress: {
+          type: 'number',
+          description:
+            'Optional 0-based index of the acceptance criterion you are currently on (task-grain). Criteria before it render as done in the checklist. Omit when not on a per-criterion task.',
+        },
+      },
+      required: ['spec_id', 'current_stage'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_promote_diagnose',
+    description:
+      "Break a bug write-up (HS-DIAG-*) down into planned work — the SAME breakdown stage `heyspex_promote_research` uses, entered from its second input kind ([[HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose]]: \"one stage, two inputs, not a second parallel tool\"). Use it when an investigation concludes the bug needs SEVERAL separately-verifiable fixes; a one-fix bug is claimed and fixed directly, exactly as today. The stage grounds first (reports the open milestone/epic already covering the area and recommends attaching over minting), then sizes by COUNTING the fixes the write-up's own `## Fix` section lists — never by length and never by AI judgment. Placement goes DOWN, never up: a matching epic gets tasks, a matching milestone with no fitting epic gets a new epic, and only when neither exists is a new milestone proposed, which asks the owner first. Everything spawned carries a resolvable milestone, no exemption. The write-up LINKS to what it spawned and never parents it — an epic parented to a bug report does not render on the roadmap — and its own `parent:` keeps its existing job of grouping small bugs under one epic. Once it has spawned work the write-up leaves the on-deck queue and its Resolution row stops offering a claim; it closes on `heyspex_verify_reproduction`, not when its child work closes.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        diagnose_id: {
+          type: 'string',
+          description:
+            'The bug write-up to break down. Accepts the frontmatter `id:` (e.g. HS-WZ62), the full file basename, the basename with .md, or a [[wikilink]]. Resolution reads specs/diagnoses/ and the file\'s own `type:` — no id-shape pattern match, so a bare era-3 file key works.',
+        },
+        accepted: {
+          type: 'boolean',
+          description:
+            'Two-phase, like the research path. Omit on the FIRST call to get the grounding report (what already covers this area), the ladder result (how many fixes the write-up lists and which rung that lands on), and the proposed placement — no writes. Show that to the human, then call again with `accepted: true` to execute.',
+        },
+        confirm_new_milestone: {
+          type: 'boolean',
+          description:
+            'Required only when the proposed placement is `new_milestone` — the last rung, reached only when grounding found neither a fitting epic nor a fitting milestone. Without it the execute refuses with OWNER_CONFIRMATION_REQUIRED and writes nothing. Pass true ONLY after the owner has agreed to the proposed milestone.',
+        },
+        pillar: {
+          type: 'string',
+          description:
+            'HS-PILR-* id/basename or [[wikilink]] for an epic this call would spawn. Optional when attaching under an existing milestone that declares its own `pillar:` (it is inherited); REQUIRED for the new-milestone rung. An unresolvable pillar fails the whole execute before any write.',
+        },
+        measurement_parent_epic: {
+          type: 'string',
+          description:
+            'Only for the measure-first hold — when the write-up concludes the cause is not yet known, the only thing filed is the measurement, and a task needs an epic to live under. Name one here when grounding found no covering epic. No epic and no milestone is ever minted on this path.',
+        },
+      },
+      required: ['diagnose_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_verify_reproduction',
+    description:
+      "Record a reproduction re-run on a diagnose (HS-DIAG-*, specs/diagnoses/) and close it when the run comes back clean — criterion 7 of [[HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose]]. A bug write-up that has been broken down into work closes when its REPRODUCTION stops reproducing, NOT when its last child task closes: every one of the seven prior console read-path attempts closed clean while the bug stayed live. This is also the only route a diagnose has to `closed` at all — a diagnose is standalone, so the console's review_pending cascade (which walks milestone → epic → task) never reaches it, and 211 diagnoses sit parked at in_review/review_pending as of 2026-08-22 with nothing that would ever move them. Re-run the `## Reproduction` steps in the write-up, then call this with the verdict. `no_longer_reproduces` on a build-complete (in_review/review_pending) diagnose closes it through PATCH /api/specs/:id/status — never a hand-edited `status:`. `still_reproduces` records the verdict and closes nothing. `evidence` (≥30 chars, saying what you re-ran and what happened) is required either way; a verdict with no account of the run is a green light wired to nothing. A second re-run OVERWRITES the recorded verdict — the history lives in the diagnose's ## Change log. Cloud contract ([[HS-7UJZ-O86I-DIAG]]): in cloud reliance the diagnose is resolved and the verdict recorded THROUGH the console (GET + PUT /api/specs/:id), so a diagnose filed in cloud mode that exists only as a Neon row closes too; in local reliance the disk scan runs first and the console is consulted only when specs/diagnoses/ has no match.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description:
+            'The diagnose to record against. Accepts the frontmatter `id:` (e.g. HS-WZ62), the full file basename, a [[wikilink]], or an unambiguous id prefix. Resolution reads specs/diagnoses/ and the file\'s own `type:` — no id-shape pattern match.',
+        },
+        result: {
+          type: 'string',
+          enum: ['no_longer_reproduces', 'still_reproduces'],
+          description:
+            'The verdict of the re-run, authored by whoever ran it — never inferred from whether the child work closed.',
+        },
+        evidence: {
+          type: 'string',
+          description:
+            'What you re-ran and what happened (≥30 characters). Written into frontmatter and the change-log row.',
+        },
+        by: {
+          type: 'string',
+          description: 'Who ran it. Defaults to the detected agent identity.',
+        },
+      },
+      required: ['spec_id', 'result', 'evidence'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_submit_for_review',
+    description:
+      "Submit a completed spec for review via PATCH /api/specs/:id/status (never hand-edit frontmatter status). Applies active review-grain coercion (in_review → review_pending for units below the grain), parent rollup, and spec events. Validates acceptance-criteria progress from the active claim unless skip_ac_check: true. Releases the claim by default. Returns close_out guidance for HS-REV vs change-log seed steps per session-close-protocol. Call once all acceptance criteria are verified — after incremental heyspex_report_progress ticks.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Spec id to submit (e.g. "HS-TASK-XA40", "HS-EPIC-Y9OJ")',
+        },
+        skip_ac_check: {
+          type: 'boolean',
+          description:
+            'Bypass the ac_progress >= criteria_count gate. Use only when criteria are genuinely N/A or progress was reported under a stale claim.',
+        },
+        release_claim: {
+          type: 'boolean',
+          description: 'Release the active claim after a successful status flip (default true).',
+        },
+        actual_tokens: {
+          type: 'number',
+          description:
+            'Optional: the real context-window tokens this task consumed, if the agent knows it. Stored beside the pre-build estimate so the sprint-grouping heuristics can be calibrated (HS-HBD2).',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_record_wip',
+    description:
+      "Record the machine-readable WIP ledger for an epic at session close (POSTs /api/specs/:id/wip → .heyspex/wip-state.json). This is the SOLE structured-handoff close action — the prose next-session-handoff.md journal is retired (HS-EPIC-HNDR). The touched + untracked file lists are captured from `git status` server-side — do NOT pass them; supply only the semantic fields you alone know. The next agent's /hs-next brief surfaces this entry so it reads state instead of reconstructing it from specs + git diff ([[HS-EPIC-FCSM]] forensic-reconstruction incident). The ledger is coordination only — route durable knowledge (decisions, rationale) to vault memory specs, not here. Omitted semantic fields preserve their prior values. THE HAND-OFF PROSE GOES IN `notes` — there is no `summary` field, and passing one (or any other unlisted argument) now FAILS the call by name rather than dropping it silently ([[HS-IRX0-5KFT-DIAG]]: four hand-offs written into `summary` were lost while every call reported success). A `notes` string over 4000 characters is refused, never clipped. Every success returns a measured `stored` receipt — read back from the ledger file after the write — naming the characters/items actually kept per field, so a write that lands empty is impossible to miss.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Epic id whose WIP to record (e.g. "HS-EPIC-FCSM")',
+        },
+        specs_filed: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Spec ids filed this session (e.g. ["HS-TASK-9CVR", "HS-TASK-PK4G"])',
+        },
+        remaining: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Remaining work items, one short line each (e.g. ["9CVR conveyor", "PK4G peek agenda"])',
+        },
+        verified: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'What was built AND verified, one line each (e.g. ["shell registered in surfaces.ts, chrome-hide works"])',
+        },
+        notes: {
+          type: 'string',
+          description:
+            'THE hand-off prose for the next agent — this is the only free-text field the ledger stores. Max 4000 characters; a longer string is refused by name, never clipped. Surfaces verbatim as **Notes:** in the next /hs-next brief.',
+        },
+        agent: {
+          type: 'string',
+          description: 'Agent display name (default: detected from env)',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Session identifier (default: detected from env)',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_defer_spec',
+    description:
+      'Defer remaining work on a claimed task to the next agent: files a split child with the handoff envelope (reason / summary_done / remaining / success_criteria), updates the parent (change-log + ## Split), pins the child on-deck, releases the parent claim, and records WIP on the parent epic. Invoked mid-session on the currently-claimed task per [[HS-TASK-1U0Z-hs-defer-mcp-tool-and-slash-command]] / [[HS-EPIC-YQ5A-delegation-defer-work-from-one-agent-to]]. Optional `handoff_id` dedups re-posts ([[HS-TASK-W146-defer-idempotency-handoff-id-and-cross-a]]).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Parent task id to defer (HS-TASK-*). Defaults to the task you hold a claim on when omitted.',
+        },
+        reason: {
+          type: 'string',
+          description: 'Why the defer/split happened (context budget, blocked, lane hand-off, etc.).',
+        },
+        summary_done: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Work completed before the handoff — mirrors WIP verified semantics.',
+        },
+        remaining: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Actionable items for the picking-up agent.',
+        },
+        success_criteria: {
+          type: 'array',
+          items: { type: 'string' },
+          description: "How the child spec's reviewer knows the deferred work is done.",
+        },
+        parent_status: {
+          type: 'string',
+          enum: ['in_review', 'in_progress'],
+          description:
+            'Parent status after defer (default in_review when remainder is independently reviewable).',
+        },
+        effort: {
+          type: 'number',
+          description: 'Re-estimated effort for the child remainder (inherits parent when omitted).',
+        },
+        child_name: {
+          type: 'string',
+          description: 'Optional title for the split child (default: "<parent name> (continued)").',
+        },
+        handoff_id: {
+          type: 'string',
+          description:
+            'Optional dedup key — re-posting defer with the same handoff_id returns the existing split child instead of filing a duplicate ([[HS-TASK-W146]]).',
+        },
+        pin_on_deck: {
+          type: 'boolean',
+          description: 'Pin the child on-deck for the next /hs-next (default true).',
+        },
+        release_claim: {
+          type: 'boolean',
+          description: 'Release the parent claim after defer (default true).',
+        },
+        record_wip: {
+          type: 'boolean',
+          description: 'Record WIP on the parent epic (default true).',
+        },
+        agent: {
+          type: 'string',
+          description: 'Agent display name (default: detected from env)',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Session identifier (default: detected from env)',
+        },
+      },
+      required: ['reason', 'summary_done', 'remaining', 'success_criteria'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_handoff_record',
+    description:
+      "Upsert the CURRENT resume context for this agent/lane into the Neon control plane (PUT /api/control/handoff-context). Self-purging: overwrite-in-place keyed on lane_key (default = this agent's session), TTL/expiry set server-side — NOT an append-only ledger. Coordination ONLY (spec_id, phase, blockers, estimated_time, links); decisions/rationale/knowledge route to vault memory specs, never here — the endpoint REJECTS knowledge fields. This is the Neon successor for the handoff-coordination job; the file-based heyspex_record_wip still runs alongside until the file→Neon cutover (HS-EPIC-PFMN). Requires a reachable console + Neon.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        lane: {
+          type: 'string',
+          description: "Lane key — the upsert identity. Default: this agent's session id (one lane per session). Pass an explicit lane to share/overwrite a named lane.",
+        },
+        spec_id: {
+          type: 'string',
+          description: 'Current spec id being worked (e.g. "HS-EPIC-NCPS"); omit when no spec is in flight',
+        },
+        phase: {
+          type: 'string',
+          description: 'Short phase label (e.g. "slice", "verifying")',
+        },
+        blockers: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Coordination blockers, one short line each',
+        },
+        estimated_time: {
+          type: 'string',
+          description: 'Human time estimate to resume/finish (e.g. "~2h")',
+        },
+        links: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Relevant spec ids / links to resume against',
+        },
+        agent: {
+          type: 'string',
+          description: 'Agent display name (default: detected from env)',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Session identifier (default: detected from env; also the default lane)',
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_handoff_load',
+    budget: READ_TOOL_BUDGET,
+    description:
+      "Read the CURRENT resume context for a lane from the Neon control plane (GET /api/control/handoff-context). Default reads this agent's own lane (its session); pass lane to read a specific lane, or all:true to list every active lane (parallel-agent off-on-deck context). Self-purging — there is no per-session history to page through; expired rows read as absent.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        lane: {
+          type: 'string',
+          description: "Lane key to read. Default: this agent's session id.",
+        },
+        all: {
+          type: 'boolean',
+          description: 'List every active lane for this user instead of a single lane (ignores `lane`).',
+        },
+        agent: {
+          type: 'string',
+          description: 'Agent display name (default: detected from env)',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Session identifier (default: detected from env; also the default lane)',
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_pin_get',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Read the current on-deck pinned spec from the Neon control plane (GET /api/control/pin). Returns the pin row (spec_id, pinned_by, expires_at) or null when no pin is set / the fuse has blown. Requires a reachable console + Neon.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_milestone_show',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Show a milestone (GET /api/specs/:id). Returns its id, name, status, created, and the structured needs-breakdown shape — epics_count, needs_breakdown (true when epics: []), needs_breakdown_message (the locked "Needs breakdown — file the first epic to start", else null). Consume needs_breakdown directly; do not re-derive from epics_count. [[HS-TASK-HMSE]] / [[HS-EPIC-MNBD]].',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Milestone id or basename (e.g. "HS-MIL-HMNJ").',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_pin_set',
+    description:
+      'Set or clear the on-deck pin via the Neon control plane (PUT /api/control/pin). Pass spec_id to pin a spec; OMIT spec_id (or pass null) to CLEAR the pin. Set/clear are logged as focus_events. ttl_ms: omit = default 7-day fuse, null = no fuse, number = custom ms. Requires a reachable console + Neon.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: ['string', 'null'],
+          description: 'Spec id to pin (e.g. "HS-EPIC-CLMW"). Omit or null to clear the pin.',
+        },
+        pinned_by: {
+          type: 'string',
+          description: 'Actor doing the pinning (default: detected agent identity).',
+        },
+        ttl_ms: {
+          type: ['number', 'null'],
+          description: 'Fuse in ms; null = no fuse. Omit for the server default 7-day fuse.',
+        },
+        agent: {
+          type: 'string',
+          description: 'Agent display name (default: detected from env)',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Session identifier (default: detected from env)',
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_resolve_prerequisite',
+    description:
+      'Execute ONE deterministic cross-milestone prerequisite resolution path via the console (POST /api/focus/prereq). The blocked spec depends on a prereq that lives elsewhere; `path` chooses how to resolve it: "do_first" (work the prereq now, then return), "switch_milestone" (move focus to the prereq\'s milestone), "move_in" (relocate the prereq into the blocked spec\'s milestone — REQUIRES confirm: true), "dispatch" (hand the prereq to another agent), or "defer" (push the blocked spec behind the prereq). Optional auto_return brings focus back to the blocked spec when the prereq resolves. Returns { ok: true, result } on success; a 409 confirmation_required (e.g. an unconfirmed move_in) and other failures surface the console error body. Requires a reachable console. [[HS-EPIC-QQBD]]',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        blocked_id: {
+          type: 'string',
+          description: 'Spec id that is blocked by the prerequisite (e.g. "HS-EPIC-CLMW").',
+        },
+        prereq_id: {
+          type: 'string',
+          description: 'Spec id of the prerequisite that must be resolved.',
+        },
+        path: {
+          type: 'string',
+          enum: ['do_first', 'switch_milestone', 'move_in', 'dispatch', 'defer'],
+          description:
+            'The resolution path to execute. "move_in" requires confirm: true.',
+        },
+        auto_return: {
+          type: 'boolean',
+          description:
+            'Return focus to the blocked spec automatically once the prerequisite resolves.',
+        },
+        confirm: {
+          type: 'boolean',
+          description: 'Required (true) for the "move_in" path; the console returns 409 confirmation_required without it.',
+        },
+        prereq_milestone_id: {
+          type: 'string',
+          description: 'Milestone id of the prerequisite (optional hint; resolved server-side when omitted).',
+        },
+        blocked_milestone_id: {
+          type: 'string',
+          description: 'Milestone id of the blocked spec (optional hint; resolved server-side when omitted).',
+        },
+        return_to: {
+          type: 'string',
+          description: 'Spec id to return focus to (optional; defaults to the blocked spec).',
+        },
+      },
+      required: ['blocked_id', 'prereq_id', 'path'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_claim_acquire',
+    description:
+      'Atomically acquire a claim on a spec via the Neon control plane (POST /api/control/active-claims/acquire). Returns acquired:true with the claim on success, or acquired:false + already_claimed naming the existing claimant when another agent holds it (atomic INSERT … ON CONFLICT — exactly one of N concurrent acquires wins). This is the control-plane primitive that heyspex_claim_spec routes through once the file→Neon cutover lands (HS-EPIC-PFMN). Requires a reachable console + Neon.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Spec id to claim (e.g. "HS-EPIC-CLMW").',
+        },
+        ttl_ms: {
+          type: ['number', 'null'],
+          description: 'Claim fuse in ms; null = no fuse. Omit for the server default.',
+        },
+        agent: {
+          type: 'string',
+          description: 'Agent display name (default: detected from env)',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Session identifier (default: detected from env)',
+        },
+        wait_if_held: {
+          type: 'boolean',
+          description:
+            'When true and the spec is already claimed, join the waiting line behind the holder instead of just being refused — the refusal then reports the waiter\'s queue position. Omit for today\'s behaviour (a held spec just refuses).',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_claim_release',
+    description:
+      'Release a claim on a spec via the Neon control plane (DELETE /api/control/active-claims/:spec_id). Returns released:true, or not_found when no active claim exists for the spec. Logs a released claim_event. Requires a reachable console + Neon.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Spec id whose claim to release.',
+        },
+        agent: {
+          type: 'string',
+          description: 'Releasing agent (recorded on the event; default: detected from env)',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Session identifier (default: detected from env)',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_claim_list',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'List all active claims from the Neon control plane (GET /api/control/active-claims), newest first. Use as parallel-agent off-on-deck context to see which specs other agents currently hold. Requires a reachable console + Neon.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_claim_file',
+    description:
+      'Claim a file path for exclusive editing (POSTs /api/file-claims/acquire). Default TTL 5 minutes — a crashed agent releases the file after expiry. Returns acquired:true on success, or acquired:false + the claiming agent when another agent holds the file. Call before writing to a shared spec file — this is the ephemeral stopgap ([[HS-Y00G-EPIC]]) that prevents silent data loss while the CRDT layer is built.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: {
+          type: 'string',
+          description: 'Vault-relative path to claim (e.g. "specs/epics/HS-EPIC-YQ5A.md")',
+        },
+        agent: {
+          type: 'string',
+          description: 'Agent display name (default: detected from env)',
+        },
+        session_id: {
+          type: 'string',
+          description: 'Session identifier (default: detected from env)',
+        },
+        ttl_ms: {
+          type: ['number', 'null'],
+          description: 'Claim TTL in ms; defaults to 5 minutes (300000).',
+        },
+        working_spec_id: {
+          type: 'string',
+          description: 'The spec id the agent is working on (informational, optional).',
+        },
+      },
+      required: ['file_path'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_release_file_claim',
+    description:
+      'Release a file claim (DELETEs /api/file-claims/release). Call after writing to release the lock so other agents can edit. Also auto-released by TTL expiry on crashed agents.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: {
+          type: 'string',
+          description: 'Vault-relative path to release',
+        },
+      },
+      required: ['file_path'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_list_known_tags',
+    budget: listBudget('tags'),
+    description:
+      'List the vault tag vocabulary (GET /api/scheduler/known-tags): distinct frontmatter `tags:` values with per-tag spec counts, sorted by count desc then tag asc. The reply is ONE page under `tags` plus `next_cursor` (keyset over (count, tag) from an aggregate query — never the whole vocabulary, never a total count; [[HS-4H8T-8KK5-TASK-every-mcp-read-tool-declares-a-byte]] resolving [[HS-7QM6-1Q1C-DIAG-heyspex-list-known-tags-response-busts-t]]). Call this BEFORE proposing a focus-areas pivot so you only suggest tags that actually exist — agents must pick from this closed vocabulary, never invent tags ([[HS-EPIC-7WJN]] / focus-intent-routing); the first page (most-used tags) is what a focus pivot needs. Also returns `drift: [{ a, b, reason, similarity }]` — near-duplicate tag pairs within the page (e.g. `chrome-ext`/`chrome-extension`) flagged by lexical string similarity so you can propose a merge; no tag is changed automatically ([[HS-TASK-H0SI]]). Requires a reachable console.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          default: 100,
+          description: 'Page size (default: 100, max: 500). The page is fitted to the tool byte budget — a trimmed page hands back a `next_cursor` that resumes at the first tag dropped.',
+        },
+        after: {
+          type: 'string',
+          description: 'Opaque cursor: the `next_cursor` value of the prior page. Omit for page 1. A page whose `next_cursor` is null was the last one.',
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_set_focus_areas',
+    description:
+      'Declare the active roadmap focus areas (PUT /api/scheduler/focus-areas). Specs whose `tags:` intersect this set float to the top of their layer on the What\'s Next / roadmap surfaces; everything else stays in scheduler order but dims. Pick `tags` ONLY from heyspex_list_known_tags (closed vocabulary). Follow the focus-intent-routing procedure: confirm with the user first, and NEVER add a tag the user said to STOP working on (negation). Returns the new state. Requires a reachable console.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        rationale: { type: 'string', description: 'Short reason for the pivot (user-facing).' },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tag strings from the known-tags vocabulary to focus on.',
+        },
+        expires_at: { type: 'string', description: 'Optional ISO 8601 expiry; omit for no fuse.' },
+        replace: {
+          type: 'boolean',
+          description: 'Replace the current focus set (default) vs merge — the route treats focus as replace-by-default.',
+        },
+      },
+      required: ['tags'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_get_focus_areas',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Read the current roadmap focus areas (GET /api/scheduler/focus-areas) → the active state, or { active: false } when none is set. Requires a reachable console.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_clear_focus_areas',
+    description:
+      'Clear the roadmap focus areas (DELETE /api/scheduler/focus-areas) — the roadmap returns to undimmed scheduler order. Returns { active: false }. Requires a reachable console.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_resolve_focus_intent',
+    description:
+      'Resolve a free-text focus utterance to a WIDE candidate window of relevant specs via lexical wide-recall (BM25 over titles/bodies/tags), tuned for Recall@N — YOUR LLM reranks the window to pick the focus tags ([[llm-as-reranker-lexical-recall-companion-architecture]]). NOT embeddings (Gate B = NO, [[retrieval-substrate-lexical-not-embeddings-gate-b-no]]). Returns { utterance, candidates: [{ spec, tags, why }], total }; top_k caps the window (default 30, max 50). Utterances need not use a spec\'s exact tag word. Returns an empty window (not an error) on no match; fall back to heyspex_list_known_tags + exact-tag NLU when the window is empty.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        utterance: { type: 'string', description: 'The user\'s free-text focus phrase.' },
+        top_k: { type: 'number', description: 'Optional max suggestions to return (Phase B).' },
+      },
+      required: ['utterance'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_search_specs',
+    budget: listBudget('matches'),
+    description:
+      'Search the CLOUD spec vault by TEXT — the duplicate check to run before filing a diagnose/task/epic ([[HS-YFLS]]). Pass the raw symptom sentence as `query`; the tool splits it into bounded angles (the phrase, quoted concept bigrams, the OR-ed salient terms) against GET /api/search and merges the windows, because a long sentence passed verbatim is AND-ed by websearch_to_tsquery and matches nothing. Reads the SYSTEM OF RECORD over HTTP — never local disk, whose mirror is incomplete in PROD mode — so a `grep` of the checkout is not a substitute. Returns { query, terms, queries_tried, searched, result, match_count, matches: [{ id, name, type, status, rank, snippet, matched_by }] }. NEGATIVES ARE EXPLICIT AND DISTINCT: `result: "no_match"` with `searched: true` means the corpus was read and holds nothing (safe to file); `result: "no_query"` means nothing searchable was extracted; every transport/auth/scope problem is an isError envelope (CONSOLE_UNREACHABLE, CONSOLE_NOT_SIGNED_IN, VAULT_SCOPE_UNRESOLVED, VAULT_SCOPE_UNAUTHORIZED, SEARCH_FAILED) — NEVER an empty list. Use this, not heyspex_resolve_focus_intent, to find a specific spec: that tool resolves a focus utterance to a wide tag-based window for reranking and will happily return 20 specs that share one broad tag.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'The symptom sentence or concept to search for, as you would write it in a bug report. Long sentences are fine and preferred — the tool extracts the salient terms itself.',
+        },
+        top_k: {
+          type: 'number',
+          description: 'Max matches to return (default 10, max 30).',
+        },
+        type: {
+          type: 'string',
+          description: 'Optional spec-type filter, single or CSV (e.g. "diagnose" or "task,epic").',
+        },
+        status: {
+          type: 'string',
+          description: 'Optional status filter, single or CSV (e.g. "open,in_progress"). Omit when checking for duplicates — a closed spec is still a duplicate.',
+        },
+      },
+      required: ['query'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_events_show',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Read the per-spec audit log from the Neon control plane (GET /api/control/spec-events), newest first. Optional kind / since / limit filters. event kinds: status_change, wikilink_added, wikilink_removed, review_requested, review_resolved, priority_change, parent_change, claim_acquired, claim_released. Requires a reachable console + Neon.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Spec id whose event log to read.',
+        },
+        kind: {
+          type: 'string',
+          description: 'Filter by event kind (one of the nine spec_event kinds).',
+        },
+        since: {
+          type: 'string',
+          description: 'Only events at/after this ISO date.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Cap the number of rows returned (positive integer).',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_evidence_show',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Read a spec\'s FULL consolidated evidence trail in one call (GET /api/evidence/:specId): the `## Change log` table parsed from the spec markdown, `spec_events` from the Neon control plane, and matching dev-factory cost-ledger / seat-gate / seat-audit rows. Backs both the console UI and this tool from the same logic ([[HS-BNDJ-TASK-consolidated-evidence-read-path-evidence]]). Pass the spec BASENAME when you have it (e.g. "HS-BNDJ-TASK-consolidated-evidence-read-path-evidence") — child tasks of an epic share the frontmatter id, so the basename is the only unique handle per task; a bare shared id resolves to no match (returns found:false plus the sibling basenames to disambiguate with). Never errors on an unknown/missing spec — returns { found: false, notes: [...] } instead of failing. NOTE: cost-ledger/seat-gate/seat-audit rows are keyed by the dev-factory pipeline\'s bare id only, so when the resolved spec shares its id with siblings those three sections may include sibling rows too — the response\'s `notes` field calls this out when it applies. Requires a reachable console.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Spec basename (preferred, unique) or bare frontmatter id whose evidence trail to read.',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_export_events',
+    description:
+      'Run the idempotent audit export (POST /api/control/export-events): the control-plane event logs (claim_events + focus_events + spec_events on the paid tier; .heyspex/*-history.jsonl on the free tier) land in specs/events/YYYY-MM.jsonl, one file per UTC month, byte-identical on re-run. A LOCAL console writes the files into its own vault; a CLOUD console (app.heyspex.com) has no vault on disk, so it RETURNS the month files and this tool merges them into the vault repo this session resolves (the receipt names files_written_locally / unchanged_locally) — run it from a checkout of the vault repo. Call this at session close to flush the audit trail to the vault (git-clone-is-backup). Optional since lower bound. Requires a reachable console; works on both tiers and both modes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since: {
+          type: 'string',
+          description: 'Only export events at/after this ISO date (default: all history).',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_record_alignment',
+    description:
+      'Record the pre-execution alignment checkpoint on an epic/milestone after breaking it down or revisiting its tasks for drift ([[pre-execution-alignment-gate]]). Writes alignment_reviewed_at (+ optional alignment_summary / alignment_override) into the spec frontmatter, which clears the hard gate that /hs-next raises on a childless or drifted node. Pass override_reason to proceed past a drift finding you judge a false positive / intentional supersession — it is stored as alignment_override for the audit trail. The gate re-fires when a corpus doc (related/depends_on/milestone) is modified after the checkpoint (temporal drift, HS-TASK-DCRP) or the 7-day fuse expires. (Signature hashing was removed in HS-TASK-DSIG — it was non-deterministic; drift is now temporal, not hash-based.)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        spec_id: {
+          type: 'string',
+          description: 'Epic or milestone id to checkpoint (e.g. "HS-EPIC-MILE", "HS-MIL-IART")',
+        },
+        summary: {
+          type: 'string',
+          description: 'One-line note on what was broken down / confirmed (stored as alignment_summary)',
+        },
+        override_reason: {
+          type: 'string',
+          description: 'Why a detected drift finding is being accepted/overridden (stored as alignment_override). Must be at least 40 characters AFTER TRIMMING and actually say why the finding is a false positive or an intentional supersession — a shorter one, an empty string, or whitespace only returns `error: "ALIGNMENT_OVERRIDE_REASON_TOO_THIN"` and records nothing at all (not even the checkpoint). The response reports `overridden` per what was actually STORED. Omit this argument entirely on a clean review — note that omitting it clears the checkpoint with no reason bar, because the gate reads alignment_reviewed_at and never reads alignment_override.',
+        },
+        skipped_despite_findings: {
+          type: 'boolean',
+          description:
+            'After a breakdown review (step 1b): false when BLOCKER/SIBLING findings were resolved before filing; true when you filed despite unresolved findings. Stamps the plan-review marker for skip-rate telemetry ([[HS-TASK-MEN2]]). Omit when no breakdown review ran.',
+        },
+      },
+      required: ['spec_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_propose_metadata',
+    description:
+      'AI-propose the four scheduler fields (depends_on, kind, effort, requires_user_testing) plus a reasoning string for a new task/epic via console POST /api/ai/propose-metadata. Haiku 4.5; one-shot at create time only — never on edit, status change, or update flows ([[HS-TASK-TAOD]]). Returns { ok, kind, effort, requires_user_testing, depends_on, reasoning } on success; { ok: false, reason, message } on failure (caller falls back to manual entry).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Spec name / title' },
+        body: { type: 'string', description: 'Spec body markdown that the model reads' },
+        specType: {
+          type: 'string',
+          enum: ['task', 'epic', 'capture'],
+          description: 'Spec type being proposed for (informs the prompt framing)',
+        },
+        parentExcerpt: {
+          type: 'string',
+          description: 'Optional excerpt of the parent epic body for tier calibration',
+        },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_promote_research',
+    description:
+      'Promote a research doc (HS-RES-*) to a milestone with AI-assisted epic stubs ([[HS-TASK-QQHP]]). **Default: target_milestone "NEW"** (omit target_milestone to default). Attaching to an existing milestone is the exception — target must be status: open; in_progress requires attach_to_in_progress_milestone + attach_override_reason (≥40 chars). Two-phase flow: omit accepted_stubs for AI proposals (Phase 1), then call again with accepted_stubs to execute (Phase 2). Research stays status: open (evergreen); enhances link is the promoted signal. Every spawned epic requires a resolvable `pillar:` (top-level `pillar` batch default or a per-stub override) — an unresolved pillar fails the whole execute with `error: "pillar_required"` before any write ([[pillar-assignment-protocol]]). Spawned milestone + epics also inherit `family:` from the source research doc.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        research_id: {
+          type: 'string',
+          description: 'Id or basename of the research to promote (must be in vault; must not already enhance the target milestone). Accepts the frontmatter `id:` (e.g. HS-X5FH), the full file basename (HS-X5FH-TN54-RES-<slug>), the basename with .md, a [[wikilink]], or a legacy HS-RES-* id.',
+        },
+        target_milestone: {
+          type: 'string',
+          description:
+            'Optional. Defaults to "NEW". HS-MIL-* id/basename for an existing open milestone (exception path), or "NEW" to create a fresh milestone (then new_milestone_name is required).',
+        },
+        new_milestone_name: {
+          type: 'string',
+          description: 'Required when target_milestone === "NEW". Human-readable milestone title.',
+        },
+        attach_to_in_progress_milestone: {
+          type: 'boolean',
+          description:
+            'Rare owner exception only. When true, allows spawning into a target milestone with status: in_progress. Requires attach_override_reason (≥40 chars). Default false — use NEW instead.',
+        },
+        attach_override_reason: {
+          type: 'string',
+          description:
+            'Audit trail when attach_to_in_progress_milestone is true. Must be ≥40 chars explaining why epics belong on an in-progress milestone.',
+        },
+        intent: {
+          type: 'string',
+          enum: ['spawn', 'augment', 'both'],
+          description:
+            'spawn = create new epics from AI stubs; augment = record research-side reverse pointers on existing epics; both = do both.',
+        },
+        spawn_epic_count: {
+          type: 'number',
+          description: 'Hint for the AI proposer for how many stubs to propose (clamped to [1, 6]). Default 2.',
+        },
+        augment_epic_ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Required when intent includes "augment". HS-EPIC-* ids (or basenames) of existing epics to augment. Each must already belong to the target milestone.',
+        },
+        pillar: {
+          type: 'string',
+          description:
+            'Batch-default pillar for every spawned epic: an HS-PILR-* id/basename or [[wikilink]] naming an existing pillar doc under specs/pillars/ ([[pillar-assignment-protocol]]). A per-stub `pillar` (in accepted_stubs) overrides this default. REQUIRED whenever accepted_stubs is present (Phase 2 execute) — either this top-level default or a per-stub override must resolve for EVERY spawned epic to a pillar that exists on disk BEFORE any file is written, mirroring POST /api/specs\' hard-block on epics without one. If neither is supplied or the reference does not resolve, execute fails the WHOLE call with `error: "pillar_required"` (lists the pillars that DO exist) before any write; no partial spawn.',
+        },
+        accepted_stubs: {
+          type: 'array',
+          description:
+            'Phase-2 execution payload. Each stub is the agent-confirmed (possibly edited) form of a Phase-1 proposed_stubs entry. Required to execute the spawn writes; omit on the first call to get AI proposals back for review. Every stub here spawns an epic, and every spawned epic REQUIRES a resolvable pillar (this stub\'s `pillar` or the top-level `pillar` batch default) — an unresolved pillar fails the whole execute with `error: "pillar_required"` before any file is written.',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              kind: { type: 'string', enum: ['infra', 'foundation', 'feature', 'polish'] },
+              effort: { type: 'number', enum: [1, 2, 3, 5, 8, 13] },
+              depends_on: { type: 'array', items: { type: 'string' } },
+              rationale: { type: 'string' },
+              pillar: {
+                type: 'string',
+                description:
+                  'Per-stub pillar override (HS-PILR-* id/basename or [[wikilink]]) — wins over the top-level `pillar` batch default. REQUIRED (this or the top-level default) for this stub\'s spawned epic to resolve; same `pillar_required` failure mode — fails the whole execute before any write — when neither resolves to a pillar doc on disk.',
+              },
+            },
+            required: ['name', 'kind', 'effort'],
+            additionalProperties: false,
+          },
+        },
+        stub_edit_note: {
+          type: 'string',
+          description:
+            'What the human changed about the proposed stubs, and why (≥40 chars). Only needed when NONE of the accepted_stubs names match any name from the Phase-1 proposal — a full rewrite is legitimate, but so is an agent inventing stubs after the review, and the two look identical from here. Supplying this records the human\'s intent; without it a fully-drifted execute returns `error: "STUB_REVIEW_DRIFT"`.',
+        },
+      },
+      required: ['research_id', 'intent'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_promote_capture',
+    description:
+      'Promote 1+ captures (HS-CAP-*) into a research doc (HS-RES-*, new or existing) with AI-assisted outline ([[HS-TASK-WQCE]] of [[HS-EPIC-M2J3]]). Two-phase flow when `target_research: "NEW"`: omit `accepted_outline` to get an AI-proposed `{ name, outline, tags, enhances_suggestion }` back for human review (Phase 1: no file writes), then call again with the same args plus `accepted_outline: {...}` to execute the transactional writes (Phase 2: creates the research file with sources_captures populated, mutates each capture\'s informs_research, sets promoted_to on first promotion only). Existing-research target skips Phase 1 — the tool goes straight to the bidirectional append and is idempotent on re-runs. Closed-research target is allowed but flagged with `warning: "TARGET_RESEARCH_CLOSED"`; the closed research keeps its existing enhances pointer untouched. The Phase-2 response also carries `research_still_stub` / `unresolved_placeholder_count` / `next_step` — when the resulting research doc still has unresolved `_TBD — fill in this section._` outline placeholders (freshly created, or an existing target that was never filled in), it is an outline of section headings only, NOT authored findings; run the `/hs-res` method against it before calling `heyspex_promote_research`, which will otherwise refuse with `RESEARCH_STILL_STUB` ([[HS-DSFO-49G3-DIAG-promote-capture-s-success-response]]). A NEW research doc INHERITS the family key of the first/primary capture_ids entry unconditionally ([[family-id-is-inherited-capture-research]], owner ruling 2026-07-12) — any number of research docs may now legally share one family key (the V3 shared-surname model, [[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]: `id:` keys onto the per-file file key, not the family, so there is no collision to fall back from). Bidirectional consistency (capture.informs_research ⇔ research.sources_captures) is enforced by scripts/validate-vault-ids.mjs per [[HS-TASK-YJX6]].',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        capture_ids: {
+          type: 'array',
+          minItems: 1,
+          items: { type: 'string' },
+          description: 'One or more HS-CAP-* ids to promote into the target research.',
+        },
+        target_research: {
+          type: 'string',
+          description:
+            'HS-RES-* id of an existing research, OR the literal string "NEW" to create a fresh research doc (then new_research_name + accepted_outline are required).',
+        },
+        new_research_name: {
+          type: 'string',
+          description:
+            'Required when target_research === "NEW". Working name used in the AI prompt as a hint; the human may edit before confirming accepted_outline.name.',
+        },
+        enhances: {
+          type: 'string',
+          description:
+            'Optional HS-MIL-* id or basename. When set on a NEW research create, the research is filed with enhances pointing at that milestone. Omit to leave the research exploratory (enhances added later by /hs-promote-research).',
+        },
+        accepted_outline: {
+          type: 'object',
+          description:
+            'Phase-2 execution payload (only required for target_research === "NEW"). The agent-confirmed (possibly edited) form of the Phase-1 proposed_outline. For existing target_research no outline is needed — sources_captures is just extended.',
+          properties: {
+            name: { type: 'string', description: 'Final research name (used to form the slug + title).' },
+            outline: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Ordered list of section headings the new research doc should contain.',
+            },
+            tags: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Frontmatter tag list for the new research doc.',
+            },
+            enhances_suggestion: {
+              type: 'string',
+              description: 'Optional milestone basename suggestion echoed from the AI for the audit trail.',
+            },
+            research_type: {
+              type: 'string',
+              enum: ['new-feature', 'enhancement', 'diagnose', 'code-audit', 'reference'],
+              description:
+                "The declared purpose of the new research doc ([[entity-model]] §research, [[HS-120I-TASK-implement-research-type-field-end-to-end]]). Written into frontmatter; defaults to 'reference' when omitted. HS-MVC1 supplies a kind-derived suggestion here.",
+            },
+            scope: {
+              type: 'string',
+              enum: ['internal', 'codebase', 'external', 'all'],
+              description:
+                "How broad a search context this research was run at ([[entity-model]] §research, [[HS-NGD1-TASK-consolidate-and-fix-the-research-scope-field]]). Written into frontmatter; defaults to 'internal' when omitted.",
+            },
+          },
+          required: ['name', 'outline'],
+          additionalProperties: false,
+        },
+        force_promote: {
+          type: 'boolean',
+          description:
+            'Sufficiency-gate override ([[HS-0CFX-TASK]] / [[HS-3EFV-EPIC]]). Promotion is blocked with `error: "CAPTURE_INSUFFICIENT"` (naming the missing elements: core-idea, example, done-criteria, kind, user-stories) when a capture scores below the sufficiency bar — the intended response is to ELICIT the missing detail from the user and improve the capture, not to force. Pass true ONLY when the human explicitly says to promote anyway.',
+        },
+      },
+      required: ['capture_ids', 'target_research'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_promote_capture_to_diagnose',
+    description:
+      'Promote ONE bug-report capture (HS-CAP-*) into a new first-class diagnose spec (HS-DIAG-*, specs/diagnoses/) — the executable bug fix ([[HS-MIL-BFIX]]). Single-phase (no AI outline): the capture\'s Core Idea seeds the diagnose Symptom; Reproduction/Root cause/Red herrings/Fix/Sweep/Acceptance criteria are fill-in skeletons — Root cause prompts the level check (if you fix exactly this, can the same class of failure still happen?), Red herrings holds the tempting-but-wrong fixes you ruled out, Sweep is the sibling-sweep receipt, Acceptance criteria asks for a check that FAILS when the fix is reverted. Prompted, never enforced: a trivial bug may leave them empty. The diagnose is standalone (no parent) and carries `severity:` (error|warning|info; default warning) which ranks it on the Resolution surface + on-deck. Bidirectional linkage: diagnose.promoted_from ⇔ capture.promoted_to (first-promotion) + capture.informs_diagnose (idempotent append). Transactional commit with rollback. Use this instead of heyspex_promote_capture when the capture is a bug to fix, not research to aggregate.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        capture_id: {
+          type: 'string',
+          description: 'The HS-CAP-* id of the bug-report capture to promote into a diagnose.',
+        },
+        severity: {
+          type: 'string',
+          enum: ['error', 'warning', 'info'],
+          description: 'Bug severity (default warning). error = P0/blocker, warning = normal, info = minor.',
+        },
+        name: {
+          type: 'string',
+          description: 'Optional diagnose name (used for title + slug). Defaults to the capture name.',
+        },
+      },
+      required: ['capture_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_promote_research_to_diagnose',
+    description:
+      'Promote a research investigation (HS-RES-*) that surfaced a bug into a new first-class diagnose spec (HS-DIAG-*, specs/diagnoses/) — the research-side sibling of heyspex_promote_capture_to_diagnose ([[HS-MSHY-TASK-research-diagnose-link-send-bugs-to-the]]). Reuses the existing diagnose machinery — no new infrastructure. Single-phase (no AI outline): the research\'s `## Executive Summary` (falling back to its `name:`) seeds the diagnose Symptom; Reproduction/Root cause/Red herrings/Fix/Sweep/Acceptance criteria are fill-in skeletons — Root cause prompts the level check (if you fix exactly this, can the same class of failure still happen?), Red herrings holds the tempting-but-wrong fixes you ruled out, Sweep is the sibling-sweep receipt, Acceptance criteria asks for a check that FAILS when the fix is reverted. Prompted, never enforced: a trivial bug may leave them empty. The diagnose is standalone (no parent) and carries `severity:` (error|warning|info; default warning). Bidirectional linkage: research.produces_diagnose ⇔ diagnose.derived_from (mirrors research.spawned_epics ⇔ epic.derived_from). Duplicate promotion of the SAME (research_id, diagnose name) pair is rejected with DIAGNOSE_ALREADY_PROMOTED (idempotent no-op, no new file) — a research doc is evergreen and may still spawn a genuinely different diagnose under a different name later. Transactional commit with rollback.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        research_id: {
+          type: 'string',
+          description: 'The HS-RES-* id of the research investigation to promote into a diagnose.',
+        },
+        severity: {
+          type: 'string',
+          enum: ['error', 'warning', 'info'],
+          description: 'Bug severity (default warning). error = P0/blocker, warning = normal, info = minor.',
+        },
+        name: {
+          type: 'string',
+          description: 'Optional diagnose name (used for title + slug + the duplicate-promotion key). Defaults to the research name.',
+        },
+      },
+      required: ['research_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_split_research',
+    description:
+      'Split a research doc (HS-RES-*) into N (≥2) child research docs — each targeting exactly one milestone — before promotion ([[HS-TASK-GTH9]] of [[HS-EPIC-M2J3]]). The original stays as an audit archive carrying `split_into:` linkage; each child carries `split_from:` linkage plus a caller-provided body_slice and a subset of the original\'s sources_captures. Capture files\' `informs_research:` arrays update bidirectionally per [[HS-TASK-YJX6]]. Research is evergreen ([[research-is-evergreen]]): the archive stays `status: open` and re-split is guarded by the presence of `split_into:` (RESEARCH_ALREADY_SPLIT). Children land as `status: open` — milestone binding happens later via /hs-promote-research (split is content partitioning, not promotion). Each returned child also carries `research_still_stub` / `unresolved_placeholder_count` — set when its body_slice still has unresolved `_TBD — fill in this section._` outline placeholders (e.g. splitting a promote-capture outline stub before running /hs-res); a top-level `next_step` names the /hs-res follow-up when any child is still a stub, since `heyspex_promote_research` will otherwise refuse that child with `RESEARCH_STILL_STUB` ([[HS-DSFO-49G3-DIAG-promote-capture-s-success-response]]). Children inherit the ORIGINAL research\'s family key unconditionally ([[family-id-is-inherited-capture-research]], owner ruling 2026-07-12) — every child AND the archived original may now legally share one family key (the V3 shared-surname model, [[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]: `id:` keys onto the per-file file key, not the family, so there is no collision to fall back from). All writes commit transactionally; any failure rolls back. Caller prepares body_slices — AI auto_partition is intentionally out of scope in v1.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        research_id: {
+          type: 'string',
+          description: 'Id or basename of the research to split (must be in vault and not already split — no `split_into:`). Accepts the frontmatter `id:`, the full file basename, a [[wikilink]], or a legacy HS-RES-* id.',
+        },
+        splits: {
+          type: 'array',
+          minItems: 2,
+          description:
+            'Array of ≥2 split entries. Each entry produces one child research doc.',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Human-readable child title (becomes name + slug).' },
+              target_milestone: {
+                type: 'string',
+                description:
+                  'HS-MIL-* id or basename of the target milestone, OR the literal string "NEW" to indicate a future milestone (recorded in the body callout; not allocated at split time).',
+              },
+              new_milestone_name: {
+                type: 'string',
+                description: 'Required when target_milestone === "NEW". Human-readable milestone title (recorded in body callout only).',
+              },
+              body_slice: {
+                type: 'string',
+                description: 'Markdown content for this child\'s body. Caller-prepared (no auto-partition in v1).',
+              },
+              sources_captures: {
+                type: 'array',
+                items: { type: 'string' },
+                description:
+                  'Subset of the original research\'s sources_captures (HS-CAP-* ids or basenames). May be empty. May overlap across children (Capture → Research is M:N per [[HS-TASK-YJX6]]).',
+              },
+            },
+            required: ['name', 'target_milestone', 'body_slice', 'sources_captures'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['research_id', 'splits'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_design_list_patterns',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'List design system patterns from spex-console/public/design-system/. Returns compact summaries (name, title, layer, tags, summary) — call heyspex_design_get_pattern for the full registry-item.json. Filters: tag (case-insensitive hsTag), layer (primitive|semantic|component|pattern), query (substring against name/title/description).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tag: { type: 'string', description: 'Filter to patterns whose hsTags contains this tag (case-insensitive)' },
+        layer: {
+          type: 'string',
+          enum: ['primitive', 'semantic', 'component', 'pattern'],
+          description: 'Filter by hsLayer classification',
+        },
+        query: { type: 'string', description: 'Substring match against name/title/description (case-insensitive)' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_design_get_pattern',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Fetch one full registry-item.json from spex-console/public/design-system/r/<name>.json (the shadcn-compatible payload with HeySpex extensions). Prefer this over grepping spex-console/DESIGN.md for a single pattern.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Pattern slug (e.g. "on-deck-callout-sky")' },
+        includeCode: {
+          type: 'boolean',
+          default: true,
+          description: 'Include hsCodePreview HTML snippet (default true). Set false to slim the response.',
+        },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_design_get_token',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Look up a CSS variable (e.g. "--accent-green") across registry items plus tokens.dtcg.json. Returns dark + light values, the DTCG token kind, the token group path, and the patterns that reference the variable.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        var: {
+          type: 'string',
+          description: 'CSS variable name (with or without leading "--", e.g. "--accent-green" or "accent-green")',
+        },
+      },
+      required: ['var'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_design_get_doc',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Fetch the spex-console/DESIGN.md prose excerpt for a pattern anchor. Anchors are leading-line markers of the form **`pattern-name`** — the excerpt runs from the anchor line through the next heading or anchor.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Pattern slug to look up (matches the registry item designDocAnchor field)' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_design_propose_pattern',
+    description:
+      'File a new design pattern as a draft proposal at specs/design-proposals/<name>.json. Mirrors registry-item.json shape with hsStatus: "proposed" + provenance fields (hsProposedAt, hsProposedBy). Humans review and promote into spex-console/public/design-system/r/. Folder is exempt from manifest registration.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Kebab-case slug for the new pattern (e.g. "agent-handoff-callout"). Must be unique against shipped registry items.',
+        },
+        title: { type: 'string', description: 'Short human title for the pattern.' },
+        description: {
+          type: 'string',
+          description: 'One-paragraph description (purpose, anatomy, when to use).',
+        },
+        hsLayer: {
+          type: 'string',
+          enum: ['primitive', 'semantic', 'component', 'pattern'],
+          description: 'Layer classification.',
+        },
+        hsTags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tags (e.g. ["callout", "agent", "on-deck"]).',
+        },
+        hsDecisionRefs: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Wikilink basenames pointing to memory decisions that govern the pattern.',
+        },
+        cssVars: {
+          type: 'object',
+          description: 'Optional dark + light CSS variable blocks. Shape: { dark: { "--name": "#hex", ... }, light: { ... } }',
+        },
+        hsCodePreview: { type: 'string', description: 'Optional standalone HTML snippet preview.' },
+        designDocAnchor: { type: 'string', description: 'DESIGN.md anchor slug (default = name).' },
+        proposed_by: {
+          type: 'string',
+          description: 'Display name of the agent/human filing the proposal.',
+        },
+      },
+      required: ['name', 'title', 'description', 'hsLayer'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_list_procedures',
+    budget: listBudget('procedures'),
+    description:
+      'List HeySpex procedures from specs/protocols/.catalog.json. Returns compact summaries (name, id, title, tags, triggers, summary, path) — call heyspex_get_procedure for the full markdown body. Filters: tag (case-insensitive), trigger (intent like "file_milestone", "destructive_action"), query (substring against name/title/summary).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tag: {
+          type: 'string',
+          description: 'Filter to procedures whose tags includes this value (case-insensitive)',
+        },
+        trigger: {
+          type: 'string',
+          description:
+            'Filter to procedures that declare this trigger (e.g. "file_milestone", "destructive_action", "memory_creation", "close_session")',
+        },
+        query: {
+          type: 'string',
+          description: 'Substring match against name/title/summary (case-insensitive)',
+        },
+        limit: {
+          type: 'number',
+          default: 10,
+          description: 'Page size (default: 10, max: 50). The response is ONE page under `procedures` plus `next_cursor`, fitted to an 8 KB byte budget — never the whole catalog, never a total count ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]]).',
+        },
+        after: {
+          type: 'string',
+          description: 'Opaque cursor: the `next_cursor` value of the prior page. Omit for page 1. A page whose `next_cursor` is null was the last one.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_get_procedure',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Fetch one HeySpex procedure: catalog metadata plus the full markdown body from specs/protocols/<name>.md. Prefer this over Read-ing the protocol file directly when you only need one procedure.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Procedure slug — the filename of the protocol minus the .md extension (e.g. "spec-hierarchy", "destructive-action-checklist")',
+        },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_file_spec',
+    // Trimmed 2026-09-09 ([[HS-EZIX-NYPR-TASK-measure-default-tool-schema-bytes-per]]
+    // AC2 — one of the two largest default-visible tool descriptions). Meaning
+    // preserved (every enum value, error code, and required-field rule below
+    // survives); cut was rationale/backstory prose (why the rule exists) and
+    // spec-id citations that don't change how an agent calls the tool.
+    description:
+      'File a NEW spec of any non-capture kind in one call (POSTs /api/specs) — the deterministic path instead of hand-authoring frontmatter: the server allocates the id, generates frontmatter, links the parent, and validates. type ∈ { milestone, epic, task, diagnose, research, memory-lesson, memory-decision, memory-reference, memory-ui-pattern, review, pillar, adr }; captures are NOT supported here (use heyspex_active_capture — a type:capture call returns 400). ADR is always filed status:proposed; a non-proposed status at filing is refused (400 adr_status_forced) — the owner\'s later status flip is the recorded decision. Milestone/epic MUST pass `summary` at planning time (plan ingest / breakdown, never with tasks); task MUST pass `summary` only from the `/hs-next` breakdown. Missing summary → summary_required. Epics ALSO REQUIRE frontmatter.pillar (an existing HS-PILR theme); missing/unknown → 400 pillar_required (call again with type:"pillar" to create one). diagnose files a standalone HS-DIAG (specs/diagnoses/), optional epic/milestone parent, severity defaults to "warning". Returns { spec_id, path, landed } — landed is measured after the write (which console, the absolute path, whether it\'s really on disk, the active dev-mode). A cloud landing while this session has a local clone returns isError WRITE_LANDED_OFF_DISK with the real spec id (do not re-file); declare expect_tier: "disk"|"cloud" to enforce which. POST errors (invalid parent, missing pillar, capture rejection) surface verbatim.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          description:
+            'Entity kind: milestone | epic | task | diagnose | research | memory-lesson | memory-decision | memory-reference | memory-ui-pattern | review | pillar | adr. NOT capture (use heyspex_active_capture). diagnose = a quality note / bug that surfaces on the Resolution center (standalone by default; severity defaults to "warning"). adr = files proposed, always; the owner\'s later status flip to accepted is the recorded decision.',
+        },
+        name: {
+          type: 'string',
+          description: 'Human-readable title. The slug is derived from it server-side.',
+        },
+        summary: {
+          type: 'string',
+          description:
+            'Required plain-language summary at filing time. Milestone/epic: planning phase only (plan ingest / breakdown — never with tasks). Task: What\'s Next Launch `/hs-next` breakdown only. Alias: frontmatter.summary.',
+        },
+        frontmatter: {
+          type: 'object',
+          description:
+            'Optional frontmatter overrides/extras. Set the parent linkage here: task → parent: "[[HS-EPIC-…]]" (or a parent task), epic → milestone: "[[HS-MIL-…]]", review → parent: "[[<spec under review>]]" (required for review). Epics ALSO REQUIRE pillar: "[[HS-PILR-…]]" (the perpetual theme; filing fails 400 pillar_required without a resolvable one). Do NOT set id — it is auto-assigned.',
+          additionalProperties: true,
+        },
+        body: {
+          type: 'string',
+          description:
+            'Optional markdown body. When omitted, the server injects the canonical body skeleton for the kind.',
+        },
+        recipe_context: {
+          type: 'object',
+          description:
+            'Optional workflow-recipe start context (the object heyspex_start_recipe returns — buildRecipeStartContext output) to stamp recipe provenance on the filed spec. Forwarded verbatim to POST /api/specs, where the server reads recipe_id + tool_scope and stamps them into frontmatter ([[HS-98G6-TASK]] / [[HS-5G0P-EPIC]] AC5). Omit for non-recipe filings — the server no-ops when absent.',
+          additionalProperties: true,
+        },
+        checks: {
+          type: 'array',
+          description:
+            'OPTIONAL — the FROZEN checks manifest ([[checks-manifest-authoring]]), authored at breakdown BEFORE any builder sees the brief. Optional means optional: omitting it FILES THE TASK ANYWAY with a `no_checks_manifest` warning, and that task then reaches build-complete on the agent\'s own unverified self-report, because the verification gate in apply-status-transition.ts only bites where a manifest exists. So authoring one is how a task becomes verifiable — it is not enforced, and nothing downstream will notice you skipped it. One row per acceptance criterion, same order. The server writes specs/checks/<new-id>.checks.json and `hs check run <id>` is the per-criterion verdict. Row: { ac: <1-based position>, text: "<the criterion, verbatim>", method: "machine" | "property" | "human", checks: [ { kind: "test"|"lint"|"types"|"command"|"guard", run: "<command>", expect: "exit-0", cwd?: "<dir>" } ] }. A method:"human" row may carry no runnable check; machine/property rows must carry at least one. Two rules DO reject a manifest at filing: (1) commands run from the REPO ROOT (a cwd-less check is retried against spex-console/ as a fallback), so a command that resolves config from its working directory MUST name that directory — npx/pnpm/yarn/bun runners, `npm run <script>` and `npm test`, node_modules/.bin binaries, and bare tsc/vitest/jest/eslint/prettier/tsx/vite/next off PATH, e.g. { kind: "types", run: "npx tsc --noEmit", cwd: "spex-console" } ([[HS-IRCO-D0ME-DIAG-checks-manifests-silently-false-green]]: ~50 frozen manifests were permanently red for a reason unrelated to the code); (2) a machine/property criterion whose check cannot fail (`echo ok`, `true`, `:`, `exit 0`) is refused — a green light wired to nothing is worse than no manifest. A filtered test command (--filter/--testNamePattern/--grep/-k) asserting only exit-0 is accepted with a warning, since it exits 0 when the filter matches nothing.',
+          items: { type: 'object', additionalProperties: true },
+        },
+        expect_tier: {
+          type: 'string',
+          enum: ['disk', 'cloud'],
+          description:
+            'OPTIONAL — declare WHERE you expect the write to land, and the call fails instead of quietly landing elsewhere ([[HS-IOJW-5YDH-DIAG]]). "disk" = a file in this clone; "cloud" = the Neon index only. Omit it and the default expectation applies: any clone-less cloud landing returns WRITE_LANDED_OFF_DISK rather than plain success, because that is the shape that silently lost work on 2026-08-21. Pass "cloud" when you are deliberately working against app.heyspex.com. Every response, error or not, carries a measured `landed` block naming the console, the path, and whether the file is actually there.',
+        },
+      },
+      required: ['type', 'name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_import_agent',
+    description:
+      'Import a community agent role into a type:agent vault spec (POSTs /api/agents/import). Parity with `hs agent import` — resolves a vendored collection role, normalizes via the shared import-normalizer core, files with server-allocated id, and records source_attribution. Returns { spec_id, path, warnings }. Requires a reachable console.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        collection: {
+          type: 'string',
+          description: 'Vendored collection alias (e.g. "voltagent")',
+        },
+        role: {
+          type: 'string',
+          description: 'Role identifier within the collection (e.g. "deployment-engineer")',
+        },
+        dry_run: {
+          type: 'boolean',
+          default: false,
+          description: 'Normalize only — do not write a spec',
+        },
+      },
+      required: ['collection', 'role'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_preflight',
+    description:
+      'Pre-flight checklist for a named agent intent. Returns the procedures the agent should consult before acting, each annotated with `severity` ("required", "recommended", or "advisory" — a procedure this vault does not have is demoted to advisory with `demoted_from` and `reason`) and a short `why`. Call before high-stakes actions (filing a milestone/epic/task, destructive operations, protocol edits, memory creation, session close, spec claim) — then fetch the procedure body via heyspex_get_procedure. THIS CALL IS NOW CHECKED: a successful preflight records proof-of-use for that intent for the rest of the session, and the tools it governs read it. `heyspex_claim_spec` REFUSES with `PREFLIGHT_NOT_RUN` without a matching `claim_spec`/`execute_spec` preflight, and `heyspex_submit_for_review` refuses without `close_session`. `heyspex_file_spec` currently WARNS (attaches `preflight_warning`) when the matching `file_*` intent was not run — raise it to a refusal with HEYSPEX_PREFLIGHT_GATE_FILE_SPEC=refuse. Break-glass for the whole gate: HEYSPEX_PREFLIGHT_GATE_OFF=1.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        intent: {
+          type: 'string',
+          enum: PREFLIGHT_INTENTS,
+          description: `Agent intent to look up. One of: ${PREFLIGHT_INTENTS.join(', ')}.`,
+        },
+        thread_type: {
+          type: 'string',
+          enum: CLOSE_SESSION_THREAD_TYPES,
+          description:
+            'ONLY for intent "close_session": declare what kind of session this was, and the response returns that thread type\'s CONDITIONAL close-out steps instead of the full static checklist. Thread-type is declared (not inferred) — some signals are not session-scoped. Omit it to get the full checklist plus the list of thread types to choose from. For a mixed session, request each applicable type and run the UNION of their steps. One of: capture_only | research_only | plan_ingest_only | one_task | multi_task_epic | resolve_diagnose | mid_rollover.',
+        },
+      },
+      required: ['intent'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_list_recipes',
+    budget: listBudget('recipes'),
+    description:
+      'List HeySpex workflow-recipes from specs/recipes/ — ready-made templates that structure the START of a multi-step assisted session (Bug fix, Feature, Investigation, Refactor). With no args, returns every recipe. With intent, returns only recipes whose intent_signatures (or name/description) match, each annotated with match_strength ("high" for a signature-exact hit, "medium" for a substring/name hit). Start one with heyspex_start_recipe. Matching is case- and separator-insensitive ("fix bug" == "bug_fix").',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        intent: {
+          type: 'string',
+          description:
+            'Optional plain intent to match against recipe intent_signatures (e.g. "bug_fix", "fix bug", "refactor", "new feature"). Omit to list all recipes.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_start_recipe',
+    description:
+      'Start a HeySpex workflow-recipe: creates and pins a capture session (when the console is reachable) and returns the recipe start context — the capture_sequence to walk, the spec_template to pre-fill the resulting spec, and the recipe_id + tool_scope to stamp for provenance. Recipes structure the start of work; execution still happens in your coding agent. Pass recipe_id as the authored id ("HS-RECIPE-bug-fix") or the bare slug ("bug-fix"). If the console is unreachable the context is still returned so the flow can be walked later (status: deferred).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        recipe_id: {
+          type: 'string',
+          description: 'Recipe to start — authored id ("HS-RECIPE-bug-fix") or slug ("bug-fix").',
+        },
+        capture_text: {
+          type: 'string',
+          description: "Optional seed text for the capture (the user's initial words / the thing being worked on).",
+        },
+      },
+      required: ['recipe_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_canvas_inbox',
+    description:
+      'Pull any pending HeySpex canvas write-back messages for THIS Claude Code session ([[HS-1ROV-EPIC]] stage 5c). When a user types a reply into the session-mirror canvas in the console, it queues in the companion daemon; call this to claim those messages and act on them. Claiming marks them delivered so the Stop-hook drain does NOT re-deliver them (exactly-once across both channels — the daemon outbox is the single source of truth). Session id: pass session_id explicitly, or omit to use CLAUDE_CODE_SESSION_ID. Companion not running is a normal, non-error result: { ok:true, messages:[], note }. Returns { ok, sessionId, delivered, messages[] }.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description:
+            'The Claude Code session id to claim canvas messages for. Omit to use CLAUDE_CODE_SESSION_ID from the environment.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_dev_server_status',
+    // Trimmed 2026-09-09 ([[HS-EZIX-NYPR-TASK-measure-default-tool-schema-bytes-per]]
+    // AC2 — the other of the two largest default-visible tool descriptions).
+    // Meaning preserved (both probes, both fields, the discrepancy enum, the
+    // call-before-server-impact rule); cut was the worked example illustrating
+    // why `uiHealthy` exists.
+    description:
+      'Ground-truth status of the spex-console dev server: running, and on which port(s)? Derived from a live HTTP probe (`/api/version`) plus an OS listener scan — NOT from .heyspex/dev-server.lock.json, which can be stale, miss an untracked bare `next dev`, or disagree on port; the lockfile is read only as a hint, any disagreement surfaces as a discrepancy (stale_lock | untracked_server | multiple_servers | port_mismatch | page_probe_failed). `running` is API-probe-only — a green API does NOT prove the UI renders. Check `uiHealthy` (a second probe against a real page route; null = no console identified, true/false = checked) before trusting `running` alone as "the console is usable". CALL THIS before any server-impacting action — a migration, Neon branch reset, dependency install, deleting .next, or a second dev server — and stop a live server first. Returns { running, uiHealthy, servers[] (each with a `pageProbe` when identified as console), lockfile, discrepancies, candidatePorts, checkedAt }. Takes no arguments.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_dev_mode',
+    description:
+      'Get or set the HeySpex dev/prod mode + local/cloud reliance (epic HS-Q6M2, /hs-dev). Model: mode prod|dev; when dev, reliance local|cloud. prod and dev+cloud => cloud console (app.heyspex.com), Neon reads, cloud writes; dev+local => localhost:3000 console, disk reads, local writes. action:"get" returns the fully resolved state with the SOURCE of every value (env override → ~/.heyspex/dev-mode.json machine-local override → cloud admin setting → default prod) — a stale local override is flagged, never silent. action:"set" applies the switch: writes ~/.heyspex/dev-mode.json (the cross-component contract file the Companion also reads), updates console_url in ~/.heyspex/credentials.yaml (rung 2 of the shared console-url resolver — MCP/hooks/dev-factory repoint automatically), and best-effort updates the cloud account_settings row. Never edits repo-tracked files. mode local|cloud imply dev with that reliance. CLI face: `hs dev [mode:local|mode:cloud|mode:prod]`; console face: Settings → ADMIN → Dev Tools.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['get', 'set'],
+          description: '"get" = resolved state + sources; "set" = apply a mode change.',
+        },
+        mode: {
+          type: 'string',
+          enum: ['prod', 'dev', 'local', 'cloud'],
+          description: 'For set: target mode. local/cloud imply dev with that reliance.',
+        },
+        reliance: {
+          type: 'string',
+          enum: ['local', 'cloud'],
+          description: 'For set with mode:"dev": which reliance (default local).',
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_settings_list',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'List HeySpex workflow settings — every scalar key in .heyspex/config.yaml as dotted keys with parsed values (e.g. agent_behaviors.capture_on_idea.enabled). Read-only. Optional prefix narrows to one block (e.g. "agent_behaviors" or "agent_behaviors.intent_classifier"). Part of the settings capability (core: vendor/heyspex-mcp/config-settings.mjs; CLI face: `hs settings list`; console face: Settings → Agent Behaviors).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prefix: {
+          type: 'string',
+          description: 'Optional dotted-key prefix filter (e.g. "agent_behaviors").',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_settings_get',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'Read one HeySpex workflow setting from .heyspex/config.yaml by dotted key (e.g. "agent_behaviors.intent_classifier.min_confidence"). Read-only. Returns { key, found, value }; found:false means the key is absent and the consumer falls back to its documented default.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        key: {
+          type: 'string',
+          description: 'Dotted settings key, e.g. "agent_behaviors.capture_on_idea.ask_first".',
+        },
+      },
+      required: ['key'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_settings_set',
+    description:
+      'Change one HeySpex workflow setting in .heyspex/config.yaml — PERMISSION-GATED two-step flow (agent-settings-protocol). Settings writes always require EXPLICIT user approval, regardless of the ask_forgiveness_not_permission switch. Call 1 (key + value, NO confirm_token): nothing is written; returns status "confirmation_required" with the current value and a confirm_token. You MUST show the user the exact change and get their explicit approval. Call 2 (confirm_token only): applies the reviewed change and audits it to .heyspex/settings-history.jsonl. Tokens expire after 10 minutes. NEVER edit .heyspex/config.yaml directly — a PreToolUse gate blocks that route.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        key: {
+          type: 'string',
+          description: 'Dotted settings key to change (call 1). Ignored when confirm_token is given.',
+        },
+        value: {
+          description: 'New scalar value (string, number, boolean, or null) — call 1. Ignored when confirm_token is given.',
+          type: ['string', 'number', 'boolean', 'null'],
+        },
+        confirm_token: {
+          type: 'string',
+          description: 'The token from a prior confirmation_required response — call 2, ONLY after the user explicitly approved the exact change.',
+        },
+        actor: {
+          type: 'string',
+          description: 'Optional audit actor label (defaults to "agent (MCP)").',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_resolve_research_plan',
+    description:
+      'Resolve the CONFIGURED research plan from .heyspex/config.yaml agent_behaviors.research — the authoritative, live-read source of truth for "which research method/backend applies right now" ([[HS-LFUH-DIAG-W1YE]]). Call this before/at research time (especially before RUNG 0 `sequential` search/scrape) rather than trusting only the research-trigger hook injection, which is a best-effort snapshot taken at prompt-submit time and can go stale mid-session (a Firecrawl lease can be granted or refused, a box can go up or down). Returns { method, default_agent, default_source, resource: {source, endpoint}, note }. Read-only, no side effects. Scope note: this reads the CONFIGURED plan only — it does NOT resolve resource profiles, primary/fallback chains, or capability gating (that generalized feature is a separate, not-yet-built system: [[HS-X5GJ-RES-EU6J]]).',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_firecrawl_research',
+    description:
+      'Run ONE Firecrawl search or scrape for THIS interactive turn (RUNG 0 `sequential` — "the main agent runs the searches itself") — makes the Firecrawl backend actually REACHABLE from an interactive agent, which previously had no way to honor a configured `agent_behaviors.research.default_source: firecrawl-self-hosted/firecrawl-hosted` ([[HS-LFUH-DIAG-W1YE]] root-cause part 2). Wraps the EXISTING, self-tested dev-factory/spexcrawl/default-backends.mjs + firecrawl-adapter.mjs implementation unchanged — no search/scrape logic is reimplemented here. Respects the existing availability gates as-is, never bypasses them: the Ollama-XOR-Firecrawl mode lease (self-hosted — Night Action) or the fail-closed attended-daytime credit gate (hosted api.firecrawl.dev; this tool NEVER sets RESEARCH_ATTENDED itself, that env var is owner-only). mode:"search" needs `query`; mode:"scrape" needs `url`. ALWAYS returns ok:true with an explicit envelope — on success `{used_source:"firecrawl-self-hosted", downgraded:false, results|text}`; when the configured backend is unavailable `{used_source:"web-native", requested_source, downgraded:true, reason}` — on downgraded:true, YOU must fall back to your own native WebSearch/WebFetch and tell the user plainly that the configured backend was unavailable; never substitute silently. Only ok:false is a caller error (missing query/url).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mode: {
+          type: 'string',
+          enum: ['search', 'scrape'],
+          description: 'Which Firecrawl operation to run. Default "search".',
+        },
+        query: {
+          type: 'string',
+          description: 'Search query — required when mode is "search".',
+        },
+        url: {
+          type: 'string',
+          description: 'URL to scrape — required when mode is "scrape".',
+        },
+        spec_id: {
+          type: 'string',
+          description: 'Optional spec id for cost-ledger attribution of the call.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_plan_review',
+    description:
+      'Plan-mode quality + canonical check ([[HS-EPIC-PLRV]]). Runs overlap grep, code audit, canonical detection, vocabulary reconciliation, and Axis-B drift over a draft plan OR a proposed epic→task breakdown (scope: "breakdown"). Writes .heyspex/plan-reviews/<sha256>.json. Pass plan_path/plan_content for plan mode, OR scope breakdown + epic_id + proposed_tasks for /hs-next decomposition review (advisory v1). Optional quality_pass on breakdown runs Pass 7 (MECE/sizing/ordering); pass quality_findings from the session agent after LLM judgment — HeySpex never calls an in-app model.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        plan_path: {
+          type: 'string',
+          description: 'Path to the plan markdown file (absolute, or relative to the vault root). Preferred over plan_content.',
+        },
+        plan_content: {
+          type: 'string',
+          description: 'Inline plan markdown. Use when the plan is not yet on disk (Cursor / inline fallback). Ignored if plan_path is given.',
+        },
+        scope: {
+          type: 'string',
+          enum: ['plan', 'breakdown'],
+          description: 'Review target: "plan" (default, ExitPlanMode) or "breakdown" (/hs-next task-set review).',
+        },
+        epic_id: {
+          type: 'string',
+          description: 'When scope is "breakdown": parent epic id (e.g. HS-EPIC-XXXX). Required with proposed_tasks unless plan_content/plan_path is given.',
+        },
+        epic_name: {
+          type: 'string',
+          description: 'Optional epic title for breakdown scope serialization.',
+        },
+        proposed_tasks: {
+          type: 'array',
+          description: 'When scope is "breakdown": draft tasks as { title, scope?, files?, symbols?, depends_on? }[].',
+          items: {
+            type: 'object',
+            properties: {
+              title: { type: 'string' },
+              name: { type: 'string' },
+              scope: { type: 'string' },
+              files: { type: 'array', items: { type: 'string' } },
+              symbols: { type: 'array', items: { type: 'string' } },
+              depends_on: { type: 'array', items: { type: 'string' } },
+            },
+          },
+        },
+        quality_pass: {
+          type: 'boolean',
+          description:
+            'Breakdown only: run Pass 7 quality checks (MECE, sizing, ordering). Default false — no latency when omitted.',
+        },
+        quality_findings: {
+          type: 'array',
+          description:
+            'Breakdown + quality_pass: agent-as-judge findings from the session LLM ({ kind, title, note }). HeySpex validates and merges with heuristic checks; it never calls an in-app model.',
+          items: {
+            type: 'object',
+            properties: {
+              kind: { type: 'string', enum: ['mece_gap', 'oversize', 'missing_depends_on'] },
+              title: { type: 'string' },
+              note: { type: 'string' },
+            },
+            required: ['kind', 'title', 'note'],
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_plan_qc',
+    description:
+      'Plan-mode QC gut-check Proof-of-Use record ([[HS-EPIC-PLRV]] / [[plan-quality-canonical-check]]). After running the `/hs-qc` gut-check over a drafted plan and folding the findings in, call this to record that the gut-check happened, with an auditable findings_summary. Writes a marker file .heyspex/plan-qc/<sha256-of-plan-content>.json. The ExitPlanMode gate requires BOTH this QC marker AND the heyspex_plan_review marker for the current plan before it allows the exit. A call without a substantive findings_summary is refused (Proof-of-Use — required tool calls are otherwise gameable, [[HS-RES-2QX6]] F13). When axis_b_drift conflicts exist, the agent MUST present them to the user first — default is re-scope; pass axis_b_user_confirmed: true + axis_b_confirmation_note only after explicit user confirmation to proceed anyway. Pass plan_path (preferred) OR plan_content, plus findings_summary.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        plan_path: {
+          type: 'string',
+          description: 'Path to the plan markdown file (absolute, or relative to the vault root). Preferred over plan_content.',
+        },
+        plan_content: {
+          type: 'string',
+          description: 'Inline plan markdown. Use when the plan is not yet on disk. Ignored if plan_path is given.',
+        },
+        findings_summary: {
+          type: 'string',
+          description: 'Auditable summary of what the QC gut-check actually found — must include an "Axis B:" line. Where the plan could be wrong, risks, breakages, JTBD. If user confirmed an Axis B override, note "user confirmed override" here.',
+        },
+        axis_b_user_confirmed: {
+          type: 'boolean',
+          description: 'Set true ONLY after the user explicitly confirms they want to proceed despite axis_b_drift conflicts (not the default). Requires axis_b_confirmation_note.',
+        },
+        axis_b_confirmation_note: {
+          type: 'string',
+          description: 'Audit trail when axis_b_user_confirmed is true: which decision was overridden and what the user confirmed (>= 40 chars).',
+        },
+      },
+      required: ['findings_summary'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_regen_task',
+    description:
+      'Re-derive a single task body from its parent epic + linked plans ([[HS-EPIC-HSN1]] / [[HS-TASK-0CKW]]). Brief mode (no commit) returns the context the agent needs to author a new body. Commit mode (`commit: true` + `new_body`) soft-deletes the old body to `.trash/<epic-slug>/` and writes the new one. Reversible via .trash/.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'string',
+          description: 'Task spec id to regenerate (e.g. "HS-TASK-XXXX").',
+        },
+        commit: {
+          type: 'boolean',
+          description: 'When true, soft-delete the existing body and write `new_body`. When false (default), return the context brief only.',
+          default: false,
+        },
+        new_body: {
+          type: 'string',
+          description: 'Replacement task body (markdown including frontmatter). Required in commit mode.',
+        },
+        retire_reason: {
+          type: 'string',
+          description: 'One-line reason recorded with the retired body (optional but recommended).',
+        },
+      },
+      required: ['task_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_regen_tasks_for_epic',
+    description:
+      'Run the Stage 1-2-3 regen pipeline (generate fresh from acceptance criteria → reconcile pre-existing tasks → retire superseded ones to .trash/) for every task under an Epic ([[HS-EPIC-HSN1]] / [[HS-TASK-0CKW]]). Brief mode returns the context the agent needs to compose the fresh task set. Commit mode (`commit: true` + `task_specs[]`) atomically retires superseded tasks and writes the new bodies. All retirements land in `.trash/<epic-slug>/` and are reversible.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epic_id: {
+          type: 'string',
+          description: 'Epic spec id whose tasks should be regenerated (e.g. "HS-EPIC-XXXX").',
+        },
+        commit: {
+          type: 'boolean',
+          description: 'When true, perform Stage-3 retire + write. When false (default), return the Stage-1-2-3 brief only.',
+          default: false,
+        },
+        task_specs: {
+          type: 'array',
+          description:
+            'In commit mode, the new task set. Each entry is either { id, new_body, retire_reason } to replace an existing task, or { new_id, body, rel_path } to file a new one.',
+          items: { type: 'object' },
+        },
+      },
+      required: ['epic_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_session_end',
+    description:
+      'Signal session termination and fire SessionEnd hooks (release claim, cleanup, notify console). ' +
+      'Call this explicitly at session close — Command Code has no automatic Stop/SessionEnd hooks.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        reason: {
+          type: 'string',
+          description: 'Optional reason for session end (e.g. "completed", "handoff", "interrupted")',
+          default: 'completed',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_hooks_invoke',
+    description:
+      'Invoke HeySpex lifecycle hooks for harnesses without native hook support (Command Code). ' +
+      'Use event UserPromptSubmit with prompt on each user turn for intent detection; ' +
+      'call after plan-mode exit to get plan-ingest close guidance. ' +
+      'PreToolUse/PostToolUse replay for testing or skill-driven guardrails.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        event: {
+          type: 'string',
+          enum: ['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'SessionEnd'],
+          description: 'Hook lifecycle event to fire',
+        },
+        prompt: {
+          type: 'string',
+          description: 'User message (required for UserPromptSubmit)',
+        },
+        tool_name: {
+          type: 'string',
+          description: 'Tool name for PreToolUse/PostToolUse (default: *)',
+        },
+        tool_input: {
+          type: 'object',
+          description: 'Tool input payload for PreToolUse/PostToolUse',
+        },
+        tool_response: {
+          type: 'object',
+          description: 'Prior tool result for PostToolUse replay',
+        },
+        reason: {
+          type: 'string',
+          description: 'Session end reason when event is SessionEnd',
+        },
+      },
+      required: ['event'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_hooks_list',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'List all registered hooks from .commandcode/hooks.json. Returns the parsed config with resolved paths.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_load_tools',
+    description:
+      'Progressive tool disclosure ([[HS-MTSA-EPIC]] / [[HS-OO5K-RES]]): the default tools/list shows only the core daily-loop tools; the rest are DEFERRED — hidden, not deleted, and loadable here. Call with { list_deferred: true } to see every deferred tool (name + description) without loading. Call with { names: [...] } (or { all: true }) to make those tools visible for this session — the server emits notifications/tools/list_changed so the client refreshes. At the MCP wire level deferred tools still answer tools/call, but Claude Code only calls names present in its tools/list, so load a deferred tool here before calling it from a Claude Code session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        names: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Deferred tool names to load into the visible surface (e.g. ["heyspex_next_review"])',
+        },
+        all: {
+          type: 'boolean',
+          default: false,
+          description: 'Load every deferred tool',
+        },
+        list_deferred: {
+          type: 'boolean',
+          default: false,
+          description: 'List deferred (currently hidden) tools with descriptions, without loading them',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_fleet_queue_submit',
+    description:
+      'Submit work into the fleet-queue namespace (bearer-authed POST /api/fleet/queue) — [[HS-60Z1-EPIC]]. CURRENTLY REFUSES (error NO_RUNNER, nothing written): the only executor, dev-factory/lib/fleet-queue-runner.mjs, still reads the legacy JSONL file queue, so work accepted here would be recorded and never run — [[HS-FS7X-6S8F-DIAG-fleet-queue-submit-writes-to-a-queue]]. The runner repoint is [[HS-XOCK-60Z1-EPIC-fleet-work-queue-in-heyspex]]; to run work now, enqueue against dev-factory/lib/fleet-queue.mjs. Once a runner drains Neon (HEYSPEX_FLEET_QUEUE_RUNNER_READY=1) this returns { id, position } and work that loses a race for a busy machine-gated resource waits in the lane until a machine claims it (heyspex_fleet_queue_claim) instead of failing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        lane: {
+          type: 'string',
+          description: 'Queue lane the task waits in (e.g. "build"). Required.',
+        },
+        kind: {
+          type: 'string',
+          description: 'Task kind for eligibility filtering (defaults to "task" when omitted).',
+        },
+        payload: {
+          type: 'object',
+          description: 'Arbitrary JSON payload for the task (maps to the dispatcher\'s `spec`).',
+        },
+        requested_by: {
+          type: 'string',
+          description: 'Display name/id of the requester (informational).',
+        },
+      },
+      required: ['lane'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_fleet_queue_claim',
+    description:
+      'Claim a specific fleet-queue task by id (bearer-authed POST /api/fleet/queue/:taskId/claim) — [[HS-60Z1-EPIC]]. A 404 (unknown id) or a 409 (already claimed / terminal state — another machine won the race) is a normal outcome, not a failure: this tool surfaces those as a clean { ok:false, reason } instead of throwing, so the caller can fall back to polling the queue or picking another task.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'string',
+          description: 'The queue task id to claim.',
+        },
+        machine_key: {
+          type: 'string',
+          description: 'The claiming machine\'s fleet machine key.',
+        },
+      },
+      required: ['task_id', 'machine_key'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_fleet_queue_complete',
+    description:
+      'Mark a claimed fleet-queue task done (bearer-authed POST /api/fleet/queue/:taskId/complete) — [[HS-60Z1-EPIC]]. Records a canonical result row; the machineKey must match the machine that holds the claim. Returns { accepted: true }.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'string',
+          description: 'The queue task id to complete.',
+        },
+        machine_key: {
+          type: 'string',
+          description: 'The claiming machine\'s fleet machine key.',
+        },
+        result: {
+          type: 'object',
+          description: 'Optional result payload to record with the completion.',
+        },
+      },
+      required: ['task_id', 'machine_key'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'heyspex_fleet_queue_list',
+    budget: READ_TOOL_BUDGET,
+    description:
+      'List fleet-queue tasks (bearer-authed GET /api/fleet/queue) — [[HS-60Z1-EPIC]]. The visibility read for the queue: queue depth, in-flight (claimed) items, and history, oldest-first. Filter by lane and/or status; limit caps the returned count.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        lane: {
+          type: 'string',
+          description: 'Filter to one lane.',
+        },
+        status: {
+          type: 'string',
+          description: 'Filter to one status (e.g. "pending", "claimed", "done", "failed").',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max number of items to return.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+export const DEFAULT_VISIBLE_TOOLS = new Set([
+  // the 15 keeps from [[HS-OO5K-RES]]
+  'heyspex_validate_linkage',
+  'heyspex_next_on_deck',
+  'heyspex_save_research',
+  'heyspex_recall_memories',
+  'heyspex_claim_spec',
+  'heyspex_release_spec',
+  'heyspex_report_progress',
+  'heyspex_submit_for_review',
+  'heyspex_record_wip',
+  'heyspex_defer_spec',
+  'heyspex_list_procedures',
+  'heyspex_get_procedure',
+  'heyspex_file_spec',
+  'heyspex_preflight',
+  'heyspex_dev_server_status',
+  // /hs-dev depends on this being directly callable (epic HS-Q6M2); still
+  // within the [[HS-MTSA-EPIC]] ≤20 default-surface budget.
+  'heyspex_dev_mode',
+  // the progressive-disclosure loader itself
+  'heyspex_load_tools',
+  // [[HS-1C4L-9VZV-DIAG-multi-agent-capture-focus-pin-collision]] AC3: keep
+  // heyspex_pin_capture directly discoverable — heyspex_active_capture's own
+  // description points agents to it as the pin escape hatch, and it must not
+  // be effectively invisible behind the progressive-disclosure loader.
+  'heyspex_pin_capture',
+  // Session hand-off pair: the SessionStart / PostCompact / PreCompact hooks in
+  // scripts/claude-hooks/wip-checkpoint.mjs instruct the agent to call these
+  // by name. Claude Code refuses tools/call for any name absent from its
+  // tools/list, so a deferred hand-off tool fails every session start with
+  // "No such tool available". Fills the last two slots of the 20-tool cap.
+  'heyspex_handoff_load',
+  'heyspex_handoff_record',
+]);
+
+/** Session-scoped set of deferred tools made visible via heyspex_load_tools. */
+export const loadedToolNames = new Set();
+
+export function toolSurfaceIsFull() {
+  return String(process.env.HEYSPEX_TOOL_SURFACE ?? '').toLowerCase() === 'full';
+}
+
+/** Filter a tools/list result to the default-visible ∪ session-loaded surface. */
+export function filterToolSurface(result) {
+  if (toolSurfaceIsFull()) return result;
+  if (!result || !Array.isArray(result.tools)) return result;
+  return {
+    ...result,
+    tools: result.tools.filter(
+      (t) => DEFAULT_VISIBLE_TOOLS.has(t.name) || loadedToolNames.has(t.name),
+    ),
+  };
+}
+
+/** Parent-side handler for heyspex_load_tools (must NOT run in a fresh subprocess —
+ *  the loaded-set mutation and list_changed notification belong to the long-lived
+ *  parent that owns the client connection). */
+export function handleLoadTools(args = {}) {
+  const deferred = TOOLS.filter(
+    (t) => !DEFAULT_VISIBLE_TOOLS.has(t.name) && !loadedToolNames.has(t.name),
+  );
+  const ALLOWED_LOAD_TOOLS_KEYS = new Set(['names', 'all', 'list_deferred']);
+  const unknownKeys = Object.keys(args).filter((k) => !ALLOWED_LOAD_TOOLS_KEYS.has(k));
+  if (unknownKeys.length > 0) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: `heyspex_load_tools: unrecognized argument(s) ${unknownKeys.join(', ')}. Valid keys: names (string[]), all (boolean), list_deferred (boolean).`,
+      }],
+    };
+  }
+  if (args.names !== undefined && !Array.isArray(args.names)) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: `heyspex_load_tools: "names" must be an array of tool name strings, got ${typeof args.names}.`,
+      }],
+    };
+  }
+  if (args.list_deferred) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          deferred_count: deferred.length,
+          deferred: deferred.map((t) => ({
+            name: t.name,
+            description: String(t.description ?? '').slice(0, 160),
+          })),
+        }),
+      }],
+    };
+  }
+  if (!args.all && !(Array.isArray(args.names) && args.names.length > 0)) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: 'heyspex_load_tools: called with neither { names: [...] } nor { all: true } — nothing to load. Use { list_deferred: true } to browse deferred tools first.',
+      }],
+    };
+  }
+  const known = new Set(TOOLS.map((t) => t.name));
+  const requested = args.all ? deferred.map((t) => t.name) : args.names;
+  const unknown = requested.filter((n) => !known.has(n));
+  const loaded = [];
+  for (const n of requested) {
+    if (!known.has(n) || DEFAULT_VISIBLE_TOOLS.has(n)) continue;
+    if (!loadedToolNames.has(n)) {
+      loadedToolNames.add(n);
+      loaded.push(n);
+    }
+  }
+  if (loaded.length > 0) {
+    try {
+      sendNotification('notifications/tools/list_changed', {});
+    } catch {
+      // stdout not writable (CLI mode) — visibility still applies to later tools/list
+    }
+  }
+  return {
+    isError: unknown.length > 0 && loaded.length === 0,
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        loaded,
+        already_visible: requested.filter((n) => DEFAULT_VISIBLE_TOOLS.has(n) || (loadedToolNames.has(n) && !loaded.includes(n))),
+        unknown,
+        visible_count: DEFAULT_VISIBLE_TOOLS.size + loadedToolNames.size,
+      }),
+    }],
+  };
+}