fork_session
Agent SDKDefinition
An Agent SDK operation that creates a copy of the current session state, allowing parallel exploration of different solution paths without affecting the original session. Each fork can proceed independently; results can be compared and the best chosen.
Example Usage
Fork the session before attempting a risky refactoring to preserve a safe rollback point while exploring the approach.
Why It Matters for the CCA-F Exam
Domain 1 tests `fork_session` in two ways: (1) scenario questions where the correct answer is to fork before attempting a risky multi-step operation, and (2) distractor questions that conflate forking with subagent delegation via the Task tool. Know the difference cold.
In Depth
fork_session is an Agent SDK operation that creates a copy of the current session state — conversation history, tool results, accumulated context — and returns a new independent session branching from that snapshot. The original session is unmodified. Both the original and the fork can proceed independently, running different strategies against the same starting state. When both are done, the orchestrator can compare results and commit the better outcome.
The primary use case is parallel exploration under uncertainty: when there are two or more plausible approaches to a complex task — say, a risky database refactoring — fork the session before attempting either, then run each approach in its forked copy. If one fork produces errors or regressions, the original session is a clean rollback point. This is safer than attempting approaches sequentially in the same session, where early tool side effects can corrupt later reasoning.
A second use case is A/B evaluation: fork the same session state and vary a single parameter (system prompt phrasing, model tier, reasoning depth) across forks. Because both forks start from identical history, differences in output are attributable to the variation, not to context drift. See Session State & Resumption for how session state is structured and persisted.
Critical exam distinction: fork_session is not the Task tool. Both create new agent contexts, but the semantics differ. The Task Tool creates a fully independent subagent with no session relationship to the caller — it is delegation. fork_session creates a branched continuation of the *same logical task*, sharing provenance with the original. The forked session "knows" where it came from; a subagent does not.
Also note: forking does not duplicate external state. If the session involved tool calls that wrote to a database, those writes are real in both the original and the fork. fork_session copies the *context window representation* of what happened, not external side effects. Architects must account for this when designing fork-based recovery strategies.
How It Compares
| Dimension | `fork_session` | Task Tool (Subagent) |
|---|---|---|
| Purpose | Parallel exploration / safe rollback | Delegating a bounded subtask |
| Relationship to parent | Branch of same session; shares provenance | Fully independent; no session relationship |
| Context at start | Full copy of current session history | Only what orchestrator passes in the task prompt |
| Typical use | Try risky approach A vs. B; pick best | Delegate "search papers" to a subagent |
| Session state after | Two live sessions; original unmodified | One tool_result back in orchestrator context |
| External side-effect safety | Forks share real side effects (DB writes, etc.) | Subagent operates in scoped tool set |
Frequently Asked Questions
Does fork_session copy external state like database records?
No. `fork_session` copies the in-memory session context — the conversation history and tool results the model can see. External side effects (file writes, database mutations, API calls that already fired) are real in the world and are not rolled back or duplicated by forking. If external rollback matters, use transactions at the storage layer separately.
Can I run both the original and a fork concurrently?
Yes. Both are independent session objects after the fork. You can hand them to concurrent agent runs and then compare their results. This is exactly the parallel exploration pattern the operation is designed for.
If I want a safe rollback point, should I fork or use a subagent?
Fork. A subagent is for delegation — it starts fresh and its results come back as a tool_result. A fork is a copy of your current progress, so you can explore a risky path in the fork while the original is preserved as a checkpoint. If the fork goes wrong, discard it and continue from the original.