---
substrate: claude-subagent
适用: 总控是 Claude Code，节点执行者也是 Claude（自调自）
updated: 2026-07-28
---

## 探测

Claude Code 会话内 Agent 工具原生可用，恒成立。模型按偏好或用户指定通过 model 参数传入（不指定则继承会话模型）。

## 派发

- 一**角色**一后台子 agent（起名如 `impl-<slug>` / `review-<slug>`，便于 SendMessage 寻址），跨轮次复用。首派 prompt 给四样：加载哪个 eo-* skill、change 目录路径、本轮收敛标准、必要输入（如 review 反馈路径）；命中 SKILL.md 的条件式 Execution Guard 时再附其即时控制包，不落独立文件
- 控制包要求 worker 仅把 A 类选择随交付记录；命中 B / C 类时在变更前停止受影响分支，通过 SendMessage 向总控发结构化求裁决信号（类别、分叉、影响、推荐），等总控回灌裁决后再续原 agent
- **轮次复用 = SendMessage 发回原 agent**：修复轮、增量复审、打回重做、追问，一律续原上下文，不重开新 agent；重建时机见 SKILL.md 复用纪律
- 相互独立的节点（如同一基线上的 test 与 review）才并行；并行 >2 个先报预算等点头
- 并行组 worker（同层批 / 并行收敛组，SKILL.md ③）：spawn 时启用 worktree 隔离（Agent 工具 `isolation: worktree`），一 worker 一现场；合流 checkpoint 按 granularity §6 指派执行

## 等待与观测

后台子 agent 完成会自动唤醒总控（harness 级信号，无需 worker 配合），这是主信号。10 分钟兜底窗口：等待期挂起必须带超时（定时唤醒 / Monitor 均可）。窗口内观测**只读产物不打扰 worker**：change.md 勾选、review/test 台账增量、git log——不 SendMessage 问「进展如何」（打断即污染 worker 上下文）。到点发进度报告再续等。

## 回收

完成通知只用于唤醒总控和定位产物。正常路径按 SKILL.md ③ 读取 frontmatter 当前状态、预期工件指针、当前基线与最新结构化处置后直接路由，不打开完整 diff、不抽查或复做节点内容。只有这些事实缺失 / 冲突、出现可观察越界、计划外判据变化、Unknown B / C 或证据探测失败等客观风险信号时，才针对对应异常升级；需要实质判断就派 eo-review / eo-test，不由总控补做节点工作。

## 已知陷阱

> 本节只放出厂陷阱；运行时陷阱记在 `~/.eo-skills/loop/preferences/` 的「已知陷阱」节（前缀 `[claude-subagent]`），一并读。

- (2026-07-19) 子 agent 上下文独立：prompt 里不给 change 路径它就会自己猜——路径必给
- (2026-07-19) 用词锚定：prompt 写「看看 / 检查一下」会弱化执行强度——用节点本义动词（审查 / 实施 / 验证）
- (2026-07-24) Agent 工具偶发 teammate pane 创建超时（「Timed out waiting for the Orca runtime / tmux split pane handle」，orca status 却显示 ready、CLI 建终端正常）：重试 2 次仍失败即切换基底——orca 终端跑 `claude --model <id> --dangerously-skip-permissions`，走 orca-orchestration 的 task/dispatch 流程，模型钉住不变

---
substrate: codex-subagent
适用: 总控运行在 Codex CLI 侧（eo-loop 被 Codex 加载执行）
updated: 2026-07-28
---

## 探测

运行环境即 Codex（`$` 前缀 skill 可用）即成立。总控在 Claude 侧而节点要 codex 模型的**跨侧**场景不属本基底——走 orca-orchestration。

## 派发

