What you will be able to do
- Choose between continue, resume and fork for a given deployment, and explain why continue is unsafe when sessions run concurrently
- Capture a session ID early enough that a crashed worker can still resume
- Design an external SessionStore so sessions survive container restarts and move between hosts
- Tell apart what a transcript records from what actually exists on disk, and reconcile the two on resume
- Keep a session to one owner, and plan a model-version cutover for long-lived sessions
Key concept
Session ID as the durability handle — A long-running agent survives interruption only if its application can name the exact session to restore. The session ID is that name. Everything durable (resume, fork, external storage, rewinds) is keyed on it, so where and when you record it decides what you can recover.
1.Choosing continue, resume or fork
An agent that runs for hours, or picks a task back up days later, needs its conversation history to outlive the process that started it. The Agent SDK persists that history as a session, and you get it back in one of three ways. The difference between them is who keeps track of which session is which.
| Mechanism | How it picks the session | When it wins |
|---|---|---|
| continue: true (TypeScript) / continue_conversation=True (Python) | The most recent session in the current directory; you track nothing | One conversation at a time, such as a single-user tool restarted after a crash |
| resume with a session ID | Exactly the session whose ID you pass | Many sessions side by side, such as one per user or one per job, or returning to a session that isn't the newest |
| Fork (resume plus fork_session=True / forkSession: true) | Branches from the given ID into a new session with its own ID | Trying an alternative approach while the original thread stays intact |
Continue is a convenience, not an identity. It means "the newest session here". That is correct only if nothing else could have written a newer one. Picture a support backend that serves every chat message with continue. When two customers write at the same moment, the newest session in the directory may belong to the other customer, and their order details end up in the wrong reply. Once a process handles more than one conversation, store an ID per conversation and pass it to resume.
A fork is how you branch, never how you share. The forked run reports its own ID, distinct from the one you resumed, and the original session is untouched: resuming the original afterwards continues its own thread. Two forks are two independent histories, and the session API (forkSession(), listSessions(), deleteSession() and the rest) has no operation that merges them back into one.
Resume is also the recovery path after a run hits a limit. If a run ended with error_max_turns or error_max_budget_usd, resume the same ID with a higher limit. In a single-shot query() call the SDK raises after yielding that error result, so catch the error first, then resume.
Checkpoint 1 of 9· Match them up
Match each scenario to the way of returning to a prior session that fits it best.
Tap a term, then the definition that fits it.
Continue takes the newest session in the directory, so it is only safe when one conversation runs at a time. When many conversations run side by side, you store each one's ID and pass it to resume. A fork branches into a new session with its own ID and leaves the original thread unchanged.
“Resume takes a specific session ID. You track the ID. Required when you have multiple sessions (for example, one per user in a multi-user app)”Source: code.claude.com
2.Capturing the session ID before anything can fail
Record the ID from the first message, not the last. The basic examples read session_id off the ResultMessage. That works for error results such as hitting the turn limit, which still arrive as a result. It fails in exactly the case durability exists for: a killed container or a dropped connection, where no result is ever yielded. A run opens with a system message of subtype init, and that message already carries session_id. Write it to the job record, keyed by job ID, the moment it arrives.
for await (const message of query({
prompt: "Instead of JWT, outline how OAuth2 would work for the auth module",
options: {
resume: sessionId,
forkSession: true,
maxTurns: 5
}
})) {
if (message.type === "system" && message.subtype === "init") {
forkedId = message.session_id; // The fork's ID, distinct from sessionId
}Neither of the usual shortcuts can replace a stored ID. Restarting with continue reattaches to whichever session is newest in the directory, which on a shared worker may belong to another job. Listing transcripts on disk and taking the newest has the same flaw, with extra steps. The ID is the one the SDK reports back in its messages, so the job record has to capture that value rather than mint its own.
Checkpoint 2 of 9· Check yourself
A batch service runs one agent job per container and autoscaling can kill containers mid-run. To make sure every interrupted job can be resumed later, how should the worker record the session ID?
A killed container or a dropped connection yields no result message, so code that captures the ID from the result never records it. The init message carries the SDK-assigned session_id at the start of the run. Continue can pick up another job's newer session, and an ID you generate yourself is not one the SDK knows.
“connection or process failures yield no result message, so session_id stays None.”Source: code.claude.com
Checkpoint 3 of 9· Exam question
Basalt Bank runs a nightly reconciliation service in which a pool of worker processes each execute long agent runs against ledger exports. Every job has a record keyed by job id, and several jobs share the same host and the same transcript directory at once. When a worker crashed mid-run, before any result message arrived, the on-call engineer found that the job record held a session ID only from the final result, so on restart there was nothing to resume. Starting over would repeat hours of work and re-query the ledger. The engineer noted that the init message at the start of every run had already carried a session identifier, but nothing recorded it, and the transcript directory held several recent files from other jobs. What is the best design change?
Correct answer: A — Persist the session ID when the init message arrives, keyed by job id, so a later resume works even if no result was produced
- A. The session ID is available early in the run, so saving it then makes recovery possible even for runs that never complete.
- B. Continue picks the newest session in a directory, which is ambiguous when workers run several jobs and can resume the wrong one.
- C. Picking the newest transcript is a guess; on a host that ran several jobs it may be a different job's session.
- D. The SDK assigns session IDs itself; an application-made identifier is not a reference that resume can use to find the transcript.
Sources1
3.Making sessions outlive the machine
By default a session is a local file, and resume only works where that file is. A resumed ID still needs the session file on the current machine. Serverless functions, autoscaled workers and CI runners don't share a filesystem, and local containers are ephemeral. Without help, a job rescheduled onto another host has nothing to resume.
A SessionStore adapter mirrors transcripts to storage you run yourself: an object store, a key-value store or a database. With it, any replica can resume any session, and transcripts survive redeploys under your own retention, encryption and access rules. You pass the same store to every query() call through sessionStore / session_store. Only two methods are required.
type SessionStore = {
// Required
append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
// Optional
listSessions?(
projectKey: string,
): Promise<Array<{ sessionId: string; mtime: number }>>;
listSessionSummaries?(projectKey: string): Promise<SessionSummaryEntry[]>;
delete?(key: SessionKey): Promise<void>;
listSubkeys?(key: {
projectKey: string;
sessionId: string;
}): Promise<string[]>;
};| Method | If you omit it |
|---|---|
| listSessions | continue: true throws, because the SDK cannot find the store's newest session |
| listSubkeys | Only the main transcript is restored on resume; subagent transcripts are not discovered |
| delete | deleteSession() is a no-op, which suits append-only backends |
| listSessionSummaries | Listing falls back to listSessions plus one load per session |
Because of that deletion, the store's own availability and backups become the durability guarantee, so treat it like any other system of record. The mirror is also built from local writes, so persistSession: false in TypeScript switches it off along with them. The SDK ships a conformance suite, run_session_store_conformance, for checking a custom adapter before you rely on it.
Checkpoint 4 of 9· Check yourself
Your orchestrator saves each job's session ID from the init message. Autoscaling then moves an interrupted job to a fresh worker that does not share a filesystem with the old one. What lets the new worker resume that job's conversation?
By default a session is a local file, so resuming an ID only works on a machine that has that file. If a SessionStore is passed to every query(), the transcripts are copied to shared storage, so any replica can load the session by its ID. Continue and fork also read the local session file, so neither helps on a new host.
“Mirror Agent SDK session transcripts to your own object store, key-value store, or database so other hosts can resume your sessions.”Source: code.claude.com
4.A transcript is not proof that work happened
Resume restores the conversation, not the world. The transcript says what the agent did and saw, but files, databases and external systems can have moved on since then. When a job is rescheduled onto a worker with a clean checkout, the transcript may say three config files were edited even though none of those edits exist on that disk. A resumed agent that trusts the transcript will skip work that was never persisted.
Interruptions open a second gap. When Claude Code resumes a session, a tool that was still running when the previous process crashed does not get rerun. Whether that tool's side effect happened is unknown, so resume logic should check the real state before moving on. Did the file change land? Did the write commit? Redo any step whose effect is missing, and make side-effecting steps safe to repeat.
File checkpointing is the SDK's tool for the opposite problem: undoing changes the agent made. With enable_file_checkpointing=True / enableFileCheckpointing: true, the SDK backs up files as the agent edits them. You also pass the replay-user-messages extra arg so the stream carries user-message UUIDs, which serve as restore points. Only your own prompts count as checkpoints; tool results don't. Later you resume the session and call rewind_files / rewindFiles with a UUID, or do the same from the CLI:
CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>Checkpoint 5 of 9· Fill the gap
An agent's refactor went wrong, and you want to put the files back the way they were at an earlier prompt. To do that, you reopen the run that made the edits and rewind it. Which flag completes this command?
CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p ? <session-id> --rewind-files <checkpoint-uuid>To rewind, you resume the exact session that made the edits, using its ID, and then pass a checkpoint UUID from that session. Continue reopens whichever session is newest and takes no ID. A fork branches into a new session with its own ID, so it is not the run whose file backups you want.
Source: code.claude.com5.One session, one owner
A session transcript is append-only, and resuming an ID appends to it. If two processes resume the same ID at the same time, both append turns and tool calls to one history and to the store behind it. The SDK calls append after each batch of transcript entries is written. The usual way into this state is a job queue: a worker runs past its visibility timeout, the queue redelivers the job, and two workers now drive one session with conflicting tool calls.
The job runner has to guarantee a single owner, because the agent cannot. A sound design looks like this:
- Before resuming, the worker acquires a per-job lease and keeps renewing it for as long as the agent runs. A worker without the lease does not resume.
- Each side-effecting write carries the lease's token. If a stalled worker's lease has expired and passed to someone else, the downstream system rejects its stale token instead of accepting a second, conflicting write.
- On restart, the new owner resumes the stored ID and checks real state, as described for transcripts above.
The tempting alternatives fail. A 24-hour visibility timeout makes redelivery rarer without preventing it, and it delays recovery when a worker really has died. Asking the agent in its prompt to check whether another worker is active hands a coordination guarantee to a model that cannot see the other process. Forking on every pickup produces separate histories with no merge operation, so the conflict just moves into reconciling transcripts by hand.
Checkpoint 6 of 9· Check yourself
After a worker runs past its queue visibility timeout, the job is redelivered. A second worker resumes the same stored session ID while the first worker is still running. What happens, and where does the fix belong?
Resuming an ID appends to that session's append-only transcript, and the store's append is called after each batch of entries. Two resumers therefore write one interleaved history. The SDK does not block this or fork on its own, and a longer timeout only makes redelivery rarer. The job runner has to guarantee one owner.
“After each batch of transcript entries is written locally. Entries are JSON-safe objects, one per line in the local JSONL.”Source: code.claude.com
Checkpoint 7 of 9· Exam question
Cobalt Clinics runs an agent that drafts patient-intake summaries and updates scheduling records through tool calls. Jobs arrive on a message queue consumed by several workers. Two queue workers pick up the same job after a visibility timeout and both resume the same session ID, appending conflicting tool calls. Logs show the first worker was not dead: a long garbage-collection stall paused it, and it then kept writing to the scheduling system minutes after the second worker took over. Operations rejects any approach that leaves a crashed worker's job waiting for hours, and the SDK team confirms it has no facility for merging divergent transcripts. Prompt-level guardrails were tried last quarter and the duplicates continued. Select TWO changes that prevent this.(Select 2)
Correct answers: A, B — Acquire a per-job lease before resuming and keep renewing it while the agent runs, so only one worker owns the session; Fence side-effecting writes with the lease's token so that a stale worker whose lease expired has its writes rejected
- A. A renewable lease gives a single owner and hands the job over safely when a worker dies.
- B. Fencing tokens protect external systems from a paused or delayed worker that still believes it owns the job.
- C. A huge timeout leaves a crashed worker's job stuck for a day and still allows duplicates when a worker simply runs slowly.
- D. Forking duplicates the work and its side effects, and merging two divergent transcripts is not something the SDK does for you.
- E. The agent has no reliable way to observe other workers, and a prompt instruction cannot enforce mutual exclusion.
6.Surviving a model version change
A long-lived session carries history written by one model and may be continued by another. When Claude Code resumes with --resume or --continue, the session continues on the model it was using, apart from a few documented exceptions. Applications that upgrade their model setting still hit this boundary, though. A session that has been compacted resumes from the last compaction's summary plus the messages that followed it (see context compaction), so the new model may be reading a summary of steps rather than the steps themselves. One visible symptom: resumed agents loop on steps that are already finished.
The robust fix is to stop relying on the transcript as the only record of progress. Keep a ledger of completed steps and key decisions outside the conversation and give it to the model explicitly when the session resumes. Anthropic's long-running harness work uses a claude-progress.txt file plus git history so a fresh context window can quickly see where work stands. The memory tool follows the same principle. It runs client-side: Claude requests file operations, your application executes them, and you decide where the data lives.
Then test the cutover rather than assume it. Recorded sessions in a SessionStore can be loaded on any host. Replay a sample of long ones on the new model in staging, and compare which steps it marks complete against the outcomes you stored. Forking keeps the production originals untouched while you do it.
Checkpoint 8 of 9· Check yourself
Before moving a fleet of long-running agents to a new model, your team wants to replay a sample of stored production sessions on that model in staging. The goal is to compare which steps it marks complete against the recorded outcomes. How should staging open each stored session so the production history stays intact?
A fork branches from the stored ID into a new session with its own ID, so the replay cannot add turns to the production transcript. Resuming the ID directly adds the staging turns to the production history, and deleting the session afterwards destroys the original record. Continue just picks the newest session and does not let you choose which sampled session to replay.
“Original session is untouched; resuming it continues the JWT thread”Source: code.claude.com
Checkpoint 9 of 9· Exam question
Amber Analytics runs an agent that prepares multi-day customer reconciliation reports, persisting each session's transcript so work can resume after interruptions. After a model upgrade, some long persisted sessions resumed on the new model now loop on steps that are already finished, and some re-send notices that were already delivered. Short sessions are unaffected. The provider has announced a retirement date for the current model, so every session must be running on the new one soon. Operations holds recorded outcomes for several hundred completed long sessions and has a staging environment that mirrors production. Today, progress can only be inferred from the transcript text, and rerunning finished work is expensive. Select TWO actions that best de-risk the cutover.(Select 2)
Correct answers: A, B — Replay a sample of recorded long sessions on the new model in staging, comparing step completion against the stored outcomes before cutover; Keep a ledger of completed steps and decisions outside the transcript so the new model gets the durable state explicitly in its prompt
- A. Replaying real long sessions on the candidate model gives evidence of resume behavior before users see it.
- B. Externalized state does not depend on how a given model interprets an older transcript, so completed work stays unambiguous.
- C. Models are deprecated on a schedule, so pinning forever only postpones the same problem and leaves a forced migration later.
- D. Discarding all sessions throws away completed work and cost, and it still leaves the new model's resume behavior untested.
- E. A prompt line is untested and unenforced; it may help but cannot replace a ledger or a staged evaluation.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/agent-sdk/sessionsOfficial docs
“Continue finds the most recent session in the current directory. You don’t track anything.”
↩︎ Choosing continue, resume or fork“Original session is untouched; resuming it continues the JWT thread”
↩︎ Choosing continue, resume or fork“connection or process failures yield no result message, so session_id stays None.”
↩︎ Capturing the session ID before anything can fail“Resume takes a specific session ID. You track the ID. Required when you have multiple sessions”
↩︎ Capturing the session ID before anything can fail“Same machine only: the session file still needs to exist on the current machine.”
↩︎ Making sessions outlive the machine“Try an alternative approach without losing the original”
↩︎ One session, one owner“Resume takes a specific session ID. You track the ID. Required when you have multiple sessions”
↩︎ Key concept“Continue finds the most recent session in the current directory. You don’t track anything.”
↩︎ Exam trap 1“connection or process failures yield no result message, so session_id stays None.”
↩︎ Exam trap 2“Same machine only: the session file still needs to exist on the current machine.”
↩︎ Exam trap 3“Resume takes a specific session ID. You track the ID. Required when you have multiple sessions (for example, one per user in a multi-user app)”
↩︎ Checkpoint“Original session is untouched; resuming it continues the JWT thread”
↩︎ Checkpoint - 2.
“forkSession()”
↩︎ Choosing continue, resume or fork“Local containers are ephemeral. An external store survives restarts and redeploys.”
↩︎ Making sessions outlive the machine“During resume, to discover subagent transcripts. If undefined, only the main transcript is restored.”
↩︎ Making sessions outlive the machine“writes its file backups straight to local disk, and the SDK doesn’t mirror them to the store.”
↩︎ A transcript is not proof that work happened“After each batch of transcript entries is written locally.”
↩︎ One session, one owner“Run resumed from the store: the local copy is deleted at run end, so the store holds the only durable copy.”
↩︎ Prediction“Mirror Agent SDK session transcripts to your own object store, key-value store, or database so other hosts can resume your sessions.”
↩︎ Checkpoint“After each batch of transcript entries is written locally. Entries are JSON-safe objects, one per line in the local JSONL.”
↩︎ Checkpoint - 3.https://code.claude.com/docs/en/sessionsOfficial docs
“a tool that was still running when the previous process ended, for example in a crash, doesn’t get rerun when you resume.”
↩︎ A transcript is not proof that work happened“with claude --resume or --continue, the session continues on the model it was using”
↩︎ Surviving a model version change“Claude continues with the last compaction’s summary”
↩︎ Surviving a model version change“a tool that was still running when the previous process ended, for example in a crash, doesn’t get rerun when you resume.”
↩︎ Exam trap 4 - 4.
“Update checkpoint at each prompt you send; a tool result isn't one”
↩︎ A transcript is not proof that work happened - 5.
“The memory tool operates client-side: Claude requests file operations, and your application runs them.”
↩︎ Surviving a model version change - 6.
“quickly understand the state of work when starting with a fresh context window, which is accomplished with the claude-progress.txt file alongside the git history”
↩︎ Surviving a model version change