| name | codex-external-handoff |
| description | 从 WorkBuddy、Claude Code 或其他本地 Agent 无头调用 Codex App Server，创建可见、命名、持久的 Codex Thread，并执行继续追问、状态查询、结果取回、取消和打开。用于复杂研究、跨项目取材、章节审校、确定性工程或重要决策；一次性格式检查和无需保留上下文的小提取继续用 codex exec --ephemeral，Codex 内部组队不走本 Skill。 |
Codex External Handoff
目标
让外部 Agent 把正式任务交给本地 Codex，同时保留后台执行的顺畅和可见 Thread 的监督、恢复与人工接管能力。
运行入口
从已安装 Skill 目录调用脚本：
HANDOFF="skills/codex-external-handoff/scripts/codex_external_handoff.py"
python3 "$HANDOFF" doctor
首次使用、Codex 升级或调用失败时先运行 doctor。正式任务先读取 task-package.md；排查协议或兼容问题时读取 app-server-contract.md。
路由
- 需要跨项目检索、复杂研究、架构设计、代码审校、确定性工程、重要判断、继续追问或人工接管：使用本 Skill 创建持久 Thread。
- 输出用完即丢、无需监督、无需追问的格式检查或简单提取：直接使用
codex exec --ephemeral。
- Codex 已经是当前宿主且任务只涉及内部多 Agent 分工：使用 Codex 原生团队能力，不经外部交接。
执行
- 形成最小任务包，明确目标、允许读取的范围、禁止事项、证据要求和验收标准。正文较长时写入临时或项目登记的任务文件。
- 默认以
read-only + approvalPolicy=never 创建 Thread。只有任务包明确授权写入并列出目标路径时，才传 --sandbox workspace-write；本 Skill 不提供 danger-full-access。
- 创建并立即返回
job_id、thread_id 和打开地址：
python3 "$HANDOFF" ask \
--title "架构设计与方案审查" \
--task-file /absolute/path/to/task.md \
--cwd "$PWD" \
--model gpt-5.6-sol \
--effort high
- 后台任务用以下命令管理：
python3 "$HANDOFF" status <JOB_ID_OR_THREAD_ID>
python3 "$HANDOFF" result <JOB_ID_OR_THREAD_ID>
python3 "$HANDOFF" continue <JOB_ID_OR_THREAD_ID> --task-file /path/to/follow-up.md
python3 "$HANDOFF" cancel <JOB_ID_OR_THREAD_ID>
python3 "$HANDOFF" open <JOB_ID_OR_THREAD_ID>
ask 默认后台运行；本轮必须等结果时增加 --wait。复杂规划、全库只读取材和重要审校可用 max，普通执行和草稿检查用 high。
- 读取
result 的结构化结论、证据、风险、产物和建议状态增量。外部 Agent 负责核验和决定是否采纳；Codex Thread 不直接修改项目权威状态或绕过人工确认。
交接合同
job_id 是本地后台运行回执，thread_id 是可继续、可恢复、可在 Codex App 打开的权威会话标识。- 任务正文只在启动前暂存，Worker 读取后删除；运行回执保存在本机 Codex 状态目录，不进入项目 Git。
- 默认线程工作目录是当前项目根。跨项目检索仍保持项目根
cwd，在任务包中声明只读来源范围。
- 同一 Thread 同一时刻只运行一个外部任务；需要并行判断时创建多个新 Thread，不并发续问同一 Thread。
- 外部 Agent 或最终集成者是 canonical 文件和状态的唯一写入者。Codex 只返回证据、产物和建议增量，除非任务包明确授权写入并满足项目安全边界。
完成标准
交接只有在以下信息齐全时完成：job_id、thread_id、Thread 标题、运行状态、结构化结果或明确错误、证据、风险、产物路径、建议状态增量，以及可用的 codex://threads/<threadId> 或 codex resume <threadId>。
路由用例位于 evals/；运行实现由 scripts/codex_external_handoff.py 和 tests/ 验证。
