Study notes · 3.8% of the exam

1.7 Manage session state, resumption, and forking

Continue, resume, fork or restart agent sessions appropriately: resume named sessions when prior context is valid, fork to explore divergent approaches from a shared baseline, tell a resumed agent what changed, and start fresh with a structured summary when prior tool results are stale.

Key points

1
A session is the persisted conversation: prompts, every tool call and result, and every response, written to ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl on the machine that ran it. Sessions persist the conversation, not the filesystem; file changes are real and shared with anything else in that directory (use file checkpointing to snapshot and revert files).
2
Claude Code CLI: claude --name <name> (or /rename) labels a session; claude --resume <name-or-id> (-r) reopens that specific conversation; claude --continue (-c) reopens only the most recent session in the directory; --fork-session combined with --resume or --continue branches under a new session ID.
3
Agent SDK: capture session_id from the result message (or the init system message); pass it as resume to continue that session, or resume plus fork_session=True (forkSession: true) to branch. continue_conversation=True / continue: true picks up the most recent session without an ID. Python's ClaudeSDKClient keeps the same session across client.query() calls automatically.
4
Forking creates a new session that starts with a copy of the original's history and diverges from there; the original ID and history stay untouched. Fork once per branch to compare two testing or refactoring strategies from the same analysis; resuming the same ID sequentially would chain the branches together.
5
Because forks share a working directory, two forks that both edit files clobber each other. Isolate the filesystem per branch (separate checkout or git worktree, or run sequentially with checkpoint revert) when forks will make changes rather than just reason.
6
Resume when the prior context is mostly valid: following up on a completed analysis, recovering from error_max_turns or error_max_budget_usd with a higher limit, or restarting the process after a shutdown. The agent then acts without re-reading files.
7
A resumed agent still holds the old tool results and has no way to know files changed. When a few analysed files were modified, resume and open with a message that names the changed files and asks for targeted re-analysis, rather than forcing a full re-exploration.
8
When most prior tool results are stale (a large refactor), or the transcript is bloated with dead-end output and only the decisions matter, start a new session with a structured summary of the valid findings injected into the prompt. This is more reliable than resuming into contradictory, outdated evidence.
9
Session files are local. On ephemeral CI runners or other hosts, resume fails with session-not-found and continue finds nothing. Options: mirror transcripts via a session_store adapter, move the .jsonl file, or (most robust when only results matter) capture findings as application state and feed a fresh session. Do not commit transcripts to the repo.
10
Subagents can be resumed too: the Agent tool result carries an agentId; resume the parent session_id and reference that agent ID in the prompt, passing the same agents definitions.
11
Common distractors: --continue when a specific older session is wanted; --fork-session used alone as if it selected a session; forking to "refresh" stale context (a fork copies the same stale results); resuming silently after code changed; re-exploring everything when only a handful of files changed.

Read the source

Test yourself on 1.7 Manage session state, resumption, and forking

Ten questions, with the answer and explanation after each one.