Recover locally before changing the research plan

Learning objective

Have subagents recover locally from transient errors; let the coordinator choose a modified query, alternate source, or partial completion only after local recovery fails.

Core idea

For an architect designing recovery ownership, the specialist and coordinator have different information. The specialist holds the failed operation’s context and the work already completed. The coordinator holds the overall research plan and can compare the missing slice with other findings. Let the specialist absorb recoverable interruptions, then escalate unresolved failures with enough context for a plan-level decision.

Local recovery does not mean unlimited retries. It means repeating an eligible operation within a defined boundary while retaining completed work. Once that recovery fails, the coordinator chooses whether to change the query, use another source, or accept a qualified partial result.

Anthropic’s multi-agent research article describes combining agent adaptation with deterministic retry logic and checkpoints, and resuming work rather than restarting from the beginning. The exam objective applies that pattern to specialist failures. See 5.3.2 for the report that crosses the escalation boundary.

How it works

Separate source failures from Claude request failures

Source-service and Messages API timeouts occur at different boundaries and can have different retry owners. Place source-service retries in the source adapter or specialist execution code. Put the policy in AgentDefinition.prompt so the specialist knows when to stop local recovery and return its unresolved work.

If a client source tool ultimately fails, tool_result.is_error: true with instructive content lets Claude adapt to the failure. That signal does not configure the source service’s retry count. Your application defines that count and carries the exhausted attempt history into the final report.

The Python SDK for the Claude API separately documents max_retries and timeout. It retries eligible connection errors, HTTP 408, 409, 429, and HTTP statuses of 500 or higher twice by default with short exponential backoff. max_retries configures or disables those retries. These Python API SDK options do not configure arbitrary source tools.

The Python API SDK’s default timeout is ten minutes, and timed-out requests are retried twice by default. An attempt limit therefore does not imply a short completion deadline. Use its timeout option when configuring that request path.

Bound the specialist’s recovery

See 2.2.5 for the local attempt budget, deadlines, exhaustion state, and attemptedSteps and partialResults metadata. Require the specialist to preserve that recovery record and completed findings when it escalates an unresolved operation. A completed zero-match search remains an evidence outcome under 5.3.1, not a transient failure to retry.

Escalate changes to the plan

After eligible local recovery fails, return the four-part report from 5.3.2 plus the attempts already made. The coordinator then compares three distinct decisions:

Choose a modified query when the attempted query bundled topics or used filters that prevented useful retrieval. Name the actual change in the revised assignment: split by country, narrow the requested period, or correct an invalid parameter. Do not rerun the exhausted unchanged query under a different specialist’s name and call that a revised strategy.

Choose an alternate source when the missing evidence can be obtained through another permitted route. Tell the specialist which question the alternate source must answer and what authority or scope the evidence needs. A retrieved ministry report can be a useful route to official figures; a general commentary page is not automatically equivalent to the unavailable statistics release. The coordinator must assess whether the substitute addresses the original question.

Choose partial completion when the surviving findings answer useful independent parts of the assignment and the unresolved portion can be stated explicitly. Pass the original topic list and the missing slice to synthesis, not only the documents that succeeded. If the requested conclusion depends on the missing evidence, leave that conclusion unresolved rather than lowering its evidence requirement to make the workflow appear complete.

The coordinator can give a specialist a revised assignment through the delegation prompt, including the surviving findings and the unresolved query. See 1.3.3 for the broader context-passing contract.

Only failed local recovery reaches the coordinator, whose plan-level decisions either return a revised assignment to a specialist or pass the missing slice to synthesis.

Recognize Claude Code’s interruption reporting

Claude Code first attempts continuation when a subagent response is cut off mid-stream and the partial response contains text but no tool calls. It prompts the subagent to continue, including in interactive sessions; the run ends on the error only once those continuations are used up. This recovery precedes the foreground and background failure-reporting outcomes.

For a foreground subagent cut off by a rate limit, overload, or server error after producing text, the Agent tool returns partial output with a note that the task did not finish. If it produced nothing or only tool calls, the failure names Agent terminated early due to an API error and includes error detail. For a background subagent, Claude Code marks the subagent failed and reports the API error with its last output.

Claude Code also applies a configured fallback model chain to subagents: when a covered failure occurs, the subagent continues on the first model in the chain that accepts the request. Configure a session chain with --fallback-model, which accepts a comma-separated list, or persist it with the fallbackModel settings array; the flag takes precedence. Chains are capped at three models after duplicate removal, and a switch lasts for the current turn only.

Fallback chains cover overloaded, unavailable, or other non-retryable server errors. Authentication, billing, rate-limit, request-size, transport errors, and organization-policy denials do not trigger a switch. These are Claude Code API-recovery mechanisms, not remedies for a failed external search query. Once the underlying API error clears, the subagent documentation directs you to retry the task or resume the subagent.

These failure-reporting guarantees belong to the cited Claude Code behavior; other integrations need their own verified contract.

Key distinctions and trade-offs

Local retry versus plan revision: A retry repeats an eligible operation. Splitting a query, changing sources, or narrowing the deliverable changes the plan and belongs to the coordinator in this design.

API SDK retries versus source-tool retries: Python max_retries controls eligible Claude API requests. It does not retry another service merely because a subagent calls it.

Reported partial output versus completed evidence: Marked interrupted output preserves work. The coordinator still checks what that output establishes before using it as a finished finding.

Local recovery avoids unnecessary replanning, but excessive retries delay the decisions that might actually restore coverage. Early escalation creates unnecessary coordinator work; late escalation leaves no opportunity to adapt. Use a bounded policy and an informative handoff rather than either extreme.

Architecture / decision scenario

A specialist gathers official hospital admissions figures while other specialists investigate clinical guidance and regional policies. It has already retrieved a ministry report when its statistics source times out. Its source adapter performs the permitted local attempts while preserving that report.

The attempts fail, so the specialist returns the source timeout, exact query, attempt history, partial finding, and alternatives. It does not restart every investigation or silently switch the assignment to a different country. The coordinator evaluates the missing figures against the whole research goal.

First, it assigns separate country queries instead of the failed combined query. If the source remains inaccessible, it considers direct analysis of the retrieved ministry report as an alternate route. If neither route supplies the missing figures within the job’s constraints, it accepts partial completion and requires a named coverage gap.

The coordinator keeps the successful clinical and policy findings throughout. Its choice concerns the unresolved statistics slice. If the interruption instead ends the Claude Code subagent run itself, it treats the returned cut-off note or API failure as incomplete work and evaluates any surviving output before resuming or reassigning the task.

Common exam traps

• Escalating every transient source interruption before local recovery.
• Retrying indefinitely instead of returning an exhausted recovery report.
• Treating a completed zero-match search as a network failure.
• Assuming Python max_retries configures arbitrary source tools.
• Restarting all specialists after one source fails.
• Letting a specialist silently narrow the deliverable instead of having the coordinator choose partial completion.

What to remember

Keep bounded transient recovery close to the failed operation. Preserve completed work, report exhausted attempts, and let the coordinator choose query revision, another source, or qualified partial delivery. Distinguish source-tool recovery from API SDK retries and Claude Code’s reporting of interrupted subagent runs.

Knowledge check

References

• Anthropic, How we built our multi-agent research system.
• Anthropic, Subagents in the SDK.
• Anthropic, Handle tool calls.
• Anthropic, Python SDK.
• Anthropic, Create custom subagents.
• Anthropic, Model configuration.