@fusengine/harness 0.1.91 → 0.1.92

package/src/adapters/cursor/native-schemas.ts

@@ -0,0 +1,161 @@
+/**
+ * @module native-schemas
+ * Per-event field validators for Cursor's documented native stdout contract.
+ * Extracted from native-response.ts to keep that module focused on the
+ * passthrough decision logic (SOLID file-size split, not a plafond workaround).
+ *
+ * Field lists are binary-verified against Cursor 3.18.25 (agent-cli
+ * `190.index.js` / `workbench.desktop.main.js`, validators `R`/`Ded`) and
+ * match the published hooks documentation.
+ */
+
+/** A single-field runtime type check used to build a {@link NativeSchema}. */
+export type FieldValidator = (value: unknown) => boolean;
+
+/** The exact field set (and per-field validator) Cursor reads for one event. */
+export interface NativeSchema {
+  fields: Readonly<Record<string, FieldValidator>>;
+  required?: readonly string[];
+}
+
+const stringValue: FieldValidator = (value) => typeof value === "string";
+const booleanValue: FieldValidator = (value) => typeof value === "boolean";
+
+/** A plain `{}`-literal or `Object.create(null)` object — never a class instance or array. */
+export const plainRecord = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  try {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+  } catch {
+    return false;
+  }
+};
+
+type JsonFrame = { value: unknown; leave?: false } | { value: object; leave: true };
+
+function jsonChildren(value: object): unknown[] | null {
+  const keys = Reflect.ownKeys(value);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Array.isArray(value)) {
+    if (Object.getPrototypeOf(value) !== Array.prototype) return null;
+    const length = descriptors.length;
+    if (!length || !("value" in length) || !Number.isSafeInteger(length.value) || length.value < 0) return null;
+    if (keys.length !== length.value + 1 || keys.some((key) => typeof key === "symbol")) return null;
+    const children: unknown[] = [];
+    for (let index = 0; index < length.value; index += 1) {
+      const descriptor = descriptors[String(index)];
+      if (!descriptor?.enumerable || !("value" in descriptor)) return null;
+      children.push(descriptor.value);
+    }
+    return children;
+  }
+  if (!plainRecord(value) || keys.some((key) => typeof key === "symbol")) return null;
+  const children: unknown[] = [];
+  for (const key of keys) {
+    const descriptor = descriptors[key as string];
+    if (!descriptor?.enumerable || !("value" in descriptor)) return null;
+    children.push(descriptor.value);
+  }
+  return children;
+}
+
+function jsonValue(root: unknown): boolean {
+  const active = new WeakSet<object>();
+  const stack: JsonFrame[] = [{ value: root }];
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    if (frame.leave) {
+      active.delete(frame.value);
+      continue;
+    }
+    const { value } = frame;
+    if (value === null || typeof value === "string" || typeof value === "boolean") continue;
+    if (typeof value === "number") {
+      if (!Number.isFinite(value)) return false;
+      continue;
+    }
+    if (typeof value !== "object" || active.has(value)) return false;
+    let children: unknown[] | null;
+    try {
+      children = jsonChildren(value);
+    } catch {
+      return false;
+    }
+    if (!children) return false;
+    active.add(value);
+    stack.push({ value, leave: true });
+    for (let index = children.length - 1; index >= 0; index -= 1) stack.push({ value: children[index] });
+  }
+  return true;
+}
+
+/** A JSON-safe plain object (no cycles, no non-finite numbers, no exotic prototypes). */
+export const recordValue: FieldValidator = (value) => plainRecord(value) && jsonValue(value);
+const stringRecord: FieldValidator = (value) => {
+  if (!recordValue(value)) return false;
+  try {
+    return Object.values(Object.getOwnPropertyDescriptors(value as object))
+      .every((descriptor) => "value" in descriptor && typeof descriptor.value === "string");
+  } catch {
+    return false;
+  }
+};
+const stringArray: FieldValidator = (value) => Array.isArray(value) && value.every(stringValue);
+const permission = (...values: string[]): FieldValidator => (value) => typeof value === "string" && values.includes(value);
+
+const EMPTY: NativeSchema = { fields: {} };
+const FOLLOWUP: NativeSchema = { fields: { followup_message: stringValue } };
+const PERMISSION_ASK: NativeSchema = {
+  fields: { permission: permission("allow", "deny", "ask"), user_message: stringValue, agent_message: stringValue },
+  required: ["permission"],
+};
+
+const PRE_TOOL_USE: NativeSchema = {
+  fields: {
+    permission: permission("allow", "deny", "ask"),
+    user_message: stringValue,
+    agent_message: stringValue,
+    updated_input: recordValue,
+    additional_context: stringValue,
+  },
+  required: ["permission"],
+};
+
+/**
+ * Exact native stdout field set Cursor 3.18.25 reads per hook event.
+ * Nothing beyond this list is invented: any additional key on a candidate
+ * value fails {@link isNativeCursorResponse} in native-response.ts.
+ */
+export const NATIVE_SCHEMAS: Readonly<Record<string, NativeSchema>> = {
+  sessionStart: {
+    fields: { env: stringRecord, additional_context: stringValue, continue: booleanValue, user_message: stringValue },
+  },
+  sessionEnd: EMPTY,
+  beforeSubmitPrompt: {
+    fields: { continue: booleanValue, user_message: stringValue, additional_context: stringValue },
+    required: ["continue"],
+  },
+  preCompact: { fields: { user_message: stringValue } },
+  subagentStart: {
+    fields: { permission: permission("allow", "deny"), user_message: stringValue }, required: ["permission"],
+  },
+  subagentStop: FOLLOWUP,
+  preToolUse: PRE_TOOL_USE,
+  postToolUse: { fields: { updated_mcp_tool_output: recordValue, additional_context: stringValue } },
+  postToolUseFailure: { fields: { additional_context: stringValue } },
+  beforeShellExecution: PERMISSION_ASK,
+  afterShellExecution: EMPTY,
+  beforeMCPExecution: PERMISSION_ASK,
+  afterMCPExecution: EMPTY,
+  beforeReadFile: {
+    fields: { permission: permission("allow", "deny"), user_message: stringValue }, required: ["permission"],
+  },
+  afterFileEdit: EMPTY,
+  beforeTabFileRead: { fields: { permission: permission("allow", "deny") }, required: ["permission"] },
+  afterTabFileEdit: EMPTY,
+  afterAgentResponse: EMPTY,
+  afterAgentThought: EMPTY,
+  stop: FOLLOWUP,
+  workspaceOpen: { fields: { pluginPaths: stringArray } },
+};

