Which field is the load-bearing one in a handoff packet?

next_action (without it, the document is a status report, not a handoff)

Why are handoffs generated, not written?

Hand-written handoffs get skipped on a hard day; the generator reads workbench artifacts and emits the packet, so the agent just leaves the workbench in a state the generator can summarize

Which two forms does the packet ship in?

handoff.md (human-readable) and handoff.json (machine-readable, both from the same source artifacts; JSON wins on divergence)

How does the lesson distinguish compaction from handoff?

Compaction extends a session; handoff closes one cleanly and starts the next in fresh context. The packet is what makes that transition cheap

Compaction is paid, handoff is free

What does the lesson recommend about when to wrap up a session?

Before 50-75% context budget, while context is intact; cheap to write before compression artifacts pollute state

What does the lesson recommend trimming the feedback log to in the packet?

Last K entries plus every entry with a non-zero exit, so the packet stays small while the failure history survives

What metadata makes coordination across multi-agent sessions work?

branch, last_known_good_commit, and status (active | superseded | archived); only one active handoff per branch and topic

Multi-Session Handoff

The session is going to end. The work is not. The handoff packet is the artifact that turns "the agent worked for an hour" into "the next session is productive in the first minute." Build it on purpose, not as an afterthought.

Lesson 40 of 54Build~50 minutesPython (stdlib)

Before this: Lesson 34 of Phase 14 (Repo Memory), lesson 38 of Phase 14 (Verification), lesson 39 of Phase 14 (Reviewer)

On this page

Learning Objectives

Identify the seven fields every handoff packet needs.
Generate a handoff from the workbench artifacts without hand-writing prose.
Trim large feedback logs into a handoff-sized summary.
Make the next session's first action deterministic.

The Problem

The session ends. The agent says "great, we made progress." The next session opens. The next agent asks "where did we leave off?" The first agent's answer is gone. The next agent rediscovers, re-runs the same commands, re-asks the human the same questions, and burns thirty minutes recovering the last thirty seconds of the previous session.

The cost of a bad handoff is paid every session for the life of the task. The fix is a packet generated automatically at session end: what changed, why, what was tried, what failed, what is left, what to do first next time.

The Concept

Seven fields every handoff carries

Field	Question it answers
`summary`	One paragraph of what was done
`changed_files`	The diff at a glance
`commands_run`	What was actually executed
`failed_attempts`	What was tried and why it did not work
`open_risks`	What could bite next session, with severity
`next_action`	The first concrete step next session takes
`verdict_pointer`	Path to the verification + review reports

The next_action field is the load-bearing one. A handoff with everything except next_action is a status report, not a handoff.

Handoffs are generated, not written

A hand-written handoff is a handoff that gets skipped on a hard day. The generator reads the workbench artifacts and emits the packet. The agent's job is to leave the workbench in a state the generator can summarize, not to write the summary.

Two forms: human-readable and machine-readable

handoff.md is what the human reads. handoff.json is what the next agent loads. Both come from the same source artifacts. If they diverge, the JSON wins.

Feedback log trimming

The full feedback_record.jsonl may be hundreds of entries. The handoff carries only the last K plus every entry with a non-zero exit. The next session loads the full log if it needs to, but the packet stays small.

Leave a clean state

A handoff describes the work. A clean state makes the work resumable. They are not the same thing. A perfect handoff.md is worthless if the next session opens to a half-applied diff, a temp file the agent forgot, a stray branch, and tests that error before they even run. The next agent then spends its first ten minutes cleaning up after the last one instead of building, and the cost compounds every session for the life of the task.

So the session does not end when the feature works. It ends when the workbench is in a state the generator can summarize and the next session can trust. Cleanup is its own phase, run before the handoff, and it is a check, not a habit, because a habit is the thing that gets skipped on a hard day.

