The loop of D1.1 runs inside a single context window. Real agents outlive one window — they pause, resume on another host, or branch to try an alternative. The state that survives is the session, and this chapter fixes what a session is, the three controls that carry or branch it, and the one discipline that outlasts the session itself. This closes Domain 1: the loop, scaled across many windows.

Do I know this already? Diagnostic

Answer these confidently and you can skim ahead to Exam essentials; if any is shaky, read closely — each is developed below.

What does a session persist — and what does it not?
Write the literal Python (or TS) call for continue, resume, and fork.
If a forked agent edits a file, is the change isolated from the original session? Why?
A resume call returns an empty, fresh session. What is the single most likely cause?
You must finish an interrupted job on a different host tomorrow. What is more robust than shipping the transcript?

Check your answers

The conversation — prompt, tool calls, results, and responses as JSONL under ~/.claude/projects/<encoded-cwd>/ — not the filesystem; reverting file changes is file checkpointing’s job.
continue_conversation=True / continue: true; resume=sessionId / resume: sessionId; fork_session=True / forkSession: true.
No — forking branches the conversation history, not the filesystem, so both forks share one disk and the edit is real and visible to any session in that directory.
A mismatched cwd — sessions are looked up under ~/.claude/projects/<encoded-cwd>/, so resuming from a different directory derives the wrong path and starts fresh.
Capture the artifacts you care about as application state (analysis output, decisions, file diffs) and pass them into a fresh session’s prompt — more robust than shipping transcript files around.

A session is the persisted conversation

A session is the conversation history — the prompt and every tool call, tool result, and response — persisted as JSONL on disk at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. [Official] Work with sessions · AnthropicT1-official original The boundary that matters most is what a session does not include:

“Sessions persist the conversation, not the filesystem. To snapshot and revert file changes the agent made, use file checkpointing.” [Official] Work with sessions · AnthropicT1-official original

continue, resume, and fork

Three controls carry or branch a session — and the exam expects you to recognize their literal spellings, which differ between Python and TypeScript. [Official] Work with sessions · AnthropicT1-official original

Control	Literal call (Python / TS)	What it does	When to reach for it
`continue`	`continue_conversation=True` / `continue: true`	Picks up the most recent session in the current `cwd` — no ID needed	Resume after a process restart in the same directory
`resume`	`resume=sessionId` / `resume: sessionId`	Picks up a specific session by ID	Multi-user / multi-conversation apps where “most recent” is ambiguous
`fork`	`fork_session=True` / `forkSession: true`	Starts a new session ID from a copy of the original’s history; the original is untouched	Try an alternative direction without losing the original thread

continue and resume extend one thread; fork splits one into two. Capture the ID you’ll need later from ResultMessage.session_id — it is present even on errors. [Official] Work with sessions · AnthropicT1-official original

Fork branches the conversation, not the filesystem

The most-missed property of forking is the same boundary from section 1, sharpened:

“Forking branches the conversation history, not the filesystem. If a forked agent edits files, those changes are real and visible to any session working in the same directory.” [Official] Work with sessions · AnthropicT1-official original

Resume to recover — and the encoded-cwd trap

resume is the recovery tool for a loop that ended on a budget. When a session stops with error_max_turns (D1.1), you resume it with a higher limit and let it finish rather than restarting from scratch. [Official] Work with sessions · AnthropicT1-official original Because the work hit a budget, not a wall, the transcript is intact and resumable. [Official] How the agent loop works · AnthropicT1-official original

Recovering an error_max_turns session Worked example

A first run is bounded too tight and stops with subtype: "error_max_turns" (D1.1) — its .result is empty, but its transcript is intact. Recover it instead of restarting:

# First run returned error_max_turns; we captured its session_id from ResultMessage.session_id
async for message in query(
    prompt="Continue the refactor where you left off.",
    options=ClaudeAgentOptions(resume=session_id, max_turns=40),  # specific session, bigger budget
):
    ...

Two things must be right or resume silently starts fresh: (1) you pass the specific session_id (captured from the first run’s ResultMessage, which is populated even on the error), and (2) you run from the same cwd as the original, because the lookup path is ~/.claude/projects/<encoded-cwd>/. Bump max_turns so the resumed session can actually finish. Restarting from scratch would re-pay every turn already spent; resuming continues the intact transcript.

The single most common resume bug is the encoded-cwd mismatch:

