delegation-protocol
The main thread is a decision-maker with a scarce context window, not a worker.
Everything it reads itself, it pays for on every subsequent turn.
Scope boundary — these compose in sequence, they do not compete:
how to farm work out → here;
whether the result means the task is done →
;
the mechanics of committing → your commit-workflow skill.
When to Invoke
- About to read a lot of files, grep a repo, or look something up.
- About to make the same mechanical edit across many files.
- Something needs verifying or reviewing.
- Writing a prompt for a subagent, or choosing which tier to spawn.
- About to run agents in parallel.
- A subagent just reported back.
- Tempted to suggest the user switch the conversation's model.
- Your last search/grep/read on this exact target (same repo, same symbol,
same file set) didn't fully resolve it and you're about to run another one
— that's the "don't know which file it's in" threshold firing right now,
not a reason to narrow once more yourself.
Core Rules
-
[NEVER VIOLATE] Never run two agents in parallel if both may write to the
same file. Whichever finishes second silently overwrites the first — no
error, no conflict marker, no trace. Parallelise reading and analysis;
serialise writing.
-
[NEVER VIOLATE] When delegating a verification or review, hand over the
artifact and the acceptance criteria only — never your reasoning, your draft
rationale, or your defence of the work.
A reviewer who has read your argument reviews your argument. The entire value
of a fresh context is that it does not already believe you. Anchor it and you
have converted a gate into a rubber stamp — while still paying for it, and
still feeling reassured.
-
Hitting a threshold means delegate, not "consider delegating". The
numbers below are deliberately numbers. A vague threshold never fires.
-
Do not accept a delegated result wholesale. See the last section.
Hard Thresholds
| Situation | Action |
|---|
| You expect to read more than 3 files or more than 400 lines to answer | Search agent |
| You do not know which file the thing is in | Search agent |
| Looking up web pages or official documentation | Delegate |
| The same mechanical change across more than 5 files | Cheap agent executes; you spot-check |
| Any judgement-level verification or review | Fresh-context agent (mechanical checks you may run yourself — see ) |
⚠️ The "don't know which file it's in" row fires the moment a first search
attempt doesn't resolve it — not after several. Each subsequent narrowing
grep on the same target feels like progress; measured against the rule, it's
the same "don't know which file" state repeating. Treat a second attempt on
the same target as the trigger, not a fourth.
"It's faster if I just do it myself" is an illusion at the main-thread level.
It is faster this turn. The context burned is repaid with interest on every
turn afterwards, and the debt stays invisible until the thread starts forgetting
things it was told.
Do not renegotiate a threshold because this case feels like an exception. If a
threshold is genuinely wrong, change it deliberately, with evidence, outside the
task that tripped it.
If This Environment Has No Subagents
Not every harness can spawn agents, and some runs are non-interactive. Then:
- The thresholds become a budget warning rather than a dispatch instruction:
the work still costs context, so do it in the smallest slice that answers the
question, write intermediate findings to a file, and work from the file.
- Judgement-level verification cannot be faked by doing it yourself. Run every
deterministic mechanical check available, then follow 's
"When No Subagent Is Available" procedure in full — starting with
its first step, which is to check whether a human can be the fresh reader
before anything gets downgraded. That procedure is not restated here on
purpose: one copy, one place to change it.
- Never treat the absence of a reviewer as permission to self-certify.
Every Delegation Prompt Needs Three Things
Missing any one, do not send it:
- Goal and motivation — what this is for, and who consumes the result.
An agent that knows why produces a usable answer; one that doesn't produces
a technically-responsive one.
- Acceptance criteria — objectively checkable. If you cannot write these,
you have not thought the task through; that is the finding, not the agent's
problem.
- Reporting format — field by field. "Report your findings" returns an
essay you then have to read, which defeats the point.
The Reporting Contract (paste into every delegation prompt)
- Conclusions only, anchored as .
- Long output goes to a file; report the path plus a three-line summary.
- Copy numbers exactly — never round, rephrase, or tidy a figure.
- "Not found" is a valid answer. Say so plainly; never fill the gap with
something plausible.
- Never paste whole files back.
Choosing a Tier
Think in tiers, not model names — names and IDs change, tiers don't:
| Tier | Use for |
|---|
| Cheap | Mechanical work, inventories, read-backs, bulk edits |
| Standard | Ordinary search, implementation, routine review — and the main thread |
| Expensive | Genuine judgement calls, adversarial review, second opinions |
| Premium | Rare. Confirm before spending it (nobody to confirm with → don't). |
Do not keep a table of exact model IDs, prices, or feature-support matrices in
your rules or skills. It is a copy of vendor documentation: it goes stale
silently, and a stale copy is worse than none because it is believed. Use the
harness's own alias or tier selector where one exists. Where the harness insists
on a concrete identifier and offers no lookup, state the tier you intended and
take the harness default — do not reconstruct an identifier from memory.
Escalation
- Cheap tier fails acceptance once → go straight to standard. No second
attempt: another round-trip plus re-verification costs more than escalating.
- Standard tier fails twice on the same subtask → escalate to the expensive
tier with the full failure trace. Escalating without the trace just buys a
more expensive repetition of the same mistake.
- Once the expensive tier finds the pattern, drop back to a cheap tier to apply
it across the remaining cases.
⚠️ When you need a stronger model, spawn a subagent at that tier — do not ask
the user to switch the conversation's model. On providers that use prompt
caching, switching the main thread's model invalidates the cache, so the whole
conversation history is re-sent uncached on the next call. Measured on one real
session: of 7 observed cache breaks, 6 immediately followed a manual model
switch, averaging ~294k tokens burned per switch (single-session sample, one
provider — the magnitude will differ elsewhere, and on a provider without prompt
caching this particular cost does not apply). A subagent costs only its own call
and leaves the main thread's cache intact. Suggest a manual switch only when the
work genuinely cannot be delegated — it needs continuous back-and-forth with the
user rather than being a self-contained subtask — and weigh the rebuild cost
first.
When the Result Comes Back
- Spot-check one or two load-bearing claims. Any number heading into a
deliverable needs a second source.
- Warning signs: the report is suspiciously clean, or states a key fact you have
never seen first-hand evidence for.
- ⚠️ "X does not exist" is a far stronger claim than "X exists" and needs
correspondingly more evidence — recorded twice in practice, the second time
while writing up the first. Before accepting a non-existence result,
check the search actually covered backup directories, lock files, and
alternate locations — not just the obvious live path. A search that only
proves "not in the place I looked" is routinely written up as "never existed".