@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/src/activities/execute-deep-agent/status-builder-shared.ts

@@ -9,7 +9,15 @@
 import { create } from "@bufbuild/protobuf";
 import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
 import type { StreamingUsageSummary } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { utcTimestamp } from "../../shared/status.js";
+import {
+  POLICY_ENGINE_VERSION,
+  resolveApprovalProvenance,
+  toProtoPolicySource,
+  type MergedToolPolicy,
+} from "../../shared/approval-policy.js";
+import type { ToolApprovalCategory } from "../../shared/tool-kind.js";
 
 // ── Usage Accumulator ──────────────────────────────────────────────
 
@@ -129,30 +137,61 @@ export function extractToolResultV3(output: unknown): string {
   }
 }
 
-// ── Approval Args Sanitization ─────────────────────────────────────
+// ── Authorization Provenance ───────────────────────────────────────
 
-const SENSITIVE_ARG_KEYS = new Set([
-  "password", "token", "secret", "api_key", "apikey",
-  "credentials", "auth", "authorization",
-]);
+/**
+ * The policy inputs the StatusBuilders need to attribute a tool call's approval
+ * provenance. The full {@link ApprovalPolicyProvider} (status-builder.ts) is
+ * structurally this — defined here so the shared stamper has no import cycle back
+ * into the builders.
+ */
+export interface ApprovalProvenanceInputs {
+  readonly policies: ReadonlyMap<string, MergedToolPolicy>;
+  readonly toolServerMap: ReadonlyMap<string, string>;
+  /**
+   * Built-in categories with a run-lifetime lease, so a leased built-in is
+   * attributed to its lease (approval_lease) rather than the plain category gate.
+   * Optional (mirroring {@link ApprovalGateConfig.leasedCategories}); absent =
+   * no lease active.
+   */
+  readonly leasedCategories?: ReadonlySet<ToolApprovalCategory>;
+  /** Pre-armed spec.auto_approve_all — the one whole-run global bypass. */
+  readonly globalBypass: boolean;
+}
 
-const MAX_ARGS_PREVIEW_LENGTH = 500;
+/** Shared empty set so a provider without leases allocates nothing per call. */
+const NO_LEASED_CATEGORIES: ReadonlySet<ToolApprovalCategory> = new Set();
 
-export function sanitizeArgsPreview(args: Record<string, unknown>): string {
-  const sanitized: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(args)) {
-    if (SENSITIVE_ARG_KEYS.has(key.toLowerCase())) {
-      sanitized[key] = "[REDACTED]";
-    } else {
-      sanitized[key] = value;
-    }
-  }
-  try {
-    const json = JSON.stringify(sanitized);
-    return json.length > MAX_ARGS_PREVIEW_LENGTH
-      ? json.slice(0, MAX_ARGS_PREVIEW_LENGTH) + "…"
-      : json;
-  } catch {
-    return "";
-  }
+/**
+ * Stamp a tool call's authorization provenance — which policy layer governs it —
+ * alongside `tool_kind`, in exactly the spot both builders classify the tool.
+ *
+ * This is the read-side companion to the gate: it records WHY a tool is gated or
+ * auto-approved for every observed tool call, so the persisted record is
+ * auditable and the UI can explain the gate. Built-ins that no layer governs (a
+ * read-only built-in) and the no-provider path both leave the field at
+ * UNSPECIFIED, like an unclassified tool_kind.
+ */
+export function stampApprovalProvenance(
+  tc: ToolCall,
+  provider: ApprovalProvenanceInputs | null,
+): void {
+  if (!provider) return;
+  const serverSlug = tc.mcpServerSlug || provider.toolServerMap.get(tc.name) || "";
+  const source = resolveApprovalProvenance(
+    tc.name,
+    serverSlug,
+    provider.policies,
+    provider.leasedCategories ?? NO_LEASED_CATEGORIES,
+    provider.globalBypass,
+  );
+  tc.approvalPolicySource = toProtoPolicySource(source);
+  if (source) tc.policyEngineVersion = POLICY_ENGINE_VERSION;
 }
+
+// ── Approval Args Sanitization ─────────────────────────────────────
+
+// Relocated to src/shared/args-preview.ts so both harnesses share one home for
+// arg sanitization. Re-exported here so the native importers (status-builder,
+// v3-status-builder, approval-file-change) keep their existing import path.
+export { sanitizeArgsPreview } from "../../shared/args-preview.js";

