@aexol/spectral 0.9.221 → 0.9.223

package/dist/agent/index.d.ts

@@ -22,13 +22,17 @@
  *   - Tool filtering (only the tools specified in agent config)
  *   - Model selection (session model preferred, agent-configured as fallback)
  *   - Signal propagation (abort passthrough)
- *   - Access to observational memory via the recall tool
+ *   - Access to observational memory via the `recall` and
+ *     `write_project_observation` tools, which run against a parent-session
+ *     point-in-time snapshot (branch + session id); other observation tools
+ *     (`share_project_observation`, `receive_agent_observations`,
+ *     `compact_context`, `subagent`) remain excluded
  */
 import type { AgentTool } from "../sdk/agent-core/index.js";
 import { type ExtensionAPI, type ExtensionContext } from "../sdk/coding-agent/index.js";
 import { type AgentConfig } from "./agents.js";
 import type { ServerEvent } from "../server/wire.ts";
-import type { ExtensionContext as RichExtensionContext } from "../sdk/coding-agent/core/extensions/types.js";
+import type { ReadonlySessionManager } from "../sdk/coding-agent/core/session-manager.js";
 /**
  * Build the system prompt for a subagent session.
  *
@@ -44,8 +48,21 @@ export declare function buildSubagentSystemPrompt(baseSystemPrompt: string | und
  * Give subagents a point-in-time branch view without exposing the live parent
  * SessionManager. Each getBranch call returns fresh clones of the snapshot.
  */
-export declare function createSubagentSessionManagerSnapshot(sessionManager: ExtensionContext["sessionManager"]): Pick<RichExtensionContext["sessionManager"], "getBranch">;
+export declare function createSubagentSessionManagerSnapshot(sessionManager: ExtensionContext["sessionManager"]): Pick<ReadonlySessionManager, "getBranch" | "getSessionId">;
 export declare function resolveSubagentTools(cwd: string, ext: ExtensionAPI, ctx: ExtensionContext): AgentTool[];
