/codex-handoff

Codex CLI Host Adapter

Load this adapter only when SKILL.md selects Codex's native orchestration tools. Do not read or apply the Claude Code adapter in the same handoff.

Native multi-agent support is required. Stop with a compatibility blocker if the orchestration tools become unavailable. Never invoke codex exec or fall back to any nested CLI process.

Native Agent Configuration

When the user has not specified a model preference, use these tiers for research and implementation:

Under this default selection, Astra at xhigh is the ceiling and Astra is implementation-only. Research agents use Luna or Sol — research gathers evidence, the parent synthesizes. Never select low, ultra, or max. Keep the highest-tier agent's scope minimal and move deferrable validation to the validation owner.

Spawn every research or implementation worker with a self-contained prompt and fork_turns: "none". This avoids copying the parent conversation and permits explicit model and reasoning_effort selection. Use a stable lowercase task name derived from its manifest ID and scope, and preserve the visible R1 or A1 ID in the prompt and report.

Never exceed the active-agent concurrency limit reported by the harness. Reserve one slot for the parent and account for other active workers when reported. Split a wider manifest into dependency-preserving waves; the eight-agent shared limit is total implementation agents, not concurrent width. With no reported concurrency cap, launch one worker at a time.

Codex subagents inherit the parent sandbox and approval policy: research stays under the parent's read-only controls, and implementation cannot bypass the permissions selected for the approved parent turn. For every research-only handoff, the shared prompt's strict no-edit boundary is mandatory; treat any reported edit as a contract violation.

Research Mechanics

For each selected research agent, call spawn_agent with fork_turns: "none", the selected model and effort, and the shared self-contained research prompt. Start all agents that fit the current concurrency allowance without waiting between launches; place any remainder in a later research wave.

Wait for native results with wait_agent. Fold the returned findings into the parent plan or research-only response per the shared Research Phase. Do not create progress, result, stderr, sentinel, or watcher artifacts. Treat any reported edit as a contract violation.

Plan Manifest

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

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

Use the native configuration table above for every manifest row unless the user's explicit preference overrides its model selection. Do not add artificial timeout budgets: native agent lifetime and waiting are owned by the harness.

Execution Mechanics

The ai-coord session that performs writes owns the claim. Native Codex subagents inherit the parent session identity, so the parent owns the coordination claim for every delegated write scope. 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. Every worker prompt must forbid those lifecycle commands and permit only ai-coord status, ai-coord touched, ai-coord inbox, ai-coord msg, and ai-coord finding. Include this fact in every worker prompt so the parent's claim is treated as authorization rather than a conflict; unrelated claims on the exact assigned scope can still block work.

Before implementation wave 1, the 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; require READY before launch. When the claim queues or blocks, run ai-coord wait as a foreground command with a command timeout above its -t value (300 seconds by default), apply the shared wake handling, and repeat until READY; never end the turn between waits.

After plan approval, call spawn_agent for each implementation worker with:

• fork_turns: "none";
• the model and reasoning_effort from its approved manifest row;
• a stable task name and a self-contained prompt satisfying the shared implementation prompt contract.

Start all independent workers that fit the concurrency allowance without waiting between calls. Reconcile the entire wave before launching dependents. Never spawn more workers merely because a thread is quiet.

Use wait_agent with timeout_ms: 900000 while any agent is running; it returns early for mailbox updates, completed results, or user steering. Codex's native thread UI is the progress surface: do not reproduce it with custom dashboards, polling loops, wrapper artifacts, or synthetic percentages. Ground any concise user update in an actual agent result or harness state.

Practice wait economy: when wait_agent returns without a settled result, an actionable mailbox message, or user steering, immediately call it again after the permitted fifteen-minute status update when one is due — no analysis, extra narration, or list_agents round-trips. Reserve reasoning and user-visible status for settlements, steering-worthy evidence, or that one compact update per roughly fifteen minutes of elapsed wave time; every idle wakeup otherwise costs a full model turn.

Use send_message only to steer a currently running agent when new evidence shows it is off track or missing material context. Do not use it for routine check-ins, completed agents, or retries.

Collection and Failure Handling

Read each completed agent's final message and require every field in the shared result contract. Apply the shared scope, validation, dependency-gating, and working-tree reconciliation rules before starting the next wave.

A returned status: blocked is a plan blocker, not an infrastructure failure. An agent-tool error or a final result missing required fields is an infrastructure failure only when the harness evidence supports that classification. After inspecting partial edits, use exactly one followup_task on that same agent with a short verify-and-continue prompt naming the partial files and missing evidence. Do not spawn a replacement agent. A second infrastructure failure blocks that agent and its dependents.

Completion Report

Rely on native thread rendering while work runs. At settlement, render ### 🏁 Codex handoff — <completed|blocked> with the strategy, total agent count, and wave count. Include a compact per-agent table with model, effort, result, and summary, then ### 📦 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.