@stigmer/runner 3.0.2 → 3.0.4

package/src/activities/execute-cursor/__tests__/hook-script.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Behavior tests for the generated preToolUse bash hook.
+ *
+ * These run the ACTUAL bash script the runner writes into the workspace, feeding
+ * it the REAL hook-input shape captured from @cursor/sdk (PascalCase
+ * `tool_name`; `file_path`/`command` in `tool_input`). They are the strongest
+ * guard against the regression this work fixes: a gated built-in must be denied,
+ * its denial must be recorded with a token byte-identical to the runner's
+ * grantToken, and an exact-resource grant must allow only that resource.
+ *
+ * Skipped automatically where bash is unavailable.
+ */
+
+import { describe, it, expect, beforeAll, afterEach } from "vitest";
+import { execFileSync, execSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { generateHookScript } from "../hook-script.js";
+import { buildApprovalState, grantToken, toolIdentity, type ApprovalGrant } from "../approval-state.js";
+import type { McpToolPolicyEntry } from "../approval-state.js";
+
+let hasBash = false;
+try {
+  execSync("bash -c 'exit 0'", { stdio: "ignore" });
+  hasBash = true;
+} catch {
+  hasBash = false;
+}
+
+const d = hasBash ? describe : describe.skip;
+
+const tempDirs: string[] = [];
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+interface Harness {
+  decide(input: object): { permission: string; raw: string };
+  ledger(): Array<{ toolName: string; token: string }>;
+  resetLedger(): void;
+}
+
+function setup(opts: {
+  autoApproveAll?: boolean;
+  grants?: ApprovalGrant[];
+  mcpPolicies?: Record<string, McpToolPolicyEntry>;
+  noStateFile?: boolean;
+}): Harness {
+  const ws = mkdtempSync(join(tmpdir(), "hook-script-"));
+  tempDirs.push(ws);
+  const dir = join(ws, ".cursor", "hooks");
+  mkdirSync(dir, { recursive: true });
+  const statePath = join(dir, "state.json");
+  const ledgerPath = join(dir, "denials.jsonl");
+  const scriptPath = join(dir, "hook.sh");
+  writeFileSync(scriptPath, generateHookScript(statePath, ledgerPath), "utf-8");
+
+  if (!opts.noStateFile) {
+    const policies = new Map(
+      Object.entries(opts.mcpPolicies ?? {}).map(([name, p]) => [
+        `srv/${name}`,
+        { toolName: name, mcpServerSlug: "srv", requiresApproval: p.requiresApproval, approvalMessage: p.message ?? "" },
+      ]),
+    );
+    const state = buildApprovalState(policies, opts.autoApproveAll ?? false, opts.grants);
+    writeFileSync(statePath, JSON.stringify(state), "utf-8");
+  }
+
+  return {
+    decide(input: object) {
+      const raw = execFileSync("bash", [scriptPath], { input: JSON.stringify(input) }).toString();
+      const permission = raw.includes('"permission":"deny"') ? "deny" : raw.includes('"permission":"allow"') ? "allow" : "?";
+      return { permission, raw };
+    },
+    ledger() {
+      if (!existsSync(ledgerPath)) return [];
+      return readFileSync(ledgerPath, "utf-8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+    },
+    resetLedger() {
+      writeFileSync(ledgerPath, "", "utf-8");
+    },
+  };
+}
+
+// Real hook-input shapes (PascalCase name, file_path/command in tool_input).
+const hookWrite = (filePath: string) => ({ tool_name: "Write", tool_input: { file_path: filePath, content: "x" } });
+const hookShell = (command: string) => ({ tool_name: "Shell", tool_input: { command, cwd: "/x", timeout: 30000 } });
+const hookDelete = (filePath: string) => ({ tool_name: "Delete", tool_input: { file_path: filePath } });
+const hookRead = (filePath: string) => ({ tool_name: "Read", tool_input: { file_path: filePath } });
+
+d("generated preToolUse hook", () => {
+  it("denies gated built-ins (Write/Shell/Delete) and records a category+salient token", () => {
+    const h = setup({});
+
+    for (const [input, category, salient] of [
+      [hookWrite("/x/a.txt"), "write", "/x/a.txt"],
+      [hookShell("rm -rf build"), "shell", "rm -rf build"],
+      [hookDelete("/x/b.txt"), "delete", "/x/b.txt"],
+    ] as const) {
+      h.resetLedger();
+      expect(h.decide(input).permission).toBe("deny");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      // Byte-identical to the runner's grantToken(category, salient).
+      expect(ledger[0].token).toBe(grantToken(category, salient));
+    }
+  });
+
+  it("allows read-only built-ins", () => {
+    const h = setup({});
+    expect(h.decide(hookRead("/x/a.txt")).permission).toBe("allow");
+    expect(h.ledger()).toEqual([]);
+  });
+
+  it("auto-approve-all allows even gated built-ins", () => {
+    const h = setup({ autoApproveAll: true });
+    expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("allow");
+  });
+
+  it("allows the EXACT granted resource and re-gates any other (no name-only over-grant)", () => {
+    const id = toolIdentity("edit", "", { path: "/x/a.txt" });
+    const h = setup({ grants: [{ toolName: "edit", mcpServerSlug: "", key: id.key, salient: id.salient }] });
+
+    // Same resource the user approved -> allowed on the resumed turn.
+    expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("allow");
+    // A different file is NOT covered by the grant -> still gated.
+    expect(h.decide(hookWrite("/x/OTHER.txt")).permission).toBe("deny");
+  });
+
+  it("denies require-approval MCP tools and allows them once granted (name-only)", () => {
+    const mcpPolicies = { apply_x: { requiresApproval: true, message: "Apply X" } };
+    const denyH = setup({ mcpPolicies });
+    expect(denyH.decide({ tool_name: "apply_x", tool_input: {} }).permission).toBe("deny");
+    expect(denyH.ledger()[0].token).toBe(grantToken("apply_x", ""));
+
+    const grantH = setup({
+      mcpPolicies,
+      grants: [{ toolName: "apply_x", mcpServerSlug: "srv", key: "apply_x", salient: "" }],
+    });
+    expect(grantH.decide({ tool_name: "apply_x", tool_input: {} }).permission).toBe("allow");
+  });
+
+  it("fails closed (deny) when the state file is missing", () => {
+    const h = setup({ noStateFile: true });
+    expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("deny");
+  });
+
+  // Regression: the original grep-based extraction truncated string values at
+  // the first JSON-escaped character, so a shell command containing double
+  // quotes (e.g. `printf '%s' 'x' > "file"`) produced a ledger token that never
+  // matched the runner's grantToken — the denied call stayed COMPLETED in the
+  // persisted messages and a grant for it was re-denied on reinvocation.
+  // (Observed live in TestCursorHarness_HITL_ResumedTurn_StillGated.)
+  it("records a byte-identical token for commands with quotes, escapes, and newlines", () => {
+    const commands = [
+      'printf \'%s\' \'hello\' > "/tmp/a dir/resumed-gate.txt"',
+      'echo "double \\"nested\\" quotes" && echo done',
+      "line1\nline2\twith\ttabs",
+      'unicode: caf\u00e9 \u2014 emoji \u{1F600}',
+    ];
+    for (const command of commands) {
+      const h = setup({});
+      expect(h.decide(hookShell(command)).permission).toBe("deny");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].token).toBe(grantToken("shell", command));
+    }
+  });
+
+  it("allows the exact granted shell command even when it contains quotes", () => {
+    const command = 'printf \'%s\' \'hello-resume\' > "/x/resumed-gate.txt"';
+    const id = toolIdentity("shell", "", { command });
+    const h = setup({ grants: [{ toolName: "shell", mcpServerSlug: "", key: id.key, salient: id.salient }] });
+
+    expect(h.decide(hookShell(command)).permission).toBe("allow");
+    // A different command is NOT covered by the grant -> still gated.
+    expect(h.decide(hookShell('rm -rf "/x"')).permission).toBe("deny");
+  });
+
+  it("still denies gated tools via the bash fallback when the Node binary is unavailable", () => {
+    const ws = mkdtempSync(join(tmpdir(), "hook-script-fallback-"));
+    tempDirs.push(ws);
+    const dir = join(ws, ".cursor", "hooks");
+    mkdirSync(dir, { recursive: true });
+    const statePath = join(dir, "state.json");
+    const ledgerPath = join(dir, "denials.jsonl");
+    const scriptPath = join(dir, "hook.sh");
+    // Break the baked Node path to force the grep/cut fallback.
+    const script = generateHookScript(statePath, ledgerPath)
+      .replace(`NODE_BIN="${process.execPath}"`, 'NODE_BIN="/nonexistent/node"');
+    writeFileSync(scriptPath, script, "utf-8");
+    writeFileSync(statePath, JSON.stringify(buildApprovalState(new Map(), false)), "utf-8");
+
+    const raw = execFileSync("bash", [scriptPath], {
+      input: JSON.stringify(hookWrite("/x/a.txt")),
+    }).toString();
+    expect(raw).toContain('"permission":"deny"');
+    const ledger = readFileSync(ledgerPath, "utf-8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+    expect(ledger).toHaveLength(1);
+    expect(ledger[0].token).toBe(grantToken("write", "/x/a.txt"));
+  });
+});

package/src/activities/execute-cursor/__tests__/message-translator.test.ts

@@ -617,6 +617,99 @@ describe("MessageAccumulator tool call status transitions", () => {
     });
   });
 
