Adding subagents to a coding task feels like adding a review team. One agent checks the requirements, another looks for test bias, and a third verifies the implementation. If every result comes back clean, the work should be safer.
Sometimes the review system becomes the work.
This is a postmortem of an AI coding framework study that spent 6 hours 36 minutes in review loops while the main experiment ran zero times. At least 14 traceable subagent sessions were involved. Related documents and code grew to 4,876 lines. The task pool was marked ready or frozen four times, and its review scope widened repeatedly along the way.
The lesson is not “never use subagents.” The failure was a missing control plane: nobody owned the global objective or the authority to stop. Every reviewer could be right inside a narrow scope while the overall effort still failed.
Four rules would have prevented most of the damage:
- Do not split a task when the worker must repeatedly reread shared decisions.
- Set a global time, review-pass, and re-delegation budget before spawning work.
- Classify new findings as blockers, improvements, or follow-ups.
- Give one coordinator the completion artifact and the authority to finish.
The original goal
The project was preparing a fair task pool for a comparison of AI coding frameworks. The plan was to compare vanilla Codex, Codex with a concise instruction, and several framework workflows under the same conditions. Before running models, the task pool needed answerable prompts, reproducible public tests, defensible scoring, and a private validation boundary.
That preparation was worthwhile. The problem was that “done” kept being refined after the review process had already started. The criteria expanded from “the agent can solve it and the public test is reproducible” to questions such as:
- Is the source issue separated from the accepted solution?
- Does the prompt leak the preferred implementation?
- Does the validator test behavior rather than a file path or symbol name?
- Can structurally different implementations pass?
- Was a required clarification asked before the first code mutation?
- Do the public prompt and private validator measure the same observable contract?
Each question was reasonable. Together, without a change-control rule, they turned every successful review into permission for another review dimension.
The record below is reconstructed from private research logs and Git timestamps. Session names, local paths, private validators, and withheld oracle answers are intentionally omitted. This is evidence of one failure structure, not a failure rate for any product.
The 6-hour 36-minute sequence
| Stage | What happened | Local success | System-level cost |
|---|---|---|---|
| Candidate pool | Public issues and benchmark candidates were screened | Unusable candidates were removed | Research notes and setup constraints grew |
| Answerability review | Prompts, provenance, and public tests were checked | Ambiguity and source errors were found | Prompts and boundaries were rewritten |
| Bias review | Validators were checked for patch and topology bias | Hidden answer leakage was reduced | Validators, fixed test inputs, and evidence multiplied |
| First freeze | The pool was marked ready under the current criteria | Current blockers were cleared | No rule said what could break the freeze |
| Re-review | A new reviewer raised observability, timing, and alternative-implementation concerns | Residual risks became more explicit | The pool reopened and another pass began |
| Repeated freeze | The revised tree was marked ready again | The current review scope improved | No global pass or time limit had been spent |
| Outcome | At least 14 sessions, four freezes, and 4,876 lines | Review artifacts became more rigorous | The primary experiment count remained zero |
“Frozen” meant “no known blocker under the current review scope.” Reviewers could still reopen the pool and propose a wider scope. A freeze became a checkpoint instead of a finish line.
Why locally correct reviews failed globally
1. Local optimization had no global owner
Looking back at the workflow, the reviewers’ local job was to find issues. The project succeeded only when the experiment ran and produced usable results. No role was responsible for comparing the value of another review with the cost of delaying the experiment.
Finding a possible validator bias can be correct. Spending two more hours fixing it delays the first clearly labeled pilot by two hours. We measured review quality, not time to the first experiment.
2. The definition of done moved after each pass
The first freeze did not contain every timing or alternative-implementation requirement added later. A newly discovered good practice was promoted directly to a mandatory gate. Earlier READY decisions were not necessarily wrong, but there was no explicit record of what changed or why the new finding was severe enough to reopen the pool.
3. Re-delegation had no ceiling
A reviewer found a problem, an implementation worker fixed it, and another reviewer reread the result. The new review found another concern and started another cycle. There was no maximum review count, delegation depth, or total time budget. “One more check” had no natural stopping point.
4. The subtasks were not truly independent
Answerability, implementation bias, and validator behavior were different perspectives on the same prompts, tasks, and scoring boundary. Each worker reread the repository and summarized the same assumptions. This was distributed inspection of shared state, not independent parallel work.
5. The error budget was one-sided
Missing a possible bias felt expensive. Delaying the primary experiment did not have a number attached to it. Without an opportunity-cost metric, caution always won, even when the remaining concern was non-blocking.
6. Artifact growth looked like progress
More plans, validator files, and review transcripts created a visible sense of progress. We were watching the rate of artifact growth. The primary metric—first experiment run—did not move. Artifact quality and movement toward the actual outcome needed separate dashboards.
7. There was no freeze-break policy
When a new concern appeared, there was no rule for deciding whether to reopen the pool or defer it. Security, data leakage, and an untestable contract should break a freeze. An extra example or a broader analysis usually should not. We had no severity rule to make that decision.
What the official guidance says
The official documents cited here do not say “delegate more.” They point instead to bounded, independent work and to the cost of coordination when work shares state or follows one chain of reasoning.
OpenAI’s Codex subagent documentation and Multi-agent guide recommend parallel delegation for bounded work such as codebase exploration, document comparison, and independent tests. Each worker performs its own model and tool work, so token use rises too. When work follows one sequence or repeatedly changes shared state, the main agent needs to reconcile and prioritize results. OpenAI’s long-running work guidance makes the adjacent point: write the outcome, constraints, and verification criteria down together.
Claude Code’s official subagent documentation keeps quick targeted changes, frequent back-and-forth, and tightly coupled phases in the main conversation. It places verbose, independent investigation with subagents. That distinction maps directly onto this incident.
Anthropic’s context-engineering guidance treats context as a finite resource, while its long-running harness article recommends progress records and structured artifacts between sessions. The point is not to keep adding workers; it is to keep the next worker from misunderstanding the work already done. A preprint study reaches a compatible, narrower conclusion: the value of multi-agent coordination depends on task structure. It is not a coding-project failure-rate estimate.
Prevention: write the delegation contract first
If these questions do not have answers, keep the work in the main conversation until the task is decomposed more clearly.
| Control | Decision required before delegation |
|---|---|
| Independence | Can the worker finish without repeatedly reading another worker’s decisions? |
| Owner | Who alone can declare the whole task complete? |
| Budget | What wall-clock, interaction, and review-pass limits apply globally? |
| Re-delegation | Can a worker spawn another worker? What is the maximum depth? |
| Finding class | What makes a result a blocker, an improvement, or a follow-up? |
| Freeze break | Which evidence and severity are allowed to reopen the design? |
| Completion artifact | What exact summary, patch, test result, or decision must return? |
There is no universal number for every repository. A conservative starting policy is one implementation pass plus one independent review. A second review requires a new, evidenced blocker and explicit coordinator approval. When the budget ends, return the known residual risk to a person instead of silently extending the run.
Delegation contract template
Objective: [one bounded outcome]
Allowed scope: [files or sources the worker may read or change]
Out of scope: [features, modules, and new review criteria not allowed]
Dependencies: [decisions and inputs that are already fixed]
Budget: [wall-clock time] / [max interactions] / [max re-delegation depth]
Re-delegation: prohibited; return any blocker with direct evidence.
Completion artifact: [summary, changed files, test command, and result]
Stop conditions: stop when the artifact is complete, scope expands, or the
budget is exhausted; return control to the coordinator.Detection: signs that the loop is overheating
Stop adding reviewers when several of these signals appear together:
- plans and review records grow faster than the implementation diff;
- multiple agents reread the same files and run the same validation;
- READY and NOT READY alternate without a changed primary requirement;
- the main metric—first run, first patch, or first deployment—does not move;
- every rereview covers a wider scope than the previous one;
- summaries contain new work but no completion decision;
- agents or background processes remain active after their result was consumed.
These signals do not prove that a worker failed. They show that the coordination layer is becoming more expensive than the task.
“Keep going until done” is especially dangerous because it grants permission to repeat without defining what done means. Pair it with a time cap, a maximum iteration count, a no-diff stop rule, and a condition for returning control to a person.
Recovery: what to do after the loop starts
- Stop new delegation and re-review requests. Do not create more work while diagnosing the loop.
- Inventory the current state. List active agents, processes, artifacts, and unresolved findings.
- Restate the original outcome. In this case: create a task pool, pass minimum validation, and run the experiment.
- Classify every finding. Separate experiment-blocking evidence from non-blocking improvements and follow-ups.
- Assign one completion owner. That person can reject scope expansion.
- Verify only remaining blockers and the completion artifact. Do not replay already-passed review dimensions.
- Resume the main task first. Open optional improvements after the first run, patch, or deployment.
- Turn the failure into a durable rule. Add the missing budget and stop condition to the next delegation contract.
Stopping here does not mean deleting logs or destroying workspaces. Preserve useful evidence, identify live processes, and close or steer work only after its state is known.
Review result template
Verdict: READY | BLOCKED | READY WITH FOLLOW-UPS
Verified directly:
- [file, command, or output]
Blockers:
- [none, or reproducible evidence]
Non-blocking improvements:
- [work that can wait]
Unverified assumptions:
- [what was not checked]
Is another review justified: yes/no
If yes, name the new blocker and the maximum review scope in one sentence.Coordinator stop rule
Close the loop when any of these is true:
- the agreed completion artifact passes;
- a new finding has no direct blocker evidence;
- the maximum review pass or time budget is reached;
- the next review repeats a dimension already verified;
- resolving the new concern costs more than its risk class permits.
Main agent or subagent?
| Question | Main agent | Subagent |
|---|---|---|
| Dependencies | Planning, implementation, and tests share decisions | Results are independent |
| State | The same files or shared state change frequently | Read-heavy work or an isolated worktree |
| Output | Intermediate judgment must shape the next step | Large logs or documents can return as a short summary |
| Interaction | The user needs frequent back-and-forth | The worker can finish without clarification |
| Latency | A fast targeted edit matters | Parallel execution clearly reduces wall-clock time |
| Completion | A person decides immediately with the agent | A concrete artifact and verification command exist |
The official OpenAI and Claude Code guidance converges on this table. Use subagents for independent exploration, testing, triage, summarization, or comparison. Keep tightly coupled planning, implementation, and testing together. If workers must communicate continuously or edit the same shared state, the coordination design deserves as much attention as the model prompt.
Frequently asked questions
How many subagents should run at once?
Count independent workstreams first, then estimate the cost of merging their results. Add workers only when parallel execution and context isolation clearly beat a single agent’s sequential run. “More” is not a budget.
Should every implementation have an independent review?
Not necessarily. A small, well-tested change may need only the main agent and a quick human check. Increase review budget for security, data migration, or public API changes where failure is expensive. Repetition is not the same as coverage.
What should happen when a new issue appears after freeze?
Classify it before reopening. Data leakage, an untestable contract, or a failure that invalidates the experiment is a freeze-breaking blocker. Additional examples, wording improvements, and broader analysis belong in follow-ups. A freeze that every reviewer can break is not a freeze.
How do I safely stop an existing runaway loop?
Stop new delegation, inspect active agents and processes, preserve logs and artifacts, and let one coordinator recheck only the remaining blockers. Avoid broad deletion before the recovery evidence is understood.
Conclusion
AI coding frameworks and subagents are not quality bonuses layered on top of a model. They are control mechanisms that spend time, context, and interaction to reduce a particular failure.
In this incident, the missing ingredient was not another reviewer. Everyone could find problems; nobody could finish the whole task. The next design should therefore begin with the outcome and minimum completion criteria, delegate only independent work, budget reviews, classify new findings, and give one coordinator the authority to close the loop.
Add a subagent only when isolation removes more coordination than it creates—and decide who can end the work before you delegate it.
Sources and further reading
Official documentation
- OpenAI Codex subagents — independent work, context isolation, token cost, and read-heavy versus write-heavy workflows
- OpenAI Multi-agent guide — bounded parallel delegation and the cost of sequential or shared-state work
- OpenAI Codex long-running work — outcomes, constraints, verification, and context ownership
- Claude Code subagents — when to keep work in the main conversation
- Claude Code parallel agents — subagents, agent teams, and worktree isolation
- Anthropic: Effective context engineering for AI agents — finite context and iterative curation
- Anthropic: Effective harnesses for long-running agents — progress artifacts between sessions
Research
- Towards a Science of Scaling Agent Systems — how task structure and coordination topology change multi-agent outcomes