@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

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

@@ -31,17 +31,28 @@
  */
 
 import { create } from "@bufbuild/protobuf";
+import type { JsonObject } from "@bufbuild/protobuf";
 import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
 import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
-import { MessageType, ToolCallStatus, SubAgentStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { MessageType, ToolCallStatus, SubAgentStatus, ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { SDKMessage } from "@cursor/sdk";
 import type { MergedToolPolicy } from "./approval-policy.js";
-import { lookupMcpToolPolicy, resolveApprovalMessage, builtInRequiresApproval, getBuiltInApprovalMessage } from "./approval-policy.js";
-import { grantToken, toolIdentity, type DeniedLedgerEntry } from "./approval-state.js";
+import { lookupMcpToolPolicy, resolveApprovalMessage, builtInRequiresApproval, getBuiltInApprovalMessage, SALIENT_ARG_FIELDS } from "./approval-policy.js";
+import {
+  POLICY_ENGINE_VERSION,
+  resolveApprovalProvenance,
+  toProtoPolicySource,
+} from "../../shared/approval-policy.js";
+import { grantToken, primaryToken, toolIdentity, type DeniedLedgerEntry } from "./approval-state.js";
 import { utcTimestamp } from "../../shared/status.js";
-import { classifyTool } from "../../shared/tool-kind.js";
+import { hideToolCallRow, isToolCallRowHidden } from "../../shared/tool-row.js";
+import { classifyTool, toolApprovalCategory, type ToolApprovalCategory } from "../../shared/tool-kind.js";
+import { resolveWorkspacePath } from "../../shared/file-change.js";
+import { contentDigest } from "../../shared/file-tools.js";
+import { buildElidedArgsPreview } from "../../shared/args-preview.js";
+import type { WorkspaceBackend } from "../../shared/workspace/types.js";
 
 export { utcTimestamp };
 
@@ -163,10 +174,17 @@ function translateToolCall(event: Extract<SDKMessage, { type: "tool_call" }>): A
  *
  * Approval fields are populated when mergedPolicies are provided.
  * Without policies, only basic fields are set (backward compatible).
+ *
+ * When mergedPolicies are provided, the tool call also carries its authorization
+ * provenance (approval_policy_source) — which policy layer gated or cleared it —
+ * derived from the same merged policy chain the gate uses, so the Cursor
+ * reconstruction is as auditable as the native harness. `provenance` supplies the
+ * run-scoped context (global bypass, active leases) the per-tool map cannot.
  */
 export function buildToolCallProto(
   event: Extract<SDKMessage, { type: "tool_call" }>,
   mergedPolicies?: Map<string, MergedToolPolicy>,
+  provenance?: ApprovalProvenanceContext,
 ): ToolCall {
   const status = mapToolCallStatus(event.status);
   const mcpDetails = extractMcpToolDetails(event);
@@ -231,9 +249,38 @@ export function buildToolCallProto(
     }
   }
 
+  // Stamp authorization provenance from the same merged policy chain the gate
+  // (the deny-oracle hook + this map) uses, so the persisted record explains WHY
+  // each tool was gated or cleared. Only when policies are present — the stateless
+  // path leaves it UNSPECIFIED, like an unclassified tool_kind.
+  if (mergedPolicies) {
+    const source = resolveApprovalProvenance(
+      actualName,
+      mcpServerSlug,
+      mergedPolicies,
+      provenance?.leasedCategories ?? NO_LEASED_CATEGORIES,
+      provenance?.globalBypass ?? false,
+    );
+    toolCall.approvalPolicySource = toProtoPolicySource(source);
+    if (source) toolCall.policyEngineVersion = POLICY_ENGINE_VERSION;
+  }
+
   return toolCall;
 }
 
+/**
+ * Run-scoped approval context the Cursor reconstruction needs to attribute a tool
+ * call's provenance beyond the per-tool merged policy map: the pre-armed global
+ * bypass and the built-in categories holding a run-lifetime lease.
+ */
+export interface ApprovalProvenanceContext {
+  readonly globalBypass: boolean;
+  readonly leasedCategories: ReadonlySet<ToolApprovalCategory>;
+}
+
+/** Shared empty set so a reconstruction without leases allocates nothing. */
+const NO_LEASED_CATEGORIES: ReadonlySet<ToolApprovalCategory> = new Set();
+
 function translateTask(event: Extract<SDKMessage, { type: "task" }>): AgentMessage {
   return create(AgentMessageSchema, {
     type: MessageType.MESSAGE_SYSTEM,
@@ -432,14 +479,25 @@ function blockText(b: Record<string, unknown>): string | undefined {
  *
  * The Cursor SDK returns sub-agent work as a blob in the task tool's
  * completed event (not as streaming events with a distinct agent_id).
+ * Re-verified 2026-07-02 with live recordings on both the pinned SDK (1.0.13)
+ * and the latest (1.0.22): zero events reach the parent's run.stream() between
+ * the task tool's "running" and "completed" events, every event carries the
+ * parent's agent_id, and the child agentId visible in the task args at spawn
+ * is NOT queryable mid-run through any public read surface (Agent.listRuns /
+ * Agent.messages.list / Agent.getRun all return not-found for it; the SDK's
+ * on-disk sub-agent transcript is written only at completion). Live nested
+ * visibility is therefore an upstream SDK limitation — do not try to fake it
+ * here; the UI shows an elapsed-time affordance instead (SubAgentSection).
  * The result shape is:
  *
  *   { status: "success", value: { conversationSteps: ConversationStep[] } }
  *
- * where ConversationStep is a discriminated union:
- *   - { type: "thinkingMessage", message: { text, thinkingDurationMs? } }
- *   - { type: "assistantMessage", message: { text } }
- *   - { type: "toolCall", message: { type, args, result?, ... } }
+ * where each ConversationStep is a protobuf-oneof object keyed DIRECTLY by its
+ * kind (there is NO `{ type, message }` envelope — verified against production
+ * sub-agent blobs; see the `buildSubAgentToolCall` note):
+ *   - { thinkingMessage: { text, thinkingDurationMs? } }
+ *   - { assistantMessage: { text } }
+ *   - { toolCall: { toolCallId, <kind>ToolCall: { args, result } } }
  *
  * This function defensively parses whatever steps are present and
  * appends corresponding AgentMessage protos to the output array.
@@ -484,56 +542,172 @@ export function extractConversationSteps(
           timestamp: utcTimestamp(),
         }));
       }
-    } else if (type === "toolCall") {
-      const msg = s.message as Record<string, unknown> | undefined;
-      if (msg) {
-        const toolName = typeof msg.type === "string" ? msg.type : "unknown";
-        const toolArgs = msg.args != null ? JSON.stringify(msg.args) : "";
-        let toolResult = "";
-        if (msg.result != null) {
-          const resultObj = msg.result as Record<string, unknown>;
-          if (resultObj.status === "success" && resultObj.value != null) {
-            // Normalize a sub-agent screenshot the same way as a top-level tool
-            // result; fall back to the existing value serialization otherwise.
-            toolResult = canonicalizeImageResult(resultObj.value)
-              ?? (typeof resultObj.value === "string"
-                ? resultObj.value
-                : JSON.stringify(resultObj.value));
-          } else if (resultObj.status === "error") {
-            toolResult = typeof resultObj.error === "string"
-              ? resultObj.error
-              : JSON.stringify(resultObj);
-          } else {
-            toolResult = JSON.stringify(msg.result);
-          }
-        }
-
-        const aiMsg = create(AgentMessageSchema, {
+    } else if (s.toolCall != null) {
+      const tc = buildSubAgentToolCall(s.toolCall, out.length);
+      if (tc) {
+        out.push(create(AgentMessageSchema, {
           type: MessageType.MESSAGE_AI,
           content: "",
           timestamp: utcTimestamp(),
-          toolCalls: [create(ToolCallSchema, {
-            id: `sub-${toolName}-${out.length}`,
-            name: toolName,
-            status: ToolCallStatus.TOOL_CALL_COMPLETED,
-            argsPreview: toolArgs,
-            result: toolResult,
-            startedAt: utcTimestamp(),
-            completedAt: utcTimestamp(),
-            toolKind: classifyTool(toolName),
-          })],
-        });
-        out.push(aiMsg);
+          toolCalls: [tc],
+        }));
       }
     }
   }
 }
 