- skill 前缀是 **`$`**：`$eo-review <change 路径>`。任何时候不能写成 `/`
- prompt 遵守 SKILL.md 的最小输入；仅命中条件式 Execution Guard 时附即时控制包，不将控制包写成 `PROGRESS.md` 或其他状态文件
- 控制包要求仅 A 类随交付记录；命中 B / C 类时在变更前停止受影响工作，通过当前 Codex runtime 的 agent 消息能力发结构化求裁决信号；无可用消息能力则停止节点并以 `DECISION GATE` 结果返回，不得先采假设实施
- 子 agent / spawn 能力按 Codex 当前版本探测使用；不可用则降级为本会话顺序执行节点
- 模型与 effort 是启动参数、中途不可切——需要不同 effort 的节点分开派发
- **同角色跨轮次复用同一子会话**续发下一轮；机制上续不了则同参数重开，prompt 附上一轮报告路径作上下文补偿
- 并行组 worker（同层批 / 并行收敛组，SKILL.md ③）：一 worker 一独立现场（`git worktree add`）；无法隔离现场则不并行，降级串行

## 等待与观测

Codex 侧无完成自动唤醒时，总控主动轮询**产物**（frontmatter、台账、git log），间隔 ≥5 分钟；不向 worker 发消息催报。单窗 ≤10 分钟，到点发进度报告再续等。

## 回收

完成消息只用于唤醒总控和定位产物。正常路径按 SKILL.md ③ 读取 frontmatter 当前状态、预期工件指针、当前基线与最新结构化处置后直接路由，不打开完整 diff、不抽查或复做节点内容。只有这些事实缺失 / 冲突、出现可观察越界、计划外判据变化、Unknown B / C 或证据探测后仍未知等客观风险信号时，才针对对应异常升级；需要实质判断就派 eo-review / eo-test，总控不兼任实施、测试、审查。

## 已知陷阱

> 本节只放出厂陷阱；运行时陷阱记在 `~/.eo-skills/loop/preferences/` 的「已知陷阱」节（前缀 `[codex-subagent]`），一并读。

- `$` / `/` 前缀混写是派发高频错误，派发前自查一遍

---
substrate: orca-orchestration
适用: 节点要跨 agent 运行（执行者与总控不是同一 agent/模型栈），且需要总控监督
updated: 2026-07-28
---

## 探测

1. **先加载 `orchestration` skill 本体**（Claude 侧用 Skill 工具调 `orchestration`，codex 侧 `$orchestration`），加载完成前不得敲任何 `orca orchestration` 命令。本文件不是命令手册，只是 eo-loop 场景的增补与陷阱清单——命令契约、生命周期语义（worker_done 自动完结、handle 解析、preamble 规则）一律以 skill 本体为准，两边冲突时信 skill 并回修本文件。
2. `orca status --json` 显示 runtime 运行中，且 orchestration 实验特性已开启。失败 → 向用户提示启动 Orca 或换基底。

## 派发

1. **总控身份钉桩**（每次派发前、每个等待窗开始时重做）：按自己的 `$ORCA_PANE_KEY`（= `tabId:leafId`，跨 Orca 重启稳定）从 terminal list 解析自己 pane 的**当前** handle：

   ```sh
   COORD=$(orca terminal list --json | jq -r --arg pk "$ORCA_PANE_KEY" '.result.terminals[] | select((.tabId + ":" + .leafId) == $pk) | .handle')
   ```

   后续收发一律显式带 `$COORD`，**禁用隐式身份解析**（省略 `--from`/`--terminal` 时 CLI 按 `$ORCA_TERMINAL_HANDLE` 环境变量解析——那是会话启动时烙死的，Orca 重启后即过期，见陷阱节）
2. `orca orchestration task-create --spec "<节点目标 + change 路径 + 收敛标准>"`；命中 SKILL.md 的条件式 Execution Guard 时，把即时控制包一并放进 spec，不额外落盘，并要求 worker 仅随交付记录 A 类、B / C 类在变更前发 `decision_gate` 后暂停
3. 建 worker 终端：implement / test / review 依赖当前工作区状态，用 `orca terminal create --worktree active --command "<agent 启动命令>"`；自定义模型/effort 写进启动命令（如 `codex --dangerously-bypass-approvals-and-sandbox -m <model> -c model_reasoning_effort="high"`——codex 不带 bypass 会每步卡权限审批）
4. `orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000` 就绪后 `orca orchestration dispatch --task <id> --to <handle> --from $COORD --inject`
5. **轮次复用**：`worker_done` 后 worker 停在 agent 提示符，正好接下一轮——同一 change 内的同角色新任务 `task-create` 后 `dispatch --to <同一 handle> --inject` 续用同一终端，不重建；收敛组切换到下一 change 时按 SKILL.md 复用纪律一律重建终端重派。模型/effort 是启动参数，复用即锁定该组合；要换模型才重建终端（handle 报 stale 时 `terminal list` 重解析后仍按原终端续用）
6. **并行组 worker**（同层批 / 并行收敛组，SKILL.md ③）：一 worker 一独立 Orca child worktree 起终端，**不得共用 active 工作区**；合流 checkpoint 按 granularity §6 指派其一执行合并

