@stigmer/runner 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

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

@@ -5,14 +5,18 @@
  * sub-agent tracking, the first-denial early stop — and the loop's side of the adapter contract: progress reported per event
  * and per delta, usage reported priced, the persist awaited, and the runtime's
  * stop signal honoured at every event boundary and inside a blocked pull by
- * cancelling the SDK run. Since S2 M3 the loop no longer decides WHY it
+ * cancelling the SDK run. Since #1070 the loop no longer decides WHY it
  * stopped (stall, cost cap, pause, platform stop are the runtime's evidence;
  * `harness/__tests__/run-turn.test.ts` proves that table); it reports
  * `completed`, `first-denial` or `interrupted`.
  *
  * The loop is driven with a structural `mockRun` (an async-iterable `.stream()`)
  * and the kit's `RecordingTurnSink`, so it runs without the live Cursor SDK or
- * Temporal — mirroring the deep-agent `streaming.test.ts` pattern.
+ * Temporal — mirroring the deep-agent `streaming.test.ts` pattern. The
+ * transcript side is the REAL pair the loop runs in production — the Cursor
+ * translator into the shared `TranscriptBuilder` over `sink.status` (#1097;
+ * until then a stubbed accumulator counted calls) — so what these arms read
+ * back are rows, not mock invocations.
  */
 
 import { describe, it, expect, vi, afterEach } from "vitest";
