Session State and Resumption

Official Exam Guide Objectives

Task 1.7: Manage session state, resumption, and forking.

Knowledge of

• Named session resumption using --resume <session-name> to continue a specific prior conversation
• fork_session for creating independent branches from a shared analysis baseline to explore divergent approaches
• The importance of informing the agent about changes to previously analyzed files when resuming sessions after code modifications
• Why starting a new session with a structured summary is more reliable than resuming with stale tool results

Skills in

• Using --resume with session names to continue named investigation sessions across work sessions
• Using fork_session to create parallel exploration branches (e.g., comparing two testing strategies or refactoring approaches from a shared codebase analysis)
• Choosing between session resumption (when prior context is mostly valid) and starting fresh with injected summaries (when prior tool results are stale)
• Informing a resumed session about specific file changes for targeted re-analysis rather than requiring full re-exploration

What You Need to Know

How an agent picks work back up after a gap is a design decision, not a detail. Anything that runs across several sittings — chasing a bug through a large system, working through a codebase, research spread over days — leaves behind an accumulation: files that were read, conclusions that were drawn, chains of reasoning that led to them. This task statement is about what to do with that accumulation, and there are exactly three answers: carry it forward, split it, or set it aside and rebuild.

Three Session Management Options

Three mechanisms exist across the Agent SDK and Claude Code. They are not interchangeable — each answers a different question about the accumulated state — and the exam presents scenarios that make exactly one of them correct.

Option 1: --resume <session-name>

Resume reopens a named session exactly as it was left, with the full conversation restored — every tool result, every analysis, every chain of reasoning still present.

When to use: What the session already knows is still true. The files it read have not moved on since, and continuing costs less than rebuilding the understanding.

When NOT to use: Files have changed since the session was last active. The tool results sitting in that history now describe a codebase that no longer exists, which produces the stale context problem below.

Option 2: fork_session

Fork takes an existing session as a starting point and splits off an independent line from it. Past the branch point the two sides are unaware of each other: neither observes the other's results and neither is affected by the other's work.

When to use: The expensive groundwork is already done and you want to try more than one direction from it. Having analysed a codebase, fork to weigh two refactoring strategies against each other — both inherit the same understanding and diverge from there.

When NOT to use: You only want to carry on. Fork exists to compare alternatives, so using it for straightforward continuation creates a branch nobody needed. Resume is the continuation tool.

Option 3: Fresh start with summary injection

Open a new session carrying nothing, then seed it with a written summary of what the previous one established. No tool results come across — only the account you chose to write.

When to use: The old tool results have gone stale, because files changed, an API moved, or dependencies shifted. Also where a long session has silted up with results that no longer matter and the context would be better rebuilt than continued.

When NOT to use: The prior context is still accurate and you want the detail in it. Rebuilding by hand what resume restores for free is wasted effort.

The Stale Context Problem

This is the idea the whole task statement turns on. It arises when a session is reopened after the underlying files have moved on, leaving the agent to reason from cached reads that describe code as it used to be.

How it manifests: A developer works with Claude Code on a codebase, changes 3 files, and resumes. The advice that comes back contradicts itself — fixes are recommended for problems already solved, and code is discussed that no longer exists in the file.

Why it happens: Resuming restores everything, and everything includes each file's contents as they were when the tool read them. A file modified since is still represented in history by its old text, and the model reasons across both that record and anything read fresh, with nothing marking which is current.

The naive fix (and why it is insufficient): Resume, then ask the agent to re-read whatever changed. That improves matters without settling them: the outdated results are still in the history, so they remain available to be reasoned from — particularly on side questions where nobody thought to re-read anything.

The correct fix: Begin a new session and inject a structured summary of what was established, naming the files that have changed so those can be re-read deliberately. Nothing stale comes across, and the knowledge does.

Targeted Re-Analysis vs Full Re-Exploration

Changed files do not justify re-examining everything. Re-reading 50 files because 3 of them moved spends the session's budget re-establishing facts that never stopped being true.

The correct approach is targeted re-analysis: name the files that changed and let the agent re-examine only those. Everything else is already covered by the summary carried over from before.

What targeted re-analysis looks like in practice:

