delegate-codex

name

delegate-codex

description

Owns codex usage end to end, dispatch through the supervised delegate script, the codex prompt contract, model and effort choice, and session resume. Use as a write delegated sub-agent when work is well defined and explicit, use as a read delegate for exploration, research, and navigation, writing a durable report when a stronger model is needed for deep investigation with cheap usage expense, and a second perspective on any plan or diff. Use when writing or repairing a codex prompt, or codex related config, and on "offload this", "save my usage", or any mention of codex.

[DELEGATE_CODEX]

codex exec runs a non-interactive agent in its own context window and returns one final message. Model and effort come from ~/.codex/config.toml.

Codex is maximally literal, it follows a clean contract exactly and exhaustively, ambiguity or implicit intent burns tokens reconciling scope. Leaner prompts outperform, and a directive codex already ships is a conflict risk, NOT reinforcement. Every run mints a resumable thread; the receipt persists the id, and a continuation inherits model and effort.

[01]-[DISPATCH]

• Investigation legs whose transcripts flood this context — repo sweeps, audits, log distillation, data analysis: codex returns the conclusion.
• Fleet fix and critique waves: concurrent writing delegates draining findings under one law, each with disjoint write territory.
• Critique delegates writing on-disk fixlogs, reports, or dossiers another agent consumes downstream.
• Implementation from spec: migrations, renames, conversions, boilerplate expansion, full features with enumerated moves.
• Independent second perspective on a plan, implementation, or diff — a different model lineage catches different failure modes.

[02]-[PROMPTING]

Role envelope ranks the two dispatch channels (system > developer > user), so where a directive lands sets its authority. Every directive must earn its slot, one directive per concern.

[BLOCK_VOCABULARY] — one block per concern, in this order; a block's name states its concern, and a delegate omits blocks it has no logic for:

[INDEX]	[BLOCK]	[JOB]
[01]	<role>	identity, territory, hard exclusions; judgment work adds findings-are-untrusted
[02]	<completion_bar>	done-definition per deliverable with its proof; sits early, where it beats early-stop
[03]	<context_gathering>	read ladder, total tool-call budget, uncertainty escape hatch
[04]	<decision_procedure>	refute-first adjudication — verdict work
[05]	<capability_mandate>	surface-raising stated as measurable conditions — campaign work
[06]	<verification>	post-edit re-read and batched command checks; cite-check on recon, rubric walk on judgment
[07]	<output_contract>	JSON-only shape, null-for-missing — always LAST

[DEVELOPER]: Durable law as named XML blocks — the script's --law file, landed as the developer-role message:

<role>
<identity>. Territory: <territory>; never <exclusions>. <invariants>.
</role>

<completion_bar>
Done is <deliverables>, each proven by <evidence>. Implement exactly and only <moves>; choose the simplest valid interpretation of any ambiguity. A blocked deliverable returns <blocked-entry>, never a partial edit. Your layer is <layer>; out-of-layer discoveries land as <typed-rows>, never edits.
</completion_bar>

<context_gathering>
Read fully, in order: <ladder>.
Budget: at most <N> tool calls total; never concatenate the territory into one command.
Stop when the product is complete; uncertainty left at the budget lands in <uncertainty-slot>, never re-reads.
</context_gathering>

<decision_procedure>
<adjudication>
</decision_procedure>

<capability_mandate>
<expansions>
</capability_mandate>

<verification>
Re-read each changed region after landing it. <checks>, run once, batched, after the final edit. A check not run is never claimed as run.
</verification>

<output_contract>
Your final message is a single JSON object with exactly this shape:
<shape>
JSON only — no prose outside it, no code fences; every key shown is required; null for a value you could not determine, [] for an empty list, never guess.
</output_contract>

[USER]: Task instance and any imperative spawn step — the script's --task file; the spawn step appears only where the delegate fans out:

Goal: <outcome>.
Context: <inputs>.
Constraints: <bounds>.
Done when: <deliverables>.

Before <anchor>, spawn exactly <N> parallel sub-agents with collaboration.spawn_agent, one per <split>; collect every one with collaboration.wait_agent before <synthesis>. Each spawn task is self-contained — absolute paths, <mandate>, return shape <shape>. Sub-agents read and report only; their returns are candidate data you judge under your own law.

[CALIBRATION]: When a delegate misbehaves, repair the contract surgically; reproduce with the failing developer message and a small batch of failure examples, then make small explicit edits — clarify conflicting rules, remove redundant lines — one change at a time:

