Codex Delegate

Delegate Work to Codex (CLI channel, write access)

Let the local Codex take over a well-bounded task with write access, run it in the background, and accept the result via git.

When to Delegate

• Good fit: substantial debugging / implementation / root-cause investigation; the same problem is stuck after repeated attempts and an independent second implementation would help; the user explicitly hands it to Codex.
• Bad fit: simple tasks you can finish in a few steps yourself — don't delegate for delegation's sake.
• When stuck, proactively offer to delegate; don't wait for the user to name Codex.

Workflow

# 1) Acceptance baseline: git state must be distinguishable. Ask the user to
#    commit/stash pre-existing uncommitted changes first, otherwise Codex's
#    changes and the old ones blur into one diff and can't be accepted separately.
git -C "<repo>" status --short && git -C "<repo>" rev-parse HEAD

# 2) Write the task brief to /tmp/codex_task.md (template below)

# 3) Run in the background (Shell tool block_until_ms: 0; may take minutes
#    to tens of minutes). Timestamp the output file so parallel runs don't
#    overwrite each other; after launch, note the session id from the head
#    of the terminal log file.
OUT=/tmp/codex_task_out_$(date +%s).md
codex exec --sandbox workspace-write -C "<repo>" -p high \
  -o "$OUT" - < /tmp/codex_task.md

# 4) Acceptance: read the -o output first, then inspect the actual changes,
#    finally test against the acceptance criteria in the task brief.
git -C "<repo>" diff && git -C "<repo>" status --short

Task Brief Template (block-structured contract)

One task per run. Spell out what "done" looks like — don't expect Codex to guess:

<task>Goal: <one sentence — what counts as done>. Context: <relevant files, known clues, what has been tried>.</task>
<action_safety>Only touch <directory/file scope>; do not touch <exclusions>; no unrelated refactoring; do not run git commit/push.</action_safety>
<verification_loop>Verify your own changes: <how to run tests / reproduce>; if verification fails, keep fixing until it passes or you confirm it cannot pass.</verification_loop>
<default_follow_through_policy>Make routine decisions yourself without stopping to ask; only stop to explain if you find the task premise is wrong.</default_follow_through_policy>
<compact_output_contract>At the end, output: which files changed and why → verification results → residual risks / open items.</compact_output_contract>

Routing Discipline

• Pin the reasoning effort: always add -p high (~/.codex/high.config.toml, containing only model_reasoning_effort = "high"). The main config gets dynamically rewritten by the Codex app, so the effort there is not under your control — don't rely on it.
• Pass -m only when the user names a model. Fast/cheap channel example: -m gpt-5.3-codex-spark; for higher effort use -c model_reasoning_effort=xhigh.
• When the user says "continue / keep going / apply the fix from last time / dig deeper" → resume, don't start a new session; send only the incremental instruction, don't restate the task brief. Resume with the session id noted at launch, not --last (with parallel codex runs, --last resumes the wrong session; the id is in the terminal log file header as session id: <uuid>):

codex exec resume <session-id> -o "$OUT" "Apply the first fix you proposed last time" < /dev/null

Note: when passing the prompt via argv you must append < /dev/null, otherwise codex hangs waiting on stdin and never starts (the - < file form doesn't have this problem). Only fall back to resume --last if you didn't record the id AND you've confirmed no other codex run happened in the meantime.

• Keep routing decisions (background/foreground, model, resume) out of the task brief text.

Acceptance and Failure Handling

• Codex finishing ≠ task done: you must review the diff AND test against the acceptance criteria before reporting to the user.
• When reporting, state explicitly which files Codex changed; anything Codex marked as inferred/uncertain stays marked that way — don't flatten it into certainty.
• Unsatisfied with the changes: revert wholesale with git checkout -- . && git clean -fd (confirm with the user first); or resume and have Codex fix it itself.
• If Codex fails or bails out halfway: report the failure with the most useful stderr lines and stop to ask the user; do NOT quietly take over and do the task yourself — the user chose delegation precisely to get a second, independent implementation.

Hard Guardrails

• Sandbox: workspace-write only (cannot write outside the repo); never danger-full-access, never --dangerously-bypass-approvals-and-sandbox.
• Never let Codex run git commit/push; committing stays with the user.
• For long runs, check the terminal file periodically to confirm it isn't stuck; cancel with kill <pid> using the pid in the terminal file header.