1. Start a fresh session.
2. Seed it with a written summary that states both halves: what the earlier work established, and which files have moved since — auth.ts, database.ts and api-routes.ts.
3. Only those three get re-read and re-examined.
4. The findings from that re-read are merged with the summary covering everything untouched.

It is quicker than starting over and safer than resuming, because the only material in context is either freshly read or deliberately written.

When to Use Each Option: Decision Matrix

Practical Example: The Contradictory Advice Bug

Two days of work across a codebase of 50 files. The first day covers the authentication module and turns up three problems. That evening all three are fixed, which means edits land in auth.ts, session.ts and middleware.ts.

Resuming on Day 2 produces recommendations to fix three issues that no longer exist, because the tool results describing the unfixed code were restored along with everything else. Asked directly about auth.ts, the answers alternate — sometimes describing the old version held in history, sometimes the current version just read — with no signal distinguishing the two.

The fix: start a fresh session with a summary. "Prior analysis identified three authentication issues in auth.ts, session.ts, and middleware.ts. All three have been fixed. Please re-analyse these three files to verify the fixes and check for any new issues introduced by the changes."

Nothing outdated exists in the new session to be reasoned from. The agent reads the files as they now stand, confirms the fixes, and gives advice that stays consistent because there is only one version of the truth in context.

Deep Dive

Where sessions actually live, and why resume can silently "fail"

A session is defined precisely: "the conversation history the SDK accumulates while your agent works. It contains your prompt, every tool call the agent made, every tool result, and every response. The SDK writes it to disk automatically so you can return to it later." Transcripts are stored as JSONL under a path keyed on the working directory: "sessions are stored under ~/.claude/projects/<encoded-cwd>/*.jsonl ... where <encoded-cwd> is the absolute working directory with every non-alphanumeric character replaced by -." This is documented as "the most common cause of resume returning a fresh session" — if you resume from a different working directory than the one the session was created in, the encoded path doesn't match and there's nothing to find.

Sourcecode.claude.com › sessionsfetched 2026-07-30

What a resumed session restores — the full list, and the two exceptions

Resume restores more than just messages: "conversation history: the full history, including tool calls and results" plus model, agent, permission mode, goals, and unexpired scheduled tasks. But permission mode has a documented carve-out: "permission mode: the mode the session was in. plan and bypassPermissions are never restored." A session that was in plan mode or bypassPermissions mode when it ended comes back in a different (safer) mode on resume — one more reason a resumed session's behaviour is not always identical to where you left it, beyond just stale tool results.

Sourcecode.claude.com › sessionsfetched 2026-07-30

Continue vs resume — the practical difference for automation

The two "keep working" options track state differently. The SDK sessions guide puts it plainly: "Continue finds the most recent session in the current directory. You don't track anything. ... Resume takes a specific session ID. You track the ID." The headless docs give the CLI form: "use --continue to continue the most recent conversation, or --resume with a session ID to continue a specific conversation." For a single interactive workflow, --continue is the low-friction choice. For scripted or multi-conversation automation, the docs recommend explicitly capturing the ID: "if you're running multiple conversations, capture the session ID to resume a specific one," typically via --output-format json and reading the session_id field from the result. That ID lookup is scoped to where you ran the command: "session ID lookup is scoped to the current project directory and its git worktrees," so a resume command run from a different directory than the original session won't find it.

Sourcescode.claude.com › headlesscode.claude.com › sessionsfetched 2026-07-30

Fork semantics, precisely

Forking is not a variant of resume — it is resume plus a divergence point. The SDK sessions guide: "forking creates a new session that starts with a copy of the original's history but diverges from that point. The fork gets its own session ID; the original's ID and history stay unchanged. You end up with two independent sessions you can resume separately." The Claude Code sessions doc says the same thing about /branch: "branching creates a copy of the conversation so far and switches you into it, leaving the original intact." Practically, "sessions created with /branch or --fork-session get their own session IDs and appear as separate rows" in the session picker — they are first-class, independently resumable sessions from the moment they're created, not temporary branches of the parent.

Sourcescode.claude.com › sessionscode.claude.com › sessionsfetched 2026-07-30

Sessions persist conversation, not files — checkpointing is the separate mechanism

