@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

package/src/activities/execute-deep-agent/__tests__/subagent-approval-propagation.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Runtime verification: does a SUB-AGENT approval interrupt propagate to the
+ * PARENT checkpoint, and does Command(resume=…) route back into the nested
+ * interrupt?
+ *
+ * This is the make-or-break question behind installing the approval gate on
+ * sub-agent graphs (HITL Phase 2, Slice B). The resume path in `hitl.ts` /
+ * `index.ts` reads pending interrupts from the PARENT's top-level
+ * `graphState.tasks[].interrupts` and resumes via `Command(resume={taskId: …})`.
+ * If a sub-agent interrupt does NOT surface there (or cannot be resumed),
+ * gating sub-agent tools would hang executions — strictly worse than the current
+ * bypass. So we prove the mechanism end-to-end against the real deepagents +
+ * LangGraph runtime before wiring it.
+ *
+ * Shape under test (faithful to the real pipeline): a deepagents PARENT with a
+ * checkpointer and `subagents: [worker]`; the worker is a deepagents agent
+ * carrying our real ApprovalGate middleware and NO checkpointer (exactly how
+ * compileSubagents builds it). The parent's `task` tool invokes the worker via
+ * `worker.invoke(state, {...parentConfig})` — so a GraphInterrupt thrown inside
+ * the worker (no checkpointer → re-thrown) must bubble to the parent (has
+ * checkpointer → records it).
+ */
+
+import { describe, it, expect } from "vitest";
+import { HumanMessage } from "@langchain/core/messages";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { Command, MemorySaver } from "@langchain/langgraph";
+import { createDeepAgent, StateBackend } from "deepagents";
+import { createApprovalGateMiddleware } from "../../../middleware/approval-gate.js";
+import {
+  ScriptedModel,
+  readPendingInterrupts,
+  type ScriptSelector,
+} from "../__test-utils__/scripted-model.js";
+
+// Role script for this test: the WORKER (its bound tools include the gated
+// `overwrite_file`) writes a file; the PARENT delegates via `task`. createDeepAgent
+// injects `task` into both, so the role is keyed on the worker's unique tool.
+const roleScript: ScriptSelector = (toolNames) =>
+  toolNames.includes("overwrite_file")
+    ? {
+        toolCalls: [
+          { name: "overwrite_file", args: { path: "/out.txt", content: "hello" }, id: "write_1" },
+        ],
+        done: "worker done",
+      }
+    : {
+        toolCalls: [
+          { name: "task", args: { description: "write the file", subagent_type: "worker" }, id: "task_1" },
+        ],
+        done: "parent done",
+      };
+
+describe("sub-agent approval interrupt propagation", () => {
+  it("surfaces a sub-agent interrupt at the parent checkpoint AND resumes it", async () => {
+    let executed = 0;
+    const overwriteFile = tool(
+      async () => {
+        executed += 1;
+        return "wrote file";
+      },
+      {
+        name: "overwrite_file",
+        description: "overwrite a file at a path",
+        schema: z.object({ path: z.string(), content: z.string() }),
+      },
+    );
+
+    // Worker: real ApprovalGate middleware, NO checkpointer — exactly how
+    // compileSubagents builds a sub-agent. overwrite_file classifies as
+    // FILE_WRITE, so the gate must interrupt before it runs.
+    const worker = await createDeepAgent({
+      model: new ScriptedModel(roleScript),
+      tools: [overwriteFile],
+      middleware: [
+        createApprovalGateMiddleware({ policies: new Map(), toolServerMap: new Map() }),
+      ],
+      backend: new StateBackend(),
+      generalPurposeAgent: false,
+    } as unknown as Parameters<typeof createDeepAgent>[0]);
+
+    const checkpointer = new MemorySaver();
+    const parent = await createDeepAgent({
+      model: new ScriptedModel(roleScript),
+      checkpointer: checkpointer as never,
+      backend: new StateBackend(),
+      subagents: [{ name: "worker", description: "writes files", runnable: worker as never }],
+    } as unknown as Parameters<typeof createDeepAgent>[0]);
+
+    const config = { configurable: { thread_id: "thread-1" }, recursionLimit: 50 };
+
+    // Drive to the first pause. The worker's gated tool call must NOT have run.
+    await parent.invoke({ messages: [new HumanMessage({ content: "go" })] }, config);
+
+    const afterFirst = await parent.getState(config);
+    const pending = readPendingInterrupts(afterFirst as never);
+
+    expect(pending.length).toBeGreaterThanOrEqual(1);
+    expect(pending[0].toolCallId).toBe("write_1");
+    expect(executed).toBe(0);
+
+    // Resume with APPROVE, keyed by the actual interrupt id (NOT task.id — for a
+    // nested sub-agent interrupt the two differ, and only the interrupt id routes
+    // the resume value into the worker's interrupt()).
+    const resumeDict: Record<string, { action: string }> = {};
+    for (const p of pending) resumeDict[p.interruptId] = { action: "approve" };
+
+    await parent.invoke(new Command({ resume: resumeDict }), config);
+
+    const afterResume = await parent.getState(config);
+    const stillPending = readPendingInterrupts(afterResume as never);
+
+    expect(stillPending.length).toBe(0);
+    expect(executed).toBe(1);
+  });
+
+  it("PARENT-level gated tool: interrupt-id keyed resume also works (fix is safe)", async () => {
+    // Guards the hitl.ts change: keying resume by interrupts[].id must also drive
+    // a top-level (non-sub-agent) approval, so switching off task.id is safe.
+    let executed = 0;
+    const overwriteFile = tool(
+      async () => {
+        executed += 1;
+        return "wrote file";
+      },
+      {
+        name: "overwrite_file",
+        description: "overwrite a file at a path",
+        schema: z.object({ path: z.string(), content: z.string() }),
+      },
+    );
+
+    const checkpointer = new MemorySaver();
+    const parent = await createDeepAgent({
+      model: new ScriptedModel(roleScript),
+      checkpointer: checkpointer as never,
+      backend: new StateBackend(),
+      tools: [overwriteFile],
+      middleware: [
+        createApprovalGateMiddleware({ policies: new Map(), toolServerMap: new Map() }),
+      ],
+    } as unknown as Parameters<typeof createDeepAgent>[0]);
+
+    const config = { configurable: { thread_id: "thread-parent" }, recursionLimit: 50 };
+    await parent.invoke({ messages: [new HumanMessage({ content: "go" })] }, config);
+
+    const afterFirst = await parent.getState(config);
+    const pending = readPendingInterrupts(afterFirst as never);
+    expect(pending.length).toBeGreaterThanOrEqual(1);
+    expect(executed).toBe(0);
+
+    const resumeDict: Record<string, { action: string }> = {};
+    for (const p of pending) resumeDict[p.interruptId] = { action: "approve" };
+    await parent.invoke(new Command({ resume: resumeDict }), config);
+
+    expect(readPendingInterrupts((await parent.getState(config)) as never).length).toBe(0);
+    expect(executed).toBe(1);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/subagent-gitignored-capture.test.ts

@@ -0,0 +1,213 @@
+/**
+ * End-to-end proof (real deepagents + LangGraph runtime, no LLM/network) that a
+ * SUB-AGENT's gitignored file writes are captured for CAS review at parity with
+ * the parent (Session 26, DD-19).
+ *
+ * These tests exercise the ACTUAL wiring under change — `compileSubagents` — which
+ * installs a CAS-observing backend on each sub-agent and flips its gate to flow
+ * gitignored writes (both derived from the shared observer, so "unobserved bytes"
+ * is impossible by construction). A non-secret gitignored write flows and is
+ * observed; a secret-like one is hard-blocked with nothing written; a git-tracked
+ * write is left to the boundary git diff (not observed).
+ *
+ * Scope note: the turn-boundary CANDIDATE authoring, `changeSetId`/`turnSeq`, and
+ * the Temporal resume loop are parent/activity-level machinery unchanged by this
+ * work (covered by the offline/corpus suites). These tests assert the observer
+ * capture surface (before-bytes + blocked-secret paths + on-disk result) that
+ * those consumers read.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, readFile, access } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HumanMessage } from "@langchain/core/messages";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { Command, MemorySaver } from "@langchain/langgraph";
+import { createDeepAgent, StateBackend } from "deepagents";
+import type { ApprovalGateConfig } from "../../../middleware/approval-gate.js";
+import { partitionIgnoredPathsBySecret } from "../../../shared/filereview/secret-paths.js";
+import { resolveWorkspacePath } from "../../../shared/file-change.js";
+import { CasCaptureObserver } from "../cas-capture-observer.js";
+import { compileSubagents, type TransformedSubagent } from "../subagent-transformer.js";
+import { ScriptedModel, readPendingInterrupts, type ScriptSelector } from "../__test-utils__/scripted-model.js";
+
+/** Only `src/**` is git-tracked (capturable); everything else is gitignored. */
+const isTracked = (relPath: string): boolean => relPath.startsWith("src/");
+
+describe("sub-agent gitignored capture (DD-19)", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "sa-cas-"));
+    await mkdir(join(root, "dist"), { recursive: true });
+    await mkdir(join(root, "src"), { recursive: true });
+    await mkdir(join(root, "cache"), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  function makeObserver(): CasCaptureObserver {
+    return new CasCaptureObserver({
+      rootDir: root,
+      isIgnored: async (relPath) => !isTracked(relPath),
+    });
+  }
+
+  /**
+   * A capture-mode gate wired to `observer`, exactly as setup.ts builds the parent
+   * gate and buildSubAgentMiddleware inherits it when a CAS observer backs the
+   * sub-agent (captureIgnored true).
+   */
+  function captureGate(observer: CasCaptureObserver): ApprovalGateConfig {
+    return {
+      policies: new Map(),
+      toolServerMap: new Map(),
+      fileCaptureMode: true,
+      isCapturablePath: async (raw: string) =>
+        isTracked(resolveWorkspacePath(raw, root, true).path),
+      captureIgnored: true,
+      recordBlockedSecret: (raw: string) => observer.recordBlockedSecret(raw),
+    };
+  }
+
+  /**
+   * Compile a sub-agent through the production path (the code under change), with
+   * the shared CAS observer so its backend + gate are the real capture wiring.
+   */
+  async function compileWorker(
+    observer: CasCaptureObserver,
+    script: ScriptSelector,
+    tools: TransformedSubagent["tools"] = [],
+  ) {
+    const compiled = await compileSubagents(
+      [{ name: "worker", description: "test worker", systemPrompt: "do the work", tools }],
+      {
+        approvalGate: captureGate(observer),
+        parentModelName: "test-model",
+        workspaceRootDir: root,
+        casObserver: observer,
+        modelFactory: async () => new ScriptedModel(script),
+      },
+    );
+    expect(compiled).toHaveLength(1);
+    return compiled[0];
+  }
+
+  it("captures a sub-agent's non-secret gitignored write, hard-blocks a secret one, and leaves git-tracked to the git diff", async () => {
+    const observer = makeObserver();
+
+    // A single worker; script it to write three files in one turn (no `task`, so
+    // no sub-agent delegation ambiguity — we invoke the compiled sub-agent, which
+    // IS what the parent dispatches, directly).
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: "dist/app.js", content: "console.log(1)" }, id: "w_ignored" },
+        { name: "write_file", args: { file_path: ".env", content: "SECRET=shh" }, id: "w_secret" },
+        { name: "write_file", args: { file_path: "src/app.ts", content: "export const x = 1;" }, id: "w_tracked" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(observer, script);
+    await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t1" }, recursionLimit: 50 },
+    );
+
+    // Non-secret gitignored write: flowed (on disk) AND observed (before=null ADD).
+    expect(await readFile(join(root, "dist/app.js"), "utf8")).toBe("console.log(1)");
+    expect(observer.before.has("dist/app.js")).toBe(true);
+    expect(observer.before.get("dist/app.js")).toBeNull();
+
+    // Secret-like gitignored write: hard-blocked — nothing written, path recorded.
+    await expect(access(join(root, ".env"))).rejects.toThrow();
+    expect([...observer.blockedSecretPaths]).toContain(".env");
+
+    // Git-tracked write: flowed to disk but NOT observed (the git diff owns it).
+    expect(await readFile(join(root, "src/app.ts"), "utf8")).toBe("export const x = 1;");
+    expect(observer.before.has("src/app.ts")).toBe(false);
+
+    // Bridge to the boundary: the observer state partitions into a
+    // GIT_IGNORED_CAPTURED (dist/app.js) and a DIFF_UNREVIEWABLE (.env), exactly
+    // as buildCasTurnCaptures does at the turn boundary.
+    const { capturablePaths, unreviewablePaths } = partitionIgnoredPathsBySecret(
+      observer.before.keys(),
+      observer.blockedSecretPaths,
+    );
+    expect([...capturablePaths]).toEqual(["dist/app.js"]);
+    expect([...unreviewablePaths]).toEqual([".env"]);
+  });
+
+  it("mixed turn: a sub-agent's gitignored write is captured even when the same turn pauses on a gated tool, and resume completes", async () => {
+    const observer = makeObserver();
+    let shellRuns = 0;
+    // `shell` classifies as the SHELL category, so capture mode never bypasses it —
+    // it interrupts (parity with the parent). `cas_marker` is a role marker unique
+    // to the worker (the parent lacks it), used only to select the worker's script
+    // branch — deepagents auto-injects `task` into every agent, so `task` cannot
+    // distinguish the roles.
+    const shell = tool(async () => { shellRuns += 1; return "ran"; }, {
+      name: "shell",
+      description: "run a command",
+      schema: z.object({ command: z.string() }),
+    });
+    const marker = tool(async () => "noop", {
+      name: "cas_marker",
+      description: "worker role marker",
+      schema: z.object({}),
+    });
+
+    const script: ScriptSelector = (toolNames) =>
+      toolNames.includes("cas_marker")
+        ? {
+            toolCalls: [
+              { name: "write_file", args: { file_path: "cache/data.txt", content: "cached" }, id: "w_ignored" },
+              { name: "shell", args: { command: "echo hi" }, id: "sh_1" },
+            ],
+            done: "worker done",
+          }
+        : {
+            toolCalls: [
+              { name: "task", args: { description: "work", subagent_type: "worker" }, id: "task_1" },
+            ],
+            done: "parent done",
+          };
+
+    const worker = await compileWorker(observer, script, [shell, marker] as TransformedSubagent["tools"]);
+
+    const parent = await createDeepAgent({
+      model: new ScriptedModel(script),
+      checkpointer: new MemorySaver() as never,
+      backend: new StateBackend(),
+      subagents: [{ name: worker.name, description: worker.description, runnable: worker.runnable as never }],
+    } as unknown as Parameters<typeof createDeepAgent>[0]);
+
+    const config = { configurable: { thread_id: "t2" }, recursionLimit: 50 };
+
+    // Invocation 1: the gitignored write flows and is captured BEFORE the turn
+    // pauses on the gated shell tool (the shell must NOT have run yet).
+    await parent.invoke({ messages: [new HumanMessage({ content: "go" })] }, config);
+
+    const pending = readPendingInterrupts((await parent.getState(config)) as never);
+    expect(pending.some((p) => p.toolCallId === "sh_1")).toBe(true);
+    expect(shellRuns).toBe(0);
+    expect(await readFile(join(root, "cache/data.txt"), "utf8")).toBe("cached");
+    expect(observer.before.get("cache/data.txt")).toBeNull();
+
+    // Resume with APPROVE: the worker re-runs (no checkpointer) and the shell runs
+    // once. First-touch-wins keeps the single pre-turn baseline for the re-written
+    // gitignored file (no duplicate, no post-write baseline).
+    const resumeDict: Record<string, { action: string }> = {};
+    for (const p of pending) resumeDict[p.interruptId] = { action: "approve" };
+    await parent.invoke(new Command({ resume: resumeDict }), config);
+
+    expect(readPendingInterrupts((await parent.getState(config)) as never).length).toBe(0);
+    expect(shellRuns).toBe(1);
+    expect(observer.before.size).toBe(1);
+    expect(observer.before.get("cache/data.txt")).toBeNull();
+  });
+});

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