## 等待与观测

每窗开始先重做「派发」第 1 步的身份钉桩（Orca 若重启过，handle 已漂移），然后 `orca orchestration check --wait --terminal $COORD --types worker_done,escalation,decision_gate --timeout-ms 600000`——只等**必要信号**（完成 / 升级 / 求裁决），**不要求 worker 发 heartbeat**（dispatch 注入的 preamble 之外不追加任何回报要求，worker 专注任务）。窗口超时不是 worker 失败：总控主动观测——`terminal read` 看输出、`tui-idle` 探活、读台账增量——活着就发进度报告进下一窗。禁止 sleep 轮询。收到 `decision_gate` / `ask` 用 `reply` 应答后继续等。

## 回收

`worker_done` 只用于唤醒总控和定位产物。正常路径按 SKILL.md ③ 读取 frontmatter 当前状态、预期工件指针、当前基线与最新结构化处置后直接路由，不打开完整 diff、不抽查或复做节点内容。只有这些事实缺失 / 冲突、出现可观察越界、计划外判据变化、Unknown B / C 或证据探测失败等客观风险信号时，才针对对应异常升级；review-only 的 `worker_done` 不授权总控动手修，修复派回原 impl worker 走 /eo-fix 循环内分支，需要实质判断则按 owner 规则派 eo-review / eo-test。

## 已知陷阱

> 本节只放出厂陷阱；运行时陷阱记在 `~/.eo-skills/loop/preferences/` 的「已知陷阱」节（前缀 `[orca-orchestration]`），一并读。