A session captures conversation state only: "sessions persist the conversation, not the filesystem. To snapshot and revert file changes the agent made, use file checkpointing." Checkpointing runs on a different cadence — with checkpointing enabled, "each user message in the response stream has a UUID that serves as a checkpoint" — and has its own blind spot: "only changes made through the Write, Edit, and NotebookEdit tools are tracked. Changes made through Bash commands (like echo > file.txt or sed -i) are not captured by the checkpoint system," and neither are edits a subagent applies. This matters for the stale-context problem: even if you could perfectly "undo" file changes with /rewind, resuming the conversation afterward still carries whatever stale tool results were already in history — checkpointing reverts code, not what the model believes about the code. The checkpointing docs make the same point from the other side: "file rewinding restores files on disk to a previous state. It does not rewind the conversation itself."

Sourcescode.claude.com › sessionscode.claude.com › file-checkpointingfetched 2026-07-30

Capturing a session ID headlessly, for the resume-vs-fresh-summary decision

In scripted/CI usage, the documented pattern for tracking a session to resume later is to read its ID straight out of the JSON result: session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id'). This is the concrete mechanism behind choosing resume over fresh-start-with-summary in an automated pipeline — the script has to explicitly decide, per run, whether to pass that captured session_id to --resume (prior context still valid) or to start a new session with an injected summary (prior tool results are stale), exactly the decision rule from this lesson's "Three Session Management Options."

Sourcecode.claude.com › headlessfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Implement Session Management Strategies

Difficulty: Intermediate (2/4)

45 minutes

1. Create a Claude Code session that analyses a 10-file codebase and name it with --name for later resumption

Why: Named sessions resumed with --resume enable continuation of work across breaks. The exam tests when resume is appropriate (no files changed) versus when it creates the stale context problem (files have been modified since the last session).

You should see: A named Claude Code session that reads and analyses 10 source files. The session name should be memorable for later resumption. The agent should produce findings about each file.

2. Record the key findings from the initial analysis as a structured summary (file names, issues found, recommendations)

Why: This structured summary is the knowledge you will inject into the fresh session later. The exam tests whether you preserve prior findings without carrying stale tool results. A good summary captures conclusions without raw tool output.

You should see: A structured document listing each file name, the issues found in it, severity ratings, and specific recommendations. This should be concise enough to inject into a prompt but complete enough to preserve all key findings.

3. Modify 3 files in the codebase to fix some of the identified issues

Why: Modifying files after a session creates the conditions for stale context. The old file contents remain as tool results in the session history while the actual files now contain different code. This is the exact scenario that triggers the contradictory advice bug.

You should see: Three files modified with fixes for the issues identified in the initial analysis. The changes should be substantive enough that the old and new versions would produce different analysis results.

4. Attempt to resume the session with --resume and observe any stale context issues (contradictory advice, references to old code)

Why: This demonstrates the stale context problem. The resumed session contains old tool results showing the unfixed code. The agent may recommend fixing issues that are already fixed, or give contradictory advice by referencing both old and new file contents.

You should see: The agent giving contradictory advice: recommending fixes for issues already resolved, referencing code that no longer exists, or providing inconsistent guidance about the modified files. These are the hallmarks of stale context.

5. Start a fresh session with the structured summary injected into the initial prompt, specifying the 3 changed files for targeted re-analysis

Why: Fresh start with summary injection is the correct approach when files have changed. The exam specifically tests this: no stale tool results, preserved knowledge from the prior session, and targeted re-analysis of only the changed files instead of wasteful full re-exploration.

You should see: A clean session that knows about the prior findings (from the injected summary), targets only the 3 changed files for re-analysis, and produces consistent advice without contradictions.

6. Compare the quality and consistency of advice between the stale resume and the fresh start with targeted re-analysis

Why: This comparison demonstrates why the exam favours fresh start with summary injection over naive resume after file changes. The fresh start produces consistent, accurate advice while the resume produces contradictions from stale context.

You should see: A clear quality difference: the resume session gives contradictory or outdated advice about the modified files, while the fresh session gives accurate, consistent analysis based on the current file contents.

Sources

