zeitlich 0.2.36 → 0.2.37

package/src/lib/subagent/subagent.integration.test.ts

@@ -1,8 +1,6 @@
 import { describe, expect, it, vi, afterEach } from "vitest";
 import { z } from "zod";
 
-const capturedSignalHandlers = new Map<unknown, (...args: unknown[]) => void>();
-
 let nextStartChildResult: ((prompt: string) => unknown) | null = null;
 
 vi.mock("@temporalio/workflow", () => {
@@ -34,11 +32,7 @@ vi.mock("@temporalio/workflow", () => {
       parent: { workflowId: "parent-wf-1" },
     }),
     defineSignal: vi.fn((name: string) => ({ __signal: true, name })),
-    setHandler: vi.fn(
-      (signal: unknown, handler: (...a: unknown[]) => void) => {
-        capturedSignalHandlers.set(signal, handler);
-      }
-    ),
+    setHandler: vi.fn(),
     condition: vi.fn(async (fn: () => boolean) => {
       if (!fn()) throw new Error("condition predicate was not satisfied");
     }),
@@ -57,12 +51,6 @@ vi.mock("@temporalio/workflow", () => {
               usage: { inputTokens: 100, outputTokens: 50 },
             };
 
-        for (const [signal, handler] of capturedSignalHandlers.entries()) {
-          if ((signal as { name?: string }).name === "childResult") {
-            handler({ childWorkflowId: opts.workflowId, result });
-          }
-        }
-
         return {
           signal: vi.fn(),
           result: () => Promise.resolve(result),
@@ -104,7 +92,6 @@ import type {
 } from "./types";
 afterEach(() => {
   nextStartChildResult = null;
-  capturedSignalHandlers.clear();
 });
 
 function mockWorkflow(name?: string): SubagentWorkflow {
@@ -117,6 +104,27 @@ function mockWorkflow(name?: string): SubagentWorkflow {
   return fn as SubagentWorkflow;
 }
 
+function makeMockSandboxOps() {
+  return {
+    createSandbox: vi.fn(),
+    destroySandbox: vi.fn(),
+    pauseSandbox: vi.fn(),
+    resumeSandbox: vi.fn(),
+    snapshotSandbox: vi.fn(),
+    restoreSandbox: vi.fn(),
+    deleteSandboxSnapshot: vi.fn(),
+    forkSandbox: vi.fn(),
+  };
+}
+
+/**
+ * Default no-op sandbox proxy factory — satisfies the runtime check that
+ * every sandbox-using subagent must declare `sandbox.proxy`. Tests that
+ * need to assert on destroy/cleanup create their own mock ops and wire
+ * them through `sandbox: { ..., proxy: () => opsMock }`.
+ */
+const noopSandboxProxy = () => makeMockSandboxOps();
+
 // ---------------------------------------------------------------------------
 // createSubagentTool
 // ---------------------------------------------------------------------------
@@ -377,7 +385,11 @@ describe("createSubagentHandler", () => {
       agentName: "inherit-agent",
       description: "Inherits sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "inherit", continuation: "continue" },
+      sandbox: {
+        source: "inherit",
+        continuation: "continue",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([inheritSubagent]);
@@ -406,7 +418,11 @@ describe("createSubagentHandler", () => {
       agentName: "inherit-agent",
       description: "Inherits sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "inherit", continuation: "continue" },
+      sandbox: {
+        source: "inherit",
+        continuation: "continue",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([inheritSubagent]);
@@ -427,7 +443,7 @@ describe("createSubagentHandler", () => {
       agentName: "own-agent",
       description: "Own sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", continuation: "fork" },
+      sandbox: { source: "own", continuation: "fork", proxy: noopSandboxProxy },
     };
 
     const { handler } = createSubagentHandler([ownSubagent]);
@@ -508,7 +524,7 @@ describe("createSubagentHandler", () => {
       agentName: "own-agent",
       description: "Own sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", continuation: "fork" },
+      sandbox: { source: "own", continuation: "fork", proxy: noopSandboxProxy },
     };
 
     const { handler } = createSubagentHandler([ownSubagent]);
@@ -670,7 +686,7 @@ describe("createSubagentHandler", () => {
       description: "Sandbox continuation",
       workflow: mockWorkflow(),
       thread: "fork",
-      sandbox: { source: "own", continuation: "fork" },
+      sandbox: { source: "own", continuation: "fork", proxy: noopSandboxProxy },
     };
 
     const { handler } = createSubagentHandler([contSandboxSubagent]);
@@ -726,7 +742,7 @@ describe("createSubagentHandler", () => {
       description: "Sandbox continuation",
       workflow: mockWorkflow(),
       thread: "fork",
-      sandbox: { source: "own", continuation: "fork" },
+      sandbox: { source: "own", continuation: "fork", proxy: noopSandboxProxy },
     };
 
     const { handler } = createSubagentHandler([contSandboxSubagent]);
@@ -755,10 +771,7 @@ describe("createSubagentHandler", () => {
     expect(workflowInput.thread).toBeUndefined();
   });
 
-  it("does not signal destroy for fork-mode subagent without pause-until-parent-close", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
-
+  it("does not destroy fork-mode subagent sandbox without pause-until-parent-close", async () => {
     const contSandboxSubagent: SubagentConfig = {
       agentName: "sb-cont",
       description: "Sandbox continuation",
@@ -775,25 +788,16 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastResult = startMock.mock.results.at(-1);
-    if (!lastResult) throw new Error("expected startChild call");
-    const childHandle = await lastResult.value;
-    childHandle.signal.mockClear();
-
-    await destroySubagentSandboxes();
-
-    expect(childHandle.signal).not.toHaveBeenCalled();
+    await expect(destroySubagentSandboxes()).resolves.toBeUndefined();
   });
 
-  it("does not signal destroy for sandbox=own with default shutdown", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
-
+  it("does not destroy sandbox=own with default shutdown", async () => {
+    const opsMock = makeMockSandboxOps();
     const ownSubagent: SubagentConfig = {
       agentName: "own-agent",
       description: "Own sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", continuation: "fork" },
+      sandbox: { source: "own", continuation: "fork", proxy: () => opsMock },
     };
 
     const { handler, destroySubagentSandboxes } = createSubagentHandler([
@@ -805,20 +809,20 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastResult = startMock.mock.results.at(-1);
-    if (!lastResult) throw new Error("expected startChild call");
-    const childHandle = await lastResult.value;
-    childHandle.signal.mockClear();
-
     await destroySubagentSandboxes();
 
-    expect(childHandle.signal).not.toHaveBeenCalled();
+    expect(opsMock.destroySandbox).not.toHaveBeenCalled();
   });
 
-  it("signals destroy for sandbox=own with pause-until-parent-close shutdown", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+  it("destroys sandbox via sandbox.proxy for own + pause-until-parent-close", async () => {
+    nextStartChildResult = () => ({
+      toolResponse: "done",
+      data: null,
+      threadId: "child-t",
+      sandboxId: "child-sb-99",
+    });
 
+    const opsMock = makeMockSandboxOps();
     const ownSubagent: SubagentConfig = {
       agentName: "own-agent",
       description: "Own sandbox",
@@ -827,6 +831,7 @@ describe("createSubagentHandler", () => {
         source: "own",
         continuation: "fork",
         shutdown: "pause-until-parent-close",
+        proxy: () => opsMock,
       },
     };
 
@@ -841,21 +846,20 @@ describe("createSubagentHandler", () => {
 
     await destroySubagentSandboxes();
 
-    const lastResult = startMock.mock.results.at(-1);
-    if (!lastResult) throw new Error("expected startChild call");
-    const childHandle = await lastResult.value;
-    expect(childHandle.signal).toHaveBeenCalled();
+    expect(opsMock.destroySandbox).toHaveBeenCalledWith("child-sb-99");
   });
 
-  it("does not signal destroy for inherit subagents", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
-
+  it("does not destroy inherit subagents' sandbox", async () => {
+    const opsMock = makeMockSandboxOps();
     const inheritSubagent: SubagentConfig = {
       agentName: "inherit-agent",
       description: "Inherits sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "inherit", continuation: "continue" },
+      sandbox: {
+        source: "inherit",
+        continuation: "continue",
+        proxy: () => opsMock,
+      },
     };
 
     const { handler, destroySubagentSandboxes } = createSubagentHandler([
@@ -872,14 +876,9 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastResult = startMock.mock.results.at(-1);
-    if (!lastResult) throw new Error("expected startChild call");
-    const childHandle = await lastResult.value;
-    childHandle.signal.mockClear();
-
     await destroySubagentSandboxes();
 
-    expect(childHandle.signal).not.toHaveBeenCalled();
+    expect(opsMock.destroySandbox).not.toHaveBeenCalled();
   });
 
   it("does not pass sandboxId when sandbox is none (default)", async () => {
@@ -939,10 +938,7 @@ describe("createSubagentHandler", () => {
     expect(workflowInput.sandbox).toBeUndefined();
   });
 
-  it("does not signal destroy for none subagents", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
-
+  it("destroySubagentSandboxes is a no-op for none subagents", async () => {
     const noneSubagent: SubagentConfig = {
       agentName: "none-agent",
       description: "No sandbox",
@@ -959,14 +955,7 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastResult = startMock.mock.results.at(-1);
-    if (!lastResult) throw new Error("expected startChild call");
-    const childHandle = await lastResult.value;
-    childHandle.signal.mockClear();
-
-    await destroySubagentSandboxes();
-
-    expect(childHandle.signal).not.toHaveBeenCalled();
+    await expect(destroySubagentSandboxes()).resolves.toBeUndefined();
   });
 
   // --- inherit + continuation: fork ---
@@ -979,7 +968,11 @@ describe("createSubagentHandler", () => {
       agentName: "inherit-fork",
       description: "Inherit fork",
       workflow: mockWorkflow(),
-      sandbox: { source: "inherit", continuation: "fork" },
+      sandbox: {
+        source: "inherit",
+        continuation: "fork",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([config]);
@@ -1021,7 +1014,11 @@ describe("createSubagentHandler", () => {
       description: "Own continue",
       workflow: mockWorkflow(),
       thread: "continue",
-      sandbox: { source: "own", continuation: "continue" },
+      sandbox: {
+        source: "own",
+        continuation: "continue",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([config]);
@@ -1075,7 +1072,12 @@ describe("createSubagentHandler", () => {
       agentName: "lazy-fork",
       description: "Lazy fork",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", init: "once", continuation: "fork" },
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "fork",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([config]);
@@ -1131,7 +1133,12 @@ describe("createSubagentHandler", () => {
       agentName: "lazy-cont",
       description: "Lazy continue",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", init: "once", continuation: "continue" },
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "continue",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([config]);
@@ -1165,10 +1172,7 @@ describe("createSubagentHandler", () => {
 
   // --- init: once cleanup ---
 
-  it("adds first-call child handle to pendingDestroys for init=once", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
-
+  it("destroys the persistent sandbox for init=once at parent shutdown", async () => {
     nextStartChildResult = () => ({
       toolResponse: "done",
       data: null,
@@ -1176,11 +1180,17 @@ describe("createSubagentHandler", () => {
       sandboxId: "persistent-sb",
     });
 
+    const opsMock = makeMockSandboxOps();
     const config: SubagentConfig = {
       agentName: "lazy-cleanup",
       description: "Lazy cleanup",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", init: "once", continuation: "fork" },
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "fork",
+        proxy: () => opsMock,
+      },
     };
 
     const { handler, destroySubagentSandboxes } = createSubagentHandler([
@@ -1194,10 +1204,7 @@ describe("createSubagentHandler", () => {
 
     await destroySubagentSandboxes();
 
-    const lastResult = startMock.mock.results.at(-1);
-    if (!lastResult) throw new Error("expected startChild call");
-    const childHandle = await lastResult.value;
-    expect(childHandle.signal).toHaveBeenCalled();
+    expect(opsMock.destroySandbox).toHaveBeenCalledWith("persistent-sb");
   });
 
   it("returns sandboxId in response when child creates a sandbox", async () => {
@@ -1212,7 +1219,7 @@ describe("createSubagentHandler", () => {
       agentName: "own-agent",
       description: "Own sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", continuation: "fork" },
+      sandbox: { source: "own", continuation: "fork", proxy: noopSandboxProxy },
     };
 
     const { handler } = createSubagentHandler([ownSubagent]);
@@ -1325,10 +1332,15 @@ describe("createSubagentHandler", () => {
 
   // --- keep-until-parent-close ---
 
-  it("signals destroy for sandbox=own with keep-until-parent-close shutdown", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+  it("destroys sandbox for own + keep-until-parent-close", async () => {
+    nextStartChildResult = () => ({
+      toolResponse: "done",
+      data: null,
+      threadId: "child-t",
+      sandboxId: "child-sb-77",
+    });
 
+    const opsMock = makeMockSandboxOps();
     const ownSubagent: SubagentConfig = {
       agentName: "own-keep",
       description: "Own sandbox kept",
@@ -1337,6 +1349,7 @@ describe("createSubagentHandler", () => {
         source: "own",
         continuation: "fork",
         shutdown: "keep-until-parent-close",
+        proxy: () => opsMock,
       },
     };
 
@@ -1351,21 +1364,21 @@ describe("createSubagentHandler", () => {
 
     await destroySubagentSandboxes();
 
-    const lastResult = startMock.mock.results.at(-1);
-    if (!lastResult) throw new Error("expected startChild call");
-    const childHandle = await lastResult.value;
-    expect(childHandle.signal).toHaveBeenCalled();
+    expect(opsMock.destroySandbox).toHaveBeenCalledWith("child-sb-77");
   });
 
-  it("does not signal destroy for sandbox=own with keep shutdown (without parent-close)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
-
+  it("does not destroy sandbox for own + keep (without parent-close)", async () => {
+    const opsMock = makeMockSandboxOps();
     const ownSubagent: SubagentConfig = {
       agentName: "own-keep-plain",
       description: "Own sandbox keep",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", continuation: "fork", shutdown: "keep" },
+      sandbox: {
+        source: "own",
+        continuation: "fork",
+        shutdown: "keep",
+        proxy: () => opsMock,
+      },
     };
 
     const { handler, destroySubagentSandboxes } = createSubagentHandler([
@@ -1377,14 +1390,9 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastResult = startMock.mock.results.at(-1);
-    if (!lastResult) throw new Error("expected startChild call");
-    const childHandle = await lastResult.value;
-    childHandle.signal.mockClear();
-
     await destroySubagentSandboxes();
 
-    expect(childHandle.signal).not.toHaveBeenCalled();
+    expect(opsMock.destroySandbox).not.toHaveBeenCalled();
   });
 
   // --- mustSurvive does not override user shutdown ---
@@ -1409,6 +1417,7 @@ describe("createSubagentHandler", () => {
         init: "once",
         continuation: "fork",
         shutdown: "keep-until-parent-close",
+        proxy: noopSandboxProxy,
       },
     };
 
@@ -1445,6 +1454,7 @@ describe("createSubagentHandler", () => {
         init: "once",
         continuation: "fork",
         shutdown: "pause",
+        proxy: noopSandboxProxy,
       },
     };
 
@@ -1477,7 +1487,12 @@ describe("createSubagentHandler", () => {
       description: "Continue keep",
       workflow: mockWorkflow(),
       thread: "continue",
-      sandbox: { source: "own", continuation: "continue", shutdown: "keep" },
+      sandbox: {
+        source: "own",
+        continuation: "continue",
+        shutdown: "keep",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([config]);
@@ -1509,7 +1524,12 @@ describe("createSubagentHandler", () => {
       description: "Continue destroy",
       workflow: mockWorkflow(),
       thread: "continue",
-      sandbox: { source: "own", continuation: "continue", shutdown: "destroy" },
+      sandbox: {
+        source: "own",
+        continuation: "continue",
+        shutdown: "destroy",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([config]);
@@ -1524,6 +1544,309 @@ describe("createSubagentHandler", () => {
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandboxShutdown).toBe("pause");
   });
+
+  // --- snapshot continuation ---
+
+  it("forces sandboxShutdown=snapshot and passes no sandbox on first call (continuation=snapshot)", async () => {
+    const { startChild } = await import("@temporalio/workflow");
+    const startMock = startChild as ReturnType<typeof vi.fn>;
+
+    nextStartChildResult = () => ({
+      toolResponse: "first",
+      data: null,
+      threadId: "child-snap-1",
+      baseSnapshot: {
+        sandboxId: "sb-first",
+        providerId: "test",
+        data: { tag: "base" },
+        createdAt: new Date().toISOString(),
+      },
+      snapshot: {
+        sandboxId: "sb-first",
+        providerId: "test",
+        data: { tag: "exit-1" },
+        createdAt: new Date().toISOString(),
+      },
+    });
+
+    const config: SubagentConfig = {
+      agentName: "snap-agent",
+      description: "Snapshot-driven",
+      workflow: mockWorkflow(),
+      thread: "continue",
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "snapshot",
+        proxy: noopSandboxProxy,
+      },
+    };
+
+    const { handler } = createSubagentHandler([config]);
+
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "first" },
+      { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+    );
+
+    const firstCall = startMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected startChild call");
+    const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
+    expect(firstInput.sandbox).toBeUndefined();
+    expect(firstInput.sandboxShutdown).toBe("snapshot");
+  });
+
+  it("boots follow-up from stored thread snapshot on continuation=snapshot", async () => {
+    const { startChild } = await import("@temporalio/workflow");
+    const startMock = startChild as ReturnType<typeof vi.fn>;
+
+    nextStartChildResult = () => ({
+      toolResponse: "first",
+      data: null,
+      threadId: "child-snap-2",
+      baseSnapshot: {
+        sandboxId: "sb-first",
+        providerId: "test",
+        data: { tag: "base" },
+        createdAt: new Date().toISOString(),
+      },
+      snapshot: {
+        sandboxId: "sb-first",
+        providerId: "test",
+        data: { tag: "exit-1" },
+        createdAt: new Date().toISOString(),
+      },
+    });
+
+    const config: SubagentConfig = {
+      agentName: "snap-agent",
+      description: "Snapshot-driven",
+      workflow: mockWorkflow(),
+      thread: "continue",
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "snapshot",
+        proxy: noopSandboxProxy,
+      },
+    };
+
+    const { handler } = createSubagentHandler([config]);
+
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "first" },
+      { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+    );
+
+    nextStartChildResult = () => ({
+      toolResponse: "second",
+      data: null,
+      threadId: "child-snap-2", // same thread — continuation
+      snapshot: {
+        sandboxId: "sb-second",
+        providerId: "test",
+        data: { tag: "exit-2" },
+        createdAt: new Date().toISOString(),
+      },
+    });
+
+    await handler(
+      {
+        subagent: "snap-agent",
+        description: "test",
+        prompt: "second",
+        threadId: "child-snap-2",
+      },
+      { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
+    );
+
+    const secondCall = startMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected startChild call");
+    const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
+    expect(secondInput.sandbox).toEqual({
+      mode: "from-snapshot",
+      snapshot: expect.objectContaining({ data: { tag: "exit-1" } }),
+    });
+    expect(secondInput.sandboxShutdown).toBe("snapshot");
+  });
+
+  it("uses per-agent base snapshot for a new thread when init=once + continuation=snapshot", async () => {
+    const { startChild } = await import("@temporalio/workflow");
+    const startMock = startChild as ReturnType<typeof vi.fn>;
+
+    // First call — establishes base snapshot.
+    nextStartChildResult = () => ({
+      toolResponse: "first",
+      data: null,
+      threadId: "child-snap-A",
+      baseSnapshot: {
+        sandboxId: "sb-first",
+        providerId: "test",
+        data: { tag: "base" },
+        createdAt: new Date().toISOString(),
+      },
+      snapshot: {
+        sandboxId: "sb-first",
+        providerId: "test",
+        data: { tag: "exit-A" },
+        createdAt: new Date().toISOString(),
+      },
+    });
+
+    const config: SubagentConfig = {
+      agentName: "snap-agent",
+      description: "Snapshot-driven",
+      workflow: mockWorkflow(),
+      thread: "continue",
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "snapshot",
+        proxy: noopSandboxProxy,
+      },
+    };
+
+    const { handler } = createSubagentHandler([config]);
+
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "first" },
+      { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+    );
+
+    // Third call: different thread → should use base snapshot.
+    nextStartChildResult = () => ({
+      toolResponse: "new-thread",
+      data: null,
+      threadId: "child-snap-B",
+      snapshot: {
+        sandboxId: "sb-B",
+        providerId: "test",
+        data: { tag: "exit-B" },
+        createdAt: new Date().toISOString(),
+      },
+    });
+
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "new" },
+      { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
+    );
+
+    const secondCall = startMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected startChild call");
+    const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
+    expect(secondInput.sandbox).toEqual({
+      mode: "from-snapshot",
+      snapshot: expect.objectContaining({ data: { tag: "base" } }),
+    });
+  });
+
+  it("deletes every stored snapshot via sandbox.proxy during cleanup sweep", async () => {
+    const opsMock = makeMockSandboxOps();
+    const config: SubagentConfig = {
+      agentName: "snap-agent",
+      description: "Snapshot-driven",
+      workflow: mockWorkflow(),
+      thread: "continue",
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "snapshot",
+        proxy: () => opsMock,
+      },
+    };
+
+    const { handler, cleanupSubagentSnapshots } = createSubagentHandler([
+      config,
+    ]);
+
+    // Call 1 — produces base + exit-1.
+    nextStartChildResult = () => ({
+      toolResponse: "first",
+      data: null,
+      threadId: "child-t",
+      baseSnapshot: {
+        sandboxId: "sb-first",
+        providerId: "test",
+        data: { tag: "base" },
+        createdAt: new Date().toISOString(),
+      },
+      snapshot: {
+        sandboxId: "sb-first",
+        providerId: "test",
+        data: { tag: "exit-1" },
+        createdAt: new Date().toISOString(),
+      },
+    });
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "first" },
+      { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+    );
+
+    // Call 2 — same thread, produces exit-2 (supersedes exit-1).
+    nextStartChildResult = () => ({
+      toolResponse: "second",
+      data: null,
+      threadId: "child-t",
+      snapshot: {
+        sandboxId: "sb-second",
+        providerId: "test",
+        data: { tag: "exit-2" },
+        createdAt: new Date().toISOString(),
+      },
+    });
+    await handler(
+      {
+        subagent: "snap-agent",
+        description: "test",
+        prompt: "second",
+        threadId: "child-t",
+      },
+      { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
+    );
+
+    await cleanupSubagentSnapshots();
+
+    // Parent should have deleted both the latest thread snapshot and the
+    // per-agent base snapshot through the subagent's sandbox.proxy.
+    const deletedTags = opsMock.deleteSandboxSnapshot.mock.calls.map(
+      (call) => (call[0] as { data: { tag: string } }).data.tag
+    );
+    expect(deletedTags.sort()).toEqual(["base", "exit-2"]);
+  });
+
+  it("does not call deleteSandboxSnapshot for children that produced no snapshots", async () => {
+    const opsMock = makeMockSandboxOps();
+    const config: SubagentConfig = {
+      agentName: "snap-agent",
+      description: "Snapshot-driven",
+      workflow: mockWorkflow(),
+      thread: "continue",
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "snapshot",
+        proxy: () => opsMock,
+      },
+    };
+
+    const { handler, cleanupSubagentSnapshots } = createSubagentHandler([
+      config,
+    ]);
+
+    nextStartChildResult = () => ({
+      toolResponse: "no-snap",
+      data: null,
+      threadId: "child-t",
+    });
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "run" },
+      { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+    );
+
+    await cleanupSubagentSnapshots();
+
+    expect(opsMock.deleteSandboxSnapshot).not.toHaveBeenCalled();
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -1865,64 +2188,23 @@ describe("defineSubagentWorkflow", () => {
     });
   });
 
-  it("validates destroySandbox required for keep-until-parent-close", async () => {
-    // @ts-expect-error — deliberately omitting destroySandbox to test runtime validation
-    const workflow = defineSubagentWorkflow(
-      {
-        name: "test",
-        description: "test agent",
-        sandboxShutdown: "keep-until-parent-close",
-      },
-      async () => ({
-        toolResponse: "ok",
-        data: null,
-        threadId: "t",
-        sandboxId: "sb-1",
-      })
-    );
-
-    await expect(workflow("go", {})).rejects.toThrow(
-      /keep-until-parent-close.*destroySandbox/
-    );
-  });
-
-  it("validates sandboxId required for keep-until-parent-close", async () => {
-    // @ts-expect-error — deliberately omitting sandboxId to test runtime validation
-    const workflow = defineSubagentWorkflow(
-      {
-        name: "test",
-        description: "test agent",
-        sandboxShutdown: "keep-until-parent-close",
-      },
-      async () => ({
-        toolResponse: "ok",
-        data: null,
-        threadId: "t",
-        destroySandbox: async () => {},
-      })
-    );
-
-    await expect(workflow("go", {})).rejects.toThrow(
-      /keep-until-parent-close.*sandboxId/
-    );
-  });
-
   it("uses keep-until-parent-close from workflowInput override in sessionInput", async () => {
     let capturedSession: SubagentSessionInput | undefined;
     const workflow = defineSubagentWorkflow(
       { name: "test", description: "test agent" },
       async (_prompt, sessionInput) => {
         capturedSession = sessionInput;
-        return { toolResponse: "ok", data: null, threadId: "t" };
+        return {
+          toolResponse: "ok",
+          data: null,
+          threadId: "t",
+          sandboxId: "sb-1",
+        };
       }
     );
 
-    // Validation will throw because destroySandbox is missing, but sessionInput is captured first
-    try {
-      await workflow("go", { sandboxShutdown: "keep-until-parent-close" });
-    } catch {
-      // expected — no destroySandbox callback
-    }
+    await workflow("go", { sandboxShutdown: "keep-until-parent-close" });
+
     expect(capturedSession?.sandboxShutdown).toBe("keep-until-parent-close");
   });
 });