@fusengine/harness 0.1.90 → 0.1.92

package/src/runtime/lifecycle/teammate-idle-check.ts

@@ -0,0 +1,63 @@
+/**
+ * @module teammate-idle-check
+ * TeammateIdle anti-"false done": alongside the existing sniper suggestion
+ * ({@link validateTeammateOutput}), verify that the files this teammate ANNOUNCED
+ * (session-changes `modifiedFiles`) actually exist on disk. A claimed deliverable
+ * missing on disk is a mechanically-verifiable false-done signal → warn the lead.
+ * Deduped across the fan-out; silent when nothing is verifiable. Fail-open.
+ *
+ * Claude-Code-only: no equivalent `TeammateIdle` hook exists on Codex or Hermes,
+ * so this handler is never reached through those adapters.
+ * @packageDocumentation
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { systemMessage } from "../../adapters/claude";
+import { loadSessionState, sanitizeSessionId } from "../home-state";
+import { oncePerWindow } from "../inject-dedup";
+import { defaultStateDir } from "../paths";
+import { notify } from "../notifications";
+import { validateTeammateOutput } from "./teammate-idle";
+
+/** Re-warn about the same idle teammate at most once per 30s (fan-out + retries). */
+const IDLE_DEDUP_MS = 30_000;
+
+/** The `changes` block written by `track-changes.ts` into unified session state. */
+interface Changes { modifiedFiles?: string[]; }
+
+/** Announced files (session changes) that are ABSENT on disk (the false-done set). */
+function missingDeliverables(sessionId: string, home: string): string[] {
+  const changes = loadSessionState(sessionId, home).changes as Changes | undefined;
+  return (changes?.modifiedFiles ?? []).filter((f) => typeof f === "string" && f !== "" && !existsSync(f));
+}
+
+/**
+ * Handle TeammateIdle: merge the existing sniper suggestion with a missing-
+ * deliverable warning (deduped) into one advisory `systemMessage`, or "" when
+ * neither fires. TeammateIdle rejects `hookSpecificOutput` (no `additionalContext`
+ * channel) — `systemMessage` is the only user-visible, non-blocking channel it
+ * accepts.
+ * @param data - The raw TeammateIdle payload (`teammate_name`, `session_id`).
+ * @param cwd - Project root (state dir for the dedup sidecar).
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout, or "".
+ */
+export function teammateIdleContext(data: Record<string, unknown>, cwd: string, home: string = homedir(), now: number = Date.now()): string {
+  const sniper = validateTeammateOutput(data, home);
+  const sessionId = sanitizeSessionId(data.session_id);
+  const teammate = String(data.teammate_name ?? data.team_name ?? "unknown");
+  let notice = "";
+  if (sessionId) {
+    const missing = missingDeliverables(sessionId, home);
+    if (missing.length > 0 && oncePerWindow(`idle:${sessionId}:${teammate}`, IDLE_DEDUP_MS, { now, dir: defaultStateDir(cwd) })) {
+      notice = `Teammate '${teammate}' idle but expected deliverable(s) not found on disk: ${missing.slice(0, 5).join(", ")} — verify before treating as done.`;
+    }
+  }
+  const merged = [sniper, notice].filter(Boolean).join("\n\n");
+  if (!merged) return "";
+  // An actionable idle signal (false-done or sniper suggestion) warrants human
+  // attention — voice the "human" sound (fire-and-forget, fail-open no-op).
+  notify("human");
+  return systemMessage(merged);
+}

