From 75756d2900fc17e338f243886ade5998f5a4d78b Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Thu, 30 Jul 2026 10:32:01 -0700 Subject: [PATCH] fix(codex): correct multi-agent guidance against Codex source Five claims contradicted by the Codex CLI source (V2 has no close_agent; followup_task always reaches a child; role files attach via agent_type; full-history forks accept model/effort; V2 spawn allowlist). Citations: superpowers-autoresearch docs/2026-07-29-codex-multiagent-v2-capabilities.md. --- .../references/codex-tools.md | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/skills/using-superpowers/references/codex-tools.md b/skills/using-superpowers/references/codex-tools.md index b14b5858..415638f6 100644 --- a/skills/using-superpowers/references/codex-tools.md +++ b/skills/using-superpowers/references/codex-tools.md @@ -7,7 +7,34 @@ Add to your Codex config (`~/.codex/config.toml`): multi_agent = true ``` -This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. When using subagent-driven-development, close reviewer subagents when their review returns. Keep each implementer subagent open until its task's review passes — the fix loop resumes the implementer — then close it. If your harness cannot send another message to a spawned agent, dispatch each fix round as a fresh implementer carrying the brief, the report file, and the findings. +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. ## Environment Detection