@@ -428,8 +428,7 @@ describe("transformAndCompileSubagents", () => {
     parentMcpUsages: [] as McpServerUsage[],
     skillClient: {} as unknown,
     workspaceBackend: mockWorkspaceBackend(),
-    approvalPolicies: new Map(),
-    autoApproveAll: false,
+    approvalGate: null,
     parentModelName: "claude-sonnet-4-6",
     parentHasNativeThinking: true,
     costCap: undefined,
@@ -659,8 +658,7 @@ describe("subagent-transformer edge cases", () => {
       parentMcpUsages: [],
       skillClient: {} as unknown,
       workspaceBackend: mockWorkspaceBackend({ rootDir: "" }),
-      approvalPolicies: new Map(),
-      autoApproveAll: false,
+      approvalGate: null,
       parentModelName: "claude-sonnet-4-6",
       parentHasNativeThinking: true,
       costCap: undefined,
@@ -683,8 +681,7 @@ describe("subagent-transformer edge cases", () => {
       parentMcpUsages: [],
       skillClient: {} as unknown,
       workspaceBackend: mockWorkspaceBackend(),
-      approvalPolicies: new Map(),
-      autoApproveAll: false,
+      approvalGate: null,
       parentModelName: "claude-sonnet-4-6",
       parentHasNativeThinking: true,
       costCap: undefined,

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

@@ -1,6 +1,7 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { buildSubAgentMiddleware } from "../subagent-wiring.js";
 import { createCostCapMiddleware } from "../../../middleware/cost-cap.js";
+import * as approvalGateModule from "../../../middleware/approval-gate.js";
 
 describe("buildSubAgentMiddleware", () => {
   it("returns the correct middleware order without cost cap", () => {
@@ -68,4 +69,86 @@ describe("buildSubAgentMiddleware", () => {
 
     expect(stack[2].name).toBe("ToolTruncationMiddleware");
   });
+
+  it("installs the approval gate when an approvalGate config is provided", () => {
+    const stack = buildSubAgentMiddleware({
+      approvalGate: { policies: new Map(), toolServerMap: new Map() },
+    });
+
+    // loop, budget, truncation, approval gate
+    expect(stack).toHaveLength(4);
+    expect(stack[3].name).toBe("ApprovalGateMiddleware");
+    expect(stack[3].wrapToolCall).toBeDefined();
+  });
+
+  it("omits the approval gate when approvalGate is null (auto-approve-all parity)", () => {
+    const stack = buildSubAgentMiddleware({ approvalGate: null });
+
+    expect(stack).toHaveLength(3);
+    expect(stack.some((m) => m.name === "ApprovalGateMiddleware")).toBe(false);
+  });
+
+  it("orders the gate before the cost-cap view", () => {
+    const parentCostCap = createCostCapMiddleware({
+      maxCostUsd: 10,
+      inputPricePerMillion: 3,
+      outputPricePerMillion: 15,
+      cacheReadPricePerMillion: 0.3,
+      warningPct: 80,
+    });
+
+    const stack = buildSubAgentMiddleware({
+      costCap: parentCostCap,
+      approvalGate: { policies: new Map(), toolServerMap: new Map() },
+    });
+
+    // loop, budget, truncation, approval gate, cost cap view
+    expect(stack).toHaveLength(5);
+    expect(stack[3].name).toBe("ApprovalGateMiddleware");
+    expect(stack[4].name).toBe("CostCapSubAgentView");
+  });
+
+  // captureIgnored is the structural coupling that makes sub-agent gitignored
+  // capture safe (DD-19): the gate flows gitignored writes into CAS iff a CAS
+  // observer backs the sub-agent's backend (compileSubagents passes !!casObserver).
+  describe("captureIgnored (sub-agent CAS routing)", () => {
+    it("captureIgnored:true inherits the parent gate verbatim (CAS routing + secret sink preserved)", () => {
+      const recordBlockedSecret = vi.fn();
+      const parentGate = {
+        policies: new Map(),
+        toolServerMap: new Map(),
+        captureIgnored: true,
+        recordBlockedSecret,
+      };
+      const spy = vi.spyOn(approvalGateModule, "createApprovalGateMiddleware");
+
+      buildSubAgentMiddleware({ approvalGate: parentGate, captureIgnored: true });
+
+      const cfg = spy.mock.calls[0]![0];
+      expect(cfg.captureIgnored).toBe(true);
+      expect(cfg.recordBlockedSecret).toBe(recordBlockedSecret);
+      spy.mockRestore();
+    });
+
+    it("regression lock: without captureIgnored, CAS routing is forced OFF and the secret sink dropped even if the parent gate had them", () => {
+      const recordBlockedSecret = vi.fn();
+      // A parent gate that DOES route gitignored writes into CAS — the sub-agent
+      // must not inherit that unless a CAS observer explicitly backs it, else it
+      // would apply unobserved, unreviewable bytes.
+      const parentGate = {
+        policies: new Map(),
+        toolServerMap: new Map(),
+        captureIgnored: true,
+        recordBlockedSecret,
+      };
+      const spy = vi.spyOn(approvalGateModule, "createApprovalGateMiddleware");
+
+      buildSubAgentMiddleware({ approvalGate: parentGate });
+
+      const cfg = spy.mock.calls[0]![0];
+      expect(cfg.captureIgnored).toBe(false);
+      expect(cfg.recordBlockedSecret).toBeUndefined();
+      spy.mockRestore();
+    });
+  });
 });

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

@@ -271,12 +271,15 @@ describe("V3StatusBuilder", () => {
         sb.setApprovalProvider({
           policies: new Map([
             ["my-server/dangerous_tool", {
+              toolName: "dangerous_tool",
+              mcpServerSlug: "my-server",
               requiresApproval: true,
               approvalMessage: "This tool will modify {{args.path}}",
+              source: "classifier_default",
             }],
           ]),
           toolServerMap: new Map([["dangerous_tool", "my-server"]]),
-          autoApproveAll: false,
+          globalBypass: false,
         } as ApprovalPolicyProvider);
 
         feedAll(sb, [

package/src/activities/execute-deep-agent/approval-file-change.ts

@@ -0,0 +1,80 @@
+/**
+ * Pre-execution args capture for the HITL approval gate (native harness).
+ *
+ * When the graph pauses for approval — before the tool runs — this captures a
+ * sanitized args preview so the gate can show the proposed change. It owns only
+ * the native-specific seam: correlating a gated `tool_call_id` to its arguments
+ * from graph state (the authoritative single source of truth at the interrupt,
+ * since the streamed input cache is empty and the interrupt value carries only a
+ * few fields). The approval card renders the proposed write/edit content from
+ * these args; there is no separate captured `file_changes` (removed in Phase 5
+ * Slice 4 — the args are the single source, and the Cursor deny-gate's
+ * exact-apply reads the same args on resume; see execute-cursor/exact-apply.ts).
+ *
+ * @since First-Class Diff Review (#186), approval-gate phase
+ */
+
+/** What the gate capture contributes to a `WAITING_APPROVAL` `ToolCall`. */
+export interface ApprovalCaptureResult {
+  /** Sanitized JSON args preview, omitted when there are no args to show. */
+  readonly argsPreview?: string;
+}
+
+import { sanitizeArgsPreview } from "./status-builder-shared.js";
+
+/**
+ * Correlate a gated `tool_call_id` to its arguments by scanning graph-state
+ * messages for the AI-message tool call that emitted it.
+ *
+ * Matching keys on the presence of a `tool_calls` array, which is robust to
+ * whether the message is a hydrated LangChain class instance or a plain
+ * serialized object: a `ToolMessage` carries a singular `tool_call_id`, never a
+ * `tool_calls` array, so it cannot be mistaken for the emitting AI message.
+ *
+ * Returns the args object (possibly empty when the tool call took no arguments),
+ * or `undefined` when no message in scope emitted this id — e.g. a tool call
+ * whose AI message lives only inside a nested sub-agent state, which this
+ * parent-scope scan does not reach. That degrades the gate to an args-less
+ * preview for that one interrupt, exactly as today.
+ */
+export function findAiMessageToolCallArgs(
+  messages: readonly unknown[],
+  toolCallId: string,
+): Record<string, unknown> | undefined {
+  for (const msg of messages) {
+    if (!msg || typeof msg !== "object") continue;
+    const toolCalls = (msg as { tool_calls?: unknown }).tool_calls;
+    if (!Array.isArray(toolCalls)) continue;
+
+    for (const tc of toolCalls) {
+      if (!tc || typeof tc !== "object") continue;
+      const entry = tc as { id?: unknown; args?: unknown };
+      if (entry.id !== toolCallId) continue;
+
+      return entry.args &&
+        typeof entry.args === "object" &&
+        !Array.isArray(entry.args)
+        ? (entry.args as Record<string, unknown>)
+        : {};
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Capture the gate's args preview from a single correlation lookup, keeping the
+ * call site thin.
+ *
+ * Returns an empty result when the tool call cannot be correlated or took no
+ * arguments, so the gate falls back to today's behavior for that interrupt.
+ */
+export function captureApprovalArtifacts(opts: {
+  readonly toolCallId: string;
+  readonly messages: readonly unknown[];
+}): ApprovalCaptureResult {
+  const args = findAiMessageToolCallArgs(opts.messages, opts.toolCallId);
+  if (!args || Object.keys(args).length === 0) return {};
+
+  const argsPreview = sanitizeArgsPreview(args) || undefined;
+  return { argsPreview };
+}

package/src/activities/execute-deep-agent/attachment-injector.ts

@@ -41,7 +41,14 @@ export interface InjectedFile {
 export interface InjectAttachmentsOptions {
   readonly backend: WorkspaceBackend;
   readonly attachments: readonly Attachment[];
-  readonly storage: ArtifactStorage;
+  /**
+   * Artifact storage for cloud-mode attachment download. `undefined` when the
+   * runner could not build a store (proxy misconfig). With no attachments this is
+   * never touched (the function early-returns); a cloud-mode attachment that
+   * genuinely needs storage surfaces a clear {@link AttachmentInjectionError}
+   * rather than dereferencing undefined.
+   */
+  readonly storage: ArtifactStorage | undefined;
   readonly isLocalMode: boolean;
 }
 
@@ -328,7 +335,7 @@ function deriveFilename(storageKey: string): string {
 
 async function downloadAttachment(
   attachment: Attachment,
-  storage: ArtifactStorage,
+  storage: ArtifactStorage | undefined,
   isLocalMode: boolean,
 ): Promise<Buffer> {
   // Local mode fast path: read directly from filesystem
@@ -351,16 +358,18 @@ async function downloadAttachment(
     );
   }
 
-  try {
-    const url = await storage.getDownloadUrl(attachment.storageKey);
-    const response = await fetch(url);
-
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-    }
+  // The attachment must come from storage, but the runner could not build one
+  // (proxy misconfig). Fail with an actionable message rather than dereferencing
+  // undefined — consistent with the degraded posture, never a silent skip.
+  if (!storage) {
+    throw new AttachmentInjectionError(
+      attachment.filename,
+      `artifact storage is unavailable, so this attachment (key: ${attachment.storageKey}) cannot be downloaded`,
+    );
+  }
 
-    const arrayBuffer = await response.arrayBuffer();
-    return Buffer.from(arrayBuffer);
+  try {
+    return await storage.download(attachment.storageKey);
   } catch (err) {
     if (err instanceof AttachmentInjectionError) throw err;
     throw new AttachmentInjectionError(