package/src/adapters/cursor/normalize.ts

@@ -49,12 +49,77 @@ function sanitizedCursorInput(input: Record<string, unknown>): Record<string, un
   return safe;
 }
 
+/**
+ * Closed table: Cursor's `MCP:<tool>` tool_name form on preToolUse/
+ * postToolUse/postToolUseFailure LOSES the MCP server name (ground truth:
+ * Cursor CLI 3.18.25 + official docs — only beforeMCPExecution/
+ * afterMCPExecution carry `mcp_server_name`). This reconstructs the real
+ * server for the closed set of tool names this repo's gates actually depend
+ * on (GATED_TOOLS in doc-cache-gate.ts, CONTEXT7_SOURCE, RESEARCH_TOOLS,
+ * SHOT_TOOLS, gemini-mcp-gate, shadcn-skill-gate) — same closed-table
+ * philosophy as `mcp-tool-name.ts`'s Codex aliasing, never a blanket
+ * reversal. Coordinator decision: a tool name OUTSIDE this table (server
+ * genuinely unrecoverable, and no safe placeholder) is left as Cursor's raw
+ * `MCP:<tool>` string — `test/cursor-followup-normalize.test.ts` pins this
+ * as the committed contract ("commandless MCP tools keep their name"), so a
+ * fabricated `mcp__cursor__<tool>` placeholder is never introduced for the
+ * unknown case.
+ */
+const CURSOR_MCP_TOOL_SERVERS: Readonly<Record<string, string>> = Object.assign(Object.create(null), {
+  "query-docs": "context7",
+  "resolve-library-id": "context7",
+  web_search_exa: "exa",
+  get_code_context_exa: "exa",
+  deep_researcher_start: "exa",
+  deep_researcher_check: "exa",
+  create_frontend: "gemini-design",
+  modify_frontend: "gemini-design",
+  snippet_frontend: "gemini-design",
+  search_items_in_registries: "shadcn",
+  view_items_in_registries: "shadcn",
+  get_item_examples_from_registries: "shadcn",
+  get_add_command_for_items: "shadcn",
+  get_audit_checklist: "shadcn",
+});
+
+/**
+ * The real MCP server for a bare Cursor tool name (the part after `MCP:`),
+ * or `undefined` when it isn't in the closed table. fuse-browser is inferred
+ * from the `browser_*` prefix — every fuse-browser tool is named that way
+ * and no other server in this ecosystem uses it — the remaining,
+ * non-distinctive tool names go through {@link CURSOR_MCP_TOOL_SERVERS}.
+ * NO placeholder fallback (coordinator decision, see {@link CURSOR_MCP_TOOL_SERVERS}):
+ * an unknown tool name means the server is genuinely unrecoverable, so the
+ * caller leaves the raw `MCP:<tool>` string untouched instead of fabricating one.
+ */
+function cursorMcpServer(bareTool: string): string | undefined {
+  if (bareTool.startsWith("browser_")) return "fuse-browser";
+  return CURSOR_MCP_TOOL_SERVERS[bareTool];
+}
+
+/**
+ * Canonicalize Cursor's `MCP:<tool>` tool_name (preToolUse/postToolUse/
+ * postToolUseFailure) into the shared `mcp__<server>__<tool>` shape every
+ * other harness/gate expects. Returns `undefined` — meaning "leave the raw
+ * `MCP:<tool>` string as-is" — both when `tool` isn't the `MCP:` form and
+ * when the bare tool name is outside the closed {@link CURSOR_MCP_TOOL_SERVERS}
+ * table (server unrecoverable, no placeholder fabricated).
+ */
+function cursorBareMcpToolName(tool: string | undefined): string | undefined {
+  if (!tool || !tool.startsWith("MCP:")) return undefined;
+  const bare = tool.slice(4);
+  const server = cursorMcpServer(bare);
+  return server ? `mcp__${server}__${bare}` : undefined;
+}
+
 function cursorToolName(raw: Record<string, unknown>, event: string, tool: string | undefined, hasCommand: boolean): string {
   if (hasCommand) return "Bash";
   const server = str(raw.mcp_server_name)?.trim().replace(/[^A-Za-z0-9_-]+/g, "_");
   if (/^(before|after)MCPExecution$/i.test(event) && server && tool && !tool.startsWith("mcp__")) {
     return `mcp__${server}__${tool}`;
   }
+  const bareMcp = cursorBareMcpToolName(tool);
+  if (bareMcp) return bareMcp;
   if (tool === "Write") return "Edit";
   return tool ?? "";
 }