“If a resume call returns a fresh session instead of the expected history, the most common cause is a mismatched cwd. Sessions are stored under ~/.claude/projects/<encoded-cwd>/*.jsonl, where <encoded-cwd> is the absolute working directory with every non-alphanumeric character replaced by -.” [Official] Work with sessions · AnthropicT1-official original

Scratchpads: durable state beyond the session

Sometimes the session itself is the wrong unit to carry — especially across hosts, where a CI worker or ephemeral container won’t have yesterday’s transcript file. The robust move is to lift the state you care about out of the conversation: “capture the artifacts you care about (analysis output, decisions, file diffs) as application state and pass into a fresh session’s prompt,” which the docs call “often more robust than shipping transcript files around.” [Official] Work with sessions · AnthropicT1-official original A scratchpad — a working file the agent writes to and reads from — is that same discipline applied within a run: the durable artifact, not the transcript, is the thing that survives. A fresh session then starts from that artifact, the way the best-practices guidance recommends executing a written spec in a clean session. [Official] Best practices for Claude Code · AnthropicT1-official original

This is where session state shades into memory — the design rationale for persisting durable context across many sessions is optional depth, in the Further reading.

Practice

Exercise solutions

Solution ↑ Exercise

(b) is more robust. (a) To resume by ID, the original session JSONL must be restored to the same path — ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl — and the fresh worker must run from the same cwd, because the encoded-cwd is derived from the working directory; only then does resume=sessionId (with a bumped max_turns) find the transcript. That means shipping the transcript file and reproducing the exact directory on every worker. (b) Instead, capture the artifacts that matter — the decisions made, the diff so far, the remaining plan — as application state and seed a fresh session’s prompt with them. No transcript to ship, no cwd to reproduce; the docs call this “often more robust than shipping transcript files around.” Resume is for recovering in place; cross-host work favors captured artifacts. (And note: neither option restores the files the agent edited — that is file checkpointing, separate from session state.)

Solution ↑ Exercise

C — fork. Forking starts a new session ID from a copy of the original’s history, and the original session is left untouched — exactly “branch to try an alternative without losing the original thread.” A (continue) and B (resume) both extend the same thread, so the alternative attempt would pollute the original conversation, not branch from it. D (file checkpointing) snapshots files, not the conversation — useful if the risky refactor must be revertible on disk, but it does not give you a second conversation. (Reminder: fork branches the conversation, not the filesystem, so pair it with checkpointing if the files must branch too.)

Solution ↑ Exercise

The most common cause is a mismatched cwd. Sessions are stored under ~/.claude/projects/<encoded-cwd>/*.jsonl, where <encoded-cwd> is the absolute working directory with every non-alphanumeric character replaced by -; if you resume from a different directory, the SDK derives a different encoded path, finds nothing, and starts a fresh session. The fix: run the resume from the same working directory as the original session (or otherwise ensure the encoded-cwd path matches).

Exam essentials

A session is the persisted conversation, not the filesystem — JSONL under ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. File state is separate (file checkpointing).
Three controls, with literal spellings: continue (continue_conversation=True / continue: true), resume (resume=sessionId / resume: sessionId), fork (fork_session=True / forkSession: true). resume/continue carry; fork branches (new ID from a copy; original untouched).
Fork branches the conversation, not the disk — forked file edits are real and shared. Pair with file checkpointing to branch files.
resume recovers an error_max_turns session with a bumped budget; the #1 bug is a mismatched cwd → wrong encoded path → a fresh, empty session.
For cross-host work, capture artifacts as application state and seed a fresh session’s prompt — more robust than shipping transcripts.

Part 1 · D1 Review

7 exercises across 7 chapters — interleaved review.

d1-01-agentic-loops

d1-01-ex-trace A session runs: (1) Claude calls `Read`; (2) Claude calls `Grep`; (3) Claude calls `Edit`; (4) Claude returns a text summary with no tool call. How many *turns* is this? What is the `stop_reason` on the final response, and what is the smallest `max_turns` that still lets the session finish?

d1-02-coordinator-subagent-patterns

d1-02-ex-decide A support agent has 40 tools spanning CRM, order history, messaging, and analytics, and its accuracy on multi-step tickets is falling. A teammate proposes splitting it into four subagents: *intake*, *diagnosis*, *resolution*, *follow-up*. Walk the decision framework: is multi-agent warranted here, and if so, is this the right way to cut it? State the win-condition (if any) and name the anti-pattern (if any).

d1-03-subagent-invocation

d1-03-ex-fix-delegation You define a read-only `doc-reviewer` subagent via the `agents` option — `description: "Reviews things"`, `tools: ["Read", "Grep", "Glob"]` — but it never triggers; the main agent just reviews inline. The parent's `allowedTools` is `["Read", "Edit", "Bash"]`. Diagnose the **two** reasons it won't delegate, and give the fix for each. Is the `tools` array itself part of the problem?

d1-04-multi-step-workflows

d1-04-ex-pipeline A content workflow runs four steps — research → draft → fact-check → polish — today as a single agent in one context. Quality is slipping specifically at the fact-check step: the agent waves through claims it wrote moments earlier. Evaluate two options: (a) keep it one prompt-based agent, or (b) hand the fact-check to a fresh-context reviewer with an explicit programmatic handoff. Which do you choose, where exactly do you place the split, and what would over-splitting into four role-agents cost you?

d1-05-agent-sdk-hooks

d1-05-ex-gate-normalize You must enforce two rules on an agent: (a) it may never write to any `.env` file, and (b) every `Bash` result must have its ANSI color codes stripped before the model reads it. For each rule, name the hook event you would use and the specific return field that does the work. Why can't (b) be done with the same event as (a)?

d1-06-task-decomposition

d1-06-ex-pipeline-vs-adaptive Evaluate the right decomposition structure for each task and justify it in one or two sentences. (a) A nightly job that summarizes each of 200 incoming support tickets into the same fixed JSON shape. (b) "Find out whether any of our competitors have shipped feature X — go as deep as the question needs." For whichever you call adaptive, name the failure mode you must guard against and roughly the token cost you are accepting.

d1-07-session-state

d1-07-ex-resume-ci A CI job runs an agent that stops with `error_max_turns` partway through a refactor. The job's container is torn down, and you must finish the work on a **fresh worker** tomorrow. Walk two options: (a) resume the original session by ID — what must be in place for that to work? — and (b) capture artifacts as application state. Which is more robust across hosts, and why?