AnthropicClaude Certified Architect – Foundations2026-105.4 Manage context effectively in large codebase exploration
Restore investigations from indexed worker state
Completed by the knowledge check
Learning objective
Restore interrupted multi-agent investigations from per-agent state exports and a coordinator-readable manifest.
Core idea
An architect designing a multi-agent codebase investigation needs recovery information that remains usable when the running process is gone. Give each worker a known state-export path, persist verified progress at checkpoints, and maintain a manifest that tells the coordinator where those exports are and which tasks still need work.
The CCAR-F exam guide describes structured agent state exports and a manifest loaded on resume. These are structures you design, not a built-in Claude Code recovery schema. Claude Code and the Agent SDK provide tools, lifecycle hooks, and saved sessions that can support the design. Your application owns the meaning of a finished task and the information injected into replacement workers.
See 5.4.2 for file-specific findings and 5.4.4 for phase handoffs. This lesson adds a recovery index and task state so an interrupted run can reuse accepted results and continue from verified checkpoints.
How it works
Define the export location before starting
Assign each writing-capable worker a path such as investigation/state/refund-tracer.json. Include that path in its task prompt along with the instruction to update it after meaningful discoveries. A fresh worker should not have to infer where an interrupted predecessor stored its work.
The export should preserve the assigned question, verified findings with source locations, files covered, unresolved dependencies, and the next investigation step. Include the evidence baseline so recovery can detect when code changed after a checkpoint. These are application-defined fields; their names do not configure an SDK feature.
Save progress during the investigation rather than waiting for a final report. A completion callback cannot preserve intermediate findings if the process ends before completion. Choose persistence ownership as described in 5.4.2 so the assigned worker or coordinator can save the checkpoint.
Index exports in a coordinator manifest
The manifest is a small application-owned index, for example investigation/manifest.json. Keep a task identifier, assigned question, recovery status, state-export path, and phase-summary path. An agent identifier or SDK session ID can be supplementary information; neither replaces the export’s verified findings.
Use explicit statuses that the coordinator can interpret. The following names illustrate a recovery design rather than Anthropic enum values:
| Example status | What must be true | Recovery action |
|---|---|---|
done | The accepted result is available at its recorded path | Load the result and reuse it if the evidence remains valid |
in_progress | A saved checkpoint describes partially completed work | Load and verify that checkpoint, then continue the unresolved scope |
pending | No worker has established a result for the task | Start with the phase summary and original assignment |
needs_verification | The export is missing, unreadable, or inconsistent with the evidence baseline | Verify or reconstruct the affected task before trusting its result |
Keep done tied to an accepted result, not merely a stopped agent. The task can be incomplete even when the worker has finished responding. Publish the result file before changing the manifest to the status that tells recovery to skip work; otherwise the index can point to a result that was never saved.
Use lifecycle hooks as integration points
Claude Code’s SubagentStart hook receives agent_id and agent_type, alongside common fields such as session_id and cwd. A tracking script can use those identifiers to record the worker associated with a task. Your application must still map that worker to the task and state-export path; an agent type alone is not a unique task assignment.
SubagentStart also fires on resumption, so reconcile an existing worker with its task rather than adding duplicate work. SubagentStop can fire for internal agents such as prompt suggestions and /btw, whose agent_type can be empty. Use a matcher naming your investigation’s worker types to keep those unrelated events out of the manifest tracker.
SubagentStop provides agent_id, agent_type, and agent_transcript_path. Its common transcript_path refers to the main session, so use agent_transcript_path when archiving the worker’s transcript. The Agent SDK exposes SubagentStart and SubagentStop in both Python and TypeScript through the hooks option. Python examples use HookMatcher; TypeScript uses hook matcher objects with callback arrays.
Do not assume last_assistant_message always contains the delivered report. On Claude Code v2.1.271 or later, SubagentHandback is provided only in auto mode to local non-fork subagents run by the Agent tool. For workers using that tool, the report is its message input, available as tool_input.message to a PreToolUse or PostToolUse hook matched on SubagentHandback; last_assistant_message can instead be closing text. Without that tool, last_assistant_message contains the final response text. Prefer the explicit state export as your recovery contract and treat transcripts as supporting evidence.
These hooks track starts and normal response completion. They do not replace periodic worker checkpoints. A sudden interruption can leave the manifest at in_progress, which is why it needs a usable state file rather than a promise to write one at the end.
Load, validate, and inject on recovery
After an interruption, the coordinator loads the manifest first. It verifies that referenced exports exist and that the findings still match the code baseline. It then loads accepted results for finished tasks, prepares continuation prompts for unfinished tasks, and starts pending tasks with the relevant phase summary.
A replacement worker receives the original assignment, verified completed scope, source pointers, unresolved questions, and next step. Ask it to continue the uncovered portion, not to repeat the whole repository survey. See 5.4.4 for constructing that prompt without copying the interrupted transcript.
Saved Agent SDK conversations provide another recovery option. Capture session_id from a result message and use the resume option on query() to resume that specific session. Process or connection failures can yield no result message. Capture the ID earlier from the init SystemMessage: TypeScript exposes session_id directly, while Python nests it inside SystemMessage.data. Do not expect a final result after a crash.
Sessions persist conversation history, not the filesystem. Resumption needs the saved transcript to remain available, while an export-based restart can supply selected findings to a fresh worker. See 1.7.1 for session resumption and 1.7.3 for deciding whether saved evidence is stale. Choose history continuation when it remains useful; choose a verified state handoff when you want to avoid inheriting discovery noise.
Key distinctions and trade-offs
State export versus transcript: The export is a selected record of verified progress and remaining scope. A transcript contains the conversation and intermediate operations that produced it.
Manifest versus worker evidence: The manifest tells the coordinator what to load and what action to consider. The export provides the findings that justify that action.
Worker stopped versus task complete: A lifecycle event identifies response completion. Application acceptance determines whether recovery can reuse the task’s result.
Frequent checkpoints reduce lost progress but add writes and maintenance. Checkpoint at meaningful investigation boundaries, keeping enough evidence to recover without turning every tool response into another durable artifact.
Architecture / decision scenario
A developer productivity tool is investigating a legacy refund system with three workers. The manifest records test discovery as done, ledger caller tracing as in_progress, and allocation coverage as pending. Each task has a known export path and the same verified phase-summary baseline.
The process is interrupted. On restart, the coordinator reads the manifest and confirms that the completed test inventory is present and still valid. It reuses that result. The ledger worker’s export records verified route callers and an unresolved scheduled-job directory, so the replacement receives those findings and continues with the jobs. The allocation worker starts from the phase summary because it has no previous progress.
If the ledger export is missing, the coordinator marks that task for verification rather than treating in_progress as evidence of completed discoveries. If its saved SDK session remains available and useful, the coordinator can resume it instead of creating a replacement. The manifest still supplies task ownership and acceptance state.
Common exam traps
- Restarting every investigation because one process stopped.
- Saving worker state only after the worker finishes.
- Treating example manifest statuses as SDK-defined values.
- Equating
SubagentStopwith an accepted task result. - Archiving the main
transcript_pathwhen the required evidence is the worker’s transcript. - Assuming a session ID restores files or guarantees a usable export.
What to remember
Persist worker progress at known paths, index it in a manifest, and load that manifest before redispatching work. Reuse validated completed results, inject verified checkpoints into unfinished tasks, and investigate missing or stale exports explicitly. Hooks and saved sessions support recovery; your application owns its state contract.
Knowledge check
A coordinator runs eight exploration workers over several hours. The process crashes after five of them have finished. How should the run have been designed so it can recover?
A tracker marks a task done in the manifest whenever SubagentStop fires for its worker. After an interruption, one done task has no result file at its recorded path. What should change?
done only after the accepted result is saved at the recorded pathdone on SubagentStart and clear it if the worker later failslast_assistant_message as the result whenever SubagentStop firestranscript_path as the result when the worker stopsSubagentStart marks work that has not even begun. last_assistant_message can be closing text rather than the delivered report, and transcript_path points at the main session.A SubagentStop hook archives each worker’s transcript as supporting evidence, but every archive contains the main session’s conversation. Which input field should the hook read?
transcript_path , after matching the hook on each worker’s agent typesession_id , after resolving it to that session’s saved transcript filelast_assistant_message , after writing it to the archive folderagent_transcript_path , after matching the hook on each worker’s agent typeSubagentStop receives agent_transcript_path for the subagent’s own transcript, while the common transcript_path refers to the main session whatever the matcher. last_assistant_message holds only final text, not the transcript.An Agent SDK application resumes interrupted workers with the resume option, reading each session_id from the final result message. After a process crash, no session ID is available for the workers that were running. What should the application change?
SystemMessage — a direct field in TypeScript, nested in SystemMessage.data in Python. Sessions persist conversation history, not the filesystem, so resuming restores no file changes.References
- Anthropic, Claude Certified Architect – Foundations Exam Guide
- Anthropic, Hooks reference
- Anthropic, Control execution with hooks
- Anthropic, Work with sessions
- Anthropic, Create custom subagents
- Anthropic, Tools reference