@fusengine/harness 0.1.91 → 0.1.93

package/src/adapters/cursor/context-limit.ts

@@ -0,0 +1,115 @@
+/**
+ * @module context-limit
+ * Cursor 3.18.25's `hooks-carriers` drops an `additional_context` carrier
+ * once `o.length>1e4` — but `o` is the MERGED text of every hook's
+ * `additional_context` for that event (concatenated with `"\n\n---\n\n"`
+ * before the 10,000-char check), not this harness's response in isolation.
+ * Capping our own contribution at {@link ADDITIONAL_CONTEXT_LIMIT} is
+ * therefore the LAST-RESORT guard, not the real protection: on its own it
+ * only proves OUR piece stays under 10,000, while the total across every
+ * hook plugin configured on the same event can still exceed it and get
+ * dropped wholesale — measured at ~8,400 chars on `sessionStart` from core
+ * plugins alone, close enough to the ceiling that one more plugin tips it
+ * over. The actual protection is the cross-process shared budget registry
+ * in `./context-budget.ts` (Cursor id only), which reserves a slice of the
+ * 10,000 ceiling per (session, event, generation) key BEFORE calling
+ * {@link truncateAdditionalContext} here with the reserved amount instead of
+ * the flat {@link ADDITIONAL_CONTEXT_LIMIT} — this module stays a pure,
+ * budget-agnostic primitive so it keeps working unbudgeted (its historical,
+ * still-correct behavior) wherever no budget context is available. The
+ * limit unit is UTF-16 code units (`String.prototype.length`), matching
+ * `value.length` here exactly. Only 5 events carry `additional_context`
+ * through this carrier — sessionStart, beforeSubmitPrompt, preToolUse,
+ * postToolUse, postToolUseFailure — subagentStart/subagentStop use a
+ * different, unlimited channel. "Drops silently" also only holds when no
+ * `failClosed: true` hook is declared on that step/tool: with one declared,
+ * an oversized carrier REJECTS the tool call instead of being dropped quiet.
+ */
+
+/** Cursor's hard `additional_context` character ceiling. */
+export const ADDITIONAL_CONTEXT_LIMIT = 10_000;
+
+/** Suffix appended by {@link truncateAdditionalContext} once a value is cut. */
+export const TRUNCATION_MARKER = "\n[fuse-harness] additional_context truncated to Cursor's 10000-char limit";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Truncate a string to end with {@link TRUNCATION_MARKER} once its length
+ * exceeds `limit`. Leaves shorter values untouched. Idempotent under a
+ * SHRINKING `limit` across repeated calls (e.g. an unbudgeted flat-cap pass
+ * followed by a budgeted re-cap of the same stdout — see `./respond.ts`'s
+ * `toCursorLifecycleResponse` doc): when `value` already ends with
+ * {@link TRUNCATION_MARKER}, that marker is stripped BEFORE re-slicing so the
+ * result carries exactly one marker instead of risking a duplicated/cut one.
+ * @param value - Candidate `additional_context` body.
+ * @param limit - Effective ceiling for this call (defaults to the flat
+ * {@link ADDITIONAL_CONTEXT_LIMIT}; a shared-budget caller passes a smaller,
+ * per-reservation value instead).
+ */
+export function truncateAdditionalContext(value: string, limit: number = ADDITIONAL_CONTEXT_LIMIT): string {
+  const alreadyMarked = value.endsWith(TRUNCATION_MARKER);
+  if (!alreadyMarked && value.length <= limit) return value;
+  if (limit <= TRUNCATION_MARKER.length) return TRUNCATION_MARKER.slice(0, Math.max(0, limit));
+  const base = alreadyMarked ? value.slice(0, value.length - TRUNCATION_MARKER.length) : value;
+  return base.slice(0, limit - TRUNCATION_MARKER.length) + TRUNCATION_MARKER;
+}
+
+/**
+ * Length of a Cursor stdout JSON's `additional_context` string field, or 0
+ * when the stdout is not JSON, has no such field, or that field isn't a
+ * string.
+ * @param stdout - A native Cursor JSON stdout candidate.
+ */
+export function additionalContextLength(stdout: string): number {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return 0;
+  }
+  return isPlainObject(parsed) && typeof parsed.additional_context === "string" ? parsed.additional_context.length : 0;
+}
+
+/**
+ * Re-serialize a Cursor stdout string with its `additional_context` field
+ * dropped entirely — used once the shared budget has no room left even for
+ * a truncated marker. Returns the input byte-for-byte unchanged when it is
+ * not JSON or has no string `additional_context` field.
+ * @param stdout - A native Cursor JSON stdout candidate.
+ */
+export function omitAdditionalContext(stdout: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return stdout;
+  }
+  if (!isPlainObject(parsed) || typeof parsed.additional_context !== "string") return stdout;
+  const { additional_context: _omitted, ...rest } = parsed;
+  return JSON.stringify(rest);
+}
+
+/**
+ * Re-serialize a Cursor stdout string with its `additional_context` field
+ * capped at `limit` characters. Returns the input byte-for-byte unchanged
+ * when it is not JSON, has no string `additional_context` field, or that
+ * field is already within the limit — so callers can wrap every return path
+ * unconditionally.
+ * @param stdout - A native Cursor JSON stdout candidate.
+ * @param limit - Effective ceiling for this call (see {@link truncateAdditionalContext}).
+ */
+export function capAdditionalContext(stdout: string, limit: number = ADDITIONAL_CONTEXT_LIMIT): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return stdout;
+  }
+  if (!isPlainObject(parsed) || typeof parsed.additional_context !== "string") return stdout;
+  const truncated = truncateAdditionalContext(parsed.additional_context, limit);
+  if (truncated === parsed.additional_context) return stdout;
+  return JSON.stringify({ ...parsed, additional_context: truncated });
+}