+/** Test hook: replace the run-level retry sleep (e.g. with an instant/collecting stub). */
+export declare function setSubagentRetrySleepForTesting(fn?: (ms: number, signal?: AbortSignal) => Promise<void>): void;
+/**
+ * Resolve the max number of child-run attempts for the run-level retry loop.
+ * An explicit tool param (clamped to 0-10) overrides everything — including a
+ * globally disabled retry switch. Without the param, the session default
+ * (3 retries) applies unless retry is explicitly disabled, in which case a
+ * single attempt is made.
+ */
+export declare function resolveSubagentMaxAttempts(explicit: number | undefined, settings: {
+    enabled?: boolean;
+    maxRetries?: number;
+} | undefined): number;
 export default function subagentExtension(ext: ExtensionAPI, opts?: {
     disabledAgents?: string[];
     emitSubagentEvent?: (event: ServerEvent) => void;

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,OAAO,KAAK,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAuG7G;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AA0JD;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,CAK3D;AAoBD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAoCb;AAycD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CAgaN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAqBpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,MAAM,8BAA8B,CAAC;AAItC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,OAAO,KAAK,EAAE,sBAAsB,EAAgB,MAAM,6CAA6C,CAAC;AAuGxG;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AA4JD;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,sBAAsB,EAAE,WAAW,GAAG,cAAc,CAAC,CAe5D;AA6BD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAwCb;AAqHD,2FAA2F;AAC3F,wBAAgB,+BAA+B,CAC9C,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GACtD,IAAI,CAEN;AAmBD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAC9D,MAAM,CAiBR;AA2eD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CA2aN"}

package/dist/agent/index.js

@@ -22,12 +22,17 @@
  *   - Tool filtering (only the tools specified in agent config)
  *   - Model selection (session model preferred, agent-configured as fallback)
  *   - Signal propagation (abort passthrough)
- *   - Access to observational memory via the recall tool
+ *   - Access to observational memory via the `recall` and
+ *     `write_project_observation` tools, which run against a parent-session
+ *     point-in-time snapshot (branch + session id); other observation tools
+ *     (`share_project_observation`, `receive_agent_observations`,
+ *     `compact_context`, `subagent`) remain excluded
  */
-import { agentLoop } from "../sdk/agent-core/index.js";
+import { agentLoop, agentLoopContinue, } from "../sdk/agent-core/index.js";
 import { buildIsolatedRequestTimePrunedMessagesResult, COMPACT_CONTEXT_TOOL_NAME, } from "../memory/tools/compact-context.js";
-import { StringEnum } from "../sdk/ai/index.js";
+import { isRateLimitError, isTransientApiError, isContextOverflow, isPaymentRequiredError, StringEnum, streamSimple, } from "../sdk/ai/index.js";
 import { mutateSystemPrompt } from "../sdk/coding-agent/core/system-prompt-mutator.js";
+import { sleep } from "../sdk/coding-agent/utils/sleep.js";
 import { Type } from "typebox";
 import { discoverAgents, agentMetadataBlock, } from "./agents.js";
 import { loadAgentSettings } from "../server/handlers/agent-settings.js";
@@ -40,6 +45,7 @@ import { wrapToolDefinition } from "../sdk/coding-agent/core/tools/tool-definiti
 import { RECALL_OBSERVATION_TOOL_NAME } from "../memory/tools/recall-observation.js";
 import { RECEIVE_AGENT_OBSERVATIONS_TOOL_NAME } from "../memory/tools/receive-agent-observations.js";
 import { SHARE_PROJECT_OBSERVATION_TOOL_NAME } from "../memory/tools/share-project-observation.js";
+import { WRITE_PROJECT_OBSERVATION_TOOL_NAME } from "../memory/tools/write-project-observation.js";
 import { compressSubagentToolResult } from "../memory/tool-output-compressor.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -230,8 +236,18 @@ function cloneSessionEntry(entry) {
  */
 export function createSubagentSessionManagerSnapshot(sessionManager) {
     const snapshot = sessionManager.getBranch().map(cloneSessionEntry);
+    // Optional call tolerates minimal branch-only snapshots in tests; a
+    // missing id falls through to the tools' `no_session` handling.
+    const sessionId = sessionManager.getSessionId?.();
     return {
         getBranch: () => snapshot.map(cloneSessionEntry),
+        // Captured eagerly so the session id and the branch snapshot come
+        // from the same point in time. fork/newSession mutate the live
+        // SessionManager's sessionId in place, so a lazy read could diverge
+        // from the point-in-time branch on a mid-run fork. Subagent
+        // observations must be attributed to the parent session id at
+        // snapshot creation, same branch semantics as `recall`.
+        getSessionId: () => sessionId,
     };
 }
 /**
@@ -251,14 +267,27 @@ const SUBAGENT_EXCLUDED_TOOL_NAMES = new Set([
     RECEIVE_AGENT_OBSERVATIONS_TOOL_NAME,
     SHARE_PROJECT_OBSERVATION_TOOL_NAME,
 ]);
+/**
+ * Extension tools that run with the parent session's point-in-time branch
+ * snapshot instead of the bare `{ cwd, getSystemPrompt }` isolated context.
+ */
+const SUBAGENT_SESSION_SNAPSHOT_TOOL_NAMES = new Set([
+    RECALL_OBSERVATION_TOOL_NAME,
+    WRITE_PROJECT_OBSERVATION_TOOL_NAME,
+]);
 export function resolveSubagentTools(cwd, ext, ctx) {
     // Subagents receive every tool registered on the primary agent. Built-in
     // tools are created fresh with the subagent's isolated cwd/jobs, and
-    // extension-registered tools are wrapped with an isolated context exposing
-    // only `cwd` and `getSystemPrompt` (plus a read-only branch snapshot for
-    // `recall`).
+    // extension-registered tools are wrapped with a `SubagentToolContext`:
+    // always `cwd` + `getSystemPrompt`, plus a point-in-time parent-session
+    // branch snapshot for the observation tools that need branch/session
+    // semantics. Everything else (ui, modelRegistry, live sessionManager) is
+    // absent at runtime, so handlers must guard those members.
     const tools = [];
     const jobs = new BashJobRegistry();
+    // One shared snapshot per invocation so all snapshot-routed tools observe
+    // the same parent-session epoch (branch + session id).
+    const sharedSnapshot = createSubagentSessionManagerSnapshot(ctx.sessionManager);
     for (const toolInfo of ext.getAllTools()) {
         const name = toolInfo.name;
         if (SUBAGENT_EXCLUDED_TOOL_NAMES.has(name))
@@ -278,11 +307,10 @@ export function resolveSubagentTools(cwd, ext, ctx) {
         const toolDef = ext.getToolDefinition(name);
         if (!toolDef)
             continue;
-        const isolatedContext = name === RECALL_OBSERVATION_TOOL_NAME
-            ? { cwd, sessionManager: createSubagentSessionManagerSnapshot(ctx.sessionManager), getSystemPrompt: ctx.getSystemPrompt }
+        const isolatedContext = SUBAGENT_SESSION_SNAPSHOT_TOOL_NAMES.has(name)
+            ? { cwd, sessionManager: sharedSnapshot, getSystemPrompt: ctx.getSystemPrompt }
             : { cwd, getSystemPrompt: ctx.getSystemPrompt };
-        const isolatedContextWithNoParent = isolatedContext;
-        tools.push(wrapToolDefinition(toolDef, () => isolatedContextWithNoParent));
+        tools.push(wrapToolDefinition(toolDef, () => isolatedContext));
     }
     return tools;
 }
@@ -307,15 +335,17 @@ async function mapWithConcurrencyLimit(items, concurrency, fn) {
     return results;
 }
 /**
- * Wraps `runSingleAgent` with an independent per-subagent timeout.
+ * Runs a child agent with an independent per-subagent timeout.
  *
  * Combines the parent's abort signal with a fresh timeout AbortController so
  * that no single subagent can exhaust the parent prompt's full timeout budget.
+ * The budget covers the WHOLE child run including any resume retries (see
+ * `runSingleAgent`), so wall time stays bounded by SUBAGENT_TIMEOUT_MS.
  * On timeout, returns a clear error result instead of throwing so the parent
  * agent can continue (e.g. stop a chain, or surface the error as the tool
  * result for parallel/single modes).
  */
-async function runSingleAgentWithTimeout(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx) {
+async function runSingleAgentWithTimeout(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx, maxRetries) {
     const timeoutMs = SUBAGENT_TIMEOUT_MS;
     const timeoutSeconds = timeoutMs / 1000;
     const controller = new AbortController();
@@ -329,7 +359,7 @@ async function runSingleAgentWithTimeout(defaultCwd, agents, agentName, task, cw
             signal.addEventListener("abort", onParentAbort, { once: true });
     }
     try {
-        const result = await runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, controller.signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx);
+        const result = await runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, controller.signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx, maxRetries);
         // If the timeout fired (and parent signal did not), surface a clean
         // timeout error result rather than a bare "aborted" result.
         if (controller.signal.aborted &&
@@ -352,10 +382,61 @@ async function runSingleAgentWithTimeout(defaultCwd, agents, agentName, task, cw
         clearTimeout(timeoutId);
     }
 }
+/**
+ * Backoff sleep for the run-level retry loop; overridable in tests. Abort-aware
+ * (mirrors the main session's abortable retry sleep): it rejects as soon as the
+ * run signal aborts instead of stalling for the full delay.
+ */
+let retrySleep = (ms, signal) => sleep(ms, signal);
+/** Test hook: replace the run-level retry sleep (e.g. with an instant/collecting stub). */
+export function setSubagentRetrySleepForTesting(fn) {
+    retrySleep = fn ?? ((ms, signal) => sleep(ms, signal));
+}
+/** Upper bound for the tool-level `maxRetries` param (defense against bad values). */
+const SUBAGENT_MAX_RETRIES_CAP = 10;
+/**
+ * Minimal assistant-shaped probe used to ask `isContextOverflow` about a bare
+ * error string during retry classification.
+ */
+function buildOverflowProbe(errorMessage) {
+    return {
+        role: "assistant",
+        content: [],
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        stopReason: "error",
+        errorMessage,
+    };
+}
+/**
+ * Resolve the max number of child-run attempts for the run-level retry loop.
+ * An explicit tool param (clamped to 0-10) overrides everything — including a
+ * globally disabled retry switch. Without the param, the session default
+ * (3 retries) applies unless retry is explicitly disabled, in which case a
+ * single attempt is made.
+ */
+export function resolveSubagentMaxAttempts(explicit, settings) {
+    // Non-finite values (NaN/Infinity) from direct internal callers are treated
+    // as absent — otherwise `1 + NaN` would poison the attempts cap and loop.
+    const capped = explicit !== undefined && Number.isFinite(explicit)
+        ? Math.max(0, Math.min(SUBAGENT_MAX_RETRIES_CAP, Math.floor(explicit)))
+        : undefined;
+    if (capped !== undefined)
+        return 1 + capped;
+    if (settings && settings.enabled === false)
+        return 1;
+    // Settings-derived values are hardened the same way as the explicit param:
+    // a non-finite maxRetries would otherwise poison the cap (`segments >= NaN`
+    // is never true → unbounded retries).
+    const settingsRetries = Number.isFinite(settings?.maxRetries)
+        ? Math.min(SUBAGENT_MAX_RETRIES_CAP, settings.maxRetries)
+        : undefined;
+    const retries = settingsRetries ?? 3;
+    return 1 + retries;
+}
 // ---------------------------------------------------------------------------
 // Core — run a single subagent in-process via agentLoop
 // ---------------------------------------------------------------------------
-async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx) {
+async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx, maxRetries) {
     const normalizedAgentName = agentName.replace(/^@/, "");
     const agent = agents.find((a) => a.name === normalizedAgentName);
     if (!agent) {
@@ -466,7 +547,29 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             });
         }
     };
+    // Run-level retry policy for the resume loop below (mirrors
+    // AgentSession._prepareRetry + its settings-driven backoff).
+    const retrySettings = ctx.settingsManager?.getRetrySettings?.();
+    const maxSegments = resolveSubagentMaxAttempts(maxRetries, retrySettings);
+    const baseDelayMs = Number.isFinite(retrySettings?.baseDelayMs)
+        ? retrySettings?.baseDelayMs
+        : 2000;
     try {
+        // Provider retry settings: subagents must inherit the same configurable
+        // retry policy as the main session (see sdk.ts streamFn wrapper) instead
+        // of silently falling back to provider SDK defaults (e.g. OpenAI's
+        // maxRetries=2 is too few for multi-minute outages). `ctx.settingsManager`
+        // is optional on ExtensionContext — when absent the wrapper below simply
+        // forwards options untouched, so provider/SDK defaults still apply.
+        // Optional call: symmetric with getRetrySettings?.() above — partial
+        // settingsManager stubs (extension contexts, tests) must not throw.
+        const providerRetrySettings = ctx.settingsManager?.getProviderRetrySettings?.();
+        const subagentStreamFn = (streamModel, streamContext, options) => streamSimple(streamModel, streamContext, {
+            ...options,
+            timeoutMs: options?.timeoutMs ?? providerRetrySettings?.timeoutMs,
+            maxRetries: options?.maxRetries ?? providerRetrySettings?.maxRetries,
+            maxRetryDelayMs: options?.maxRetryDelayMs ?? providerRetrySettings?.maxRetryDelayMs,
+        });
         // Invocation-local hook state; never reuse the parent extension context/runtime.
         const config = {
             model,
@@ -496,81 +599,166 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
                 }
             },
         };