Check	Clean means	Dirty blocks because
Working tree	Every change committed or explicitly stashed with a note	A half-applied diff looks like intentional work to the next agent
Temp artifacts	No `*.tmp`, scratch dirs, debug prints, or commented-out blocks left behind	Stray files pollute the diff and the next agent's mental model
Tests	Green, or red with the failure named in `open_risks`	A silent red test is a trap the next session steps in
Feature board	`feature_list.json` status reflects reality (Phase 14 · 36)	A stale board sends the next session to work that is already done
Branch	On the expected branch, no detached HEAD, no orphan branches	Wrong branch means the next session's first commit lands in the wrong place

The cleanup phase emits a clean_state.json of blocking issues; an empty list is the precondition the handoff generator asserts before it writes a packet. A handoff built on a dirty tree is not a handoff, it is a forwarded mess. The two artifacts pair: cleanup proves the workbench is safe to leave, the handoff proves the next session knows where to start.

wb-handoff-packet

Build It

code/main.py implements:

A loader that gathers state, verdict, review, and feedback into a single WorkbenchSnapshot.
A generate_handoff(snapshot) -> (markdown, payload) function.
A filter that picks the last K feedback entries plus all non-zero exits.
A demo run that writes handoff.md and handoff.json next to the script.

Run it:

python3 code/main.py

Output: a printed handoff body, plus both files on disk.

Production patterns in the wild

Codex CLI, Claude Code, and OpenCode each ship a different compaction story; the structured handoff packet sits on top of all three.

Compaction strategies vary; the packet schema does not. Codex CLI's POST /v1/responses/compact is a server-side opaque AES blob (fast path for OpenAI models); the fallback is a local "handoff summary" appended as a _summary user-role message. Claude Code runs five-stage progressive compaction at 95% of context. OpenCode does timestamp-based message hiding plus a 5-heading LLM summary. Three different mechanisms, same need: serialize what survives compression into a portable artifact. The packet is that artifact.

Fresh-session handoff is not compaction. Compaction extends a session; handoff closes one cleanly and starts the next. The Hermes Issue #20372 framing (April 2026) is right: when in-place compression starts degrading, the agent should write a compact handoff, end the session, and resume in fresh context. The packet is what makes that transition cheap. The mistake is to keep compressing until quality collapses; the fix is to budget for an early, clean handoff.

One active handoff per branch and topic. Multi-agent coordination breaks down on stale handoffs more than on bad model output. Always include branch, last_known_good_commit, and a status of active | superseded | archived. Stale handoffs are archived; only the active one drives the next session. This is the difference between handoff-as-notes and handoff-as-state.

Wrap up before 50-75% context, not at the wall. The hand-written-pattern playbook (CLAUDE.md + HANDOVER.md) reports best results when the session ends at 50-75% context budget instead of 95%. The packet generator runs cleanly before compression artifacts pollute the source state. Cheap to write while context is intact; expensive when the model is already losing its place.

Use It

Production patterns:

Session-end hook. The runtime fires the generator when the user closes the chat. The packet goes into outputs/handoff/<session_id>/.
PR template. The generator's markdown is also a PR body. Reviewers read it without opening five other files.
Cross-agent handoff. Build with one product (Claude Code), continue with another (Codex). The packet is the lingua franca.

The packet is small, regular, and cheap to produce. The cost saving compounds with every session.

Ship It

outputs/skill-handoff-generator.md produces a generator tuned to a project's artifact paths, an end-of-session hook that runs it, and a handoff.json schema the next agent reads on startup.

Exercises

Add an assumptions_to_validate field that surfaces every assumption the builder logged but the reviewer did not score above 1.
Trim the feedback summary differently for failing runs versus passing ones. Defend the asymmetry.
Include a "questions for the human" list. What is the threshold for a question to make it into the packet versus into a chat message?
Make the generator idempotent: running it twice produces the same packet. What needs to be stable for that to hold?
Add a "next session prereqs" section listing exactly the artifacts the next session must load before acting.

Key Terms