@@ -20,7 +24,11 @@ import { mkdtemp, writeFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { SDKMessage } from "@cursor/sdk";
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { RecordingTurnSink } from "../../../__test-utils__/harness-contract/recording-sink.js";
+import type { TranscriptBuilder } from "../../../harness/transcript/builder.js";
+import { sdkEvents } from "../__test-utils__/scripted-agent.js";
+import { CursorTranslator } from "../translator.js";
 import {
   consumeCursorTurnStream,
   makeCursorTurnOnDelta,
@@ -30,10 +38,11 @@ import {
   type TurnStreamState,
 } from "../turn-stream.js";
 
-// A stream event is only inspected by the loop for `type`/`name`/`status`/
-// `message`; the accumulator (stubbed) owns the rest, so a minimal cast is safe.
-function ev(obj: Record<string, unknown>): SDKMessage {
-  return obj as unknown as SDKMessage;
+/** The SDK's real event shapes, bound to one run, so the translator folds them as production would. */
+const sdk = sdkEvents("agent-test", "run-test");
+/** A `status` event whose `message` is deliberately NOT a string — the oss#299 shape the loop must not crash on. */
+function statusWithStructuredMessage(): SDKMessage {
+  return { type: "status", agent_id: "agent-test", run_id: "run-test", status: "ERROR", message: { code: 14 } } as unknown as SDKMessage;
 }
 
 async function* asyncIter(events: SDKMessage[]): AsyncIterable<SDKMessage> {
@@ -52,27 +61,8 @@ function mockRun(events: SDKMessage[]): MockRun {
   };
 }
 
-function stubAccumulator(overrides: Record<string, unknown> = {}) {
-  return {
-    processEvent: vi.fn(),
-    trackSubAgentExecution: vi.fn(),
-    finalize: vi.fn(),
-    markPersisted: vi.fn(),
-    cancelInProgressSubAgents: vi.fn(),
-    isDirty: true,
-    subAgentExecutions: [],
-    ...overrides,
-  };
-}
-
-function stubEnricher() {
-  return {
-    processDelta: vi.fn(),
-    applyEnrichments: vi.fn(),
-    finalize: vi.fn(),
-    markPersisted: vi.fn(),
-    isDirty: false,
-  };
+function translatorFor(sink: RecordingTurnSink): CursorTranslator {
+  return new CursorTranslator({ policies: new Map(), leases: { global: false, categories: new Set() }, seeded: sink.status.messages });
 }
 
 /** Prices nothing: hands the counts back as a delta with a stated cost, so the sink sees a priced delta. */
@@ -84,71 +74,104 @@ interface BuiltDeps {
   deps: CursorTurnStreamDeps;
   state: TurnStreamState;
   sink: RecordingTurnSink;
-  accumulator: ReturnType<typeof stubAccumulator>;
+  transcript: TranscriptBuilder;
 }
 
 function buildDeps(overrides: Partial<CursorTurnStreamDeps> = {}): BuiltDeps {
   const state = overrides.state ?? newTurnStreamState();
   const sink = (overrides.sink as RecordingTurnSink | undefined) ?? new RecordingTurnSink();
-  const accumulator = (overrides.accumulator as unknown as ReturnType<typeof stubAccumulator>) ?? stubAccumulator();
+  // The builder is the sink's, as the runtime hands it (#1097).
+  const transcript = sink.transcript;
 
   const deps = {
     // TurnOnDeltaDeps
     sink,
     usagePricer: stubUsagePricer(),
-    deltaEnricher: stubEnricher(),
+    translator: translatorFor(sink),
+    eventRecorder: undefined,
     promptEstimatedTokens: 100,
     executionId: "exec-test",
     state,
     // CursorTurnStreamDeps
-    accumulator,
-    todoTracker: { processEvent: vi.fn(), markPersisted: vi.fn(), isDirty: false },
-    eventRecorder: undefined,
-    // contentDirty (accumulator.isDirty) forces the persist, so shouldSendUpdate
-    // is never consulted; markUpdateSent must still exist.
+    // A tool row's start forces the persist (the builder's flag), so a text-only
+    // stream rides this scheduler, which never says yes; markUpdateSent must exist.
     scheduler: { shouldSendUpdate: () => false, markUpdateSent: vi.fn() },
     hitlDir: undefined,
     ...overrides,
   } as unknown as CursorTurnStreamDeps;
 
-  return { deps, state, sink, accumulator };
+  return { deps, state, sink, transcript };
+}
+
+/** Every root row the loop folded into the sink's status. */
+function rows(sink: RecordingTurnSink) {
+  return sink.status.messages.flatMap((m) => m.toolCalls);
 }
 
 describe("consumeCursorTurnStream", () => {
-  it("processes every event, persists live through the sink, and returns 'completed' on a natural end", async () => {
-    const { deps, state, sink, accumulator } = buildDeps();
+  it("folds every event into the sink's status through the translator and the builder, persists live, and returns 'completed' on a natural end", async () => {
+    const { deps, state, sink } = buildDeps();
 
-    const reason = await consumeCursorTurnStream(mockRun([ev({ type: "assistant" }), ev({ type: "assistant" })]), deps);
+    const reason = await consumeCursorTurnStream(
+      mockRun([sdk.assistant("Reading."), sdk.toolCall("c1", "read", "running", { path: "a" }), sdk.toolCall("c1", "read", "completed", { path: "a" }, "text")]),
+      deps,
+    );
 
     expect(reason).toBe("completed");
-    expect(accumulator.processEvent).toHaveBeenCalledTimes(2);
+    expect(sink.status.messages.map((m) => [m.content, m.toolCalls.map((tc) => tc.id)])).toEqual([["Reading.", ["c1"]]]);
+    expect(rows(sink)[0].result).toBe("text");
     // The #1 retry gap: the bare loop never persisted mid-stream. This proves the
-    // shared loop persists live — through the runtime's chokepoint.
-    expect(sink.persistRequests).toBeGreaterThan(0);
-    expect(state.eventCount).toBe(2);
+    // shared loop persists live — through the runtime's chokepoint — on the
+    // builder's discrete-change flag (a row's start and its finish).
+    expect(sink.persistRequests).toBe(2);
+    expect(sink.transcript.dirty, "the flag is cleared after each persist").toBe(false);
+    expect(state.eventCount).toBe(3);
+  });
+
+  it("drains the delta channel's queued facts after the stream event, never before it — and the delta's completion instant stands", async () => {
+    const { deps, sink } = buildDeps();
+    const onDelta = makeCursorTurnOnDelta(deps);
+    const withDeltaBetween: StreamableRun = {
+      stream: async function* () {
+        yield sdk.toolCall("sh-1", "shell", "running", { command: "make" });
+        onDelta({ update: { type: "shell-output-delta", event: { callId: "sh-1", type: "stdout", data: "building\n" } } });
+        onDelta({ update: { type: "tool-call-completed", callId: "sh-1", modelCallId: "m", toolCall: { type: "shell", args: { command: "make" }, result: { status: "success", value: { exitCode: 0, signal: "", stdout: "building\n", stderr: "", executionTime: 1 } } } } });
+        yield sdk.assistant("Built.");
+      },
+      supports: () => true,
+      cancel: async () => {},
+    };
+
+    await consumeCursorTurnStream(withDeltaBetween, deps);
+
+    const row = rows(sink)[0];
+    expect(row.result, "the output reached the row at the next stream event").toBe("building\n");
+    expect(row.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(row.completedAt, "stamped at the delta's observed instant").not.toBe("");
   });
 
   it("reports progress per event, naming the tool of a tool_call event (the stall copy's `last tool`)", async () => {
     const { deps, sink } = buildDeps();
 
-    await consumeCursorTurnStream(mockRun([ev({ type: "assistant" }), ev({ type: "tool_call", name: "shell" })]), deps);
+    await consumeCursorTurnStream(mockRun([sdk.assistant("Go."), sdk.toolCall("c1", "shell", "running", { command: "ls" })]), deps);
 
     const marks = sink.events.filter((e) => e.kind === "activity");
     expect(marks.map((m) => (m.kind === "activity" ? m.detail : undefined))).toEqual([undefined, "shell"]);
   });
 
   it("tracks a sub-agent delegation (the 'task' tool call) — dropped by the old bare retry loop", async () => {
-    const { deps, accumulator } = buildDeps();
+    const { deps, sink } = buildDeps();
 
-    await consumeCursorTurnStream(mockRun([ev({ type: "tool_call", name: "task" })]), deps);
+    await consumeCursorTurnStream(mockRun([sdk.toolCall("t1", "task", "running", { subagentType: "helper", description: "Look", prompt: "Look at it" })]), deps);
 
-    expect(accumulator.trackSubAgentExecution).toHaveBeenCalledTimes(1);
+    expect(sink.status.subAgentExecutions.map((s) => [s.id, s.name])).toEqual([["t1", "helper"]]);
+    expect(rows(sink).map((tc) => tc.id)).toEqual(["t1"]);
   });
 
   it("captures a stream ERROR status message onto state.streamErrorMessage", async () => {
     const { deps, state } = buildDeps();
 
-    await consumeCursorTurnStream(mockRun([ev({ type: "status", status: "ERROR", message: "boom" })]), deps);
+    await consumeCursorTurnStream(mockRun([sdk.status("ERROR", "boom")]), deps);
 
     expect(state.streamErrorMessage).toBe("boom");
   });
@@ -158,7 +181,7 @@ describe("consumeCursorTurnStream", () => {
     // crash classifyText downstream (.toLowerCase() on a non-string).
     const { deps, state } = buildDeps();
 
-    await consumeCursorTurnStream(mockRun([ev({ type: "status", status: "ERROR", message: { code: 14 } })]), deps);
+    await consumeCursorTurnStream(mockRun([statusWithStructuredMessage()]), deps);
 
     expect(state.streamErrorMessage).toBeUndefined();
   });
@@ -174,7 +197,7 @@ describe("consumeCursorTurnStream", () => {
       hitlDir = await mkdtemp(join(tmpdir(), "turn-stream-denial-"));
       await writeFile(join(hitlDir, "denials.jsonl"), JSON.stringify({ toolName: "shell", token: "tok-1" }) + "\n", "utf-8");
       const { deps, state } = buildDeps({ hitlDir });
-      const run = mockRun([ev({ type: "tool_call", name: "shell" })]);
+      const run = mockRun([sdk.toolCall("c1", "shell", "running", { command: "rm -rf build" })]);
 
       const reason = await consumeCursorTurnStream(run, deps);
 
@@ -189,7 +212,7 @@ describe("consumeCursorTurnStream", () => {
       await writeFile(join(hitlDir, "denials.jsonl"), "", "utf-8");
       const { deps, state } = buildDeps({ hitlDir });
 
-      const reason = await consumeCursorTurnStream(mockRun([ev({ type: "tool_call", name: "shell" })]), deps);
+      const reason = await consumeCursorTurnStream(mockRun([sdk.toolCall("c1", "shell", "running", { command: "ls" })]), deps);
 
       expect(reason).toBe("completed");
       expect(state.firstDenialDetected).toBe(false);
@@ -200,25 +223,25 @@ describe("consumeCursorTurnStream", () => {
     it("a signal aborted before the stream starts: the run is cancelled and nothing is processed", async () => {
       const sink = new RecordingTurnSink();
       sink.abort("cost-cap");
-      const { deps, accumulator } = buildDeps({ sink });
-      const run = mockRun([ev({ type: "assistant" })]);
+      const { deps } = buildDeps({ sink });
+      const run = mockRun([sdk.assistant("never folded")]);
 
       const reason = await consumeCursorTurnStream(run, deps);
 
       expect(reason).toBe("interrupted");
       expect(run.cancel).toHaveBeenCalledTimes(1);
-      expect(accumulator.processEvent).not.toHaveBeenCalled();
+      expect(sink.status.messages).toHaveLength(0);
     });
 
     it("an abort between events: the run is cancelled at once and the next event is never processed", async () => {
       const sink = new RecordingTurnSink();
-      const { deps, accumulator } = buildDeps({ sink });
+      const { deps } = buildDeps({ sink });
       // The realistic shape: the runtime aborts (a turn-ended delta crossed the
       // cap, a STOP came back from a persist) while the loop is between events.
       async function* gen(): AsyncIterable<SDKMessage> {
-        yield ev({ type: "assistant" });
+        yield sdk.assistant("first");
         sink.abort("platform-stop");
-        yield ev({ type: "assistant" });
+        yield sdk.assistant(" second");
       }
       const run: MockRun = { stream: () => gen(), supports: () => true, cancel: vi.fn(async () => {}) };
 
@@ -226,8 +249,8 @@ describe("consumeCursorTurnStream", () => {
 
       expect(reason).toBe("interrupted");
       expect(run.cancel).toHaveBeenCalledTimes(1);
-      // Event 1 was processed; event 2 hit the boundary check.
-      expect(accumulator.processEvent).toHaveBeenCalledTimes(1);
+      // Event 1 was folded; event 2 hit the boundary check.
+      expect(sink.status.messages.map((m) => m.content)).toEqual(["first"]);
     });
 
     it("an abort while the pull is blocked (a wedged stream): the cancel is what unblocks it", async () => {
@@ -238,7 +261,7 @@ describe("consumeCursorTurnStream", () => {
       // watchdog aborts.
       let unblock: (() => void) | undefined;
       async function* gen(): AsyncIterable<SDKMessage> {
-        yield ev({ type: "assistant" });
+        yield sdk.assistant("first");
         await new Promise<void>((resolve) => {
           unblock = resolve;
         });
@@ -266,7 +289,7 @@ describe("consumeCursorTurnStream", () => {
       // The break exits the for-await, which invokes the iterator's return();
       // a cancelled SDK run can reject there. The catch must exempt a stopped
       // turn's teardown exactly like the first-denial teardown.
-      const events = [ev({ type: "assistant" })];
+      const events = [sdk.assistant("first")];
       let i = 0;
       const run: MockRun = {
         stream: () => ({
@@ -293,7 +316,7 @@ describe("consumeCursorTurnStream", () => {
     it("rethrows a genuine stream failure when nothing stopped the turn", async () => {
       const { deps } = buildDeps();
       async function* gen(): AsyncIterable<SDKMessage> {
-        yield ev({ type: "assistant" });
+        yield sdk.assistant("first");
         throw new Error("transport reset");
       }
       const run: MockRun = { stream: () => gen(), supports: () => true, cancel: vi.fn(async () => {}) };
@@ -311,7 +334,8 @@ describe("makeCursorTurnOnDelta", () => {
     const onDelta = makeCursorTurnOnDelta({
       sink,
       usagePricer: usagePricer as never,
-      deltaEnricher: stubEnricher() as never,
+      translator: translatorFor(sink),
+      eventRecorder: undefined,
       promptEstimatedTokens: 10,
       executionId: "e",
       state,

package/src/activities/execute-cursor/adapter.ts

@@ -5,9 +5,10 @@
  * module boots, releases, and delegates.
  *
  * What this adapter owns: the proxy interceptors and the parked-agent cache
- * (worker lifetime), the parked agent per session (session lifetime), and one
- * engine turn (`runTurn`, through `turn.ts`). Everything else about a turn is
- * the runtime's (`harness/run-turn.ts`).
+ * (worker lifetime), the parked agent and the SDK store per session (session
+ * lifetime; `agent-session-cache.ts`, `session-store.ts`), and one engine turn
+ * (`runTurn`, through `turn.ts`). Everything else about a turn is the
+ * runtime's (`harness/run-turn.ts`).
  *
  * THIS MODULE'S STATIC GRAPH IS SDK-FREE, ON PURPOSE. The composition roots
  * import it (through `src/harness-adapters.ts`) BEFORE they boot it, and
@@ -27,7 +28,7 @@
  * The interceptors read the proxy credential from `Config.proxyTokenRef` per
  * request; which credential that is (the static root's control-plane token,
  * the manager's minted runner token) is the root's decision, not this
- * module's (Q-S2-7).
+ * module's.
  *
  * What this adapter never does: throw out of `runTurn` (an SDK failure is
  * `failed` with the classifier's sentence; an unexpected exception is
@@ -39,14 +40,14 @@
  *
  * The turn boundary (`turn-boundary.ts`) runs inside `turn.ts` and reads
  * this harness's deny-and-retry evidence — the denial ledger — into WAITING
- * rows and settled rows. The file-review capture is NOT here since S3 M4:
+ * rows and settled rows. The file-review capture is NOT here since #1096:
  * the runtime pins the baseline before this adapter runs and captures the
  * whole turn's tree after it returns (`harness/capture.ts`); what this
  * adapter contributes is the hook sidecar it binds as the runtime's CAS
  * observations (`turn-setup.ts` `installGate`).
  *
- * Extracted from `index.ts` `createCursorActivities` at S2 M3b; split from
- * the turn body at S2 M5. The seventeen hermetic goldens under
+ * Extracted from `index.ts` `createCursorActivities` in #1070, which also
+ * split it from the turn body. The seventeen hermetic goldens under
  * `__tests__/hermetic/` pin the result byte for byte.
  */
 
@@ -57,6 +58,7 @@ import { closeAllCachedAgents, evictSessionAgent } from "./agent-session-cache.j
 import { CURSOR_CAPABILITIES } from "./cursor-capabilities.js";
 import { installFetchInterceptor } from "./fetch-interceptor.js";
 import { assertHttp2ConnectPatched, installHttp2Interceptor } from "./http2-interceptor.js";
+import { releaseAllSessionStores, releaseSessionStore } from "./session-store.js";
 import type { CursorAdapterConfig } from "./turn-setup.js";
 
 /** The config slice this adapter reads per turn, taken at `boot`; a whole `Config` satisfies it. */
@@ -120,14 +122,16 @@ export function createCursorAdapter(): HarnessAdapter {
       booted = { config: resolveCursorConfig(bootConfig), runCursorTurn };
     },
 
-    /** Close every parked agent (their executor leases and MCP subprocesses). */
+    /** Close every parked agent (their executor leases and MCP subprocesses), then every session's SDK store. */
     async shutdown(): Promise<void> {
       closeAllCachedAgents();
+      await releaseAllSessionStores();
     },
 
-    /** The session is done on this host: close the agent parked for it, if any (#215). */
+    /** The session is done on this host: close the agent parked for it, if any (#215), then its SDK store (#1053). */
     async releaseSession(sessionId: string): Promise<void> {
       evictSessionAgent(sessionId);
+      await releaseSessionStore(sessionId);
     },
 
     async runTurn(input: TurnInput, sink: TurnSink): Promise<TurnOutcome> {

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

@@ -29,6 +29,7 @@ export {
   resolveApprovalMessage,
   POLICY_ENGINE_VERSION,
 } from "../../shared/approval-policy.js";
+import { CATEGORY_APPROVAL_MESSAGE } from "../../shared/approval-policy.js";
 export type { MergedToolPolicy, PolicySource } from "../../shared/approval-policy.js";
 
 /**
@@ -72,30 +73,15 @@ export type ApprovalCategory = ToolApprovalCategory;
 export const approvalCategory = toolApprovalCategory;
 
 /**
- * Human-readable approval-message template per canonical category. Keyed by
- * category (not raw tool name) so a denial surfaced from either taxonomy renders
- * the same message. Placeholders resolve against the tool args via
- * {@link resolveApprovalMessage}; `{{args.path}}` and `{{args.command}}` are the
- * stream-side field names (the runner builds the approval surface from the
- * streamed tool call, whose args use `path`/`command`).
+ * The salient argument fields — the resource a built-in acts on — are the
+ * platform's one list, `shared/args-preview.ts` `SALIENT_ARG_FIELDS` (moved
+ * there in #1097: the transcript builder previews every row over it for
+ * both harnesses). Re-exported here for this harness's identity code and the
+ * generated hook script, which inject it so the runner and the hook never
+ * disagree on which field to match.
  */
-const CATEGORY_APPROVAL_MESSAGE: Record<ApprovalCategory, string> = {
-  write: "Write file: {{args.path}}",
-  delete: "Delete: {{args.path}}",
-  shell: "Run command: {{args.command}}",
-};
-
-/**
- * Top-level tool-argument fields, in priority order, that identify the specific
- * resource a built-in tool acts on. The list deliberately spans BOTH taxonomies'
- * arg shapes: the hook input names a file `file_path` and the stream names it
- * `path`; both name a shell command `command`. Extracting the same resource
- * VALUE on both sides (the absolute path / the command string) is what lets the
- * hook-recorded denial token equal the stream-computed token. Authored here once
- * and injected into the generated preToolUse hook script so the runner and the
- * hook never disagree on which field to match.
- */
-export const SALIENT_ARG_FIELDS = ["file_path", "path", "target_notebook", "command"] as const;
+export { SALIENT_ARG_FIELDS } from "../../shared/args-preview.js";
+import { SALIENT_ARG_FIELDS } from "../../shared/args-preview.js";
 
 /**
  * Check whether a built-in (non-MCP) Cursor tool requires user approval.
@@ -152,7 +138,9 @@ export function getBuiltInGatedCategories(): Array<[string, ApprovalCategory]> {
  * Approval-message template for a gated built-in tool (either taxonomy), or
  * undefined when the tool is not gated. Resolved via {@link approvalCategory}
  * so stream-side names (`edit`/`shell`/`delete`) and hook-side names
- * (`Write`/`Shell`/`Delete`) both map to the same template. Callers resolve the
+ * (`Write`/`Shell`/`Delete`) both map to the same template — the platform's
+ * ONE table, `shared/approval-policy.ts` `CATEGORY_APPROVAL_MESSAGE`, shared
+ * with the native gate since #1097. Callers resolve the
  * placeholders against the tool args via resolveApprovalMessage.
  */
 export function getBuiltInApprovalMessage(toolName: string): string | undefined {

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

@@ -87,7 +87,7 @@ import { create } from "@bufbuild/protobuf";
 import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
-import type { AgentMessage } 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 type { MergedToolPolicy, ApprovalCategory } from "./approval-policy.js";
 import { extractArgKey, approvalCategory, POLICY_ENGINE_VERSION } from "./approval-policy.js";
 import { contentDigest } from "../../shared/file-tools.js";
@@ -286,6 +286,71 @@ export function primaryToken(key: string, salient: string, contentDigest: string
   return contentDigest ? contentToken(key, salient, contentDigest) : grantToken(key, salient);
 }
 
+/**
+ * Compute a streamed tool call's identity token in the same canonical space the
+ * 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).
+ */
+export function toolCallIdentityToken(tc: ToolCall): string {
+  const id = toolIdentity(tc.name, tc.mcpServerSlug, toolCallArgs(tc));
+  const digest = tc.approvalContentDigest || contentDigest(toolCallArgs(tc));
+  return primaryToken(id.key, id.salient, digest);
+}
+
+/**
+ * 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.
+ */
+export function decodeIdentityToken(
+  token: string,
+): { key: string; salient: string; digest: string } | undefined {
+  try {
+    const decoded = Buffer.from(token, "base64").toString("utf-8");
+    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;
+  }
+}
+
+/** Best-effort args record for a tool call (proto struct, else parsed preview). */
+export function toolCallArgs(tc: ToolCall): Record<string, unknown> {
+  if (tc.args && typeof tc.args === "object") {
+    return tc.args as Record<string, unknown>;
+  }
+  if (tc.argsPreview) {
+    try {
+      const parsed = JSON.parse(tc.argsPreview);
+      if (parsed && typeof parsed === "object") return parsed as Record<string, unknown>;
+    } catch {
+      // fall through
+    }
+  }
+  return {};
+}
+
 /**
  * The shared HMAC coarse fingerprint of an approval grant.
  *