Handoff

You hand off work to hands — and any future session can pick up the handoff.

A token-tiered delegation protocol for agent harnesses. The lead model (the "brain") only designs, writes dispatch specs, and adjudicates evidence; cheaper executor models (the "hands") burn the execution tokens. Every dispatch is a spec file on disk — the prompt you send is the permanent record — and a STATE.md ledger makes any run resumable by a fresh session with no transcript. The name is the protocol: hand off execution to cheaper hands (token tiering), and leave a handoff any session can resume (lossless continuity).

Handoff is a usage protocol over mechanisms your harness already has (subagent spawn + a per-spawn model override), not a framework you install and import. It ships with the full pre-registered evaluation that produced its design — including the experiment where dispatch lost. Read section 3 before adopting: the honest answer is "it helps above a measured task-size threshold and costs more below it."

Built and validated on Claude Code, portable to any harness with the two primitives above (docs/porting.md).

How work routes

The protocol is a decision tree over one question: who should do this unit of work, and does it warrant the spec-file ceremony?

                          incoming work unit
                                  │
        ┌─────────────────────────┼──────────────────────────┐
        ▼                         ▼                           ▼
 design · spec ·           ≤5-line trivial              real execution
 adjudication              edit                         (read files, write
        │                    │                           code, run tests)
  BRAIN keeps it       BRAIN edits inline                       │
  (its actual job)                                ┌─────────────┴─────────────┐
                                                  ▼                           ▼
                                          below break-even            at / above break-even
                                          (<~200-line artifact        (≥200-line artifact OR
                                           AND <~500-line read)        ≥500-line read, or must
                                                  │                     survive handoff, or
                                          solo is cheaper               parallel hands)
                                          (+4.4% if dispatched)                │
                                                                     hand off to HANDS
                                                                     (model REQUIRED per spawn):
                                                                     ├─ Agent(opus)  ← default
                                                                     ├─ codex exec   model diversity
                                                                     ├─ async queue  >30 min / cross-repo
                                                                     └─ claude -p    third-party overflow

Hands that enter the full DISPATCH ceremony — because the work is above the measured boundary, handoff-bound, multi-dispatch, or parallel mutation — start cold and work from the file. Below-threshold tactical spawns and read-only consultations may instead use inline prompts under the skill's documented exceptions. Every hand still returns evidence, and the brain adjudicates on that evidence without re-reading the work.

---

1. The problem

Two failure modes show up the moment you use subagents for real work:

• Flagship quota burns on execution. Most harnesses default a subagent spawn to the session's lead model. If your interactive session runs a flagship model, every "go read these six files and implement X" spawn runs on the flagship too — you pay top-tier rates for file-reading and boilerplate that a strong non-lead model would do just as well. An omitted model parameter is the silent tax: it inherits the lead model and you never notice.

• Ad-hoc orchestration leaves no audit trail. When the plan, the sub-prompts, and the decisions live only in one conversation, the work dies with that session. A new session (or a teammate, or the same person tomorrow) can't pick it up without you re-explaining everything. There is no ledger, so there is no handoff.

2. What handoff is

One protocol, three guarantees:

1. Dispatch = spec = record. The prompt sent to a hand is a file on disk (dispatch/NN-name.md): Context (self-contained — the hand starts cold), Task, Constraints, pre-written Acceptance Criteria, Verify commands, and a mandated Evidence-return format. Writing the prompt and writing the record are the same act — zero extra documentation friction.