Term	What people say	What it actually means
Handoff packet	"Session summary"	Generated artifact carrying the seven fields, both markdown and JSON
Next action	"What to do first"	The one concrete step that starts the next session
Feedback trim	"Log summary"	Last K records plus every non-zero exit
Status report	"What we did"	A document missing `next_action`; useful, but not a handoff
Verdict pointer	"Receipt"	Path to the verification + review reports for traceability

Quick quiz

Which field is the load-bearing one in a handoff packet?
1. next_action (without it, the document is a status report, not a handoff)
2. verdict_pointer
3. summary
4. commands_run
Show the answer
A. next_action (without it, the document is a status report, not a handoff) A handoff with everything except next_action is a status report; the next concrete step is what makes the next session productive.
Why are handoffs generated, not written?
1. Hand-written handoffs get skipped on a hard day; the generator reads workbench artifacts and emits the packet, so the agent just leaves the workbench in a state the generator can summarize
2. Apache 2.0 requires it
3. Generators are faster
4. Generators encrypt better
Show the answer
A. Hand-written handoffs get skipped on a hard day; the generator reads workbench artifacts and emits the packet, so the agent just leaves the workbench in a state the generator can summarize Automation closes the gap between intention and consistency.
Which two forms does the packet ship in?
1. Email and Slack
2. PDF and PNG
3. YAML and TOML
4. handoff.md (human-readable) and handoff.json (machine-readable, both from the same source artifacts; JSON wins on divergence)
Show the answer
D. handoff.md (human-readable) and handoff.json (machine-readable, both from the same source artifacts; JSON wins on divergence) Markdown for humans, JSON for the next agent; both come from the same generator.
How does the lesson distinguish compaction from handoff?
1. They are the same
2. Compaction is paid, handoff is free
3. Handoff requires GPU
4. Compaction extends a session; handoff closes one cleanly and starts the next in fresh context. The packet is what makes that transition cheap
Show the answer
D. Compaction extends a session; handoff closes one cleanly and starts the next in fresh context. The packet is what makes that transition cheap Hermes Issue 20372 framing: write a compact handoff before in-place compression degrades quality, then resume in a fresh session.
What does the lesson recommend about when to wrap up a session?
1. Before 50-75% context budget, while context is intact; cheap to write before compression artifacts pollute state
2. At 100% context, then panic
3. Only after a merge
4. Only at midnight
Show the answer
A. Before 50-75% context budget, while context is intact; cheap to write before compression artifacts pollute state Wrapping up early keeps the generator's inputs clean.
What does the lesson recommend trimming the feedback log to in the packet?
1. Last K entries plus every entry with a non-zero exit, so the packet stays small while the failure history survives
2. Random N entries
3. First K entries only
4. Only the most recent entry
Show the answer
A. Last K entries plus every entry with a non-zero exit, so the packet stays small while the failure history survives Asymmetric trim: failures must survive; trivia at the tail is cheap to keep.
What metadata makes coordination across multi-agent sessions work?
1. branch, last_known_good_commit, and status (active | superseded | archived); only one active handoff per branch and topic
2. A shared Slack channel
3. A central queue
4. Top secret encryption
Show the answer
A. branch, last_known_good_commit, and status (active | superseded | archived); only one active handoff per branch and topic Stale handoffs are the dominant multi-agent failure; status + branch + LKG keep the active set small.

Questions people ask

How do you continue AI agent work in a new session?

Have the agent end each session by writing a handoff file with completed work, remaining tasks, decisions, known problems and next steps. Start the new session by reading that file along with the project's state and task board.

What should a handoff note include?

The goal, what changed, where things stand, what was tested and the results, open questions, risks, and the exact next step. Short and specific beats long and general.

Run the code Read it on GitHub

Next lessonThe Workbench on a Real Repo Previous: Reviewer Agent: Separate Builder from Marker

Lessons from AI Engineering from Scratch by Rohit Ghumare and contributors, MIT license. Notes for owners by Lozo. License