package/src/adapters/cursor/plugin-root.ts

@@ -0,0 +1,103 @@
+/**
+ * Cursor plugin-root resolution — independent from the rules-plugin probing
+ * in `../../runtime/lifecycle/rules-root.ts`. Ground truth (Cursor 3.18.25
+ * binary + cursor.com/docs/hooks): `CURSOR_PLUGIN_ROOT` / `CLAUDE_PLUGIN_ROOT`
+ * (both equal to the plugin install dir) are injected ONLY into
+ * plugin-declared hook processes — never user (`~/.cursor/hooks.json`),
+ * project (`.cursor/hooks.json`), or enterprise hooks. A plugin hook's cwd is
+ * the plugin install dir, EXCEPT for `stop`/`subagentStop`, where it is the
+ * workspace root — callers must pass the right `cwd` for the event they are
+ * handling. Precedence: (1) `CURSOR_PLUGIN_ROOT` env, (2) `CLAUDE_PLUGIN_ROOT`
+ * env, (3) `cwd` when it carries a Cursor plugin marker
+ * (`.cursor-plugin/plugin.json`, `plugin.json` + `hooks/hooks.json`, or a
+ * bare `hooks/hooks.json` — matches installed-plugin layouts under
+ * `~/.cursor/plugins/cache/**` and `~/.cursor/plugins/local/<name>/`), (4)
+ * `none`. Cursor refuses symlinked config paths itself; we do not share that
+ * constraint, so every resolved candidate is realpath-followed instead.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+/** How the resolved Cursor plugin root was determined. */
+export type CursorPluginRootSource =
+  | "env:CURSOR_PLUGIN_ROOT"
+  | "env:CLAUDE_PLUGIN_ROOT"
+  | "cwd:plugin-marker"
+  | "none";
+
+/** Result of resolving the Cursor plugin install root. */
+export interface CursorPluginRootResult {
+  /** Realpath-resolved plugin install directory, or `null` when unproven. */
+  root: string | null;
+  /** Which precedence step produced `root`. */
+  source: CursorPluginRootSource;
+  /** One diagnostic entry per candidate that was examined and rejected. */
+  checked: string[];
+}
+
+/** Validate an env candidate: non-empty, NUL-free, absolute, existing dir. */
+function validateEnvCandidate(label: string, value: string | undefined, checked: string[]): string | null {
+  if (value === undefined || value === "") {
+    checked.push(`${label}: unset`);
+    return null;
+  }
+  if (value.includes("\0")) {
+    checked.push(`${label}: invalid (contains NUL): "${value}"`);
+    return null;
+  }
+  if (!isAbsolute(value)) {
+    checked.push(`${label}: invalid (not absolute): "${value}"`);
+    return null;
+  }
+  try {
+    if (!statSync(value).isDirectory()) {
+      checked.push(`${label}: invalid (not a directory): "${value}"`);
+      return null;
+    }
+  } catch {
+    checked.push(`${label}: invalid (no such directory): "${value}"`);
+    return null;
+  }
+  try {
+    return realpathSync.native(value);
+  } catch {
+    checked.push(`${label}: invalid (realpath failed): "${value}"`);
+    return null;
+  }
+}
+
+/** True when `dir` carries a recognized Cursor plugin install marker. */
+function hasPluginMarker(dir: string): boolean {
+  if (existsSync(join(dir, ".cursor-plugin", "plugin.json"))) return true;
+  if (existsSync(join(dir, "plugin.json")) && existsSync(join(dir, "hooks", "hooks.json"))) return true;
+  return existsSync(join(dir, "hooks", "hooks.json"));
+}
+
+/**
+ * Resolve the Cursor plugin install root a plugin-declared hook runs from.
+ * @param env - Environment (defaults to `process.env`).
+ * @param cwd - The hook process's cwd for the current event (plugin root for
+ *   most events, workspace root for `stop`/`subagentStop` — caller's choice).
+ * @returns The resolved root, its source, and every rejected candidate.
+ */
+export function resolveCursorPluginRoot(
+  env: Record<string, string | undefined>,
+  cwd: string,
+): CursorPluginRootResult {
+  const checked: string[] = [];
+  const fromCursor = validateEnvCandidate("env:CURSOR_PLUGIN_ROOT", env.CURSOR_PLUGIN_ROOT, checked);
+  if (fromCursor) return { root: fromCursor, source: "env:CURSOR_PLUGIN_ROOT", checked };
+  const fromClaude = validateEnvCandidate("env:CLAUDE_PLUGIN_ROOT", env.CLAUDE_PLUGIN_ROOT, checked);
+  if (fromClaude) return { root: fromClaude, source: "env:CLAUDE_PLUGIN_ROOT", checked };
+  if (hasPluginMarker(cwd)) {
+    let resolved = cwd;
+    try {
+      resolved = realpathSync.native(cwd);
+    } catch {
+      /* keep raw cwd when realpath fails (e.g. already-canonical or unreadable parent) */
+    }
+    return { root: resolved, source: "cwd:plugin-marker", checked };
+  }
+  checked.push(`cwd:"${cwd}": no plugin marker found`);
+  return { root: null, source: "none", checked };
+}

