CertSafari
    Anthropic Claude Certified Developer – Professional (CCDV-P)· Lessons

    Domain 1 · Lesson 2/25

    Durable agent sessions: resume, persist, checkpoint and survive model changes

    Durable Execution and State Management

    17 min read
    4.25% of exam
    6 sources
    Published 19 Nov 2026
    Docs as of 18 Nov 2026

    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.

    Three ways to return to a prior run
    MechanismHow it picks the sessionWhen it wins
    continue: true (TypeScript) / continue_conversation=True (Python)The most recent session in the current directory; you track nothingOne conversation at a time, such as a single-user tool restarted after a crash
    resume with a session IDExactly the session whose ID you passMany 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 IDTrying 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.

    Sources12

    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.

    Reading the session ID from the init message (shown here for a fork, whose new ID first appears there)typescript
      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?

    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?

    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.

    The SessionStore contract (TypeScript)typescript
    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[]>;
    };
    What leaving an optional method out costs you
    MethodIf you omit it
    listSessionscontinue: true throws, because the SDK cannot find the store's newest session
    listSubkeysOnly the main transcript is restored on resume; subagent transcripts are not discovered
    deletedeleteSession() is a no-op, which suits append-only backends
    listSessionSummariesListing 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?

    Sources21

    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:

    Rewinding files to a checkpoint from the command linebash
    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>

    Sources324

    5.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?

    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)

    0 of 2 selected

    Sources21

    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?

    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)

    0 of 2 selected

    Sources356

    Sources

    (6)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “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. 2.
      “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. 3.
      “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. 4.
      “Update checkpoint at each prompt you send; a tool result isn't one”
      ↩︎ A transcript is not proof that work happened
    5. 5.
      “The memory tool operates client-side: Claude requests file operations, and your application runs them.”
      ↩︎ Surviving a model version change
    6. 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

    Ready to test yourself?

    Practise Anthropic Claude Certified Developer – Professional (CCDV-P) in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.