126. Runner-owned policy for native Codex children
Date: 2026-09-29
Status
Accepted
Context
Review and retro dispatch sub-agents with fresh contexts and selected personas (agent architecture). On Codex they run in one context today: fullsend registers no roles, although Codex already offers its native spawn_agent tool to parent models whose catalog entry selects collaboration V1 (#6970).
ADR 0104 makes child models a runner decision and planned Codex support for agents[].subagents. Its persona frontmatter does not carry over: model: values are Claude aliases, and Codex has no per-child tool allowlist, so ADR 0104's rule that an unservable tools: list fails Bootstrap would reject every review persona. Codex also rereads a role's file and $CODEX_HOME/hooks.json whenever a child starts, so the launch-time checks of ADR 0100 do not cover children, and the model chooses the spawn arguments: context inheritance, model, effort and resume.
Options
- Single context (status quo). No new mechanism; review and retro keep no independent child contexts on Codex.
- Native children governed by instructions only. Nothing enforces fresh context, depth or model choice; a parent can fork its conversation into the challenger or pick any OpenAI model.
- Native children under a runner-owned role and dispatch policy (chosen).
- Option 3 plus write protection of the runtime's files. Closes the time-of-check window noted below. Each way to do it adds a platform requirement: Landlock needs kernel 6.2+ and a Python outside the sandbox's writable paths, and stops new top-level
$HOMEentries; a read-only OpenShell path is fixed at sandbox creation, before the per-run files exist; roles baked into the image tie them to image releases. A separate decision if the residual below is not acceptable.
Decision
Codex children run under a policy the runner provisions and enforces.
- Only an agent whose tools include
Agentdelegates, as on Claude Code and pi. Bootstrap registers its skill personas plus a genericdefaultand an instruction-onlyexplorerole. Other agents run with Codex's multi-agent tools off. - Child models resolve as in ADR 0104 without the frontmatter step:
subagents.<persona>, thensubagents.default, then the parent's live model. Only OpenAI model IDs are accepted, and an explicit model that cannot be served fails rather than falling back. Personamodel:andtools:frontmatter is reported, not applied. - A mandatory PreToolUse hook, installed even when optional security hooks are off, admits only a V1 spawn of a registered role with
fork_context: falseand no model or effort override. It rejects resume and any spawn from a child. Native configuration limits depth to one and open children to four. - Before admitting a spawn, the hook checks
hooks.jsonand the role files against digests the runner recorded at Bootstrap, as the ADR 0100 adapter does for each hook script before invoking it. - The hook fails closed: a policy violation, a digest mismatch, a missing file, unreadable input or any error in the hook denies the spawn with exit 2 and a reason, the only exit Codex treats as a block. Bootstrap fails if it cannot install the hook.
Consequences
- Review and retro can delegate on Codex once the paired instructions ship; a parent model whose catalog entry selects collaboration V2 cannot delegate under this policy.
- Departures from ADR 0104 on Codex: persona
model:is not applied, personatools:are instructions only (every child has the parent's shell andapply_patch), and an unregistered role is always rejected becausedefaultandexploreare always registered. codeandfixdeclare notools:, so they also get roles, as on pi.- The spawn-time check has ADR 0100's residuals: a change that lands between the check and the child's load goes undetected within the iteration, and a handler Codex cannot complete, such as one that times out, is recorded as failed and does not block.
- Token totals include children, attributed per native thread; Codex still reports no dollar cost.
- Role loading, hook reload and collaboration tool names are revalidated on each Codex CLI bump.
