@stigmer/runner 3.1.7 → 3.1.9

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

@@ -58,6 +58,8 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       // 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");
     }
   });
 
@@ -88,9 +90,17 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
   // 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", () => {
+  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, DD-26).
+    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");
   });
 
   // MCP gating runs ONLY on the beforeMCPExecution event (preToolUse does not
@@ -105,6 +115,7 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       expect(res.raw).toContain("Approve click?");
       expect(h.ledger()).toHaveLength(1);
       expect(h.ledger()[0].token).toBe(grantToken("click", ""));
+      expect(h.ledger()[0].kind).toBe("approval");
     });
 
     it("denial agent_message frames approval as automatic and never trains ask-in-prose", () => {
@@ -149,9 +160,16 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       expect(h.decide(hookMcp("click")).permission).toBe("allow");
     });
 
-    it("fails closed (deny) when the state file is missing", () => {
+    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("click", ""));
+      expect(ledger[0]).not.toHaveProperty("input");
     });
 
     it("does NOT gate the same MCP tool delivered on preToolUse (no double-gating)", () => {
@@ -422,11 +440,14 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
   // Deny-gate secret hard-block (DD-26 #2): 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 NO
-  // ledger entry, so it never becomes an approvable WAITING row; a non-secret
-  // write still deny-gates, and a delete (content-less) stays gated.
+  // 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 (DD-26: 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 (DD-26 #2)", () => {
-    it("hard-blocks a secret-like write and records NO ledger entry", () => {
+    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");
@@ -434,7 +455,12 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       // 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");
-      expect(h.ledger()).toEqual([]); // never recorded → never approvable
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].kind).toBe("secret");
+      // DD-26 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)", () => {
@@ -442,7 +468,7 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       const dec = h.decide(hookEdit(".ssh/id_rsa"));
       expect(dec.permission).toBe("deny");
       expect(dec.raw).toContain("blocked for security");
-      expect(h.ledger()).toEqual([]);
+      expect(h.ledger().map((e) => e.kind)).toEqual(["secret"]);
     });
 
     it("still deny-gates a NON-secret write and records its content for approval", () => {
@@ -451,6 +477,7 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       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", () => {
@@ -459,7 +486,8 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       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()).toEqual([]);
+      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)", () => {
@@ -467,7 +495,7 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       const dec = h.decide(hookWrite(".env", "API_KEY=abc"));
       expect(dec.permission).toBe("deny");
       expect(dec.raw).toContain("blocked for security");
-      expect(h.ledger()).toEqual([]);
+      expect(h.ledger().map((e) => e.kind)).toEqual(["secret"]);
     });
 
     it("does NOT hard-block a secret DELETE (no content; stays deny-gated)", () => {
@@ -517,19 +545,43 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("ORIGINAL");
     });
 
-    it("hard-blocks a secret-like gitignored write and records NO denial-ledger entry", async () => {
+    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: it must never enter the denial ledger (which
-      // drives WAITING_APPROVAL) — it surfaces as DIFF_UNREVIEWABLE instead.
-      expect(h.ledger()).toEqual([]);
+      // 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 (DD-26).
+      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,
@@ -594,12 +646,14 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
       expect(obs.captured[0].before).toBeNull();
     });
 
-    it("hard-blocks a secret-like write and records NO denial-ledger entry", async () => {
+    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");
-      expect(h.ledger()).toEqual([]);
+      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"]);
@@ -657,5 +711,7 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
     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");
   });
 });

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

@@ -867,6 +867,71 @@ describe("MessageAccumulator tool call status transitions", () => {
     });
   });
 