package/src/adapters/cursor/context.ts

@@ -30,17 +30,36 @@ function contains(root: string, filePath: string): boolean {
   return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
 
-/** Select Cursor's project scope without replacing a valid payload cwd. */
+/**
+ * Select Cursor's project scope without replacing a valid payload cwd. Order:
+ * payload `cwd` -> longest workspace root containing `filePath` ->
+ * `workspaceRoots[0]` -> `CURSOR_PROJECT_DIR` env -> `CLAUDE_PROJECT_DIR` env
+ * -> `fallback`. Both env vars are validated the same way as any other Cursor
+ * path (`cursorAbsolutePath`: absolute, NUL-free, realpath-resolved), so an
+ * unset or malformed value is silently skipped rather than trusted.
+ * @param cwd - Cursor payload `cwd`, when present.
+ * @param workspaceRoots - Validated, deduped Cursor `workspace_roots`.
+ * @param filePath - The file the current event targets, when present.
+ * @param fallback - Caller-supplied last resort (never `process.cwd()`).
+ * @param env - Environment (defaults to `process.env`).
+ * @returns The resolved project root.
+ */
 export function cursorProjectCwd(
   cwd: string | undefined,
   workspaceRoots: readonly string[],
   filePath: string | undefined,
   fallback: string,
+  env: Record<string, string | undefined> = process.env,
 ): string {
   if (cwd) return cwd;
   if (filePath) {
     const matches = workspaceRoots.filter((root) => contains(root, filePath));
     if (matches.length > 0) return matches.sort((a, b) => b.length - a.length)[0]!;
   }
-  return workspaceRoots[0] ?? fallback;
+  if (workspaceRoots[0]) return workspaceRoots[0];
+  const fromCursorEnv = cursorAbsolutePath(env.CURSOR_PROJECT_DIR);
+  if (fromCursorEnv) return fromCursorEnv;
+  const fromClaudeEnv = cursorAbsolutePath(env.CLAUDE_PROJECT_DIR);
+  if (fromClaudeEnv) return fromClaudeEnv;
+  return fallback;
 }

package/src/adapters/cursor/interfaces/context-budget.ts

@@ -0,0 +1,25 @@
+/**
+ * Reservation key + registry location for one hook invocation's slice of
+ * Cursor's shared, cross-process `additional_context` budget (see
+ * `../context-budget.ts`). `undefined` at a call site means "no shared
+ * budget available" — callers then fall back to the flat per-response cap.
+ */
+export interface CursorBudgetContext {
+  /** Project state directory the registry file lives under (see `defaultStateDir`). */
+  stateDir: string;
+  /** Cursor `session_id` (its `conversation_id`). */
+  sessionId: string;
+  /** Raw Cursor `hook_event_name` (e.g. `"sessionStart"`). */
+  event: string;
+  /** Cursor `generation_id`; absent on `sessionStart`/`workspaceOpen`. */
+  generationId?: string;
+  /**
+   * Cursor `tool_use_id`; present on preToolUse/postToolUse/postToolUseFailure
+   * — Cursor merges `additional_context` PER TOOL CALL for these events, not
+   * once per (session, event, generation), so this must join the key or
+   * concurrent tool calls in the same generation would wrongly share one slice.
+   */
+  toolUseId?: string;
+  /** Test seam: injectable clock (defaults to `Date.now()`). */
+  now?: number;
+}

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

@@ -1,132 +1,13 @@
-type FieldValidator = (value: unknown) => boolean;
-
-interface NativeSchema {
-  fields: Readonly<Record<string, FieldValidator>>;
-  required?: readonly string[];
-}
-
-const stringValue: FieldValidator = (value) => typeof value === "string";
-const booleanValue: FieldValidator = (value) => typeof value === "boolean";
-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;
-}
-
-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 NATIVE_SCHEMAS = {
-  sessionStart: {
-    fields: { env: stringRecord, additional_context: stringValue, continue: booleanValue, user_message: stringValue },
-  },
-  sessionEnd: EMPTY,
-  beforeSubmitPrompt: { fields: { continue: booleanValue, user_message: stringValue }, required: ["continue"] },
-  preCompact: { fields: { user_message: stringValue } },
-  subagentStart: {
-    fields: { permission: permission("allow", "deny"), user_message: stringValue }, required: ["permission"],
-  },
-  subagentStop: FOLLOWUP,
-  preToolUse: {
-    fields: { ...PERMISSION_ASK.fields, updated_input: recordValue }, required: ["permission"],
-  },
-  postToolUse: { fields: { updated_mcp_tool_output: recordValue, additional_context: stringValue } },
-  postToolUseFailure: EMPTY,
-  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 } },
-} as const satisfies Record<string, NativeSchema>;
-
+import { NATIVE_SCHEMAS, recordValue, type NativeSchema } from "./native-schemas";
+
+/**
+ * Check that every enumerable own key of `value` is a documented field for
+ * `eventName` and passes its validator, and that every required field is
+ * present. Rejects prototype-polluted or exotic-shaped candidates via
+ * {@link recordValue}.
+ * @param value - Parsed JSON candidate.
+ * @param eventName - The Cursor hook event the candidate would answer.
+ */
 function isNativeCursorResponse(value: unknown, eventName: string): boolean {
   try {
     if (!recordValue(value)) return false;

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 };
+}