baton is a tool I've been building for two months. You talk to one Claude Code session, the conductor, and it runs a team of other agents for you: a researcher, a planner, a principal engineer, an implementer and a reviewer. Every goal starts with a proposal I approve. After that the team delivers it as reviewed commits on one branch, and the session stops with a one-page guide before anything gets pushed.
This post is about what went wrong along the way. Most of the code in baton isn't there to make agents smarter. It exists because agents skipped a step, waited on something that was never going to finish, or burned money in a way I only noticed afterwards.
The first version was a tmux script. Each role ran in its own pane, and a handoff meant typing a prompt into the next pane. Within a week I'd swapped tmux for herdr (a multiplexer that can tell you whether an agent pane is idle or working) and swapped a markdown backlog for kata, an issue tracker with a CLI and a --blocked-by dependency graph. Handoffs became kata comments, and a script called baton-handoff typed the next prompt into the target pane.
Treating a terminal as an API produced bugs:
.dispatch-state/<role>.queue), with bounces pushed to the front and state changes serialized by an mkdir lock./clear raced the payload./clearBody: ... as a single line. The item was marked as delivered even though nothing had started. Now the courier waits for the pane to go idle after baton-handoff ran inside the calling agent's shell while that agent was still mid-turn. Codex's sandbox can't reach herdr's socket and kills detached child processes, so handoffs from a Codex pane silently went nowhere. The fix was to move delivery out of the agents entirely. baton-courier process, started by baton start outside every sandbox, delivers whatever is at the head of the queue.
By that point I had a small distributed system whose transport was keystrokes, and no single piece of it was the hard part. The hard part was getting agents to follow a process.
On 13 October the implementer and the reviewer passed one backlog item back and forth, a handoff every 6 to 12 seconds, until I noticed. Every review the reviewer wrote said PASS.
Here's what happened. The item was small, so the conductor skipped the researcher and principal and sent it straight to the implementer. That was allowed. But the feature workflow depended on two bookkeeping commands:
baton-item start <item> # record the commit the item starts from
baton-item complete <item> "<verification>" # record the commit the item ends at
When an item went through the full pipeline, start ran at dispatch. On the shortcut path nobody ran it, and the implementer never ran complete either. So when the reviewer's PASS went through the gate, the gate refused it:
verify_item() {
local item="$1" history="${2:-unchanged}" completed reviewed
completed="$(item_value "$item" completed_commit)"
reviewed="$(item_value "$item" reviewed_commit)"
[ -n "$completed" ] || { echo "item $item has no completed commit recorded" >&2; return 1; }
[ "$(item_value "$item" verdict)" = PASS ] || { echo "item $item has no recorded PASS for its latest completed commit" >&2; return 1; }
[ "$reviewed" = "$completed" ] || { echo "item $item was reviewed at ${reviewed:0:12}, not its completed commit ${completed:0:12}" >&2; return 1; }
...
}
The failed gate turned the reviewer's handoff into status: blocked, route: implementer, with no reason attached. The implementer saw "blocked", looked at its work, decided it was done, and handed off "done" again. The reviewer reviewed again, passed again, got blocked again. Each agent behaved correctly given what it could see, and no rule in either prompt said "if this keeps happening, stop".
Fixing it was worse than the loop itself. The implementer ran baton-item start after the work was already committed, so the recorded start was HEAD. Then complete refused with "item has no commit on the session branch yet", which was true, because start and HEAD were the same commit. There was no way to back-date a start, and the implementer (correctly) wouldn't hand-edit the state files. In the end it made one small, real follow-up commit on top so complete had something to record. Dozens of kata comments had piled up on the item before anyone stepped in.
The incident report lists seven lessons. The one that changed how I build everything since is this:
A rule that lives only in a prompt is eventually skipped.
The conductor prompt said to run start at dispatch, and the conductor skipped it on a path the prompt didn't spell out. So the next big feature (the proposal phase) put its rules into baton-handoff itself. During a proposal, a handoff to the implementer exits with code 3 and the message "the proposal phase builds nothing". A second critique in the same round is refused. Since the refusal happens in the agent's own shell, the agent sees the reason straight away and doesn't need to remember a rule.
baton-item grew into the most important file in the repo. It's 545 lines of bash that record evidence on disk: the commit an item started from, the commit it was completed at, the commit the reviewer reviewed, and the verdict. Commands refuse whenever that evidence doesn't line up:
start refuses during the proposal phase, and it refuses if any other item hasn't passed review yet.complete refuses if the branch no longer contains the item's start commit, or if nothing has been committed since the start.gate refuses if the branch has moved past the reviewed commit.publish refuses unless the owner has approved the exact tip being pushed.
require_unrewritten_history() {
local tip
[ -n "$remote" ] || return 0
tip="$(published_tip || true)"
[ -z "$tip" ] || git_in merge-base --is-ancestor "$tip" HEAD 2>/dev/null ||
fail "pushed history was rewritten: the published tip ${tip:0:12} is not an ancestor of HEAD ..."
}
The error messages are written for the agent that will read them. Each one says what's wrong and what to do next, because an agent that gets a bare "failed" will retry or improvise.
One rule turned out to be too strict. Review fixes get folded into the commit they belong to (git commit --fixup=<sha>, then GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash <item start>), and the reviewer re-checks the result with git range-diff. That means the PR is a series of commits that each have one purpose, instead of "address review feedback" piled on top. But once I'd restacked the branch onto an updated base, final-start refused every item, because no reviewed commit was an ancestor of HEAD any more. With no tool to re-point the evidence, the conductor hand-edited the files under items/ three times in one session, guessing at a mapping for a commit that no longer existed.
The fix was to ask what the check was actually protecting. Before the final review, the ancestry check protects the item reviews. During finalization the final reviewer reads the whole of base..HEAD, and that review is what gates the push. So final-start now requires every item to have a PASS on its completed commit, but no longer requires that commit to be on the branch. start still runs the ancestry check, so a rewrite in the middle of delivery is still caught.
On 30 October I deleted most of what I've described so far. Claude Code had shipped agent teams: one session can spawn teammates and talk to them directly with SendMessage. The courier, baton-handoff, the pane queues, the Stop hook and Codex/omp support all went. The worktree per session, the kata backlog, the proposal phase and baton-item stayed.
That's the part I'd point to if someone asked whether the first version was wasted. The transport was thrown away, but the rules about evidence all carried over.
The new design moved the cost problem somewhere else.
baton has a baton cost command that adds up token use per model from a session's transcripts. Every number below comes from looking at it and asking why.
The conductor read code. Each conductor turn re-reads its entire context at Opus prices, and anything it reads stays in that context for every later turn. A file it reads early in a session gets paid for again on every turn until the session ends. Now the conductor never reads code or diffs beyond git diff --stat. When it has a question about code, it asks a cheap teammate (a reviewer on Haiku, or Sonnet if it needs judgement), which answers in three lines. Teammates message the conductor only at defined check-ins, and idle notices get no reply, because each message wakes the most expensive model in the session.
Even a small CLI quirk added up. kata's close command needs --evidence and a message of at least 40 characters. Without them every session spent two or three conductor turns retrying the close. The fix was a single line in the prompt.
Teammates were reused across items. One implementer that carried over across five backlog items reached a median context of 324k tokens, and that one agent accounted for 12.7% of a day's usage. Now teammates stay warm within an item for its review rounds, and every new item gets a fresh one.
Every teammate compiled Rust from scratch. Each one built into its own target dir and then cleaned it to save disk. In one session the target dirs reached 29, 39 and 198 GiB, and every rebuild took minutes per teammate per review round. Now the whole session shares one CARGO_TARGET_DIR under the session's marker directory, and nobody may clean it. baton remove already deletes the marker dir, so the cache is cleaned once, when the session ends.
A typo fix took 45 to 60 minutes. Every item ran the full test suite twice (once by the implementer, once by the reviewer), finalization ran it twice more, and even trivial items waited for a plan check-in and a full review. Nothing before the reviewer pushed back on over-engineering, so extra work was only caught after someone had built it. Two changes came out of this. Slow suites now run once, in the final review, and each item runs only the fast checks plus the tests that cover the change. And every role works toward "the smallest change that meets the goal": the principal has to trace each part of a design back to an acceptance criterion, and the reviewer flags over-engineering as an important finding.
This was my favourite failure. Two final reviewers and an implementer each started a test run in the background and ended their turn "waiting for it". Nothing wakes an agent when a background process exits. The conductor, asked for status, told me they were still running. For hours.
In the same session, a teammate's wait loop used pgrep -f on a pattern that matched its own command line, so it waited on itself forever. And an implementer ran git reset to move HEAD so a tool would see a range of commits, which is a great way to lose work.
The team protocol now has a section on long-running commands. A job that might outlast one tool call gets started detached, with its log, pid and exit code in files, and the agent waits on it in foreground calls in the same turn:
nohup bash -c '<command> >"$BATON_MARKER_DIR/jobs/<name>.log" 2>&1; echo $? >"$BATON_MARKER_DIR/jobs/<name>.exit"' \
>/dev/null 2>&1 & echo $! >"$BATON_MARKER_DIR/jobs/<name>.pid"
for i in $(seq 100); do
[ -f "$BATON_MARKER_DIR/jobs/<name>.exit" ] || ! kill -0 "$(cat "$BATON_MARKER_DIR/jobs/<name>.pid")" 2>/dev/null && break
sleep 5
done
If the process is gone and there's no exit file, the job was killed, and the agent has to say so instead of waiting. Suites that only fit one run per machine (a browser end-to-end suite, say) run under flock so runs from different sessions queue up. A test failure only counts as "environmental" if it also fails on the session's base commit, checked out with git archive into a temp dir, never by moving HEAD.
In one session in a client's Rust backend, the team ignored the repository's comment rules completely. The repo had an 80-line .claude/rules/01-comments.md. The only way rules reached the team was a "house rules" brief written by a Haiku teammate, and it had cut those 80 lines down to half a line.
Summaries are lossy, and a cheap model summarizing rules loses the very details the rules exist to state. Now baton finds the rule files itself (CLAUDE.md, AGENTS.md and CONTRIBUTING.md at any depth, .claude/rules, .cursor/rules, Copilot instructions, and untracked ones in the original checkout) and lists their paths in the conductor's prompt. The brief is only an index. Teammates read every applicable file in full before touching a matching path, the implementer checks its diff against them before the pre-commit check-in, and the reviewer treats any violation as a blocker.
Even listing the files had a bug. Tracked files like .claude/rules/01-comments.md showed up twice, once from my checkout and once from the worktree, because under en_US.UTF-8 sort and comm disagree on how to order paths that start with a dot, so comm reported tracked files as untracked. Sorting and comparing under LC_ALL=C keeps them in step.
Last week I found that 16 negative assertions in baton's test suite had never been able to fail:
set -e
! grep -q "should not appear" output.txt # passes whether or not the line is there
bash's set -e does not exit on a command whose status is inverted with !. It's in the manual, and I'd still written 16 of these. Each one now ends in || exit 1. It was humbling to find this while writing a tool whose whole point is not trusting a claim that something passed.
The agents are good at the work. Process is where they fall down: running a bookkeeping step on a path nobody spelled out, noticing they're in a loop, remembering a background job, telling a real failure from an environmental one. Every one of those got fixed the same way. The check moved out of the prompt and into a tool that refuses, with an error message written for whoever reads it next.
Then measure. Most of the cost changes in this post came from reading baton cost after a session and asking which agent spent what, and on what. None of them came from guessing beforehand.
baton is on GitHub at dilutedev/baton. The incident report quoted above is in reports/.