Session State & Resumption
Resume continues, fork diverges, and a fresh start with summary injection fixes stale context. Learn which to pick when files have changed under a long-running agent.
Long-running agents - debugging a system, reviewing a large codebase - accumulate context: tool results, file analyses, and reasoning chains. Managing that state across sessions is the focus of this lesson, and the central concept the exam tests is the stale context problem. There are three ways to carry work forward, and each fits a different situation.
Three session-management options
- `--resume <name>` - continue a specific named session, restoring the full history including all prior tool results. Right when prior context is still valid and files have not changed; wrong when files have been modified.
- `fork_session` - branch independently from a shared baseline to explore divergent approaches (e.g. comparing two refactoring strategies). Each branch is independent; results do not propagate. Wrong for simply continuing or for handling stale context.
- Fresh start with summary injection - begin a brand-new session and inject a structured summary of prior findings. Right when tool results are stale or the history has degraded; it preserves knowledge without carrying old tool outputs.
Sessions are named with --name/-n when created and reopened with --resume <name>. The -c/--continue flag resumes the most recent conversation in the current directory without naming it explicitly.
The stale context problem
When you --resume after modifying files, the whole history - including old tool results - is restored. Those old file contents linger as tool outputs even though the files have since changed. The agent then reasons from cached results that no longer reflect reality: it may recommend changes already made, reference code that no longer exists, or give contradictory advice - citing stale results for one decision and a fresh read for another.
When files have changed, do not --resume. Start a fresh session with a structured summary of prior findings and name the files that changed so the agent can do targeted re-analysis. The fresh session has no stale tool results, yet still preserves prior knowledge.
Calling `--resume` after modifying files. The full history - including stale tool results with the old file contents - is restored, so the agent recommends changes already made or cites code that no longer exists. Just re-reading the files leaves the stale outputs in history too.
claude --resume audit # old tool results lingerStart a fresh session and inject a structured summary, naming the changed files for targeted re-analysis. No stale tool results, prior knowledge preserved.
s = client.start_session() # clean baseline
s.inject_context(summary) # "3 files changed - re-read only these"Resuming and just asking the agent to re-read the modified files leaves the old tool outputs sitting in history. The model can still reference that stale data for tangential decisions. Only a fresh session removes the stale results entirely.
Targeted re-analysis beats full re-exploration
If only 3 of 50 files changed, do not re-analyze the whole codebase. Start fresh, inject a summary, and name the changed files so the agent re-reads only those - combining fresh analysis of the modified files with the preserved summary of the unchanged ones. This is faster and more reliable than either stale resumption or full re-exploration.
# Files changed since last session -> fresh start + summary injection.
summary = (
"Prior analysis found 3 auth issues in auth.ts, session.ts, "
"middleware.ts - all now fixed. Re-analyze ONLY these 3 files to "
"verify the fixes and check for new issues; treat the rest as unchanged."
)
session = client.start_session() # fresh: no stale tool results
session.inject_context(summary) # preserve prior knowledge
session.run("Verify the three modified files.")
# fork_session is for DIVERGENT exploration, not stale context:
# branch_a = base.fork_session() # try refactoring strategy A
# branch_b = base.fork_session() # try refactoring strategy B| Scenario | Best option |
|---|---|
| Continuing work, no files changed | --resume |
| Comparing two refactoring approaches | fork_session |
| Resuming after modifying 3 of 50 files | Fresh start + summary |
| Long session with cluttered history | Fresh start + summary |
| Resuming after dependency updates | Fresh start + summary |
Do not reach for fork_session to escape stale results - a fork branches from the existing session and carries its stale tool outputs along. Only a fresh start with summary injection gives a clean baseline.
How the exam will try to trick you
The distractors below look right under time pressure — learn the tell.
- The trap
Re-explore the whole 50-file codebase when only 3 files changed.
Correct answerName the 3 changed files for targeted re-analysis and treat the rest as unchanged.
Why: Full re-exploration is wasteful; the agent only needs to re-read what actually changed.
- The trap
Use
--resumeto continue work after files have been modified.Correct answerStart a fresh session with summary injection instead.
Why: Resuming restores stale tool results, so the agent reasons from outdated file contents and gives contradictory advice.
- The trap
Treat
fork_sessionand--resumeas serving the same purpose.Correct answerfork_sessionbranches for divergent approaches;--resumecontinues the same conversation.Why: They serve entirely different purposes - one diverges, the other continues.
- The trap
Reach for
fork_sessionto escape stale context after file changes.Correct answerUse a fresh start with summary injection for a clean baseline.
Why: A fork branches from the existing session and inherits its stale tool results.
Key takeaways
- Three options with distinct purposes: --resume continues, fork_session diverges, fresh start + summary resolves stale context.
- The stale context problem: resuming after file changes restores old tool results and produces contradictory advice.
- When files have changed, start a fresh session with a structured summary rather than --resume.
- Targeted re-analysis (name the changed files) beats full re-exploration of the whole codebase.
- Naively re-reading files during a resume leaves stale tool results in history - the model can still use them.
- fork_session inherits stale context, so it is not the fix for changed files - it is for divergent exploration.
Frequently asked questions
What is the difference between --resume and fork_session in Claude?+
--resume continues a specific named session along the same line of investigation, restoring its full history. fork_session creates an independent branch from a shared baseline so you can explore divergent approaches without the branches affecting each other.
What is the stale context problem when resuming a Claude session?+
It occurs when you resume a session after files have changed. The restored history still contains old tool results reflecting the previous file contents, so the agent may recommend already-made changes, reference deleted code, or give contradictory advice mixing stale and fresh data.
How should I resume work after modifying a few files in a large codebase?+
Start a fresh session and inject a structured summary of prior findings, naming the files that changed so the agent performs targeted re-analysis of only those files. This avoids stale tool results while preserving prior knowledge, and is faster than re-exploring the whole codebase.