package/src/activities/execute-deep-agent/status-builder.ts

@@ -25,7 +25,7 @@ import {
   MessageType,
   ToolCallStatus,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { type MergedToolPolicy, resolveApprovalMessage as resolveApprovalMsg } from "../../shared/approval-policy.js";
+import { resolveApprovalMessage as resolveApprovalMsg } from "../../shared/approval-policy.js";
 import { classifyTool } from "../../shared/tool-kind.js";
 import { ExecutionState } from "./execution-state.js";
 import { utcTimestamp } from "../../shared/status.js";
@@ -34,6 +34,8 @@ import {
   UsageAccumulator,
   extractToolResult,
   sanitizeArgsPreview,
+  stampApprovalProvenance,
+  type ApprovalProvenanceInputs,
 } from "./status-builder-shared.js";
 
 /** Minimal LangGraph streamEvents v2 event shape. */
@@ -48,11 +50,16 @@ export interface StreamEvent {
 
 type EventHandler = (event: StreamEvent, namespace: string) => void;
 
-export interface ApprovalPolicyProvider {
-  readonly policies: ReadonlyMap<string, MergedToolPolicy>;
-  readonly toolServerMap: ReadonlyMap<string, string>;
-  readonly autoApproveAll: boolean;
-}
+/**
+ * The approval inputs the StatusBuilder reads to set requires-approval and to
+ * attribute each tool call's authorization provenance.
+ *
+ * Extends {@link ApprovalProvenanceInputs} so the provenance stamper and the
+ * builder share one shape. `globalBypass` is the pre-armed spec.auto_approve_all
+ * (the one whole-run global bypass); `leasedCategories` lets a leased built-in be
+ * attributed to its run-lifetime lease rather than the plain category gate.
+ */
+export interface ApprovalPolicyProvider extends ApprovalProvenanceInputs {}
 
 export class StatusBuilder {
   readonly executionId: string;
@@ -67,6 +74,14 @@ export class StatusBuilder {
     this.executionId = executionId;
     this.state = new ExecutionState(initialStatus);
 
+    // Resume path: when constructed from a persisted transcript (status seeded
+    // in index.ts on a durable-checkpoint resume), rebuild the tool-call index
+    // so resumed tool events reconcile to the existing calls instead of
+    // duplicating them. A first run carries no messages, so this is a no-op.
+    if (initialStatus.messages.length > 0) {
+      this.state.rebuildToolCallIndex();
+    }
+
     initialStatus.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
     if (!initialStatus.startedAt) {
       initialStatus.startedAt = utcTimestamp();
@@ -198,11 +213,29 @@ export class StatusBuilder {
   }
 
   private handleToolStart(event: StreamEvent, namespace: string): void {
+    const toolName = event.name ?? "unknown_tool";
+
+    // Resume reconciliation (v2): the seeded WAITING_APPROVAL tool call was
+    // indexed by its tool_call_id, but a resumed on_tool_start carries a fresh
+    // LangGraph run_id and exposes no tool_call_id. Match by tool name +
+    // pending-approval status so the existing call is resolved in place rather
+    // than duplicated, then re-key it under run_id so handleToolEnd resolves the
+    // same object. This name match is a v2-only fallback — v3 (the default) keys
+    // by the exact tool_call_id; it resolves the first pending call of that
+    // name, which is unambiguous for the single-gate resume the workflow drives.
+    const seeded = this.findResumableSeededToolCall(toolName);
+    if (seeded) {
+      seeded.status = ToolCallStatus.TOOL_CALL_RUNNING;
+      this.state.toolCalls.set(event.run_id, seeded);
+      this.state.toolStartTimes.set(event.run_id, performance.now());
+      this._forceNextUpdate = true;
+      return;
+    }
+
     const parentMsg = this.state.currentAiMessage.get(namespace)
       ?? this.ensureAiMessageForToolCall(event.run_id, namespace);
     if (!parentMsg) return;
 
-    const toolName = event.name ?? "unknown_tool";
     const rawArgs = event.data?.input as Record<string, unknown> | undefined;
     const args = rawArgs ?? {};
 
@@ -228,6 +261,11 @@ export class StatusBuilder {
     // Classify after mcpServerSlug is set so MCP tools resolve correctly.
     tc.toolKind = classifyTool(tc.name, tc.mcpServerSlug);
 
+    // Stamp authorization provenance in the same spot as tool_kind, for every
+    // observed tool call (gated or auto-approved). A gated call is re-seeded on
+    // reinvocation (index.ts) with the same source carried through the interrupt.
+    stampApprovalProvenance(tc, this.approvalProvider);
+
     if (approvalReq.requiresApproval) {
       tc.requiresApproval = true;
       tc.approvalMessage = approvalReq.message;
@@ -248,6 +286,23 @@ export class StatusBuilder {
     this._forceNextUpdate = true;
   }
 
+  /**
+   * Find a seeded tool call awaiting approval for the given name, for v2 resume
+   * reconciliation. Returns the first WAITING_APPROVAL call of that name in the
+   * rebuilt index, or undefined when none is pending (the normal first-run path).
+   */
+  private findResumableSeededToolCall(toolName: string): ToolCall | undefined {
+    for (const tc of this.state.toolCalls.values()) {
+      if (
+        tc.name === toolName &&
+        tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL
+      ) {
+        return tc;
+      }
+    }
+    return undefined;
+  }
+
   private checkApprovalRequirement(
     toolName: string,
     args: Record<string, unknown>,
@@ -258,7 +313,7 @@ export class StatusBuilder {
 
     const serverSlug = this.approvalProvider.toolServerMap.get(toolName) ?? "";
 
-    if (this.approvalProvider.autoApproveAll) {
+    if (this.approvalProvider.globalBypass) {
       return { requiresApproval: false, message: "", serverSlug };
     }
 

package/src/activities/execute-deep-agent/streaming-side-effects.ts

@@ -9,12 +9,7 @@
 import type { V3ProtocolEvent } from "./v3-event-recorder.js";
 import type { InlinePublisher } from "./inline-publisher.js";
 import type { WriteBackCoordinator } from "./writeback-coordinator.js";
-
-const FILE_MODIFYING_TOOLS = new Set([
-  "write_file", "edit_file", "create_file",
-  "write", "edit", "create",
-  "str_replace_editor",
-]);
+import { extractFilePath, isFileModifyingTool } from "../../shared/file-tools.js";
 
 interface CachedToolInput {
   readonly toolName: string;
@@ -64,7 +59,7 @@ export class StreamingSideEffects {
       const cached = this.inputCache.get(callId);
       this.inputCache.delete(callId);
       if (!cached) return;
-      if (!FILE_MODIFYING_TOOLS.has(cached.toolName)) return;
+      if (!isFileModifyingTool(cached.toolName)) return;
 
       const filePath = extractFilePath(cached.input);
       if (!filePath) return;
@@ -78,12 +73,3 @@ export class StreamingSideEffects {
     }
   }
 }
-
-function extractFilePath(input: Record<string, unknown>): string | null {
-  if (typeof input.path === "string") return input.path;
-  if (typeof input.file_path === "string") return input.file_path;
-  if (typeof input.filePath === "string") return input.filePath;
-  if (typeof input.filename === "string") return input.filename;
-  if (typeof input.file === "string") return input.file;
-  return null;
-}

package/src/activities/execute-deep-agent/streaming.ts

@@ -42,6 +42,7 @@ import type { InlinePublisher } from "./inline-publisher.js";
 import type { WriteBackCoordinator } from "./writeback-coordinator.js";
 import { createV2EventRecorder } from "./event-recorder.js";
 import { streamExecutionV3 } from "./streaming-v3.js";
+import { extractFilePath, isFileModifyingTool } from "../../shared/file-tools.js";
 
 const DEFAULT_STALL_TIMEOUT_MS = 120_000;
 
@@ -283,25 +284,14 @@ function checkStallTimeout(
   }
 }
 
-const FILE_MODIFYING_TOOLS = new Set([
-  "write_file", "edit_file", "create_file",
-  "write", "edit", "create",
-  "str_replace_editor",
-]);
-
 function extractFilePathFromToolEnd(event: StreamEvent): string | null {
   const toolName = event.name ?? "";
-  if (!FILE_MODIFYING_TOOLS.has(toolName)) return null;
+  if (!isFileModifyingTool(toolName)) return null;
 
   const input = event.data?.input as Record<string, unknown> | undefined;
   if (!input) return null;
 
-  if (typeof input.path === "string") return input.path;
-  if (typeof input.file_path === "string") return input.file_path;
-  if (typeof input.filename === "string") return input.filename;
-  if (typeof input.file === "string") return input.file;
-
-  return null;
+  return extractFilePath(input);
 }
 
 export class StallTimeoutError extends Error {

package/src/activities/execute-deep-agent/subagent-transformer.ts

@@ -25,7 +25,9 @@ import type { SubAgent, McpServerUsage } from "@stigmer/protos/ai/stigmer/agenti
 
 import type { WorkspaceBackend } from "../../shared/workspace/types.js";
 import type { StigmerClient } from "../../client/stigmer-client.js";
-import type { MergedToolPolicy } from "../../shared/approval-policy.js";
+import type { ApprovalGateConfig } from "../../middleware/approval-gate.js";
+import { CasCaptureFilesystemBackend } from "./cas-capture-backend.js";
+import type { CasCaptureObserver } from "./cas-capture-observer.js";
 import type { CostCapMiddleware, StigmerMiddleware } from "../../middleware/index.js";
 import { createThinkTool } from "../../middleware/index.js";
 import { buildSubAgentMiddleware } from "./subagent-wiring.js";
@@ -131,18 +133,32 @@ export interface SubagentTransformOptions {
   readonly parentMcpUsages: readonly McpServerUsage[];
   readonly skillClient: StigmerClient;
   readonly workspaceBackend: WorkspaceBackend;
-  readonly approvalPolicies: ReadonlyMap<string, MergedToolPolicy>;
-  readonly autoApproveAll: boolean;
+  /**
+   * The parent's approval-gate config, inherited verbatim so a mutating tool
+   * inside a sub-agent is gated identically to one in the parent (same policies,
+   * toolServerMap, fingerprint key, execution id). Null under auto-approve-all,
+   * where the parent gate is inert too — sub-agents then install no gate either.
+   */
+  readonly approvalGate: ApprovalGateConfig | null;
+  /**
+   * The parent turn's shared CAS observer, present only in capture mode. When
+   * supplied, each sub-agent is built with a CAS-observing filesystem backend
+   * wired to THIS observer, so its gitignored writes are captured into the same
+   * change set as the parent's (Session 26, DD-19). Absent outside capture mode,
+   * where sub-agents keep the plain backend and the classic gitignored deny-gate.
+   */
+  readonly casObserver?: CasCaptureObserver;
   readonly parentModelName: string;
   readonly parentHasNativeThinking: boolean;
   readonly costCap?: CostCapMiddleware;
   /**
    * Builds a configured chat-model instance for a given model name. When
    * provided, sub-agents are compiled with the same proxy-aware model client
-   * as the parent (base URL, auth headers, API key). When absent (unit tests),
-   * the model name string is passed to deepagents directly.
+   * as the parent (base URL, auth headers, API key) — including registry-id
+   * resolution, which is why this is async. When absent (unit tests), the
+   * model name string is passed to deepagents directly.
    */
-  readonly modelFactory?: (modelName: string) => BaseChatModel;
+  readonly modelFactory?: (modelName: string) => Promise<BaseChatModel>;
 }
 
 // =========================================================================
@@ -404,9 +420,12 @@ export async function compileSubagents(
   transformed: readonly TransformedSubagent[],
   opts: {
     readonly costCap?: CostCapMiddleware;
+    readonly approvalGate?: ApprovalGateConfig | null;
     readonly parentModelName: string;
     readonly workspaceRootDir: string;
-    readonly modelFactory?: (modelName: string) => BaseChatModel;
+    /** Shared CAS observer (capture mode only); see {@link SubagentTransformOptions.casObserver}. */
+    readonly casObserver?: CasCaptureObserver;
+    readonly modelFactory?: (modelName: string) => Promise<BaseChatModel>;
   },
 ): Promise<CompiledSubAgent[]> {
   if (transformed.length === 0) return [];
@@ -416,23 +435,40 @@ export async function compileSubagents(
 
   for (const spec of transformed) {
     try {
+      // Structural coupling (DD-19): a sub-agent gate flows gitignored writes into
+      // CAS iff a CAS observer backs that sub-agent's filesystem backend. Deriving
+      // both from the same `casObserver` makes "unobserved unreviewable bytes"
+      // impossible by construction.
       const middleware = buildSubAgentMiddleware({
         costCap: opts.costCap,
+        approvalGate: opts.approvalGate,
+        captureIgnored: !!opts.casObserver,
       });
 
       const modelName = spec.model ?? opts.parentModelName;
-      // Use a configured model instance (proxy base URL + auth) when a
-      // factory is supplied so sub-agent LLM calls route through the same
-      // proxy as the parent. Falling back to the bare name lets deepagents
-      // construct a default client (unit tests / no-proxy paths).
-      const model = opts.modelFactory ? opts.modelFactory(modelName) : modelName;
+      // Use a configured model instance (proxy base URL + auth, plus registry
+      // id -> API id resolution) when a factory is supplied so sub-agent LLM
+      // calls route through the same proxy as the parent. Falling back to the
+      // bare name lets deepagents construct a default client (unit tests /
+      // no-proxy paths).
+      const model = opts.modelFactory ? await opts.modelFactory(modelName) : modelName;
+
+      // Capture mode: a CAS-observing backend wired to the shared observer, so
+      // the sub-agent's gitignored writes are captured (same class the parent
+      // uses). Otherwise the plain backend + classic gitignored deny-gate.
+      const backend = opts.casObserver
+        ? new CasCaptureFilesystemBackend(
+            { rootDir: opts.workspaceRootDir },
+            { observer: opts.casObserver },
+          )
+        : new FilesystemBackend({ rootDir: opts.workspaceRootDir });
 
       const agentGraph = await createDeepAgent({
         model,
         systemPrompt: spec.systemPrompt,
         tools: spec.tools.length > 0 ? spec.tools : undefined,
         middleware: middleware as unknown[],
-        backend: new FilesystemBackend({ rootDir: opts.workspaceRootDir }),
+        backend,
         generalPurposeAgent: false,
       } as Parameters<typeof createDeepAgent>[0]);
 
@@ -489,6 +525,8 @@ export async function transformAndCompileSubagents(
     parentMcpUsages,
     skillClient,
     workspaceBackend,
+    approvalGate,
+    casObserver,
     parentModelName,
     parentHasNativeThinking,
     costCap,
@@ -602,8 +640,10 @@ export async function transformAndCompileSubagents(
   // Step 4: Compile all subagents
   const compiled = await compileSubagents(allSpecs, {
     costCap,
+    approvalGate,
     parentModelName,
     workspaceRootDir: workspaceBackend.rootDir,
+    casObserver,
     modelFactory,
   });
 

package/src/activities/execute-deep-agent/subagent-wiring.ts

@@ -5,13 +5,21 @@
  * - Fresh loop detection (independent cycle tracking)
  * - Fresh tool truncation (same limits as parent)
  * - Periodic execution budget (interval=30, max=4 advisories)
+ * - Approval gate (so a mutating tool *inside* a sub-agent is gated, not
+ *   bypassed) — installed only when the parent itself is gated
+ *   (`approvalGate` present; absent under auto-approve-all)
  * - Shared cost cap view (parent's budget, no reset on sub-agent start)
  *
  * The sub-agent middleware stack does NOT include:
  * - Graceful stop (parent handles STOP signal propagation)
  * - OTel spans (parent's OTel context propagates automatically)
  * - Error hints (applied at tool level, not sub-agent level)
- * - Approval gate (sub-agent interrupts propagate to parent checkpoint)
+ *
+ * Approval-gate note: the gate is what *creates* the LangGraph `interrupt()`.
+ * A sub-agent's interrupt does surface at the parent checkpoint and resumes
+ * correctly (verified in subagent-approval-propagation.test.ts), but only if
+ * the gate runs inside the sub-agent in the first place — omitting it here was
+ * the live HITL bypass this wiring closes.
  */
 
 import type { StigmerMiddleware, ToolTruncationConfig } from "../../middleware/types.js";
@@ -19,6 +27,10 @@ import type { CostCapMiddleware } from "../../middleware/index.js";
 import { createLoopDetectionMiddleware } from "../../middleware/loop-detection.js";
 import { createToolTruncationMiddleware } from "../../middleware/tool-truncation.js";
 import { createExecutionBudgetMiddleware } from "../../middleware/execution-budget.js";
+import {
+  createApprovalGateMiddleware,
+  type ApprovalGateConfig,
+} from "../../middleware/approval-gate.js";
 
 const SUB_AGENT_ADVISORY_INTERVAL = 30;
 const SUB_AGENT_MAX_ADVISORIES = 4;
@@ -26,13 +38,31 @@ const SUB_AGENT_MAX_ADVISORIES = 4;
 export interface SubAgentMiddlewareOptions {
   readonly costCap?: CostCapMiddleware;
   readonly toolTruncation?: Partial<ToolTruncationConfig>;
+  /**
+   * Approval gate config inherited from the parent. When present, the sub-agent
+   * gates its own mutating tool calls; when null/undefined (e.g. auto-approve-
+   * all, where the parent gate is inert too) no gate is installed.
+   */
+  readonly approvalGate?: ApprovalGateConfig | null;
+  /**
+   * Route the sub-agent's gitignored writes into CAS capture (apply-then-review)
+   * instead of the interrupt gate. TRUE iff a CAS observer backs the sub-agent's
+   * filesystem backend (DD-19) — `compileSubagents` derives it from
+   * `!!casObserver`, keeping the gate and the backend coupled. Default false =
+   * the classic gitignored deny-gate, because flowing a gitignored edit on an
+   * unobserved backend would apply unreviewable bytes.
+   */
+  readonly captureIgnored?: boolean;
 }
 
 /**
  * Build the middleware stack for a single sub-agent.
  *
- * Returns an ordered array matching the Python `compile_subagent` composition:
- * loop detection → execution budget (periodic) → tool truncation → cost cap view.
+ * Returns an ordered array mirroring the parent composition:
+ * loop detection → execution budget (periodic) → tool truncation →
+ * [approval gate] → cost cap view. The gate sits before the cost-cap view so an
+ * approval pause happens before budget accounting, matching the parent order
+ * (…→ truncation → graceful-stop → approval gate → cost cap …).
  */
 export function buildSubAgentMiddleware(
   options: SubAgentMiddlewareOptions = {},
@@ -48,6 +78,23 @@ export function buildSubAgentMiddleware(
 
   stack.push(createToolTruncationMiddleware(options.toolTruncation));
 
+  if (options.approvalGate) {
+    // captureIgnored (DD-19): a sub-agent flows gitignored writes into CAS iff a
+    // CAS observer backs its filesystem backend (compileSubagents passes this as
+    // `!!casObserver`). When true, inherit the parent gate verbatim so its
+    // captureIgnored + recordBlockedSecret feed the SAME shared observer that
+    // backs the sub-agent's writes. When false (default; non-capture mode, or no
+    // observer), force CAS routing off and drop the blocked-secret sink so
+    // gitignored paths stay on the interrupt gate — a flowed gitignored edit on an
+    // unobserved backend would apply unobserved, unreviewable bytes. Sub-agent
+    // git-tracked edits are always captured by the backend-agnostic boundary diff.
+    stack.push(createApprovalGateMiddleware(
+      options.captureIgnored
+        ? options.approvalGate
+        : { ...options.approvalGate, captureIgnored: false, recordBlockedSecret: undefined },
+    ));
+  }
+
   if (options.costCap) {
     stack.push(options.costCap.forSubAgent());
   }

package/src/activities/execute-deep-agent/v3-status-builder.ts

@@ -24,7 +24,7 @@ import {
   MessageType,
   ToolCallStatus,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { type MergedToolPolicy, resolveApprovalMessage as resolveApprovalMsg } from "../../shared/approval-policy.js";
+import { resolveApprovalMessage as resolveApprovalMsg } from "../../shared/approval-policy.js";
 import { classifyTool } from "../../shared/tool-kind.js";
 import { ExecutionState } from "./execution-state.js";
 import { utcTimestamp } from "../../shared/status.js";
@@ -36,6 +36,7 @@ import {
   UsageAccumulator,
   extractToolResultV3,
   sanitizeArgsPreview,
+  stampApprovalProvenance,
 } from "./status-builder-shared.js";
 import { SubAgentTracker } from "./subagent-tracker.js";
 
@@ -54,6 +55,15 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     this.executionId = executionId;
     this.state = new ExecutionState(initialStatus);
 
+    // Resume path: when constructed from a persisted transcript (status seeded
+    // in index.ts on a durable-checkpoint resume), rebuild the tool-call index
+    // so resumed tool_started/tool_finished events reconcile to the existing
+    // calls instead of duplicating them. A first run carries no messages, so
+    // this is a no-op.
+    if (initialStatus.messages.length > 0) {
+      this.state.rebuildToolCallIndex();
+    }
+
     initialStatus.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
     if (!initialStatus.startedAt) {
       initialStatus.startedAt = utcTimestamp();
@@ -244,6 +254,25 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     input: Record<string, unknown>,
     namespace: string,
   ): void {
+    // Resume reconciliation: the gated tool call already exists, seeded from the
+    // persisted transcript of a prior invocation (seedStatusFromExecution in
+    // index.ts). The durable checkpoint re-emits tool_started now that approval
+    // is granted — flip the existing call to RUNNING in place rather than
+    // appending a duplicate or re-triggering the approval gate. v3 keys by
+    // tool_call_id, so this is an exact match (no name heuristics needed).
+    const existing = this.state.toolCalls.get(callId);
+    if (existing) {
+      if (existing.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL) {
+        existing.status = ToolCallStatus.TOOL_CALL_RUNNING;
+      }
+      if (Object.keys(input).length > 0 && !existing.args) {
+        existing.args = input as JsonObject;
+      }
+      this.state.toolStartTimes.set(callId, performance.now());
+      this._forceNextUpdate = true;
+      return;
+    }
+
     const agentNs = this.resolveAgentNamespace(namespace);
     const parentMsg = this.state.currentAiMessage.get(agentNs)
       ?? this.ensureAiMessageForToolCall(agentNs);
@@ -271,6 +300,11 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     // Classify after mcpServerSlug is set so MCP tools resolve correctly.
     tc.toolKind = classifyTool(tc.name, tc.mcpServerSlug);
 
+    // Stamp authorization provenance in the same spot as tool_kind, for every
+    // observed tool call (gated or auto-approved). A gated call is re-seeded on
+    // reinvocation (index.ts) with the same source carried through the interrupt.
+    stampApprovalProvenance(tc, this.approvalProvider);
+
     if (approvalReq.requiresApproval) {
       tc.requiresApproval = true;
       tc.approvalMessage = approvalReq.message;
@@ -368,7 +402,7 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
 
     const serverSlug = this.approvalProvider.toolServerMap.get(toolName) ?? "";
 
-    if (this.approvalProvider.autoApproveAll) {
+    if (this.approvalProvider.globalBypass) {
       return { requiresApproval: false, message: "", serverSlug };
     }
 

package/src/claimcheck/payload-codec.ts

@@ -82,15 +82,15 @@ export class ClaimcheckPayloadCodec implements PayloadCodec {
       Buffer.from(payload.data!).toString("utf-8"),
     );
 
-    const downloadUrl = await this.storage.getDownloadUrl(marker.key);
-    const response = await fetch(downloadUrl);
-    if (!response.ok) {
-      throw new Error(
-        `Claimcheck retrieve failed for key ${marker.key}: HTTP ${response.status}`,
-      );
+    let rawBuf: Buffer;
+    try {
+      rawBuf = await this.storage.download(marker.key);
+    } catch (err) {
+      // Preserve the claimcheck-scoped error contract; the shared download error
+      // already carries the HTTP status (proxy) or the miss (local) as the cause.
+      const cause = err instanceof Error ? err.message : String(err);
+      throw new Error(`Claimcheck retrieve failed for key ${marker.key}: ${cause}`);
     }
-
-    const rawBuf = Buffer.from(await response.arrayBuffer());
     const dataBuf = marker.compressed ? decompress(rawBuf) : rawBuf;
 
     return {

package/src/client/stigmer-client.ts

@@ -273,12 +273,20 @@ export class StigmerClient {
   async updateWorkflowExecutionStatus(
     executionId: string,
     status: WorkflowExecutionStatus,
-    options?: { updatePendingApprovals?: boolean },
+    options?: {
+      updatePendingApprovals?: boolean;
+      updatePendingFileReviews?: boolean;
+      // The child a per-child merge targets (required whenever either update flag
+      // is set, including the scoped-clear case where the list is empty).
+      pendingUpdateChildAgentExecutionId?: string;
+    },
   ): Promise<WorkflowExecution> {
     const input = create(WorkflowExecutionUpdateStatusInputSchema, {
       executionId,
       status,
       updatePendingApprovals: options?.updatePendingApprovals ?? false,
+      updatePendingFileReviews: options?.updatePendingFileReviews ?? false,
+      pendingUpdateChildAgentExecutionId: options?.pendingUpdateChildAgentExecutionId ?? "",
     });
     return this.workflowExecutionCommand.updateStatus(input);
   }