AnthropicClaude Certified Architect – Foundations2026-101.3 Configure subagent invocation, context passing, and spawning
Choose a fork or a fresh specialist
Completed by the knowledge check
Learning objective
Distinguish forking a session from an existing history baseline (fork_session) from spawning a fresh subagent with isolated context.
Core idea
For an architect exploring alternative approaches, choose the starting context deliberately. A session fork copies an existing conversation into a separate session, so a branch can build on the shared analysis without extending the original history. A fresh subagent starts its own conversation and receives the assignment you explicitly supply.
These are different ways to distribute context. A fork is useful when the history itself is the required baseline. A fresh specialist is useful when a bounded prompt can provide everything the assignment needs. Neither choice, by itself, creates an isolated copy of files or automatically combines the resulting conclusions.
How it works
Fork an SDK session from its history
The Agent SDK’s session guide documents forking with query() options. In Python, use ClaudeAgentOptions(resume=SESSION_ID, fork_session=True). In TypeScript, use options: { resume: sessionId, forkSession: true }. The language-specific spelling matters: the objective names Python’s fork_session, while the TypeScript option is forkSession.
resume identifies the existing session whose history becomes the baseline. With the fork option enabled, the SDK creates a separate session ID rather than appending to the original session. Capture the branch’s session_id from its result message. You then have two independently resumable histories: the original baseline and the divergent branch.
The session guide says session_id appears on every result message, whether the result is success or error. Connection or process failures can produce no result message, so handle the absence of an ID rather than inventing one.
Distinguish a fork from an ordinary resume
resume without a fork continues the identified session and adds to its history. This is appropriate when you want the next turn of the same investigation. resume with the fork option creates a branch for an alternative direction while preserving the source conversation.
Suppose a coordinator has analyzed two authentication approaches and developed one proposal. Resuming the original session to examine the alternative changes the ongoing thread. Forking at that baseline lets you explore the alternative in a separate history while leaving the first proposal’s thread available for later continuation.
If the baseline is earlier than the session’s last message, Python’s resume_session_at loads history up to and including the specified message UUID. Use it with resume and fork_session=True to branch from that point; it requires Python Agent SDK v0.2.137 or later.
Label the IDs by purpose: resume the branch ID for branch-specific follow-up and the original ID for baseline work. The ID passed to resume, not a task label or agent role, identifies which history you extend.
The SDK also documents transcript-copying helpers named fork_session() in Python and forkSession() in TypeScript. Those functions copy a transcript and return a fork result; the similarly named boolean query options fork when resuming. For this objective’s execution pattern, pair the boolean option with resume. Do not confuse a callable helper with the option field or assume calling the helper runs an investigation.
Spawn a fresh specialist with explicit input
Define a specialist through the SDK’s agents option and AgentDefinition, then have the coordinator invoke it through Agent. An ordinary, non-fork subagent starts with no parent conversation history. It receives its own AgentDefinition.prompt and the Agent call’s prompt. Put the specific question, necessary decisions, and prior findings into that assignment; see 1.3.3 for the complete context contract.
Fresh does not mean empty: tool definitions and project instructions still load under the SDK’s settings rules (see 1.2.1). What the specialist lacks is the parent’s conversation and tool results, so the assignment names the relevant baseline rather than “what we already discussed.”
Intermediate subagent tool calls and results remain inside the specialist’s conversation, and its final report returns to the parent. This keeps a narrow investigation from adding every search and file read to the coordinator’s context. Use the evidence handoff from 1.3.4 when the next decision needs supporting content rather than only a conclusion.
Account for forked subagents too
The product documentation makes an explicit exception to fresh subagent context: a forked subagent inherits the parent conversation. With fork mode on, Claude Code can request the fork subagent type through the Agent tool. Its documentation describes the inherited system prompt, tools, model, and message history, while the fork’s subsequent tool calls remain separate and only its final result returns.
Fork mode is on by default in interactive Claude Code v2.1.232 or later and off by default in non-interactive mode with -p and in the Agent SDK. An SDK application enables it by setting CLAUDE_CODE_FORK_SUBAGENT to "1" through the env option; see 1.3.3. This setting controls Agent-based forks, not the session fork option paired with resume.
This forked-subagent mechanism is distinct from the application creating a separately resumable SDK session through resume and fork_session or forkSession. Both copy a history baseline, but they occupy different control paths. Treat “subagent” alone as insufficient evidence of fresh context; determine whether the invocation is an ordinary specialist or a fork.
Key distinctions and trade-offs
The documented mechanisms differ in their context and continuation behavior:
| Mechanism | Starting context | Intended continuation |
|---|---|---|
resume alone | Identified session history | Extend the same session |
resume plus fork option | Copy of identified session history | Explore a separately identified branch |
| Two forks of the same session ID | Two copies of one unchanged baseline | Compare two alternatives side by side |
Fresh Agent specialist | Own prompt and explicit assignment, without parent history | Return focused findings to the coordinator |
Agent with fork subagent type, fork mode on | Parent conversation baseline | Return a side investigation’s final result |
Copying history preserves background but also carries assumptions and irrelevant content. A fresh specialist can receive a more selective assignment, at the cost of explicitly assembling the context. Choose based on the inputs the investigation needs, rather than treating forks as universally better delegation.
Sessions persist conversation, not filesystem snapshots. The session guide explicitly warns that file edits made by a fork are real and visible to sessions working in the same directory. Use file checkpointing when the requirement is to snapshot and revert edits; do not assume fork_session creates repository isolation. A separate conversation is not a separate checkout.
Architecture / decision scenario
A developer-productivity agent analyzes an authentication module and records a shared analysis baseline. The team wants to compare two refactoring approaches without losing that baseline. The application captures the original session_id and launches a Python query with resume set to that ID and fork_session=True to investigate the alternative. It records the branch ID separately.
The application resumes the original ID to continue the first approach. Each history can now receive its own follow-up without appending to the other. The assignments ask for analysis, since both sessions use the same working directory and a conversation fork does not protect their files from competing edits.
A separate specialist only needs to assess one function against an explicit requirement. The coordinator invokes a fresh Agent subagent with that requirement, the relevant file location, and the needed findings. Copying the whole authentication discussion would add unrelated assumptions. The specialist returns its report, which the coordinator uses when comparing the two approaches.
If the application has set CLAUDE_CODE_FORK_SUBAGENT=1 and the coordinator chooses a fork subagent because the side task requires the entire discussion, it recognizes the inherited-history exception. The final comparison names which branch or specialist produced each finding rather than assuming the independent histories merged themselves.
Common exam traps
- Treating
resumealone as a branch that preserves the original history unchanged. - Using Python’s
fork_sessionspelling as the TypeScript query option. - Expecting a fresh specialist to receive the parent’s analysis automatically.
- Equating session-history branching with filesystem isolation or rollback.
- Confusing a transcript-copying helper function with the boolean query option.
- Applying the exam guide’s isolation statement to the documented
forksubagent exception.
Where the exam guide differs
The exam guide states that subagents “do not automatically inherit parent context” and names “fork-based session management” as the way to explore divergent approaches from a shared analysis baseline; it does not mention the fork subagent type. The product has both mechanisms. The SDK session fork, resume with fork_session=True in Python or forkSession: true in TypeScript, creates a separately resumable session. Claude Code’s fork subagent inherits the parent’s conversation, and interactive Claude Code turns fork mode on by default from v2.1.232. In an exam item about divergent approaches from one baseline, choose the session fork, and read “subagent” as a fresh specialist that starts without the parent’s conversation.
What to remember
Fork an existing SDK session with resume plus Python’s fork_session=True or TypeScript’s forkSession: true, and track the resulting session ID. Spawn a fresh specialist when an explicit, bounded assignment is enough. Qualify isolation claims for forked subagents, and treat conversation history separately from file state.
Knowledge check
An Agent SDK session holds a finished analysis of an authentication module. The team wants to explore two refactoring approaches, each building on that full history, with separate conversation histories and without redoing the analysis. Which approach fits?
resume with fork_session=True in Python or forkSession: true in TypeScript — starts from a copy of the same history under its own session ID, and the original stays unchanged. Resuming twice appends to one history, so the second approach sees the first; a summary loses the full baseline; and running both in one session mixes them.Two forks of an analysis session each apply a different refactoring in the same working directory. Afterwards, the original session’s next turn finds files changed by both forks. What explains this?
During a long authentication discussion, a coordinator needs one function checked against a single stated requirement. The check needs only the requirement, the file location, and two prior findings, and the discussion’s other assumptions must not influence it. Which mechanism fits?
resume and the fork option, then run the checkfork subagent type through Agent for the checkAgent with an explicit assignmentfork subagent both copy the whole discussion, and resuming the session adds the check to the same history.In interactive Claude Code v2.1.232, an architect assumes every subagent starts with nothing from the parent conversation. A side investigation is spawned with the fork subagent type. What does it start with?
References
- Anthropic, Session management
- Anthropic, Subagents in the SDK
- Anthropic, Create custom subagents
- Anthropic, Python SDK reference
- Anthropic, TypeScript SDK reference
- Anthropic, Claude Certified Architect – Foundations Exam Guide