Delegation protocol

Delegation is only cheaper than main-thread work if (a) the noisy work happens in someone else's context and (b) the task spec is smaller than the work itself. This protocol enforces both.

1. Task spec template (mandatory for any writing delegation)

GOAL: <one sentence, observable outcome>
ALLOWED FILES: <explicit paths or globs - the writer may touch nothing else>
NON-GOALS: <what must NOT change; include "no refactors" by default>
ACCEPTANCE: <verifiable criteria, bullet list>
VALIDATION: <exact commands: test / lint / build - from CLAUDE.md project commands>
RISK PATH: <yes/no, per CLAUDE.md risk paths. If yes: adversarial review is mandatory>
EXPECTED DIFF SHAPE: <files x approximate size - lets any reviewer spot drift instantly>

If VALIDATION cannot be filled, the project commands in CLAUDE.md are missing: ask the human to fill them before delegating. A spec without validation commands is decorative.

2. Routing table

3. Execution rules

• One writer per file per unit of work. Never run two writing agents on overlapping paths; if parallel work is unavoidable, use separate branches or git worktrees.
• No agent reviews its own authorship. Author↔reviewer independence is the non-negotiable axis (cross-family is a bonus on top, not a substitute): the reviewer of a diff must be a different agent than who wrote it. A fresh critique pass by the same agent still catches lapses, so it is not worthless - but it shares the author's systematic blind spots (it writes the bug and waves it through for the same reason), so it does NOT discharge the review requirement. When authorship is split, review each portion by an agent that did not write it: Codex-authored code -> diff-reviewer (Sonnet) or human; Claude-authored code -> Codex adversarial. State the diff's author in every review delegation prompt - the reviewer's blind-spot disclosure depends on it; diff-reviewer treats an unstated author as UNKNOWN and fails closed: the same-family caveat applies, and no Codex routing is recommended until authorship is stated.
• Review terminates by convergence, not by exhaustion. Every review produces fixes, and those fixes are new authorship nobody has reviewed - so independence recurses (diff -> review -> fixes -> review of the fixes -> ...). Read literally that never ends; two things make it converge. First, each fix-round review is narrow: the delta plus its dependency cone - what the fix touches and what depends on it - not the whole diff again, and not just the changed lines (a locally-correct fix can still break an already-approved caller, so the cone is the scope, not the line count). The reviewer verifies only that (a) the fixes resolve the findings they claimed to, and (b) they introduce nothing new, especially on risk paths. Second, the loop has a stop condition: halt when an independent pass over the last authored delta yields no new actionable findings - then the most recent authorship carries a green independent pass and you merge. A pass whose only findings are nits counts as clean: leave them and the loop closes; apply any and those edits are a new delta that gets its narrow pass like any other fix. It normally converges in 1-2 rounds because fix-rounds shrink - but shrinkage is why it is cheap, not why it terminates. What guarantees termination is the stop condition plus a round cap: if rounds ping-pong or grow instead of shrinking, that is diagnostic, not a tax - the change is ill-posed or the spec is wrong - so escalate to a human rather than loop.
• The independent pass is mandatory only where a defect can act without a human in the loop: code, executable config, hooks, migrations, anything on a risk path or with runtime/behavioral surface. There a bug crashes, corrupts, or leaks before anyone reads it, so the author's self-check never discharges the review. Pure prose with no runtime surface - docs, comments, formatting - sits below the line: any defect is mediated by whoever reads it, so the author may self-check and merge. This is what "behavioral" means in the §2 pre-merge row - every branch that changes behavior, not every commit. One caveat, because the threshold is "can the defect act unmediated", not "is it a .md": instruction docs (skills, CLAUDE.md, specs) shape behavior indirectly, so a wrong rule is a real defect - just a slow, human-mediated one - and when that guidance is high-stakes, take the independent pass voluntarily even though it is not mandated.
• Background long Codex jobs; collect with /codex:status then /codex:result. While a writer runs, do not start another writer on the same paths.
• Review at branch level (--base), never per micro-commit: each review re-establishes diff context - a fixed overhead - so amortize it per feature.
• No review on a red tree: before dispatching any review - Codex, Grok or diff-reviewer, first pass or fix round - the unit's VALIDATION commands (§1) pass on the tree under review (a unit without any, such as pure prose, has nothing to gate). On a failure, dispatch nothing and return the output to the diff's author for the fix - a different writer makes the branch mixed-authorship (per-portion review, above). Review quota buys what no local command can report.
• Do not delegate tasks smaller than their spec: if writing the spec takes longer than writing the diff, do the work on the main thread.