+/**
+ * The failure branches of a sub-agent tool call's `result` oneof. A completion
+ * is `{ success: ... }`; every other branch is a non-completion the UI must show
+ * as failed — an errored read/glob/grep (`error`), or a shell the approval gate
+ * stopped (`permissionDenied` / `rejected`).
+ */
+const SUBAGENT_TOOL_RESULT_FAILURE_KEYS = new Set([
+  "error",
+  "permissionDenied",
+  "rejected",
+]);
+
+/**
+ * Build a ToolCall proto from one sub-agent `toolCall` conversation step.
+ *
+ * The Cursor SDK serializes a sub-agent's tool call as protobuf-oneof JSON:
+ *
+ *   { toolCallId, <kind>ToolCall: { args, result } }
+ *
+ * The tool family is the lone `<kind>ToolCall` sibling of `toolCallId` (e.g.
+ * `readToolCall`, `globToolCall`, `grepToolCall`, `shellToolCall`); the bare
+ * tool name (`read`) is the suffix-stripped key, which feeds the shared
+ * {@link classifyTool} exactly like a top-level call. `result` is itself a oneof
+ * `{ success | error | permissionDenied | rejected }` (see
+ * {@link interpretSubAgentToolResult}).
+ *
+ * This is deliberately key-driven rather than an enumerated switch, so a new
+ * tool family the SDK adds surfaces automatically instead of being dropped.
+ * Returns undefined when no `<kind>ToolCall` key is present (a malformed or
+ * forward-incompatible step), so the caller skips it rather than emitting a
+ * blank, nameless tool call.
+ *
+ * History: an earlier revision parsed a `{ type: "toolCall", message: { type,
+ * args, result: { status, value } } }` envelope. That shape never appears in the
+ * real task-result blob (confirmed against production sub-agent outputs and the
+ * WA03 capture), so every sub-agent tool call was silently discarded and the UI
+ * showed a sub-agent that "did nothing".
+ */
+function buildSubAgentToolCall(
+  toolCall: unknown,
+  seq: number,
+): ToolCall | undefined {
+  if (toolCall == null || typeof toolCall !== "object") return undefined;
+  const obj = toolCall as Record<string, unknown>;
+
+  const kindKey = Object.keys(obj).find(
+    (k) => k !== "toolCallId" && k.endsWith("ToolCall"),
+  );
+  if (!kindKey) return undefined;
+
+  const name = kindKey.slice(0, -"ToolCall".length);
+  const inner =
+    obj[kindKey] != null && typeof obj[kindKey] === "object"
+      ? (obj[kindKey] as Record<string, unknown>)
+      : {};
+  // Prefer the SDK's real call id so the row is stable across resumes and never
+  // collides with a sibling; fall back to a per-step synthetic id only when the
+  // SDK omits one.
+  const id =
+    typeof obj.toolCallId === "string" && obj.toolCallId
+      ? obj.toolCallId
+      : `sub-${name}-${seq}`;
+
+  const { status, result, error } = interpretSubAgentToolResult(inner.result);
+
+  const tc = create(ToolCallSchema, {
+    id,
+    name,
+    status,
+    result,
+    error,
+    startedAt: utcTimestamp(),
+    completedAt: utcTimestamp(),
+    toolKind: classifyTool(name),
+  });
+
+  if (inner.args != null && typeof inner.args === "object") {
+    tc.args = inner.args as JsonObject;
+    tc.argsPreview = JSON.stringify(inner.args);
+  }
+  return tc;
+}
+
+/**
+ * Map a sub-agent tool call's `result` oneof to a (status, result, error)
+ * triple. `success` → COMPLETED with the serialized payload (a screenshot is
+ * canonicalized the same way as a top-level result); any failure branch (see
+ * {@link SUBAGENT_TOOL_RESULT_FAILURE_KEYS}) → FAILED with the serialized
+ * detail. An absent result is a COMPLETED call with no output — the SDK omits
+ * `result` for a call that reports nothing.
+ */
+function interpretSubAgentToolResult(result: unknown): {
+  status: ToolCallStatus;
+  result: string;
+  error: string;
+} {
+  if (result == null || typeof result !== "object") {
+    return { status: ToolCallStatus.TOOL_CALL_COMPLETED, result: "", error: "" };
+  }
+  const r = result as Record<string, unknown>;
+
+  if ("success" in r) {
+    const val = r.success;
+    const str =
+      canonicalizeImageResult(val) ??
+      (typeof val === "string" ? val : JSON.stringify(val));
+    return { status: ToolCallStatus.TOOL_CALL_COMPLETED, result: str, error: "" };
+  }
+
+  const failKey = Object.keys(r).find((k) =>
+    SUBAGENT_TOOL_RESULT_FAILURE_KEYS.has(k),
+  );
+  if (failKey) {
+    const val = r[failKey];
+    const detail = typeof val === "string" ? val : JSON.stringify(val);
+    return { status: ToolCallStatus.TOOL_CALL_FAILED, result: "", error: detail };
+  }
+
+  // Unknown oneof branch — surface it as a completed result rather than drop it.
+  return {
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    result: JSON.stringify(r),
+    error: "",
+  };
+}
+
 /**
  * Options for creating a MessageAccumulator with policy awareness.
  */
 export interface MessageAccumulatorOptions {
   mergedPolicies?: Map<string, MergedToolPolicy>;
+  /**
+   * Run-scoped approval context (global bypass + active leases) so reconstructed
+   * tool calls carry their authorization provenance. Omitted in unit tests that
+   * only assert basic translation; provenance then stays UNSPECIFIED.
+   */
+  provenance?: ApprovalProvenanceContext;
+  /**
+   * Absolute workspace root, used to render file-change paths relative to the
+   * workspace (with the absolute path retained). Omitted in unit tests, in
+   * which case raw tool-arg paths are used verbatim.
+   */
+  workspaceRoot?: string;
+  /**
+   * Sub-agent executions carried over from the persisted transcript on a
+   * durable resume (see seedCursorTranscriptFromExecution in index.ts). The
+   * accumulator re-registers them so a sub-agent's resumed lifecycle updates
+   * merge onto the seeded row instead of producing a duplicate, and so the row
+   * survives the round-trip rather than being dropped from the rebuilt status.
+   * Empty on a first run.
+   */
+  seededSubAgents?: SubAgentExecution[];
 }
 
 /**
@@ -596,12 +770,44 @@ export class MessageAccumulator {
   private readonly _subAgentExecutions: SubAgentExecution[] = [];
   private readonly subAgentMap = new Map<string, SubAgentExecution>();
   private readonly mergedPolicies?: Map<string, MergedToolPolicy>;
+  private readonly provenance?: ApprovalProvenanceContext;
+  private readonly workspaceRoot?: string;
   private readonly toolCallIndex = new Map<string, ToolCall>();
   private _dirty = false;
 
   constructor(messages: AgentMessage[], options?: MessageAccumulatorOptions) {
     this.messages = messages;
     this.mergedPolicies = options?.mergedPolicies;
+    this.provenance = options?.provenance;
+    this.workspaceRoot = options?.workspaceRoot;
+
+    // Resume seeding. When constructed over a pre-seeded transcript (a durable
+    // resume — see seedCursorTranscriptFromExecution in index.ts), rebuild the
+    // by-id tool-call index so a cross-message completion for a seeded call
+    // resolves onto the existing proto, and re-register seeded sub-agents so
+    // their resumed lifecycle updates merge in place. A first run carries an
+    // empty transcript and no seed, so both are no-ops. Mirrors the deep-agent
+    // ExecutionState.rebuildToolCallIndex + sub-agent re-registration on resume.
+    this.rebuildToolCallIndex();
+    for (const sub of options?.seededSubAgents ?? []) {
+      this._subAgentExecutions.push(sub);
+      if (sub.id) this.subAgentMap.set(sub.id, sub);
+    }
+  }
+
+  /**
+   * Index every tool call already present in the (seeded) transcript by its
+   * call_id. Called once at construction: on a first run the transcript is empty
+   * (no-op); on a resume it lets re-emitted lifecycle events for a previously
+   * committed call_id reconcile onto the existing proto instead of duplicating.
+   */
+  private rebuildToolCallIndex(): void {
+    this.toolCallIndex.clear();
+    for (const message of this.messages) {
+      for (const tc of message.toolCalls) {
+        if (tc.id) this.toolCallIndex.set(tc.id, tc);
+      }
+    }
   }
 
   get subAgentExecutions(): SubAgentExecution[] {
@@ -696,17 +902,62 @@ export class MessageAccumulator {
     if (SUPPRESSED_TOOL_NAMES.has(event.name)) return;
 
     const existing = this.toolCallIndex.get(event.call_id);
-    if (!existing) {
-      const tc = buildToolCallProto(event, this.mergedPolicies);
-      this.findOrCreateLastAiMessage().toolCalls.push(tc);
-      this.toolCallIndex.set(event.call_id, tc);
-      // A new tool call is a discrete, user-visible event — force a prompt
-      // flush so the live UI surfaces it the instant it starts.
-      this._dirty = true;
+    if (existing) {
+      this.mergeToolCallEvent(existing, event);
+      return;
+    }
+
+    const tc = buildToolCallProto(event, this.mergedPolicies, this.provenance);
+
+    // Resume reconciliation. A resumed Cursor agent re-runs a previously
+    // approved tool with a BRAND-NEW call_id, so it misses the by-id index
+    // above. Reconcile it onto the seeded WAITING_APPROVAL call with the same
+    // canonical identity (the (category, salient)/MCP-name space the hook and
+    // grants already use — see toolCallIdentityToken) and keep the original id.
+    // Without this the seeded approved call and the re-run would both appear (a
+    // duplicate row) and dropping the seeded id would trip the backend's
+    // append-only-at-identity guard, stalling the run. This generalizes the v2
+    // deep-agent StatusBuilder.findResumableSeededToolCall (a tool-name match)
+    // to the full Cursor identity, reusing the single existing identity
+    // definition rather than introducing a parallel one.
+    const seeded = this.findResumableSeededToolCall(tc);
+    if (seeded) {
+      // Re-key the fresh call_id onto the seeded proto so this call_id's later
+      // lifecycle events resolve here, then merge in place. mergeToolCallEvent
+      // advances WAITING_APPROVAL (non-terminal) toward the event's status.
+      this.toolCallIndex.set(event.call_id, seeded);
+      this.mergeToolCallEvent(seeded, event);
       return;
     }
 
-    this.mergeToolCallEvent(existing, event);
+    this.findOrCreateLastAiMessage().toolCalls.push(tc);
+    this.toolCallIndex.set(event.call_id, tc);
+    // A new tool call is a discrete, user-visible event — force a prompt
+    // flush so the live UI surfaces it the instant it starts.
+    this._dirty = true;
+  }
+
+  /**
+   * Find a seeded, still-gated tool call this resumed event should reconcile
+   * onto: the first tool call in the index that is still WAITING_APPROVAL and
+   * shares the candidate's canonical identity token. "First" (Map iteration =
+   * transcript order) mirrors the v2 deep-agent's ordered first-unreconciled
+   * match — once reconciled a call leaves WAITING_APPROVAL, so a second co-
+   * pending call with the same identity naturally reconciles onto the next one.
+   * Tool calls created during this turn are not WAITING_APPROVAL until the
+   * post-stream denial reconciliation runs, so they can never be matched here.
+   */
+  private findResumableSeededToolCall(candidate: ToolCall): ToolCall | undefined {
+    const wanted = toolCallIdentityToken(candidate);
+    for (const tc of this.toolCallIndex.values()) {
+      if (
+        tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL &&
+        toolCallIdentityToken(tc) === wanted
+      ) {
+        return tc;
+      }
+    }
+    return undefined;
   }
 
   /**
@@ -902,76 +1153,682 @@ export class MessageAccumulator {
  * approved once should produce one approval regardless of how many times the
  * agent re-attempted it within the turn.
  *
- * If a ledger denial has no matching streamed tool call (rare — Cursor normally
- * emits a tool_call event for every attempt), a placeholder WAITING_APPROVAL
- * tool call is synthesized so the gate still surfaces and never renders as a
- * silent success.
+ * ONE GATE PER TURN (deny-only clean pause). The Cursor harness can only gate by
+ * the hook returning `deny`, which Cursor surfaces to the model as a tool
+ * *failure* — so a blocked model frequently improvises a workaround (the
+ * canonical case: a denied `edit notes.md` followed ~2.5s later by a
+ * `shell: cat > notes.md`, in the SAME assistant message with no narration
+ * between them — observed in production, exec aex_01kw4p0cqgk0j8vvxbs5t8gv59).
+ * The first-denial stop (index.ts) tries to cancel the turn at that first
+ * denial, but `run.cancel()` is async and races the SDK's auto-execution, so the
+ * workaround can still stream and land a SECOND denial in the ledger. Two
+ * denials of distinct identity would otherwise surface two approval cards for
+ * one logical intent. Their identities differ (`write\nnotes.md` vs
+ * `shell\ncat > notes.md`), so no same-identity twin collapse can join them, and
+ * they share one message, so no positional rule can separate them; the only
+ * honest signal that the second is a reaction is CAUSALITY — it was emitted
+ * after the model saw the first denial. We therefore ANCHOR on the FIRST ledger
+ * denial of the turn (the ledger is reset per turn and appended in denial order,
+ * so ledger[0] is the original intent) and surface ONLY that identity. Every
+ * other denied identity in the turn — a post-denial workaround, or a genuine
+ * co-pending sibling the deny-only harness defers — is blanked in place to a
+ * hidden SKIPPED row ({@link collapseNonAnchorDenials}). A deferred sibling is
+ * not lost: on resume it re-attempts and gates again next turn (sequential
+ * gating). The native (LangGraph) harness pauses BEFORE the model can react, so
+ * it keeps full in-turn co-pending and is untouched by this rule. This is the
+ * near-term, invariant-preserving stepping stone to the Tool Execution Gateway,
+ * where an un-leased workaround is refused by construction.
+ *
+ * Correlation runs in two passes. The first matches the streamed token to a
+ * ledger token byte-for-byte (the common case). The hook, however, records its
+ * token from the RAW path Cursor hands it — a bash script cannot normalize a
+ * path against the workspace root — so an ABSOLUTE hook `file_path` against a
+ * RELATIVE stream `path` (or vice versa) yields two different raw tokens for one
+ * edit and the exact pass misses. The runner CAN normalize, so a second pass
+ * matches any still-unmatched FILE denial to a streamed call by (category,
+ * workspace-normalized path) and overlays the REAL streamed call, never appending
+ * a content-less placeholder beside it. This is the difference between one honest
+ * gate and two cards, one of which reads "No preview available". It reuses the
+ * single tool-identity definition + `resolveWorkspacePath`; it introduces no
+ * parallel identity.
  *
- * Returns the tool calls now marked WAITING_APPROVAL (overlaid + synthesized).
+ * Only after BOTH passes miss is a placeholder WAITING_APPROVAL tool call
+ * synthesized (rare — Cursor normally emits a tool_call event for every
+ * attempt), so the gate still surfaces and never renders as a silent success.
+ * Critically, every match overlays a call IN PLACE (the committed id is
+ * preserved): the backend's append-only-at-identity transcript guard rejects a
+ * finalize that drops a previously-committed tool-call id, so reconciliation may
+ * only reconcile entries in place, never remove them.
+ *
+ * Every matched/synthesized call is enriched with the hook-captured authoritative
+ * input (`ledger.input`) via {@link applyGateInput}: the full proposed args, a
+ * compact `args_preview`, and the content digest — so the approval card renders
+ * the proposed write/edit content from `args` and a resume re-gates a diverging
+ * sibling edit. A missing capture (the hook's grep fallback) degrades to the
+ * prior behavior.
+ *
+ * Returns the tool calls now marked WAITING_APPROVAL — the single anchor gate
+ * for the turn (overlaid or, rarely, synthesized).
  */
-export function reconcileDeniedToolCalls(
+export async function reconcileDeniedToolCalls(
   messages: AgentMessage[],
   ledger: DeniedLedgerEntry[],
   mergedPolicies?: Map<string, MergedToolPolicy>,
-): ToolCall[] {
+  workspaceBackend?: WorkspaceBackend,
+): Promise<ToolCall[]> {
   if (ledger.length === 0) return [];
 
-  // One approval per denied identity; a resource re-attempted within the turn
-  // is gated under the same token and collapses to a single approval.
+  // The workspace the gated files live in; its rootDir normalizes paths for the
+  // abs-vs-rel correlation fallback (normalizedFileSalient).
+  const workspaceRoot = workspaceBackend?.rootDir;
+
+  // One gate per turn: anchor on the FIRST ledger denial. The ledger is reset
+  // per turn and appended in denial order, so ledger[0] is the model's original
+  // intent; any later denial of a DIFFERENT identity is a post-denial workaround
+  // or a deferred co-pending sibling (see the doc comment). We surface ONLY the
+  // anchor identity below and blank every other denied identity to a hidden
+  // SKIPPED row. `deniedTokens` still carries every denied identity — it is the
+  // scope for that collapse, never an additional gate.
+  const anchorToken = ledger[0].token;
   const deniedTokens = new Set(ledger.map((e) => e.token));
-  const matched = new Set<string>();
+  // The authoritative pre-execution args the hook captured for the anchor. A
+  // resource re-attempted within the turn shares a token; last write wins (the
+  // attempts carry the same proposed change).
+  let anchorInput: Record<string, unknown> | undefined;
+  for (const e of ledger) {
+    if (e.token === anchorToken && e.input) anchorInput = e.input;
+  }
+  const matchedCalls = new Set<ToolCall>();
   const result: ToolCall[] = [];
+  let anchorMatched = false;
 
-  // 1. Overlay WAITING_APPROVAL onto the streamed tool calls that were denied.
+  // 1. Exact overlay: a streamed call whose token equals the anchor denial token
+  //    byte-for-byte (the path form agreed on both sides). The anchor resource
+  //    re-attempted within the turn shares one token and collapses to a single
+  //    approval (the first match is the keeper; same-identity twins are blanked
+  //    by collapseRedundantToolCallTwins below).
   for (const msg of messages) {
+    if (anchorMatched) break;
     for (const tc of msg.toolCalls) {
-      const token = toolCallIdentityToken(tc);
-      if (!deniedTokens.has(token) || matched.has(token)) continue;
-      markWaitingApproval(tc, mergedPolicies);
-      matched.add(token);
+      if (toolCallIdentityToken(tc) !== anchorToken) continue;
+      overlayDeniedStreamCall(tc, anchorInput, mergedPolicies);
+      matchedCalls.add(tc);
       result.push(tc);
+      anchorMatched = true;
+      break;
     }
   }
 
-  // 2. Synthesize a tool call for any denial that never produced a stream event.
-  // Rare with correct correlation (Cursor emits a tool_call for every attempt),
-  // so this is a defensive net that still surfaces the gate rather than letting
-  // a denied tool render as a silent success.
-  for (const entry of ledger) {
-    if (matched.has(entry.token)) continue;
-    const decoded = decodeIdentityToken(entry.token);
+  // 2. Normalized-path fallback (the abs-vs-rel drift fix): if the anchor is a
+  //    FILE denial the exact pass missed, match a streamed call by (category,
+  //    workspace-normalized path) and overlay the REAL call — never a content-
+  //    less placeholder beside it. Requires the workspace root to normalize;
+  //    shell/MCP denials (no path) and resumes without a root fall through to
+  //    synthesis.
+  if (!anchorMatched && workspaceRoot) {
+    const decoded = decodeIdentityToken(anchorToken);
+    const wanted = decoded
+      ? normalizedFileSalient(decoded.key, decoded.salient, workspaceRoot)
+      : undefined;
+    if (wanted) {
+      const tc = findUnmatchedStreamCallByNormalizedSalient(
+        messages, matchedCalls, wanted, workspaceRoot,
+      );
+      if (tc) {
+        overlayDeniedStreamCall(tc, anchorInput, mergedPolicies);
+        matchedCalls.add(tc);
+        result.push(tc);
+        anchorMatched = true;
+      }
+    }
+  }
+
+  // 2a. One gate per turn: blank every denied identity OTHER than the anchor to a
+  //     hidden SKIPPED row (the workaround shell, or a deferred co-pending
+  //     sibling). Runs BEFORE the WAITING_FOR_APPROVAL persist so a reaction is
+  //     never persisted as WAITING_APPROVAL — the backend authors an approval
+  //     REQUESTED event only from a WAITING_APPROVAL tool call, so collapsing
+  //     here keeps the append-only approval-event stream free of an orphan
+  //     REQUESTED that would need retraction.
+  const nonAnchorCollapsed = collapseNonAnchorDenials(messages, deniedTokens, anchorToken);
+  if (nonAnchorCollapsed > 0) {
+    console.log(
+      `ExecuteCursor reconcile collapsed ${nonAnchorCollapsed} non-anchor denied ` +
+        `tool call(s) to hidden SKIPPED (one gate per turn; anchor is the first ` +
+        `denial of the turn)`,
+    );
+  }
+
+  // 2b. Collapse same-turn duplicate edits. When the model emitted the SAME
+  //     resource twice in one turn (two call ids, one identity token), only the
+  //     FIRST same-token stream call was overlaid into the gate above; any OTHER
+  //     same-token call stays a committed row (RUNNING zombie, or a
+  //     denied-reported-as-success COMPLETED) that would render as a second,
+  //     content-less card beside the gate (the reported "No preview available"
+  //     duplicate). The overlaid gate is now WAITING_APPROVAL, so the shared
+  //     routine recognizes it as the keeper and blanks the twins IN PLACE to
+  //     hidden SKIPPED rows — we cannot drop them, since the backend's
+  //     append-only-at-identity guard rejects removing a previously-committed
+  //     tool-call id, but the id is preserved so the finalize stays append-only.
+  const collapsed = collapseRedundantToolCallTwins(messages);
+  if (collapsed > 0) {
+    console.log(
+      `ExecuteCursor reconcile collapsed ${collapsed} redundant tool-call twin(s) ` +
+        `superseded by the approval gate (kept in place as hidden SKIPPED rows)`,
+    );
+  }
+
+  // 2c. Finalize interrupted rows. The first-denial stop cancelled the run, so
+  //     a tool call still PENDING/RUNNING here can never complete — no event
+  //     will ever deliver its result, and left alone it persists as a spinner
+  //     forever. The canonical victim is a post-denial workaround whose own
+  //     hook denial raced (or never reached) the final ledger read, so the
+  //     token-scoped collapse in 2a could not see it (production case
+  //     aex_01kwj07f7g23c3wp9sn8496z5g: a python-write shell reaction persisted
+  //     as RUNNING with requiresApproval=true). Whatever the cause, a
+  //     non-terminal row on a turn that is pausing is an interrupted attempt
+  //     with no output: collapse it to the same hidden SKIPPED shape as every
+  //     other superseded row (in place — the append-only-at-identity guard
+  //     forbids dropping a committed id). Runs AFTER the anchor overlay, so the
+  //     gate itself (now WAITING_APPROVAL) is never touched.
+  const interrupted = finalizeInterruptedToolCalls(messages);
+  if (interrupted > 0) {
+    console.log(
+      `ExecuteCursor reconcile collapsed ${interrupted} interrupted non-terminal ` +
+        `tool call(s) that can never complete (run cancelled at first denial)`,
+    );
+  }
+
+  // 3. Synthesize the anchor gate if it matched NO streamed call in either pass
+  //    (rare — Cursor emits a tool_call event for every attempt), so the gate
+  //    still surfaces rather than rendering as a silent success. After the
+  //    normalized fallback this should be ~0; the caller logs a divergence when
+  //    it is not (a synthesized id is prefixed `approval:`). Only the anchor is
+  //    ever synthesized: non-anchor denials are deliberately collapsed, never
+  //    surfaced (one gate per turn).
+  if (!anchorMatched) {
+    const anchorEntry = ledger.find((e) => e.token === anchorToken) ?? ledger[0];
+    const decoded = decodeIdentityToken(anchorToken);
     // Display the hook's raw tool name; carry the decoded salient so the grant
     // rebuilt from this tool call on reinvocation keys on the same resource.
-    const displayName = entry.toolName || decoded?.key || "tool";
+    const displayName = anchorEntry.toolName || decoded?.key || "tool";
     const salient = decoded?.salient ?? "";
-    const tc = synthesizeWaitingApprovalToolCall(displayName, salient, entry.token, mergedPolicies);
+    const tc = synthesizeWaitingApprovalToolCall(
+      displayName, salient, decoded?.digest ?? "", anchorToken, mergedPolicies,
+    );
+    // The hook-captured input upgrades the placeholder from a bare {path} to the
+    // full proposed args, so even a synthesized gate shows the proposed change.
+    applyGateInput(tc, anchorInput ?? anchorEntry.input);
     appendToolCallToLastAiMessage(messages, tc);
-    matched.add(entry.token);
     result.push(tc);
   }
 
   return result;
 }
 
+/**
+ * Overlay WAITING_APPROVAL onto a streamed tool call the hook denied. Mutates
+ * `tc` in place — the call keeps its committed id, so the backend's
+ * append-only-at-identity transcript guard accepts the finalize (an in-place
+ * status change is a reconcile, not a drop). The single overlay routine for both
+ * the exact and the normalized correlation passes, so the gate diff can never
+ * diverge between them. The hook-captured `input` (when present) is the
+ * authoritative, complete proposed args — the stream may have carried only
+ * partial args before the first-denial cancel — so it supplies the args preview
+ * and the content digest (see {@link applyGateInput}).
+ */
+function overlayDeniedStreamCall(
+  tc: ToolCall,
+  input: Record<string, unknown> | undefined,
+  mergedPolicies: Map<string, MergedToolPolicy> | undefined,
+): void {
+  markWaitingApproval(tc, mergedPolicies);
+  applyGateInput(tc, input);
+}
+
+/**
+ * Collapse every tool call still in a non-terminal state (PENDING / RUNNING)
+ * to the hidden SKIPPED row shape, returning how many were collapsed.
+ *
+ * Called only on the pause-for-approval path, after the anchor gate has been
+ * overlaid to WAITING_APPROVAL: the run was cancelled, so nothing will ever
+ * complete these calls, and a permanently-RUNNING row would render as an
+ * eternal spinner beside the approval card. This is the causality sibling of
+ * {@link collapseNonAnchorDenials}: that collapse is token-scoped (it needs the
+ * denial in the ledger), while this one catches the attempt whose hook denial
+ * raced the final ledger read or whose execution the cancel interrupted
+ * outright — either way an attempt with no output that the turn's end orphaned.
+ */
+function finalizeInterruptedToolCalls(messages: AgentMessage[]): number {
+  let finalized = 0;
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      if (
+        tc.status !== ToolCallStatus.TOOL_CALL_PENDING &&
+        tc.status !== ToolCallStatus.TOOL_CALL_RUNNING
+      ) {
+        continue;
+      }
+      hideToolCallRow(tc);
+      finalized++;
+    }
+  }
+  return finalized;
+}
+
+/**
+ * Recognizes a tool call already blanked to a hidden collapsed row, so a second
+ * pass never re-collapses it (and never miscounts). Mirrors the SDK's
+ * `isCollapsedToolCall` shape without importing across the runner/SDK seam.
+ */
+function isAlreadyCollapsed(tc: ToolCall): boolean {
+  return (
+    tc.status === ToolCallStatus.TOOL_CALL_SKIPPED &&
+    !tc.requiresApproval &&
+    !tc.result &&
+    !tc.error &&
+    !tc.argsPreview
+  );
+}
+
+/**
+ * Whether a tool call carries a change/output of its own — the signal that it is
+ * authoritative for its resource rather than a redundant denial/cancel twin.
+ *
+ * The notion of "change" is category-aware on purpose:
+ *  - A file mutation (`write`/`delete`) never carries an authoritative change on
+ *    the tool-call ROW: under apply-then-review its review lives in the
+ *    `FileChangeSet` ledger (capture mode), and under the no-storage deny-gate it
+ *    is the WAITING_APPROVAL gate itself (kept explicitly by the caller). So a
+ *    file row is authoritative only as that gate, never on its own — hence
+ *    `false` here. (Before Phase 5 Slice 4 this read `file_changes.length > 0`;
+ *    that field is gone, and the row was never the review surface.)
+ *  - Every other gated tool (shell, MCP) has no ledger; its "change" is its
+ *    execution output, so a genuine run carries a non-empty `result` while a
+ *    denied/cancelled attempt that never executed does not. This keeps two
+ *    distinct shell runs (each with output) both visible while still collapsing a
+ *    same-command denial twin.
+ */
+function carriesOwnChange(tc: ToolCall): boolean {
+  const category = toolApprovalCategory(tc.name);
+  if (category === "write" || category === "delete") {
+    return false;
+  }
+  return !!tc.result;
+}
+
+/**
+ * Collapse redundant same-identity tool-call twins to a single visible row.
+ *
+ * The model frequently emits the SAME gated action twice in one turn (two
+ * tool-call ids, one identity). When the first attempt is gated and the run is
+ * cancelled mid-flight, the extra attempt never receives a terminal event and
+ * persists as a stuck `RUNNING` row ("No preview available"); other variants are
+ * a denied-reported-as-success `COMPLETED` with an empty result, two no-change
+ * `COMPLETED` attempts where neither carries a change, or — on the denial path —
+ * a `FAILED` twin beside the overlaid gate. All render as a duplicate card beside
+ * the real action (or the approval gate). This is the recurring duplicate-card
+ * defect, most visible for file edits but shared by every gated tool family.
+ *
+ * The routine is harness-agnostic and a pure function of `messages`:
+ *
+ * 1. Scope to GATED identities — file mutations (`write`/`delete`) and shell key
+ *    on their cross-taxonomy category; MCP tools are recognized by their server
+ *    slug. A same-turn duplicate of a gated tool is a denial/cancel artifact, not
+ *    meaningful repetition. The category is name-derived (via {@link toolIdentity}
+ *    -> approvalCategory), so a twin cancelled before classification (empty
+ *    `toolKind`) is still scoped via its name (`edit` -> `write`). Ungated
+ *    read-only tools are left untouched.
+ * 2. Group those calls by `toolCallIdentityToken` — the SAME `toolIdentity` used
+ *    for denial correlation and resume grants, so scope and grouping cannot drift.
+ * 3. In each group the keepers carry authoritative state — a change/output of
+ *    their own (see {@link carriesOwnChange}) or the approval gate itself
+ *    (`WAITING_APPROVAL`). For a file mutation the gate is the sole authoritative
+ *    row: the row carries no diff (review lives in the `FileChangeSet` ledger, or
+ *    is the no-storage deny-gate itself), so a denied write's same-identity
+ *    siblings — a denied/zombie row or a stale snapshot from a second attempt —
+ *    collapse onto the gate. A shell/MCP twin keeps every distinct run with
+ *    output. If NO member qualifies (every attempt produced no change), keep
+ *    exactly ONE representative — preferring a terminal attempt over a stuck
+ *    `RUNNING` zombie — so the resource still shows a single card. Every
+ *    non-keeper is blanked in place to a hidden `SKIPPED` row (see
+ *    {@link collapseDenialTwin}).
+ *
+ * It is deliberately subtractive — it only ever HIDES a row, never invents a
+ * terminal state. The committed `id` is preserved on every collapse, so the
+ * finalize stays append-only by construction and the backend's
+ * append-only-at-identity guard accepts it. Returns the number collapsed, for
+ * observability.
+ */
+export function collapseRedundantToolCallTwins(messages: AgentMessage[]): number {
+  const groups = new Map<string, ToolCall[]>();
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      const id = toolIdentity(tc.name, tc.mcpServerSlug, toolCallArgs(tc));
+      const gated = tc.mcpServerSlug
+        ? true
+        : id.key === "write" || id.key === "delete" || id.key === "shell";
+      if (!gated) continue;
+      const token = grantToken(id.key, id.salient);
+      const bucket = groups.get(token);
+      if (bucket) bucket.push(tc);
+      else groups.set(token, [tc]);
+    }
+  }
+
+  let collapsed = 0;
+  for (const group of groups.values()) {
+    if (group.length < 2) continue; // a lone call is never a twin
+
+    // Keepers carry authoritative state: a change/output of their own
+    // (carriesOwnChange) or the approval gate itself. For a file mutation the gate
+    // is the sole authoritative row (the row carries no diff — review lives in the
+    // ledger, or the row IS the no-storage deny-gate), so a denied write's
+    // same-identity siblings collapse onto it; a shell/MCP twin keeps every
+    // distinct run with output.
+    const keepers = new Set<ToolCall>(
+      group.filter(
+        (tc) =>
+          carriesOwnChange(tc) ||
+          tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      ),
+    );
+    // All attempts produced no change (e.g. denied-reported-as-success): keep one
+    // representative, preferring a settled outcome over a stuck RUNNING zombie.
+    if (keepers.size === 0) {
+      const terminal = [...group].reverse().find((tc) => isTerminalToolStatus(tc.status));
+      keepers.add(terminal ?? group[0]);
+    }
+
+    for (const tc of group) {
+      if (keepers.has(tc)) continue;
+      if (isAlreadyCollapsed(tc)) continue;
+      collapseDenialTwin(tc);
+      collapsed++;
+    }
+  }
+  return collapsed;
+}
+
+/**
+ * One gate per turn: blank every DENIED tool call whose identity differs from
+ * the anchor (the first denial of the turn) to a hidden SKIPPED row.
+ *
+ * This is the cross-identity complement of {@link collapseRedundantToolCallTwins}
+ * (which only joins SAME-identity duplicates). The canonical target is the
+ * deny-only workaround — a denied `edit notes.md` followed by a `shell:
+ * cat > notes.md` whose identity (`shell\n…`) differs from the edit's
+ * (`write\nnotes.md`), so no twin collapse can join them and (since they share
+ * one assistant message) no positional rule can separate them. The honest signal
+ * that the shell is redundant is that it is a DIFFERENT denied identity in the
+ * same turn as the anchor; under the one-gate-per-turn contract every such
+ * identity is either a post-denial reaction or a co-pending sibling the harness
+ * defers to the next turn, so it is hidden, not surfaced.
+ *
+ * Scoped strictly to identities present in `deniedTokens`: a non-denied tool
+ * (an earlier read/glob, or an already-granted call that ran) is never touched.
+ * Subtractive and id-preserving (via {@link collapseDenialTwin}), so the finalize
+ * stays append-only. Returns the number collapsed, for observability.
+ */
+function collapseNonAnchorDenials(
+  messages: AgentMessage[],
+  deniedTokens: ReadonlySet<string>,
+  anchorToken: string,
+): number {
+  let collapsed = 0;
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      const token = toolCallIdentityToken(tc);
+      if (token === anchorToken) continue;
+      if (!deniedTokens.has(token)) continue;
+      if (isAlreadyCollapsed(tc)) continue;
+      collapseDenialTwin(tc);
+      collapsed++;
+    }
+  }
+  return collapsed;
+}
+
+/**
+ * Blank a superseded denial twin in place to a hidden SKIPPED row. Keeps the
+ * committed `id` (append-only), `name`, and `toolKind`; clears every renderable
+ * surface and the approval flags so the SDK's `isCollapsedToolCall` predicate
+ * recognizes it and renders nothing. The structured `args` are left as the honest
+ * stored record of the redundant attempt (never rendered, since the row is
+ * hidden; the gate carries the authoritative proposed change).
+ */
+function collapseDenialTwin(tc: ToolCall): void {
+  hideToolCallRow(tc);
+}
+
+// `hideToolCallRow` (the "hidden row" shape, shared by the denial-twin collapse
+// and the capture flow) lives in shared/tool-row.ts so both harnesses collapse
+// rows identically; imported at the top of this module.
+
+/**
+ * Overlay the hook-captured authoritative tool input onto a gated tool call so
+ * the approval card can show the proposed change before the user approves.
+ *
+ * When `input` is present it becomes the single source for the preview: the full
+ * structured `args` (the approval card renders the proposed write/edit content
+ * from these), a compact-but-always-valid `args_preview` (the field a resumed
+ * turn parses to rebuild the grant salient — so salient fields are never elided),
+ * and the content digest.
+ *
+ * The digest is the resume identity: it binds the grant to (category, path,
+ * content) so a sibling edit to the same file re-gates rather than riding an
+ * earlier approval through. It is also the identity the Cursor deny-gate's
+ * exact-apply reads on resume — together with the whole-file bytes in `args` — to
+ * write exactly what was approved (see exact-apply.ts). There is no separate
+ * captured `file_changes` mirror; `args` is the single source for both the
+ * preview and the applied bytes.
+ *
+ * With no `input` (the hook's grep fallback) there is nothing authoritative to
+ * stamp and the call keeps its existing args.
+ */
+function applyGateInput(
+  tc: ToolCall,
+  input: Record<string, unknown> | undefined,
+): void {
+  if (!input) return;
+  tc.args = input as JsonObject;
+  tc.argsPreview = buildElidedArgsPreview(input, SALIENT_ARG_FIELDS);
+  // Stamp the content digest from the AUTHORITATIVE captured input, so the
+  // approved edit's exact content survives to resume on a small, never-elided
+  // field — the grant then binds to (category, path, content) and a sibling
+  // edit to the same file re-gates. Empty for a non-content tool. This is the
+  // one place the digest is authored; everything downstream reads the field.
+  tc.approvalContentDigest = contentDigest(input);
+}
+
+/**
+ * The workspace-normalized identity of a FILE approval category's salient, or
+ * undefined for a non-file category (shell, whose salient is a command, not a
+ * path) or an empty salient. Both the hook-decoded denial salient and a streamed
+ * call's salient pass through this, so an absolute-vs-relative path difference
+ * collapses to one comparable key (`category + "\n" + relPath`). Restricting to
+ * write/delete keeps a shell command from being mangled by path normalization.
+ */
+function normalizedFileSalient(
+  category: string,
+  salient: string,
+  workspaceRoot: string,
+): string | undefined {
+  if ((category !== "write" && category !== "delete") || !salient) return undefined;
+  const { path } = resolveWorkspacePath(salient, workspaceRoot, /* virtualRoot */ false);
+  return `${category}\n${path}`;
+}
+
+/**
+ * Find the first not-yet-overlaid streamed tool call whose workspace-normalized
+ * (category, path) equals `wanted`. Skips calls already claimed by an earlier
+ * denial so several concurrent file denials each overlay a distinct stream call.
+ */
+function findUnmatchedStreamCallByNormalizedSalient(
+  messages: AgentMessage[],
+  matchedCalls: ReadonlySet<ToolCall>,
+  wanted: string,
+  workspaceRoot: string,
+): ToolCall | undefined {
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      if (matchedCalls.has(tc)) continue;
+      const id = toolIdentity(tc.name, tc.mcpServerSlug, toolCallArgs(tc));
+      if (normalizedFileSalient(id.key, id.salient, workspaceRoot) === wanted) {
+        return tc;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Redact provisional post-denial narration when a Cursor turn pauses for approval.
+ *
+ * THE PROBLEM. Unlike the native harness — which gates with a LangGraph
+ * `interrupt()` *before* the tool runs, so the model never sees a denial — the
+ * Cursor harness can only gate via the file-based `beforeMCPExecution`/
+ * `preToolUse` hook returning `deny`. Cursor surfaces that deny to the model as
+ * a tool *failure* (often its own generic "blocked by a hook" text; see the
+ * Phase 0 ground-truth capture in cursor_hitl_test.go), and there is no
+ * non-leaky SDK approval primitive to use instead (the `request` event is
+ * opaque and carries no responder). So a well-behaved model frequently reacts by
+ * narrating defeat — "I couldn't do this; enable the hook in your Cursor
+ * settings" — which would otherwise be persisted as the assistant's verdict and
+ * rendered right next to the approval card that is, in fact, asking the user to
+ * approve. Contradictory and alarming.
+ *
+ * THE GUARANTEE. The runner's job is to simplify this data, not mirror its
+ * complexity: a turn that pauses for approval must read the SAME shape the
+ * native harness produces — `[pre-tool text][tool calls WAITING_APPROVAL]`, with
+ * no post-denial verdict. We therefore BLANK (clear the `content` of, and mark
+ * non-streaming) the trailing assistant/thinking messages that (a) appear
+ * positionally AFTER the last message bearing a WAITING_APPROVAL tool call and
+ * (b) carry no tool calls of their own. The approval card (projected from the
+ * WAITING_APPROVAL tool-call status) becomes the single, unambiguous source of
+ * truth. The blanked messages are already invisible on every surface via the
+ * existing empty-message handling (`buildThreadItems` skips empty `MESSAGE_AI`;
+ * `MessageEntry` renders nothing for empty `MESSAGE_THINKING`), so the shared
+ * `@stigmer/react`/Ink components stay harness-agnostic with zero per-harness UI
+ * special-casing — the cleanliness lives in the data, not in each consumer.
+ *
+ * WHY BLANK INSTEAD OF REMOVE. Removing the messages would make the persisted
+ * WAITING_FOR_APPROVAL transcript SHORTER than the in-progress transcript the
+ * runner already streamed. The backend's append-only message guard rejects a
+ * shrink for a non-terminal execution (it protects against regressed/partial
+ * writes). Blanking keeps the message COUNT identical, so the finalize is
+ * append-only BY CONSTRUCTION and the guard accepts it with no special case —
+ * which is why this phase deletes the backend's former `isApprovalFinalize`
+ * shrink exception in both editions. The transcript is the authoritative *raw*
+ * record; the verbatim narration text remains recoverable from the runner logs
+ * and the recorded cursor-event stream.
+ *
+ * WHY THIS IS DETERMINISTIC. `attachToolCallToLastAi` calls
+ * `finalizeStreaming(run_id)` before attaching a tool call, so any assistant
+ * text the model emits *after* the denied tool call always starts a NEW message
+ * — post-denial narration is never merged into the message that holds the gated
+ * call. We stop at the first non-narration message — one bearing a VISIBLE tool
+ * call — so legitimately-executed tools after the gate and any text around them
+ * are never touched; only the contiguous trailing reaction block is blanked. A
+ * message whose every tool call was collapsed to the hidden SKIPPED row (a
+ * post-denial workaround or an interrupted attempt — see
+ * collapseNonAnchorDenials / finalizeInterruptedToolCalls, which run first) IS
+ * trailing narration: its rows render as absent, so only its text remains, and
+ * that text is precisely the reaction this redaction exists to blank. Treating
+ * it as a stop would strand every reaction message behind it (the production
+ * shape in aex_01kwj07f7g23c3wp9sn8496z5g: [gate][thinking][narration+workaround
+ * row] — the old walk stopped at the workaround message and redacted nothing).
+ * The first-denial stop in index.ts is the primary mechanism that keeps this
+ * block small (it ends the turn before the model produces inter-tool
+ * narration); this redaction is the backstop for any token that streamed before
+ * the cancel landed.
+ *
+ * Returns the blanked messages (for diagnostics); mutates `messages` in place.
+ */
+export function clearProvisionalPostDenialNarration(
+  messages: AgentMessage[],
+  deniedToolCalls: ToolCall[],
+): AgentMessage[] {
+  if (deniedToolCalls.length === 0) return [];
+
+  // reconcileDeniedToolCalls returns the very ToolCall protos held inside
+  // messages[].toolCalls (overlaid) or appended to the last AI message
+  // (synthesized), so object identity is a stable, exact match.
+  const denied = new Set(deniedToolCalls);
+
+  let lastGatedIdx = -1;
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].toolCalls.some((tc) => denied.has(tc))) {
+      lastGatedIdx = i;
+    }
+  }
+  if (lastGatedIdx < 0) return [];
+
+  const redacted: AgentMessage[] = [];
+  for (let i = messages.length - 1; i > lastGatedIdx; i--) {
+    const msg = messages[i];
+    const isProvisionalNarration =
+      (msg.type === MessageType.MESSAGE_AI || msg.type === MessageType.MESSAGE_THINKING) &&
+      msg.toolCalls.every((tc) => isToolCallRowHidden(tc));
+    // Stop at the first message that is NOT trailing narration: a message
+    // bearing a visible (non-collapsed) tool call marks real activity we must
+    // preserve, and anything before it is no longer "trailing".
+    if (!isProvisionalNarration) break;
+    // Blank in place — keep the message so the transcript count never shrinks,
+    // but drop its provisional content so no consumer renders the defeatist
+    // verdict. Empty AI/THINKING messages are hidden by the SDK already; hidden
+    // SKIPPED rows already render as absent.
+    msg.content = "";
+    msg.isStreaming = false;
+    redacted.unshift(msg);
+  }
+  return redacted;
+}
+
 /**
  * Compute a streamed tool call's identity token in the same canonical space the
- * preToolUse hook records denials in (see {@link toolIdentity} and grantToken).
- * The token keys on the cross-taxonomy category + salient resource, so a stream
- * `edit` (token `base64("write\n/path")`) correlates to the hook's `Write` deny
- * for the same path, even though the two layers name the tool differently.
+ * preToolUse hook records denials in (see {@link toolIdentity} / primaryToken).
+ * The token keys on the cross-taxonomy category + salient resource PLUS, for a
+ * file edit/write, the {@link contentDigest} of the edit content — so a stream
+ * `edit` correlates to the hook's `Write` deny for the same path AND content,
+ * and an approval of one edit does not match a DIFFERENT edit to the same file.
+ *
+ * The digest is read from the persisted `approval_content_digest` field when
+ * present (a seeded gate carries it, stable even if `args` was elided), and is
+ * recomputed from the call's args otherwise (a freshly-streamed call). For a
+ * shell/delete/MCP call (no content) it falls back to the coarse token, exactly
+ * as before — so those identities are unchanged.
+ *
+ * Exported so the resume-grant round-trip can be locked against it: the grant a
+ * resume mints for an approved tool (buildApprovalGrants -> primaryToken) must
+ * equal THIS denial/overlay identity, or the re-issued call is re-gated forever
+ * (the dual-path drift the approval-state round-trip suite guards against).
  */
