Context Handoff

Context Handoff

Context Handoff keeps a short, structured note for every Board card, so the next round or session starts in context at the lowest cost. Instead of always replaying a long session history, the runner can start a fresh session from the note when that is cheaper. It is on whenever Token Saver is on; there is no separate switch.

Overview

• Every card — and every design build or planner turn — has one handoff note.
• The agent keeps the note current at key moments: after the plan, after a decision, after a commit, and before it stops.
• If a session died without a fresh note, the runner writes one from the transcript with a local haiku model, so session content stays on the machine.
• Before each round, the runner prices resume against fresh from the note and picks the cheaper one.
• An operator can edit the note to steer the next round.

The note

A note is Markdown with these ## sections, in this order, and at most about 3,000 tokens:

1. Goal
2. Done
3. Next
4. Decisions and why
5. Dead ends
6. Files touched
7. How to verify
8. Checklist status
9. Open questions

A note that misses a section, repeats one, is out of order, has an empty Goal or is too large is refused with the reasons, and the agent rewrites it.

The note lives in the card's worktree as .agentdock/handoff.md (git-excluded). Only a project with session content on also sends a copy to the server.

How the next round starts

flowchart TD
  N["New round of a card"] --> E["Runner estimates the first turn both ways"]
  E --> R["Resume: whole session history<br/>(cache read if warm, uncached if cold)"]
  E --> F["Fresh: the note + diff summary<br/>+ checklist status + card prompt"]
  R --> C{"Which is cheaper?"}
  F --> C
  C -- "resume" --> RS["--resume the old session"]
  C -- "fresh" --> FS["New session started from the note"]

Loading

1. Before a round, the runner estimates the cost of its first turn resumed and fresh.
2. It picks the cheaper one and stores both estimates on the round.
3. It never discards the old session — it can still be resumed later.

A warm cache and a short history resume; a cold cache and a long history start fresh from the note.

Keeping the note fresh

The runner checks the note at every stop and right before Claude Code compacts the session (the plugin's PreCompact hook). A note older than the round's last commit is stale, and the agent is asked to update it once per round:

• At a stop, the request is typed at the agent's prompt.
• Before a compaction, the request comes with the note in the context Claude Code adds right after compacting. The stops of that round do not ask again.

Design builds and planner turns

A design build or planner turn runs headless and read-only, so its agent does not keep a note. When one is interrupted — killed, cancelled, timed out or failed — haiku writes a note from its stream. The next attempt at the same work that starts a new session starts from that note. A planner turn that resumes its session already has the context and is not given the note. A run that succeeds clears it.

Using it

• Card sheet › Handoff shows the note's sections, who updated it (the agent, haiku or a person) and when. Lines a person wrote are highlighted. With session content off, the section says the note is kept on the machine.
• Card face chip — resumed from handoff · saved ≈ $x when the runner started a fresh session from the note, or resumed session when it used --resume. A card's first round has no chip.

Steering a round by editing the note

1. Open the card and go to Handoff.
2. Click Edit, change the note, and click Save note.
3. The next round starts from your version.

Lines you add or change are marked as yours, and the agent never rewrites them — it keeps them verbatim when it updates the note. Write an instruction there ("do not touch the migration", "next: only the API tests") and it stays.

Note

Edit needs the project to ship session content, a card that already has a worktree (its first round writes the note), and an online, up-to-date runner.

The save says	It means
not edited: session content on the machine, or no worktree	nothing on the server to edit, or the first round has not run yet
not saved: does not follow the format	fix the listed sections and save again
runner offline or too old	start or update the runner, then save again
runner could not apply the note	the runner answered with an error; the note is unchanged

In your own terminal

A Claude Code session you start in a card's worktree or branch receives the note through the nautelle plugin's SessionStart hook. track_card on that card returns it, and the resume_context MCP tool returns it on demand — read from the machine, so it works with session content off. See Claude Code Integration.

See also

• Token Saver · Steward · Claude Code Integration
• User guide: docs/guides/context-handoff.md

Decisions: ADR-0042 · Spec: #449, #494