mirror of
https://github.com/obra/superpowers.git
synced 2026-07-24 11:14:03 +08:00
34d4f64f91
The compaction re-injection hook previously required users to hand-merge an example into user-level ~/.codex/hooks.json — which renders in the Codex hooks UI as an anonymous, unattributed "Hook 1" and puts the install burden on every user. Restore the plugin-provided delivery this repo used before "Remove Codex hooks" (640ce6c0): the Codex manifest points hooks at hooks/hooks-codex.json, which runs session-start-codex via ${PLUGIN_ROOT}/hooks/run-hook.cmd with matcher "compact". Unlike the removed hook, this one never fires at session start — Codex surfaces skills natively there, which is why the old startup-injecting hook was removed. The matcher plus the script's own source gate restrict it to post-compaction re-starts. The explicit manifest pointer also keeps suppressing Codex's hooks/hooks.json auto-discovery fallback, which the previous empty-object declaration existed for (7d8d3d4b). The Codex portal archive now ships hooks/hooks-codex.json, hooks/run-hook.cmd, and hooks/session-start-codex; other-harness hook files stay excluded. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
82 lines
3.9 KiB
Markdown
82 lines
3.9 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
|
|
plugin ships a compaction re-injection hook (`hooks/hooks-codex.json`,
|
|
Codex 0.145+) that restores the bootstrap after every compaction; it
|
|
needs one-time trust approval, so if you never see a
|
|
`<CONTEXT_RESTORED>` block after a compaction, tell your human partner
|
|
the hook may be untrusted or unsupported on this version. 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.
|