/codex-handoff

Claude Code Host Adapter

Load this adapter only when SKILL.md selects the Claude Code orchestration surface. Do not read or apply the Codex CLI adapter in the same handoff.

This adapter requires Git, /bin/bash, Python 3, and an authenticated Codex CLI with dangerous bypass support. Claude Code 2.1.98+ is recommended for live progress through the Monitor tool. Stop with a compatibility error when a required runner prerequisite is unavailable.

Research Mechanics

For each research agent selected by the shared contract, resolve ../scripts/run-codex-handoff.sh relative to this file and use the implementation launch template with --read-only. Give every agent separate <agent-id>.progress.jsonl, <agent-id>.result.json, and <agent-id>.stderr.log artifacts. Start all selected agents as background Bash tasks (run_in_background: true) in the same turn, then watch the wave through the implementation watcher and Monitor flow below. The runner-enforced read-only sandbox permits this launch in any host mode.

Give each research agent a self-contained prompt containing the open questions, exact investigation scope, read-only boundary, relevant repository constraints, and stopping rule from the shared prompt contract. Require every field in research-result.schema.json; prohibit plans, design decisions, and edits.

When the user has not explicitly included research agents in a model preference, select research configuration from these tiers:

Under this default selection, use Luna for bounded surveys and Sol for involved ones; Astra is implementation-only — research gathers evidence, the parent synthesizes. Never select low, ultra, or max. Research should normally use shorter budgets than implementation; keep the baseline between 10 and 15 minutes unless repository evidence says otherwise.

When the research wave settles, parse each result against research-result.schema.json, read its stderr artifact for failure forensics, and return the findings to the shared Research Phase for the plan or research-only response. Do not reconcile the working tree.

Plan Manifest and Configuration

Use this exact host-specific table inside the shared ## Codex Handoff plan section:

| Agent | Wave | Depends on | Scope              | Model                                    | Effort                  | Timeout             | Implementation brief                                   | Completion evidence                 |
| ----- | ---- | ---------- | ------------------ | ---------------------------------------- | ----------------------- | ------------------- | ------------------------------------------------------ | ----------------------------------- |
| `A1`  | `1`  | `none`     | `<files/behavior>` | `<gpt-6-luna\|gpt-6.1-sol\|gpt-6-astra>` | `<medium\|high\|xhigh>` | `<minutes> minutes` | `<outcome, edits, constraints, and stopping criteria>` | `<commands and observable results>` |

When the user has not specified a model preference, select implementation configuration from these tiers:

An explicit user model preference replaces this task-complexity model selection, but effort and timeout still follow the applicable work tier. Never select low, ultra, or max. Adjust a timeout when repository evidence shows that required validation needs materially more or less time. The timeout is a kill-switch, not pacing: Codex never sees it and an early finish costs nothing, so size it only to bound how long a hung agent can block its wave.

Keep the highest-tier agent's scope minimal and move deferrable validation to the validation owner.

Execution Mechanics

Launch

Resolve ../scripts/run-codex-handoff.sh to an absolute path relative to this file; never search for it in the target repository. Each invocation is one Codex agent.

Without --read-only, the runner deliberately disables Codex approvals and sandboxing. Use that mode only after the user approves the plan and accepts that agents can read, modify, or delete any files accessible to the host account. The runner pins every Codex process to the default service tier, overriding inherited fast or priority selection without changing persisted Codex configuration.

Before implementation wave 1, the Claude parent promotes the named draft recorded over the full manifest write-scope union during the shared Plan Phase: ai-coord start --draft <plan-slug> (or ai-coord bundle start --draft <plan-slug> for two or more Git roots). Only when promotion reports no draft named ..., use the plan's explicit ai-coord start '<label>' '<path>'... fallback (or ai-coord bundle start '<label>' '<absolute-path>'...) over that union. Name exact files individually and use --recursive only for true subtrees; require READY before launch. When the claim queues or blocks, run ai-coord wait as a background Bash task (run_in_background: true) so its return wakes the session, and apply the shared wake handling; never end the turn to pause. Hold that claim through reconciliation, required polish, and commit; the parent claim authorizes each delegate's assigned writes and is not a conflict.

One work item per session requires the full union up front. When follow-on work expands the scope, do so only at a wave boundary: run ai-coord done, then start a fresh item over the enlarged union before launching the next wave.