-        const stream = agentLoop([{ role: "user", content: [{ type: "text", text: task }], timestamp: Date.now() }], {
+        const initialPrompt = [
+            {
+                role: "user",
+                content: [{ type: "text", text: task }],
+                timestamp: Date.now(),
+            },
+        ];
+        const baseContext = {
             systemPrompt: `${effectivePrompt}\n\n---\n\n# Task\n\n${task}`,
             messages: [],
             tools,
-        }, config, signal);
+        };
         // Collect messages from the stream
         const collectedMessages = [];
         let hadError = false;
-        for await (const event of stream) {
-            if (signal?.aborted) {
-                hadError = true;
-                break;
-            }
-            onInternalEvent?.(event, parentToolCallId);
-            if (event.type === "message_update" && event.message?.role === "assistant") {
-                // Forward streaming text/thinking deltas so the UI can show the
-                // subagent process as it's generated, not just the final result.
-                const inner = event.assistantMessageEvent;
-                if (inner?.type === "text_delta" && inner.delta) {
-                    streamingText += inner.delta;
-                    emitUpdate();
+        let segments = 0;
+        // One child run may span several segments: the first one starts the
+        // loop, any later one resumes it. Tool results already recorded in
+        // `collectedMessages` are part of the resumed context, so tools are
+        // never re-executed by a retry.
+        const consumeStream = async (stream) => {
+            for await (const event of stream) {
+                if (signal?.aborted) {
+                    hadError = true;
+                    break;
                 }
-                else if (inner?.type === "thinking_delta" && inner.delta) {
-                    thinkingText += inner.delta;
-                    if (inner.metadata) {
-                        thinkingMetadata = { ...(thinkingMetadata ?? {}), ...inner.metadata };
+                onInternalEvent?.(event, parentToolCallId);
+                if (event.type === "message_update" && event.message?.role === "assistant") {
+                    // Forward streaming text/thinking deltas so the UI can show the
+                    // subagent process as it's generated, not just the final result.
+                    const inner = event.assistantMessageEvent;
+                    if (inner?.type === "text_delta" && inner.delta) {
+                        streamingText += inner.delta;
+                        emitUpdate();
                     }
-                    emitUpdate();
-                }
-                continue;
-            }
-            if (event.type === "message_end" && event.message) {
-                const msg = event.message;
-                collectedMessages.push(msg);
-                if (msg.role === "assistant") {
-                    // Reset streaming accumulator — final text is now in messages
-                    streamingText = "";
-                    currentResult.usage.turns++;
-                    const usage = msg.usage;
-                    if (usage) {
-                        currentResult.usage.input += usage.input || 0;
-                        currentResult.usage.output += usage.output || 0;
-                        currentResult.usage.cacheRead += usage.cacheRead || 0;
-                        currentResult.usage.cacheWrite += usage.cacheWrite || 0;
-                        currentResult.usage.cost += usage.cost?.total || 0;
-                        currentResult.usage.contextTokens = usage.totalTokens || 0;
+                    else if (inner?.type === "thinking_delta" && inner.delta) {
+                        thinkingText += inner.delta;
+                        if (inner.metadata) {
+                            thinkingMetadata = { ...(thinkingMetadata ?? {}), ...inner.metadata };
+                        }
+                        emitUpdate();
                     }
-                    if (!currentResult.model && msg.model)
-                        currentResult.model = msg.model;
-                    if (msg.stopReason)
-                        currentResult.stopReason = msg.stopReason;
-                    if (msg.errorMessage)
-                        currentResult.errorMessage = msg.errorMessage;
-                    if (msg.stopReason === "error" || msg.stopReason === "aborted") {
-                        hadError = true;
+                    continue;
+                }
+                if (event.type === "message_end" && event.message) {
+                    const msg = event.message;
+                    collectedMessages.push(msg);
+                    if (msg.role === "assistant") {
+                        // Reset streaming accumulator — final text is now in messages
+                        streamingText = "";
+                        currentResult.usage.turns++;
+                        const usage = msg.usage;
+                        if (usage) {
+                            currentResult.usage.input += usage.input || 0;
+                            currentResult.usage.output += usage.output || 0;
+                            currentResult.usage.cacheRead += usage.cacheRead || 0;
+                            currentResult.usage.cacheWrite += usage.cacheWrite || 0;
+                            currentResult.usage.cost += usage.cost?.total || 0;
+                            currentResult.usage.contextTokens = usage.totalTokens || 0;
+                        }
+                        if (!currentResult.model && msg.model)
+                            currentResult.model = msg.model;
+                        if (msg.stopReason)
+                            currentResult.stopReason = msg.stopReason;
+                        if (msg.errorMessage)
+                            currentResult.errorMessage = msg.errorMessage;
+                        if (msg.stopReason === "error" || msg.stopReason === "aborted") {
+                            hadError = true;
+                        }
                     }
+                    currentResult.messages = [...collectedMessages];
+                    emitUpdate();
+                }
+                if (event.type === "tool_execution_end" && event.isError) {
+                    emitUpdate();
+                }
+                if (event.type === "agent_end" && event.error) {
+                    hadError = true;
+                    currentResult.errorMessage = event.error;
+                    currentResult.stderr = event.error;
                 }
-                currentResult.messages = [...collectedMessages];
-                emitUpdate();
             }
-            if (event.type === "tool_execution_end" && event.isError) {
-                emitUpdate();
+        };
+        for (;;) {
+            segments++;
+            // Per-segment transient state: a resumed segment must be able to
+            // succeed without inheriting the previous segment's failure flags.
+            hadError = false;
+            streamingText = "";
+            // Drop thinking accumulated by the failed segment so the live sheet
+            // shows the resumed segment's reasoning, not stale text.
+            thinkingText = "";
+            thinkingMetadata = undefined;
+            currentResult.stopReason = undefined;
+            currentResult.errorMessage = undefined;
+            currentResult.stderr = "";
+            // Resume (segments > 1) continues the child with its existing
+            // transcript through `agentLoopContinue` — the same mechanism the
+            // main session uses (Agent.continue → runAgentLoopContinue) — so
+            // already-executed tools are NOT re-run. Only when there is nothing
+            // to resume from (empty transcript) do we fall back to a fresh
+            // `agentLoop` call, which then re-emits the initial prompt.
+            const canResume = collectedMessages.length > 0 &&
+                collectedMessages[collectedMessages.length - 1].role !== "assistant";
+            const stream = segments === 1 || !canResume
+                ? agentLoop(initialPrompt, baseContext, config, signal, subagentStreamFn)
+                : agentLoopContinue({ ...baseContext, messages: [...collectedMessages] }, config, signal, subagentStreamFn);
+            await consumeStream(stream);
+            // Drain the stream result (already consumed by iteration, but ensure cleanup)
+            try {
+                await stream.result();
             }
-            if (event.type === "agent_end" && event.error) {
-                hadError = true;
-                currentResult.errorMessage = event.error;
-                currentResult.stderr = event.error;
+            catch {
+                // Stream result error — already handled by message events
             }
-        }
-        // Drain the stream result (already consumed by iteration, but ensure cleanup)
-        try {
-            await stream.result();
-        }
-        catch {
-            // Stream result error — already handled by message events
+            // ── Run-level retry decision (mirrors AgentSession._prepareRetry) ──
+            if (segments >= maxSegments)
+                break;
+            if (currentResult.stopReason !== "error")
+                break;
+            // Abort after a completed segment (parent stop or budget timeout):
+            // never retry, and never sleep into a phantom extra segment.
+            if (signal?.aborted)
+                break;
+            const errorMessage = currentResult.errorMessage || "";
+            // Payment required (402) is a billing problem — retries cannot help.
+            // Explicit for parity with AgentSession._isRetryableError.
+            if (isPaymentRequiredError(errorMessage))
+                break;
+            // Context overflow is a hard failure, not transient. It must be
+            // checked before the classifiers because overflow messages can
+            // contain bare status-code-like numerals (e.g. "501234 tokens >
+            // 500000 maximum").
+            if (isContextOverflow(buildOverflowProbe(errorMessage), model.contextWindow)) {
+                break;
+            }
+            if (!isRateLimitError(errorMessage) && !isTransientApiError(errorMessage)) {
+                break;
+            }
+            // Drop the failed assistant message(s) so the child resumes AT the
+            // failed turn instead of re-running it. Several trailing assistant
+            // messages are possible: the in-loop retry emits a failed assistant
+            // message before popping it from the loop context.
+            while (collectedMessages.length > 0 &&
+                collectedMessages[collectedMessages.length - 1].role === "assistant") {
+                collectedMessages.pop();
+            }
+            currentResult.messages = [...collectedMessages];
+            try {
+                await retrySleep(baseDelayMs * 2 ** (segments - 1), signal);
+            }
+            catch {
+                // Aborted during the backoff window (the sleep rejects on abort):
+                // fall through to the check below instead of throwing out of the
+                // child run.
+            }
+            // Abort during the backoff window: break so the attempt annotation
+            // counts only completed segments.
+            if (signal?.aborted)
+                break;
         }
         currentResult.exitCode = hadError ? 1 : 0;
         if (signal?.aborted) {
@@ -578,6 +766,12 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             currentResult.stopReason = "aborted";
             currentResult.errorMessage = "Subagent was aborted";
         }
+        if (segments > 1) {
+            currentResult.attempts = segments;
+            if (currentResult.exitCode !== 0 && currentResult.errorMessage) {
+                currentResult.errorMessage = `${currentResult.errorMessage} (failed after ${segments} attempts)`;
+            }
+        }
         return currentResult;
     }
     catch (err) {
@@ -625,6 +819,11 @@ const SubagentParams = Type.Object({
     cwd: Type.Optional(Type.String({
         description: "Working directory for the agent process (single mode)",
     })),
+    maxRetries: Type.Optional(Type.Integer({
+        description: "Max automatic resume retries after a transient provider failure: the child resumes at the failed turn instead of restarting, so its tools are not re-executed (overrides the configured retry count and a disabled retry switch; 0-10).",
+        minimum: 0,
+        maximum: 10,
+    })),
 });
 // ---------------------------------------------------------------------------
 // Extension entry point
@@ -807,7 +1006,7 @@ export default function subagentExtension(ext, opts) {
                             }
                         }
                         : undefined;
-                    const result = await runSingleAgentWithTimeout(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"), _toolCallId, emitSubagentToolProgress, ext, ctx);
+                    const result = await runSingleAgentWithTimeout(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"), _toolCallId, emitSubagentToolProgress, ext, ctx, params.maxRetries);
                     results.push(result);
                     const isError = result.exitCode !== 0 ||
                         result.stopReason === "error" ||
@@ -834,7 +1033,9 @@ export default function subagentExtension(ext, opts) {
                     const output = truncateOutput(getFinalOutput(r.messages) || "(no output)", SUBAGENT_OUTPUT_LIMIT);
                     const status = r.exitCode === 0
                         ? "completed"
-                        : "failed";
+                        : r.attempts && r.attempts > 1
+                            ? `failed (after ${r.attempts} attempts)`
+                            : "failed";
                     return `[step ${idx + 1} - ${r.agent}] ${status}:\n${output}`;
                 });
                 return {
@@ -892,7 +1093,7 @@ export default function subagentExtension(ext, opts) {
                             allResults[index] = partial.details.results[0];
                             emitParallelUpdate();
                         }
-                    }, makeDetails("parallel"), _toolCallId, emitSubagentToolProgress, ext, ctx);
+                    }, makeDetails("parallel"), _toolCallId, emitSubagentToolProgress, ext, ctx, params.maxRetries);
                     allResults[index] = result;
                     emitParallelUpdate();
                     return result;
@@ -900,7 +1101,12 @@ export default function subagentExtension(ext, opts) {
                 const successCount = results.filter((r) => r.exitCode === 0).length;
                 const summaries = results.map((r) => {
                     const output = truncateOutput(getFinalOutput(r.messages), SUBAGENT_OUTPUT_LIMIT);
-                    return `[${r.agent}] ${r.exitCode === 0 ? "completed" : "failed"}:\n${output || "(no output)"}`;
+                    const status = r.exitCode === 0
+                        ? "completed"
+                        : r.attempts && r.attempts > 1
+                            ? `failed (after ${r.attempts} attempts)`
+                            : "failed";
+                    return `[${r.agent}] ${status}:\n${output || "(no output)"}`;
                 });
                 return {
                     content: [
@@ -914,7 +1120,7 @@ export default function subagentExtension(ext, opts) {
             }
             // ── Single mode ─────────────────────────────────────────────
             if (params.agent && params.task) {
-                const result = await runSingleAgentWithTimeout(ctx.cwd, agents, params.agent, params.task, params.cwd, undefined, signal, onUpdate, makeDetails("single"), _toolCallId, emitSubagentToolProgress, ext, ctx);
+                const result = await runSingleAgentWithTimeout(ctx.cwd, agents, params.agent, params.task, params.cwd, undefined, signal, onUpdate, makeDetails("single"), _toolCallId, emitSubagentToolProgress, ext, ctx, params.maxRetries);
                 const isError = result.exitCode !== 0 ||
                     result.stopReason === "error" ||
                     result.stopReason === "aborted";