feat(subagent): require replay safety for recovery availability

A worker that wrote files or ran a shell command before its provider
gave out was still marked continuable, so a successor with the same
brief could repeat those side effects. Recovery is now available only
when every tool the run requested or started is a read, search, or web
read; anything else, including MCP and unknown tools, fails closed to
side_effects_completed and normal director-led continuation.

Author: bwachman

src/agent/tool-classification.ts

@@ -29,6 +29,19 @@ export const SEARCH_QUERY_TOOLS: ReadonlySet<string> = new Set([
   "search_files",
 ]);
 
+/**
+ * Tools whose call a recovery may replay without repeating a side effect:
+ * path-keyed reads, search queries, and web reads. Deliberately narrow and
+ * closed: run_shell, writes, MCP, and any tool not named here make a failed
+ * run ineligible for enforced recovery.
+ */
+export const REPLAY_SAFE_TOOLS: ReadonlySet<string> = new Set([
+  ...PATH_KEYED_READ_TOOLS,
+  ...SEARCH_QUERY_TOOLS,
+  "web_fetch",
+  "web_search",
+]);
+
 /**
  * Tools that never need an approval prompt (cannot change the workspace):
  * the director's read surface minus run_shell/web_fetch/web_search, which

src/subagent/session-store-failure-record.test.ts

@@ -186,6 +186,32 @@ describe("terminal failure record", () => {
     expect(after?.error).toBe("first");
   });
 
+  test("a retryable failure after a write or shell call is not replay-safe", () => {
+    for (const tool of ["write_file", "run_shell", "mcp__x__y"]) {
+      const { sessions } = store();
+      const id = startRunning(sessions);
+      sessions.appendEvent(id, toolStart("read_file", "c1"));
+      sessions.appendEvent(id, toolStart(tool, "c2"));
+      sessions.fail(id, "timeout", { failure_class: "provider_retryable" });
+      expect(sessions.get(id)?.failure?.recovery).toEqual({
+        available: false,
+        reason: "side_effects_completed",
+      });
+    }
+  });
+
+  test("a retryable failure after only read calls stays eligible", () => {
+    const { sessions } = store();
+    const id = startRunning(sessions);
+    sessions.appendEvent(id, toolStart("read_file", "c1"));
+    sessions.appendEvent(id, toolStart("grep", "c2"));
+    sessions.fail(id, "timeout", { failure_class: "provider_retryable" });
+    expect(sessions.get(id)?.failure?.recovery).toEqual({
+      available: true,
+      reason: "eligible",
+    });
+  });
+
   test("a teardown failure reports partial cleanup", () => {
     const { sessions } = store();
     const id = startRunning(sessions);

src/subagent/session-store.ts

@@ -33,6 +33,7 @@ import { canonicalToolName } from "../agent/canonical-tool-name.js";
 import {
   classifySubAgentFailure,
   failureClassForStopReason,
+  isReplaySafeToolName,
   isSubAgentLoopGuardError,
   recoveryFor,
   type SubAgentFailureClass,
@@ -843,6 +844,10 @@ export function createSubAgentSessionStore(
             attempt,
             followupTurn: followupTurns.has(id),
             cause: pendingFailures.get(id)?.cause,
+            // Every tool the run requested, started, or finished: a call
+            // that started may have landed its side effect before the run
+            // died, so this is a superset of completed calls.
+            replaySafe: session.toolNames.every(isReplaySafeToolName),
           }),
         ),
         attempt,

src/subagent/terminal-failure.test.ts

@@ -6,6 +6,7 @@ import {
   createSubAgentLoopGuardError,
   failureClassForStopReason,
   isProviderFailureClass,
+  isReplaySafeToolName,
   isSubAgentLoopGuardError,
   recoveryFor,
 } from "./terminal-failure.js";
@@ -108,6 +109,7 @@ describe("recoveryFor", () => {
         failureClass: "provider_retryable",
         attempt: 1,
         followupTurn: false,
+        replaySafe: true,
       }),
     ).toEqual({ available: true, reason: "eligible" });
   });
@@ -120,7 +122,12 @@ describe("recoveryFor", () => {
     "error",
   ] as const)("%s is not_retryable", (failureClass) => {
     expect(
-      recoveryFor({ failureClass, attempt: 1, followupTurn: false }),
+      recoveryFor({
+        failureClass,
+        attempt: 1,
+        followupTurn: false,
+        replaySafe: true,
+      }),
     ).toEqual({ available: false, reason: "not_retryable" });
   });
 
@@ -131,6 +138,7 @@ describe("recoveryFor", () => {
         attempt: 1,
         followupTurn: false,
         cause: providerError("retryable"),
+        replaySafe: true,
       }),
     ).toEqual({ available: true, reason: "eligible" });
     expect(
@@ -139,6 +147,7 @@ describe("recoveryFor", () => {
         attempt: 1,
         followupTurn: false,
         cause: createSubAgentLoopGuardError(providerError("timeout")),
+        replaySafe: true,
       }),
     ).toEqual({ available: true, reason: "eligible" });
   });
@@ -150,6 +159,7 @@ describe("recoveryFor", () => {
         attempt: 1,
         followupTurn: false,
         cause: providerError("credential_failure"),
+        replaySafe: true,
       }),
     ).toEqual({ available: false, reason: "not_retryable" });
     expect(
@@ -158,6 +168,7 @@ describe("recoveryFor", () => {
         attempt: 1,
         followupTurn: false,
         cause: new Error("doom"),
+        replaySafe: true,
       }),
     ).toEqual({ available: false, reason: "not_retryable" });
     expect(
@@ -166,6 +177,7 @@ describe("recoveryFor", () => {
         attempt: 1,
         followupTurn: true,
         cause: providerError("retryable"),
+        replaySafe: true,
       }),
     ).toEqual({ available: false, reason: "not_retryable" });
     expect(
@@ -174,6 +186,7 @@ describe("recoveryFor", () => {
         attempt: 2,
         followupTurn: false,
         cause: providerError("retryable"),
+        replaySafe: true,
       }),
     ).toEqual({ available: false, reason: "recovery_exhausted" });
   });
@@ -184,14 +197,50 @@ describe("recoveryFor", () => {
         failureClass: "provider_retryable",
         attempt: 1,
         followupTurn: true,
+        replaySafe: true,
       }),
     ).toEqual({ available: false, reason: "not_retryable" });
   });
 
+  test("a retryable failure after a non-replay-safe call has side effects", () => {
+    expect(
+      recoveryFor({
+        failureClass: "provider_retryable",
+        attempt: 1,
+        followupTurn: false,
+        replaySafe: false,
+      }),
+    ).toEqual({ available: false, reason: "side_effects_completed" });
+  });
+
+  test("only read, search, and web read tools are replay-safe", () => {
+    for (const name of ["read_file", "read", "grep", "search_files"]) {
+      expect(isReplaySafeToolName(name)).toBe(true);
+    }
+    for (const name of ["web_fetch", "web_search"]) {
+      expect(isReplaySafeToolName(name)).toBe(true);
+    }
+    for (const name of [
+      "write_file",
+      "edit_file",
+      "run_shell",
+      "bash",
+      "mcp__server__tool",
+      "some_unknown_tool",
+    ]) {
+      expect(isReplaySafeToolName(name)).toBe(false);
+    }
+  });
+
   test("a failed recovery attempt is exhausted whatever its class", () => {
     for (const failureClass of ["provider_retryable", "error"] as const) {
       expect(
-        recoveryFor({ failureClass, attempt: 2, followupTurn: false }),
+        recoveryFor({
+          failureClass,
+          attempt: 2,
+          followupTurn: false,
+          replaySafe: true,
+        }),
       ).toEqual({ available: false, reason: "recovery_exhausted" });
     }
   });

src/subagent/terminal-failure.ts

@@ -3,6 +3,8 @@ import {
   isResolvedProviderFailureError,
 } from "../inference-error-message.js";
 import { errorMessage } from "../agent/error-message.js";
+import { canonicalToolName } from "../agent/canonical-tool-name.js";
+import { REPLAY_SAFE_TOOLS } from "../agent/tool-classification.js";
 import type { ForcedStopReason } from "./stop-policy.js";
 
 /**
@@ -125,22 +127,33 @@ export function classifySubAgentFailure(
   return "error";
 }
 
+/** Whether a call to `name` can be replayed by a recovery attempt. */
+export function isReplaySafeToolName(name: string): boolean {
+  return REPLAY_SAFE_TOOLS.has(canonicalToolName(name));
+}
+
 /**
  * Recovery availability for a freshly written record. The chain cap wins
  * over class: a recovery attempt that fails is exhausted whatever its cause.
+ * Replay safety fails closed: any tool outside the read-only allowlist means
+ * a replacement could repeat a side effect.
  */
 export function recoveryFor(input: {
   failureClass: SubAgentFailureClass;
   attempt: number;
   followupTurn: boolean;
   cause?: unknown;
+  replaySafe: boolean;
 }): SubAgentRecovery {
   if (input.attempt > 1) {
     return { available: false, reason: "recovery_exhausted" };
   }
   if (input.followupTurn || !isRetryableFailure(input)) {
     return { available: false, reason: "not_retryable" };
   }
+  if (!input.replaySafe) {
+    return { available: false, reason: "side_effects_completed" };
+  }
   return { available: true, reason: "eligible" };
 }