Session state, resume and crash recovery

What to do when a long pipeline dies halfway.

4 min read · Lesson 8 of 12 in this domain

There are two different situations that look similar and have opposite answers. If a session crashed, its tail is untrustworthy — a tool may have half-written its result, leaving the transcript in a state the model will read as fact. Resuming on top of that propagates corruption, so you extract what you have verified into a durable checkpoint and start clean. If a session is healthy but the world changed underneath it (files edited out of band), resuming is right — but the agent has no way to detect those edits, so you must name them. Ask yourself: is the session's own record damaged, or merely stale?

• A crashed session's trailing tool results are unreliable — some may be partial or orphaned. Resuming directly on top of that state propagates the corruption.
• The correct recovery is: extract verified findings into a durable structured checkpoint, start a fresh session, and inject the checkpoint — explicitly labelling which items are complete, partial and pending.
• For a clean session where files changed underneath you, resuming is right — but you must name the delta. The agent cannot detect out-of-band file changes and will report stale findings as current.
• Forking is for exploring divergent branches from a known-good point, not for recovering from a failure.
• Do not discard the completed work: dropping the finished items destroys the cross-item context the synthesis step depends on.

Source: Claude Docs — Agent SDK · Independent study aid, not affiliated with or endorsed by Anthropic.