"Use when offloading a bounded audit, broad search, extraction, or mechanical edit to a plan-covered CLI agent. Trigger on 'delegate' or 'offload'. Not for PR review (use slim-review), work needing this session's decisions, or a repo you are mid-editing."
Install
npx skillscat add sirmaelstrom/workit/codex-delegate Install via the SkillsCat registry.
Model-Aware Delegate — Route Leaf Work Off the Expensive Channel
The conductor is the context-rich channel. Token-hungry grunt work burns it on work a cheaper model can do just as well. Delegate the leaf work; keep orchestration, architecture, and integration judgment in the conductor.
For worktree-backed agent execution, the lane lifecycle is encoded in ${CLAUDE_PLUGIN_ROOT}/scripts/lane.mjs; the binding behavior is ${CLAUDE_PLUGIN_ROOT}/reference/patterns/lane-supervision.md.
Route by Phase
Pick the execution surface by the phase of work, not just its size:
| Phase | Surface | Why |
|---|---|---|
| Research / context-gathering / bulk reads | Cheapest fitting leaf agent | Input-token-heavy; needs coverage, not brilliance |
| Planning / architecture / judgment calls | Conductor only | Needs the session's accumulated context and the strongest reasoning |
| Execution of a well-specified, self-contained chunk | Cheapest fitting leaf agent | The spec carries the intelligence; execution is grunt work |
The conductor stays the orchestrator: it decides, delegates, and integrates the distilled result. It does not absorb the bulk tokens.
Select by Circumstance, Not Loyalty
Apply the self-containment gate first, then select the least expensive surface that fits:
| Target | Choose it when | Cost / effort posture | Do not choose it for |
|---|---|---|---|
Astra (codex-astra — GPT-6 Astra in the Codex harness, at low) |
Default for verdicts since 2026-09-23 (operator ruling, quest 458d87c9): codebase audits, "is X guarded", pre-merge verification — any output where a wrong answer ships a bug. On the graded FCA audit it had 0 wrong verdicts against GPT-6 Sol's 5 and Terra's 6 |
$0 marginal, ChatGPT-plan covered. The plan's codex bucket has no 5-hour window (weekly only, since 2026-09-09); an Astra@low full-repo audit arm is ≤ ~0.67 points of the weekly meter, a diff-review arm well under that (astra-diff-review-measurement.md). Read the meter with the app-server probe (auto-memory codex-app-server-rate-limits-read-replaces-usage-page) rather than assuming either figure |
Build work (GPT-6 Sol's measured role); anything Luna can take; unattended fan-out (burst behaviour on the weekly tier is untested) |
GPT-6 Sol (codex — GPT-6 Sol in the Codex harness, at high, since 2026-09-23) |
Default for build work: difficult bounded implementation, repair, build lanes. On a replayed bounded fix it produced the same design as Terra with both pre-fix failure proofs, in 649 s against Terra's 1002 s, with 65% fewer reasoning tokens | $0 marginal, same channel; high reasoning; the 88x conductor-token saving measured on its predecessor applies to the channel, not the model | Verdict-only audits (Terra-parity there: same "guard mechanism credits the whole file" failure shape); work requiring conductor context |
Luna (codex-luna in the Codex harness; luna where an API agent runner exists) |
High-volume, repetitive, well-specified leaf grunt: mechanical edits, test generation, extraction, classification, or many independent small checks | Also $0 through the Codex harness — 43% faster, ~15% fewer plan tokens; medium reasoning by default | Architecture, ambiguous diagnosis, synthesis across leaf results, direct conversational work — and any verdict about safety or correctness (see threshold) |
GPT-5.6 Terra left the defaults on 2026-09-23 (operator ruling, quest 458d87c9): there is no GPT-6 Terra, and GPT-6 Sol (priced at or below it) passed Terra's build and review roles on graded replays, while Astra had already beaten it on verdicts. The slug gpt-5.6-terra still serves on the plan (it is not deprecated). Name it explicitly only to reproduce an old arm. Evidence: outputs/workshops/gpt6-sol-role-mapping/measurement.md.
Grok is off the delegation roster (operator decision, 2026-08-10). It is metered
xAI spend, and liberal delegation was trending toward $25–50/month for work two
plan-covered channels already do. Both tiers above are $0 marginal — there is no
delegation case that justifies paying for a third. Do not reach for Grok here even
if a grok alias is registered and looks available; if Codex capacity is the
constraint, wait or narrow the task rather than spending.
The Terra-vs-Luna threshold (measured)
Do not pick between a verdict tier and Luna on cost — they are the same $0 plan-covered channel. Luna buys wall-clock and plan capacity, and pays in silent incompleteness. Measured 2026-08-07 with Terra as the verdict tier (the verdict tier is Astra@low since 2026-09-23; the Luna side of this threshold is unchanged), both tiers on a byte-identical whole-repo audit (outputs/workshops/codex-delegation-pattern/luna-arm-measurement.md):
| Choose | For | Evidence |
|---|---|---|
| Terra @ high | Any output that is a verdict about safety or correctness — audits, "is X guarded", pre-merge verification, anything where a miss ships a bug | Luna returned a confident wrong PASS on 2 of 9 examined stores (22%), citing real code at real line numbers. Terra found 3 genuine defects that both Luna and the July baseline called clean |
| Luna @ medium | Enumeration and extraction whose output is mechanically checkable — inventories, find-all-X, classification, bulk mechanical edits | 141 s vs 249 s (−43%), 79k vs 93k leaf tokens (−15%), full recall of the known defect set |
A wrong verdict and a wrong locator both arrive in the register of a verified finding. Luna's three failure modes — 25% silent store-coverage shortfall, 22% false PASS, one hallucinated directory — were all invisible in a handback that read as complete.
The Astra re-cut (measured 2026-09-05)
GPT-6 Astra landed on the plan and re-ran the same byte-identical FCA audit the same afternoon as a fresh Terra@high run (outputs/workshops/codex-delegation-pattern/astra-arm-measurement.md). Three arms, 41/41 coverage on all of them, every disagreement settled by reading the cited code:
| Arm | Wrong verdicts | Output / reasoning tokens | Note |
|---|---|---|---|
| Terra @ high | 6 — 5 false GUARDED (it recognised a guard mechanism and credited the whole file) + 1 false DEFECT | 13.6k / 8.1k | Terra's failure is mis-judgement with full coverage, which the coverage assertion cannot catch |
| Astra @ high | 0 in the 10 DEFECTs checked; found 5 real defects Terra called GUARDED (cached-reopen paths, last-item archive, an unretired optimistic write) | 6.3k / 1.8k | 21% less input than Terra for a strictly better handback |
| Astra @ low | identical DEFECT set to Astra@high | 4.8k / 0.7k | Dropped the repo path prefix on every locator — the locator grep below catches it; add "repo-relative paths" to the prompt |
On verdict quality Astra@low dominated Terra@high on this task shape. The plan window, not the verdict, is the constraint: the same afternoon burned a codex reset, and Astra's 5-hour window closed again the following evening under ordinary use. The plan cost line in that doc ("~8% of a window per audit arm") is derived from one whole-afternoon reading, not measured per arm, and OpenAI does not publish per-model plan draw — so "fewer tokens" is not "cheaper on the plan". Operator ruling 2026-09-06: Terra stays the default; Astra is explicit opt-in for verdict-critical, single-arm work until the AI subscription capacity experiment (quest 13255ef0) measures plan draw per model. Luna stays the enumeration tier. n=1 per arm, one task shape, one grader — directional, like the Luna numbers. The diff-review shape was measured on 2026-09-09 (astra-diff-review-measurement.md). Superseded 2026-09-23: the plan-window constraint behind the "Terra stays the default" ruling went away with the weekly-only tier, and the defaults moved (next section).
The GPT-6 re-cut (measured 2026-09-23)
GPT-6 Sol and Luna landed on the plan on 2026-09-22. Every arm replayed a benchmark that was already graded, against rules written before any arm ran (outputs/workshops/gpt6-sol-role-mapping/measurement.md):
| Shape | GPT-6 Sol @ high | Terra @ high | Astra |
|---|---|---|---|
| FCA audit, wrong verdicts of 41 | 5 (4 at xhigh) | 6 | 0 |
| #620 diff review, recall of 3 known | 3 | 2 | 2 |
| Bounded fix (743b33ee), correct + wall | correct, 649 s | correct, 1002 s | correct, 595 s (@medium) |
Resulting defaults: Astra@low for verdicts, GPT-6 Sol@high for build work. GPT-6 Luna replaced 5.6 Luna in Observatory's session summarizer (0 fabrications vs 1 on the frozen floor). The enumeration tier here stays gpt-5.6-luna: GPT-6 Luna was not measured on enumeration. n=1 per arm.
Assert the handback (all tiers, non-negotiable)
The conductor never reads the files, so the handback's coverage and locators are the deliverable. Two checks, each ~one line, catch every mechanical failure observed:
- Demand a coverage statement and compare it to ground truth: end every prompt with "Close with: examined N of M files matching
<glob>." Thenfindthe glob and check N against M. Luna silently skipped 3 async-bearing stores; Terra silently skipped every leaf component underlib/components/by reading "island/store" literally. The same assertion catches both — neither is a tier-specific flaw. - Grep every cited path against the filesystem before acting on a finding or passing it upward. A hallucinated directory turns a correct finding into one you must re-derive — spending exactly the tokens the delegation saved.
(This is the delegation-side instance of the closed-output lesson from the leaf-task inventory: the closed frame makes failure detectable, not output trustworthy. Nothing detects it unless you run the check.)
Availability gate
Do not confuse a registered Observatory/Dogan alias with a subprocess the current host can spawn.
codex-astra,codex, andcodex-lunaare actionable from an interactive coding session throughcodex exec.- A registered
grokalias is not a delegation target — see the roster note above. Neither is any other metered runner: if the only reachable surface is metered, do the work in the conductor or narrow it, and do not inline the repository into an API prompt (that erases the token saving and bills for it).
When to Delegate — Task Shapes
Delegate when the task matches a token-hungry shape:
- Whole-repo or large-directory audit ("check every X for pattern Y")
- PDF / large-document extraction or summarization
- Large-data or log scan
- Computer-use / screenshot-loop style repetitive verification
- Broad "find X across everything" searches whose result is a short list
The Self-Containment Gate (must pass)
A delegated agent is fresh and stateless. It has none of your mid-session context. Before delegating, ask:
Can I write this task as a standalone prompt — target paths, definitions of the patterns to find, output contract — that a stranger could execute correctly with zero knowledge of this conversation?
- Yes → delegate. Example: "Audit every Svelte island in
<abs repo path>for async loads missing a load-sequence guard; return file → finding → line ref, max 80 lines." Everything needed is in the prompt. - No → don't delegate. Example: "Refactor this the way we discussed" or any task whose correctness depends on decisions, constraints, or partial edits accumulated in the current session. Handing it off either loses the context or forces you to serialize it all into the prompt — at which point you've spent the tokens anyway.
If the task needs the conductor's working memory, the conductor does it.
The Handback Contract — Distilled Only (load-bearing)
If raw tokens flow back into the conductor, the cost just moved — the win evaporates. Every delegated prompt MUST demand a bounded, structured return:
- State the exact output shape (findings list, table, diff, single answer).
- Set an explicit ceiling: "Maximum N lines total."
- Forbid dumps: "Do NOT include file contents, full transcripts, or raw data."
- Read back only Codex's final message — never cat its scratch output or session log into the conductor's context.
Codex-Harness Invocation
codex exec --model gpt-6-astra -c model_reasoning_effort=low --sandbox danger-full-access --skip-git-repo-check -C "<absolute target dir>" - <<'EOF'
<self-contained prompt, ending with the bounded-return contract>
EOF(- reads the prompt from stdin — safest for multi-line prompts. On Windows/PowerShell, pipe the prompt file: Get-Content prompt.txt -Raw | codex exec ... -.)
- Verdict default (audits, "is X guarded", pre-merge verification):
--model gpt-6-astra -c model_reasoning_effort=low(the Observatorycodex-astraslug). Read the weekly meter before a fan-out (the tier has no 5-hour window since 2026-09-09); lane supervision selects 5h when available, otherwise weekly, and trips at or below its configured floor. - Build default (bounded implementation, repair, lanes):
--model gpt-6-sol -c model_reasoning_effort=high(the Observatorycodexposture since 2026-09-23; the CLI's own default for gpt-6-sol is medium, and every measured arm ran at high). Slugs rot — before a large fan-out, or on a 400, verify the live slug against~/.codex/models_cache.jsonand the roster's model registry. When lane supervision reports the plan meter as unknown (thewarningfield), the conductor makes a manual account read (the app-server probe) before any further dispatch. Tell it "cite repo-relative paths exactly as they appear in the file list" — at low it dropped the path prefix on every locator in the 2026-09-05 arm, and that one line fixed it on both 09-09 arms. - High-volume grunt: use
--model gpt-5.6-luna -c model_reasoning_effort=medium(the Observatorycodex-lunaposture). Set it explicitly: the Codex CLI's configured default may otherwise raise Luna to high. - Use model slugs, not Observatory aliases, on the raw
codex exec --modelflag. The aliases describe the roster posture; the CLI accepts the underlying slug. - Sandbox:
--sandbox danger-full-accessfor audits/scans/extraction (most delegations), with an explicit "do not modify any files" clause in the prompt. The clause is a request, not a sandbox — Terra honored it on every audit arm through 2026-09-08, then on 2026-09-09 a Terra council seat under the same clause created two git worktrees, junctioned theirnode_modulesto the canonical Observatory checkout, and recursively deleted them, gutting the live checkout's packages while pm2 read green (quest a0180149). Add "do not create git worktrees, do not delete directories, do not run git write commands" to the prompt, and after any handback that mentions a worktree, cleanup, or removal, count the canonicalnode_modules(npm ls --depth=0) before trusting the box. ⚠️ Do NOT use--sandbox read-onlyon this Windows box: the sandbox runner fails at the first child spawn (CreateProcessAsUserW failed: 5) and the model returns a plausible ungrounded answer with no surfaced error (auto-memorycodex-exec-readonly-sandbox-broken-windows). Useworkspace-writeonly when the delegated task must produce files, and point it at a scratch dir or worktree — never let a delegated task write into a repo the conductor is mid-edit on. - MCP: assume none.
codex execsilently skips HTTP-transport MCP servers — a delegated task that "uses the gateway" will no-op without error. Keep delegated tasks fully self-contained (filesystem + shell only). If a task genuinely needs an MCP tool, inject a stdio server explicitly via-c mcp_servers.<name>.command=...flags; never assume anything from the interactive session is reachable. - Verify against
codex exec, the non-interactive form — never against the interactivecodexUI. They differ in config handling and MCP behavior; a pattern proven interactively can fail underexec.
Prompt template
You are auditing/processing <target> at <absolute path>. READ-ONLY — modify nothing.
Task: <complete, standalone description — include definitions of every
pattern/term, because you have no other context>.
EARLY EXIT: <the investigate or build clause from "Standing prompt clauses"
below, verbatim>.
Do NOT open GitHub issues or PRs beyond the one asked for; anything you cannot
do or think should follow goes in your final message.
Return DISTILLED findings only:
- <exact output structure: e.g. "file path — pattern # — one-line evidence — line ref">
- Close with EXACTLY: "examined N of M files matching <glob>" — the real counts.
- Maximum <N> lines total. Do NOT include file contents or raw data.The coverage line is load-bearing, not politeness: it is the only thing that makes an
incomplete audit distinguishable from a clean one. Check its N against your own find,
and grep every returned path against the filesystem — both tiers have been measured
silently skipping files and citing at least one directory that does not exist.
Standing prompt clauses (every delegated or lane prompt)
Three clauses ride every prompt this skill, a burn-down lane, or a fan-out sends. The first
two are cost controls: the first stops a leaf from grinding through options 2–17 when option
1 was right and cheap (a bounded audit arm costs ~8% of a Codex 5-hour window, and a mid-run
limit hit is turn.failed with no handback); the second stops it from filing follow-ups
into the repo's issue tracker. The third is a coverage question.
Early exit. Pick the shape by the prompt's verb and paste it verbatim:
- Investigate / audit / diagnose:
EARLY EXIT: if you find a fix that is small (roughly one file, a few lines) and you believe it is sufficient, STOP and report it instead of continuing the sweep. Report exactly: (1) the edit, as a diff; (2) file path and line; (3) the evidence of sufficiency — the failing behavior it closes, and what you checked that shows nothing else depends on the change. Do not apply it. An early exit that omits (3) is a lazy handback and will be rejected. - Build / repair:
EARLY EXIT: if the brief assumed more work than the fix needs, make the small fix, stop, and say so — do not build the assumed scope around it. Your final message names the fix, its location, and the evidence that it is sufficient (the behavior it closes; what you checked that shows nothing else depends on it).
The evidence line is the guard, not decoration: the failure an early exit invites is a fix
that is simple and wrong, and the clause makes such a fix refutable by the reader in one
read rather than trusted on the writer's say-so. A handback that claims an early exit
without (3) is treated as incomplete and re-run with the clause quoted back. (Source: the
investigating-agent prompt in Theo's 2026-09-08 video; quest 8945de7f.)
Follow-ups destination.Do NOT open GitHub issues or PRs beyond the one asked for; anything you cannot do or think should follow goes in your final message.
Measured 2026-09-03: three lanes in one sitting each filed a GitHub issue for something
outside their brief when the prompt left this unsaid — "do not merge" constrains git, not
the tracker (auto-memory lane-prompt-must-name-where-followups-go). The conductor
harvests follow-ups to the Spine; a lane that files one anyway gets it closed with a
comment pointing at the quest.
Boundary question.Under ## Follow-ups, list the callers of any function you add a check to, and every construct in your files that intercepts another lane's or a prior WP's types (catch blocks, filters, handlers), with the base type grepped and the grep output quoted. "None" is an answer; silence is not.
Measured in Burn-down Y (governance measurement §3.4, 2026-09-26): three cross-lane Majors —
ya round 2, yd3 round 1 (which shipped as an unannounced production deploy), yd4's silence —
were each a caller or a catch on a type another lane owned, and no resident line had asked
the lane to look. A question makes the looking visible: a lane with nothing to list writes
"none" and the reviewer knows it looked. Falsifier: a lane edits a shared function or adds
an exception type with no caller or catch grep earlier in its transcript. (Quest e06b24a5.)
Reading the result
Codex prints a header, the transcript, and a tokens used line. The final assistant message is the handback. Sanity-check it: if it exceeded the line ceiling or dumped raw content, tighten the contract and re-run — do not paste the oversized output onward.
Cost posture
- Conductor→Codex (Astra, GPT-6 Sol, or Luna) delegation is pure arbitrage when the CLI is plan-covered: expensive-channel tokens saved, $0 marginal spend on the sub.
- API Luna is metered; its lower token price does not beat $0. Prefer the Codex harness, where both tiers are plan-covered. Metered runners are not a delegation target here at all — a cheaper-per-token bill is still a bill against $0.
- The ChatGPT Plus tier has real (unpublished) throughput limits. Treat this as a spillover valve, not a workhorse — one heavy delegation at a time, not a fan-out of dozens.
- The scarce resource is plan capacity, not dollars. Between two $0 channels there is no dollar axis to optimize; budget in leaf tokens and wall-clock instead. Measured on one whole-repo audit: Terra 93,353 tok / 249 s vs Luna 79,431 tok / 141 s — and both roughly half the 197,290 the same task cost on gpt-5.5 in July, a model-generation gain rather than a tier effect.
Anti-patterns
- Delegating a task that needs mid-session context (fails the self-containment gate) — you'll serialize the context into the prompt and spend the tokens anyway, or get a wrong answer.
- Accepting an unbounded handback ("here's everything I found, plus the files") — the contract must cap it before the run.
- Delegating planning, orchestration, or judgment — leaf agents execute well-specified work; they do not carry your session's intent.
- Reaching for a metered runner (Grok, API Luna) because its alias is registered — the roster is two plan-covered tiers, and "it was available" is not a spend rationale.
- Piping codex's full session log or scratch files back into the conductor "for reference".
- Using this as a parallelism engine on the $20 tier — it's a cost valve, not a compute farm.
Origin: codex-delegation-pattern workshop (spec-LITE, 2026-07-04), quest cb3ce3e7; roster expansion quest 93d32058 (2026-07-10). Mechanism proven in Observatory's CodexCliProvider and the review council's lead lens. Measurement gate (D5) run 2026-07-06: outputs/workshops/codex-delegation-pattern/measurement.md — 177,307 → ~2,020 conductor tokens (98.9%, ~88x) with the same 4/4 defect set.
Terra-vs-Luna threshold measured 2026-08-07, quest a170a58d: outputs/workshops/codex-delegation-pattern/luna-arm-measurement.md — both tiers re-run same-day on a byte-identical prompt (the D5 baseline's gpt-5.5 + --sandbox read-only invocation is no longer reproducible). Directional, n=1 run per arm.