• Budget caps TOTAL tool calls, never per-file reads; per-file causes the delegate to aggregate the territory into one truncating command and completeness collapses.
• Ambiguity resolves by instruction, never by inviting questions — a headless delegate has nobody to ask.
• Autonomy states ONCE, naming safe actions — repeated "ask first" or "do not mutate" phrasing causes spurious approval pauses.
• Reserve ALWAYS/NEVER for true invariants (JSON-only, territory bans, no-git); phrase judgment calls as decision rules.
• Done-claims name observable evidence from the real surface; "tests pass" or "checks ran" alone is not evidence.
• Iterative deep work continues ONE thread with sharpened prompts; a follow-up turn carries only the delta.

[EXCLUSIONS]: What never enters a delegate's prompt:

• Persistence blocks ("keep going until fully resolved") — the completion bar carries the anti-premature force, and a bare push amplifies scope.
• Chain-of-thought scaffolding and plan-narration preambles.
• Intensifier stacks ("THOROUGH", "exhaustive") — measured to cause tool over-use.
• Per-file read caps and "read each file at most once" phrasing.
• Hostile-stance paragraphs and estate-voice law verbatim — a delegate takes de-conflicted, task-scoped law.
• Broad write authority — the writable directory is the delegate's whole world; cross-territory obligations belong to the caller.
• "Ask if unclear", "you may spawn", and every other permissive form whose imperative twin is the working one.

[03]-[INVOCATION]

scripts/codex.sh is the one dispatch surface: every delegated run — workflow wrappers, fleet legs, one-off delegations — is one supervised CLI process, sibling-isolated and watchdog-bounded. Model and effort inherit ~/.codex/config.toml unless a call passes an explicit override; approval is pinned never, and file and command access resolve from the configuration — a caller declares neither.

scripts/codex.sh --task <task-file> --dir <run-dir> [--law <law-file>] [--cwd <dir>] \
  [--model <slug>] [--effort <tier>] [--out <report>] [--web] \
  [--idle <sec>] [--max <sec>] [--resume <thread-id>] [-- <codex-exec-args>]