4. Handling results

• Compare the result against EXPECTED DIFF SHAPE first; drift is cheaper to catch by shape than by reading.
• Every delegated report opens with a provenance line - who ran, on which model, at what effort (one declared exception: premium-reasoner's cost notice comes first, provenance immediately below, per its gate) - with three honesty tiers, never conflated: verified (the model quoted from the subagent's own runtime context - observed harness behavior, not a documented contract, which is why the fallback below exists; when the statement is present, the line also exposes a silently-skipped frontmatter pin per invocation), requested (Codex rescue's --model/--effort flags - the Codex CLI never echoes the runtime model back on stdout; it does RECORD it, so a Codex line stays requested only until someone reads the session rollout named in §6 step 5, which promotes it to verified - do that for any review verdict you are about to act on), and configured (/codex:review inherits Codex's resolved configuration - which is NOT necessarily a repo-local .codex/config.toml: when that file is absent, the global ~/.codex/config.toml governs; report the values from whichever file actually resolves and say which one - for the built-in reviewer the model is review_model when set - "CLI default (unknown)" only when neither sets a value). Agents quote their context statement or write "model not reported by harness" - never self-belief. The orchestrator composes and labels the Codex lines.
• Report spend with the same honesty: quote the harness-reported usage from each Agent tool result (tokens, tool uses, duration) per delegation when the runtime exposes it - observed behavior, not a documented contract; when it does not, write "usage not reported by harness", never infer - plus a running total for the unit of work. Codex-side token usage is not reported by the plugin runtime at all - say so and point at the OpenAI-side usage page. Never convert tokens to money (rates rot and are banned from this repo); which pool the tokens drew from (weekly plan quota vs API credits) is not visible programmatically - the human verifies with /usage, the same pattern as the premium-reasoner cost notice.
• If the result deviates from the spec: reject with a delta list and re-delegate. Do not silently fix deviations on the main thread - that hides drift.
• Before moving on, summarize the decision (1-3 lines) into the relevant spec/ADR file under docs/, and keep the main context clean.

5. Cost guards