package/src/runtime/lifecycle/teammate-idle.ts

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { loadSessionState, sanitizeSessionId } from "../home-state";
+
+/** The `changes` block written by `track-changes.ts` into unified session state. */
+interface Changes {
+  cumulativeCodeFiles?: number;
+  modifiedFiles?: string[];
+}
+
+/**
+ * Handle TeammateIdle: when the teammate's session-changes file shows code was
+ * modified, suggest sniper validation as plain text — TeammateIdle has no
+ * `additionalContext` channel (rejects `hookSpecificOutput`), so the caller
+ * ({@link module:teammate-idle-check.teammateIdleContext}) rides this text on
+ * the `systemMessage` channel instead. Ports `teammate-idle/validate-teammate-output.py`.
+ * @param data - The raw hook payload.
+ * @param home - Home dir (defaults to `~`).
+ * @returns The plain notice text, or "" when no code file was modified.
+ */
+export function validateTeammateOutput(data: Record<string, unknown>, home: string = homedir()): string {
+  const teammate = String(data.teammate_name ?? "unknown");
+  const sessionId = sanitizeSessionId(data.session_id) ?? "unknown";
+  const changes = loadSessionState(sessionId, home).changes as Changes | undefined;
+  const count = changes?.cumulativeCodeFiles ?? 0;
+  if (count === 0) return "";
+  const files = (changes?.modifiedFiles ?? []).slice(0, 5).join(", ");
+  return `Teammate '${teammate}' going idle after modifying ${count} code file(s): ${files}. Consider running sniper validation.`;
+}

package/src/runtime/lifecycle/tool-failure.ts

@@ -0,0 +1,24 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Handle PostToolUseFailure: append a `TOOL_FAILURE` line to
+ * `~/.claude/logs/tool-failures.log`, skipping user interrupts. Ports
+ * `post-tool-use/log-tool-failure.py`. No stdout (logging only).
+ * @param data - The raw hook payload.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ */
+export function logToolFailure(data: Record<string, unknown>, home: string = homedir(), now: number = Date.now()): void {
+  if (data.is_interrupt === true) return;
+  const tool = String(data.tool_name ?? "unknown");
+  const error = String(data.error ?? "unknown error");
+  const sessionId = String(data.session_id ?? "unknown");
+  const ts = new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+  const dir = join(home, ".claude", "logs");
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "tool-failures.log"), `[${ts}] TOOL_FAILURE session=${sessionId} tool=${tool} error=${error}\n`, "utf-8");
+  } catch { /* best effort */ }
+}

package/src/runtime/lifecycle/track-changes.ts

@@ -0,0 +1,61 @@
+import { basename } from "node:path";
+import { homedir } from "node:os";
+import { attachSystemMessage, contextResponse } from "../../adapters/claude";
+import { loadSessionState, sanitizeSessionId, saveSessionState, sessionsDir } from "../home-state";
+import { onceExclusive } from "../inject-dedup";
+import { BURST_DEDUP_MS } from "../burst-window";
+import { sniperRequiredNotice } from "../notices";
+
+/** Code-file extensions tracked for sniper (mirrors track-session-changes.py). */
+const CODE_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|vue|svelte|astro)$/;
+
+/** Shape of the `changes` block persisted in per-session state. */
+interface Changes {
+  cumulativeCodeFiles: number;
+  modifiedFiles: string[];
+  lastModifiedFile?: string;
+  lastCheck?: string;
+}
+
+/**
+ * Handle PostToolUse Write/Edit: track the cumulative set of modified code
+ * files per session and emit the mandatory "SNIPER VALIDATION REQUIRED"
+ * additionalContext. Ports `post-tool-use/track-session-changes.py`.
+ * @param sessionIdRaw - Raw session id from the payload.
+ * @param filePath - The edited file path.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout (possibly empty when not a code file).
+ */
+export function trackSessionChanges(sessionIdRaw: unknown, filePath: string, home: string = homedir(), now: number = Date.now()): string {
+  if (!filePath || !CODE_EXT.test(filePath)) return "";
+  const sid = sanitizeSessionId(sessionIdRaw) ?? "unknown";
+  const state = loadSessionState(sid, home);
+  const prev = (state.changes as Changes | undefined) ?? { cumulativeCodeFiles: 0, modifiedFiles: [] };
+  const files = [...prev.modifiedFiles];
+  let count = prev.cumulativeCodeFiles;
+  if (!files.includes(filePath)) { count += 1; files.push(filePath); }
+  state.changes = {
+    cumulativeCodeFiles: count,
+    modifiedFiles: files,
+    lastModifiedFile: filePath,
+    lastCheck: new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z"),
+  } satisfies Changes;
+  saveSessionState(sid, state, home);
+  // Emit the mandatory reminder ONCE per (file+session) burst: the ~11 sibling
+  // plugin hooks of one PostToolUse event would otherwise inject it ~11× (token
+  // noise). A real re-edit past the window reminds again. See burst-window.
+  // Exclusive mode (not the JSON oncePerWindow): this call is exactly the
+  // high-concurrency shape that mode is best-effort against under the real
+  // ~11-process fan-out (lesson 2026-07-05 16:00).
+  if (!onceExclusive(`sniper:${sid}:${filePath}`, BURST_DEDUP_MS, { now, dir: sessionsDir(home) })) return "";
+  const fname = basename(filePath);
+  const stdout = contextResponse(
+    "PostToolUse",
+    `SNIPER VALIDATION REQUIRED: Code file '${fname}' was modified. You MUST now run the sniper agent (fuse-ai-pilot:sniper) to validate this modification before continuing. This is mandatory per CLAUDE.md rules.`,
+  );
+  // User-visible companion to the additionalContext reminder above (which only
+  // reaches the agent, never the human) — rides the SAME oncePerWindow gate above,
+  // so the ×11 hook fan-out never duplicates it.
+  return attachSystemMessage(stdout, sniperRequiredNotice(fname));
+}

