mirror of
https://github.com/obra/superpowers.git
synced 2026-07-26 04:04:03 +08:00
5ab3297ad7
README gains the hook install step for Codex users (hooks.json merge, one-time trust prompt, --dangerously-bypass-hook-trust for headless automation). codex-tools.md aligns its claims with the mechanism — the dispatch rules bind every spawn, the printed hints appear at scripted boundaries, and the hook covers post-compaction re-grounding — and adds a section telling controllers compaction sheds these instructions and to treat every printed hint as authoritative. The hints file gains a drift-cure footer both scripts print after the role line: in the instrumented run that broke post-compaction, reprinted hints alone did not heal the already-broken dispatch pattern across three subsequent boundaries — recovery text must name the drift and prescribe the re-read. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
## Subagent dispatch requires multi-agent support
|
|
|
|
Add to your Codex config (`~/.codex/config.toml`):
|
|
|
|
```toml
|
|
[features]
|
|
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.
|
|
|
|
## SDD dispatch on Codex
|
|
|
|
Every SDD `spawn_agent` call sets `fork_turns: "none"` — the default
|
|
`"all"` forks your whole transcript into the child and refuses model
|
|
and effort overrides.
|
|
|
|
If your `spawn_agent` schema has `model` and `reasoning_effort`
|
|
parameters (Codex 0.145+), set both on every dispatch: task-brief and
|
|
review-package print a `dispatch:` hint line with the exact values —
|
|
copy it onto the call verbatim, every time, even late in a long
|
|
session. The hints print at those scripts' boundaries; every other
|
|
spawn — ad-hoc fan-outs included — follows the same table without a
|
|
printed reminder. Those hints are the Model Selection mapping on Codex:
|
|
reviewer tier never exceeds implementer tier, no fix round gets an
|
|
effort bump, and rounds 4-5's "more capable model" means a fresh
|
|
implementer at the same tier — needing more is a BLOCKED escalation
|
|
to your human partner. Inherited frontier-tier subagents are a
|
|
measured cause of runs spinning out for hours. (Values live in
|
|
`codex-dispatch.hints` beside this file; they track the spawn_agent
|
|
model allowlist.)
|
|
|
|
Without those parameters (Codex 0.144 and earlier), children inherit
|
|
your model and effort with no override — role files in
|
|
`~/.codex/agents/` do not attach to spawns either. Tell your human
|
|
partner before starting a plan of more than a few tasks, and offer a
|
|
lower-effort session instead.
|
|
|
|
## Compaction sheds these instructions
|
|
|
|
Context compaction replaces your transcript with a summary that keeps
|
|
your progress but not your working instructions — the first
|
|
post-compaction dispatch is where routing drift starts, and once one
|
|
bare spawn lands, the broken pattern becomes its own precedent. The
|
|
compaction re-injection hook (README, "Codex: compaction re-injection
|
|
hook") restores the bootstrap after every compaction; recommend it to
|
|
your human partner if it is not installed. Without it, the printed
|
|
`dispatch:` hints are your only re-grounding — treat every one you see
|
|
as authoritative, especially right after a summary appears in your
|
|
context.
|
|
|
|
## Environment Detection
|
|
|
|
Skills that create worktrees or finish branches should detect their
|
|
environment with read-only git commands before proceeding:
|
|
|
|
```bash
|
|
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.
|