superpowers/skills/using-superpowers/references/codex-tools.md

Subagent dispatch requires multi-agent support

Add to your Codex config (~/.codex/config.toml):

[features]
multi_agent = true

This enables the multi-agent tools that skills like dispatching-parallel-agents and subagent-driven-development use. Which tools you get depends on the multi-agent version your model preset selects (current presets run V2; older ones run V1). Trust your actual tool list over any table — including this one — when they disagree.

• Spawning: give children a clean context with spawn_agent {fork_turns: "none"}; the default "all" copies your entire transcript into the child. On Codex 0.145+, role files under ~/.codex/agents/ attach to isolated forks via agent_type. Full-history forks accept model and reasoning_effort overrides (only agent_type is refused there) — isolated forks are the SDD default for context hygiene, not because overrides require them.
• Fix rounds: resume the implementer with followup_task — it delivers your message, triggers a turn, and transparently reloads a child the harness evicted. Never dispatch a fresh implementer on the theory that a spawned agent cannot be messaged again; on V2 it always can.
• Lifecycle: V2 has no close_agent. Finished children are evicted automatically when slots are needed; leaving them unclosed costs nothing. Only V1 sessions have close_agent — there, close reviewers when their review returns, and close each implementer after its task's review passes.
• Model names: never copy a model name from a skill, table, or old session into spawn_agent without checking it against your current spawn allowlist — V2 accepts only V2-capable presets and hard-errors on the rest.

Waiting on children

wait_agent is an event subscription, not a poll: a long wait wakes the moment a child produces mailbox activity, with the same latency as a short one. Short-timeout polling buys nothing and costs a tool call — and a context rebill — per poll. In measured sessions, roughly two-thirds of all wait calls were short polls that timed out.

• While you still have local work, do not wait at all. A completed child's final answer is pushed into your mailbox and arrives with your next turn.
• When you are genuinely idle with children outstanding, issue ONE wait_agent with a long timeout_ms — 900000 (15 minutes) or more — and let the event wake you.
• Completion mail cannot wake an idle controller (it is delivered without triggering a turn); covering that idle window is wait_agent's only job. If a long wait times out, check list_agents for stuck children — do not fall back to short polls.

Environment Detection

Skills that create worktrees or finish branches should detect their environment with read-only git commands before proceeding:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

• GIT_DIR != GIT_COMMON → already in a linked worktree (skip creation)
• BRANCH empty → detached HEAD (cannot branch/push/PR from sandbox)

See using-git-worktrees Step 0 and finishing-a-development-branch Step 1 for how each skill uses these signals.

Codex App Finishing

When the sandbox blocks branch/push operations (detached HEAD in an externally managed worktree), the agent commits all work and informs the user to use the App's native controls:

• "Create branch" — names the branch, then commit/push/PR via App UI
• "Hand off to local" — transfers work to the user's local checkout

The agent can still run tests, stage files, and output suggested branch names, commit messages, and PR descriptions for the user to copy.