• Claude Code Documentation — Anthropic
• Claude Code in Action (Skilljar) — Anthropic
• Claude Agent SDK Overview — Anthropic
• Claude Agent SDK — Sessions — Anthropic
• Claude Code — Sessions — Anthropic
• Claude Code — Headless mode — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Create a Claude Code session that analyses a 10-file codebase and name it with --name for later resumption

Why: Named sessions resumed with --resume enable continuation of work across breaks. The exam tests when resume is appropriate (no files changed) versus when it creates the stale context problem (files have been modified since the last session).

You should see: A named Claude Code session that reads and analyses 10 source files. The session name should be memorable for later resumption. The agent should produce findings about each file.

Step 2. Record the key findings from the initial analysis as a structured summary (file names, issues found, recommendations)

Why: This structured summary is the knowledge you will inject into the fresh session later. The exam tests whether you preserve prior findings without carrying stale tool results. A good summary captures conclusions without raw tool output.

You should see: A structured document listing each file name, the issues found in it, severity ratings, and specific recommendations. This should be concise enough to inject into a prompt but complete enough to preserve all key findings.

# Session Summary: code-review-session

## Findings
- **auth.ts**: SQL injection in login query (critical), missing input validation (high)
- **database.ts**: Connection pool not closed on error (medium), no retry logic (low)
- **api-routes.ts**: No rate limiting on public endpoints (high), inconsistent error responses (medium)
- **utils.ts**: No issues found
...

## Key Recommendations
1. Fix SQL injection in auth.ts immediately
2. Add connection cleanup in database.ts error handlers
3. Implement rate limiting middleware for api-routes.ts

Step 3. Modify 3 files in the codebase to fix some of the identified issues

Why: Modifying files after a session creates the conditions for stale context. The old file contents remain as tool results in the session history while the actual files now contain different code. This is the exact scenario that triggers the contradictory advice bug.

You should see: Three files modified with fixes for the issues identified in the initial analysis. The changes should be substantive enough that the old and new versions would produce different analysis results.

# Example fixes to apply:
# auth.ts: Replace string concatenation with parameterised query
# database.ts: Add try/finally with pool.release() in error path
# api-routes.ts: Add rate limiting middleware to public endpoints

Step 4. Attempt to resume the session with --resume and observe any stale context issues (contradictory advice, references to old code)

Why: This demonstrates the stale context problem. The resumed session contains old tool results showing the unfixed code. The agent may recommend fixing issues that are already fixed, or give contradictory advice by referencing both old and new file contents.

You should see: The agent giving contradictory advice: recommending fixes for issues already resolved, referencing code that no longer exists, or providing inconsistent guidance about the modified files. These are the hallmarks of stale context.

claude --resume code-review-session "What is the current state of auth.ts? Are there still security issues that need fixing?"
# Watch for:
# - Recommending fixes you already applied
# - Referencing old code that no longer exists
# - Contradictory statements about the same file

Step 5. Start a fresh session with the structured summary injected into the initial prompt, specifying the 3 changed files for targeted re-analysis

Why: Fresh start with summary injection is the correct approach when files have changed. The exam specifically tests this: no stale tool results, preserved knowledge from the prior session, and targeted re-analysis of only the changed files instead of wasteful full re-exploration.

You should see: A clean session that knows about the prior findings (from the injected summary), targets only the 3 changed files for re-analysis, and produces consistent advice without contradictions.

Step 6. Compare the quality and consistency of advice between the stale resume and the fresh start with targeted re-analysis

Why: This comparison demonstrates why the exam favours fresh start with summary injection over naive resume after file changes. The fresh start produces consistent, accurate advice while the resume produces contradictions from stale context.

You should see: A clear quality difference: the resume session gives contradictory or outdated advice about the modified files, while the fresh session gives accurate, consistent analysis based on the current file contents.

# Comparison Results
| Metric | --resume | Fresh + Summary |
|--------|----------|----------------|
| References old code | Yes - cited unfixed SQL injection | No - recognised parameterised query |
| Recommends applied fixes | Yes - suggested fixing auth.ts | No - confirmed fix was correct |
| Consistent advice | No - contradicted itself on auth.ts | Yes - all advice matched current code |
| Files analysed | All 10 (unnecessary) | Only 3 changed files (efficient) |

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the work you did for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review what you actually ran and what came back.