heyspex 0.1.0 → 0.2.1

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

@@ -0,0 +1,657 @@
+// JSON-RPC method handlers for initialize, tools/list, tools/call (the
+// dispatchHeySpexTool switch), session/end and hooks/*, plus the seat banner and
+// peer-presence injection applied to every tool result. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { executeHook, finalizeToolResultWithHooks, listHookConfig, loadHooksConfig, matchHooks, runHooks } from './hooks-engine.mjs';
+import { detectAgentIdentity, getConfig } from './mcp-config.mjs';
+import { setWriteOutboxRoot } from './write-outbox.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+import { evaluatePreflightGate } from './preflight-gate.mjs';
+import { evaluateObligationBackstop } from './obligation-backstop.mjs';
+import { TOOLS, handleLoadTools } from './tool-catalog.mjs';
+import { handleNextOnDeck, handleNextResolution, handleNextReview, handleResolvePrerequisite, handleSuggestPillar } from './on-deck-brief.mjs';
+import { handleFileSpec, handleGroundPlan, handlePlanQc, handlePlanReview, handlePushPlan, handleRegisterSpec, handleValidateLinkage, handleValidateUserSkills } from './filing-tools.mjs';
+import { handleActiveResearch, handleCompleteResearch, handlePromoteResearch, handlePromoteResearchToDiagnose, handleSaveResearch, handleSplitResearch } from './research-handlers.mjs';
+import { handleRecallMemoriesViaTier } from './memory-tools.mjs';
+import { handleCanvasInbox, handleEditFile, handleListKnownTags, handleProposeMetadata, handleRegenTask, handleRegenTasksForEpic, handleShipEpic } from './spec-edit-tools.mjs';
+import { handleAuthorSummary } from './summary-write-tools.mjs';
+import { handleActiveCapture, handlePinCapture, handlePromoteCapture, handlePromoteCaptureToDiagnose, handleUpdateCapture } from './capture-tools.mjs';
+import { handleClaimAcquire, handleClaimFile, handleClaimList, handleClaimRelease, handleClaimSpec, handleDeferSpec, handleRecordAlignmentViaTier, handleRecordWip, handleReleaseFileClaim, handleReleaseSpec, handleReportProgress, handleSubmitForReview } from './claim-tools.mjs';
+import { handlePromoteDiagnose, handleVerifyReproduction } from './diagnose-handlers.mjs';
+import { handleHandoffLoad, handleHandoffRecord, handleImportAgent } from './session-tools.mjs';
+import { handleEventsShow, handleEvidenceShow, handleExportEvents, handleMilestoneShow } from './events-tools.mjs';
+import { handleClearFocusAreas, handleGetFocusAreas, handlePinGet, handlePinSet, handleResolveFocusIntent, handleSetFocusAreas } from './focus-tools.mjs';
+import { handleSearchSpecs } from './search-specs.mjs';
+import { handleDesignGetDoc, handleDesignGetPattern, handleDesignGetToken, handleDesignListPatterns, handleDesignProposePattern } from './design-handlers.mjs';
+import { handleGetProcedureViaTier, handleListProceduresViaTier, handleRunPreflightViaTier } from './procedure-handlers.mjs';
+import { handleListRecipes, handleStartRecipe } from './recipe-handlers.mjs';
+import { handleFleetQueueClaim, handleFleetQueueComplete, handleFleetQueueList, handleFleetQueueSubmit } from './fleet-handlers.mjs';
+import { handleDevMode, handleDevServerStatus } from './dev-tools.mjs';
+import { wrapDesignResult } from './tool-helpers.mjs';
+import { executeSettingsGet, executeSettingsList, executeSettingsSet } from './settings-tools.mjs';
+import { executeFirecrawlResearch, executeResolveResearchPlan } from './research-tools.mjs';
+import { formatSeatBanner, readSeatsRegistry, resolveSeat } from './seat-identity.mjs';
+import { seatBlockForSessionSurface } from './seat-block-ledger.mjs';
+import { resolveCooModeEnabled } from '../../dev-factory/lib/fleet-readiness.mjs';
+import { applyToolBudget } from './response-budget.mjs';
+import { resolveDevMode } from '../../scripts/lib/dev-mode.mjs';
+import { dirname, join } from 'node:path';
+import { MODULE_DIR } from './package-root.mjs';
+
+export const SERVER_NAME = 'heyspex';
+
+/**
+ * Read the server version from the nearest `package.json`, walking up from
+ * THIS file's own directory (`vendor/heyspex-mcp/package.json` if one ever
+ * exists, else the repo root's) — [[HS-7OKX-0JNK-TASK]]. Previously a
+ * hard-coded `'0.9.0'` that had drifted from the packed `heyspex@0.1.0`, so
+ * the `initialize` handshake's `serverInfo.version` disagreed with what was
+ * actually installed. Never throws: an unreadable/missing/malformed
+ * package.json anywhere up the tree falls through to `'0.0.0-unknown'`.
+ */
+export function readServerVersion() {
+  let dir = MODULE_DIR;
+  for (let i = 0; i < 16; i += 1) {
+    const candidate = join(dir, 'package.json');
+    if (existsSync(candidate)) {
+      try {
+        const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+        if (pkg && typeof pkg.version === 'string' && pkg.version.trim()) {
+          return pkg.version;
+        }
+      } catch {
+        // malformed package.json at this level — keep walking up rather than throw
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+  return '0.0.0-unknown';
+}
+
+export const SERVER_VERSION = readServerVersion();
+
+// MCP Channels capability is advertised in the initialize handshake.
+// Per https://code.claude.com/docs/en/channels-reference#server-options the
+// channel capability is nested under `experimental` and pushed events use
+// the `notifications/claude/channel` method. The instructions string is
+// injected into Claude's system prompt so it knows how to react to
+// <channel source="heyspex" …> events emitted by capture-channel.mjs.
+// Owning epic: [[HS-EPIC-QXJ3-modal-agent-handshake-mcp-channels-push-]].
+export const CHANNEL_INSTRUCTIONS =
+  'Events from the heyspex capture flow arrive as <channel source="heyspex" capture_id="HS-CAP-XXXX" event_type="user_quote">…</channel>. ' +
+  'When you receive one, call heyspex_active_capture WITH spec_id set to that exact capture_id ' +
+  '(e.g. heyspex_active_capture({ spec_id: "HS-CAP-XXXX" })) to fetch the latest capture state, and pass that same spec_id ' +
+  'to every heyspex_update_capture call for this capture. Do NOT call these tools without spec_id when you have the channel capture_id — ' +
+  'the no-spec_id path attaches to whichever capture was most recently active, which may be a different session (another console tab, ' +
+  'the companion app, or another agent) and would write to the wrong capture id. Then respond per the /hs-capture capture protocol ' +
+  '(Capture → Ground=Expand [grounding auto-writes agent_expansion, no confirm] → Promote to research). Do not infer user_quote ' +
+  'contents from the channel hint alone — always fetch fresh state via the tool.';
+
+// ── Dev-factory seat identity delivery (epic HS-CXO0) ────────────────────────
+// Resolve the seat THIS caller holds — gated by the shared fleet-readiness
+// predicate (identical to the SessionStart hook → no drift). Returns null (inject
+// nothing) on any error, cooMode off / auto-not-ready, or an unknown caller. A
+// Builder worker resolves to the Builder seat, a COO session to COO — each is told
+// its OWN seat, never another's.
+export function resolveInjectableSeat() {
+  try {
+    const { vaultRoot } = getConfig();
+    const registry = readSeatsRegistry(vaultRoot);
+    if (!registry) return null;
+    if (!resolveCooModeEnabled(registry.settings?.cooMode).enabled) return null;
+    const identity = detectAgentIdentity();
+    return resolveSeat(identity, { registry, env: process.env });
+  } catch {
+    return null; // seat logic must never break the server
+  }
+}
+
+export async function handleInitialize(params) {
+  let instructions = CHANNEL_INSTRUCTIONS;
+  try {
+    const banner = formatSeatBanner(resolveInjectableSeat());
+    if (banner) {
+      // Gate on the shared per-session ledger (HS-8U8X) rather than emitting
+      // unconditionally — the first tool result of the session (see cli.mjs
+      // maybePrependSeatBanner) shares this same ledger, so whichever surface
+      // asks first wins and the other gets null, never a second copy.
+      const { sessionId } = detectAgentIdentity();
+      const toSend = await seatBlockForSessionSurface(sessionId, 'mcp_instructions', banner);
+      if (toSend) instructions += `\n\n${toSend}`;
+    }
+  } catch {
+    // never break the initialize handshake on seat logic
+  }
+  return {
+    protocolVersion: '2024-11-05',
+    capabilities: {
+      // listChanged: heyspex_load_tools expands the visible surface at runtime
+      // ([[HS-LCRS-TASK]] progressive disclosure) and notifies the client.
+      tools: { listChanged: true },
+      prompts: {},
+      // [[HS-EPIC-QXJ3]] — channels capability nested under `experimental`
+      // per https://code.claude.com/docs/en/channels-reference#server-options.
+      // Presence registers the notification listener; emission happens in
+      // capture-channel.mjs via sendNotification('notifications/claude/channel', …).
+      experimental: {
+        'claude/channel': {},
+      },
+    },
+    instructions,
+    serverInfo: {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+  };
+}
+
+export function handleToolsList() {
+  // `budget` is a server-side contract (enforced below), not part of the MCP
+  // Tool wire shape — strip it so the client sees only name/description/schema.
+  return { tools: TOOLS.map(({ budget: _budget, ...tool }) => tool) };
+}
+
+/** The catalog's declared byte budget for a tool, or `null` when it declares none. */
+export function toolBudgetFor(name) {
+  const tool = TOOLS_BY_NAME.get(name);
+  return tool?.budget && Number(tool.budget.max_bytes) > 0 ? tool.budget : null;
+}
+
+const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+
+/**
+ * Every tool call goes through here. A tool that declares `budget` in the
+ * catalog ([[HS-4H8T-8KK5-TASK-every-mcp-read-tool-declares-a-byte]]) has
+ * its reply bounded to `budget.max_bytes` on the way out — trailing list items
+ * dropped behind a `next_cursor`, `truncated: true` — and a budget cursor on
+ * the way in resumes from the first dropped item (see response-budget.mjs).
+ * A tool without a budget is dispatched untouched.
+ */
+export function dispatchHeySpexTool(name, args, vaultRoot, config) {
+  // Lets deep writers (createSpecViaConsole & co.) and the first-success drain
+  // find the write outbox without every caller threading a vaultRoot.
+  setWriteOutboxRoot(vaultRoot);
+  return applyToolBudget(
+    name,
+    args,
+    (effectiveArgs) => dispatchHeySpexToolUnbudgeted(name, effectiveArgs, vaultRoot, config),
+    toolBudgetFor(name),
+  );
+}
+
+function dispatchHeySpexToolUnbudgeted(name, args, vaultRoot, config) {
+  switch (name) {
+    case 'heyspex_load_tools':
+      // Normally intercepted parent-side at the tools/call dispatch; this case is
+      // defense-in-depth for direct handleToolsCall callers (subprocess/CLI paths).
+      return handleLoadTools(args);
+    case 'heyspex_next_on_deck':
+      return handleNextOnDeck(vaultRoot, config, args);
+    case 'heyspex_next_review':
+      return handleNextReview(vaultRoot, config, args);
+    case 'heyspex_next_resolution':
+      return handleNextResolution(args);
+    case 'heyspex_validate_linkage':
+      return handleValidateLinkage(vaultRoot, args);
+    case 'heyspex_suggest_pillar':
+      return handleSuggestPillar(args);
+    case 'heyspex_validate_user_skills':
+      return handleValidateUserSkills(vaultRoot, args);
+    case 'heyspex_register_spec':
+      return handleRegisterSpec(vaultRoot, args);
+    case 'heyspex_save_research':
+      return handleSaveResearch(vaultRoot, args);
+    case 'heyspex_recall_memories':
+      return handleRecallMemoriesViaTier(vaultRoot, args);
+    case 'heyspex_push_plan':
+      return handlePushPlan(vaultRoot, args);
+    case 'heyspex_backfill_epic':
+      return handleShipEpic(vaultRoot, args);
+    case 'heyspex_ground_plan':
+      return handleGroundPlan(vaultRoot, args);
+    case 'heyspex_plan_review':
+      return handlePlanReview(vaultRoot, args);
+    case 'heyspex_plan_qc':
+      return handlePlanQc(vaultRoot, args);
+    case 'heyspex_active_capture':
+      return handleActiveCapture(vaultRoot, args);
+    case 'heyspex_update_capture':
+      return handleUpdateCapture(vaultRoot, args);
+    case 'heyspex_pin_capture':
+      return handlePinCapture(vaultRoot, args);
+    case 'heyspex_active_research':
+      return handleActiveResearch(vaultRoot, args);
+    case 'heyspex_complete_research':
+      return handleCompleteResearch(vaultRoot, args);
+    case 'heyspex_claim_spec':
+      return handleClaimSpec(args);
+    case 'heyspex_report_progress':
+      return handleReportProgress(args);
+    case 'heyspex_submit_for_review':
+      return handleSubmitForReview(vaultRoot, args);
+    case 'heyspex_verify_reproduction':
+      return handleVerifyReproduction(vaultRoot, args);
+    case 'heyspex_promote_diagnose':
+      return handlePromoteDiagnose(vaultRoot, args);
+    case 'heyspex_release_spec':
+      return handleReleaseSpec(args);
+    case 'heyspex_record_wip':
+      return handleRecordWip(args);
+    case 'heyspex_author_summary':
+      return handleAuthorSummary(vaultRoot, args);
+    case 'heyspex_defer_spec':
+      return handleDeferSpec(args);
+    case 'heyspex_handoff_record':
+      return handleHandoffRecord(args);
+    case 'heyspex_handoff_load':
+      return handleHandoffLoad(args);
+    case 'heyspex_milestone_show':
+      return handleMilestoneShow(args);
+    case 'heyspex_pin_get':
+      return handlePinGet(args);
+    case 'heyspex_pin_set':
+      return handlePinSet(args);
+    case 'heyspex_resolve_prerequisite':
+      return handleResolvePrerequisite(args);
+    case 'heyspex_claim_acquire':
+      return handleClaimAcquire(args);
+    case 'heyspex_claim_release':
+      return handleClaimRelease(args);
+    case 'heyspex_claim_list':
+      return handleClaimList(args);
+    case 'heyspex_claim_file':
+      return handleClaimFile(args);
+    case 'heyspex_release_file_claim':
+      return handleReleaseFileClaim(args);
+    case 'heyspex_edit_file':
+      return handleEditFile(args);
+    case 'heyspex_list_known_tags':
+      return handleListKnownTags(args);
+    case 'heyspex_set_focus_areas':
+      return handleSetFocusAreas(args);
+    case 'heyspex_get_focus_areas':
+      return handleGetFocusAreas(args);
+    case 'heyspex_clear_focus_areas':
+      return handleClearFocusAreas(args);
+    case 'heyspex_resolve_focus_intent':
+      return handleResolveFocusIntent(args);
+    case 'heyspex_search_specs':
+      return handleSearchSpecs(args);
+    case 'heyspex_events_show':
+      return handleEventsShow(args);
+    case 'heyspex_evidence_show':
+      return handleEvidenceShow(args);
+    case 'heyspex_export_events':
+      return handleExportEvents(args);
+    case 'heyspex_propose_metadata':
+      return handleProposeMetadata(args);
+    case 'heyspex_promote_research':
+      return handlePromoteResearch(vaultRoot, args);
+    case 'heyspex_promote_capture':
+      return handlePromoteCapture(vaultRoot, args);
+    case 'heyspex_promote_capture_to_diagnose':
+      return handlePromoteCaptureToDiagnose(vaultRoot, args);
+    case 'heyspex_promote_research_to_diagnose':
+      return handlePromoteResearchToDiagnose(vaultRoot, args);
+    case 'heyspex_split_research':
+      return handleSplitResearch(vaultRoot, args);
+    case 'heyspex_record_alignment':
+      return handleRecordAlignmentViaTier(vaultRoot, config, args);
+    case 'heyspex_design_list_patterns':
+      return handleDesignListPatterns(vaultRoot, args);
+    case 'heyspex_design_get_pattern':
+      return handleDesignGetPattern(vaultRoot, args);
+    case 'heyspex_design_get_token':
+      return handleDesignGetToken(vaultRoot, args);
+    case 'heyspex_design_get_doc':
+      return handleDesignGetDoc(vaultRoot, args);
+    case 'heyspex_design_propose_pattern':
+      return handleDesignProposePattern(vaultRoot, args);
+    case 'heyspex_list_procedures':
+      return handleListProceduresViaTier(vaultRoot, args);
+    case 'heyspex_get_procedure':
+      return handleGetProcedureViaTier(vaultRoot, args);
+    case 'heyspex_file_spec':
+      return handleFileSpec(args, vaultRoot);
+    case 'heyspex_import_agent':
+      return handleImportAgent(args);
+    case 'heyspex_preflight':
+      return handleRunPreflightViaTier(vaultRoot, args);
+    case 'heyspex_list_recipes':
+      return handleListRecipes(vaultRoot, args);
+    case 'heyspex_start_recipe':
+      return handleStartRecipe(vaultRoot, args);
+    case 'heyspex_canvas_inbox':
+      return handleCanvasInbox(vaultRoot, args);
+    case 'heyspex_fleet_queue_submit':
+      return handleFleetQueueSubmit(args);
+    case 'heyspex_fleet_queue_claim':
+      return handleFleetQueueClaim(args);
+    case 'heyspex_fleet_queue_complete':
+      return handleFleetQueueComplete(args);
+    case 'heyspex_fleet_queue_list':
+      return handleFleetQueueList(args);
+
+    case 'heyspex_dev_server_status':
+      return handleDevServerStatus(vaultRoot);
+    case 'heyspex_dev_mode':
+      return handleDevMode(vaultRoot, args);
+    case 'heyspex_settings_list':
+      return wrapDesignResult(executeSettingsList(vaultRoot, args));
+    case 'heyspex_settings_get':
+      return wrapDesignResult(executeSettingsGet(vaultRoot, args));
+    case 'heyspex_settings_set':
+      return wrapDesignResult(executeSettingsSet(vaultRoot, args));
+    case 'heyspex_resolve_research_plan':
+      // async since HS-ZJSP (the Firecrawl endpoint is resolved through the lazy
+      // dev-factory bridge) — same Promise-returning shape as the case below.
+      return executeResolveResearchPlan(vaultRoot).then(wrapDesignResult);
+    case 'heyspex_firecrawl_research':
+      // dispatchHeySpexTool is NOT async (mirrors the heyspex_dev_server_status precedent
+      // above) — return the chained Promise directly; finalizeToolResultWithHooks/
+      // Promise.resolve() at the call site unwrap it.
+      return executeFirecrawlResearch(args).then(wrapDesignResult);
+    case 'heyspex_regen_task':
+      return handleRegenTask(vaultRoot, args);
+    case 'heyspex_regen_tasks_for_epic':
+      return handleRegenTasksForEpic(vaultRoot, args);
+    default:
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+      };
+  }
+}
+
+/**
+ * Mode-aware vault gate, shared by `tools/call` (here) and `prompts/get`
+ * (cli.mjs). Returns `null` to proceed, or a `{ error, message }` payload.
+ *
+ * The old gate was `if (!existsSync(vaultRoot)) refuse` — mode-blind. In
+ * prod / cloud reliance (`resolveDevMode().readTier === 'neon'`) the server
+ * runs locally under Claude Code but every read is Neon-via-console and every
+ * write goes to the console, so a machine may legitimately have NO vault
+ * clone on disk; refusing there took every tool offline for exactly the
+ * customers the cloud path exists for. So: an absent root only refuses on the
+ * disk tier. On the neon tier the call proceeds with `vaultRoot` possibly
+ * absent — the `*ViaTier` handlers never touch it for reads, and the few
+ * machine-local writes (preflight markers) fall back to the HeySpex home
+ * (preflight-gate.mjs `preflightMarkerDir`).
+ *
+ * `resolveDevMode` is synchronous (env -> ~/.heyspex/dev-mode.json -> default
+ * prod) so `handleToolsCall` keeps its sync contract; a failure to resolve the
+ * mode degrades to the disk-tier refusal, the safe direction.
+ *
+ * Coverage: vault-gate-mode-aware.test.mjs drives `handleToolsCall` itself with
+ * a nonexistent root on both tiers. Note that cloud-reliant-session.test.mjs
+ * BYPASSES this gate on purpose — it calls the `*ViaTier` helpers directly —
+ * so it proves the handlers, not the gate; keep both.
+ */
+export function vaultRootGateVerdict(vaultRoot, { env = process.env } = {}) {
+  if (typeof vaultRoot === 'string' && vaultRoot && existsSync(vaultRoot)) return null;
+  let readTier = 'disk';
+  try {
+    readTier = resolveDevMode({ env }).readTier;
+  } catch {
+    readTier = 'disk';
+  }
+  if (readTier === 'neon') return null;
+  return { error: 'VAULT_NOT_FOUND', message: `Vault root not found: ${vaultRoot}` };
+}
+
+export function handleToolsCall(params) {
+  let { name, arguments: args = {} } = params;
+  const config = getConfig();
+  const vaultRoot = config.vaultRoot;
+
+  const gate = vaultRootGateVerdict(vaultRoot);
+  if (gate) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(gate) }],
+    };
+  }
+
+  const hooksCfg = loadHooksConfig(vaultRoot);
+
+  // Meta hook plumbing — avoid Pre/PostToolUse recursion on hook tools themselves.
+  if (name === 'heyspex_session_end') return handleSessionEnd(vaultRoot, args, hooksCfg);
+  if (name === 'heyspex_hooks_list') return applyToolBudget(name, args, () => handleHooksList(vaultRoot), toolBudgetFor(name));
+  if (name === 'heyspex_hooks_invoke') return handleHooksInvoke(vaultRoot, args, hooksCfg);
+
+  // ── PreToolUse hooks ──
+  const preResult = runHooks('PreToolUse', name, args, null, hooksCfg);
+  if (preResult.blocked) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'HOOK_BLOCKED',
+          message: preResult.reason ?? 'Blocked by PreToolUse hook',
+        }),
+      }],
+    };
+  }
+  if (preResult.modifiedInput) {
+    args = preResult.modifiedInput;
+  }
+
+  // Preflight proof-of-use ([[preflight-gate]]). Deliberately here and not in a
+  // PreToolUse hook: hooks fail open and `.heyspex/mode.json` can disarm them,
+  // whereas this runs on every call in every session. `refuse` returns instead
+  // of dispatching; `warn` lets the call through and rides along on the result.
+  const preflightVerdict = evaluatePreflightGate(
+    vaultRoot,
+    name,
+    args,
+    detectAgentIdentity(args.agent, args.session_id).sessionId,
+  );
+  if (preflightVerdict && preflightVerdict.level === 'refuse') {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: preflightVerdict.error,
+          message: preflightVerdict.message,
+          required_intents: preflightVerdict.intents,
+          tool: preflightVerdict.tool,
+        }, null, 2),
+      }],
+    };
+  }
+
+  // Capture-obligation backstop ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]): holds on surfaces where
+  // no hook loads. Fail open; break-glass HEYSPEX_OBLIGATION_BACKSTOP_OFF=1.
+  const obligationVerdict = evaluateObligationBackstop(name, args, {
+    sessionId: detectAgentIdentity(args.agent, args.session_id).sessionId,
+    vaultRoot,
+  });
+  if (obligationVerdict) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(obligationVerdict, null, 2) }],
+    };
+  }
+
+  const result = dispatchHeySpexTool(name, args, vaultRoot, config);
+  const finalized = finalizeToolResultWithHooks(name, args, result, hooksCfg, preResult);
+  return preflightVerdict && preflightVerdict.level === 'warn'
+    ? attachPreflightWarning(finalized, preflightVerdict)
+    : finalized;
+}
+
+/**
+ * Ride a warn-level preflight verdict along on an otherwise successful result.
+ * Best-effort by construction — a result whose text is not JSON is left exactly
+ * as it was rather than mangled to carry a warning.
+ */
+export function attachPreflightWarning(result, verdict) {
+  try {
+    const block = result?.content?.[0];
+    if (!block || block.type !== 'text' || typeof block.text !== 'string') return result;
+    const payload = JSON.parse(block.text);
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return result;
+    payload.preflight_warning = {
+      code: verdict.error,
+      message: verdict.message,
+      required_intents: verdict.intents,
+    };
+    return {
+      ...result,
+      content: [{ ...block, text: JSON.stringify(payload, null, 2) }, ...result.content.slice(1)],
+    };
+  } catch {
+    return result;
+  }
+}
+
+/**
+ * Handle heyspex_session_end — fire SessionEnd hooks and return results.
+ *
+ * The agent calls this explicitly at session close to trigger cleanup hooks
+ * (release claim, record WIP, notify console). In Claude Code these fire
+ * automatically via SessionEnd/Stop hooks; in Command Code the agent must
+ * call this tool.
+ */
+export function handleSessionEnd(vaultRoot, args, hooksCfg) {
+  const cfg = hooksCfg ?? loadHooksConfig(vaultRoot);
+  const groups = matchHooks('SessionEnd', 'heyspex_session_end', cfg);
+  if (groups.length === 0) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          session_ended: true,
+          hooks_run: 0,
+          note: 'No SessionEnd hooks configured. Call heyspex_release_spec if a spec is claimed.',
+        }, null, 2),
+      }],
+    };
+  }
+
+  const results = [];
+  const payload = {
+    hook_event_name: 'SessionEnd',
+    tool_name: 'heyspex_session_end',
+    tool_input: { reason: args?.reason ?? 'completed' },
+    cwd: vaultRoot,
+  };
+
+  for (const group of groups) {
+    const handlers = group.hooks ?? [];
+    for (const hookDef of handlers) {
+      try {
+        const r = executeHook(hookDef, payload, { vaultRoot });
+        results.push({
+          command: hookDef.command,
+          args: hookDef.args,
+          success: !r.blocked,
+          ...(r.reason ? { reason: r.reason } : {}),
+        });
+      } catch (err) {
+        results.push({
+          command: hookDef.command,
+          success: false,
+          error: err?.message ?? String(err),
+        });
+      }
+    }
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        session_ended: true,
+        hooks_run: results.length,
+        results,
+      }, null, 2),
+    }],
+  };
+}
+
+/**
+ * Handle heyspex_hooks_invoke — run lifecycle hooks on demand (Command Code parity).
+ */
+export function handleHooksInvoke(vaultRoot, args, hooksCfg) {
+  const event = args?.event;
+  const validEvents = ['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'SessionEnd'];
+  if (!validEvents.includes(event)) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'INVALID_EVENT',
+          message: `event must be one of: ${validEvents.join(', ')}`,
+        }),
+      }],
+    };
+  }
+
+  if (event === 'SessionEnd') {
+    return handleSessionEnd(vaultRoot, { reason: args?.reason ?? 'hooks_invoke' }, hooksCfg);
+  }
+
+  if (event === 'UserPromptSubmit') {
+    const prompt = args?.prompt;
+    if (typeof prompt !== 'string' || !prompt.trim()) {
+      return {
+        isError: true,
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: 'MISSING_PROMPT',
+            message: 'prompt is required for UserPromptSubmit',
+          }),
+        }],
+      };
+    }
+    const hookResult = runHooks('UserPromptSubmit', '*', { prompt }, null, hooksCfg);
+    return formatHookInvokeResult(hookResult);
+  }
+
+  const toolName = args?.tool_name ?? '*';
+  const toolInput = args?.tool_input ?? {};
+
+  if (event === 'PreToolUse') {
+    const hookResult = runHooks('PreToolUse', toolName, toolInput, null, hooksCfg);
+    return formatHookInvokeResult(hookResult);
+  }
+
+  const toolResponse = args?.tool_response ?? {};
+  const hookResult = runHooks('PostToolUse', toolName, toolInput, toolResponse, hooksCfg);
+  return formatHookInvokeResult(hookResult);
+}
+
+export function formatHookInvokeResult(hookResult) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        blocked: hookResult.blocked ?? false,
+        reason: hookResult.reason ?? null,
+        additional_contexts: hookResult.additionalContexts ?? [],
+        modified_input: hookResult.modifiedInput ?? null,
+      }, null, 2),
+    }],
+  };
+}
+
+/**
+ * Handle heyspex_hooks_list — return the active hook configuration.
+ */
+export function handleHooksList(vaultRoot) {
+  const cfg = listHookConfig(vaultRoot);
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(cfg, null, 2),
+    }],
+  };
+}