package/src/adapters/cursor/respond.ts

@@ -1,6 +1,9 @@
 import { formatPrompt, type Prompt } from "../../prompt/types";
 import { cursorEventContract } from "./events";
 import { parseNativeCursorStdout } from "./native-response";
+import { capAdditionalContext } from "./context-limit";
+import { capAdditionalContextWithBudget } from "./context-budget";
+import type { CursorBudgetContext } from "./interfaces/context-budget";
 
 const AGENT_MESSAGE_EVENTS = new Set([
   "preToolUse",
@@ -30,39 +33,73 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Render a portable policy prompt using the native Cursor event contract. */
+/**
+ * Render a portable policy prompt using the native Cursor event contract.
+ * Switches exhaustively on {@link CursorResponseKind} — the `never` default
+ * fails to compile if a new kind is ever added without a matching case.
+ * `contract.known === false` is not tested separately: the single
+ * `UNKNOWN_EVENT` fallback in events.ts always pairs `known: false` with
+ * `response: "neutral"`, so both collapse to the same `"{}"` branch.
+ */
 export function toCursorResponse(prompt: Prompt, eventName: string): string {
   const contract = cursorEventContract(eventName);
   const message = formatPrompt(prompt);
-  if (!contract.known || contract.response === "neutral" || contract.response === "plugin-paths") return "{}";
-  if (contract.response === "post-context" || contract.response === "session-context") {
-    return JSON.stringify({ additional_context: message });
+  switch (contract.response) {
+    case "neutral":
+    case "plugin-paths":
+      return "{}";
+    case "post-context":
+    case "session-context":
+      return capAdditionalContext(JSON.stringify({ additional_context: message }));
+    case "followup":
+      return JSON.stringify({ followup_message: message });
+    case "compact-notice":
+      return JSON.stringify({ user_message: prompt.userMessage ?? message });
+    case "submit-control":
+      return JSON.stringify({ continue: prompt.kind !== "block", user_message: prompt.userMessage ?? message });
+    case "permission": {
+      if (prompt.kind === "inform") {
+        return JSON.stringify({
+          permission: "allow",
+          ...permissionMessages(eventName, prompt.userMessage, prompt.reason ? message : undefined),
+        });
+      }
+      const userMessage = prompt.kind === "ask"
+        ? `[downgraded from ask — Cursor does not enforce approval for this event]\n${message}`
+        : message;
+      return JSON.stringify({
+        permission: "deny",
+        ...permissionMessages(eventName, userMessage, userMessage),
+      });
+    }
+    default: {
+      const exhaustive: never = contract.response;
+      return exhaustive;
+    }
   }
-  if (contract.response === "followup") return JSON.stringify({ followup_message: message });
-  if (contract.response === "compact-notice") return JSON.stringify({ user_message: prompt.userMessage ?? message });
-  if (contract.response === "submit-control") {
-    return JSON.stringify({ continue: prompt.kind !== "block", user_message: prompt.userMessage ?? message });
-  }
-  if (prompt.kind === "inform") {
-    return JSON.stringify({
-      permission: "allow",
-      ...permissionMessages(eventName, prompt.userMessage, prompt.reason ? message : undefined),
-    });
-  }
-  const userMessage = prompt.kind === "ask"
-    ? `[downgraded from ask — Cursor does not enforce approval for this event]\n${message}`
-    : message;
-  return JSON.stringify({
-    permission: "deny",
-    ...permissionMessages(eventName, userMessage, userMessage),
-  });
 }
 
-/** Convert a shared lifecycle handler's output to the native Cursor envelope. */
-export function toCursorLifecycleResponse(stdout: string, eventName: string): string {
+/**
+ * Convert a shared lifecycle handler's output to the native Cursor envelope.
+ * The `neutral` and empty-`text` short circuits run before the switch (they
+ * apply identically across several {@link CursorResponseKind} values), so
+ * only the remaining 7 kinds need a case — `never` below still catches a
+ * future kind added without updating this function. This is the single
+ * point every Cursor stdout passes through exactly once (see `handle.ts`'s
+ * `handleHook`), so `budget` — when supplied — is reserved from and
+ * recorded into here, never at the inner `toCursorResponse` pre-cap (that
+ * one's output is re-capped here again on the native-passthrough branch
+ * below, so budgeting it too would double-count the same contribution).
+ * @param stdout - The shared handler's raw stdout for this hook invocation.
+ * @param eventName - Cursor's raw `hook_event_name`.
+ * @param budget - Shared `additional_context` budget context (see
+ * {@link CursorBudgetContext}); `undefined` falls back to the flat
+ * per-response 10,000-char cap, unbudgeted.
+ */
+export function toCursorLifecycleResponse(stdout: string, eventName: string, budget?: CursorBudgetContext): string {
   const contract = cursorEventContract(eventName);
   const native = parseNativeCursorStdout(stdout, eventName);
-  if (native !== null) return native;
+  if (native !== null) return capAdditionalContextWithBudget(native, budget);
   let text = stdout;
   let decision: "allow" | "deny" | "ask" | undefined;
   let userMessage = "";
@@ -97,27 +134,37 @@ export function toCursorLifecycleResponse(stdout: string, eventName: string): st
   }
   if (contract.response === "neutral") return "{}";
   if (!text) return contract.response === "permission" ? '{"permission":"allow"}' : "{}";
-  if (contract.response === "session-context" || contract.response === "post-context") {
-    return JSON.stringify({ additional_context: text });
-  }
-  if (contract.response === "permission") {
-    const permission = decision === "deny" || decision === "ask" ? "deny" : "allow";
-    const denied = permission === "deny";
-    // Cursor subagentStart can gate creation but has no model-context channel.
-    // Drop shared context and its "injected" notice on allow: preserving either
-    // would claim delivery the native event contract cannot perform.
-    if (eventName === "subagentStart" && !denied) return '{"permission":"allow"}';
-    return JSON.stringify({
-      permission,
-      ...permissionMessages(
-        eventName,
-        userMessage || (denied ? decisionMessage || agentMessage : ""),
-        agentMessage || (denied ? decisionMessage || userMessage : structured ? "" : text),
-      ),
-    });
+  switch (contract.response) {
+    case "session-context":
+    case "post-context":
+      return capAdditionalContextWithBudget(JSON.stringify({ additional_context: text }), budget);
+    case "permission": {
+      const permission = decision === "deny" || decision === "ask" ? "deny" : "allow";
+      const denied = permission === "deny";
+      // Cursor subagentStart can gate creation but has no model-context channel.
+      // Drop shared context and its "injected" notice on allow: preserving either
+      // would claim delivery the native event contract cannot perform.
+      if (eventName === "subagentStart" && !denied) return '{"permission":"allow"}';
+      return JSON.stringify({
+        permission,
+        ...permissionMessages(
+          eventName,
+          userMessage || (denied ? decisionMessage || agentMessage : ""),
+          agentMessage || (denied ? decisionMessage || userMessage : structured ? "" : text),
+        ),
+      });
+    }
+    case "followup":
+      return JSON.stringify({ followup_message: text });
+    case "compact-notice":
+      return JSON.stringify({ user_message: text });
+    case "submit-control":
+      return JSON.stringify({ continue: true, user_message: text });
+    case "plugin-paths":
+      return "{}";
+    default: {
+      const exhaustive: never = contract.response;
+      return exhaustive;
+    }
   }
-  if (contract.response === "followup") return JSON.stringify({ followup_message: text });
-  if (contract.response === "compact-notice") return JSON.stringify({ user_message: text });
-  if (contract.response === "submit-control") return JSON.stringify({ continue: true, user_message: text });
-  return "{}";
 }

package/src/runtime/handle.ts

@@ -1,10 +1,12 @@
+import { join } from "node:path";
 import { projectLayout } from "../config/layout";
 import { detectFramework } from "../policy/detect-framework";
 import { detectCreationIntent } from "../policy/creation-intent";
 import { recordBrainstormRequired } from "../tracking/session-state";
 import { withTrack } from "../tracking/store";
 import { normalizeEvent } from "./normalize";
-import { defaultStateDir, trackFile } from "./paths";
+import { defaultStateDir, projectHash, trackFile } from "./paths";
+import { fuseHarnessHome } from "./home-state";
 import { designLifecycle } from "./design-lifecycle";
 import { promptSubmitContext } from "./inject-context";
 import { lifecycleStdout } from "./lifecycle-bridge";
@@ -22,6 +24,7 @@ import { codexPromptOrigin } from "./confirm/codex-prompt-origin";
 import { cursorProjectCwd } from "../adapters/cursor/context";
 import { toCursorLifecycleResponse } from "../adapters/cursor/respond";
 import type { HandleOptions, HandleOutcome } from "./handle-types";
+import type { NormalizedEvent } from "./normalize";
 export type { HandleOptions, HandleOutcome } from "./handle-types";
 
 /** Raw Claude hook event name from a payload (empty when absent). */
@@ -29,6 +32,62 @@ function rawEventName(payload: Record<string, unknown>): string {
   return typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
 }
 
+/**
+ * `payload.tool_input` parsed into an object when it's a JSON STRING —
+ * Cursor's real wire format for `beforeMCPExecution`/`afterMCPExecution`
+ * (ground truth), unlike every other harness (and Cursor's own
+ * `preToolUse`/`postToolUse`), which always sends it as an object already.
+ * `undefined` when `tool_input` is already an object, absent, or fails to
+ * parse into one (fail-open — the caller then keeps the original value).
+ * @param payload - The raw hook payload.
+ */
+function cursorParsedToolInput(payload: Record<string, unknown>): Record<string, unknown> | undefined {
+  const raw = payload.tool_input;
+  if (typeof raw !== "string") return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `id === "cursor"` only: project the already-resolved canonical `tool_name`
+ * (`event.tool`, normalized by {@link normalizeEvent}) and `cwd` (the project
+ * root resolved via `cursorProjectCwd`, already applied to `opts.cwd`) onto a
+ * shallow payload copy — the single passage point for every downstream
+ * consumer that reads `payload.tool_name`/`payload.cwd`/`payload.tool_input`
+ * RAW instead of `event.tool`/`opts.cwd`/`event.input` (lifecycle-bridge's
+ * `failure-lesson.ts`/`agent-memory.ts`, handle-scope-async's aipilot/memory
+ * dispatchers — including `doc-cache-gate.ts`'s `libraryOf`, which never
+ * `JSON.parse`s a string `tool_input` itself — and the seo scope's
+ * `post-tool-use.ts`). `tool_input` is additionally replaced by its parsed
+ * object form via {@link cursorParsedToolInput} when Cursor sent it as a
+ * JSON string (`beforeMCPExecution`/`afterMCPExecution`). Cursor's own wire
+ * values ("Shell", `MCP:<tool>`, a bare `workspace_roots` array with no
+ * `cwd` field, a stringified `tool_input`, …) are preserved under
+ * `cursor_tool_name`/`cursor_cwd`/`cursor_tool_input` so nothing is lost.
+ * Every other harness id is untouched (returns the SAME object,
+ * byte-identical).
+ * @param payload - The raw hook payload.
+ * @param event - The already-normalized event (`event.tool` is canonical).
+ * @param cwd - The resolved project root for this invocation.
+ * @param id - Harness adapter id.
+ */
+function cursorRawPayloadProjection(payload: Record<string, unknown>, event: NormalizedEvent, cwd: string, id: string): Record<string, unknown> {
+  if (id !== "cursor") return payload;
+  const parsedToolInput = cursorParsedToolInput(payload);
+  return {
+    ...payload,
+    cursor_tool_name: payload.tool_name,
+    cursor_cwd: payload.cwd,
+    tool_name: event.tool,
+    cwd,
+    ...(parsedToolInput ? { cursor_tool_input: payload.tool_input, tool_input: parsedToolInput } : {}),
+  };
+}
+
 /**
  * The full hook handler: on a PRE event it gates the tool-use (stateless guards
  * then APEX gates from the session track) and returns the native response; on a
@@ -41,6 +100,10 @@ async function handleHookCore(id: string, payload: Record<string, unknown>, opts
     const cursorCwd = cursorProjectCwd(event.cwd, event.workspaceRoots ?? [], event.filePath, opts.cwd);
     if (cursorCwd !== opts.cwd) opts = { ...opts, cwd: cursorCwd };
   }
+  // Single passage point (see cursorRawPayloadProjection doc): every raw-payload
+  // consumer below this line gets the canonical tool_name/cwd on Cursor; every
+  // other harness id gets `payload` back untouched (byte-identical object).
+  const hookPayload = cursorRawPayloadProjection(payload, event, opts.cwd, id);
   const rawPrompt = payload.prompt;
   const userPrompt = typeof rawPrompt === "string" || Array.isArray(rawPrompt) ? promptText(rawPrompt) : undefined;
   if (id === "codex" && rawEventName(payload) === "UserPromptSubmit" && userPrompt !== undefined) {
@@ -75,11 +138,11 @@ async function handleHookCore(id: string, payload: Record<string, unknown>, opts
   if (id === "codex" && rawEventName(payload) === "SessionStart") resyncCodexAgents();
 
   // Async per-scope lifecycle (aipilot cache handlers + memory-neural Graphiti).
-  const asyncOut = await asyncScopeStdout(opts.scope, rawEventName(payload), payload, opts.cwd, opts.now, id);
+  const asyncOut = await asyncScopeStdout(opts.scope, rawEventName(payload), hookPayload, opts.cwd, opts.now, id);
   if (asyncOut !== null) return { stdout: asyncOut, exit: 0 };
 
   // Ported lifecycle/session/context hooks (SessionStart, SubagentStart/Stop, etc.).
-  const life = lifecycleStdout(payload, opts.cwd, opts.scope ?? "core", opts.now, id);
+  const life = lifecycleStdout(hookPayload, opts.cwd, opts.scope ?? "core", opts.now, id);
   if (life !== null) {
     // Claude-Code-only: attachBudgetRecap's systemMessage envelope assumes the
     // Claude adapter's stdout shape (mirrors the designLifecycle gate above).
@@ -99,18 +162,36 @@ async function handleHookCore(id: string, payload: Record<string, unknown>, opts
   }
 
   if (event.phase === "post") {
-    return handlePost({ id, payload, event, framework, mcpDir, designCacheDir, file, opts });
+    return handlePost({ id, payload: hookPayload, event, framework, mcpDir, designCacheDir, file, opts });
   }
 
-  return handlePre({ id, payload, event, framework, mcpDir, designCacheDir, file, opts });
+  return handlePre({ id, payload: hookPayload, event, framework, mcpDir, designCacheDir, file, opts });
 }
 
 /**
  * Run one hook and adapt every Cursor scope outcome at the common runtime exit.
  * Other harnesses retain the core handler's stdout and exit status unchanged.
+ * Cursor's shared `additional_context` budget context (see
+ * `../adapters/cursor/context-budget.ts`) is assembled here too — this is
+ * the single point every Cursor stdout passes through exactly once, so it's
+ * also the single point that reserves from and records into the registry.
+ * With no `session_id`/`conversation_id` at all, `sessionId` is `""` — the
+ * registry key would degenerate to one bucket shared by every session-less
+ * call on the same (cwd, event) pair, so `budget` stays `undefined` instead
+ * (falls back to the flat per-response cap in `toCursorLifecycleResponse`,
+ * with zero registry I/O). `stateDir` honors `opts.home` (test-only OS home
+ * override, see `HandleOptions`) so tests never need the real `os.homedir()`.
  */
 export async function handleHook(id: string, payload: Record<string, unknown>, opts: HandleOptions): Promise<HandleOutcome> {
   const outcome = await handleHookCore(id, payload, opts);
   if (id !== "cursor") return outcome;
-  return { ...outcome, stdout: toCursorLifecycleResponse(outcome.stdout, rawEventName(payload)) };
+  const eventName = rawEventName(payload);
+  const cursorEvent = normalizeEvent(id, payload);
+  const cwd = cursorProjectCwd(cursorEvent.cwd, cursorEvent.workspaceRoots ?? [], cursorEvent.filePath, opts.cwd);
+  const sessionId = cursorEvent.sessionId;
+  const generationId = typeof payload.generation_id === "string" && payload.generation_id ? payload.generation_id : undefined;
+  const toolUseId = typeof payload.tool_use_id === "string" && payload.tool_use_id ? payload.tool_use_id : undefined;
+  const stateDir = join(fuseHarnessHome(opts.home), "state", projectHash(cwd));
+  const budget = sessionId ? { stateDir, sessionId, event: eventName, generationId, toolUseId } : undefined;
+  return { ...outcome, stdout: toCursorLifecycleResponse(outcome.stdout, eventName, budget) };
 }