+  // The Cursor SDK can emit the lifecycle for one call_id more than once.
+  // Observed in production: two "running" events ~0.5s apart for a task/edit
+  // tool produced two ToolCall entries with the SAME id (a "thin" copy with no
+  // result and a "full" copy), rendering the same call two or three times in
+  // the UI. The accumulator must upsert by call_id so a call maps to exactly
+  // one ToolCall.
+  describe("tool call idempotency (one ToolCall per call_id)", () => {
+    it("duplicate running events for one call_id create a single ToolCall", () => {
+      const messages: AgentMessage[] = [];
+      const acc = new MessageAccumulator(messages);
+
+      acc.processEvent(assistantEvent("r1", "Editing a file."));
+      acc.processEvent(toolCallEvent("tc-dup", "edit", "running", "r1", { args: { path: "a.ts" } }));
+      acc.processEvent(toolCallEvent("tc-dup", "edit", "running", "r1", { args: { path: "a.ts" } }));
+
+      expect(countToolCallsWithId(messages, "tc-dup")).toBe(1);
+      expect(findToolCallById(messages, "tc-dup")!.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+    });
+
+    it("running -> completed -> running re-emit keeps a single COMPLETED ToolCall", () => {
+      const messages: AgentMessage[] = [];
+      const acc = new MessageAccumulator(messages);
+
+      acc.processEvent(assistantEvent("r1", "Running a tool."));
+      acc.processEvent(toolCallEvent("tc-1", "Shell", "running", "r1"));
+      acc.processEvent(toolCallEvent("tc-1", "Shell", "completed", "r1", { result: "OK" }));
+      // A late "running" re-emit must not regress the terminal status.
+      acc.processEvent(toolCallEvent("tc-1", "Shell", "running", "r1"));
+
+      expect(countToolCallsWithId(messages, "tc-1")).toBe(1);
+      const tc = findToolCallById(messages, "tc-1")!;
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+      expect(tc.result).toBe("OK");
+      expect(tc.completedAt).toBeTruthy();
+    });
+
+    it("thin-then-full: a result-bearing completion populates the single ToolCall created by an empty running", () => {
+      const messages: AgentMessage[] = [];
+      const acc = new MessageAccumulator(messages);
+
+      // Reproduces the production pattern: two running events, then one
+      // completion that carries the full result.
+      acc.processEvent(assistantEvent("r1", "Delegating work."));
+      acc.processEvent(toolCallEvent("tc-task", "task", "running", "r1", { result: "" }));
+      acc.processEvent(toolCallEvent("tc-task", "task", "running", "r1", { result: "" }));
+      acc.processEvent(toolCallEvent("tc-task", "task", "completed", "r1", { result: "full result blob" }));
+
+      expect(countToolCallsWithId(messages, "tc-task")).toBe(1);
+      const tc = findToolCallById(messages, "tc-task")!;
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+      expect(tc.result).toBe("full result blob");
+    });
+
+    it("a result-less re-emit after completion does not wipe the captured result", () => {
+      const messages: AgentMessage[] = [];
+      const acc = new MessageAccumulator(messages);
+
+      acc.processEvent(assistantEvent("r1", "Running a tool."));
+      acc.processEvent(toolCallEvent("tc-1", "read", "running", "r1"));
+      acc.processEvent(toolCallEvent("tc-1", "read", "completed", "r1", { result: "file contents" }));
+      acc.processEvent(toolCallEvent("tc-1", "read", "completed", "r1", { result: "" }));
+
+      expect(countToolCallsWithId(messages, "tc-1")).toBe(1);
+      expect(findToolCallById(messages, "tc-1")!.result).toBe("file contents");
+    });
+
+    it("duplicate task running events yield one task ToolCall and one sub-agent (production repro)", () => {
+      const messages: AgentMessage[] = [];
+      const acc = new MessageAccumulator(messages);
+
+      // Mirror the ExecuteCursor stream loop: every task tool_call event is fed
+      // to both processEvent() (tool call) and trackSubAgentExecution().
+      acc.processEvent(assistantEvent("r1", "I'll explore the repo."));
+      const args = { subagentType: { kind: "explore" }, description: "Explore repo structure and docs", prompt: "Go" };
+
+      const run1 = toolCallEvent("tc-explore", "task", "running", "r1", { args, result: "" });
+      acc.processEvent(run1);
+      acc.trackSubAgentExecution(run1);
+
+      const run2 = toolCallEvent("tc-explore", "task", "running", "r1", { args, result: "" });
+      acc.processEvent(run2);
+      acc.trackSubAgentExecution(run2);
+
+      const done = toolCallEvent("tc-explore", "task", "completed", "r1", { result: "explored" });
+      acc.processEvent(done);
+      acc.trackSubAgentExecution(done);
+
+      expect(countToolCallsWithId(messages, "tc-explore")).toBe(1);
+      expect(acc.subAgentExecutions).toHaveLength(1);
+      expect(acc.subAgentExecutions[0].id).toBe("tc-explore");
+    });
+  });
+
   describe("cancelInProgressSubAgentProtos standalone", () => {
     it("cancels IN_PROGRESS/PENDING protos in place and reports whether anything changed", () => {
       const running = create(SubAgentExecutionSchema, {

package/src/activities/execute-cursor/__tests__/session-lifecycle.test.ts

@@ -7,12 +7,20 @@
  * collide. These invariants are correctness-critical, hence the explicit tests.
  */
 
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
 import { mkdtempSync, rmSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { resolvePlatformOptions } from "../session-lifecycle.js";
+vi.mock("@cursor/sdk", () => ({
+  Agent: {
+    create: vi.fn(async () => ({ agentId: "agent-created" })),
+    resume: vi.fn(async () => ({ agentId: "agent-resumed" })),
+  },
+}));
+
+import { Agent } from "@cursor/sdk";
+import { resolvePlatformOptions, createAgent, resumeAgent } from "../session-lifecycle.js";
 
 const tempRoots: string[] = [];
 
@@ -63,3 +71,66 @@ describe("resolvePlatformOptions", () => {
     expect(() => resolvePlatformOptions("ses-123", "")).toThrow(/workspaceRootDir is required/);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Workspace binding across create/resume
+//
+// Regression: Agent.resume() does not persist local.cwd. When resumeAgent()
+// omitted it, the SDK fell back to process.cwd() — re-rooting the resumed
+// agent in the runner's own working directory and loading the "project"
+// setting source (the .cursor/hooks.json carrying the HITL approval hook)
+// from that wrong directory. Result: on every resumed turn, file edits and
+// shell commands ran unguarded with no approval card (observed in production
+// execution aex_01ktr5na07f5xtmn0dz3mfjtdp).
+// ---------------------------------------------------------------------------
+
+describe("workspace binding on create/resume", () => {
+  const baseOptions = {
+    apiKey: "key",
+    sessionId: "ses-cwd-test",
+    model: "gpt-test",
+  };
+
+  it("createAgent passes the single workspace dir as local.cwd", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    await createAgent({
+      ...baseOptions,
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+
+    const callOptions = vi.mocked(Agent.create).mock.calls.at(-1)![0] as any;
+    expect(callOptions.local.cwd).toBe("/work/repo-a");
+    expect(callOptions.local.settingSources).toContain("project");
+  });
+
+  it("resumeAgent re-supplies local.cwd (not persisted by Agent.resume)", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    await resumeAgent({
+      ...baseOptions,
+      agentId: "agent-123",
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+
+    const [agentId, callOptions] = vi.mocked(Agent.resume).mock.calls.at(-1)! as [string, any];
+    expect(agentId).toBe("agent-123");
+    // The load-bearing assertion: without cwd the SDK re-roots the agent at
+    // process.cwd() and the project HITL hook never loads on resumed turns.
+    expect(callOptions.local.cwd).toBe("/work/repo-a");
+    expect(callOptions.local.settingSources).toContain("project");
+  });
+
+  it("resumeAgent passes multiple workspace dirs as an array cwd", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    await resumeAgent({
+      ...baseOptions,
+      agentId: "agent-456",
+      workspaceDirs: ["/work/repo-a", "/work/repo-b"],
+      workspaceRootDir,
+    });
+
+    const callOptions = vi.mocked(Agent.resume).mock.calls.at(-1)![1] as any;
+    expect(callOptions.local.cwd).toEqual(["/work/repo-a", "/work/repo-b"]);
+  });
+});

package/src/activities/execute-cursor/approval-policy.ts

@@ -18,7 +18,9 @@
 
 import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import type { ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import { classifyTool } from "../../shared/tool-kind.js";
 
 /**
  * A single tool's merged approval decision after evaluating all policy layers.
@@ -31,61 +33,141 @@ export interface MergedToolPolicy {
 }
 
 /**
- * Built-in (non-MCP) Cursor tools that mutate the workspace or execute
- * commands. These require approval when auto_approve_all is false, mirroring
- * the native harness's DANGEROUS_PLATFORM_TOOLS (write/edit/create/delete/
- * execute/shell). Each value is an approval-message template resolved against
- * the tool args (see resolveApprovalMessage); its placeholder names the same
- * field the grant matcher keys on (path/command/target_notebook).
+ * Built-in Cursor tools the preToolUse hook gates, named as the hook receives
+ * them.
+ *
+ * Critical: the Cursor preToolUse hook and the SDK event stream use DIFFERENT
+ * tool taxonomies for the same operation. The hook's `tool_name` is PascalCase
+ * (`Write` for any file create/edit, `Shell`, `Delete`); the stream's
+ * `event.name` is lowercase (`edit`, `shell`, `delete`). This set is the HOOK
+ * taxonomy because it is consulted only to build the hook's gated set and its
+ * name->category mapping. Cross-layer correlation never compares these raw
+ * names — it uses {@link approvalCategory} (see below).
  */
-const BUILT_IN_GATED = new Map<string, string>([
-  ["Write", "Write file: {{args.path}}"],
-  ["StrReplace", "Edit file: {{args.path}}"],
-  ["EditNotebook", "Edit notebook: {{args.target_notebook}}"],
-  ["Shell", "Run command: {{args.command}}"],
-  ["Delete", "Delete: {{args.path}}"],
+const BUILT_IN_GATED: ReadonlySet<string> = new Set([
+  "Write",
+  "StrReplace",
+  "EditNotebook",
+  "Shell",
+  "Delete",
 ]);
 
+/**
+ * Canonical approval category for a gated tool, derived from EITHER taxonomy's
+ * name via the shared {@link classifyTool}.
+ *
+ * The hook (`Write`/`Shell`/`Delete`) and the stream (`edit`/`shell`/`delete`)
+ * name the same operation differently, so neither raw name is a stable
+ * cross-layer identity. The category collapses both onto one value so the denial
+ * ledger (recorded by the hook) correlates to the streamed tool call (read by
+ * the runner) and so an approval grant matches the agent's re-attempt on
+ * reinvocation regardless of which taxonomy named it. `FILE_WRITE` and
+ * `FILE_EDIT` both map to `write` because the Cursor hook reports every file
+ * mutation — create or edit — as `Write`.
+ *
+ * Returns undefined for non-gated tools (read-only built-ins, MCP tools, and
+ * anything `classifyTool` does not place in a mutating kind).
+ */
+export type ApprovalCategory = "write" | "delete" | "shell";
+
+export function approvalCategory(toolName: string): ApprovalCategory | undefined {
+  switch (classifyTool(toolName)) {
+    case ToolKind.FILE_WRITE:
+    case ToolKind.FILE_EDIT:
+      return "write";
+    case ToolKind.FILE_DELETE:
+      return "delete";
+    case ToolKind.SHELL:
+      return "shell";
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Human-readable approval-message template per canonical category. Keyed by
+ * category (not raw tool name) so a denial surfaced from either taxonomy renders
+ * the same message. Placeholders resolve against the tool args via
+ * {@link resolveApprovalMessage}; `{{args.path}}` and `{{args.command}}` are the
+ * stream-side field names (the runner builds the approval surface from the
+ * streamed tool call, whose args use `path`/`command`).
+ */
+const CATEGORY_APPROVAL_MESSAGE: Record<ApprovalCategory, string> = {
+  write: "Write file: {{args.path}}",
+  delete: "Delete: {{args.path}}",
+  shell: "Run command: {{args.command}}",
+};
+
 /**
  * Top-level tool-argument fields, in priority order, that identify the specific
- * resource a built-in tool acts on. Used to render approval messages and to key
- * HITL approval grants (see approval-state.ts). Authored here once and injected
- * into the generated preToolUse hook script so the runner and the hook always
- * agree on which field to match.
+ * resource a built-in tool acts on. The list deliberately spans BOTH taxonomies'
+ * arg shapes: the hook input names a file `file_path` and the stream names it
+ * `path`; both name a shell command `command`. Extracting the same resource
+ * VALUE on both sides (the absolute path / the command string) is what lets the
+ * hook-recorded denial token equal the stream-computed token. Authored here once
+ * and injected into the generated preToolUse hook script so the runner and the
+ * hook never disagree on which field to match.
  */
-export const SALIENT_ARG_FIELDS = ["path", "command", "target_notebook"] as const;
+export const SALIENT_ARG_FIELDS = ["file_path", "path", "target_notebook", "command"] as const;
 
 /**
  * Check whether a built-in (non-MCP) Cursor tool requires user approval.
  *
- * Only the explicitly gated, mutating/destructive tools require approval;
- * everything else (read-only built-ins, and — at the hook layer — auto-approved
- * MCP tools) is allowed. This "gate the dangerous set, allow the rest" model
- * mirrors the native harness's resolveToolApproval, which also defaults
- * unlisted tools to no-approval. It is deliberately fail-OPEN for unknown
- * tools: the merged MCP policy map carries only the tools that REQUIRE
- * approval, so a fail-closed default would wrongly deny every auto-approved
- * MCP tool, which the hook cannot distinguish from an unknown built-in by name.
+ * Resolved via {@link approvalCategory} so it answers correctly for BOTH
+ * taxonomies — the hook's `Write`/`Shell`/`Delete` and the stream's
+ * `edit`/`shell`/`delete` all return true. Only mutating/destructive tools are
+ * gated; everything else (read-only built-ins, and — at the hook layer —
+ * auto-approved MCP tools) is allowed. This "gate the dangerous set, allow the
+ * rest" model mirrors the native harness's resolveToolApproval. It is
+ * deliberately fail-OPEN for unknown tools: the merged MCP policy map carries
+ * only the tools that REQUIRE approval, so a fail-closed default would wrongly
+ * deny every auto-approved MCP tool, which the hook cannot distinguish from an
+ * unknown built-in by name.
  */
 export function builtInRequiresApproval(toolName: string): boolean {
-  return BUILT_IN_GATED.has(toolName);
+  return approvalCategory(toolName) !== undefined;
 }
 
 /**
  * Returns the built-in tool names that require approval (the gated set the
  * preToolUse hook denies unless auto-approved or granted on reinvocation).
+ *
+ * These are HOOK-taxonomy names (PascalCase), because the hook matches its own
+ * `tool_name`. See {@link approvalCategory} for the cross-layer identity.
  */
 export function getBuiltInGatedList(): string[] {
-  return [...BUILT_IN_GATED.keys()];
+  return [...BUILT_IN_GATED];
+}
+
+/**
+ * Returns the gated built-in tools as `(hookToolName, category)` pairs.
+ *
+ * Injected into the generated preToolUse hook so the bash script can map its
+ * incoming `tool_name` to the canonical category used for the denial/grant
+ * token — the same category the runner computes from the stream side via
+ * {@link approvalCategory}. Authoring it here keeps the mapping single-sourced;
+ * a gated built-in with no category would be a programming error, so it is
+ * filtered out (and would simply not be gated rather than crash the hook).
+ */
+export function getBuiltInGatedCategories(): Array<[string, ApprovalCategory]> {
+  const pairs: Array<[string, ApprovalCategory]> = [];
+  for (const name of BUILT_IN_GATED) {
+    const category = approvalCategory(name);
+    if (category) pairs.push([name, category]);
+  }
+  return pairs;
 }
 
 /**
- * Approval-message template for a gated built-in tool, or undefined when the
- * tool is not a known gated built-in. Callers resolve the placeholders against
- * the tool args via resolveApprovalMessage.
+ * Approval-message template for a gated built-in tool (either taxonomy), or
+ * undefined when the tool is not gated. Resolved via {@link approvalCategory}
+ * so stream-side names (`edit`/`shell`/`delete`) and hook-side names
+ * (`Write`/`Shell`/`Delete`) both map to the same template. Callers resolve the
+ * placeholders against the tool args via resolveApprovalMessage.
  */
 export function getBuiltInApprovalMessage(toolName: string): string | undefined {
-  return BUILT_IN_GATED.get(toolName);
+  const category = approvalCategory(toolName);
+  return category ? CATEGORY_APPROVAL_MESSAGE[category] : undefined;
 }
 
 /**