+  // The recovery supersede rule (issue #207): TOOL_CALL_INTERRUPTED is
+  // server-authored when an execution terminalizes with the call in flight. If
+  // that FAILED execution is recovered, the harness checkpoint can re-execute
+  // the call under its original call id — so INTERRUPTED is the one settled
+  // status the monotonic guard lets live execution evidence supersede in
+  // place. Every other terminal status stays immovable.
+  describe("recovery supersede of TOOL_CALL_INTERRUPTED", () => {
+    function seededInterruptedTranscript(callId: string): AgentMessage[] {
+      return [
+        create(AgentMessageSchema, {
+          type: MessageType.MESSAGE_AI,
+          content: "Running a command.",
+          toolCalls: [
+            create(ToolCallSchema, {
+              id: callId,
+              name: "Shell",
+              status: ToolCallStatus.TOOL_CALL_INTERRUPTED,
+              completedAt: "2026-07-08T00:00:00Z",
+            }),
+          ],
+        }),
+      ];
+    }
+
+    it("a replayed lifecycle event advances a seeded INTERRUPTED row to its true outcome", () => {
+      const messages = seededInterruptedTranscript("tc-replayed");
+      const acc = new MessageAccumulator(messages);
+
+      acc.processEvent(toolCallEvent("tc-replayed", "Shell", "running"));
+      expect(findToolCallById(messages, "tc-replayed")!.status).toBe(
+        ToolCallStatus.TOOL_CALL_RUNNING,
+      );
+
+      acc.processEvent(toolCallEvent("tc-replayed", "Shell", "completed", "run-1", { result: "OK" }));
+
+      expect(countToolCallsWithId(messages, "tc-replayed")).toBe(1);
+      const tc = findToolCallById(messages, "tc-replayed")!;
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+      expect(tc.result).toBe("OK");
+    });
+
+    it("a genuinely terminal seeded row (COMPLETED) still refuses to regress", () => {
+      const messages: AgentMessage[] = [
+        create(AgentMessageSchema, {
+          type: MessageType.MESSAGE_AI,
+          toolCalls: [
+            create(ToolCallSchema, {
+              id: "tc-done",
+              name: "Shell",
+              status: ToolCallStatus.TOOL_CALL_COMPLETED,
+              result: "final",
+            }),
+          ],
+        }),
+      ];
+      const acc = new MessageAccumulator(messages);
+
+      acc.processEvent(toolCallEvent("tc-done", "Shell", "running"));
+
+      expect(findToolCallById(messages, "tc-done")!.status).toBe(
+        ToolCallStatus.TOOL_CALL_COMPLETED,
+      );
+    });
+  });
+
   // Issue #179: the live thinking/tool-call trace was starved because the Cursor
   // loop's persist cadence had no force-flush for tool-call lifecycle. The
   // accumulator's isDirty signal is now the force-flush source: it MUST fire on

package/src/activities/execute-cursor/__tests__/turn-boundary.test.ts