package/src/runtime/lifecycle/validate-solid.ts

@@ -0,0 +1,70 @@
+/**
+ * PreToolUse (matcher "Write|Edit") for the solid scope: deny a Go top-level
+ * interface or a Python `ABC` subclass defined outside its language's
+ * `/interfaces/` directory. Ports `solid/scripts/validate-solid.py`'s
+ * `check_go`/`check_python` only — its `check_nextjs`/`check_laravel`/
+ * `check_swift` siblings are NOT ported here: they are a strict subset of the
+ * already-ported `framework-solid-gates.ts` (react/nextjs/laravel/swift),
+ * which fire unconditionally on file extension/content rather than being
+ * gated behind `SOLID_PROJECT_TYPE`. Inert when `SOLID_PROJECT_TYPE` is
+ * absent/"unknown"/nextjs/laravel/swift/rust (parity: the Python hook only
+ * has a `go`/`python` validator).
+ *
+ * Detection rides the conventions module (MASKED content, column-0 anchored
+ * for Go): the old naive regexes matched inside comments/strings and
+ * indented locals — all killed. LEGACY-level detections keep the exact hard
+ * deny (byte-parity); EXTENDED-level ones (Go `interface{` without the
+ * space, Python `Protocol`) follow `FUSE_CONVENTIONS_MODE` — advisory
+ * (non-blocking additionalContext) by default, deny only on `"deny"`
+ * (owner Amendment 5, external audit D0.2).
+ */
+import { contextResponse, denyResponse } from "../../adapters/claude";
+import { interfaceDeclLevel } from "../../policy/conventions/interfaces";
+import { conventionsMode } from "../../policy/conventions/verdict";
+
+/** Go: deny a top-level interface declared outside `/interfaces/`. */
+function checkGo(filePath: string, content: string, env: Record<string, string | undefined>): string | null {
+  if (!filePath.endsWith(".go") || filePath.includes("/interfaces/")) return null;
+  const level = interfaceDeclLevel(filePath, content);
+  if (level === null) return null;
+  const msg = "SOLID: Interfaces must be in internal/interfaces/";
+  if (level === "legacy" || conventionsMode(env) === "deny") return denyResponse("PreToolUse", msg);
+  return contextResponse("PreToolUse", msg);
+}
+
+/** Python: deny an ABC subclass declared outside `/interfaces/`. */
+function checkPython(filePath: string, content: string, env: Record<string, string | undefined>): string | null {
+  if (!filePath.endsWith(".py") || filePath.includes("/interfaces/")) return null;
+  const level = interfaceDeclLevel(filePath, content);
+  if (level === null) return null;
+  const msg = "SOLID: Abstract classes must be in src/interfaces/";
+  if (level === "legacy" || conventionsMode(env) === "deny") return denyResponse("PreToolUse", msg);
+  return contextResponse("PreToolUse", msg);
+}
+
+/** `SOLID_PROJECT_TYPE` values this gate validates (parity subset — see module doc). */
+const VALIDATORS: Record<string, (filePath: string, content: string, env: Record<string, string | undefined>) => string | null> = {
+  go: checkGo,
+  python: checkPython,
+};
+
+/**
+ * Deny (or advise on) a Write/Edit that violates the Go/Python interface-location SOLID rule.
+ * @param tool - The tool name (only "Write"/"Edit" are checked).
+ * @param filePath - The written file's absolute path.
+ * @param content - The written/edited content (`new_string` snippet on Edit).
+ * @param env - Environment (defaults to `process.env`).
+ * @returns The PreToolUse response, or `""` when clean/inert.
+ */
+export function validateSolidGate(
+  tool: string,
+  filePath: string,
+  content: string,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const ptype = env.SOLID_PROJECT_TYPE ?? "";
+  if (!ptype || ptype === "unknown") return "";
+  if (tool !== "Write" && tool !== "Edit") return "";
+  if (!filePath) return "";
+  return VALIDATORS[ptype]?.(filePath, content, env) ?? "";
+}

