codex-delegate

Codex Delegate

目标

把一个可以独立完成的长任务交给后台 subagent；subagent 内部用 shell 启动 codex exec，再用 write_stdin 长等待直至完成，最后由后台 subagent 把结果带回主会话。

流程

┌─ 主会话
│  ├─ shell(command -v codex && codex --version)
│  └─ spawn(run_in_background=true, profile="scripting" 或 "general")
│     └─ 后台 subagent
│        ├─ write_file(<task_dir>/prompt.txt)
│        ├─ shell(yield_time_ms=30000)
│        │  └─ codex exec --cd <repo> --output-last-message <task_dir>/codex-result.md - < <task_dir>/prompt.txt
│        │     └─ 若返回 execution_id，write_stdin(yield_time_ms=300000) 续接到完成
│        ├─ read_file(<task_dir>/codex-result.md)
│        └─ read_file(<task_dir>/codex-session.txt)
└─ subagent 完成后回灌结果

使用规则

1. 主 agent 必须先检查 codex 是否存在：调用 shell(command="command -v codex && codex --version")。如果失败，直接告诉用户本机没有可用 Codex CLI，不要 spawn。不要把这个检查下放给 subagent。
2. 如果用户已经给出 repo 路径，主 agent 不要为了理解任务先 list_dir、read_file、shell find/grep 探索该仓库；只把 repo 路径和任务目标原样传给 spawn。代码库探索由 Codex delegate 完成。
3. 只有用户没给 repo 路径、路径明显缺失、或用户要求主 agent 先确认路径时，主 agent 才做最小路径检查。
4. 主 agent 不要在 spawn task 里写“重点读取这些文件”“我已经发现这些入口”“候选路径如下”这类预探索结果；除非用户原文明确指定文件。spawn task 只能包含用户给出的 repo 路径、用户目标、输出要求和本技能的执行约束。
5. Codex prompt 必须要求 Codex 自己从整个 repo 发现入口、目录和相关文件，而不是沿着主 agent 预先挑出的文件列表工作。
6. 检查通过后，外层必须用 spawn(run_in_background=true)，不要在主会话里直接跑长时间 codex exec。
7. subagent 的 profile 选 scripting；如果任务还需要联网调研，选 general。
8. subagent 内部启动 codex exec 时把 yield_time_ms 设为 30000；若返回 execution_id，用空 chars 的 write_stdin 续接，并把 yield_time_ms 设为 300000，直到结果不再返回 execution_id。
9. timeout 是 execution 进程组的硬截止，默认 14400 秒；它不控制单次等待。只有需要更短硬截止时才显式传入。
10. codex exec 要用 --cd <repo> 指定工作目录，避免依赖 shell 的 cd 状态。
11. 默认把任务说明写入 prompt 文件，再用 codex exec --cd <repo> - < prompt.txt 读取，避免 shell 引号、换行和特殊字符破坏 prompt。
12. 必须给 codex exec 加 --output-last-message <task_dir>/codex-result.md，完成后读这个文件作为主要结果；不要从 /tmp/akashic-shell-*.log 里 grep 或 tail 输出。
13. 同时把 stdout+stderr 保存到 <task_dir>/codex-run.log，因为 session id: ... 在 stderr 里。
14. 如果需要后续复用同一个 Codex 会话，必须从 codex-run.log 提取 session id，写入 <task_dir>/codex-session.txt，并在回复里告诉主会话这个 session id。
15. prompt、result、run log、session id 都必须放在 subagent 任务目录 <task_dir>；不要写 /tmp，也不要依赖 /tmp/akashic-shell-*.log。