What You Need to Know
A session is one conversation with an agent that you can return to. Its conversation history holds the agent's reasoning and every tool result. A tool result is the output of a tool call, such as a file's contents when the agent read it. Long-running tasks include debugging a complex system, reviewing a large codebase and multi-day research. In these tasks, the history fills with tool results, file analyses and reasoning chains. Session management determines how an agent keeps continuity across work sessions. Task Statement 1.7 covers how to manage that accumulated state: when to continue it, when to branch it and when to start fresh. A tool result is stale when the file it describes has changed since the agent read it.
This lesson uses one made-up example throughout: a shoe repair shop whose owner uses Claude Code to review the shop's files. The files are the price list, the repair-ticket template and the supplier order sheet. On day one the agent reads the files and finds three pricing errors. Overnight the owner fixes all three by editing those three files. On day two the owner wants to continue.
Three Session Management Options
The Agent SDK and Claude Code give you three approaches to session management. Each does a different job.
Option 1: --resume <session-name>
Resume continues a specific named session from the point where it stopped. It restores the entire conversation history, including every tool result, analysis and line of reasoning. Use it when the prior context is mostly still valid. The files have not changed significantly since the last session, and you want to continue from exactly where you stopped.
Do not resume when the earlier tool results are stale. This happens when files have changed since the last session, and much of what the history says about them no longer matches the codebase. If most of the context is still valid, resume and tell the agent which files changed. Otherwise the stale context problem occurs: the agent reasons from tool results that no longer reflect the current files. Resume would suit the shop after a night when nobody changed the files. Resume does not suit day two, because the day-one analysis was based on three files, and those three files have changed.
Current state: how sessions get their names
--resume only resumes sessions that already exist. It accepts a session ID or name, or opens an interactive list where you choose a session, but it never creates a session. Current state (checked 6 October 2026): you name a CLI session at start with --name / -n, or mid-session with /rename. You continue it later with claude --resume <name>. There is also -c / --continue, which resumes the most recent conversation in the current directory without naming anything. (Source: the Claude Code CLI reference.)
Option 2: fork_session
Fork creates an independent branch from a shared analysis baseline. The baseline is the analysis in the session so far, and both branches start from it. After the fork, each branch operates independently. Changes in one branch do not affect the other, and neither branch can see the other's results.
Current state (checked 6 October 2026): in the SDK you set fork_session beside resume, not instead of it. resume picks the session, and fork_session: true starts a new session from a copy of that history instead of appending to it. The CLI pairs --fork-session with --resume the same way. (Source: the Agent SDK sessions guide. Lesson 1.3 has the full note.)
Use fork when you have completed an initial analysis and want to explore divergent approaches from that shared starting point. For example, after analysing a codebase, you fork to compare two refactoring strategies. Each fork starts from the same initial understanding and then follows a different approach. Do not fork when you simply want to continue the same line of investigation. Fork is for divergence. If you are not comparing alternatives, use resume. After day one, the owner could fork to compare two pricing fixes: a higher resoling price, or a charge for rush jobs. Both branches start from the same reading of the files, and neither branch sees what the other concludes.
Option 3: Fresh start with summary injection
Start a completely new session and inject a structured summary of the prior session's findings into its initial context. The new session has no stale tool results. It has only the curated summary that you provide. Use a fresh start when tool results from the prior session are stale because files have changed, APIs have been updated or dependencies have changed. Use a fresh start too when context has degraded over a long session. In that case, too many irrelevant tool results clutter the history. In both cases you need a new session without stale or irrelevant tool results, and you need to keep the prior knowledge. If the prior context is still valid and you want the full conversation history, resume is more efficient. Fresh start is the right choice for the shop on day two.
Key Concept
Three session management options serve three distinct purposes: resume for continuation, fork for divergent exploration, and fresh start with summary injection for when prior tool results are stale.
The Stale Context Problem
The stale context problem is the central concept of this task statement. It occurs when an agent resumes a session after code or other files have changed. The agent then reasons from cached tool results that no longer reflect the current state of those files.
When you resume a session, the entire conversation history is restored, including every tool result from the previous session. Suppose the agent read a file in the previous session, and the file has changed since then. The file's old contents stay in the conversation as a tool result. The model reasons from that stale data alongside any new data, and the two contradict each other. The symptom is contradictory advice about the changed files. The agent recommends changes that were already made, or refers to code that no longer exists.
On day two the owner resumes the session, and the agent recommends fixing the three errors that the owner fixed overnight. The tool results showing the old price list are still in the history. When the agent is asked about the current price list, it gives contradictory answers. Sometimes it quotes the old version from the stale tool result, and sometimes it quotes the new version from a fresh read.
The obvious fix is to resume and ask the agent to re-read the changed files. This fix is better than nothing, but the stale tool results remain in the conversation history. The model may still refer to old information from earlier in the context. The model is most likely to do this for tangential decisions that do not directly involve the changed files.
The correct fix is to start a fresh session with a structured summary of prior findings. Specify which files have changed, so the agent can run a targeted re-analysis of those files. The fresh session has no stale tool results. The injected summary keeps what the prior session learned, without the outdated data. For the shop, the new session reads the current files, verifies the three fixes and gives consistent advice.
Targeted Re-Analysis vs Full Re-Exploration
When files have changed, the agent does not need to re-analyse everything. Re-reading 50 files because 3 of them changed is wasted time. Targeted re-analysis means telling the agent which files changed and letting it re-analyse only those. The summary from the prior session covers everything that has not changed.
On day two, the shop's targeted re-analysis runs in four steps:
- Start a fresh session.
- Inject a structured summary: "Prior analysis found three pricing errors. All three have been fixed in these 3 files: the price list, the repair-ticket template and the supplier order sheet. Re-analyse only these files to verify the fixes and check for any new issues the changes introduced."
- The agent re-reads and re-analyses only the 3 changed files.
- It combines the fresh analysis of the changed files with the preserved summary of the unchanged files.
This is faster than full re-exploration and more reliable than resuming with stale context.
When to Use Each Option: Decision Matrix
| Scenario | Best Option | Reasoning |
|---|---|---|
| Continuing work from yesterday, no files changed | --resume | Prior context is valid, full history is useful |
| Comparing two refactoring approaches | fork_session | Divergent exploration from shared baseline |
| Resuming after modifying the 3 core files most of the earlier analysis relied on | Fresh start + summary | Stale tool results for modified files would cause contradictions |
| Long session with cluttered history | Fresh start + summary | Degraded context benefits from a clean baseline |
| Exploring a testing strategy vs a documentation strategy | fork_session | Two independent approaches from the same analysis |
| Resuming after dependency updates | Fresh start + summary | Multiple files may have changed indirectly |
In the exam
The exam tests whether you can select the right option for each scenario. Resume the session when prior context is mostly valid. Start fresh with an injected summary when prior tool results are stale. A typical question describes a session that was resumed after files changed, and an agent that gives contradictory advice. The right answer is a fresh session with a structured summary, plus targeted re-analysis of the changed files. Starting a new session with a structured summary is more reliable than resuming with stale tool results.
Exam Trap
The exam tests whether you recognise that resuming after file changes can cause stale context. Simply resuming and asking the agent to re-read changed files is not the best answer. The stale results remain in history and can still influence reasoning. A fresh start with summary injection is more reliable.
Exam Traps
Suggesting full re-exploration of a 50-file codebase when only 3 files changed
Full re-exploration is wasteful. Inform the agent about the specific 3 files that changed for targeted re-analysis. The prior summary covers everything else.
Resuming a session when most of its earlier tool results describe files that have since changed
The resumed history keeps the old file contents, so the agent reasons from stale results and gives contradictory advice. Start fresh with a structured summary instead. If most of the context is still valid, resume and tell the agent which files changed.
Using fork_session to continue a single line of investigation
fork_session starts a new session from a copy of the history and leaves the original unchanged, so one piece of work is split across sessions. Use --resume to continue the same session, and fork_session to compare divergent approaches from it.
Using fork_session to handle stale context after file changes
fork_session branches from the existing session, which still contains stale tool results. The fork inherits the stale context. A fresh start with summary injection is the correct approach for stale data.
Practice Scenario
A developer resumes a Claude Code session after modifying 3 files in a 50-file codebase. The 3 files are the core modules, and most of the session's earlier reasoning was built on their old versions. The agent gives contradictory advice about the modified files because it is reasoning from stale tool results. The other 47 files are untouched, and the developer has no time to have them all read again. What is the correct approach?
Build Exercise
Implement Session Management Strategies
What you'll learn
- The three session management options: resume, fork_session, and fresh start with summary injection
- Why resuming after file changes leads to the stale context problem
- How structured summary injection preserves knowledge without stale tool results
- When targeted re-analysis is more efficient than full re-exploration
- The difference between fork_session (divergent exploration) and resume (continuation)
- 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.
- 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.
- 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.
- 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 signs of stale context.
- 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.
- 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
- Agent SDK: Work with sessions — Anthropic
- CCAR-F Exam Guide v1.0: Task Statement 1.7 — Anthropic