Multi-agent control layers & cockpits

You split a feature across three worktrees. Agent one finishes the upload endpoint, agent two wraps the schema migration, agent three fills in the tests. Every diff is green, every diff is clean, and the integrated branch crashes on a runtime error no single agent ever saw. This is a context collision, and it is the parallel-agent version of a merge conflict — except git never flags it, because no two agents touched the same line.

The canonical case: agent A hardens the auth middleware and renames requireAuth to requireAuthenticatedUser; agent B refactors the user type from { id, email } to { id, identity: { email } }. Both pass their own tests, because each only regenerated the tests inside its scope. Merged, the middleware calls a function that exists but passes a user shape that no longer does, and you get Cannot read properties of undefined (reading 'email'). Neither agent ever ran a build containing both diffs.

Worktrees give isolation, not coordination. The fix is a written context contract handed to every agent, with four load-bearing sections: Scope (the exact files each agent owns; everything else is read-only), Interface boundary (the function signatures, exported types, route paths, and schema shapes that cannot change without a sync step), Shared state (a policy for package.json, tsconfig.json, and the migrations directory — one owner, or no agent edits it), and Merge order (a single line deciding who lands first, chosen by which diffs unblock the others). Then merge as a procedure, not a vibe: review each diff against main, merge in the contracted order, run the full suite after every merge, and reject any diff that crossed its boundary rather than hand-patching it. And skip parallelism below the threshold — work one agent finishes in under two hours, or anything touching build, CI, or deploy, is cheaper done serially.

Running one coding agent is a conversation. Running four is an operations problem. A Claude Code session refactors one repo while a Codex session writes tests in another and two more grind through a migration — and the work stops being about prompts and becomes about coordination: which agent is blocked, which is waiting on you to approve a destructive command, and which quietly went off the rails ten minutes ago.

The failure mode builders describe is the alt-tab tax. Each agent lives in its own terminal, and the terminals do not talk to each other. To answer a basic question — is anything finished, is anything stuck — you cycle through windows, scroll back through output, and try to remember which session was assigned what. A terminal shows you a stream of text, not a status. Four streams give you four times the text and no summary. There is no single place that says: agent A is done, agent B is mid-task, agent C has been waiting eleven minutes for you to approve a file deletion.

Chat is the wrong shape for this. What long-running agent work needs is a status board with plain states — idle, running, blocked, needs review, failed, done — each carrying the project, the agent, the current command, elapsed time, and the next possible action. That turns "babysit the agent or forget it exists" into cheap supervision. The unit of attention is no longer the prompt; it is the fleet. The mature version isn't full autonomy — it's a cockpit where you glance once and see who needs you, instead of reconstructing five sessions from scrollback.

Plan-then-execute agents burn tokens faster than chat assistants because they run several inference passes per turn: one to plan, several to execute, more to self-correct. Done well it's worth it. Done badly you get two failure modes. Under-scoped: you say "fix the auth bug," the agent runs 90 seconds, makes 12 file edits, refactors something unrelated, breaks two tests, and hands you a sprawling diff to undo. Over-budgeted: you say "review this 200-line file and refactor," and four minutes later it has reorganized imports, moved a helper, fixed a README typo, and returned 600 lines across nine files. Both burn tokens for results you can't ship.

The pattern that fixes both is scope → plan → cap → verify:

1. Scope the run first, in three sentences: Goal, Files in scope (max 3–5), Out of scope (an explicit list of what not to touch). Twenty-five tokens of scope saves a 5,000-token over-broad run.
2. Force a plan before code: "Output a numbered plan in 5 lines or fewer. Wait for approval." The plan is cheap (~1K tokens) and lets you redirect before the expensive execution phase.
3. Cap the executor: "Maximum 3 file edits. If you can't finish in 3, stop and explain why." A soft cap makes the agent decide consciously instead of drifting.
4. Verify cheaply: "Run only the tests in auth.test.ts and report failures" — naming which tests avoids a 30–180 second full-suite run and the token cost of digesting its output.

Then run a weekly token-burn audit: pull the last 20 agent runs, bucket by token consumption, and look at the prompts behind the top 20%. They almost always lack a Files-in-scope / Out-of-scope clause. Two situations justify relaxing the discipline — genuinely exploratory tasks, and repo-wide migrations where traversal is the point — but there, set a session token budget instead of a file-count cap.

