Manage session state, resumption, and forking

Long-running agent work spans days and branches. This statement covers the three levers the certification grades: resume, fork, and deliberate restart. The CLI has a fourth that the guide does not test — --continue (-c), which reopens the most recent conversation in the current directory without naming anything.¹⁷ If it shows up as an option on a named investigation stem, it is not the credited answer: the guide's whole point in 1.7 is the deliberate choice of which prior session, and --continue makes that choice for you.

Lever	Reach for it when	What the next session starts from
--resume <session-name>	Prior context is still substantially valid	The whole prior conversation, cached tool results included
fork_session	Two approaches should diverge from one expensive baseline	The shared baseline, inherited — no branch sees another's work18
Start fresh with a structured summary	Prior tool results are stale	A short summary of conclusions that you inject; no raw tool output

Named resumption with --resume

--resume <session-name> continues a specific prior conversation, with its accumulated exploration, findings and decisions intact. Naming sessions is what makes this usable: --resume payment-refactor is a reliable handle for the investigation you were running yesterday, whereas an opaque identifier is not. Use it when picking up an investigation whose prior context is still substantially valid.

The CLI accepts either form — --resume <name> or --resume <id> — and --resume with no argument opens a picker of recent sessions. The guide teaches the named form because a name is the handle you can put in a runbook or a ticket; that is the habit being graded.

fork_session for divergent exploration

fork_session creates an independent branch from a shared baseline.⁹ The value is that the expensive part — mapping the codebase, understanding the data model, reading the existing tests — is done once, and each branch inherits it. You then explore genuinely divergent approaches in parallel without contaminating each other. Fork A pursues integration tests through the public API while fork B pursues unit tests with dependency injection; or fork A tries the incremental refactor and fork B the rewrite. Compare outcomes and keep one. Without forking you either re-derive the baseline per branch or let one branch's dead ends pollute the other's context.

One terminology warning, because nothing else in the guide flags it: "fork" means two unrelated things. fork_session here creates a branch that inherits a shared analysis baseline. context: fork in skill frontmatter (Domain 3, §3.2) isolates a skill's working context, so its file reads and intermediate notes never enter the main conversation — only its final result does. Same word, opposite concern — inheritance versus isolation — and the two share no mechanism.

Resume versus start fresh

The important judgment call. Resume when prior context is mostly valid. Start a new session with an injected structured summary when prior tool results are stale.

Staleness is the crux. A resumed session's history contains tool results — file contents, test output, grep matches — captured at a point in time. If the code has since changed, those results are now confidently wrong, and the agent will reason from them: editing a function that no longer exists, citing a line number that moved, assuming a test still fails. A resumed session with stale tool results is more dangerous than a fresh one, because the errors look grounded.

So if files changed since the last session, you have two options. The more reliable one is to start fresh with a structured summary of the conclusions, not the raw tool output. The other is to resume and explicitly inform the agent which files changed, so it re-reads exactly those instead of trusting cached content or re-exploring the entire codebase. Targeted re-analysis is the middle path: cheaper than a full re-exploration, safer than blind trust.

A useful habit: end each work session by having the agent write a structured summary — findings, decisions, open questions, files touched. That artifact makes both resume-with-updates and fresh-start-with-summary cheap.

# Continue the specific named investigation from yesterday.
claude --resume payment-refactor

# First message of the resumed session — invalidate only the stale reads:
# "Since our last session, two files changed on main:
#    - billing/invoice.ts
#    - payments/gateway.ts
#  Re-read both before continuing. Your earlier reads of these files are stale;
#  everything else from our analysis still holds. Then confirm whether the three
#  seams we identified are still the right extraction points."

// ILLUSTRATIVE PSEUDOCODE. The shape of the flow is the point; the field and
// function names below are not an SDK signature. The guide's term for the
// mechanism is fork_session.

// One expensive baseline: module map, dependency graph, coverage, conventions.
const baseline = await runSession({
  sessionName: 'payments-baseline',
  prompt: 'Map the payments module: dependencies, entry points, existing coverage, test conventions.',
});

// Two divergent branches, each inheriting the baseline, neither polluting the other.
const [integrationBranch, unitBranch] = await Promise.all([
  runSession({
    resume: baseline.sessionId,
    fork_session: true, // independent branch from the shared baseline
    prompt: 'Strategy A: integration tests through the public API. Report coverage, runtime, refactor cost.',
  }),
  runSession({
    resume: baseline.sessionId,
    fork_session: true,
    prompt: 'Strategy B: unit tests with injected dependencies. Report coverage, runtime, refactor cost.',
  }),
]);

// Compare on measured outcomes; carry exactly one forward.

## Prior investigation summary — checkout double-charge (2 weeks ago)

### Conclusions reached
- Double charges correlate with client retries during gateway timeouts.
- The idempotency key is derived from the cart hash, which changes on retry.

### Decisions taken
- Key idempotency on a client-generated request ID instead of the cart hash.

### Open questions
- Does the gateway honor idempotency keys on the refund path too?

### Must be re-verified (code has changed since)
- checkout/service.ts and payments/gateway.ts were rewritten. Re-read both.
- The failing test named in the old session may no longer exist. Re-run the suite.

Do not rely on any file contents or test output from the previous session.