Write the task brief to a file. Like a contract: exact scope and file
ownership, the interface to build against, repo conventions to follow, and
an instruction to report deviations instead of improvising. If the brief
would be longer than the diff, don't delegate. For a defect fix, make the
gate fail first: encode the bug as a failing regression check (test or
fixture assertion) before dispatch and say so in the brief — the
delegate's "gate passed" is then proof the defect died, not a claim.
State invariants, not failure-path branches. A brief that dictates what
to do when something goes wrong ships the orchestrator's unexamined premise
straight into the code, and the delegate will implement it faithfully. Say
"never type into an unintended app"; do not say "on timeout post the
keystroke anyway so text is not lost". Before writing any "or else X is
lost" rationale, verify X can actually be lost. In PR #676 it could not —
the transcript was already on the clipboard and in history — so the brief's
own safety clause recreated the exact bug the PR existed to fix, and only a
cross-harness adversarial run caught it.
Mutation-check any fixture the delegate authored. A test written by the
same agent that wrote the fix can pass for reasons unrelated to the fix.
Revert the fix, confirm the test goes red, restore. PR #676: a delegate's
"notice does not fire" test asserted the absence of a label in a state where
an unrelated guard already prevented it — green with the fix removed. PR #677
is the harder version: a delegate rewrote an existing test so its own
regression would pass.
Fill and dispatch (-t is the brief file; gate defaults to
pnpm check && pnpm typecheck && pnpm test):
scripts/run-codex.sh -t <brief.md> [-C <worktree>] [-g "<gate>"] [-c "<extra constraints>"] [-o <out>] \
[-m <model>] [-e <effort>] [-S <tier>]
scripts/run-claude.sh -t <brief.md> [same flags, minus -S; -m takes
sonnet|opus|haiku (default opus), -e takes
low|medium|high|xhigh|max (default medium — the
brief carries the hard thinking; bump for subtle
defect fixes)]
Codex model/effort/speed (defaults come from ~/.codex/config.toml;
only pass a flag when the user asked for something specific):
Allowed models (for now): gpt-5.6-sol (config default; main work),
gpt-5.6-terra (quick review/feedback passes), gpt-5.6-luna (cheap fast
bulk; not a primary pick) — the script rejects anything else.
| User says | Flag |
|---|
| "sol" / "terra" / "luna" | -m gpt-5.6-sol / -m gpt-5.6-terra / -m gpt-5.6-luna |
| "think hard" | -e high |
| "max effort" | -e xhigh (rarely needed — high covers almost everything) |
| "quick pass" / "low effort" | -e low (or minimal/none) |
| "fast" | -S fast (bills ~2.5x credits — see below) |
| "standard speed" | -S standard (the script's default) |
Effort is none|minimal|low|medium|high|xhigh (validated client-side; the
API only rejects a bad value after the session has started). Calibration:
medium is the workhorse, high for genuinely hard briefs, xhigh almost
never — 5.6 at medium/high already runs long and completes tasks
end-to-end.
Speed maps to Codex's service_tier config: fast = priority, standard =
default — the only two tiers the gpt-5.6 models advertise; anything else
is silently dropped by Codex, so the script fails closed on other values.
The script defaults to standard, overriding the user config's
priority: fast bills ~2.5x credits, and 5.6's long autonomous runs make
the burn unpredictable. Delegations are background work; only pass
-S fast when the user explicitly asks.
After the run the script prints the Codex session id; follow up in the
same session with codex exec resume <id> "<prompt>". Sessions cannot be
named at dispatch (/rename is TUI-only as of codex 0.144) — the id is
the handle. Resume only for short follow-ups: gpt-5.6 input past ~272k
tokens bills 2x, so a fresh scoped brief beats resuming a long session.
--dry-run on either prints the filled prompt. run-codex.sh uses
codex exec -s workspace-write (OS sandbox caps writes to the worktree);
run-claude.sh uses headless claude -p --permission-mode acceptEdits
with exactly the standard gate commands allowlisted (a custom -g gate
outside that set fails closed — extend the allowlist in the script
deliberately, never to bare pnpm:*/cargo:*, which would reopen
pnpm exec git / pnpm dlx / cargo run). Claude-side enforcement is
policy-level, and the delegate reads the whole repo — instruction-like
text anywhere in it is injection surface, so only dispatch onto checkouts
you trust. Both runners fail loudly if the delegate moved HEAD.