package/src/runtime/lifecycle/validate-tailwind.ts

@@ -0,0 +1,80 @@
+/**
+ * PostToolUse (matcher "Write|Edit") for the tailwindcss scope: warn
+ * (non-blocking) on a deprecated `@tailwind` directive, excessive `@apply`
+ * usage, and an overlong `className` string on a just-written CSS/TSX/JSX
+ * file inside a detected Tailwind project. Ports `validate-tailwind.py`.
+ */
+import { dirname, join } from "node:path";
+import { readText, pathExists } from "../../util/runtime-io";
+import { contextResponse } from "../../adapters/claude";
+
+/** Tailwind config file names checked at each ancestor directory. */
+const TAILWIND_CONFIGS = ["tailwind.config.js", "tailwind.config.ts", "tailwind.config.mjs", "tailwind.config.cjs"];
+
+/** Walk up to 20 levels from `filePath`'s directory to the nearest ancestor holding `package.json` or a Tailwind config (parity `find_project_root`). */
+function findProjectRoot(filePath: string): string | null {
+  let dir = dirname(filePath);
+  for (let i = 0; i < 20; i++) {
+    if (pathExists(join(dir, "package.json")) || TAILWIND_CONFIGS.some((cfg) => pathExists(join(dir, cfg)))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/** True when `filePath` belongs to a Tailwind project (v3 config, or `tailwindcss` in package.json deps). Parity `is_tailwind_project`. */
+function isTailwindProject(filePath: string): boolean {
+  const root = findProjectRoot(filePath);
+  if (!root) return false;
+  if (TAILWIND_CONFIGS.some((cfg) => pathExists(join(root, cfg)))) return true;
+  const pkgPath = join(root, "package.json");
+  if (!pathExists(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(readText(pkgPath)) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+    return Boolean(pkg.dependencies?.tailwindcss) || Boolean(pkg.devDependencies?.tailwindcss);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate Tailwind best practices on a just-written file.
+ * @param tool - The tool name (only "Write"/"Edit" are checked).
+ * @param filePath - The written file's absolute path.
+ * @returns The PostToolUse `additionalContext` response, or `""` when clean/inert.
+ */
+export function validateTailwind(tool: string, filePath: string): string {
+  if (tool !== "Write" && tool !== "Edit") return "";
+  if (!/\.(css|tsx|jsx)$/.test(filePath)) return "";
+  if (!pathExists(filePath) || !isTailwindProject(filePath)) return "";
+
+  let content: string;
+  try {
+    content = readText(filePath);
+  } catch {
+    return "";
+  }
+
+  const warnings: string[] = [];
+
+  if (filePath.endsWith(".css")) {
+    if (/@tailwind (base|components|utilities)/.test(content)) {
+      warnings.push("Tailwind v4: @tailwind directives are deprecated - use @import 'tailwindcss'.");
+    }
+    const applyCount = (content.match(/@apply/g) ?? []).length;
+    if (applyCount > 10) {
+      warnings.push(`Excessive @apply usage (${applyCount}) - prefer utility classes directly.`);
+    }
+  }
+
+  if (/\.(tsx|jsx)$/.test(filePath)) {
+    const longClasses = (content.match(/className="[^"]{150,}"/g) ?? []).length;
+    if (longClasses > 0) {
+      warnings.push(`Very long className (${longClasses} lines) - extract to @utility or use cn().`);
+    }
+  }
+
+  if (warnings.length === 0) return "";
+  return contextResponse("PostToolUse", warnings.join(" "));
+}

package/src/runtime/lifecycle-bridge.ts

@@ -0,0 +1,74 @@
+import { dispatchLifecycle, postEditTypescript, trackSessionChanges, type PluginScope } from "./lifecycle";
+import { autoDocumentRead } from "./lifecycle/auto-document-reads";
+import { contextResponse } from "../adapters/claude";
+import { cursorEventContract } from "../adapters/cursor/events";
+import { toCursorLifecycleResponse } from "../adapters/cursor/respond";
+import type { NormalizedEvent } from "./normalize";
+
+/** Raw event name from a payload (Cline lacks one; lifecycle is Claude-only). */
+function rawEvent(payload: Record<string, unknown>): string {
+  return typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+}
+
+/** Extract the `additionalContext` body from a `contextResponse(...)` stdout string ("" when empty/unparseable). */
+function additionalContextOf(stdout: string): string {
+  if (!stdout) return "";
+  try {
+    const parsed = JSON.parse(stdout) as { hookSpecificOutput?: { additionalContext?: string } };
+    return parsed.hookSpecificOutput?.additionalContext ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Run the ported lifecycle/session/context hooks (SessionStart, SubagentStart/
+ * Stop, TeammateIdle, PostToolUseFailure, PreCompact, SessionEnd,
+ * InstructionsLoaded, rules-scope UserPromptSubmit). Returns the native stdout
+ * when handled, or `null` to fall through to the tool-use pipeline.
+ * @param payload - The raw hook payload.
+ * @param cwd - Project root.
+ * @param scope - The invoking plugin scope (defaults to `core`).
+ * @param now - Clock.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native stdout, or `null` when unhandled.
+ */
+export function lifecycleStdout(payload: Record<string, unknown>, cwd: string, scope: PluginScope, now: number, id: string = "claude-code"): string | null {
+  const wireEvent = rawEvent(payload);
+  if (id !== "cursor") return dispatchLifecycle({ event: wireEvent, payload, cwd, scope, now, id });
+  const lifecycleEvent = cursorEventContract(wireEvent).lifecycle;
+  if (lifecycleEvent === null) return null;
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : payload.conversation_id;
+  const stdout = dispatchLifecycle({
+    event: lifecycleEvent,
+    payload: { ...payload, session_id: sessionId },
+    cwd,
+    scope,
+    now,
+    id,
+  });
+  return stdout === null ? null : toCursorLifecycleResponse(stdout, wireEvent);
+}
+
+/**
+ * Post-edit additions for core-scope PostToolUse: auto-document a Read of a
+ * SKILL.md/README/docs file; else (Write/Edit) track cumulative session
+ * changes (sniper reminder) AND report eslint/prettier issues — parity
+ * core-guards hooks.json, which runs both as independent PostToolUse commands
+ * rather than short-circuiting one on the other. Returns the combined extra
+ * stdout, or "" when nothing to emit.
+ * @param scope - The invoking plugin scope.
+ * @param event - The normalized event.
+ * @param now - Clock.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The extra stdout (possibly empty).
+ */
+export async function postEditContext(scope: PluginScope, event: NormalizedEvent, now: number, id: string = "claude-code"): Promise<string> {
+  if (scope !== "core" || !event.filePath) return "";
+  if (event.tool === "Read") return autoDocumentRead(event.filePath, now, id);
+  if (event.tool !== "Write" && event.tool !== "Edit") return "";
+  const sniper = trackSessionChanges(event.sessionId, event.filePath, undefined, now);
+  const lint = postEditTypescript(event.filePath);
+  if (!sniper || !lint) return sniper || lint;
+  return contextResponse("PostToolUse", `${additionalContextOf(sniper)}\n\n${additionalContextOf(lint)}`);
+}

package/src/runtime/mcp-key.ts

@@ -0,0 +1,44 @@
+/** Cache-key + tool-class helpers for the MCP/WebFetch interception pipeline. */
+import { parseEnvInt } from "../config/env";
+
+/** Default cached-MCP freshness in seconds (48h). */
+const MCP_TTL_DEFAULT_SEC = 172_800;
+/** Default WebFetch freshness in seconds (24h, parity with Python). */
+const WEBFETCH_TTL_DEFAULT_SEC = 86_400;
+
+/** Cached-MCP freshness (ms) from `FUSE_MCP_TTL_SEC` (default 48h). */
+export const MCP_TTL_MS: number = parseEnvInt(process.env.FUSE_MCP_TTL_SEC, MCP_TTL_DEFAULT_SEC) * 1000;
+
+/** WebFetch freshness (ms) from `FUSE_WEBFETCH_TTL_SEC` (default 24h; pages stale faster than docs). */
+export const WEBFETCH_TTL_MS: number = parseEnvInt(process.env.FUSE_WEBFETCH_TTL_SEC, WEBFETCH_TTL_DEFAULT_SEC) * 1000;
+
+/** WebFetch prompt slice folded into its cache key (parity with Python prompt[:500]). */
+const PROMPT_TRUNC = 500;
+
+/** True for the WebFetch tool (exact name) or Kimi Code CLI's `FetchURL` equivalent. */
+export function isWebFetch(tool: string): boolean {
+  return tool === "WebFetch" || tool === "FetchURL";
+}
+
+/** MCP doc tools + WebFetch/FetchURL whose calls are cached / verbosity-capped. */
+export function isMcpTool(tool: string): boolean {
+  return /context7|exa|webfetch|web_fetch/i.test(tool) || isWebFetch(tool);
+}
+
+/** The query/url that keys the cache. */
+export function queryOf(input: Record<string, unknown>): string {
+  const q = input.query ?? input.url ?? input.libraryId ?? "";
+  return typeof q === "string" ? q : JSON.stringify(q);
+}
+
+/**
+ * The string that keys the cache for `tool`. WebFetch folds `url + "\n" +
+ * prompt[:500]` (parity with Python) so distinct prompts on the same URL never
+ * collide; every other tool keys on {@link queryOf}.
+ */
+export function cacheQueryOf(tool: string, input: Record<string, unknown>): string {
+  if (!isWebFetch(tool)) return queryOf(input);
+  const url = typeof input.url === "string" ? input.url.trim() : "";
+  const prompt = typeof input.prompt === "string" ? input.prompt : "";
+  return `${url}\n${prompt.slice(0, PROMPT_TRUNC)}`;
+}

package/src/runtime/mcp-tool-name.ts

@@ -0,0 +1,92 @@
+/**
+ * @module mcp-tool-name
+ * Canonicalizes a Codex-only MCP `tool_name` alias back to its original
+ * hyphenated form, so every existing dash-keyed consumer (`SHOT_TOOLS`,
+ * `RESEARCH_TOOLS`/`classifyExplore`, `docSourceOf`, the design-pipeline
+ * `NAV`/`SCROLL`/`GEMINI` constants, …) recognizes a Codex MCP call exactly
+ * like the same call on Claude/Kimi/Cursor/Cline/Gemini — no per-consumer
+ * change needed.
+ *
+ * Codex CLI globally rewrites every `-` to `_` across the FULL qualified MCP
+ * tool identifier before it ever reaches a hook, in `sanitize_responses_api_tool_name()`
+ * (`codex-rs/core/src/mcp_connection_manager.rs`, introduced by
+ * openai/codex#14605 — "Normalize MCP tool names to code-mode safe form",
+ * code-mode forbids `-` in identifiers). openai/codex#18385's own
+ * `SCENARIO_DASH_TOOL` test proves the REWRITTEN form is what reaches hooks:
+ * the `echo-tool` tool of server `rmcp` is delivered to hooks as
+ * `mcp__rmcp__echo_tool`. Confirmed independently in THIS repo's terrain:
+ * `~/.codex/config.toml` declares `[mcp_servers.fuse-browser]` (dash) while
+ * Codex session logs and this harness's own dual-marketplace hook payloads
+ * (`~/.codex/plugins/.../hooks.json` matchers) observe `mcp__fuse_browser__*`
+ * (underscore) — Claude never emits that form (0 occurrences across its
+ * transcripts vs 137x the dash form).
+ *
+ * The rewrite is deliberately NOT undone with a generic `_` -> `-` regex:
+ * openai/codex#15832 and #15565 document it as NON-INVERSIBLE — a server
+ * literally named `autok_local` collides with a dash-named `autok-local`
+ * once both pass through the same rewrite, and OpenAI's own fix was a closed
+ * canonical table, never a general regex. The SAME ambiguity exists on our
+ * side: a generic reversal would corrupt tool segments that legitimately
+ * contain an underscore already (`browser_screenshot`, `node_repl`,
+ * `build_sim`, …). So this module only reverses the FOUR entries proven
+ * above to matter to this repo's gates — every other segment passes through
+ * untouched.
+ * @packageDocumentation
+ */
+
+/**
+ * Codex-mangled MCP server segment -> its real (dash) server name. Closed set
+ * — see module doc. `Object.create(null)` (never a `{}` literal): `serverKey`
+ * is an attacker-influenced string (an MCP server can register itself as
+ * `"__proto__"`/`"constructor"`/`"toString"`), and a `{}`-literal lookup by
+ * such a key returns the INHERITED `Object.prototype` member instead of
+ * `undefined` — an object/function, so `?? serverKey` never falls back and
+ * the result silently corrupts to `"mcp__[object Object]__…"` (proven in
+ * `test/mcp-tool-name.test.ts`, prototype-pollution-read case). A null-
+ * prototype object has no inherited members, so every lookup outside the two
+ * literal keys below is a clean miss.
+ */
+const SERVER_ALIASES: Readonly<Record<string, string>> = Object.assign(Object.create(null), {
+  fuse_browser: "fuse-browser",
+  gemini_design: "gemini-design",
+});
+
+/**
+ * Codex-mangled MCP tool segment -> its real (dash) tool name. Both entries
+ * are `context7`-exclusive tool names — applied ONLY when the canonical
+ * server is `"context7"` (see the explicit guard in
+ * {@link canonicalizeMcpToolName}), never globally. A same-named tool on any
+ * other server (e.g. a hypothetical `exa__query_docs`) passes through
+ * untouched: openai/codex#15832 documents exactly this class of collision as
+ * the reason the rewrite must stay a closed, scoped table, never a blanket
+ * one. Closed set, same null-prototype rationale as {@link SERVER_ALIASES}.
+ */
+const TOOL_ALIASES: Readonly<Record<string, string>> = Object.assign(Object.create(null), {
+  query_docs: "query-docs",
+  resolve_library_id: "resolve-library-id",
+});
+
+/**
+ * Canonicalize a Codex-only MCP tool-name alias to its dash form. Scoped to
+ * `id === "codex"` — every other harness id passes through unchanged. The
+ * server segment is rewritten via the closed {@link SERVER_ALIASES} table;
+ * the tool segment is rewritten via {@link TOOL_ALIASES} ONLY when the
+ * (already-resolved) canonical server is `"context7"` — every other server's
+ * tool segment is left untouched even if it happens to share a name with a
+ * context7 tool. Every other `mcp__<server>__<tool>` segment (or non-MCP
+ * tool name) is returned byte-identical (see `test/mcp-tool-name.test.ts`
+ * for the non-regression proof across ids, trap tool names, and the
+ * server-scoping cases).
+ * @param id - Harness adapter id (e.g. "codex", "claude-code", "kimi").
+ * @param tool - Raw `tool_name` from the hook payload.
+ */
+export function canonicalizeMcpToolName(id: string, tool: string): string {
+  if (id !== "codex") return tool;
+  const parts = tool.split("__");
+  if (parts.length < 3 || parts[0] !== "mcp") return tool;
+  const serverKey = parts[1] ?? "";
+  const toolKey = parts.slice(2).join("__");
+  const server = SERVER_ALIASES[serverKey] ?? serverKey;
+  const rest = server === "context7" ? (TOOL_ALIASES[toolKey] ?? toolKey) : toolKey;
+  return `mcp__${server}__${rest}`;
+}

package/src/runtime/mcp.ts

@@ -0,0 +1,91 @@
+import { capVerbosity } from "../policy/verbosity";
+import { cacheLookupMeta, cacheLookupSubstringMeta, type CacheHit } from "../cache/store";
+import { extractText } from "../cache/mcp-response";
+import { mcpCacheWrite, webfetchCacheWrite } from "../cache/mcp-store";
+import { WEBFETCH_TTL_MS, cacheQueryOf, isMcpTool, isWebFetch } from "./mcp-key";
+import { kimiDenyResponse } from "../adapters/kimi";
+
+export { MCP_TTL_MS, WEBFETCH_TTL_MS, cacheQueryOf, isMcpTool, queryOf } from "./mcp-key";
+
+function denyWith(id: string, content: string): string {
+  if (id === "claude-code" || id === "codex") {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: content } });
+  }
+  if (id === "gemini-cli") return JSON.stringify({ decision: "deny", reason: content });
+  if (id === "kimi") return kimiDenyResponse(content);
+  return "";
+}
+
+function mutateWith(id: string, input: Record<string, unknown>): string {
+  if (id === "claude-code" || id === "codex") {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: input } });
+  }
+  if (id === "gemini-cli") return JSON.stringify({ hookSpecificOutput: { tool_input: input } });
+  // Kimi has no input-mutation contract (`updatedInput` is undocumented
+  // upstream) — the exa verbosity cap stays inoperative there.
+  return "";
+}
+
+/** The doc provider a served cache-hit satisfies (`exa`/`context7`), else undefined. */
+function docSourceOf(tool: string): string | undefined {
+  if (/exa/i.test(tool)) return "exa";
+  if (/context7/i.test(tool)) return "context7";
+  return undefined;
+}
+
+/**
+ * Wrap a cache hit's body in the harness-facing `CACHE HIT` notice — parity with
+ * `webfetch-cache-lookup.py` / `mcp-cache-lookup.py` (KB = body chars/1024 + 1,
+ * age hours = ageMs/3_600_000, both floored).
+ */
+function cacheHitText(web: boolean, hit: CacheHit): string {
+  const kb = Math.floor(hit.body.length / 1024) + 1;
+  const hours = Math.floor(hit.ageMs / 3_600_000);
+  return web
+    ? `CACHE HIT WebFetch (~${kb}KB saved, cached ${hours}h ago):\n\n${hit.body}\n\nModify the URL or query to force a fresh fetch.`
+    : `CACHE HIT (~${kb}KB saved, cached ${hours}h ago): ${hit.body}\n\nRephrase to force a re-call.`;
+}
+
+/** A pre-event MCP interception: the native response + any doc source it satisfied. */
+export interface McpIntercept {
+  stdout: string;
+  docSource?: string;
+}
+
+/**
+ * Pre-event MCP interception: serve a fresh cache hit (deny + cached content),
+ * else cap exa verbosity (allow + mutated input), else null to allow normally.
+ * Harnesses without input-mutation/cache support fall through to null.
+ */
+export function mcpPreIntercept(id: string, tool: string, input: Record<string, unknown>, dir: string, ttlMs: number, now: number): McpIntercept | null {
+  if (!isMcpTool(tool)) return null;
+  const web = isWebFetch(tool);
+  const ttl = web ? WEBFETCH_TTL_MS : ttlMs;
+  const key = cacheQueryOf(tool, input);
+  // Exact key first; for MCP docs fall back to a substring hit (Python `rg -i -F`).
+  const hit = cacheLookupMeta(dir, tool, key, ttl, now) ?? (web ? null : cacheLookupSubstringMeta(dir, key, ttl, now));
+  if (hit) {
+    const served = denyWith(id, cacheHitText(web, hit));
+    if (served) return { stdout: served, docSource: docSourceOf(tool) };
+  }
+  const capped = capVerbosity(tool, input);
+  if (capped) {
+    const mutated = mutateWith(id, capped);
+    if (mutated) return { stdout: mutated };
+  }
+  return null;
+}
+
+/**
+ * Post-event: persist the MCP/WebFetch response (extracted to markdown). MCP docs
+ * go through {@link mcpCacheWrite} (compact + Jaccard-dedup + `index.json`);
+ * WebFetch uses {@link webfetchCacheWrite} (compact, exact key, no index).
+ * @param now - Current epoch ms (timestamp source; defaults to `Date.now()`).
+ */
+export function mcpPostStore(tool: string, input: Record<string, unknown>, response: unknown, dir: string, now: number = Date.now()): void {
+  if (!isMcpTool(tool)) return;
+  const text = extractText(response);
+  const key = cacheQueryOf(tool, input);
+  if (isWebFetch(tool)) webfetchCacheWrite(dir, tool, key, text, now);
+  else mcpCacheWrite(dir, tool, key, text, now);
+}