- (2026-07-19) 终端有输出 ≠ 完成，不要据此杀 worker 重派；长任务 15-60 分钟是常态
- (2026-07-19) terminal handle 重启后会变，报 `terminal_handle_stale` 时用 `terminal list` 重解析；绝不用 handle 对比判归属
- (2026-07-19) 同一 task 连败 3 次会被 runtime 熔断置 failed——第 2 次失败就该停下向用户报卡点，别撞到熔断
- (2026-07-25) **claude TUI worker 的注入/提交竞态**（codex 弹窗吞注入的姊妹陷阱）：dispatch --inject 后立刻补回车会**跑在注入文本前面**——空回车先落、任务文本后到，文本干坐输入框永不执行；有时注入整体被吞（框内空无一物）。标准姿势：dispatch 后先 `terminal read` 验证任务文本**已在框内**再 `send --enter`；框内为空 = 注入被吞，用 task-list 取 spec 原文 `terminal send --text "<spec>" --enter` 补投（附 worker_done 上报命令）。另：claude worker 终端在完成一轮 worker_done 后常变 terminal_not_writable——轮次复用前先探测，不可写即重建终端重派
- (2026-07-24) codex 终端刚创建即 dispatch --inject，注入会被启动期的目录信任弹窗吞掉（dispatch 状态仍显示成功）：必须先 `terminal wait --for tui-idle` **满足**（satisfied:true）再 dispatch；已被吞时任务卡 dispatched 态无法重派，救法 = `terminal send --enter` 手动补投任务文本（附 worker_done 上报命令，--to 填总控终端 handle）
- (2026-07-24) worker_done 未必自动完结任务：skill 本体口径是**有效** worker_done 会自动置 completed；总控收信身份脱节时（见下条）runtime 关联不上就不会。同终端派下一轮前先 `task-list` 核对上轮状态，仍卡 dispatched 才手动 `task-update --id <上轮task> --status completed` 兜底（合法状态枚举：pending/ready/dispatched/completed/failed/blocked，没有 done）
- (2026-07-24) **隐式身份解析的真实机制与失效条件**（受控实验实证，修正本条早先「每次 Bash 调用都不可信」的错误结论）：省略 `--from`/`--terminal` 时 CLI 按 `$ORCA_TERMINAL_HANDLE` 环境变量解析身份——该值会话启动时烙死、同会话所有 Bash 子进程恒定（解析是**确定性**的，不随调用漂移），Orca 重启后 pane 换发新 handle 而 env 不更新，即过期。runtime 对死 handle 的收发**静默成功**（check 返回空、send 照收，零报错），过期后自动解析 = 稳定守着死信箱瞎等。最危险的是**混用**：dispatch 按 terminal list 显式解析活 handle、check 靠 env 自动解析死 handle，收发指向两个信箱——worker 回包完好排队、任务正常自动完结，总控却永远收不到。pull 模型信件永久排队：身份钉对后迟到的 check 也能全量补收，「监听没在场所以错过」不成立、唯一致死因就是身份不对。防治即「派发」第 1 步身份钉桩；`inbox`（跨收件人非消费）兜底审计；task-list+git 工件为完成判据的持久真相。另：check 消费型语义，同一时刻只留一个监听，起新先杀旧。
- (2026-08-07) **`reply --id` 对 `decision_gate` 类型消息回注可能不达**：codex worker 的 decision_gate 等待中，总控 `reply --id <gate_msg>` 返回 ok 但 worker 两轮超时未收到（最终 escalation）。可靠回注通道 = `send --to dispatch:<dispatch_id>`（worker 下次 check 必收）+ 并行 `reply`  escalation 线程留痕。低层 `dispatch --inject` 创建的 ctx_* dispatch 不被 `worker-show`/`worker-release` 识别（dispatch_not_found），清理用 `terminal close`。
- (2026-08-08) **worker-start 的 receipt 不可信为注入凭证**：worker-start 返回 `stage: input_accepted` 但注入文本撞上 codex 启动期 MCP 引导刷屏（尤其 MCP 启动失败重试时）仍会被吞，输入框实际为空。dispatch/worker-start 后必须 `terminal read` 亲验任务文本在框内或已进入 transcript；被吞救法 = `terminal send --text "<spec 原文 + worker_done 上报命令（task-id/dispatch-id）>" --enter` 补投，补投后再次 read 验证

---
substrate: <kebab-name>
适用: <一句话：什么调用形态下选它>
updated: <YYYY-MM-DD>
---

## 探测

<确认本基底当前可用的命令或条件；不可用即跳过本基底，换下一候选。
若本基底包装的是既有 skill（有独立 SKILL.md），探测第一步必须是**加载该 skill 本体**——基底文件只写 eo-loop 场景增补与陷阱，不复制命令契约，冲突时以 skill 本体为准>

## 派发

<把一个 eo 节点交给它执行的具体方式：调用入口、模型/effort 如何指定、prompt 必备要素（遵守 SKILL.md 的「写目标不写步骤」纪律；命中条件式 Execution Guard 时附总控从既有 SoT 即时编译的控制包，不另行落盘；明确本基底怎样传递 Unknown 求裁决信号——仅 A 类可随交付记录，B / C 类必须在变更前停下并求裁决）>

## 等待与观测

<如何窗口化等待（单窗 ≤10 分钟）；总控如何**主动**观测进度与探活（读什么产物 / 终端 / 台账）——不得要求 worker 中途回报；窗口到期无完成信号时的动作>

## 回收

<结果如何取回；正常路径从哪里读取推进所需的路由事实（frontmatter / 工件指针 / 基线 / 结构化处置），并明确不抽查、不复做节点内容。列出本基底能观察到的客观风险信号及针对性升级方式；命中 Unknown B / C、证据有界探测失败或路由事实缺失 / 冲突时只处理对应异常，不让总控兼任实施、测试或审查>

## 已知陷阱

<(YYYY-MM-DD) 已验证的坑，一条一行。本节只放出厂陷阱；运行时新学到的坑记进 `~/.eo-skills/loop/preferences/` 的「已知陷阱」节（条目前缀 `[<基底名>]`），读本节时一并读>