2. A STATE.md ledger is the single source of truth. Goal / Now / Done / Todo / Blockers / Decisions / Next-Session-Entry-Point. A fresh session resumes from STATE.md + the non-accepted dispatch/* files alone. No conversation transcript required.

3. Flagship-floor model tiering. Never spawn the lead model as a hand (that defeats the entire point); pick the strongest non-lead model that 100% covers the task's purpose — capability-first, because one rework round costs far more than the per-token price delta. The model parameter is required on every spawn.

Not the OpenAI Agents SDK's handoffs (peer-to-peer control transfer between agents). Here, handoff means two specific things: offloading execution DOWN a model tier, and passing work FORWARD across sessions via the ledger.

And one discipline that keeps it from becoming ceremony theater:

• Ceremony only above the measured break-even. The full DISPATCH-file protocol is worth its fixed cost only when the task is big enough (~≥200-line artifact or ~≥500-line code-read), must survive a session handoff, or runs parallel hands. Below that, a plain inline spawn (still with an explicit model) is cheaper, and the git commit is the audit trail. Handoff is a ceremony you enter when scale warrants — see the evidence for exactly where that line sits.

The brain adjudicates on returned evidence, never by re-reading the hand's work — it re-runs at least one Verify command (Iron Law: no evidence, no accept) and, for high-risk diffs, dispatches a read-only reviewer over the full change.

3. Evidence

Handoff was pre-registered and evaluated before this repo existed. Thresholds were locked in eval/EVAL_PROTOCOL.md before any run, so post-hoc reinterpretation isn't possible. The full protocol, running log, and report are in eval/; two real dispatches are in eval/worked-examples/.

Experiment	Pre-registered bar	Result
E1 token economics — small task (≤175-line artifacts)	brain output −40%	FAIL direction: +4.4% — dispatch cost more (7,218 vs 6,915 brain-output tokens)
E1 token economics — large task (219–330-line artifacts, 570–730-line reads)	brain output −40%	PASS: −68.6% (8,030 vs 25,612 brain-output tokens)
E2 handoff losslessness — blind relay	≥9/10 state answers + zero redone work + zero rescue	PASS: 9/10, zero redone accepted work, zero user rescue
E3 output quality floor — blind, both pairs	dispatched ≤1 grade below solo on any dimension	PASS: dispatched ≥ solo on every dimension; the only concrete defects were in the solo artifacts

The break-even is the headline finding, not a footnote. Dispatch carries a fixed brain cost (~5–8k tokens to write the spec + adjudicate + update the ledger). That cost is dead weight on small tasks and amortizes decisively on large, code-reading-heavy ones. On these two data points the crossover sits near ~200 lines of artifact / ~500 lines of code-read. Below it, do the work solo. Above it, dispatch.

Honesty notes (read before quoting any number)

• Total tokens go UP, by design. The large-task run burned ~44k total tokens (8,030 lead-model + ~36k hand) versus ~25.6k for the solo baseline. Handoff's claim is lead-model offload + brain availability during execution, not total-token thrift. If your cost model is dominated by total tokens rather than by which model burns them, handoff is the wrong tool (see section 4). The blended-dollar verdict depends on your lead:hand price ratio — we recorded the break-even formula but make no dollar claim.

• Small n (n=2 pairs). Do not extrapolate magnitudes. Two pairs, one per scale point, same-session timestamp slicing, a cross-language large pair (bash vs TypeScript), and a read-burden asymmetry that mildly favored the thesis (all disclosed at pre-registration lock). The direction is consistent; treat "+4.4% small / −68.6% large" as "fixed-cost penalty on small tasks, multi-x saving on large ones", not as portable constants.

• A measurement erratum — kept in, because it's a feature of the method. The first instrument summed raw transcript rows; one API turn writes one row per content block, so it inflated lead-model totals 3–5× (and naive dedup would have undercounted hands ~500×, since their rows are progressive snapshots). The corrected instrument aggregates per message id taking the max of each usage field. Both pairs were re-derived on the corrected tool; the small-task FAIL direction survived (its magnitude shrank from a misreported +29% to the true +4.4%). The blind quality judge — with no knowledge of the measurement work — independently re-discovered the exact same counting bug in the artifact under review. Convergent validation: two independent paths found the same defect.

Runnable checks

The two executable pieces of the skill — the adjudication helper and the dispatch-gate hook — ship with their own tests. From a clean checkout:

$ bash skill/tests/adjudicate.test.sh
TOTAL: 23  PASS: 23  FAIL: 0
$ bash skill/tests/dispatch-gate.test.sh
TOTAL: 11  PASS: 11  FAIL: 0

The committed eval/ artifacts make the locked protocol, derived results, caveats, and worked examples inspectable. They do not include the private source transcripts, so raw token accounting cannot be reproduced from the public checkout alone. Given a source session transcript, skill/scripts/token-report.sh regenerates the per-model accounting.

4. When NOT to use handoff

• Small tasks below the break-even. A <200-line artifact that needs <500 lines of reading is cheaper done solo (or with a ≤5-line direct edit). The eval measured dispatch losing by 4.4% here. Reach for a plain inline spawn only when you need the brain free for parallel work or you want the spec-first test rigor — not to save tokens.

• Single-session throwaway work. If nothing needs to survive the session and there's no handoff, the ledger earns nothing. Skip the ceremony.

• Total-token-budget-sensitive users. Handoff deliberately spends more total tokens to move burn off the lead model. If your constraint is total tokens (not lead-model tokens or wall-clock parallelism), this trade goes the wrong way for you.

5. Install & adapt

Claude Code:

git clone <this-repo> handoff && cd handoff
bash install.sh

install.sh copies skill/ into ~/.claude/skills/handoff/ (backing up any existing copy first) and prints two snippets for you to paste into your own CLAUDE.md — a trigger row and a model-tiering section. It never edits your settings.json; you stay in control of what your harness auto-loads. Re-running it is safe (idempotent, with a timestamped backup each time).

Any other harness: handoff needs only two primitives — the ability to spawn a subagent, and a per-spawn model override. See docs/porting.md for how to map the four dispatch channels, the DISPATCH/STATE files, and the model-tiering rule onto a non-Claude-Code harness.

Repository layout

README.md          this file
LICENSE            MIT
install.sh         Claude Code installer (prints CLAUDE.md snippets; no settings.json edits)
skill/             the handoff skill (SKILL.md, templates/, references/, scripts/, hooks/, tests/)
eval/              the full pre-registered evaluation (protocol, report, running log, E2 relay files)
  worked-examples/ two real dispatch files, sanitized, as concrete samples
docs/porting.md    adapting handoff to non-Claude-Code harnesses

---

Copyright (c) 2026 Zane Wang. MIT licensed. The evaluation numbers above are real and reproducible from eval/; they are the honest result of a pre-registered test, FAIL directions included.