@@ -17,7 +17,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { create } from "@bufbuild/protobuf";
+import { create, type JsonObject } from "@bufbuild/protobuf";
 import {
   AgentMessageSchema,
   ToolCallSchema,
@@ -238,6 +238,133 @@ describe("runTurnBoundary", () => {
     expect(shellCall.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
   });
 
+  // ── Issue #205: unattributed hook blocks and the kind split ────────────────
+
+  /** A FAILED tool call carrying Cursor's generic hook-block error text. */
+  function hookBlockedCall(id: string, name: string, args: JsonObject) {
+    return create(ToolCallSchema, {
+      id,
+      name,
+      status: ToolCallStatus.TOOL_CALL_FAILED,
+      error: "Command blocked by a hook.",
+      args,
+    });
+  }
+
+  /** Append one entry to this turn's denial ledger. */
+  async function appendLedgerEntry(entry: Record<string, unknown>): Promise<void> {
+    await writeFile(denialLedgerPath(hitlDir), JSON.stringify(entry) + "\n", { flag: "a" });
+  }
+
+  it("reports a foreign hook block on a non-pausing turn (the #205 silent-complete shape)", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID,
+    });
+
+    // A foreign .cursor/hooks.json hook denied the write: Cursor stamped its
+    // generic error, our ledger stayed empty, the tree is untouched. Before
+    // this fix the boundary reported a clean non-waiting turn and the run
+    // completed silently with the work undone.
+    const blocked = hookBlockedCall("tc-foreign", "edit", { path: "notes.md" });
+    status.messages.push(
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [blocked] }),
+    );
+
+    const result = await runTurnBoundary(
+      boundaryOpts(status, baseline, { foreignGatingHooks: ["./team-policy.sh"] }),
+    );
+
+    expect(result.waiting).toBe(false);
+    expect(result.unattributedHookBlocks).toEqual([
+      { toolCallId: "tc-foreign", toolName: "edit", error: "Command blocked by a hook." },
+    ]);
+    // The row itself is untouched — no gate was manufactured for a block no
+    // approval can lift; the caller fails the execution instead.
+    expect(blocked.status).toBe(ToolCallStatus.TOOL_CALL_FAILED);
+  });
+
+  it("attributes a secret hard-block (kind:'secret'): no pause, no false foreign-hook report", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID,
+    });
+
+    const secretRow = hookBlockedCall("tc-secret", "edit", { path: ".env" });
+    status.messages.push(
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [secretRow] }),
+    );
+    await writeFile(
+      denialLedgerPath(hitlDir),
+      JSON.stringify({
+        toolName: "Write", token: toolCallIdentityToken(secretRow), kind: "secret",
+      }) + "\n",
+      "utf-8",
+    );
+
+    const result = await runTurnBoundary(boundaryOpts(status, baseline));
+
+    // Not a pause (the agent was told to move on), not a foreign block (our
+    // own kinded entry attributes it), and never a WAITING_APPROVAL overlay.
+    expect(result.waiting).toBe(false);
+    expect(result.deniedToolCallCount).toBe(0);
+    expect(result.unattributedHookBlocks).toEqual([]);
+    expect(secretRow.status).toBe(ToolCallStatus.TOOL_CALL_FAILED);
+  });
+
+  it("mixed turn: pauses on our anchor while still reporting the foreign block", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID,
+    });
+
+    const ourGated = create(ToolCallSchema, {
+      id: "tc-ours", name: "shell",
+      status: ToolCallStatus.TOOL_CALL_RUNNING,
+      args: { command: "rm -rf build" },
+    });
+    const foreign = hookBlockedCall("tc-theirs", "shell", { command: "terraform apply" });
+    status.messages.push(
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [ourGated, foreign] }),
+    );
+    await appendLedgerEntry({ toolName: "shell", token: toolCallIdentityToken(ourGated), kind: "approval" });
+
+    const result = await runTurnBoundary(boundaryOpts(status, baseline));
+
+    // The pause wins (a pausing turn is never silent); the foreign block is
+    // still surfaced so the caller can log it next to the approval.
+    expect(result.waiting).toBe(true);
+    expect(ourGated.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+    expect(result.unattributedHookBlocks.map((b) => b.toolCallId)).toEqual(["tc-theirs"]);
+  });
+
+  it("excludes a kinded (secret) deny from the flowed-edit stamp (full-ledger deniedTokens)", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID,
+    });
+
+    // One edit genuinely flowed (tree changed + streamed row); one secret-like
+    // write was hard-blocked (FAILED row + kind:"secret" entry, tree untouched).
+    await write("notes.md", "original notes\nplus a real edit\n");
+    status.messages.push(streamedEdit("tc-flowed", "notes.md", "original notes\nplus a real edit\n"));
+    const secretRow = hookBlockedCall("tc-secret", "edit", { path: ".env" });
+    status.messages.push(
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [secretRow] }),
+    );
+    await appendLedgerEntry({ toolName: "Write", token: toolCallIdentityToken(secretRow), kind: "secret" });
+
+    const result = await runTurnBoundary(boundaryOpts(status, baseline));
+
+    // The flowed edit is captured + stamped; the secret-blocked row is NOT
+    // stamped into a change set that does not contain its file — every ledger
+    // kind means "this action did not execute", so the stamp uses the FULL set.
+    expect(result.waiting).toBe(true);
+    expect(result.capturedChangeCount).toBe(1);
+    expect(status.messages[0].toolCalls[0].fileChangeSetId).toBe(CHANGE_SET_ID);
+    expect(secretRow.fileChangeSetId).toBe("");
+  });
+
   it("waits for the denial-stop cancel to settle before reading the ledger", async () => {
     const status = newStatus();
     const baseline = await captureBaselineToLedger({

package/src/activities/execute-cursor/__tests__/workspace-setup.test.ts

@@ -216,6 +216,65 @@ describe("buildMergedConfig", () => {
   });
 });
 
+// ── Issue #205: foreign gating hook reporting ────────────────────────────────
+// The merge PRESERVES the user's own hooks (correct — never clobber their
+// config), but Cursor runs every configured hook and a deny from any of them
+// blocks the runner's tools without writing our denial ledger. buildMergedConfig
+// therefore reports the foreign commands left on the GATING events so the
+// runner can log the exposure and name the culprit when the turn boundary
+// detects an unattributed hook block.
+describe("buildMergedConfig — foreign gating hook reporting (issue #205)", () => {
+  const bothEvents = [
+    { event: "preToolUse", scriptPath: "/abs/hitl/stigmer-approval.sh" },
+    { event: "beforeMCPExecution", scriptPath: "/abs/hitl/stigmer-approval.sh" },
+  ];
+
+  it("reports no foreign hooks when no hooks.json exists", () => {
+    expect(buildMergedConfig(null, bothEvents).foreignGatingHooks).toEqual([]);
+  });
+
+  it("reports user commands on the gating events, ignoring non-gating events", () => {
+    const original = JSON.stringify({
+      version: 1,
+      hooks: {
+        preToolUse: [{ command: "./gate-writes.sh", failClosed: true }],
+        beforeMCPExecution: [{ command: "./gate-mcp.sh" }],
+        // postToolUse cannot deny a tool — it must not be reported.
+        postToolUse: [{ command: "./audit.sh" }],
+      },
+    });
+    const { foreignGatingHooks } = buildMergedConfig(original, bothEvents);
+    expect(foreignGatingHooks).toEqual(["./gate-writes.sh", "./gate-mcp.sh"]);
+  });
+
+  it("excludes Stigmer's own entries (current and legacy) from the report", () => {
+    const original = JSON.stringify({
+      version: 1,
+      hooks: {
+        preToolUse: [
+          { command: "/home/u/.stigmer/sessions/ses-1/hitl/stigmer-approval.sh" },
+          { command: ".cursor/hooks/stigmer-approval.sh" }, // pre-#173 legacy
+          { command: "./user.sh" },
+        ],
+      },
+    });
+    const { foreignGatingHooks } = buildMergedConfig(original, bothEvents);
+    expect(foreignGatingHooks).toEqual(["./user.sh"]);
+  });
+
+  it("ignores malformed entries without a string command", () => {
+    const original = JSON.stringify({
+      version: 1,
+      hooks: { preToolUse: [{ command: 42 }, { timeout: 5 }, null, "bare-string"] },
+    });
+    expect(buildMergedConfig(original, bothEvents).foreignGatingHooks).toEqual([]);
+  });
+
+  it("reports nothing for an unparseable hooks.json (replaced for the turn, so it cannot run)", () => {
+    expect(buildMergedConfig("{ not json", bothEvents).foreignGatingHooks).toEqual([]);
+  });
+});
+
 describe("installHitlGate / removeHitlGate", () => {
   const approvalState = buildApprovalState(new Map(), false, new Set());
 
@@ -290,6 +349,42 @@ describe("installHitlGate / removeHitlGate", () => {
     expect(existsSync(join(workspaceRoot, ".cursor", "hooks"))).toBe(false);
   });
 
+  it("surfaces the preserved foreign gating hooks on the install handle", async () => {
+    const { workspaceRoot, hitlDir } = dirs();
+    const cursorDir = join(workspaceRoot, ".cursor");
+    mkdirSync(cursorDir, { recursive: true });
+    writeFileSync(
+      join(cursorDir, "hooks.json"),
+      JSON.stringify({
+        version: 1,
+        hooks: {
+          preToolUse: [{ command: "./gate-writes.sh", failClosed: true }],
+          postToolUse: [{ command: "./audit.sh" }],
+        },
+      }),
+      "utf-8",
+    );
+
+    const handle = await installHitlGate({
+      workspaceRoot, hitlDir, approvalState, runnerPid: process.pid,
+    });
+    // The user's gating hook is preserved in the merged config AND reported on
+    // the handle (both registered events read the same preToolUse array here,
+    // so the report carries the one foreign command once per gating event it
+    // could fire on — preToolUse only, since beforeMCPExecution was absent).
+    expect(handle.foreignGatingHooks).toEqual(["./gate-writes.sh"]);
+    await removeHitlGate(handle);
+  });
+
+  it("reports no foreign hooks for a pristine workspace", async () => {
+    const { workspaceRoot, hitlDir } = dirs();
+    const handle = await installHitlGate({
+      workspaceRoot, hitlDir, approvalState, runnerPid: process.pid,
+    });
+    expect(handle.foreignGatingHooks).toEqual([]);
+    await removeHitlGate(handle);
+  });
+
   it("restores a pre-existing user hooks.json byte-for-byte after teardown", async () => {
     const { workspaceRoot, hitlDir } = dirs();
     const cursorDir = join(workspaceRoot, ".cursor");

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

@@ -56,14 +56,24 @@
  *
  * Denial ledger (hook → runner):
  * The state file is the runner's INPUT to the hook. Its symmetric OUTPUT is the
- * denial ledger (denials.jsonl): when the hook denies a tool, it appends
- * the call's identity token to this file. The runner reads the ledger after the
- * run to learn which tool calls were gated — the hook is the only component that
- * actually makes the per-call allow/deny decision, so its ledger is the
- * authoritative "what was denied this turn" signal (the cursor analog of the
- * native harness's LangGraph interrupts). The token uses the SAME identity space
- * as approvedGrantTokens, so a denial token approved this turn becomes a grant
- * token next turn.
+ * denial ledger (denials.jsonl): EVERY deny the hook issues appends the call's
+ * identity token to this file, tagged with a `kind` (see {@link DenialKind}) —
+ * so the ledger is the complete, authoritative record of what THIS hook blocked
+ * this turn (the cursor analog of the native harness's LangGraph interrupts).
+ * The kinds split by consumer semantics:
+ *
+ * - Only APPROVAL-kind entries pause the run (the first-denial stop and
+ *   reconcileDeniedToolCalls filter to them via {@link approvalDenials}); a
+ *   secret hard-block or a fail-closed deny must never surface an approval the
+ *   user cannot meaningfully grant.
+ * - The FULL ledger (all kinds) means "these actions did NOT execute": it feeds
+ *   capture stamping and DD-28 provenance, and it is the ATTRIBUTION set for
+ *   issue #205 — a hook-blocked tool call with NO ledger entry of any kind was
+ *   blocked by a FOREIGN hook (or a failed ledger append), an invariant
+ *   violation the turn boundary surfaces instead of completing silently.
+ *
+ * The token uses the SAME identity space as approvedGrantTokens, so a denial
+ * token approved this turn becomes a grant token next turn.
  */
 
 import { watch } from "node:fs";
@@ -433,12 +443,40 @@ export async function writeApprovalStateFile(
 
 const DENIAL_LEDGER_FILE = "denials.jsonl";
 
+/**
+ * The attribution taxonomy of a hook denial (mirrored byte-for-byte by the
+ * generated bash script — see hook-script.ts record_denial):
+ *
+ * - `approval`      — the normal gate: the runner surfaces it as a
+ *                     WAITING_APPROVAL pause. The ONLY kind that pauses.
+ * - `secret`        — DD-26 secret hard-block: intentional, non-pausing (the
+ *                     agent was told to move on), recorded content-free.
+ * - `capture-error` — CAS staging failed; the write stayed on the deny-gate.
+ *                     Content-free (the staging error means secret
+ *                     classification may never have run).
+ * - `fail-closed`   — the approval state file was missing, so everything gated
+ *                     denied. A turn-level "the gate itself was broken" fact.
+ *
+ * An unknown kind string is preserved as-is: it is treated as non-pausing (an
+ * unknown deny must never manufacture an approval) but still attributes the
+ * blocked call to our own hook.
+ */
+export type DenialKind = "approval" | "secret" | "capture-error" | "fail-closed";
+
+/** The one kind that pauses the run for user approval. */
+export const APPROVAL_DENIAL_KIND: DenialKind = "approval";
+
 /**
  * One denial recorded by the preToolUse hook. `token` is the call's identity in
  * the same space as grantToken() (base64 of `toolName \n salientArg`), used to
  * correlate the denial back to the streamed tool call. `toolName` is carried raw
  * for human-readable debugging of the ledger file.
  *
+ * `kind` is the attribution taxonomy entry (see {@link DenialKind}). Optional
+ * for tolerance: an entry written without one (the pre-kind ledger format, or a
+ * hand-built test fixture) is an approval-kind denial — see
+ * {@link denialKindOf}.
+ *
  * `input` is the authoritative pre-execution tool arguments the hook captured
  * from the Cursor `tool_input` payload (decoded from the ledger's base64 form).
  * It is the cursor analog of the native harness reading the AI-message tool-call
@@ -446,15 +484,33 @@ const DENIAL_LEDGER_FILE = "denials.jsonl";
  * proposed change is in hand before the tool runs. The runner overlays it onto
  * the gated tool call so the approval card can show the proposed content/diff
  * before the user approves. Absent when the hook ran its grep fallback (the Node
- * binary was unavailable), in which case the gate degrades to stream-recovered
- * args exactly as before.
+ * binary was unavailable) — the gate then degrades to stream-recovered args —
+ * and ALWAYS absent for non-approval kinds (DD-26: only an approval-kind entry
+ * may carry proposed content).
  */
 export interface DeniedLedgerEntry {
   toolName: string;
   token: string;
+  kind?: string;
   input?: Record<string, unknown>;
 }
 
+/** The effective kind of a ledger entry (absent → approval, the pre-kind format). */
+export function denialKindOf(entry: DeniedLedgerEntry): string {
+  return entry.kind || APPROVAL_DENIAL_KIND;
+}
+
+/**
+ * The entries that pause the run for user approval — the ONLY kind
+ * reconcileDeniedToolCalls may turn into WAITING_APPROVAL gates and the only
+ * kind the first-denial stop may cancel the run for. Every other consumer
+ * (capture stamping, DD-28 provenance, foreign-hook attribution) wants the FULL
+ * ledger: all kinds mean "this action did not execute".
+ */
+export function approvalDenials(entries: readonly DeniedLedgerEntry[]): DeniedLedgerEntry[] {
+  return entries.filter((e) => denialKindOf(e) === APPROVAL_DENIAL_KIND);
+}
+
 /**
  * Absolute path of the per-turn denial ledger the hook appends to, inside the
  * session's runner-owned HITL directory (never the user's workspace).
@@ -540,11 +596,19 @@ export async function readDenialLedger(
     const trimmed = line.trim();
     if (!trimmed) continue;
     try {
-      const obj = JSON.parse(trimmed) as { toolName?: unknown; token?: unknown; input?: unknown };
+      const obj = JSON.parse(trimmed) as {
+        toolName?: unknown;
+        token?: unknown;
+        kind?: unknown;
+        input?: unknown;
+      };
       if (typeof obj.token === "string" && obj.token) {
         entries.push({
           toolName: typeof obj.toolName === "string" ? obj.toolName : "",
           token: obj.token,
+          // A garbled/missing kind degrades to undefined → approval (the
+          // pre-kind format); see denialKindOf.
+          kind: typeof obj.kind === "string" && obj.kind ? obj.kind : undefined,
           input: decodeLedgerInput(obj.input),
         });
       }