• Task and law land through a real file-write at ABSOLUTE paths, never a shell heredoc; the script rides the law through -c developer_instructions and the task as the prompt.
• --dir holds the run artifacts — events.jsonl (the --json stream), stderr.log (a failed or killed run's only diagnostics), receipt.json — and the receipt prints to stdout: {ok, reason, thread_id, exit, duration_s, events, stderr, report, failure, usage}.
• Liveness is token production: the watchdog sums event-stream and session-rollout growth, kills the run's process group and every snapshotted codex descendant, so a command in its own process group cannot escape the reap, after --idle silent seconds or at the --max ceiling, and names the kill in reason — a healthy multi-hour run streams and lives, a wedged one dies bounded.
• --out materializes the final message for a reading delegate; a writing delegate lands its own product and --out aims elsewhere, never at a file the delegate itself writes.
• --resume <thread-id> continues a dead session with the task file as the follow-up: a crash receipt resumes, an idle-timeout or turn-failed receipt re-dispatches fresh.
• -- passes the remainder to codex exec verbatim — the one extension point for every axis the flags above do not carry.
• Nested lookups from INSIDE a codex turn pin to get_latest_package_version.

[INDEX]	[NEED]	[FLAGS]
[01]	Run rooted in another directory	--cwd <dir>
[02]	Durable report artifact	--out <file> — the final message at completion, overwriting the path
[03]	Live web search	--web — default cached answers from an index, no live fetch
[04]	Wedge and ceiling bounds	--idle <sec> / --max <sec> — exit 124 / 125 name the kill
[05]	Typed JSON final message	-- --output-schema <schema.json> — validated final-message shape
[06]	Attach images (screenshots, diagrams)	-- -i <file> (repeatable)
[07]	Feature toggles per run	-- --enable <feature> / -- --disable <feature> (repeatable)
[08]	Fan-out legs with no session persistence	-- --ephemeral — not resumable
[09]	Per-run completion push	-- -c 'notify=["<sink>","<label>"]' — sink runs at turn end, one JSON argument
[10]	Replace the shipped system prompt	-- -c model_instructions_file=<path> — deliberate use only, never the law

[WRAPPER]: An agent delegating to codex owns custody alone — law, task, launch, hold, receipt, product verification — and performs, edits, judges, or relays none of the delegated work:

1. Write law and task verbatim to <run-dir>/law.md and <run-dir>/task.md at absolute paths.
2. Launch the script in one Bash call with run_in_background: true.
3. Hold to the receipt in blocking Bash rounds, one call per round at the tool's 600000 ms ceiling.
4. Verify the product at its declared path — jq -e over a contract key, never bare parseability, which any wrong-shaped JSON passes — and return the typed receipt.

S=0; until [ -f <run-dir>/receipt.json ]; do sleep 5; S=$((S+5)); [ $S -ge 570 ] && break; done
[ -f <run-dir>/receipt.json ] && cat <run-dir>/receipt.json || echo PENDING

PENDING reports a delegate still producing: run the identical call again, as many rounds as the work takes. The bound rides the in-loop counter — no timeout binary sits on PATH. A launch alone yields no product and no notification; the hold is the wrapper's whole job, and the receipt is its first output.

[EVENT_STREAM] — events.jsonl vocabulary:

• thread.started{thread_id} (the resume id)
• turn.started, item.started/item.completed, then turn.completed (with usage) or turn.failed
• agent_message carries the final text, command_execution carries {command, aggregated_output, exit_code, status}
• item.type=="error" item is NOT a run failure — the skills-budget warning rides one on every run under a large library; the receipt classifies by turn events only.

[04]-[MODEL_AND_EFFORT]

Default configuration carries non-trivial writes, deep design, hard reviews, whole fix or critique fleets, and second perspectives without an override.

[INDEX]	[TIER]	[SELECT]	[USE]
[01]	low	--effort low	trivial glue: probes, extraction, classification, relabels
[02]	medium	--effort medium	menial writes and fan-out legs where throughput beats depth
[03]	xhigh	--effort xhigh	deeper single-agent reasoning for the hardest investigation, design, and review legs

[05]-[FAN_OUT]

Independent scopes run as concurrent delegates, one per scope, each with its own --dir; reconcile reports after all complete. Concurrent write runs against overlapping paths collide — partition write scopes or serialize.

Inside ONE delegate, collaboration.* is the subagent tool family — spawn_agent, send_message, followup_task, wait_agent, interrupt_agent, list_agents. Children share the workspace live, inherit the model, and inherit NO conversation turns unless fork_turns opts in — a spawn task is self-contained like any codex prompt.

• An injected developer-role gate admits children ONLY on imperative spawn wording in the user prompt or AGENTS.md/skill chain.
• Permissive "you may spawn" and developer_instructions mandates fail silently with zero spawns.
• grep the parent rollout for function_call items named spawn_agent, collab_tool_call is a stale marker and false-negative.
• A writing delegate writes its own report as its final act; the caller verifies (jq -e) — re-emitting a codex product through another agent's Write is lossy at scale.
• Row-shaped sweep rides ONE delegate's spawn_agents_on_csv: one worker per CSV row under the concurrency cap, output_schema typing each row and output_csv_path exporting the combined results.

[06]-[SESSIONS]

codex archive <id> / unarchive <id> is the reversible lifecycle; codex delete removes one session, its --force unreliable across spawned children — bulk cleanup is a date-scoped sqlite prune, matching rollout deletions, and VACUUM. [features] memories/chronicle rows gate those features independently of corpus deletion.

[STORE]: one rollout per session at ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<ts>-<uuidv7>.jsonl:

• Filename timestamp is LOCAL time, the payload's is UTC.
• session_index.jsonl LAGS live runs, so correlate by datestamped filename.
• Sqlite store filenames embed their migration generation — resolve the live name instead of pinning it.

[RESUME]:

• resume --last is valid only when nothing else ran in between; under concurrency resume by explicit id. -- --ephemeral runs record nothing.
• The receipt's thread_id (= thread.started.thread_id in events.jsonl) feeds --resume with the follow-up as the task file; resume --all surfaces sessions recorded under another cwd.

[07]-[REVIEW]

codex review runs an independent non-interactive review. Scope flags — --uncommitted, --base <branch>, --commit <sha> — are mutually exclusive with each other AND with a focus prompt: a prompt is valid only on bare codex review, and every focused scoped review routes through codex exec with an explicit diff task. A fleet-grade review delegate runs codex exec review — the same scope flags with --json, -o, and --output-schema typed findings.