Codex Subagents

---
name: codex-subagents
description: >-
  Use when dispatching subagent work to GPT models (gpt-6.1-sol, gpt-6-astra) via the Codex CLI, including inside Workflows.
---

# Codex Subagents

Two dispatch mechanisms. Model choice and when-to-escalate live in CLAUDE.md.

## Regular subagents: codex CLI

```bash
TASK_FILE=/path/to/task.md
codex exec -m gpt-6.1-sol -c model_reasoning_effort=medium -s workspace-write - < "$TASK_FILE"
```

- **Prompt transport**: write dynamic or untrusted task text to `TASK_FILE` with the Write tool, then pass the file on stdin. Keep task text out of the Bash command so it cannot alter shell syntax.
- **Sandbox**: `-s workspace-write` for implementation, `-s read-only` for investigation and review.
- **Untrusted directories**: outside a trusted git repo codex exits early — add `--skip-git-repo-check` or `git init` the scratch dir.
- **Parallel**: one background Bash call per task. Parallel implementation tasks get separate worktrees so edits don't collide.
- **Follow-up to the same worker**: `codex exec resume --last -m gpt-6.1-sol -c model_reasoning_effort=medium "<feedback>" </dev/null` — preserves that worker's context.
- **Timeout**: codex runs can exceed Bash's 10-minute default — pass an explicit timeout, or run in the background and poll for a report file.

## In Workflows: Sonnet wrapper

Workflow/Agent `model` parameters only take Claude models. To use a GPT model in a workflow stage, spawn a thin Sonnet wrapper that shells out and relays:

```js
agent(
  `Delegate the task between the tags to Codex. Create a temporary file with
mktemp, save only the tagged task text to it with the Write tool, then pass the
file on stdin to this fixed command (substitute only the shell-quoted temp path):
codex exec -m gpt-6.1-sol -c model_reasoning_effort=medium -s read-only - < <temp-path>

Return Codex's output verbatim, adding no analysis.

<task>
${task}
</task>`,
  {
    model: "sonnet",
    effort: "low",
    label: "gpt-6.1-sol:review-auth",
    schema: REPORT,
  },
);
```

- **Label with a `gpt-6.1-sol:` prefix** — the workflow UI shows the wrapper's Claude model, so the label is the only indication of the real worker.
- **`schema` on the wrapper** gets structured output back from codex's free-text report.
- **`isolation: 'worktree'`** for parallel implementation wrappers.
- Workflow token budgets only count Claude tokens; codex work is invisible to `budget.spent()`.

## Orchestrating

1. **Decompose** — each task gets acceptance criteria: observable, checkable outcomes (files changed, tests passing, behaviors demonstrated).
2. **Dispatch** — simple, self-contained prompts. Codex is not Claude: it does only what it's told, so drop guardrail scaffolding. Review/investigation prompts end with: "If you find nothing, say so clearly and name what you inspected."
3. **Verify** — check output against the acceptance criteria yourself (read the diff, run typecheck/tests). A worker's self-report is a claim, not evidence.
4. **Iterate** — `resume` with criteria-referenced feedback, ~3 rounds; then do it yourself or surface the blocker.
5. **Integrate** — final assembly, commits, and user-facing summary stay with the orchestrator.

When a worker misbehaves, ask what went wrong and append the fix here.

## Learned the hard way

- `codex exec resume` accepts `-m` and `-c` but not `-s`; the resumed session keeps the sandbox it was started with.
- `-s workspace-write` mounts `.git` read-only, so a worker cannot commit even inside the workspace. Tell workers never to run git; the orchestrator commits, per TODO, by staging paths.
- Plan before code, in two phases: first `codex exec -s read-only` with the task and "write your plan per TODO with the key choices, then stop"; review it against the acceptance criteria and post it on the issue if a human wants to see it. Phase two is a fresh `codex exec -s workspace-write` whose task file carries the approved plan, because a resumed session keeps the read-only sandbox. A single implementation run never shows its plan.
- Codex reads `~/.codex/AGENTS.md`, which is Mia's global rules including the Memory section, so a worker will try to run `memo`. Every task file starts with "You are a subagent. Don't run memo."
- Babysitting stays with the orchestrator: a review loop is hours of waiting, not a capability Codex adds.