-function toolCallIdentityToken(tc: ToolCall): string {
+export function toolCallIdentityToken(tc: ToolCall): string {
   const id = toolIdentity(tc.name, tc.mcpServerSlug, toolCallArgs(tc));
-  return grantToken(id.key, id.salient);
+  const digest = tc.approvalContentDigest || contentDigest(toolCallArgs(tc));
+  return primaryToken(id.key, id.salient, digest);
 }
 
-/** Decode a grantToken back into its (key, salient) for the synthesis fallback. */
-function decodeIdentityToken(token: string): { key: string; salient: string } | undefined {
+/**
+ * Decode a primary token back into its (key, salient, digest) for the synthesis
+ * fallback. The token is `base64(key \n salient)` (coarse) or
+ * `base64(key \n salient \n digest)` (content-exact); the digest is the optional
+ * third segment. salient never contains a newline (a path or shell command), so
+ * splitting on the first two newlines is unambiguous.
+ */
+function decodeIdentityToken(
+  token: string,
+): { key: string; salient: string; digest: string } | undefined {
   try {
     const decoded = Buffer.from(token, "base64").toString("utf-8");
-    const nl = decoded.indexOf("\n");
-    if (nl < 0) return undefined;
-    return { key: decoded.slice(0, nl), salient: decoded.slice(nl + 1) };
+    const first = decoded.indexOf("\n");
+    if (first < 0) return undefined;
+    const key = decoded.slice(0, first);
+    const rest = decoded.slice(first + 1);
+    const second = rest.indexOf("\n");
+    if (second < 0) return { key, salient: rest, digest: "" };
+    return { key, salient: rest.slice(0, second), digest: rest.slice(second + 1) };
   } catch {
     return undefined;
   }
@@ -1017,6 +1874,7 @@ function markWaitingApproval(
 function synthesizeWaitingApprovalToolCall(
   displayName: string,
   salient: string,
+  digest: string,
   token: string,
   mergedPolicies?: Map<string, MergedToolPolicy>,
 ): ToolCall {
@@ -1028,6 +1886,10 @@ function synthesizeWaitingApprovalToolCall(
     startedAt: utcTimestamp(),
     approvalRequestedAt: utcTimestamp(),
     toolKind: classifyTool(displayName),
+    // Carry the decoded digest so this placeholder's identity (and the grant
+    // rebuilt from it on resume) equals the anchor's content token. applyGateInput
+    // overwrites it from the authoritative input when one was captured.
+    approvalContentDigest: digest,
   });
   // Carry the salient resource so reconstructAdjudicatedApprovals -> the grant
   // builder keys on the same resource the hook will see on the re-attempt.
@@ -1037,6 +1899,18 @@ function synthesizeWaitingApprovalToolCall(
   tc.approvalMessage = salient
     ? `Tool requires approval: ${displayName} (${salient})`
     : resolveDeniedApprovalMessage(displayName, "", {}, mergedPolicies);
+  // A synthesized call is a ledger denial — it was gated, so it has a governing
+  // layer. A denied call never occurs under a global bypass or a matching lease,
+  // so empty leases + no bypass faithfully attribute it (a built-in resolves to
+  // builtin_category; an MCP placeholder lacks a reconstructed slug and stays
+  // UNSPECIFIED rather than be mislabeled).
+  if (mergedPolicies) {
+    const source = resolveApprovalProvenance(
+      displayName, "", mergedPolicies, NO_LEASED_CATEGORIES, false,
+    );
+    tc.approvalPolicySource = toProtoPolicySource(source);
+    if (source) tc.policyEngineVersion = POLICY_ENGINE_VERSION;
+  }
   return tc;
 }