Claude Agent SDK Session Recovery: Resume, Fork, Compact, and Checkpoint Safely

Long-running agents fail in ordinary ways: a worker restarts, a context window tightens, an experiment needs a clean branch, or a task moves to another host. A production recovery design starts by separating two things that are often treated as one: the conversation transcript and the durable work state.

Use the right recovery operation

Choose the operation from the failure mode, not from convenience.

• Continue when the same managed session and its environment are still active. This preserves the shortest path to the next tool call.
• Resume when you need the existing conversation on a new process or later turn. The transcript gives the agent context, but it is not a replacement for durable task artifacts.
• Fork when an agent should test an alternative plan without changing the original trajectory. A fork is useful for parallel diagnosis, prompt changes, or a risky migration.
• Checkpoint when the work must survive a process, sandbox, or host boundary. Checkpointing records the state that another agent or a fresh session can verify and continue.

The Claude Agent SDK session browser example distinguishes resuming a session from forking it: a fork begins with copied conversation history while leaving the original session unchanged. That is a strong default for experiments because operators can compare outcomes without losing the primary path.

Treat compaction as context management, not disaster recovery

Context compaction can preserve a useful summary when a conversation becomes long. It is valuable, but it cannot guarantee that every operational detail needed by a later worker remains available. Anthropic's guidance for long-running agents makes the same operational point: incremental progress and explicit artifacts are more dependable than asking a future session to reconstruct the entire task from context alone.

Before an agent reaches a compaction boundary, write a checkpoint that includes:

1. the intended outcome and current acceptance criteria;
2. completed work, with links or paths to verified artifacts;
3. open decisions, assumptions, and known risks;
4. commands or tests already run, plus their results;
5. the next smallest verifiable action;
6. identifiers for the session, repository revision, data snapshot, and external dependencies.

This turns a handoff from a narrative into an executable operating record. A new session can inspect the repository, rerun the stated checks, and decide whether the next action is still safe.

Design for the environment boundary

Managed sessions can retain conversation history while a session is available, and sandbox checkpoints can preserve environment state for a period. That does not make those environments an indefinite source of truth. A production system should store its important task state in a durable, access-controlled location that can be validated independently of a specific sandbox.

For cross-host recovery, persist a compact task manifest and the outputs it references. Keep the manifest separate from secrets, and record only opaque references for credentials or protected systems. If files are needed elsewhere, synchronize them through the team's approved storage or repository workflow, then verify hashes or tests after transfer.

A simple recovery flow is:

1. Load the latest task manifest and validate its artifact references.
2. Decide whether the work needs continue, resume, fork, or a clean restart.
3. Restore only the minimum inputs required for the next verifiable step.
4. Run the recorded check before making new changes.
5. Write a fresh checkpoint after every meaningful boundary.

Add recovery to agent evaluation

A useful agent evaluation does not stop at whether a task completed once. Exercise recovery scenarios: restart midway through a tool workflow, compact after a long investigation, fork a risky fix, and move the next step to a different worker. Measure whether the agent can identify the latest verified artifact, avoid repeating destructive work, and explain what remains uncertain.

For teams building Claude agents in production, the practical goal is not perfect memory. It is a small, auditable chain of state that lets the next execution make progress safely. ClaudeExperts can help design that architecture, including session strategy, explicit task artifacts, observability, and recovery tests for the workflows that matter most.

Sources

• Anthropic: Effective harnesses for long-running agents
• Anthropic: Build a Claude Agent SDK session browser
• Anthropic: Context editing
• Anthropic: Managed agent events and streaming