Handoff and checkpoints

Status: draft 0.1 (agent-checkpoint/0.1). Fixes friction #19 (no checkpoints on long tasks) and #20 (handoffs pass free text). Reference implementation: agent_index/checkpoint.py.

A checkpoint is the smallest record that lets a task resume after a failure. The same record is what one agent should hand to another, in place of a long free-text summary.

Record

{
  "format": "agent-checkpoint/0.1",
  "task_id": "tide-report-2026-11",
  "goal": "Write a one-page tide pool report for the newsletter",
  "done": ["Found 6 sources", "Drafted sections 1 and 2"],
  "next": ["Draft section 3", "Check every figure against its source"],
  "state": {"sources": ["https://coast.example/tide-pools"], "word_count": 540},
  "artifacts": ["drafts/tide-report.md"],
  "notes": "The marine station data is from summer 2025 only.",
  "step": 4,
  "saved_at": "2026-11-09T08:02:11Z"
}

Field	Meaning
`goal`	The outcome, in the requester's words. Never rewritten by later steps.
`done`	Steps finished, oldest first.
`next`	Steps left, in the order the agent plans to do them.
`state`	Small structured data the next step needs: ids, URLs, counts, decisions. Not page text.
`artifacts`	Files or URLs produced so far.
`notes`	Caveats the next agent must know.

Rules

Save after every step that would be expensive to redo.
Writes are atomic (write to a temp file, then rename), so a crash never leaves half a checkpoint.
A receiving agent reads goal, next and notes first and does not need the sender's transcript.
Page content goes in the shared cache, referenced by URL in state, never pasted into the record. The receiving agent fetches it from agent-index for free.