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

package/src/shared/__tests__/approval-policy.test.ts

@@ -13,6 +13,7 @@ import {
   resolveApprovalMessage,
   deriveActiveLeases,
   resolveApprovalProvenance,
+  resolveToolApproval,
   toProtoPolicySource,
   type ActiveLeases,
   type MergedToolPolicy,
@@ -510,6 +511,50 @@ describe("resolveApprovalProvenance", () => {
 // cases assert the mapping is total and that undefined collapses to UNSPECIFIED.
 // ---------------------------------------------------------------------------
 
+describe("resolveToolApproval — THE gate decision, shared by the gate and the translators", () => {
+  const NO_CATEGORIES: ReadonlySet<ToolApprovalCategory> = new Set();
+  const gated: ReadonlyMap<string, MergedToolPolicy> = new Map([
+    ["github/create_issue", { toolName: "create_issue", mcpServerSlug: "github", requiresApproval: true, approvalMessage: "Create issue '{{args.title}}'?", source: "agent_override" }],
+  ]);
+
+  it("an MCP tool with a gating policy waits, with the policy's message resolved and its layer as source", () => {
+    expect(resolveToolApproval("create_issue", "github", { title: "Fix crash" }, gated, NO_CATEGORIES)).toEqual({
+      requiresApproval: true,
+      message: "Create issue 'Fix crash'?",
+      source: "agent_override",
+    });
+  });
+
+  it("an MCP tool absent from the policy map runs — the classifier cleared it (fail-open), source classifier_default", () => {
+    expect(resolveToolApproval("list_issues", "github", {}, gated, NO_CATEGORIES)).toEqual({
+      requiresApproval: false,
+      message: "",
+      source: "classifier_default",
+    });
+  });
+
+  it("a mutating built-in waits with its category's message (fail-closed), source builtin_category", () => {
+    expect(resolveToolApproval("execute", "", { command: "rm -rf build" }, new Map(), NO_CATEGORIES)).toEqual({
+      requiresApproval: true,
+      message: "Run command: rm -rf build",
+      source: "builtin_category",
+    });
+  });
+
+  it("a mutating built-in whose category is leased runs, source approval_lease", () => {
+    expect(resolveToolApproval("execute", "", { command: "ls" }, new Map(), new Set<ToolApprovalCategory>(["shell"]))).toEqual({
+      requiresApproval: false,
+      message: "",
+      source: "approval_lease",
+    });
+  });
+
+  it("a read-only or unclassified built-in runs (fail-open)", () => {
+    expect(resolveToolApproval("read_file", "", { path: "/x" }, new Map(), NO_CATEGORIES).requiresApproval).toBe(false);
+    expect(resolveToolApproval("think", "", {}, new Map(), NO_CATEGORIES).requiresApproval).toBe(false);
+  });
+});
+
 describe("toProtoPolicySource", () => {
   it("maps undefined (no governing layer) to UNSPECIFIED", () => {
     expect(toProtoPolicySource(undefined)).toBe(ApprovalPolicySource.UNSPECIFIED);

package/src/shared/__tests__/args-preview.test.ts

@@ -1,38 +1,46 @@
 /**
- * Unit tests for the shared args-preview sanitizers.
+ * Unit tests for the shared args-preview builder — the ONE preview rule every
+ * tool row carries since #1097.
  *
  * The Cursor gate path depends on {@link buildElidedArgsPreview} producing a
  * SMALL, ALWAYS-VALID, salient-preserving preview: the resumed turn re-parses it
  * to rebuild an approval grant's identity, and the persist-time size backstop
  * would replace an oversized preview with an unparseable marker. These pin those
  * invariants so a large write can never silently break the resume round-trip.
+ * (The native harness's whole-string-truncating `sanitizeArgsPreview` and its
+ * two arms went with it: a preview that could truncate to invalid JSON has no
+ * caller left.)
  */
 
 import { describe, it, expect } from "vitest";
-import {
-  buildElidedArgsPreview,
-  sanitizeArgsPreview,
-  MAX_ARGS_PREVIEW_LENGTH,
-} from "../args-preview.js";
+import { buildElidedArgsPreview, redactSensitiveArgs, SALIENT_ARG_FIELDS } from "../args-preview.js";
 
-describe("sanitizeArgsPreview (native)", () => {
-  it("redacts sensitive keys", () => {
-    const out = JSON.parse(sanitizeArgsPreview({ api_key: "sk-123", path: "a.txt" }));
-    expect(out.api_key).toBe("[REDACTED]");
-    expect(out.path).toBe("a.txt");
+describe("SALIENT_ARG_FIELDS", () => {
+  it("spans both harnesses' shapes for a file and a shell command, in priority order", () => {
+    expect([...SALIENT_ARG_FIELDS]).toEqual(["file_path", "path", "target_notebook", "command"]);
   });
+});
 
-  it("truncates the whole string past the cap", () => {
-    const preview = sanitizeArgsPreview({ contents: "x".repeat(MAX_ARGS_PREVIEW_LENGTH * 2) });
-    expect(preview.length).toBeLessThanOrEqual(MAX_ARGS_PREVIEW_LENGTH + 1);
-    expect(preview.endsWith("…")).toBe(true);
+describe("redactSensitiveArgs", () => {
+  it("redacts secret keys case-insensitively and keeps everything else verbatim", () => {
+    expect(redactSensitiveArgs({ Api_Key: "sk-123", path: "a.txt", n: 1 })).toEqual({ Api_Key: "[REDACTED]", path: "a.txt", n: 1 });
   });
 });
 
-describe("buildElidedArgsPreview (cursor gate)", () => {
-  const SALIENT = ["file_path", "path", "target_notebook", "command"] as const;
+describe("buildElidedArgsPreview", () => {
+  const SALIENT = SALIENT_ARG_FIELDS;
+
+  it("is exactly JSON.stringify(args) for short, secret-free args (what every native row now carries)", () => {
+    expect(buildElidedArgsPreview({ path: "/x", n: 2 }, SALIENT)).toBe(JSON.stringify({ path: "/x", n: 2 }));
+  });
 
-  it("stays valid JSON and small for a large write, eliding the content value", () => {
+  it("yields an empty string for unserializable args instead of throwing", () => {
+    const cyclic: Record<string, unknown> = {};
+    cyclic.self = cyclic;
+    expect(buildElidedArgsPreview(cyclic, SALIENT)).toBe("");
+  });
+
+  it("stays valid JSON and small for a large write, leaving the content value out", () => {
     const content = "line\n".repeat(100_000); // ~500 KB
     const preview = buildElidedArgsPreview(
       { path: "src/big.ts", contents: content },
@@ -43,9 +51,21 @@ describe("buildElidedArgsPreview (cursor gate)", () => {
     const parsed = JSON.parse(preview) as Record<string, unknown>;
     // Bounded — nowhere near the raw content size.
     expect(preview.length).toBeLessThan(1_000);
-    // The salient path survives verbatim (grant identity), content is elided.
+    // The salient path survives verbatim (grant identity); the content is not
+    // in the preview at all — never an in-band marker a reader could mistake
+    // for the file (stigmer#1107): a surface that needs it reads the row's args.
     expect(parsed.path).toBe("src/big.ts");
-    expect(parsed.contents).toBe(`[${content.length} chars]`);
+    expect("contents" in parsed).toBe(false);
+  });
+
+  it("a value at the cap is carried whole; one character over is left out", () => {
+    const atCap = "a".repeat(200);
+    const overCap = "a".repeat(201);
+    const parsed = JSON.parse(
+      buildElidedArgsPreview({ path: "x", note: atCap, essay: overCap }, SALIENT),
+    ) as Record<string, unknown>;
+    expect(parsed.note).toBe(atCap);
+    expect("essay" in parsed).toBe(false);
   });
 
   it("never elides a salient field, even a very long shell command", () => {

package/src/shared/__tests__/attachment-naming.test.ts

@@ -129,7 +129,7 @@ describe("cross-harness naming parity", () => {
       makeAttachment("Makefile", "attachments/01D/Makefile"),
     ];
 
-    // One attachment pipeline serves both harnesses since S3 M2b (Q-S3-14);
+    // One attachment pipeline serves both harnesses since #1096;
     // the names it lands are the ones the React SDK's table above predicts.
     const resolved = await resolveAttachments(attachments, {
       sessionId,

package/src/shared/__tests__/attachment-resolver.test.ts

@@ -1,15 +1,15 @@
 /**
  * Tests for the attachment resolver — the turn runtime's attachment phase,
- * the one pipeline for both harnesses since S3 M2b (the native twin,
+ * the one pipeline for both harnesses since #1096 (the native twin,
  * `attachment-injector.ts`, retired then; its ZIP guards moved to
- * `attachment-zip.ts` at S3 M1).
+ * `attachment-zip.ts` in the same PR).
  *
  * The load-bearing behaviors: storage-key attachments materialize under the
  * platform inputs dir (the universal path — every server-created attachment
  * carries a storage key), the workspace `.stigmer` symlink exists even when
  * the agent has no skills, and any attachment that cannot be materialized
  * fails the resolution loudly (the silent-skip regression behind "plan file
- * wasn't found"). Since S3 M1 (Q-S3-14, Q-M1-2) the resolver is the one
+ * wasn't found"). Since #1096 the resolver is the one
  * attachment pipeline for every harness, so it also pins the two behaviors
  * lifted from the native injector: `extract` archives land under their mount
  * directory through the shared #567 guards, and an explicit `mountPath` is
@@ -279,7 +279,7 @@ describe("resolveAttachments", () => {
 
   // ── Explicit mountPath: honoured inside the inputs namespace, refused outside ──
 
-  describe("mountPath (S3 M1, Q-M1-2)", () => {
+  describe("mountPath", () => {
     it("places a file at its explicit `inputs/…` path, in every spelling the producers use", async () => {
       const { storage } = makeInMemoryArtifactStorage();
       await storage.upload("k/a", Buffer.from("A"), "text/plain");
@@ -364,7 +364,7 @@ describe("resolveAttachments", () => {
 
   // ── Archives: `extract` lands the entries under the mount directory ──────
 
-  describe("extract (S3 M1, Q-S3-14)", () => {
+  describe("extract", () => {
     const archive = () =>
       Buffer.from(
         buildZip([

package/src/shared/__tests__/attachment-zip.test.ts

@@ -3,7 +3,7 @@
  * (`shared/attachment-zip.ts`): the manifest checks (paths, traversal, null
  * bytes, duplicates, methods, emptiness, count and declared-size caps) and
  * the central-directory parsing that issue #567 made authoritative. Moved
- * from the native injector's test file at S3 M1 with the code; every
+ * from the native injector's test file in #1096 with the code; every
  * archive comes from the shared real-shape builder
  * (@stigmer/zip-structure/testing). The write of an admitted entry is each
  * caller's and is pinned in that caller's tests (`attachment-resolver.test.ts`).

package/src/shared/__tests__/blueprint-resolver.test.ts

@@ -4,7 +4,7 @@
  * (`resolveAgentBlueprint`). Union, deduplicated by slug, the session's ref
  * winning a collision (it may pin a different version).
  *
- * Carried from `skill-writer.test.ts` at S3 M2b, when the native
+ * Carried from `skill-writer.test.ts` in #1096, when the native
  * orchestrator's byte-twin of this function was deleted with its module;
  * until then the runtime's copy was tested only through the twin.
  */

package/src/shared/__tests__/cost-guard.test.ts

@@ -1,6 +1,6 @@
 /**
  * Unit tests for the max_cost_usd hard-stop guard (cost-guard.ts), which the
- * Cursor activity calls today and the turn runtime takes over in S2 M3.
+ * Cursor activity called until the turn runtime took it over in #1070.
  *
  * The guard is the cursor-side analog of the native cost-cap middleware
  * (middleware/cost-cap.ts): same proto semantics (0/unset = no cap), same

package/src/shared/__tests__/exact-apply.test.ts

@@ -1,5 +1,6 @@
 /**
- * @regression file-hitl-phase0 — pins file-edit HITL fix #4 (see _projects/2026-06/20260630.01.file-change-hitl-redesign/tasks/T01_3_regression-manifest.md)
+ * @regression file-hitl-phase0 — pins exact-apply: the runner applies the exact
+ * approved whole-file bytes, never model-regenerated ones.
  *
  * Unit tests for resume-time exact-apply (the HITL "what you approve is what gets
  * applied" guarantee for the Cursor deny-only harness).

package/src/shared/__tests__/persist-decision.test.ts

@@ -1,12 +1,13 @@
 /**
  * Unit tests for the streaming persist decision (issue #179), the shared
- * cadence rule the Cursor stream loop calls today and the turn runtime
- * takes over in S2 M3.
+ * cadence rule both adapters' stream loops read.
  *
- * Validates the converged cadence: discrete force-flush signals persist
+ * Validates the converged cadence: a discrete transcript change persists
  * immediately, while high-frequency token deltas ride the shared
  * StreamingUpdateScheduler's time cadence (rather than the old, time-blind
- * `eventCount % 20` gate that starved short turns).
+ * `eventCount % 20` gate that starved short turns). The signal is the one
+ * transcript builder's `dirty` flag (since #1097); until then three
+ * Cursor-named flags, two of them constant `false` on both loops.
  */
 
 import { describe, it, expect } from "vitest";
@@ -22,65 +23,50 @@ const CONFIG: StreamingConfig = {
   burstThreshold: 50,
 };
 
-const NO_FORCE = {
-  deltaEnricherDirty: false,
-  todosDirty: false,
-  contentDirty: false,
-} as const;
-
 describe("shouldPersistStreamingStatus", () => {
   it("persists on the first event via the scheduler (kills the opaque-wait at turn start)", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
-    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 1, 0)).toBe(true);
+    expect(shouldPersistStreamingStatus(false, scheduler, 1, 0)).toBe(true);
   });
 
-  it("does not persist a sub-500ms token delta with no force signal", () => {
+  it("does not persist a sub-500ms token delta while the transcript is clean", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
     scheduler.markUpdateSent(1, 0); // first flush already sent
 
     // 100ms later, one more delta event — too soon for the time cadence.
-    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 2, 100)).toBe(false);
+    expect(shouldPersistStreamingStatus(false, scheduler, 2, 100)).toBe(false);
   });
 
   it("persists a token delta once the 500ms cadence elapses", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
     scheduler.markUpdateSent(1, 0);
 
-    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 2, 500)).toBe(true);
+    expect(shouldPersistStreamingStatus(false, scheduler, 2, 500)).toBe(true);
   });
 
-  it.each([
-    ["contentDirty (tool call / sub-agent)", { ...NO_FORCE, contentDirty: true }],
-    ["todosDirty", { ...NO_FORCE, todosDirty: true }],
-    ["deltaEnricherDirty (shell output)", { ...NO_FORCE, deltaEnricherDirty: true }],
-  ])("force-flushes immediately on %s, bypassing the time cadence", (_label, signals) => {
+  it("flushes immediately when the transcript is dirty, bypassing the time cadence", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
     scheduler.markUpdateSent(1, 0);
 
     // Only 1ms after the last flush: the scheduler alone would say no...
-    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 2, 1)).toBe(false);
-    // ...but any discrete force signal flushes now.
-    expect(shouldPersistStreamingStatus(signals, scheduler, 2, 1)).toBe(true);
+    expect(shouldPersistStreamingStatus(false, scheduler, 2, 1)).toBe(false);
+    // ...but a discrete transcript change flushes now.
+    expect(shouldPersistStreamingStatus(true, scheduler, 2, 1)).toBe(true);
   });
 
   // The #179 starvation scenario: a short turn of < 20 events. Under the old
   // `eventCount % 20` gate, a tool call appearing at event 3 (and completing at
   // event 4) would never be persisted until the unconditional final flush. With
-  // the converged decision, the tool lifecycle force-flushes the instant it
-  // happens, regardless of how few events the turn has.
+  // the converged decision, the tool lifecycle flushes the instant it happens,
+  // regardless of how few events the turn has.
   it("surfaces a tool call on a short (<20 event) turn", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
     const flushes: number[] = [];
     let clock = 0;
 
     // Helper mirroring the loop: decide, then mark both clocks on a flush.
-    const tick = (eventCount: number, contentDirty: boolean) => {
-      const persist = shouldPersistStreamingStatus(
-        { ...NO_FORCE, contentDirty },
-        scheduler,
-        eventCount,
-        clock,
-      );
+    const tick = (eventCount: number, transcriptDirty: boolean) => {
+      const persist = shouldPersistStreamingStatus(transcriptDirty, scheduler, eventCount, clock);
       if (persist) {
         flushes.push(eventCount);
         scheduler.markUpdateSent(eventCount, clock);
@@ -90,8 +76,8 @@ describe("shouldPersistStreamingStatus", () => {
 
     tick(1, false); // assistant delta — first-event flush
     tick(2, false); // thinking delta — within 500ms, no flush
-    tick(3, true);  // tool call starts — force-flush
-    tick(4, true);  // tool call completes — force-flush
+    tick(3, true);  // tool call starts — the transcript is dirty, flush
+    tick(4, true);  // tool call completes — dirty again, flush
     tick(5, false); // closing assistant delta — within 500ms, no flush
 
     // The tool lifecycle (events 3 and 4) is observed live; event 1 is the

package/src/shared/__tests__/prompt-sections.test.ts

@@ -2,7 +2,7 @@
  * The shared prompt glue (`shared/prompt-sections.ts`): the standing order,
  * the input-files lines, the skill selection and the also-available sentence
  * (the sentence's arms came from `skill-writer.test.ts`, retired with its
- * module at S3 M5). What each harness renders AROUND these is pinned whole by
+ * module in #1096). What each harness renders AROUND these is pinned whole by
  * the two builders' prompt goldens (`execute-deep-agent/__tests__/
  * prompt-goldens.test.ts`, `execute-cursor/__tests__/prompt-goldens.test.ts`);
  * this file pins the glue's own contract, harness-free.

package/src/shared/__tests__/stamp-flowed-rows.test.ts

@@ -1,7 +1,7 @@
 /**
  * Unit tests for the shared turn-boundary flowed-row stamping
  * (`shared/tool-row.ts` `stampFlowedFileEditRows` /
- * `stampFlowedSubAgentFileEditRows`; the deep-agent's copy until S3 M4), with
+ * `stampFlowedSubAgentFileEditRows`; the deep-agent's copy until #1096), with
  * emphasis on the sub-agent path added by the DD-24 follow-up: sub-agent edit
  * rows fold into the parent turn's change set, so they carry the parent change
  * set id, scoped to this turn by tool-call-id novelty (they lack the

package/src/shared/__tests__/status-offload.test.ts

@@ -342,7 +342,7 @@ describe("offloadOversizedToolOutputs", () => {
     await offloadOversizedToolOutputs(status, ctx);
     expect(uploads).toHaveLength(1);
 
-    // Simulate mergeToolCallEvent re-inflating the inline result with the SAME
+    // Simulate the builder's finish upsert re-inflating the inline result with the SAME
     // bytes on a subsequent persist; the ref's content hash still matches.
     status.messages[0].toolCalls[0].result = result;
     await offloadOversizedToolOutputs(status, ctx);

package/src/shared/__tests__/streaming-scheduler.test.ts

@@ -1,7 +1,6 @@
 import { describe, it, expect, vi, afterEach } from "vitest";
 import {
   StreamingUpdateScheduler,
-  UpdateReason,
   loadStreamingConfig,
   type StreamingConfig,
 } from "../streaming-scheduler.js";
@@ -17,7 +16,7 @@ describe("StreamingUpdateScheduler", () => {
     it("always sends on first event", () => {
       const s = new StreamingUpdateScheduler(BASE_CONFIG, 0);
       expect(s.shouldSendUpdate(1, 0)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.FIRST_UPDATE);
+      expect(s.updateReason).toBe("first_update");
     });
 
     it("does not send if zero events processed", () => {
@@ -32,7 +31,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(0, 0);
 
       expect(s.shouldSendUpdate(1, 500)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.TIME_THRESHOLD);
+      expect(s.updateReason).toBe("time_threshold");
     });
 
     it("does not send before minInterval", () => {
@@ -40,7 +39,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(0, 0);
 
       expect(s.shouldSendUpdate(1, 499)).toBe(false);
-      expect(s.updateReason).toBe(UpdateReason.NONE);
+      expect(s.updateReason).toBe("none");
     });
 
     it("does not send after minInterval with zero new events", () => {
@@ -57,7 +56,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(0, 0);
 
       expect(s.shouldSendUpdate(50, 100)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.BURST_PROTECTION);
+      expect(s.updateReason).toBe("burst_protection");
     });
 
     it("does not send at threshold - 1", () => {
@@ -74,7 +73,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(10, 0);
 
       expect(s.shouldSendUpdate(10, 5000)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.KEEPALIVE);
+      expect(s.updateReason).toBe("keepalive");
     });
 
     it("does not send keepalive before maxInterval", () => {
@@ -91,7 +90,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(10, 1000);
 
       expect(s.shouldSendUpdate(11, 1500)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.TIME_THRESHOLD);
+      expect(s.updateReason).toBe("time_threshold");
 
       s.markUpdateSent(11, 1500);
 
@@ -125,7 +124,7 @@ describe("StreamingUpdateScheduler", () => {
       const s = new StreamingUpdateScheduler(BASE_CONFIG, 0);
       // First check with event and enough time — should be FIRST_UPDATE, not TIME_THRESHOLD
       expect(s.shouldSendUpdate(1, 600)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.FIRST_UPDATE);
+      expect(s.updateReason).toBe("first_update");
     });
 
     it("time_threshold takes priority over burst_protection", () => {
@@ -134,7 +133,7 @@ describe("StreamingUpdateScheduler", () => {
 
       // Both time and burst conditions met — time wins
       expect(s.shouldSendUpdate(50, 500)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.TIME_THRESHOLD);
+      expect(s.updateReason).toBe("time_threshold");
     });
   });
 });

package/src/shared/__tests__/todos.test.ts

@@ -1,6 +1,6 @@
 /**
  * Unit tests for applyTodoUpdate — the harness-agnostic to-do map projection
- * shared by the Cursor TodoTracker and the native v2/v3 status builders.
+ * the one transcript builder projects a todo write through, for both harnesses.
  *
  * These pin the exact mapping contract (status coercion, id synthesis,
  * created_at preservation, merge vs. full-replace, clear-on-empty, defensive

package/src/shared/__tests__/tool-row.test.ts

@@ -382,7 +382,7 @@ describe("collectSettledToolCallIds", () => {
     // scoping them as this-turn would mis-attribute a dead call to the
     // resuming turn's change set. (The Cursor monotonic guard makes the
     // opposite call for the same status so a replayed event can still advance
-    // the row; see isTerminalToolStatus in message-translator.ts.)
+    // the row; see isSettled in harness/transcript/builder.ts.)
     const ids = collectSettledToolCallIds([
       msgWith("tc-interrupted", ToolCallStatus.TOOL_CALL_INTERRUPTED),
     ]);

package/src/shared/approval-policy.ts

@@ -466,3 +466,98 @@ export function resolveApprovalMessage(
       return JSON.stringify(value);
     });
 }
+
+// ── The gate's decision ─────────────────────────────────────────────
+
+/**
+ * THE approval-message template per mutating built-in category — the one
+ * table both harnesses word their approval cards from (since #1097).
+ * Keyed by category (not raw tool name) so every alias of a mutation renders
+ * one message; placeholders resolve against the stream arg shape
+ * (`path`/`command`; `resolveApprovalMessage`). The native gate decides with
+ * it (`resolveToolApproval`), the Cursor translator words its `gate` from it
+ * (`execute-cursor/approval-policy.ts` `getBuiltInApprovalMessage`), and the
+ * Cursor boundary resolves a denied call's message through the same path.
+ *
+ * Until then the Cursor harness carried a table of its own and the two differed
+ * by a word — `shell` read "Run command" there and "Execute command" here.
+ * Unified on the plainer word: a user reads "Run command" and knows
+ * what is being asked. Known and deliberately left (#1112):
+ * `write` resolves `{{args.path}}`, while deepagents' file tools send
+ * `file_path`, so a gated native write reads "Write file: <unknown>".
+ */
+export const CATEGORY_APPROVAL_MESSAGE: Record<ToolApprovalCategory, string> = {
+  write: "Write file: {{args.path}}",
+  delete: "Delete: {{args.path}}",
+  shell: "Run command: {{args.command}}",
+};
+
+/** What the gate decides for one call: whether it waits, the message the card shows, and which layer said so. */
+export interface ApprovalRequirement {
+  readonly requiresApproval: boolean;
+  readonly message: string;
+  /** Which policy layer determined this verdict — stamped on the shadow receipt. */
+  readonly source: PolicySource;
+}
+
+/**
+ * THE approval decision for one tool call — the same function the native gate
+ * (`middleware/approval-gate.ts`) interrupts on and the native translator
+ * reports as `tool_started.gate`, so the row can never disagree with the gate
+ * about whether a call waits (since #1097; until then the transcript
+ * builder carried its own weaker copy that gated MCP tools only). Its
+ * read-side twin is {@link resolveApprovalProvenance}, which answers "which
+ * layer governs this call" for EVERY call, gated or not.
+ *
+ * MCP tools stay governed by the connect-flow classifier + four-level policy
+ * chain. The policy map carries only the tools that REQUIRE approval, so an
+ * absent entry means the classifier already auto-approved it — fail-OPEN is
+ * correct here (a fail-closed default would re-gate everything the classifier
+ * cleared). A server-scoped lease surfaces as an absent entry too: the leased
+ * server's tools are dropped from `policies` upstream (`mergeApprovalPolicies`),
+ * so a lease-cleared MCP tool takes the same auto-approve path (its receipt
+ * therefore reads classifier_default rather than approval_lease; a faithful
+ * per-server lease provenance would need the lease set threaded here and is
+ * deferred with the rest of the persisted-receipt work).
+ *
+ * Built-in/platform tools: gate exactly the mutating categories through the
+ * shared classifier — fail-CLOSED for the mutating set (write/edit/delete/shell
+ * require approval), fail-open for read-only and unclassified built-ins. A
+ * run-lifetime category lease (the user chose "approve all <category>" earlier
+ * in this run) auto-approves every built-in of that category for the rest of
+ * the run — the scoped successor to auto-approve-all.
+ */
+export function resolveToolApproval(
+  toolName: string,
+  serverSlug: string,
+  args: Record<string, unknown>,
+  policies: ReadonlyMap<string, MergedToolPolicy>,
+  leasedCategories: ReadonlySet<ToolApprovalCategory>,
+): ApprovalRequirement {
+  if (serverSlug) {
+    const key = `${serverSlug}/${toolName}`;
+    const policy = policies.get(key);
+    if (policy) {
+      return {
+        requiresApproval: policy.requiresApproval,
+        message: resolveApprovalMessage(policy.approvalMessage, toolName, args),
+        source: policy.source,
+      };
+    }
+    return { requiresApproval: false, message: "", source: "classifier_default" };
+  }
+
+  const category = toolApprovalCategory(toolName);
+  if (category) {
+    if (leasedCategories.has(category)) {
+      return { requiresApproval: false, message: "", source: "approval_lease" };
+    }
+    return {
+      requiresApproval: true,
+      message: resolveApprovalMessage(CATEGORY_APPROVAL_MESSAGE[category], toolName, args),
+      source: "builtin_category",
+    };
+  }
+
+  return { requiresApproval: false, message: "", source: "builtin_category" };
+}