Multi-agent coding workflows rarely fail because the model is weak. They fail because the handoff is vague. One agent explores, one plans, one writes code, one verifies — and it sounds efficient until the executor starts guessing what the planner meant, or the verifier finds the task quietly changed halfway through. The fix isn't a longer prompt; it's a standard handoff that reads like an execution contract. The executor should read it in under a minute and know four things: what outcome matters, what is in scope, how success is verified, and what must not change. Any missing piece gets filled with assumptions — and that's where the expensive mistakes start.

A complete handoff has these sections:

• Goal — one sentence naming an observable result ("return 400 with password_required when password is missing"), not a topic area.
• Why now — the concrete failure or user-facing consequence, so the task doesn't drift into abstract cleanup.
• Files in scope — the highest-leverage line; naming two exact files bounds the search area, while "the login flow" authorizes a repo walk.
• Out of scope — "no schema changes, no refactors"; this is what stops the helpful side quest.
• Current state — evidence, not theory: what was reproduced, what the stack trace showed, what the tests don't cover.
• Required change — diagnosis turned into concrete actions.
• Verification — operational checks ("run the auth test file; send a login request without a password, expect 400"), not "make sure it works."
• Done criteria — what finished looks like, which is different from what to run: an executor can pass a test while changing five extra files.
• Open questions — the stop-sign section: "if this needs a schema migration, stop and escalate."

Not every task needs the split — skip it when the job is tiny, or when one agent already has all the context. The bar isn't "did the planner think hard," it's "could a different agent execute this cleanly on the first pass."

