Why I retired the orchestrator subagent in Claude Code — three structural constraints from the official harness spec
Introduction
When I first put together a configuration that splits work across several AIs, one of the roles I placed was the “dispatcher”. It decides who gets what and in what order, verifies the result, and passes it on — close to a project lead on a human team. Inserting a tier of AI dedicated to that role looks reasonable intuitively.
Run it in practice, though, and the role turns out to be structurally unable to function. And the grounds for that are not taste or hunch: they are stated plainly in Claude Code’s official specification (the harness spec). This article lays out three reasons for retiring the dispatcher, and records a small but not-to-be-overlooked error I found weeks later when I re-checked my own explanation against the original.
Defect 1: no means of checking with the owner
The operating rules I had given the dispatcher included the sentence “when unsure of a judgement, check with the owner”. Reasonable-looking, but the official spec says:
The first filter removes these tools, even when listed in the
toolsfield:
AskUserQuestion
The tool for putting a question to the owner is removed across the board, even when written explicitly into the subordinate AI’s tool allow-list. That is, “check” does not exist as an option at all. An instruction to “ask when unsure” was, to a counterpart with no means of asking, synonymous with “decide for yourself”.
Defect 2: results cannot be received
When does the result of delegated work come back? The official explanation runs:
As of v2.1.198, subagents run in the background by default.
A background subagent’s results reach Claude as a completion notification in a later turn.
The default execution mode is “background” — move on without waiting for the result, and the report arrives in a “later turn”. The problem arises when the delegating side is itself a subordinate AI. When the dispatcher throws work further down, the report should arrive in the dispatcher’s “later turn”; but the dispatcher ended its own turn the moment it threw the work, and there is no one anywhere to receive it. This shape actually occurred several times, with work stalling and no report arriving.
Defect 3: reports cannot be verified
The dispatcher’s definition did not include the tool for checking state itself (permission to run shell commands). So even when a subordinate AI reported “done”, there was no way to corroborate it and no option but to pass it upward as it stood. In practice, against a report of “I had a branch created”, the measured counts of changed files, branches, and commits were all zero.
There were grounds outside the structure as well
Separately from the three defects, a text Anthropic itself wrote about harness design carries a sentence that makes a dispatcher design hard to support.
Separating the agent doing the work from the agent judging it proves to be a strong lever … tuning a standalone evaluator to be skeptical turns out to be far more tractable than making a generator critical of its own work.
Out of the box, Claude is a poor QA agent. In early runs, I watched it identify legitimate issues, then talk itself into deciding they weren’t a big deal and approve the work anyway.
A dispatcher easily ends up standing where it does both “have the work done” and “verify it”. But by the official observation, letting it evaluate its own output means it talks itself out of legitimate issues and approves the work anyway. Separating the working agent from the judging agent is itself the lever that works, and a configuration loading both onto a single dispatcher faces the opposite way from that finding.
The design that was retired
On the strength of the three structural defects and that finding, I removed the dispatch-only role itself and went back to a form in which the delegating side directly directs the executor and the verifier. I also adjusted the safety device’s scope so as not to needlessly block executions originating from subordinate AIs.
2026-08-06: the design that delegates work via a single "dispatcher"
│
├─▶ defect 1: cannot ask the owner
│ └─ the tool for checking is removed unconditionally from every subagent (official)
│
├─▶ defect 2: cannot receive results
│ └─ the default execution mode is "the result arrives in a later turn"
│ └─ when the dispatcher is itself a subagent, no destination exists
│ (return edge: it actually stalled several times, with no report)
│
└─▶ defect 3: cannot verify reports
└─ the dispatcher's definition holds no shell-execution permission
└─ no option but to pass "done" straight upward
│
▼
+ a further ground: self-evaluation does not work (official harness finding)
│
▼
retire the dispatcher role. Move to directing the executor and verifier directly
│
▼ …(two weeks later, re-reading the same primary source)
2026-08-19: match, character by character, the explanation I wrote as grounds for "cannot ask the owner" against the official original
│
└─▶ one conditional clause found missing
(return edge: the retirement decision did not waver, but the quotation supporting it was defective)
Measured now — has the dispatcher really gone
Rather than leaving it at description, I checked the current configuration for real. Counting the definition files of the subordinate AIs work is handed to gave the following (measured 2026-08-24; filenames replaced with role labels).
$ grep -H "^model:" <定義ファイル群>
<review-agent-1>.md:model: opus
<work-agent-1>.md:model: sonnet
<work-agent-2>.md:model: sonnet
<work-agent-3>.md:model: sonnet
<review-agent-2>.md:model: opus
<work-agent-4>.md:model: sonnet
<work-agent-5>.md:model: sonnet
<review-agent-3>.md:model: opus
<work-agent-6>.md:model: sonnet
$ ls <定義ファイル群> | wc -l
9
Three verifiers and six workers, nine in total. No dispatch-only role exists as a definition file. The retirement decision is reflected not only in the text but in the actual configuration.
Weeks later, the defect turned out to be in my own quotation
About two weeks after retiring the dispatcher, I had occasion to re-read the same official specification. This time I read it not as “were my earlier judgements correct” but as “how had I been quoting it”, matching character by character against the original.
The explanation I had written as grounds for the retirement said this:
AskUserQuestionis stripped unconditionally from every subagent. The same goes forEnterPlanMode/ExitPlanMode.
The official original, meanwhile, ran:
Agent, when the subagent is at the depth limit; in a fork the tool stays listed but returns an error instead of spawningAskUserQuestionEnterPlanModeExitPlanMode, unless the subagent’spermissionModeisplan
AskUserQuestion carries no condition. But ExitPlanMode carries the condition “unless the operating mode is plan”. Agent carries one too: “only when the depth limit has been reached”. My explanation had lumped those conditional items in as “likewise unconditional”. The retirement decision itself did not waver at its core — the unconditional removal of AskUserQuestion — but the surrounding quotation carried the error of a dropped conditional clause.
Dropping a conditional clause and generalising when quoting a primary source is not a one-off here; it is a type of error that has recurred. Had I kept using an explanation I wrote once without re-reading it, on the grounds that it was “already checked”, I would never have noticed the omission.
Deciding to retire something is not the end of it
Removing the dispatcher tier resolved the structural problems of reports not arriving and claims not being corroborable. But re-verifying the explanation that supported that decision showed that the understanding of the structure can be correct while the sentence expressing it carries an error. A decision and the text recording that decision have to be verified separately.
I cut a tier not because the role was underpowered. “Hand it to a person when a judgement is needed” was structurally impossible from that position — it was an error of placement, having given command to a role that could not do it. So far nothing has gone wrong for having retired it.