Platform Adaptation

Platform Adaptation

If your harness appears here, read its reference file for special instructions:

• Codex: references/codex-tools.md
• Pi: references/pi-tools.md
• Antigravity: references/antigravity-tools.md

也就是说，[codex-tools.md](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/using-superpowers/references/codex-tools.md?utm_source=gitcode_repo_files) 不是独立的工具手册，而是 Codex 宿主下 Superpowers 技能的“行为修正层”：它告诉技能在 Codex 环境下该做什么、不该做什么。全文只有三个部分——子代理调度、环境检测、Codex App 收尾——每一节都对应一个具体的运行时差异。

## 子代理调度：开启 multi_agent 特性

Superpowers 的多个技能依赖“派生子代理”这一能力，例如 [dispatching-parallel-agents](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/dispatching-parallel-agents/SKILL.md?utm_source=gitcode_repo_files)（并行派发独立任务的子代理）和 [subagent-driven-development](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/subagent-driven-development/SKILL.md?utm_source=gitcode_repo_files)（逐任务派发实现者子代理并做评审）。在 Codex 上，这些能力需要显式开启。

参考文件 [codex-tools.md](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/using-superpowers/references/codex-tools.md?utm_source=gitcode_repo_files#L1-L10) 给出的配置是向 Codex 配置文件 `~/.codex/config.toml` 追加：

```toml
[features]
multi_agent = true

开启后，Codex 会暴露三个多代理工具：

工具	用途
spawn_agent	派生（生成）一个新的子代理线程
wait_agent	等待子代理完成并取回其结果
close_agent	关闭已完成的子代理，释放资源

一个值得注意的细节：multi_agent 是替代早期已废弃的 collab 特性的新开关。RELEASE-NOTES.md 记录了这一变更——“Codex docs fix — replaced deprecated collab flag with multi_agent in Codex documentation”，因此在新环境中配置时不应再使用 collab。

子代理的关闭时机：由修复循环决定的生命周期

参考文件对 close_agent 的使用时机给出了非常具体的规则，这直接对应 subagent-driven-development 技能的修复循环（fix loop）设计：

• 评审者子代理：评审返回后立即关闭；
• 实现者子代理：保持开启，直到该任务通过评审才关闭——因为修复循环的第 1–3 轮会向同一个实现者续发消息（resume），它的上下文仍然完整；
• 降级路径：如果宿主无法向已派生的代理续发消息，则每一轮修复都改派一个全新的实现者，随派发携带任务简报文件（brief）、报告文件（report file）和发现清单（findings）。

这条规则与 subagent-driven-development/SKILL.md 中的修复循环描述互相印证：

Rounds 1-3 — resume the original implementer. Send it the open findings verbatim. Its context is intact: it knows the task, the code, and its own choices. If your harness cannot send another message to a live subagent, dispatch a fresh implementer carrying the brief path, the report-file path, and the findings — the report file is the persistent memory either way.

换句话说，Codex 参考文件把“resume 优先、报告文件为持久记忆、新派发兜底”这套循环语义翻译成了 Codex 特有的代理生命周期操作：能 resume 就续用（所以实现者要一直开着），不能 resume 就换新。这也是该参考文件随修复循环重设计而同步演进的结果，见 2026-07-15-sdd-fix-loop-redesign.md 中对这段文字的重写记录。

环境检测：三条只读 git 命令判断沙箱状态

参考文件的第二部分是全文的技术核心 codex-tools.md：

## 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)

这三条命令全部是只读操作（`rev-parse` 与 `branch --show-current` 不产生任何副作用），在任何沙箱下都能安全执行，从而在动手之前判定环境。它们派生出两个信号：

1. **已在链接 worktree 中**：`GIT_DIR != GIT_COMMON`。普通仓库中两个值都解析到同一个 `.git` 目录；而在链接 worktree 中，`git-dir` 是 `.git/worktrees/<name>`，`git-common-dir` 是 `.git`。
2. **处于游离 HEAD**：`BRANCH` 为空，表示当前不在任何命名分支上——在 Codex App 的沙箱 worktree 中，这意味着无法创建分支、推送或开 PR。

### 为什么用 git-dir 对比 git-common-dir，而不是 show-toplevel

设计规格 [2026-03-23-codex-app-compatibility-design.md](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md?utm_source=gitcode_repo_files#L42-L51) 给出了选择该信号组合的四个理由：

- 普通仓库中 `git-dir` 与 `git-common-dir` 解析到同一 `.git` 目录；
- 链接 worktree 中 `git-dir` 是 `.git/worktrees/<name>` 而 `git-common-dir` 是 `.git`；
- **子模块场景两者相等**，避免了 `show-toplevel` 方案会产生误判的假阳性；
- 通过 `cd ... && pwd -P` 解析绝对路径，同时处理了相对路径问题（普通仓库中 `git-common-dir` 返回相对的 `.git`，worktree 中返回绝对路径）和符号链接问题（macOS 的 `/tmp` → `/private/tmp`）。

当前 [using-git-worktrees/SKILL.md](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/using-git-worktrees/SKILL.md?utm_source=gitcode_repo_files#L26-L31) 的 Step 0 还在检测命令之上加了一道**子模块防护**，作为对误判风险的进一步加固：

```bash
# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

检测信号驱动的两张决策表

worktree 技能侧——using-git-worktrees 的 Step 0 规定：若 GIT_DIR != GIT_COMMON（且非子模块），则跳过 worktree 创建，直接进入项目安装与基线测试，并按分支状态报告（在分支上 / 游离 HEAD 由宿主管理）。若相等，则走完整的原生工具优先、git worktree add 兜底的创建流程。

收尾技能侧——finishing-a-development-branch 的 Step 2 用同一组信号决定展示哪个菜单、如何做清理：

状态	菜单	清理
GIT_DIR == GIT_COMMON（普通仓库）	标准 3 选项	无 worktree 可清理
GIT_DIR != GIT_COMMON，命名分支	标准 3 选项	基于来源判断（见 Step 6）
GIT_DIR != GIT_COMMON，游离 HEAD	缩减 2 选项（无本地合并）	外部管理——保留不动

设计规格中的完整决策矩阵（规格文档）：

链接 worktree？	游离 HEAD？	环境	行为
否	否	Claude Code / Codex CLI / 普通 git	完整技能行为（不变）
是	是	Codex App worktree（workspace-write 沙箱）	跳过 worktree 创建；收尾时输出交接负载
是	否	Codex App（Full access）或手动 worktree	跳过 worktree 创建；完整收尾流程
否	是	少见（手动游离 HEAD）	正常创建 worktree；收尾时给出警告

规格文档同时记录了在 Codex App 上实测得到的沙箱行为边界（实测数据）：

操作	workspace-write 沙箱	Full access 沙箱
git add / git commit	可用	可用
git checkout -b	被阻断（不能写 .git/refs/heads/）	可用
git push	被阻断（网络 + .git/refs/remotes/）	可用
gh pr create	被阻断（网络）	可用
git status/diff/log	可用	可用

另有两个关键实测发现：spawn_agent 派生的子代理共享父线程的文件系统（通过标记文件测试确认），这正是“报告文件作为持久记忆、跨代理交接”可行的前提；以及 Codex App 头部始终提供 “Create branch” 按钮，其原生收尾流程为 Create branch → Commit 弹窗 → Commit and push / Commit and create PR。

Codex App 收尾：沙箱内的交接协议

当环境被判定为“外部管理的 worktree + 游离 HEAD”——即沙箱阻断分支/推送操作时——参考文件的第三部分 Codex App Finishing 规定了 Agent 的收尾行为：

## 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.