@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

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

@@ -0,0 +1,1408 @@
+/**
+ * @regression file-hitl-gate — pins that decisions bind to the active turn's
+ * denial ledger, never a stale one, and that a resume respects its order.
+ *
+ * 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, onTestFinished } from "vitest";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { buildHookClientScript, generateHookScript } from "../hook-script.js";
+import { create as createMessage } from "@bufbuild/protobuf";
+import { HookGroupSchema, HookHandlerSchema } from "@stigmer/apis/ai/stigmer/agentic/plugin/v1/hooks_pb";
+import { HookEvaluator } from "../../../shared/hooks/evaluate.js";
+import { HookSet } from "../../../shared/hooks/hook-set.js";
+import { buildShellEnv } from "../../../shared/shell-env.js";
+import { startHookServer } from "../hook-server.js";
+import { CursorEngineToolViews } from "../hook-views.js";
+import { buildApprovalState, grantToken, hookAskDigest, primaryToken, scopeRefusalToken, toolIdentity } from "../approval-state.js";
+import { AGENT_SCOPE_KEY, READ_SCOPE_KEY, compileHookToolScope, scopeKey } from "../hook-scope.js";
+import { CURSOR_SDK_TOOL_COVERS } from "@stigmer/tool-vocabulary";
+import { ToolScope } from "../../../shared/tool-lists.js";
+import { mcpToolKey } from "../../../shared/approval-policy.js";
+import { contentDigest } from "../../../shared/file-tools.js";
+import {
+  setupCursorHookHarness as setup,
+  hasBash,
+  hookWrite,
+  hookEdit,
+  hookShell,
+  hookDelete,
+  hookRead,
+  hookMcp,
+  hookMcpPreToolUse,
+  hookSubagentStart,
+  hookBuiltin,
+  NO_MCP_DEFAULT,
+} from "../__test-utils__/cursor-hook-harness.js";
+
+/** Decode the base64(JSON(tool_input)) the hook records on a denial. */
+function decodeInput(b64: string | undefined): Record<string, unknown> {
+  if (!b64) throw new Error("ledger entry carried no input");
+  return JSON.parse(Buffer.from(b64, "base64").toString("utf-8")) as Record<string, unknown>;
+}
+
+const d = hasBash ? describe : describe.skip;
+
+d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
+  it("denies gated built-ins and records the PRIMARY token (content-exact for a write, coarse for shell/delete)", () => {
+    const h = setup({});
+
+    for (const [input, category, salient, args] of [
+      // hookWrite defaults content "x"; the hook records the content-exact token.
+      [hookWrite("/x/a.txt"), "write", "/x/a.txt", { content: "x" }],
+      [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 primaryToken: content-exact when the hook
+      // can compute an edit digest (the write), else the coarse grantToken.
+      expect(ledger[0].token).toBe(primaryToken(category, salient, contentDigest(args)));
+      // The normal gate is the APPROVAL kind — the only kind that pauses.
+      expect(ledger[0].kind).toBe("approval");
+    }
+  });
+
+  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("a run-lifetime category lease allows that category and ONLY that category", () => {
+    // "Approve all shell commands" must let later shell calls through while still
+    // gating a write — the scoped successor to the old global auto-approve-all.
+    const h = setup({ leasedCategories: ["shell"] });
+    expect(h.decide(hookShell("rm -rf build")).permission).toBe("allow");
+    const writeDecision = h.decide(hookWrite("/x/a.txt"));
+    expect(writeDecision.permission).toBe("deny");
+    // The denied, non-leased write is still recorded for the runner.
+    expect(h.ledger().map((e) => e.toolName)).toContain("Write");
+  });
+
+  // Exact-resource lease isolation ("no name-only over-grant") moved to the
+  // gateway Contract Test Kit's invariant 10, where the SAME bash hook is driven
+  // through the Cursor substrate adapter alongside the deep-agent substrate. See
+  // src/__tests__/approval-gateway-contract.test.ts.
+
+  it("fails closed (deny) when the state file is missing, recorded as kind fail-closed", () => {
+    const h = setup({ noStateFile: true });
+    expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("deny");
+    // The broken-gate deny is ATTRIBUTABLE (issue #205): recorded under the
+    // primary token with kind "fail-closed" and — like every non-approval
+    // kind — content-free (no input field: secret content is never persisted).
+    const ledger = h.ledger();
+    expect(ledger).toHaveLength(1);
+    expect(ledger[0].kind).toBe("fail-closed");
+    expect(ledger[0].token).toBe(primaryToken("write", "/x/a.txt", contentDigest({ content: "x" })));
+    expect(ledger[0]).not.toHaveProperty("input");
+  });
+
+  // Unattended approval mode: same gate, different RESOLUTION — the
+  // approval-deny arms record the non-pausing "unattended" kind with an
+  // adapt-and-explain message. What is gated must be byte-identical to
+  // interactive mode; only the kind and the agent message differ.
+  describe("unattended approval mode", () => {
+    it("denies a gated built-in with kind 'unattended' and the adapt message (no resume promise)", () => {
+      const h = setup({ unattendedSkip: true });
+      const res = h.decide(hookShell("rm -rf build"));
+      expect(res.permission).toBe("deny");
+      expect(res.raw).toContain("skipped automatically");
+      expect(res.raw).not.toContain("resume you");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].kind).toBe("unattended");
+      // Same identity space as interactive mode — the stamping correlates on it.
+      expect(ledger[0].token).toBe(primaryToken("shell", "rm -rf build", ""));
+      // Non-approval kinds are content-free (no approval card needs a preview).
+      expect(ledger[0]).not.toHaveProperty("input");
+    });
+
+    it("denies a require-approval MCP tool with kind 'unattended'", () => {
+      const h = setup({
+        unattendedSkip: true,
+        destructiveMcpTools: ["drop_table"],
+      });
+      const res = h.decide(hookMcp("drop_table", { table: "users" }));
+      expect(res.permission).toBe("deny");
+      expect(res.raw).toContain("skipped automatically");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].kind).toBe("unattended");
+      expect(ledger[0].token).toBe(grantToken("srv/drop_table", ""));
+    });
+
+    it("still allows auto-approved MCP tools and read-only built-ins (gating is unchanged)", () => {
+      const h = setup({
+        unattendedSkip: true,
+        destructiveMcpTools: ["drop_table"],
+      });
+      expect(h.decide(hookMcp("list_tables")).permission).toBe("allow");
+      expect(h.decide(hookRead("/x/a.txt")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("the secret hard-block stays kind 'secret' (mode-independent)", () => {
+      const h = setup({ unattendedSkip: true });
+      const res = h.decide(hookWrite("/x/.env", "API_KEY=abc"));
+      expect(res.permission).toBe("deny");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].kind).toBe("secret");
+    });
+  });
+
+  // File review off (stigmer#1471): a built-in write or delete flows
+  // unreviewed and unasked; the secret-like write block stays, keyed on the
+  // git substrate; shell and destructive MCP still ask.
+  describe("file review off", () => {
+    it("allows a write and a delete with no ledger entry, in a git workspace and in a non-git one", () => {
+      for (const gitWorkspace of [true, false]) {
+        const h = setup({ fileReview: false, gitWorkspace });
+        expect(h.decide(hookWrite(join(h.root, "notes.md"))).permission).toBe("allow");
+        expect(h.decide(hookDelete(join(h.root, "old.md"))).permission).toBe("allow");
+        expect(h.ledger()).toEqual([]);
+      }
+    });
+
+    it("allows a write on an unattended surface: it is applied, not skipped", () => {
+      const h = setup({ fileReview: false, unattendedSkip: true });
+      expect(h.decide(hookWrite(join(h.root, "reply.md"))).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("shell and a destructive MCP tool still ask", () => {
+      const h = setup({ fileReview: false, destructiveMcpTools: ["drop_table"] });
+      expect(h.decide(hookShell("rm -rf build")).permission).toBe("deny");
+      expect(h.decide(hookMcp("drop_table", { table: "users" })).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["approval", "approval"]);
+    });
+
+    it("a tracked .env.example in a git workspace flows: the secret rule is keyed on the substrate", () => {
+      const h = setup({ fileReview: false, gitignored: [] });
+      expect(h.decide(hookWrite(join(h.root, "config/.env.example"), "KEY=")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("a gitignored or non-git secret-like write is still refused, kind 'secret'", () => {
+      const ignored = setup({ fileReview: false, gitignored: [".env"] });
+      expect(ignored.decide(hookWrite(join(ignored.root, ".env"), "API_KEY=abc")).permission).toBe("deny");
+      expect(ignored.ledger().map((e) => e.kind)).toEqual(["secret"]);
+
+      const nonGit = setup({ fileReview: false, gitWorkspace: false });
+      expect(nonGit.decide(hookWrite(join(nonGit.root, ".env"), "API_KEY=abc")).permission).toBe("deny");
+      expect(nonGit.ledger().map((e) => e.kind)).toEqual(["secret"]);
+    });
+
+    it("review on with no substrate still asks before a write (the deny-gate)", () => {
+      const h = setup({ fileReview: true, captureMode: false, gitWorkspace: false });
+      expect(h.decide(hookWrite(join(h.root, "notes.md"))).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["approval"]);
+    });
+  });
+
+  // MCP gating runs ONLY on the beforeMCPExecution event (preToolUse does not
+  // enforce MCP), so a denial is recorded in exactly one place. The identity is
+  // server and tool (base64("<server>/<tool>\n")): both are identical on the
+  // hook input and the runner's stream event, and a grant for one server's
+  // tool never covers an equal tool name on another.
+  describe("MCP tools (beforeMCPExecution event)", () => {
+    it("denies a destructive MCP tool and surfaces its approval message", () => {
+      const h = setup({ destructiveMcpTools: ["click"] });
+      const res = h.decide(hookMcp("click", { app: "Slack", element_index: "59" }));
+      expect(res.permission).toBe("deny");
+      expect(res.raw).toContain("Execute click");
+      expect(h.ledger()).toHaveLength(1);
+      expect(h.ledger()[0].token).toBe(grantToken("srv/click", ""));
+      expect(h.ledger()[0].kind).toBe("approval");
+    });
+
+    it("denial agent_message frames approval as automatic and never trains ask-in-prose", () => {
+      const h = setup({ destructiveMcpTools: ["click"] });
+      const res = h.decide(hookMcp("click"));
+      // The agent_message must tell the model approval is handled automatically
+      // and that it should continue, NOT stop and wait or ask for permission.
+      expect(res.raw).toContain("submitted to the user for approval automatically");
+      expect(res.raw).toContain("continue with the rest of the task");
+      // It must reframe the deny as the approval gate working as intended and
+      // forbid the "fix your Cursor settings" narration that the leaky MCP deny
+      // path otherwise provokes.
+      expect(res.raw.toLowerCase()).toContain("not an error");
+      expect(res.raw.toLowerCase()).toContain("cursor settings");
+      // The old propose-then-wait framing and internal sentinel must be gone.
+      expect(res.raw).not.toContain("STIGMER_APPROVAL_REQUIRED");
+      expect(res.raw).not.toContain("Stop and wait");
+    });
+
+    it("allows a require-approval MCP tool once it has been granted (reinvocation)", () => {
+      const h = setup({
+        destructiveMcpTools: ["click"],
+        grants: [{ toolName: "click", mcpServerSlug: "srv", key: "srv/click", salient: "", contentDigest: "", sourceToolCallId: "consent-1" }],
+      });
+      expect(h.decide(hookMcp("click")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("a grant for one server's tool does not let an equal tool name through on another server", () => {
+      const h = setup({
+        destructiveMcpTools: ["click"],
+        grants: [{ toolName: "click", mcpServerSlug: "other", key: "other/click", salient: "", contentDigest: "", sourceToolCallId: "consent-1" }],
+      });
+      expect(h.decide(hookMcp("click")).permission).toBe("deny");
+      expect(h.ledger()[0]!.token).toBe(grantToken("srv/click", ""));
+    });
+
+    it("keys an MCP grant on server and tool in the bash fallback too, when the Node binary is unavailable", () => {
+      const grant = (slug: string) => [{ toolName: "click", mcpServerSlug: slug, key: `${slug}/click`, salient: "", contentDigest: "", sourceToolCallId: "consent-1" }];
+      const withoutNode = (h: ReturnType<typeof setup>) => {
+        const scriptPath = join(h.hitlDir, "hook.sh");
+        writeFileSync(scriptPath, readFileSync(scriptPath, "utf-8").replace(`NODE_BIN="${process.execPath}"`, 'NODE_BIN="/nonexistent/node"'), "utf-8");
+        return h;
+      };
+      const granted = withoutNode(setup({ destructiveMcpTools: ["click"], grants: grant("srv") }));
+      expect(granted.decide(hookMcp("click")).permission).toBe("allow");
+      const elsewhere = withoutNode(setup({ destructiveMcpTools: ["click"], grants: grant("other") }));
+      expect(elsewhere.decide(hookMcp("click")).permission).toBe("deny");
+      expect(elsewhere.ledger()[0]!.token, "the token the stream row's identity recomputes").toBe(grantToken("srv/click", ""));
+    });
+
+    it("allows an MCP tool its server does not mark destructive", () => {
+      const h = setup({ destructiveMcpTools: ["click"] });
+      expect(h.decide(hookMcp("list_apps")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("asks before every tool of a server whose tools could not be listed this turn, on that server only", () => {
+      // The turn start's listing failed for "srv", so whether any of its
+      // tools changes anything is unknown: the approval default asks for
+      // every one of them (shared/approval-policy.ts `unlisted`), and the
+      // hook is the Cursor engine's only MCP gate.
+      const h = setup({ unlistedMcpServers: ["srv"] });
+      const res = h.decide(hookMcp("anything"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger().map((entry) => [entry.kind, entry.token])).toEqual([["approval", grantToken("srv/anything", "")]]);
+      expect(h.decide(hookMcp("anything", {}, "other")).permission, "another server's tool").toBe("allow");
+    });
+
+    it("a lease clears a server whose tools could not be listed", () => {
+      const h = setup({ unlistedMcpServers: ["srv"], leasedMcpServers: ["srv"] });
+      expect(h.decide(hookMcp("anything")).permission).toBe("allow");
+    });
+
+    it("auto-approve-all allows a require-approval MCP tool", () => {
+      const h = setup({ autoApproveAll: true, destructiveMcpTools: ["click"] });
+      expect(h.decide(hookMcp("click")).permission).toBe("allow");
+    });
+
+    it("fails closed (deny) when the state file is missing, recorded as kind fail-closed", () => {
+      const h = setup({ noStateFile: true });
+      expect(h.decide(hookMcp("click")).permission).toBe("deny");
+      // Attributable under the MCP name-token (the identity the stream row
+      // computes for an MCP call), content-free like every non-approval kind.
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].kind).toBe("fail-closed");
+      expect(ledger[0].token).toBe(grantToken("srv/click", ""));
+      expect(ledger[0]).not.toHaveProperty("input");
+    });
+
+    it("does NOT gate the same MCP tool delivered on preToolUse (no double-gating)", () => {
+      const h = setup({ destructiveMcpTools: ["click"] });
+      // preToolUse must fall through to allow for MCP — gating belongs to
+      // beforeMCPExecution alone, so the denial is never recorded twice.
+      expect(h.decide(hookMcpPreToolUse("click")).permission).toBe("allow");
+      expect(h.decide({ tool_name: "click", tool_input: "{}", hook_event_name: "preToolUse" }).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("keys the destructive set by server: the same tool name on another server passes", () => {
+      const h = setup({ destructiveMcpTools: ["click"] });
+      expect(h.decide(hookMcp("click", {}, "other")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("a leased server's destructive tool passes", () => {
+      const h = setup({ destructiveMcpTools: ["click"], leasedMcpServers: ["srv"] });
+      expect(h.decide(hookMcp("click")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("scope guard: a foreign MCP invocation is allowed and never recorded", () => {
+      const h = setup({
+        destructiveMcpTools: ["click"],
+        runnerPid: 2_147_483_600,
+      });
+      expect(h.decide(hookMcp("click")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+  });
+
+  // The agent's tool lists (scope arm 1a): compiled by the runner
+  // (hook-scope.ts) and only looked up here. A refusal is kind "disabled":
+  // non-pausing, permanent, and placed BEFORE the capture arms,
+  // autoApproveAll and every grant, because a list is not an approval gate.
+  describe("tool lists (scope arm)", () => {
+    const READ_ONLY = { tools: ["Read", "Grep", "mcp__srv"], disallowedTools: [] };
+
+    it("refuses a built-in outside an allow-list with the lists' message, recorded under the tool's scope token", () => {
+      const h = setup({ lists: READ_ONLY });
+      const res = h.decide(hookShell("ls"));
+      expect(res.permission).toBe("deny");
+      expect(res.raw).toContain("Shell is not available to this agent");
+      expect(res.raw).toContain('tools [Read, Grep, mcp__srv]');
+      expect(res.raw).not.toContain("submitted to the user for approval");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].kind).toBe("disabled");
+      expect(ledger[0].token).toBe(scopeRefusalToken(scopeKey("shell", CURSOR_SDK_TOOL_COVERS)));
+      expect(ledger[0]).not.toHaveProperty("input");
+      // The refusal text rides the ledger (base64) for the boundary to stamp on the row.
+      expect(Buffer.from(String(ledger[0].message), "base64").toString("utf-8")).toBe(JSON.parse(res.raw).agent_message);
+    });
+
+    it("refuses a built-in a deny-list names and leaves the rest to the approval gate", () => {
+      const h = setup({ lists: { tools: [], disallowedTools: ["Bash(git push *)"] } });
+      expect(h.decide(hookShell("git status")).permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+      h.resetLedger();
+      // Write is not denied by the list, so it reaches the ordinary approval gate.
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("approval");
+    });
+
+    it("a hook tool covering a denied Claude tool is refused: never Write refuses Delete and the hook's Write, not StrReplace", () => {
+      const h = setup({ lists: { tools: [], disallowedTools: ["Write"] } });
+      expect(h.decide(hookDelete("/x/a.txt")).permission).toBe("deny");
+      expect(h.decide(hookWrite("/x/b.txt")).permission).toBe("deny");
+      // StrReplace covers Edit alone, so it reaches the ordinary approval gate.
+      expect(h.decide(hookEdit("/x/a.txt")).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["disabled", "disabled", "approval"]);
+    });
+
+    it("an engine extra is refused only under an allow-list", () => {
+      const allow = setup({ lists: READ_ONLY });
+      expect(allow.decide(hookBuiltin("GenerateImage", { prompt: "a cat" })).permission).toBe("deny");
+      const deny = setup({ lists: { tools: [], disallowedTools: ["Bash"] } });
+      expect(deny.decide(hookBuiltin("GenerateImage", { prompt: "a cat" })).permission).toBe("allow");
+    });
+
+    it("binds under autoApproveAll, a category lease and a grant (no approval posture resurrects an excluded tool)", () => {
+      const h = setup({
+        lists: READ_ONLY,
+        autoApproveAll: true,
+        leasedCategories: ["shell"],
+        grants: [{ toolName: "shell", mcpServerSlug: "", key: "shell", salient: "ls", contentDigest: "", sourceToolCallId: "consent-1" }],
+      });
+      expect(h.decide(hookShell("ls")).permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("binds ahead of capture mode: an excluded write is refused, not staged", () => {
+      const h = setup({ lists: READ_ONLY, captureMode: true, gitignored: [] });
+      expect(h.decide(hookWrite(join(h.root, "a.txt"))).permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("stays kind disabled under unattended mode (mode-independent)", () => {
+      const h = setup({ lists: READ_ONLY, unattendedSkip: true });
+      expect(h.decide(hookShell("ls")).permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("Read excluded: a real platform file read through the turn's .stigmer link passes; anything else is refused", () => {
+      const h = setup({ lists: { tools: ["Grep"], disallowedTools: [] } });
+      mkdirSync(join(h.platformDir, "skills/a"), { recursive: true });
+      mkdirSync(join(h.platformDir, "inputs"), { recursive: true });
+      writeFileSync(join(h.platformDir, "skills/a/SKILL.md"), "# skill", "utf-8");
+      writeFileSync(join(h.platformDir, "inputs/spec.pdf"), "pdf", "utf-8");
+      mkdirSync(join(h.root, "src"), { recursive: true });
+      writeFileSync(join(h.root, "src/main.ts"), "code", "utf-8");
+      writeFileSync(join(h.root, "secrets.txt"), "secret", "utf-8");
+      // A link inside platform content pointing out of it, into the workspace.
+      symlinkSync(h.root, join(h.platformDir, "inputs/escape"), "dir");
+
+      expect(h.decide(hookBuiltin("Read", { file_path: join(h.root, ".stigmer/skills/a/SKILL.md") })).permission).toBe("allow");
+      expect(h.decide(hookBuiltin("Read", { file_path: ".stigmer/inputs/spec.pdf" }, h.root)).permission).toBe("allow");
+      expect(h.ledger(), "an admitted read records nothing").toEqual([]);
+
+      const refused = [
+        join(h.root, "src/main.ts"),
+        // ".." is resolved before the real path is taken.
+        join(h.root, ".stigmer/../secrets.txt"),
+        // Through the platform link, out through a link inside the content.
+        join(h.root, ".stigmer/inputs/escape/secrets.txt"),
+        // A file that does not exist has no real path to admit.
+        join(h.root, ".stigmer/inputs/missing.pdf"),
+      ];
+      for (const file of refused) expect(h.decide(hookBuiltin("Read", { file_path: file })).permission, file).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["disabled", "disabled", "disabled", "disabled"]);
+      // A Read refusal names the call: the path as given.
+      expect(h.ledger()[0].token).toBe(scopeRefusalToken(READ_SCOPE_KEY, join(h.root, "src/main.ts")));
+    });
+
+    it("Skill denied: a read of a skill's files is refused even with Read in scope; other platform content still reads", () => {
+      const h = setup({ lists: { tools: [], disallowedTools: ["Skill"] } });
+      mkdirSync(join(h.platformDir, "skills/a"), { recursive: true });
+      mkdirSync(join(h.platformDir, "plugins/abc/skills/b"), { recursive: true });
+      mkdirSync(join(h.platformDir, "inputs"), { recursive: true });
+      writeFileSync(join(h.platformDir, "skills/a/SKILL.md"), "# skill", "utf-8");
+      writeFileSync(join(h.platformDir, "plugins/abc/skills/b/SKILL.md"), "# plugin skill", "utf-8");
+      writeFileSync(join(h.platformDir, "inputs/spec.pdf"), "pdf", "utf-8");
+      writeFileSync(join(h.root, "notes.md"), "notes", "utf-8");
+
+      expect(h.decide(hookBuiltin("Read", { file_path: join(h.root, ".stigmer/skills/a/SKILL.md") })).permission).toBe("deny");
+      expect(h.decide(hookBuiltin("Read", { file_path: ".stigmer/plugins/abc/skills/b/SKILL.md" }, h.root)).permission).toBe("deny");
+      expect(h.decide(hookBuiltin("Read", { file_path: join(h.root, ".stigmer/inputs/spec.pdf") })).permission).toBe("allow");
+      expect(h.decide(hookBuiltin("Read", { file_path: join(h.root, "notes.md") })).permission).toBe("allow");
+      expect(h.decide(hookBuiltin("Read", { file_path: join(h.root, "missing.md") })).permission, "a missing file is the read's own error").toBe("allow");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["disabled", "disabled"]);
+      expect(h.ledger()[0].token).toBe(scopeRefusalToken(READ_SCOPE_KEY, join(h.root, ".stigmer/skills/a/SKILL.md")));
+    });
+
+    it("Skill denied: a read anywhere in a mounted plugin's tree, or under a differently cased skills dir, is refused", () => {
+      const h = setup({ lists: { tools: [], disallowedTools: ["Skill"] } });
+      // A manifest-declared skill directory, and a directory whose name
+      // differs from skills/ only in case (as it may on any filesystem).
+      mkdirSync(join(h.platformDir, "plugins/abc/my-skills/solo"), { recursive: true });
+      mkdirSync(join(h.platformDir, "Skills/a"), { recursive: true });
+      writeFileSync(join(h.platformDir, "plugins/abc/my-skills/solo/SKILL.md"), "# declared", "utf-8");
+      writeFileSync(join(h.platformDir, "Skills/a/SKILL.md"), "# cased", "utf-8");
+
+      expect(h.decide(hookBuiltin("Read", { file_path: ".stigmer/plugins/abc/my-skills/solo/SKILL.md" }, h.root)).permission).toBe("deny");
+      expect(h.decide(hookBuiltin("Read", { file_path: join(h.root, ".stigmer/Skills/a/SKILL.md") })).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["disabled", "disabled"]);
+    });
+
+    it("Skill denied: a case-folded spelling of skills/ that the filesystem opens is refused", (ctx) => {
+      const h = setup({ lists: { tools: [], disallowedTools: ["Skill"] } });
+      mkdirSync(join(h.platformDir, "skills/a"), { recursive: true });
+      writeFileSync(join(h.platformDir, "skills/a/SKILL.md"), "# skill", "utf-8");
+      // U+017F (long s) folds to "s" on a case-insensitive filesystem but
+      // not under toLowerCase: only the path on disk names skills/.
+      const variant = join(h.root, ".stigmer/\u017Fkills/a/SKILL.md");
+      if (!existsSync(variant)) ctx.skip();
+
+      expect(h.decide(hookBuiltin("Read", { file_path: variant })).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["disabled"]);
+    });
+
+    it("Read excluded on an unlinked turn: a repository's own .stigmer symlink admits nothing", () => {
+      const h = setup({ lists: { tools: ["Grep"], disallowedTools: [] }, stigmerLink: "repo" });
+      writeFileSync(join(h.root, "repo-state/notes.md"), "repo file", "utf-8");
+      expect(h.decide(hookBuiltin("Read", { file_path: join(h.root, ".stigmer/notes.md") })).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["disabled"]);
+    });
+
+    it("refuses an MCP tool by server AND tool, recorded under its server/tool scope token", () => {
+      const h = setup({
+        lists: { tools: ["mcp__srv__list_apps"], disallowedTools: [] },
+        mcpServers: [{ slug: "srv", listedTools: ["list_apps", "click"] }, { slug: "other", listedTools: ["list_apps"] }],
+      });
+      expect(h.decide(hookMcp("list_apps")).permission).toBe("allow");
+      const res = h.decide(hookMcp("click", { app: "Slack" }));
+      expect(res.permission).toBe("deny");
+      expect(res.raw).toContain("click is not available to this agent");
+      // The same tool name on another server is a different tool.
+      expect(h.decide(hookMcp("list_apps", {}, "other")).permission).toBe("deny");
+      const ledger = h.ledger();
+      expect(ledger.map((e) => e.kind)).toEqual(["disabled", "disabled"]);
+      expect(ledger[0].token).toBe(scopeRefusalToken(mcpToolKey("srv", "click")));
+      expect(ledger[1].token).toBe(scopeRefusalToken(mcpToolKey("other", "list_apps")));
+    });
+
+    it("answers an MCP tool of a server the turn start could not list by its server's family entry", () => {
+      const h = setup({
+        lists: { tools: ["mcp__srv"], disallowedTools: ["mcp__srv__drop_all"] },
+        mcpServers: [{ slug: "srv", listedTools: null }],
+      });
+      expect(h.decide(hookMcp("brand_new")).permission).toBe("allow");
+      expect(h.decide(hookMcp("drop_all")).permission).toBe("deny");
+      expect(h.decide(hookMcp("anything", {}, "unknown_server")).permission).toBe("deny");
+    });
+
+    it("keeps the platform's attachment servers in scope under any allow-list", () => {
+      const h = setup({ lists: READ_ONLY, platformServerSlugs: ["stigmer-memory"], mcpServers: [{ slug: "stigmer-memory", listedTools: null }] });
+      expect(h.decide(hookMcp("remember", {}, "stigmer-memory")).permission).toBe("allow");
+    });
+
+    it("an excluded MCP tool is refused under autoApproveAll and ahead of its grant", () => {
+      const h = setup({
+        lists: { tools: [], disallowedTools: ["mcp__srv__click"] },
+        autoApproveAll: true,
+        grants: [{ toolName: "click", mcpServerSlug: "srv", key: "click", salient: "", contentDigest: "", sourceToolCallId: "consent-1" }],
+      });
+      expect(h.decide(hookMcp("click")).permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("an in-scope destructive MCP tool still reaches the approval gate (lists and approvals compose)", () => {
+      const h = setup({ lists: { tools: ["mcp__srv"], disallowedTools: [] }, destructiveMcpTools: ["click"] });
+      const res = h.decide(hookMcp("click"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("approval");
+    });
+
+    it("subagentStart: refuses a type outside Agent(type, …), Cursor's built-in types included, and allows a listed one", () => {
+      const h = setup({ lists: { tools: ["Read", "Agent(researcher, Explore)"], disallowedTools: [] }, subAgentTypes: ["researcher", "writer"] });
+      expect(h.decide(hookSubagentStart("researcher")).permission).toBe("allow");
+      expect(h.decide(hookSubagentStart("explore")).permission).toBe("allow");
+      const writer = h.decide(hookSubagentStart("writer"));
+      expect(writer.permission).toBe("deny");
+      expect(writer.raw).toContain("Agent(writer) is not available to this agent");
+      expect(h.decide(hookSubagentStart("generalPurpose")).permission).toBe("deny");
+      const ledger = h.ledger();
+      expect(ledger.map((e) => e.kind)).toEqual(["disabled", "disabled"]);
+      // A sub-agent start's refusal names the call: the normalized type.
+      expect(ledger[0].token).toBe(scopeRefusalToken(AGENT_SCOPE_KEY, "writer"));
+    });
+
+    it("subagentStart: Cursor's generalPurpose is the general-purpose type a list names", () => {
+      const gp = setup({ lists: { tools: ["Read", "Agent(general-purpose)"], disallowedTools: [] } });
+      expect(gp.decide(hookSubagentStart("generalPurpose")).permission).toBe("allow");
+      const explore = setup({ lists: { tools: ["Read", "Agent(explore)"], disallowedTools: [] } });
+      expect(explore.decide(hookSubagentStart("generalPurpose")).permission).toBe("deny");
+      expect(explore.decide(hookSubagentStart("Explore")).permission).toBe("allow");
+      expect(explore.ledger().map((e) => e.kind)).toEqual(["disabled"]);
+    });
+
+    it("preToolUse Task: a subagent_type outside Agent(type, …) is refused at the call, recorded with its type", () => {
+      const h = setup({ lists: { tools: ["Read", "Agent(explore)"], disallowedTools: [] } });
+      const res = h.decide(hookBuiltin("Task", { subagent_type: "generalPurpose", description: "Do", prompt: "Do it." }));
+      expect(res.permission).toBe("deny");
+      expect(res.raw).toContain("Agent(generalPurpose) is not available to this agent");
+      expect(h.decide(hookBuiltin("Task", { subagent_type: "Explore", prompt: "Look." })).permission).toBe("allow");
+      // A Task naming no type keeps the subagentStart path.
+      expect(h.decide(hookBuiltin("Task", { prompt: "Something." })).permission).toBe("allow");
+      const ledger = h.ledger();
+      expect(ledger.map((e) => e.kind)).toEqual(["disabled"]);
+      expect(ledger[0].token).toBe(scopeRefusalToken(AGENT_SCOPE_KEY, "generalpurpose"));
+    });
+
+    it("subagentStart: allowed with no lists, and refused when the lists exclude Agent", () => {
+      expect(setup({}).decide(hookSubagentStart("explore")).permission).toBe("allow");
+      const h = setup({ lists: { tools: [], disallowedTools: ["Agent"] } });
+      expect(h.decide(hookSubagentStart("explore")).permission).toBe("deny");
+    });
+
+    it("an agent with no lists is never refused by the scope arm", () => {
+      const h = setup({ autoApproveAll: true });
+      expect(h.decide(hookBuiltin("GenerateImage", {})).permission).toBe("allow");
+      expect(h.decide(hookMcp("anything", {}, "any")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("an MCP tool named like a state flag cannot switch the flag on (the scope rides the state opaque)", () => {
+      // A deny-list leaves these tools in scope, so the compiled table holds
+      // `"autoApproveAll":true` and `"captureMode":true` as answers. In scope,
+      // a write must still reach the approval gate and be held there.
+      const h = setup({
+        lists: { tools: [], disallowedTools: ["Bash"] },
+        mcpServers: [{ slug: "srv", listedTools: ["autoApproveAll", "captureMode", "unattendedSkip"] }],
+      });
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["approval"]);
+    });
+
+    it("scope guard: a foreign invocation is allowed and never recorded, lists or not", () => {
+      const h = setup({ lists: READ_ONLY, runnerPid: 2_147_483_600 });
+      expect(h.decide(hookShell("ls")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+  });
+
+  // The hook captures the COMPLETE tool_input on every denial (base64(JSON)),
+  // so the runner can overlay the proposed change onto the gated tool call for
+  // the approval preview — the cursor analog of the native harness reading args
+  // from graph state at the interrupt. These pin the capture across taxonomies
+  // (built-in object tool_input vs. MCP JSON-string tool_input).
+  describe("captures tool_input on the denial ledger", () => {
+    it("records the full built-in write input (object tool_input)", () => {
+      const h = setup({});
+      expect(h.decide(hookWrite("/x/a.txt", "export const x = 1;\n")).permission).toBe("deny");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(decodeInput(ledger[0].input)).toEqual({
+        file_path: "/x/a.txt",
+        content: "export const x = 1;\n",
+      });
+    });
+
+    it("records an edit's old/new replacement strings", () => {
+      const h = setup({});
+      expect(h.decide(hookEdit("/x/a.txt", "alpha", "beta")).permission).toBe("deny");
+      expect(decodeInput(h.ledger()[0].input)).toEqual({
+        file_path: "/x/a.txt",
+        old_string: "alpha",
+        new_string: "beta",
+      });
+    });
+
+    it("parses and records the MCP JSON-STRING tool_input", () => {
+      // Cursor delivers MCP tool_input as a JSON string, not an object — the
+      // extractor must parse it so the captured input is the same object shape.
+      const h = setup({ destructiveMcpTools: ["click"] });
+      expect(h.decide(hookMcp("click", { app: "Slack", element_index: "59" })).permission).toBe("deny");
+      expect(decodeInput(h.ledger()[0].input)).toEqual({ app: "Slack", element_index: "59" });
+    });
+
+    it("captures large multi-line content intact (printf, not echo/argv)", () => {
+      const content = "line\n".repeat(20_000); // ~100 KB, exercises the printf write
+      const h = setup({});
+      expect(h.decide(hookWrite("/x/big.ts", content)).permission).toBe("deny");
+      expect(decodeInput(h.ledger()[0].input).content).toBe(content);
+    });
+  });
+
+  // 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, contentDigest: "", sourceToolCallId: "consent-1" }] });
+
+    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");
+  });
+
+  // The full runner<->hook closure, per gated category and for the bytes most
+  // likely to drift: the token the RUNNER writes into approval-state.json (via
+  // buildApprovalState, exactly as index.ts does on resume) is byte-identical to
+  // the token the HOOK records when it denies the same action, and the hook's
+  // grep -qF membership check then ALLOWS the re-issued call. This is the precise
+  // production safety property — "approve once, allowed on the resumed turn" —
+  // closed end to end rather than asserted on either half alone.
+  describe("runner grant <-> hook allow closure (tricky args, every gated category)", () => {
+    const cases: Array<{
+      label: string;
+      streamName: string;
+      streamArgs: Record<string, unknown>;
+      hookInput: object;
+      otherHookInput: object;
+    }> = [
+      {
+        label: "write — path with spaces, quotes, and unicode",
+        streamName: "edit",
+        // Content matches hookWrite's default ("x") so the runner-side grant
+        // digest equals the hook-side content digest (content-exact closure).
+        streamArgs: { path: '/work/a dir/"café" notes.md', content: "x" },
+        hookInput: hookWrite('/work/a dir/"café" notes.md'),
+        otherHookInput: hookWrite("/work/other.md"),
+      },
+      {
+        label: "shell — multi-line heredoc with quotes and unicode",
+        streamName: "shell",
+        streamArgs: { command: "cat > notes.md << 'EOF'\n# Notes — \"x\" café\nEOF" },
+        hookInput: hookShell("cat > notes.md << 'EOF'\n# Notes — \"x\" café\nEOF"),
+        otherHookInput: hookShell("rm -rf build"),
+      },
+      {
+        label: "delete — path with quotes",
+        streamName: "delete",
+        streamArgs: { path: '/work/"old" file.tmp' },
+        hookInput: hookDelete('/work/"old" file.tmp'),
+        otherHookInput: hookDelete("/work/keep.tmp"),
+      },
+    ];
+
+    for (const { label, streamName, streamArgs, hookInput, otherHookInput } of cases) {
+      it(`${label}: the state-file token the runner writes is the token the hook denies and then allows`, () => {
+        // 1. The hook denies the un-granted call and records its identity token.
+        const denyHarness = setup({});
+        expect(denyHarness.decide(hookInput).permission).toBe("deny");
+        const denialLedger = denyHarness.ledger();
+        expect(denialLedger).toHaveLength(1);
+        const hookDenialToken = denialLedger[0].token;
+
+        // 2. The runner mints the grant from the STREAM-side identity (the only
+        //    side it sees) and writes it into the real state file via
+        //    buildApprovalState — the exact path index.ts takes on resume.
+        const id = toolIdentity(streamName, "", streamArgs);
+        const state = buildApprovalState(NO_MCP_DEFAULT, false, new Set(), [
+          { toolName: streamName, mcpServerSlug: "", key: id.key, salient: id.salient, contentDigest: contentDigest(streamArgs), sourceToolCallId: "consent-1" },
+        ]);
+
+        // 3. The state file carries the byte-exact token the hook recomputed —
+        //    the grep -qF membership the bash hook performs (string equality).
+        expect(state.approvedGrantTokens).toContain(hookDenialToken);
+
+        // 4. With that state file, the hook ALLOWS the re-issued (fresh-id) call
+        //    and re-gates a DIFFERENT resource of the same category.
+        const grantHarness = setup({ grants: state.approvedGrants });
+        expect(grantHarness.decide(hookInput).permission).toBe("allow");
+        expect(grantHarness.decide(otherHookInput).permission).toBe("deny");
+      });
+    }
+  });
+
+  it("sibling isolation: approving one edit does NOT allow a DIFFERENT edit to the same file", () => {
+    // The exact reported bug, closed end-to-end through the real hook: approving
+    // the rename must re-gate the later `## TODO` edit to the SAME file.
+    const path = "/work/notes.md";
+    const renameArgs = { path, content: "Planton" };
+    const id = toolIdentity("edit", "", renameArgs);
+    const state = buildApprovalState(NO_MCP_DEFAULT, false, new Set(), [
+      { toolName: "edit", mcpServerSlug: "", key: id.key, salient: id.salient, contentDigest: contentDigest(renameArgs), sourceToolCallId: "consent-1" },
+    ]);
+    const h = setup({ grants: state.approvedGrants });
+
+    // The approved edit, re-issued with the SAME content, is allowed.
+    expect(h.decide(hookWrite(path, "Planton")).permission).toBe("allow");
+    // A DIFFERENT edit to the SAME file is re-gated — the sibling hole is closed.
+    expect(h.decide(hookWrite(path, "## TODO")).permission).toBe("deny");
+  });
+
+  // Issue #173: the hook ships on the workspace's shared .cursor/hooks.json, so
+  // the user's own Cursor IDE (a DIFFERENT process tree) would load and run it
+  // too. The scope guard must allow any invocation that does not descend from
+  // the runner process — without gating it and without writing the denial ledger
+  // (a foreign denial would surface as a phantom approval card in the session).
+  describe("scope guard (issue #173): foreign invocations are not gated", () => {
+    // A PID that cannot be an ancestor of the test's bash child. macOS pid_max is
+    // 99998; this is comfortably above it and above a freshly-booted Linux
+    // pid range, so get_ppid yields nothing and the walk reports "not own".
+    const FOREIGN_PID = 2_147_483_600;
+
+    it("allows a gated built-in when the invocation is not the runner's own agent", () => {
+      const h = setup({ runnerPid: FOREIGN_PID });
+      // The IDE would have this DENIED if the gate applied — it must be allowed.
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("allow");
+      expect(h.decide(hookShell("rm -rf build")).permission).toBe("allow");
+    });
+
+    it("never writes the denial ledger for a foreign invocation (no phantom approvals)", () => {
+      const h = setup({ runnerPid: FOREIGN_PID });
+      h.resetLedger();
+      h.decide(hookWrite("/x/a.txt"));
+      h.decide(hookShell("gh issue view 173"));
+      // The IDE's tool calls must NOT leak into the ledger the runner reads back.
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("allows a foreign invocation even when the state file is missing", () => {
+      // Fail-closed is for the runner's OWN agent; a foreign client must never be
+      // blocked by a missing state file (that was the multi-root exit-127 lockup).
+      const h = setup({ runnerPid: FOREIGN_PID, noStateFile: true });
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("still gates the runner's own agent (control: gate applies in-process)", () => {
+      // Same inputs, but runnerPid defaults to this process (an ancestor of the
+      // bash child) — the gate must apply, proving the guard discriminates.
+      const h = setup({});
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("deny");
+      expect(h.ledger()).toHaveLength(1);
+    });
+  });
+
+  // Capture mode (git workspaces): file mutations flow during the turn (the
+  // runner captures the whole change set with git and gates it per-file at the
+  // turn boundary), while shell/MCP and gitignored writes stay on the deny-gate.
+  describe("capture mode (git workspaces)", () => {
+    it("allows write/edit/delete to flow and records no denial", () => {
+      const h = setup({ captureMode: true });
+      expect(h.decide(hookWrite("normal.txt")).permission).toBe("allow");
+      expect(h.decide(hookEdit("normal.txt")).permission).toBe("allow");
+      expect(h.decide(hookDelete("normal.txt")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("still gates shell (it is not git-reversible)", () => {
+      const h = setup({ captureMode: true });
+      expect(h.decide(hookShell("rm -rf build")).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.toolName)).toContain("Shell");
+    });
+
+    it("still gates require-approval MCP tools", () => {
+      const h = setup({ captureMode: true, destructiveMcpTools: ["click"] });
+      expect(h.decide(hookMcp("click")).permission).toBe("deny");
+    });
+
+    it("keeps gating a write to a GITIGNORED path (the snapshot cannot revert it)", () => {
+      // A NON-secret gitignored path is invisible to the git snapshot, so capture
+      // mode must still gate it for explicit approval. (A secret-like gitignored
+      // write is hard-blocked instead — see the deny-gate secret cases below.)
+      const h = setup({ captureMode: true, gitignored: ["ignored.txt"] });
+      expect(h.decide(hookWrite("ignored.txt")).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.toolName)).toContain("Write");
+      // A non-ignored sibling still flows.
+      expect(h.decide(hookWrite("normal.txt")).permission).toBe("allow");
+    });
+
+    it("keeps gating a DELETE of a gitignored path", () => {
+      const h = setup({ captureMode: true, gitignored: ["secret.txt"] });
+      expect(h.decide(hookDelete("secret.txt")).permission).toBe("deny");
+    });
+  });
+
+  // Deny-gate secret hard-block: with no capture substrate for a write
+  // (capture off — the classic deny-gate — or captureIgnored off in a git-no-
+  // storage workspace) a secret-like WRITE must NOT surface its content for
+  // approval. The hook hard-blocks it with the security message and records a
+  // kind:"secret" ledger entry — ATTRIBUTABLE (issue #205: the runner must know
+  // this block was ours) but non-pausing (approvalDenials filters it out, so it
+  // never becomes an approvable WAITING row) and content-free (only the
+  // identity token, never the proposed bytes). A non-secret write still
+  // deny-gates as kind:"approval", and a delete (content-less) stays gated.
+  describe("deny-gate secret hard-block", () => {
+    it("hard-blocks a secret-like write; records an attributable, content-free secret entry", () => {
+      const h = setup({}); // captureMode off — the classic deny-gate
+      const dec = h.decide(hookWrite(".env", "API_KEY=abc"));
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("blocked for security");
+      // SECRET_BLOCKED, not APPROVAL_REQUIRED: the model is told to move on.
+      expect(dec.raw.toLowerCase()).toContain("nothing was written");
+      expect(dec.raw).not.toContain("submitted to the user for approval");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].kind).toBe("secret");
+      // Content-free on the raw ledger bytes: no input field, no trace of the content.
+      expect(ledger[0]).not.toHaveProperty("input");
+      expect(JSON.stringify(ledger[0])).not.toContain("API_KEY");
+    });
+
+    it("hard-blocks a secret-like edit (path-fragment match)", () => {
+      const h = setup({});
+      const dec = h.decide(hookEdit(".ssh/id_rsa"));
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("blocked for security");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["secret"]);
+    });
+
+    it("still deny-gates a NON-secret write and records its content for approval", () => {
+      const h = setup({});
+      const dec = h.decide(hookWrite("notes.md", "hello"));
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("submitted to the user for approval"); // APPROVAL_REQUIRED
+      expect(h.ledger().map((e) => e.toolName)).toContain("Write");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["approval"]);
+    });
+
+    it("a write-category lease does NOT bypass the secret block", () => {
+      const h = setup({ leasedCategories: ["write"] });
+      expect(h.decide(hookWrite("notes.md", "x")).permission).toBe("allow"); // non-secret rides the lease
+      const dec = h.decide(hookWrite(".env", "SECRET")); // secret is still hard-blocked
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("blocked for security");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["secret"]);
+      expect(JSON.stringify(h.ledger())).not.toContain("SECRET");
+    });
+
+    it("hard-blocks a secret write in a git workspace with captureIgnored off (no storage)", () => {
+      const h = setup({ captureMode: true, captureIgnored: false, gitignored: [".env"] });
+      const dec = h.decide(hookWrite(".env", "API_KEY=abc"));
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("blocked for security");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["secret"]);
+    });
+
+    it("does NOT hard-block a secret DELETE (no content; stays deny-gated)", () => {
+      const h = setup({});
+      expect(h.decide(hookDelete(".env")).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.toolName)).toContain("Delete");
+    });
+  });
+
+  // CAS parity: with captureIgnored on, a non-secret gitignored write no
+  // longer stays on the deny-gate — the hook stages its pre-turn bytes into the
+  // cas-observations sidecar and ALLOWS it (apply-then-review), while a secret-
+  // like gitignored write is hard-blocked and recorded as unreviewable. The
+  // sidecar is read back through the real reader.
+  describe("capture mode + captureIgnored (gitignored CAS capture)", () => {
+    it("stages a non-secret gitignored ADD and allows it (before=null)", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitignored: ["*.log"] });
+      expect(h.decide(hookWrite("app.log", "hello")).permission).toBe("allow");
+      // Flowed, not denied — it must not become a WAITING_APPROVAL row.
+      expect(h.ledger()).toEqual([]);
+      const obs = await h.observations();
+      expect(obs.secretPaths).toEqual([]);
+      expect(obs.captured).toHaveLength(1);
+      expect(obs.captured[0].path).toBe("app.log");
+      expect(obs.captured[0].before).toBeNull();
+    });
+
+    it("stages a non-secret gitignored MODIFY with the true pre-turn before-bytes", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitignored: ["*.log"] });
+      writeFileSync(join(h.root, "app.log"), "ORIGINAL", "utf-8");
+      expect(h.decide(hookWrite("app.log", "NEW")).permission).toBe("allow");
+      const obs = await h.observations();
+      expect(obs.captured).toHaveLength(1);
+      expect(obs.captured[0].before).not.toBeNull();
+      expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("ORIGINAL");
+    });
+
+    it("first-touch-wins: two edits to one gitignored path keep the original before", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitignored: ["*.log"] });
+      writeFileSync(join(h.root, "app.log"), "ORIGINAL", "utf-8");
+      expect(h.decide(hookWrite("app.log", "FIRST")).permission).toBe("allow");
+      // Simulate the first write having applied, then a second edit this turn.
+      writeFileSync(join(h.root, "app.log"), "FIRST", "utf-8");
+      expect(h.decide(hookEdit("app.log")).permission).toBe("allow");
+      const obs = await h.observations();
+      expect(obs.captured).toHaveLength(1);
+      expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("ORIGINAL");
+    });
+
+    it("hard-blocks a secret-like gitignored write; records a non-pausing secret entry", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitignored: [".env"] });
+      const d = h.decide(hookWrite(".env", "API_KEY=abc"));
+      expect(d.permission).toBe("deny");
+      expect(d.raw).toContain("blocked for security");
+      // A secret is NOT approvable: its kind:"secret" entry attributes the block
+      // to our own gate (issue #205) but is filtered out of the pause path — it
+      // surfaces as DIFF_UNREVIEWABLE instead, and carries no content.
+      const ledger = h.ledger();
+      expect(ledger.map((e) => e.kind)).toEqual(["secret"]);
+      expect(ledger[0]).not.toHaveProperty("input");
+      expect(JSON.stringify(ledger[0])).not.toContain("API_KEY");
+      const obs = await h.observations();
+      expect(obs.captured).toEqual([]);
+      expect(obs.secretPaths).toEqual([".env"]);
+    });
+
+    it("a CAS staging error fails closed and records a content-free capture-error entry", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitignored: ["*.log"] });
+      // Force the staging script's "error" result: the sidecar dir path is
+      // occupied by a regular FILE, so mkdir fails and the blob write throws.
+      // (The harness keeps state/ledger/sidecar in .cursor/hooks — its hitlDir
+      // analog; see setupCursorHookHarness.)
+      writeFileSync(join(h.root, ".cursor", "hooks", "cas-observations"), "not a dir", "utf-8");
+      const d = h.decide(hookWrite("app.log", "payload"));
+      expect(d.permission).toBe("deny");
+      // Denied with the approval message (fail-closed, today's deny-gate text)
+      // but recorded as kind "capture-error": attributable, NON-pausing (there
+      // is no approval that could make the write reviewable), and content-free
+      // (the staging error means secret classification may never have run).
+      expect(d.raw).toContain("submitted to the user for approval");
+      const ledger = h.ledger();
+      expect(ledger.map((e) => e.kind)).toEqual(["capture-error"]);
+      expect(ledger[0]).not.toHaveProperty("input");
+      expect(JSON.stringify(ledger[0])).not.toContain("payload");
+    });
+
+    it("captures under auto_approve_all too (capture is a turn property, not authorization)", async () => {
+      const h = setup({
+        captureMode: true,
+        captureIgnored: true,
+        autoApproveAll: true,
+        gitignored: ["*.log", ".env"],
+      });
+      // Non-secret gitignored write is staged + allowed even under the bypass...
+      expect(h.decide(hookWrite("app.log", "x")).permission).toBe("allow");
+      // ...and a secret-like one is STILL hard-blocked under the bypass.
+      expect(h.decide(hookWrite(".env", "SECRET")).permission).toBe("deny");
+      const obs = await h.observations();
+      expect(obs.captured.map((c) => c.path)).toEqual(["app.log"]);
+      expect(obs.secretPaths).toEqual([".env"]);
+    });
+
+    it("does not stage a git-tracked write (git captures it) — flows, no observation", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitignored: ["*.log"] });
+      expect(h.decide(hookWrite("tracked.ts", "x")).permission).toBe("allow");
+      const obs = await h.observations();
+      expect(obs.captured).toEqual([]);
+      expect(obs.secretPaths).toEqual([]);
+    });
+
+    it("stages a non-secret gitignored DELETE and allows it (issue #303)", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitignored: ["*.log"] });
+      writeFileSync(join(h.root, "app.log"), "DOOMED", "utf-8");
+      expect(h.decide(hookDelete("app.log")).permission).toBe("allow");
+      // Flowed, not denied — reviewed post-hoc as a DELETE entry, not a pause.
+      expect(h.ledger()).toEqual([]);
+      const obs = await h.observations();
+      expect(obs.secretPaths).toEqual([]);
+      expect(obs.captured).toHaveLength(1);
+      expect(obs.captured[0].path).toBe("app.log");
+      // The pre-delete bytes are staged — the restorable "before" side.
+      expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("DOOMED");
+    });
+
+    it("first-touch-wins across write-then-delete: the true pre-turn before survives", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitignored: ["*.log"] });
+      writeFileSync(join(h.root, "app.log"), "ORIGINAL", "utf-8");
+      expect(h.decide(hookWrite("app.log", "REWRITTEN")).permission).toBe("allow");
+      // Simulate the write having applied, then a delete later this turn.
+      writeFileSync(join(h.root, "app.log"), "REWRITTEN", "utf-8");
+      expect(h.decide(hookDelete("app.log")).permission).toBe("allow");
+      const obs = await h.observations();
+      expect(obs.captured).toHaveLength(1);
+      expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("ORIGINAL");
+    });
+
+    it("keeps a SECRET-LIKE gitignored delete on the deny-gate: approvable, never staged (issue #303)", async () => {
+      // Unlike a secret write (hard-blocked — its content must never surface), a
+      // delete's args expose no secret content, so a human may approve it. Its
+      // before-bytes must never enter the sidecar though: staging would both
+      // persist the secret bytes and mark the path "secret", making the boundary
+      // author a blocking DIFF_UNREVIEWABLE for a merely-gated delete.
+      const h = setup({ captureMode: true, captureIgnored: true, gitignored: [".env"] });
+      writeFileSync(join(h.root, ".env"), "API_KEY=abc", "utf-8");
+      const d = h.decide(hookDelete(".env"));
+      expect(d.permission).toBe("deny");
+      expect(d.raw).toContain("submitted to the user for approval"); // gated, not blocked
+      expect(h.ledger().map((e) => e.kind)).toEqual(["approval"]);
+      const obs = await h.observations();
+      expect(obs.captured).toEqual([]);
+      expect(obs.secretPaths).toEqual([]); // no secret marker for a gated delete
+    });
+
+    it("with captureIgnored OFF, a gitignored write stays denied and stages nothing", async () => {
+      const h = setup({ captureMode: true, captureIgnored: false, gitignored: ["*.log"] });
+      expect(h.decide(hookWrite("app.log", "x")).permission).toBe("deny");
+      const obs = await h.observations();
+      expect(obs.captured).toEqual([]);
+    });
+  });
+
+  // A NON-git workspace has no git snapshot, so EVERY file write and
+  // (issue #303) every non-secret delete is CAS-staged and flowed for review —
+  // not only gitignored ones — while shell/MCP gate as always. The workspace is
+  // deliberately NOT git-initialized.
+  describe("non-git workspace CAS capture", () => {
+    it("stages EVERY write (not just gitignored) and allows it, no denial", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitWorkspace: false });
+      writeFileSync(join(h.root, "notes.md"), "ORIGINAL", "utf-8");
+      expect(h.decide(hookWrite("notes.md", "NEW")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+      const obs = await h.observations();
+      expect(obs.secretPaths).toEqual([]);
+      expect(obs.captured).toHaveLength(1);
+      expect(obs.captured[0].path).toBe("notes.md");
+      expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("ORIGINAL");
+    });
+
+    it("stages an ADD (before=null) and allows it", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitWorkspace: false });
+      expect(h.decide(hookWrite("created.ts", "x")).permission).toBe("allow");
+      const obs = await h.observations();
+      expect(obs.captured).toHaveLength(1);
+      expect(obs.captured[0].before).toBeNull();
+    });
+
+    it("hard-blocks a secret-like write; records a non-pausing, content-free secret entry", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitWorkspace: false });
+      const dcn = h.decide(hookWrite(".env", "API_KEY=abc"));
+      expect(dcn.permission).toBe("deny");
+      expect(dcn.raw).toContain("blocked for security");
+      const ledger = h.ledger();
+      expect(ledger.map((e) => e.kind)).toEqual(["secret"]);
+      expect(JSON.stringify(ledger[0])).not.toContain("API_KEY");
+      const obs = await h.observations();
+      expect(obs.captured).toEqual([]);
+      expect(obs.secretPaths).toEqual([".env"]);
+    });
+
+    it("stages a DELETE with its pre-delete bytes and allows it (issue #303)", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitWorkspace: false });
+      writeFileSync(join(h.root, "notes.md"), "KEEP ME", "utf-8");
+      expect(h.decide(hookDelete("notes.md")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+      const obs = await h.observations();
+      expect(obs.captured).toHaveLength(1);
+      expect(obs.captured[0].path).toBe("notes.md");
+      expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("KEEP ME");
+    });
+
+    it("keeps a secret-like DELETE gated (approvable) and stages nothing", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitWorkspace: false });
+      writeFileSync(join(h.root, ".env"), "API_KEY=abc", "utf-8");
+      const d = h.decide(hookDelete(".env"));
+      expect(d.permission).toBe("deny");
+      expect(d.raw).toContain("submitted to the user for approval");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["approval"]);
+      const obs = await h.observations();
+      expect(obs.captured).toEqual([]);
+      expect(obs.secretPaths).toEqual([]);
+    });
+
+    it("still gates shell (never git-reversible, never CAS-captured)", async () => {
+      const h = setup({ captureMode: true, captureIgnored: true, gitWorkspace: false });
+      expect(h.decide(hookShell("rm -rf /")).permission).toBe("deny");
+    });
+
+    it("still gates a require-approval MCP tool", async () => {
+      const h = setup({
+        captureMode: true,
+        captureIgnored: true,
+        gitWorkspace: false,
+        destructiveMcpTools: ["click"],
+      });
+      expect(h.decide(hookMcp("click")).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-"));
+    onTestFinished(() => rmSync(ws, { recursive: true, force: true }));
+    const dir = join(ws, ".cursor", "hooks");
+    mkdirSync(dir, { recursive: true });
+    const statePath = join(dir, "state.json");
+    const ledgerPath = join(dir, "denials.jsonl");
+    const pointerPath = join(dir, "active.json");
+    const scriptPath = join(dir, "hook.sh");
+    // Break the baked Node path to force the grep/cut fallback for BOTH the
+    // active-turn pointer parse and the tool identity extraction.
+    const script = generateHookScript(pointerPath)
+      .replace(`NODE_BIN="${process.execPath}"`, 'NODE_BIN="/nonexistent/node"');
+    writeFileSync(scriptPath, script, "utf-8");
+    writeFileSync(
+      pointerPath,
+      JSON.stringify({ stateFile: statePath, ledgerFile: ledgerPath, runnerPid: process.pid }),
+      "utf-8",
+    );
+    writeFileSync(statePath, JSON.stringify(buildApprovalState(NO_MCP_DEFAULT, false, new Set())), "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"));
+    // record_denial is pure bash, so the kind tag survives the Node outage too.
+    expect(ledger[0].kind).toBe("approval");
+  });
+
+  it("refuses every call when the agent has tool lists the hook cannot evaluate (Node unavailable)", () => {
+    const ws = mkdtempSync(join(tmpdir(), "hook-script-fallback-"));
+    onTestFinished(() => rmSync(ws, { recursive: true, force: true }));
+    const dir = join(ws, ".cursor", "hooks");
+    mkdirSync(dir, { recursive: true });
+    const statePath = join(dir, "state.json");
+    const ledgerPath = join(dir, "denials.jsonl");
+    const pointerPath = join(dir, "active.json");
+    const scriptPath = join(dir, "hook.sh");
+    const script = generateHookScript(pointerPath)
+      .replace(`NODE_BIN="${process.execPath}"`, 'NODE_BIN="/nonexistent/node"');
+    writeFileSync(scriptPath, script, "utf-8");
+    writeFileSync(
+      pointerPath,
+      JSON.stringify({ stateFile: statePath, ledgerFile: ledgerPath, runnerPid: process.pid }),
+      "utf-8",
+    );
+    const toolScope = compileHookToolScope({
+      scope: ToolScope.of('Agent "a"', { tools: ["Read"], disallowedTools: [] }),
+      servers: [],
+      listing: undefined,
+      platformServerSlugs: new Set(),
+      readRoot: "",
+      subAgentTypes: [],
+    });
+    writeFileSync(
+      statePath,
+      JSON.stringify(buildApprovalState(NO_MCP_DEFAULT, true, new Set(), undefined, false, false, true, false, toolScope)),
+      "utf-8",
+    );
+
+    // Even a read, in scope, is refused: the hook cannot tell, and a list it
+    // cannot read must not widen to every tool. autoApproveAll does not help.
+    const raw = execFileSync("bash", [scriptPath], { input: JSON.stringify(hookRead("/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.map((e: { kind: string }) => e.kind)).toEqual(["fail-closed"]);
+  });
+});
+
+// The agent's hooks arm (1h) and the post arm (0b), reached through the
+// runner's hook server: a server that does not answer refuses the call (a
+// hook that cannot be asked is never skipped), a call after it ran adds
+// nothing then, and an MCP call's preToolUse firing passes on to its
+// beforeMCPExecution. The arms against a real server are the gateway
+// contract's hooks section on this substrate.
+d("generated approval hook: the agent's hooks", () => {
+  const unreachable = { socketPath: join(tmpdir(), "stigmer-no-such-hooks.sock"), token: "t" };
+
+  it("refuses a call, recorded hook-unavailable, when the hook server does not answer", () => {
+    const h = setup({ hookServer: unreachable });
+    const res = h.decide({ ...hookShell("ls"), hook_event_name: "preToolUse" });
+    expect(res.permission).toBe("deny");
+    expect(res.raw).toContain("could not run this agent hooks");
+    expect(h.ledger().map((e) => e.kind), "the gate worked; the hooks could not be asked").toEqual(["hook-unavailable"]);
+  });
+
+  it("answers a call after it ran with nothing, at once, on a turn with no hook server", () => {
+    const h = setup({});
+    const after = { hook_event_name: "postToolUse", tool_name: "Shell", tool_input: { command: "ls" }, tool_output: "{}" };
+    expect(h.decide(after).raw.trim()).toBe("{}");
+    expect(h.ledger()).toEqual([]);
+    rmSync(join(h.hitlDir, "active.json"), { force: true });
+    expect(h.decide(after).raw.trim(), "with no turn at all, too").toBe("{}");
+  });
+
+  it("lets an MCP call's preToolUse firing pass to the event that names its server", () => {
+    const h = setup({ hookServer: unreachable });
+    expect(h.decide(hookMcpPreToolUse("search")).permission).toBe("allow");
+    expect(h.ledger()).toEqual([]);
+  });
+
+  it("adds nothing after a call when no hook server answers, or when the agent has none", () => {
+    const post = { hook_event_name: "postToolUse", tool_name: "Shell", tool_input: { command: "ls" } };
+    expect(setup({ hookServer: unreachable }).decide(post).raw.trim()).toBe("{}");
+    expect(setup().decide(post).raw.trim()).toBe("{}");
+  });
+
+  it("generates a client that runs on the runner's Node and answers error or {} with no server", () => {
+    const client = buildHookClientScript();
+    expect(client).not.toContain("'");
+    const run = (mode: string) =>
+      execFileSync(process.execPath, ["-e", client, unreachable.socketPath, "t", mode, "", ""], { input: "{}" }).toString();
+    expect(run("pre")).toBe("error");
+    expect(run("post")).toBe("{}");
+  });
+});
+
+// A hook's answer meets capture and the secret block as the deny-gate's own
+// answers do: an ask that trust or a grant satisfies still has a CAS-owned
+// write staged for review; a secret-like write a hook asks on is blocked,
+// never shown on a card; a hook's allow of a git-tracked write in capture
+// mode flows to the turn's review; a staged write keeps the hook's context.
+d("generated approval hook: a hook's answer under capture and the secret block", () => {
+  async function withHook(answer: object, opts: Parameters<typeof setup>[0], run: (h: ReturnType<typeof setup>) => Promise<void>): Promise<void> {
+    const evaluator = new HookEvaluator({
+      set: HookSet.of([{
+        source: { plugin: "guard", root: "", data: "", options: new Map() },
+        groups: [createMessage(HookGroupSchema, { event: "PreToolUse", matcher: "", handlers: [createMessage(HookHandlerSchema, { command: `printf '%s' '${JSON.stringify(answer)}'` })] })],
+      }]),
+      views: new CursorEngineToolViews({ workspaceRoot: "/", serverNames: new Map(), platformServerSlugs: new Set() }),
+      sessionId: "s",
+      workspaceRoot: tmpdir(),
+      permissionMode: "default",
+      baseEnv: buildShellEnv({}),
+      homeDir: tmpdir(),
+      leases: new Set(),
+    });
+    const server = await startHookServer({ evaluator, refusals: new Map(), captureMode: opts?.captureMode ?? false, globalBypass: opts?.autoApproveAll ?? false });
+    try {
+      await run(setup({ ...opts, hookServer: { socketPath: server.socketPath, token: server.token } }));
+    } finally {
+      await server.close();
+    }
+  }
+  const ask = { hookSpecificOutput: { permissionDecision: "ask" } };
+  const allowWithContext = { hookSpecificOutput: { permissionDecision: "allow", additionalContext: "logged" } };
+
+  it("stages a gitignored write a hook asked on under trust, as it stages one without hooks", async () => {
+    await withHook(ask, { autoApproveAll: true, captureMode: true, captureIgnored: true, gitignored: ["*.log"] }, async (h) => {
+      const res = await h.decideAsync({ ...hookWrite(join(h.root, "out.log"), "x"), hook_event_name: "preToolUse" });
+      expect(res.permission).toBe("allow");
+      expect((await h.observations()).captured, "staged for review").toHaveLength(1);
+    });
+  });
+
+  it("stages a gitignored write a hook asked on that a grant answers", async () => {
+    await withHook(ask, { captureMode: true, captureIgnored: true, gitignored: ["*.log"] }, async (h) => {
+      const file = join(h.root, "out.log");
+      // The approval's grant, as the resumed turn writes it into the state.
+      const statePath = join(h.hitlDir, "state.json");
+      const state = JSON.parse(readFileSync(statePath, "utf-8")) as { approvedGrantTokens: string[] };
+      state.approvedGrantTokens.push(primaryToken("write", file, contentDigest({ file_path: file, content: "x" })));
+      writeFileSync(statePath, JSON.stringify(state), "utf-8");
+      const res = await h.decideAsync({ ...hookWrite(file, "x"), hook_event_name: "preToolUse" });
+      expect(res.permission).toBe("allow");
+      expect((await h.observations()).captured, "staged for review").toHaveLength(1);
+    });
+  });
+
+  it("refuses a call a hook asks on and rewrites, though a grant holds for the call as written; under trust the rewrite runs", async () => {
+    const root = mkdtempSync(join(tmpdir(), "ask-rewrite-"));
+    onTestFinished(() => rmSync(root, { recursive: true, force: true }));
+    const file = join(root, "a.txt");
+    const askAndMove = { hookSpecificOutput: { permissionDecision: "ask", updatedInput: { file_path: join(root, "b.txt"), content: "x" } } };
+    await withHook(askAndMove, {}, async (h) => {
+      // The approval's grant for the call as the model wrote it.
+      const statePath = join(h.hitlDir, "state.json");
+      const state = JSON.parse(readFileSync(statePath, "utf-8")) as { approvedGrantTokens: string[] };
+      state.approvedGrantTokens.push(primaryToken("write", file, contentDigest({ file_path: file, content: "x" })));
+      writeFileSync(statePath, JSON.stringify(state), "utf-8");
+      const res = await h.decideAsync({ ...hookWrite(file, "x"), hook_event_name: "preToolUse" });
+      expect(res.permission).toBe("deny");
+      expect(h.ledger().map((e) => [e.kind, Buffer.from(String(e.hook), "base64").toString("utf-8")]), "the ledger carries the hook in base64").toEqual([["hook", "guard"]]);
+    });
+    await withHook(askAndMove, { autoApproveAll: true }, async (h) => {
+      const res = await h.decideAsync({ ...hookWrite(file, "x"), hook_event_name: "preToolUse" });
+      expect(JSON.parse(res.raw.trim())).toEqual({ permission: "allow", updated_input: { file_path: join(root, "b.txt"), content: "x" } });
+    });
+  });
+
+  it("lets an approved MCP call a hook asked on through, and no other call to the same tool", async () => {
+    // The grant the runner leaves for the approval of merging PR 1 (`boundary-rows.ts` approvalDigest).
+    const grant = (digest: string) => ({ toolName: "merge", mcpServerSlug: "srv", key: "srv/merge", salient: "", contentDigest: digest, sourceToolCallId: "consent-1" });
+    await withHook(ask, { grants: [grant(hookAskDigest({ pr: 1 }))] }, async (h) => {
+      expect((await h.decideAsync(hookMcp("merge", { pr: 1 }))).permission).toBe("allow");
+      expect((await h.decideAsync(hookMcp("merge", { pr: 2 }))).permission, "merging PR 2 needs its own approval").toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["approval"]);
+    });
+    await withHook(ask, { grants: [grant("")] }, async (h) => {
+      expect((await h.decideAsync(hookMcp("merge", { pr: 1 }))).permission, "a grant for the tool alone answers no hook's ask").toBe("deny");
+    });
+  });
+
+  it("blocks a secret-like write a hook asks on, never showing it on a card", async () => {
+    await withHook(ask, {}, async (h) => {
+      const res = await h.decideAsync({ ...hookWrite(join(h.root, ".env"), "TOKEN=x"), hook_event_name: "preToolUse" });
+      expect(res.permission).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["secret"]);
+      expect(h.ledger()[0]).not.toHaveProperty("input");
+    });
+  });
+
+  it("lets a git-tracked write a hook allows flow in capture mode, and blocks a secret-like one outside it", async () => {
+    await withHook(allowWithContext, { captureMode: true, gitignored: [] }, async (h) => {
+      expect((await h.decideAsync({ ...hookWrite(join(h.root, ".env"), "TOKEN=x"), hook_event_name: "preToolUse" })).permission).toBe("allow");
+    });
+    await withHook(allowWithContext, {}, async (h) => {
+      expect((await h.decideAsync({ ...hookWrite(join(h.root, ".env"), "TOKEN=x"), hook_event_name: "preToolUse" })).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.kind)).toEqual(["secret"]);
+    });
+  });
+
+  it("keeps a hook's context on a write the capture arm staged", async () => {
+    await withHook(allowWithContext, { captureMode: true, captureIgnored: true, gitignored: ["*.log"] }, async (h) => {
+      const res = await h.decideAsync({ ...hookWrite(join(h.root, "out.log"), "x"), hook_event_name: "preToolUse" });
+      expect(JSON.parse(res.raw.trim())).toEqual({ permission: "allow", additional_context: "Hook feedback:\nlogged" });
+    });
+  });
+});