Forking Sessions and Handling Stale Context

1.fork_session: branching from a shared baseline

Suppose an agent has spent a session analyzing a codebase, and you now want to try two different approaches from that same starting point, such as two testing strategies or two refactoring plans. If you resumed the session twice in a row, the second attempt would inherit everything the first one did. A fork solves this. In the SDK you pass resume with the baseline session's ID together with fork_session=True (forkSession: true in TypeScript). The run then starts with the full baseline history but writes to a new session that gets its own ID.

    # Fork: branch from session_id into a new session
    forked_id = None
    try:
        async for message in query(
            prompt="Instead of JWT, outline how OAuth2 would work for the auth module",
            options=ClaudeAgentOptions(
                resume=session_id,
                 ? =True,
                max_turns=5,
            ),
        ):

    # Original session is untouched; resuming it continues the JWT thread
    try:
        async for message in query(
            prompt="Continue with the JWT approach",
            options=ClaudeAgentOptions(resume=session_id),
        ):

Behind the scenes, forking copies the transcript into a new file and remaps the message IDs, leaving the original alone. The session-browser cookbook also offers a standalone fork_session() function that writes the fork to disk without running the agent; you start the fork later by passing its ID to resume. The function takes up_to_message_id, which branches from a chosen point in the conversation instead of the end. Because each fork is a separate session, you can explore extract-service in one branch and strangler-fig in another, and each starts from the same analysis without seeing the other.

Sources123

2.Stale tool results after code changes

Resuming is meant to save work. The agent picks up its earlier analysis without re-reading files, and that is exactly the risk. A resumed Claude Code session reloads the full history, tool results included. So if the agent read config.ts last Tuesday and someone has rewritten it since, the old file contents are still in its context, and nothing in the history says they are out of date. The agent will reason from the version it saw.

The fix uses the one new input a resume accepts: the prompt you send with it. The SDK example shows resume=session_id together with a new instruction, and the CLI claude -r "<session>" "query" form works the same way. If you name the files that changed and what changed in them, the agent can re-read just those files and keep the rest of its analysis, instead of exploring the whole codebase again. The documentation doesn't describe a dedicated flag or automatic step for this. It is a matter of writing the right prompt, and that follows from the fact that the replayed history can't announce its own staleness.

Sources14

3.Resume, resume from summary, or start fresh

So the choice depends on how much of the earlier context is still true. If most of it holds, resume and point out the few changes. If much of it is outdated, start a new session and inject a structured summary. You capture the conclusions that are still valid (analysis output, decisions, diffs) as application state and pass them into the new session's prompt. The model then works from accurate, compact context instead of a long history full of outdated tool output. Length matters too, because context behaves like a finite resource. Anthropic's context-engineering guidance notes that recall gets worse as the token count grows.

Claude Code also has a middle option. When you resume a long session, a dialog can offer Resume from summary. That runs /compact immediately and replaces the history with a summary, your most recent exchanges, and up to five recently read files. The alternative, Resume full session as-is, loads everything unchanged.

Sources145

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Work done in a forked session also changes the original session's history.Why is that wrong?

   A fork is a separate session with its own ID. The original stays as it was and can be resumed on its own thread.

   Covered in fork_session: branching from a shared baseline

2. 2.Resuming is always the safest choice because it keeps every earlier tool result.Why is that wrong?

   Keeping every tool result is the problem once files have changed. A fresh session seeded with the results you captured avoids carrying stale reads forward.

   Covered in Resume, resume from summary, or start fresh

Practise it for real

Run one analysis, then compare two follow-up approaches from it using the Agent SDK, without either one affecting the baseline.

1. 1.Run query() with allowed_tools=["Read", "Glob", "Grep"] and the prompt "Analyze the auth module and suggest improvements", saving message.session_id from the ResultMessage.

   Why: You need the baseline session's ID before you can resume it or fork from it.

   You should see: The run prints a session ID along with the analysis result.

2. 2.Run a second query() with resume=session_id, fork_session=True, max_turns=5 and the prompt "Instead of JWT, outline how OAuth2 would work for the auth module", saving its session_id as forked_id.

   Why: fork_session starts a new session from the baseline history instead of adding to it.

   You should see: forked_id is different from session_id.

3. 3.Run a third query() with only resume=session_id and the prompt "Continue with the JWT approach".

   Why: This shows the original thread is still intact after the fork.

   You should see: The agent continues the JWT plan and makes no mention of the OAuth2 outline.