• Never enable the plugin's automatic review gate by default: it registers a Stop hook that loops Claude and Codex against each other and drains both quota pools. Supervised, high-stakes sessions only.
• If a Codex command fails on auth or quota: fall back per the routing table, and tell the human which pool is exhausted and when its window resets. If it fails because the requested model is unavailable (GPT-6.1 Sol needs Codex CLI 0.159.0 or newer plus account access; GPT-6 Astra is not on every account), fall back per the routing table - never rerun without --model: the CLI default is whatever the resolved config names, which may be Astra, so that rerun could make Astra implement or produce a review §6 step 7 must reject. A rescue goes to fast-worker; a standard review takes the §2 fallback row (Grok Build per §7 when available, else diff-reviewer); the risk-path pass degrades from Astra to GPT-6.1 Sol at the same ceiling, stating "Astra unavailable - degraded to GPT-6.1 Sol" in the report - the human may still block the merge on it - and if Sol is unavailable too, it goes to diff-reviewer with the CLAUDE.md risk-path focus text. Always tell the human which degradation was taken, and when the cause is a CLI below 0.159.0, that updating it restores the route.
• Never route mechanical work to the most expensive available model. Escalation is by difficulty, decided by the human, not by quota remaining.
• Never add PREMIUM-APPROVED to a delegation prompt on your own initiative. The token exists so that premium spend always passes through the human.
• Never use Codex Ultra or any multi-agent Codex mode: this protocol is already the orchestration layer; Ultra would duplicate it and multiply spend on both pools. That includes the ultra reasoning effort, which the Codex catalog lists above max ("Maximum reasoning with automatic task delegation"): rollouts at ultra announce proactive multi-agent delegation and spawn sub-agents, while at max Codex is told not to spawn any unless explicitly asked (measured 2026-09-29, CLI 0.144.5-0.157.0). Never pin it (--effort, -c) and never inherit it (preflight below).
• Effort follows the routing table: reviews run at the HIGHEST ALLOWED effort the invocation path exposes - max via direct, xhigh as the pinnable ceiling via inline-task (an omitted --effort inherits the resolved config, which may sit higher - legal, and rollout-verifiable); high is the floor. Writing stays at medium (high only for hard bugs or multi-module work). A pin is an exact selection, not a raise - it can LOWER a machine configured at max - so compliance is three steps, fail-closed: (a) preflight the resolved config (repo-local .codex/config.toml when present and trusted, else global ~/.codex/config.toml): at-or-above the path's ceiling (up to max), omit --effort; below it, pin the ceiling as a FLOOR; an UNSET or indeterminate value counts as BELOW (pin), never as satisfied; a resolved ultra is out of policy and never inherited - pin the ceiling (xhigh on inline-task, whose companion cannot express max; max on the raw CLI - whose only documented pin is the §2 single-commit form, so a branch review on the direct path needs the resolved config set to max first, then the flagless command), and the flagless slash commands do not run until the config changes. Preflight the MODEL the same way: the built-in reviewer runs on review_model when set, else model; the adversarial pass and tasks run on model. The ordered model is GPT-6.1 Sol, or GPT-6 Astra for the risk-path pass; the slash commands take no model flag, so on a mismatch ship that pass through the §6 inline-task mechanics with the right --model, or ask the human to point the key that pass reads (model for the adversarial pass, which the plugin runs as an ordinary turn; review_model steers only /codex:review) at it for that run, and to restore it afterwards. (b) dispatch - inline-task is the transport that pins model and effort per invocation via the companion; on the direct path the raw CLI pins via -c model_reasoning_effort=.... (c) verify the rollout afterwards (§6 step 5) and treat anything other than a rollout PROVING the ordered model (or its declared degradation, above), the intended effort, a read-only permission profile and no sub-agent calls as an INVALID verdict - do not classify its findings, re-dispatch. That covers a wrong-model rollout, a lower-effort one, an ultra one, a write-capable one, AND one you could not read: "we could not check" and "it was fine" must not look the same. The rule is path-independent: on a direct review, correlate the session id from that run's own output or status; if none can be correlated, the verdict is unverifiable - never reach for the newest rollout, which is unsafe under concurrent sessions. Beware typos: the CLI does not validate model_reasoning_effort locally - an invalid value passes parsing, prints in the run header, and dies mid-run at the API with HTTP 400 (the rejection lists the accepted values - measured 2026-08-09: none|minimal|low|medium|high|xhigh|max; the Codex catalog has since added ultra, banned above; per OpenAI's model docs, GPT-6.1 Sol accepts neither none nor minimal, and GPT-6 Astra does not accept none). Measured cost (2026-08-09, GPT-5.6 Sol): max took 16m 27s on a 16 KB diff against 3m 40s / 2m 25s / 37s at high on a 12 KB one - different inputs, so an observed association, not a controlled comparison; budget for it in the §6 deadline. Also on record, same caveat: a three-round gate pinned to high returned "may merge" on a branch a later unpinned max pass rejected with a blocker.

6. Review transport: inline-task fallback

Applies to every Codex-bound review: its dispatch on any transport, the rollout verification, finding validation and provenance of its steps 5-7 - on the direct path too - and re-enabling direct; and to validating any review or audit finding, whatever its source (step 6). Before the first step of any of these, Read codex-review-transport.md in full: its steps 1-7 are the "§6 step N" every reference names. Never act from this summary.

7. Fallback reviewer: Grok Build (optional)

Applies when the §2 fallback row sends the standard review of a Claude-authored diff to Grok Build. Before readiness (step 1), Read grok-fallback-review.md in full: its steps 1-6 are the "§7 step N" every reference names. Never act from this summary.