zeitlich 0.2.36 → 0.2.38

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,15 +32,11 @@ 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");
     }),
-    startChild: vi.fn(
+    executeChild: vi.fn(
       async (
         _workflow: unknown,
         opts: { workflowId: string; args: unknown[] }
@@ -57,17 +51,7 @@ 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),
-          workflowId: opts.workflowId,
-        };
+        return result;
       }
     ),
     getExternalWorkflowHandle: vi.fn((_id: string) => ({
@@ -104,7 +88,6 @@ import type {
 } from "./types";
 afterEach(() => {
   nextStartChildResult = null;
-  capturedSignalHandlers.clear();
 });
 
 function mockWorkflow(name?: string): SubagentWorkflow {
@@ -117,6 +100,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
 // ---------------------------------------------------------------------------
@@ -370,14 +374,18 @@ describe("createSubagentHandler", () => {
   });
 
   it("passes sandbox inherit to child when sandbox is inherit", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const inheritSubagent: SubagentConfig = {
       agentName: "inherit-agent",
       description: "Inherits sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "inherit", continuation: "continue" },
+      sandbox: {
+        source: "inherit",
+        continuation: "continue",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([inheritSubagent]);
@@ -392,8 +400,8 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toEqual({
       mode: "inherit",
@@ -406,7 +414,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]);
@@ -420,14 +432,14 @@ describe("createSubagentHandler", () => {
   });
 
   it("does not pass sandboxId to child when sandbox is own (first call)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const ownSubagent: SubagentConfig = {
       agentName: "own-agent",
       description: "Own sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", continuation: "fork" },
+      sandbox: { source: "own", continuation: "fork", proxy: noopSandboxProxy },
     };
 
     const { handler } = createSubagentHandler([ownSubagent]);
@@ -442,15 +454,15 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
   });
 
   it("resolves context function at invocation time", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     let counter = 0;
     const dynamicSubagent: SubagentConfig = {
@@ -470,15 +482,15 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const context = lastCall[1].args[2] as Record<string, unknown>;
     expect(context).toEqual({ invocation: 1 });
   });
 
   it("passes static context unchanged", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const staticSubagent: SubagentConfig = {
       agentName: "static-ctx",
@@ -494,21 +506,21 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const context = lastCall[1].args[2] as Record<string, unknown>;
     expect(context).toEqual({ key: "value" });
   });
 
   it("does not pass sandbox init when sandbox is own without prior sandbox", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const ownSubagent: SubagentConfig = {
       agentName: "own-agent",
       description: "Own sandbox",
       workflow: mockWorkflow(),
-      sandbox: { source: "own", continuation: "fork" },
+      sandbox: { source: "own", continuation: "fork", proxy: noopSandboxProxy },
     };
 
     const { handler } = createSubagentHandler([ownSubagent]);
@@ -523,8 +535,8 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
   });
@@ -532,8 +544,8 @@ describe("createSubagentHandler", () => {
   // --- Thread mode ---
 
   it("passes thread fork when thread is fork and threadId provided", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const contSubagent: SubagentConfig = {
       agentName: "cont",
@@ -554,8 +566,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.thread).toEqual({
       mode: "fork",
@@ -564,8 +576,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("passes thread continue when thread is continue", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const contSubagent: SubagentConfig = {
       agentName: "cont-mode",
@@ -586,8 +598,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.thread).toEqual({
       mode: "continue",
@@ -596,8 +608,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("does not pass thread when thread is new", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const noContSubagent: SubagentConfig = {
       agentName: "no-cont",
@@ -617,8 +629,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.thread).toBeUndefined();
   });
@@ -626,8 +638,8 @@ describe("createSubagentHandler", () => {
   // --- Sandbox continuation ---
 
   it("does not pass sandbox when thread is fork (own sandbox)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const contSandboxSubagent: SubagentConfig = {
       agentName: "sb-cont",
@@ -648,15 +660,15 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
   });
 
   it("tracks sandbox ID and passes sandbox fork on continuation", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first run done",
@@ -670,7 +682,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]);
@@ -697,8 +709,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!secondCall) throw new Error("expected second startChild call");
+    const secondCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!secondCall) throw new Error("expected second executeChild call");
     const workflowInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.thread).toEqual({
       mode: "fork",
@@ -711,8 +723,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("does not pass sandbox fork without thread continuation", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "done",
@@ -726,7 +738,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]);
@@ -748,17 +760,14 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!secondCall) throw new Error("expected executeChild call");
     const workflowInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
     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 +784,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 +805,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 +827,7 @@ describe("createSubagentHandler", () => {
         source: "own",
         continuation: "fork",
         shutdown: "pause-until-parent-close",
+        proxy: () => opsMock,
       },
     };
 
@@ -841,21 +842,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,19 +872,14 @@ 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 () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const noneSubagent: SubagentConfig = {
       agentName: "none-agent",
@@ -904,15 +899,15 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
   });
 
   it("does not pass sandboxId when sandbox is explicitly none", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const noneSubagent: SubagentConfig = {
       agentName: "none-agent",
@@ -933,16 +928,13 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     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,27 +951,24 @@ 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 ---
 
   it("forks from parent sandbox when inherit + continuation=fork", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const config: SubagentConfig = {
       agentName: "inherit-fork",
       description: "Inherit fork",
       workflow: mockWorkflow(),
-      sandbox: { source: "inherit", continuation: "fork" },
+      sandbox: {
+        source: "inherit",
+        continuation: "fork",
+        proxy: noopSandboxProxy,
+      },
     };
 
     const { handler } = createSubagentHandler([config]);
@@ -994,8 +983,8 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls.at(-1);
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls.at(-1);
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toEqual({
       mode: "fork",
@@ -1006,8 +995,8 @@ describe("createSubagentHandler", () => {
   // --- own + continuation: continue ---
 
   it("passes sandbox continue on thread continuation with continuation=continue", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1021,7 +1010,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]);
@@ -1048,8 +1041,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls.at(-1);
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
     const workflowInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toEqual({
       mode: "continue",
@@ -1061,8 +1054,8 @@ describe("createSubagentHandler", () => {
   // --- own + init: once + continuation: fork ---
 
   it("stores sandbox on first call and forks from it on second call (init=once, continuation=fork)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1075,7 +1068,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]);
@@ -1086,8 +1084,8 @@ describe("createSubagentHandler", () => {
     );
 
     // First call: no sandbox init (child creates fresh), forced pause-until-parent-close
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandbox).toBeUndefined();
     expect(firstInput.sandboxShutdown).toBe("pause-until-parent-close");
@@ -1105,8 +1103,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls.at(-1);
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
     const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(secondInput.sandbox).toEqual({
       mode: "fork",
@@ -1117,8 +1115,8 @@ describe("createSubagentHandler", () => {
   // --- own + init: once + continuation: continue ---
 
   it("stores sandbox on first call and continues it on second call (init=once, continuation=continue)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1131,7 +1129,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]);
@@ -1153,8 +1156,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls.at(-1);
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
     const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(secondInput.sandbox).toEqual({
       mode: "continue",
@@ -1165,10 +1168,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 +1176,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 +1200,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 +1215,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 +1328,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 +1345,7 @@ describe("createSubagentHandler", () => {
         source: "own",
         continuation: "fork",
         shutdown: "keep-until-parent-close",
+        proxy: () => opsMock,
       },
     };
 
@@ -1351,21 +1360,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,21 +1386,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();
+    expect(opsMock.destroySandbox).not.toHaveBeenCalled();
   });
 
   // --- mustSurvive does not override user shutdown ---
 
   it("does not override keep-until-parent-close with pause-until-parent-close for init=once", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1409,6 +1413,7 @@ describe("createSubagentHandler", () => {
         init: "once",
         continuation: "fork",
         shutdown: "keep-until-parent-close",
+        proxy: noopSandboxProxy,
       },
     };
 
@@ -1419,15 +1424,15 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandboxShutdown).toBe("keep-until-parent-close");
   });
 
   it("does not override pause with pause-until-parent-close for init=once", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1445,6 +1450,7 @@ describe("createSubagentHandler", () => {
         init: "once",
         continuation: "fork",
         shutdown: "pause",
+        proxy: noopSandboxProxy,
       },
     };
 
@@ -1455,15 +1461,15 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandboxShutdown).toBe("pause");
   });
 
   it("does not override keep with pause for continuation=continue", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1477,7 +1483,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]);
@@ -1487,15 +1498,15 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandboxShutdown).toBe("keep");
   });
 
   it("still overrides destroy with pause for continuation=continue", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1509,7 +1520,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]);
@@ -1519,11 +1535,314 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     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 { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild 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 = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild 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 { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild 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 = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild 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 { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild 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 = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild 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 +2184,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");
   });
 });