Skip to lesson

AnthropicClaude Certified Architect – Foundations2026-101.7 Manage session state, resumption, and forking

Fork peer sessions from one shared baseline

Completed by the knowledge check

Learning objective

Branch a shared session baseline into independent alternatives with --resume ... --fork-session or the SDK’s fork_session.

Core idea

When an investigation reaches a useful common baseline, preserve it before exploring divergent approaches. A session fork copies the original conversation history into a session with its own ID. Each alternative can then add its own analysis without changing the original transcript.

For an architect comparing designs, that shared starting point matters. Both alternatives inherit the same discovered constraints, file observations, and rejected hypotheses. Their prompts can focus on the question that differs instead of repeating the common investigation. The original remains available if neither alternative succeeds.

The independence applies to conversation history. Forking does not copy the filesystem. Two forked sessions in one directory can still affect the same files. See 1.3.7 for choosing a fork versus a fresh specialist; this lesson focuses on constructing and returning to several alternatives from one session baseline.

How it works

Branch explicitly in Claude Code

From the shell, pair --resume with --fork-session to select the baseline and create a different session ID:

claude --resume auth-analysis --fork-session

Here, auth-analysis is the name of your saved baseline. You can supply its session ID instead. --fork-session also works with --continue, but explicit --resume avoids selecting an unrelated most recent conversation. After entering the fork, use /rename contract-test-alternative to make the alternative easy to find.

For a second alternative, fork the original auth-analysis baseline again. Do not fork the first alternative if the comparison is supposed to start from the same analysis: that would also inherit the first alternative’s subsequent reasoning. The fork point determines which observations and assumptions the alternatives share.

The fork point determines which observations and assumptions the alternatives shareRead the two groups side by side. Forking the original baseline again gives both alternatives the same starting analysis. Forking the first alternative instead makes the second alternative inherit the first alternative's subsequent reasoning.Fork the first alternativeFork the baseline againinherits subsequent reasoningOriginal baselineFirst alternativeSecond alternativeOriginal baselineFirst alternativeSecond alternative

Inside an active Claude Code session, /branch contract-test-alternative copies the conversation so far and switches the running process into that branch. Its confirmation prints the branch’s session ID and the original ID. Return to the original through /resume by its name or ID. The original remains unchanged on disk and appears separately in the session picker.

Use the language-specific SDK option

See 1.3.7 for the SDK mechanics, expressed by these Python and TypeScript options fragments respectively:

ClaudeAgentOptions(resume=BASELINE_ID, fork_session=True)
{ resume: baselineId, forkSession: true }

BASELINE_ID and baselineId represent the captured ID of the same baseline in Python and TypeScript respectively. To create two peers, make two separate query() calls with their respective prompts and those fork options, each resuming the original baseline ID. The calls need separate returned IDs for later follow-ups.

Capture each fork’s session_id as described in 1.7.1. Save the mapping between the alternative and its returned ID; the baseline’s ID still identifies the original history. To continue an existing alternative, pass its ID through resume without setting the fork option again. Setting it again creates another branch rather than continuing that alternative.

Distinguish transcript independence from workspace independence

See 1.3.7 for the rule that session forks separate history rather than files. For a design comparison, keep exploration read-only: have each prompt request an analysis or proposed patch rather than applied edits. In both SDKs, the tools option restricts the built-in tools to the ones it names, as --tools does on the CLI. A tool list such as ["Read", "Glob", "Grep"] supports inspection without exposing the built-in editing tools. Naming Glob and Grep in tools also restores those tools on macOS, Linux, and WSL, where they are absent from the default tool set. Tool availability and permission pre-approval are distinct; see 0.6. Do not treat allowed_tools or allowedTools alone as the restriction.

If the alternatives require applied changes, use separate checkouts as the workspaces and set each SDK call’s cwd accordingly. Choose that workspace arrangement before permitting edits so each trial can evaluate its own implementation against the common baseline.

Account for the way you create the branch

/branch switches the existing process to a copied transcript. Session permission grants carry over because the process remains the same. With --fork-session in a separate process, those grants do not carry over; you re-approve there.

In-flight background subagents and Bash commands also keep running after /branch, and their output enters the branch you switched into. Do not interpret an interactive branch as a frozen copy of all running work. For a clean comparison baseline, finish the common investigation before branching and identify which completed observations support both alternatives.

Key distinctions and trade-offs

Resume versus fork: Resume adds to the selected conversation. Fork creates a different conversation seeded with the selected history.

Peer branches versus nested branches: Forking twice from one baseline gives two peers. Forking the second from the first carries the first alternative’s extra analysis into the second.

History separation versus file separation: Separate session IDs prevent subsequent conversation messages from becoming one history. They do not prevent shared-directory edits from changing the evidence another session encounters.

Forking preserves a rich baseline with little restatement, but it also copies the baseline’s assumptions. If those assumptions or tool results are already stale, both branches inherit the problem. Repair or replace that context using the decision in 1.7.3 before treating the alternatives as comparable.

Architecture / decision scenario

A Claude Code investigation maps an authentication service’s timeout behavior and identifies two testing strategies: contract tests around the refresh interface and end-to-end tests through the login flow. The architect names the completed analysis auth-analysis and preserves it as the common baseline.

The architect runs claude --resume auth-analysis --fork-session, names the branch contract-test-alternative, and requests an unapplied test design. A second invocation resumes and forks auth-analysis again for an end-to-end design. Each must evaluate the same timeout cases and report coverage gaps, setup costs, and failure evidence.

In an Agent SDK service, the equivalent calls use resume=BASELINE_ID, fork_session=True in Python or resume: baselineId, forkSession: true in TypeScript. The service captures two returned session_id values and resumes each alternative by its own ID for follow-up questions. It limits inspection calls through tools while comparing proposals.

If implementation trials become necessary, the architect places them in separate checkouts. Running both edits in the baseline’s directory would compromise the comparison despite independent session histories. The original baseline remains available for synthesis and for a third alternative if both proposals have unacceptable gaps.

Common exam traps

Avoid these branch-management mistakes:

  • Resuming the same session in two terminals and expecting independent histories; Claude Code interleaves their messages into one transcript.
  • Forking the second alternative from the first and still calling them peers.
  • Comparing strategies in two new sessions, each rebuilding its own analysis, so the alternatives no longer share one baseline.
  • Saving only the baseline ID and losing the returned IDs that identify the alternatives.
  • Forking an alternative again when the intent is to continue it.
  • Assuming a fork copies files, rolls back edits, or refreshes inherited tool results.
  • Treating allowedTools as a replacement for the tools availability restriction.

Where the exam guide differs

Note:

The exam guide names fork_session for “creating independent branches from a shared analysis baseline” and “parallel exploration branches”. fork_session is the Python Agent SDK spelling; TypeScript uses forkSession, and Claude Code uses --fork-session with --resume or --continue, or /branch inside a session. The independence the product documents is the conversation history’s: forking branches the conversation, not the filesystem, so a forked agent’s edits are real and visible to any session working in the same directory. In an exam item, read any of these spellings as the session fork, and reject an option that relies on a fork alone to keep two trials’ file edits apart.

What to remember

Fork each peer from the same baseline, capture each returned ID, and resume the selected peer for follow-up. Conversation history separates through --fork-session, Python’s fork_session, or TypeScript’s forkSession. File independence requires a separate workspace decision.

Knowledge check

References