AI coding sprawl is different from ordinary terminal sprawl because each tool claims its own terminal. Claude Code needs a persistent session, Codex wants its sandbox, and your manual debugging still happens in plain zsh. Multiply by the repos you touch in a day and the tab count doubles. Twelve tabs, three repos, one brain trying to remember which tab belongs where. The symptoms are specific: wrong-repo commands (you git push in the infra terminal thinking you're in the API repo), lost session state (which tab had the bug investigation from twenty minutes ago?), invisible active work (three sessions running — one finished, one looping, one waiting on you, and you can't tell which without clicking through), and context bleed (you paste a stack trace into the wrong agent and it starts "fixing" a repo it shouldn't touch).

Tmux solves naming and layout but not identity — a session named api tells you the repo, not whether the Claude session inside it is still active or what it's working on. The gap is between terminal organization and session awareness. A workflow that holds up today:

1. One tmux session per repo, named after the repo, not the tool. Use windows inside for claude, shell, logs. Never run a coding CLI outside its designated session.
2. Direnv for automatic context — an .envrc per repo sets project env vars, so even a wrong cd swaps your environment to match.
3. Put the session/window name in your prompt ([content-api/claude]) so wrong-repo commands are obvious before you hit enter.
4. Kill idle sessions aggressively — a coding CLI idle for over 30 minutes costs you more as ambiguity than the context you'd lose by restarting it.
5. Keep a session-inventory script that lists every active coding session across repos, and run it before starting new work so you reuse an existing session instead of spawning another.

The real fix is a workspace contract: one lane per repo, strict naming, automatic context, aggressive cleanup. Boring, and the opposite of sprawl.

If you do serious AI-assisted coding you've probably arrived at the multi-tool setup: Codex for autonomous tasks, Claude Code for chatty refactors, the shell for what neither does well, maybe Cursor in another window. Each tool is good at its slice; the cost is at the seams. You hand a half-finished idea from Claude to Codex and Codex has no context. You finish a Codex task and want to review it in Claude, so you paste the diff and re-explain the goal. You become the human switchboard between agents that each forget the decisions the others made.

The bill you actually pay isn't tokens — it's cognitive debt. Every switch is a context reload in your head: re-explain the task, re-establish what the agent already tried, re-find the terminal output that mattered, re-derive a decision you made an hour ago in another window. People split tools for rational reasons (usage limits, pay-as-you-go shocks, instructions that don't stick), but splitting your context across those tools is the mistake.

What's missing is a handoff layer — a shared substrate that carries what survives the tool change: decisions ("we chose approach X"), current state (branch, files being edited, the error under investigation), next steps, recent shell commands and their output, and the active prompt. It's distinct from a long-lived memory vault: the vault answers "what do you know about me?" (slow, standing context like project conventions in CLAUDE.md or AGENTS.md), while the handoff layer answers "what are we doing right now?" (fast, active context). Partial versions already exist — project files, MCP memory servers, manual "here's where I left off" notes — and the shape people keep converging on is one place the context lives that many tools read. Keep the context out of any single tool and the tool-juggling becomes a billing optimization instead of a cognitive tax.

A coding agent can sound completely confident while skipping tests, ignoring style rules, duplicating another agent's work, or carrying hidden context you didn't mean to include. The answer is not a stronger model; it's a workflow that exposes state. AI coding stops feeling magical the first time a generated app has to survive review, testing, handoff, and production — and at that point you need evidence: what changed, why, what was tested, and where the agent may have acted outside its boundary.

The sharpest version of this is the confident hallucination. Builders running agents across Cursor and Claude Code have watched them produce code that calls Stripe and Supabase endpoints that do not exist — the code compiles, the types line up, it reads like something a careful engineer wrote, and it fails only at runtime against the real API, usually well after the agent reported success. When one agent invents an endpoint you catch it because you're watching; when four commit in parallel, the fake call sits undetected while your attention is elsewhere. The compiler won't flag it, so a truth check against the actual API surface has to run on its own.

What review needs is runtime proof, not a polished explanation: active sessions, files touched, commands run, test output, and a link between the final diff and the run that produced it. That trail also catches false progress — an agent looping through the same search, swapping implementations, or claiming a test passed without showing the command. Without it, review turns into archaeology and every handoff becomes a trust exercise. The useful systems won't be the ones that produce the most code; they'll be the ones that leave the best trail: task intent, repo context, edits, tests, failures, retries, and final verification — enough for a developer to resume the work, review another agent, or explain the change later. Trust should be earned before merge time, while the session is still active, not reconstructed after a customer reports the bug.

Auto-approval is convenient right up until it's unclear what the agent can actually do. Remote commands, package installs, file writes, browser actions, and deployment steps carry very different risks, and a chat transcript can't be the only control plane for that action surface. The pattern developers keep rediscovering is that permissions should be designed, not remembered. One builder running multiple Claude Code, Codex, and Cursor sessions ended up writing a watcher just to catch the approval pauses he was missing across windows; another, after a production soft-launch, landed on a set of bounded-autonomy rules that survived real use: agent-as-first-reviewer, generate-then-curate, strict file and command boundaries, and explicit escalation to a human.

Human-in-the-loop doesn't mean stopping every action — that just trains you to click "approve" on autopilot. It means placing review where the cost of being wrong is high: destructive commands, secret handling, production deploys, schema migrations, and anything that mutates state you can't cheaply undo. Useful guardrails are specific. They distinguish read-only inspection from destructive commands, they make the approval decision visible instead of buried in scrollback, and they let a team declare which tools are allowed in a given project and which steps require a human.

The harness around the agent — the MCP servers, hooks, permission boundaries, and review flows people build by hand — is exactly where this lives, and it's increasingly the real product. A dry-run and an approval gate belong to the harness, not to an individual model's good manners, because the model is easier to swap than the operating layer around it. The point isn't to slow the agent down; it's to stop confusing speed with permission.

Route everything through the strongest model and cost becomes unpredictable while feedback slows down. Route everything through the cheapest and the quality failures just move downstream into debugging. Neither extreme is the answer, and the pressure is real: developers describe hitting a plan's ceiling mid-task and reaching for a second tool, getting a surprise pay-as-you-go bill, and trying to stretch a Claude Pro plan across Sonnet for execution, Haiku sub-agents, and Opus for planning with large context windows. One cloud architect testing a planning-heavy model during a production soft-launch found that planning alone burned far more of a five-hour usage window than the actual coding did — and concluded he needed clearer task-to-model routing, not a different subscription.

The practical answer is per-task routing: hard reasoning to a strong model, mechanical edits to a cheap or local one, and the ability to make that choice per task instead of per subscription. But you can only route well if you can see what each agent is doing and what each task is worth. That means cost has to be a first-class signal, not a month-end surprise — elapsed time, tokens, retries, and usage warnings visible while the run is happening, so you can spot a loop before it becomes expensive. A cheaper model repeating the wrong tool calls is still expensive; a stronger model working on stale context still wastes time.

The other half is not paying twice: prompt-cache behavior, aborted requests, and hidden summarization all quietly inflate the bill, so the workflow needs to show where tokens, time, and retries actually went before you can decide whether the model, the prompt, or the context is the real bottleneck.