For every agent, create separate per-agent artifact paths ending in <agent-id>.progress.jsonl, <agent-id>.result.json, and <agent-id>.stderr.log under ${TMPDIR:-/tmp}. Convert its approved whole-minute timeout to seconds only at the wrapper boundary, then start the runner from anywhere inside the target Git worktree as a background Bash task (run_in_background: true) with a description like Codex A1/3: <scope> (<model>, <effort>, ≤<minutes>m):

bash <skill-dir>/scripts/run-codex-handoff.sh \
  --model <agent-model> \
  --effort <agent-effort> \
  --timeout-seconds <agent-minutes-times-60> \
  --coord-identity claude/<parent-session-id> \
  --progress-file <agent-progress-file> \
  --result-file <agent-result-file> \
  2> <agent-stderr-file> <<'CODEX_PROMPT'
<agent implementation prompt>
CODEX_PROMPT

--result-file keeps structured JSON out of stdout, and redirecting stderr keeps wrapper diagnostics out of the background task display. Do not set a Bash-tool timeout; the wrapper's --timeout-seconds is the sole timeout authority and always terminates itself. Start sequential agents only after reconciling their dependencies. Start every agent in a parallel wave in the same turn. Pass the same --coord-identity on every fresh or resumed implementation launch. Research launches omit it because read-only agents make no writes and remain separately visible.

Delegate prompts forbid ai-coord lifecycle commands. Delegates launched with --coord-identity share the orchestrating session's coordination identity. The guard now rejects a delegate's ai-coord draft, ai-coord start, ai-coord bundle draft, ai-coord bundle start, ai-coord wait, or ai-coord done with exit 64 and lifecycle commands are not allowed from a delegate of <client>/<session>; the parent's claim covers this work. Require every implementation prompt to say this explicitly, permitting only ai-coord status, ai-coord touched, ai-coord inbox, ai-coord msg, and ai-coord finding; also state that the parent's claim authorizes the assigned writes rather than conflicting with them.

Delegate claims and work no longer appear as separate ai-coord status work rows; transient Codex thread inventory may remain visible while delegates run, and per-delegate progress lives in handoff artifacts.

Add these host constraints to the shared implementation prompt:

• Honor ~/.codex/rules/*.rules, which the CLI enforces even under the bypass flag. Non-interactive runs reject prompt-gated commands outright. Skim existing rules and include relevant restrictions in the prompt.
• Baseline command conventions: use rg, not grep variants; use uv run python and uv add or uv run --with, never bare Python or pip; keep Bash-only constructs inside an explicit bash <<'EOF' block; avoid recursive removal, worktree-destroying or history-rewriting Git, secret-reading commands, and package deploy or release scripts.
• Require every field in result.schema.json. The wrapper passes that schema to Codex and writes the structured result to the selected artifact.

Watch

Research and implementation waves share this watcher. Read progress-events.md for the progress-event, sentinel, settlement, and quiet/failure contracts.

Resolve ../scripts/watch-codex-wave.sh relative to this file. Arm one Monitor per wave around one watcher invocation, passing each agent's stable ID, budget in seconds, and progress path as a repeated triple:

bash <skill-dir>/scripts/watch-codex-wave.sh \
  --agent A1 <budget-seconds> <A1.progress.jsonl> \
  --agent A2 <budget-seconds> <A2.progress.jsonl>

The watcher tolerates delayed file creation and emits stable JSONL watcher.digest, watcher.sentinel, and watcher.settlement records. It owns elapsed time, event counts, last relevant activity, settled percentage, and the ten-cell bar. Set the Monitor timeout_ms above the wave's largest budget plus the 120-second no-sentinel grace. On each digest or settlement, post one short wave-status block using those exact facts. If Monitor is unavailable, run the same watcher in a foreground command; do not recreate its loop or arithmetic.

Once Monitor is armed, wait for Monitor events. Do not launch Bash sleeps, tail artifacts, poll result or progress files, or add any second wait loop. Inspect artifacts only after settlement.

The watcher settles an agent as failed with reason no-sentinel once elapsed exceeds its budget plus 120 seconds of grace. Silence is never evidence of safety buffering or model rerouting. Keep watching until the wrapper sentinel or approved timeout; never cancel, retry, extend, or downgrade because of silence. Report no recent activity during quiet periods.

Collect and Reconcile

When a sentinel arrives, read the result artifact and the stderr artifact for the codex-handoff: elapsed=<seconds>s line or failure forensics. Do not read or print background-task output; artifact-mode stdout is intentionally empty. Parse implementation results against result.schema.json before applying the shared reconciliation rules.

At each wave boundary, if ai-coord status shows that a delegate narrowed the parent's claim, re-run the parent's full ai-coord start before continuing. This recovery applies only if a delegate bypassed the guard, for example with an unrelated identity; normally the lifecycle attempt is rejected with exit 64 in the delegate's stderr artifact.

Treat timeouts, nonzero runner exits, and watcher no-sentinel settlements as failed settlements, not returned plan blockers. For a handoff.failed sentinel with reason error, inspect stderr first. When it evidences a transport, stream, or API death and no Codex-reported task failure, inspect partial edits with git status and git diff. Extract the session ID from the progress file's thread.started event and perform the shared one allowed same-agent continuation through --resume <session-id> with a fresh budget and a short verify-and-continue prompt naming the partially edited files. Fall back to one fresh relaunch only when no session ID is recoverable. Returned blocked results and timeouts are never infrastructure failures.

Commit Delegated Work

Delegated writes are attributed to the parent session, so they cannot create a delegate residual or stale-dirt baseline for those paths. Reconcile, perform required polish, and commit under the held parent claim; release it only afterward.

Legacy troubleshooting: validate an unexpected residual session ID against thread.started and its dirt blob hashes against the reconciled diff. Ask before clearing coordination state. If matching auto-baselines exclude verified delegate edits, re-prepare with --no-auto-baseline and disclose it.

Status Reporting

These dashboards and the shared completion report are mandatory. Host-rendered background-task and Monitor banners are transport notifications, not status reports. Do not expose task IDs, raw JSON, sentinels, or monitor payloads.

Use this legend consistently: 🔎 research · 🚀 kickoff · ⏳ running · ✅ completed · ⛔ blocked · ⏱️ timed out · 💥 runner error · 🧹 polish · 🏁 final report. Keep each update to one compact rendered block.

Prefix every wave-scoped kickoff, digest, and completion update with the watcher's exact ten-cell bar, percentage, and settled counts. Progress means sentinel settlement, including failed sentinels; never infer it from elapsed time, event count, or activity.

Kickoff, once per wave:

### 🚀 Wave 1/2 [░░░░░░░░░░] 0% (0/3 settled) — 3 agents launched

| Agent | Scope               | Model · effort        | Budget | State       |
| ----- | ------------------- | --------------------- | ------ | ----------- |
| A1    | `internal/pricing`  | `gpt-6.1-sol` · high  | ≤20m   | 🚀 launched |
| A2    | `internal/backfill` | `gpt-6.1-sol` · high  | ≤20m   | 🚀 launched |
| A3    | `internal/evidence` | `gpt-6.1-sol` · xhigh | ≤40m   | 🚀 launched |

Research waves use 🔎 in their heading and investigation scopes in their rows.

Wave status, on each digest or completion:

### ⏳ Wave 1/2 [███░░░░░░░] 33% (1/3 settled) — 15m elapsed

| Agent · model/effort   | Status     | Activity                   |
| ---------------------- | ---------- | -------------------------- |
| A1 · gpt-6.1-sol/high  | ⏳ 15m/20m | ran `cargo test`           |
| A2 · gpt-6.1-sol/high  | ✅ 8m      | done — 3 files, tests pass |
| A3 · gpt-6.1-sol/xhigh | ⏳ 15m/40m | no recent activity         |

At full settlement, use the final watcher settlement record. A wave with failures still reaches 100%; its heading and rows must expose those failures.

Completion Report

Render ### 🏁 Codex handoff [██████████] 100% (<settled>/<total> settled) — <completed|blocked>. Include strategy, agent count, and wave count, then one row per agent with result, requested model and effort, timeout budget versus actual elapsed, output tokens when available, and summary. For a resumed retry, report its sentinel's output-token total minus the prior run's total as that attempt's usage.

Follow the table with ### 📦 Changed, ### 🧪 Verification, ### 🧹 Polish when applicable, automatic cross-repository commit hashes when any, and ### Issues and caveats with the shared contract's Resolved and Open groups. Omit empty issue groups and the whole section when empty; write none for other applicable empty values. Never expose result JSON.