Session State, Resumption & Forking
1. Core Idea
How to preserve useful state without accidentally preserving bad or stale state.
For long-running agentic work, Claude may accumulate: User instructions, Tool results, File contents, Codebase analysis, Decisions already made, Subagent outputs, Approval status, etc.
A strong architect must know when to:
- Continue the same session
- Resume a named prior session
- Fork a session
- Start fresh
- Inject a structured summary
- Persist durable memory
- Store workflow state outside the model
2. Agent, Environment, Session
| Concept | Meaning | Exam relevance |
|---|---|---|
| Agent | Reusable, versioned configuration: model, system prompt, tools, MCP servers, skills, metadata | Defines capabilities and behavior |
| Environment | Sandbox or execution environment where the agent runs | Defines where tools execute |
| Session | Running instance of an agent inside an environment | Maintains task-specific conversation history and state |
Conceptually: an agent is a reusable configuration (model, system prompt, tools), an environment is where it runs, and a session references an agent and an environment while maintaining conversation history across interactions.
Trap:
Updating the agent changes future behavior/configuration. Resuming a session continues prior task state.3. Three Major Session-Management Options
The core options are: Resume, Fork, and Fresh start with summary injection.
3.1 Resume
Use resume when continuing the same line of work and prior context is still valid.
Typical use:
Yesterday: Claude analysed the codebase.
Today: No files changed.
Need: Continue from where we stopped.
Best choice: resume.
Claude Code supports --continue for the most recent session and --resume / --resume <session_id> for selecting or resuming a specific session.
SDK distinction:
| Option | Meaning |
|---|---|
| Continue | Pick up the most recent session in the current directory (--continue) |
| Resume | Pick up a specific session ID or name (--resume <session_id> / --resume <name>) |
| Fork | Copy prior history into a new session for an alternative direction |
The SDK docs state that continue and resume both add to an existing session, while fork creates a new session that starts with a copy of the original history. (Claude Code — Work with sessions)
Avoid resume when:
- Files have changed
- Dependencies changed
- APIs changed
- The session contains too much irrelevant history
- Old tool results may conflict with current reality
3.2 Fork
Use fork when exploring alternative approaches from the same baseline. fork_session (SDK) / --fork-session (CLI) creates independent branches from a shared analysis baseline to explore divergent approaches.
Example:
Baseline: Claude analysed the architecture.
Branch A: Try event-driven refactor.
Branch B: Try database-first refactor.
Best choice: fork.
Forking creates a new session ID while preserving the original session unchanged. Claude Code supports forking with --fork-session or /branch. (Claude Code — How Claude Code works)
Use fork when:
- Comparing multiple refactor strategies from a shared codebase analysis
- Comparing two testing strategies
- Trying two debugging hypotheses
- Testing different implementation plans
- Preserving the original session while exploring a risky alternative
Do not use fork when:
- You simply want to continue yesterday's work
- The old session has stale file reads
- You need a clean baseline
- You need to remove bad context
Exam trap:
Fork is not the solution to stale context.
3.3 Fresh Start with Summary Injection
Use this when old session context is partly useful but polluted.
Example:
Day 1: Claude analysed 50 files.
Day 2: Developer modified 3 files.
Problem: Old tool results still show the old versions.
Best choice: fresh session + structured summary + targeted re-analysis.
Start a fresh session, inject a structured summary of prior findings, list the changed files, and ask Claude to reanalyze only those changed files.
Use fresh start + summary injection when:
- Files have changed since the prior session
- Tool outputs are stale
- Session context is cluttered
- Long-running context has degraded
- A clean reasoning baseline is needed
The injected summary should include:
Prior findings:
- File/module analysed
- Key issue
- Severity
- Decision made
- Current status
- Files changed since prior analysis
- What must be re-analysed
4. The Stale Context Problem
4.1 What Happens
A session is resumed after external changes. Claude still has old tool results in its conversation history. It may reason from old file contents, old command outputs, old dependency state, and previous analysis that is no longer true.
The Claude Code docs state that returning to a session gives the agent prior context, including files it already read and analysis it already performed; this is powerful, but it means old observations may remain in context.
4.2 Typical Scenario
Claude analysed auth.ts yesterday.
Developer fixed auth.ts today.
Developer resumes the old session.
Claude recommends fixing code that no longer exists.
Root cause:
Best fix:
Start a fresh session.
Inject a structured summary.
Specify the changed files.
Perform targeted re-analysis.
Simply resuming and asking the agent to re-read changed files is insufficient because stale results remain in history and can still influence reasoning.
Choosing resume vs fresh start: Resume when prior context is mostly valid; start fresh with an injected summary when prior tool results are stale.
5. Targeted Re-Analysis Vs Full Re-Exploration
When only a few files changed, do not re-analyze the entire codebase. Inform the resumed/fresh session about the specific file changes so it performs targeted re-analysis rather than full re-exploration.
Correct workflow:
1. Start fresh session.
2. Inject prior summary.
3. List changed files.
4. Re-read only changed files.
5. Validate whether prior conclusions still hold.
6. Update final recommendation.
Example:
Prior summary:
- Payment module had 5 findings.
- Auth module had 3 findings.
- Search module had 2 findings.
Changed files:
- auth.ts
- session.ts
- middleware.ts
Task:
Re-analyse only these changed files and verify whether prior auth findings are resolved.
Trap:
The exam usually rewards targeted re-analysis because it balances freshness and efficiency.6. Session State Vs Persistent Memory
Distinguish session-local state from cross-session memory.
| State type | Scope | Use case |
|---|---|---|
| Conversation/session history | Current session | Tool calls, tool results, current task reasoning |
| External workflow state | Application/database | Verified customer, AML pass, approval status |
| Memory store | Across sessions | User preferences, project conventions, prior mistakes, domain context |
| Filesystem/sandbox | Runtime environment | Files being read/written during task |
| Handoff summary | Human escalation | Self-contained transfer of context |
Each session starts with fresh context by default; when the session ends, state built inside it is gone unless a memory store is used. Memory stores let agents carry information such as user preferences, project conventions, prior mistakes, and domain context across sessions.
Write access to a memory store should be used carefully: prompt injection from untrusted input could poison future sessions. Use read-only access when the agent does not need to update durable memory.
Exam rule:
Use session state for current-task continuity.
Use memory for durable cross-session knowledge.
Use external systems for authoritative business state.
7. Pausing for External Action
A session can pause mid-task to wait for an external action, for example, a tool needs to run, or a risky operation needs human approval — and then resume once the application supplies the result or confirmation.
Pattern:
Agent requests action.
Session pauses, waiting for external input.
Application performs approval / tool execution.
Application supplies result or confirmation.
Session resumes.
Trap:
A pause means the workflow is waiting for external input, not that the task is complete.8. Multi-Agent Sessions and Continuity
In multi-agent sessions, each agent can run in its own isolated thread. Agents may share a workspace (filesystem, credentials), but each agent has its own context-isolated conversation history; threads are persistent, so the coordinator can later send follow-ups to an agent it previously called.
Implications:
- The coordinator remains responsible for orchestration.
- Subagents may retain prior turns in their own thread.
- Tools, MCP servers, and context are not automatically shared.
- Follow-up to the same subagent can use its persistent thread.
- Cross-agent state must still be routed through the coordinator or external state.
Trap:
A subagent remembers its own prior thread, but that does not mean every other agent has that context.
9. Context Management During Long Sessions
Claude Code's context can include conversation history, file contents, command outputs, CLAUDE.md, memory, skills, and system prompts. As context fills, Claude Code compacts automatically, but early instructions can be lost; persistent rules should live in CLAUDE.md rather than relying on early conversation history.
Implications:
| Problem | Better architecture |
|---|---|
| Long session getting cluttered | Fresh start + structured summary |
| Persistent coding rules lost during compaction | Put in CLAUDE.md |
| Need branch experiment | Fork |
| Need undo local edits | Checkpointing or version control |
| Need durable project facts | Memory store or project docs |
| Need valid current file state | Re-read changed files in clean session |
Checkpointing is useful for local undo and experimentation, but it is not a replacement for version control; it also does not track all bash-command file modifications.
10. Decision Matrix
| Scenario | Best choice | Why |
|---|---|---|
| Continue same work, no files changed | Resume / continue | Prior context is valid |
| Continue most recent session in directory | --continue |
No need to track session ID |
| Resume specific named/known session | --resume <session_id> |
Select exact prior context |
| Compare two refactor approaches | Fork | Divergent exploration from shared baseline |
| Files changed since prior analysis | Fresh session + summary injection | Avoid stale tool results |
| Long session with cluttered context | Fresh session + summary injection | Clean baseline |
| Only 3 of 50 files changed | Targeted re-analysis | Avoid full re-exploration |
| Need durable user preference | Memory store | Persists across sessions |
| Need financial approval state | External workflow state | Must be authoritative |
| Tool requires human approval | Pause for external confirmation | Workflow resumes after decision |
| Multi-user app | Track session IDs explicitly | Avoid mixing user contexts |
| Autoscaled workers need resume | External session store | Local filesystem is insufficient |