Agent Bridge

Codex 是 Supervisor。Worker 是外部完整 Coding Agent。Bridge 不调用 LLM。

MCP server 名：agent-bridge
工具前缀：bridge_*

安装：npx -y codex-agent-bridge，然后新开 Codex。

什么时候用

用户要改一个 git 仓库，且应该由 Claude Code 或 DeepSeek Harness 执行。

什么时候不用

• 只问问题、读代码、做设计
• 没有 git 仓库
• OpenCode（当前 DEFERRED）
• Codex 自己改当前工作区即可

闭环

bridge_run
→ 若 state=WAITING_FOR_INPUT：读 pendingInput.options，bridge_respond（optionId + stateVersion）
→ 若 state=TASK_TIMED_OUT：wait 预算到了，Worker 已停，worktree 保留。读 ReviewPacket，然后 continue 或 reject
→ 重复直到 AWAITING_REVIEW
→ 读 structuredContent.reviewPacket（含 verification）
→ verification.passed=false 时不要 approve，除非用户明确要求
→ 不通过：bridge_continue（notes + stateVersion）
→ 再读 ReviewPacket（continue 过程中也可能再 WAITING_FOR_INPUT）
→ 通过：bridge_approve（stateVersion）
→ 用户要落到当前分支时：bridge_apply（cherry-pick，不是 merge）

worker：调试用 replay；闸门自检可用 fake；真干活用 claude 或 deepseek。V1 只选 worker。不要传、不要编造 model / provider / effort。Agent Bridge不管理DeepSeek model/provider/reasoning effort。DeepSeek effective route由运行中的Harness ACP composition决定。当前legacy integration使用上游composition配置。Claude Code 沿用其原生配置。Claude 背后的官方 Anthropic、CC Switch 或其他第三方 Provider 是 Worker 内部实现，不要猜测 effective upstream model。

项目里如果有 .agent-bridge/verify.json，bridge_run 会默认跑其中全部 verifyId。也可显式传 verifyIds。示例：templates/verify.json。

破坏性调用必须带当前 task.stateVersion。冲突时不要重试旧版本。

每次 bridge_* 任务调用都必须带同一个 project 路径。任务 UUID 的字段名是 task，不是 taskId。bridge_respond 示例：project + task + stateVersion + optionId。漏掉 project 会查到空任务库或报 journal 不存在，看起来像状态丢失。

clientRequestId 相同且内容相同会返回同一 task；内容不同会 TASK_ALREADY_EXISTS。

MCP 默认 permissionMode=gate：Worker 要写文件/跑命令时会停在 WAITING_FOR_INPUT，不要自动当任务完成。选 allow_once，除非用户明确禁止。optionId 以 pendingInput.options 为准（Claude 可能是 allow 而不是 allow-once）。没有 live waiter 时（Core 重启）不要 respond，改 bridge_continue。

timeoutMs 到期会停 Worker、保留 worktree，状态变成 TASK_TIMED_OUT。这不是完成。可以 bridge_continue 或 bridge_reject。

CLI 默认 auto（一次进程无法跨调用停闸）。

掉线后先 bridge_status（needsAttention: true）或 bridge_doctor。Core 重启会把 QUEUED / STARTING / RUNNING / VERIFYING / WAITING_FOR_INPUT 收成 AWAITING_REVIEW + interrupted，不要 respond，改 bridge_continue（Claude 可尝试 session/load）。doctor 标出遗留 worktree 时用 bridge_prune。

硬规则

• turn 结束 ≠ 任务完成
• Worker 不得 commit / push / merge / rebase
• 不要用 base..HEAD 当 diff；以 ReviewPacket / bridge_diff 为准
• 不要信 Worker 自称测过；验证只认 .agent-bridge/verify.json 的 verifyId
• approve 后 worktree 会拆掉，checkpoint 留在任务分支；落到当前分支用 bridge_apply（cherry-pick）
• 不要 merge
• crash / 死 pid / MCP 进程退出：不要 reattach 死 pid。hydrate 后看 interrupted。bridge_continue 会尝试 Claude session/load；失败或 DeepSeek 则 REHYDRATE
• DeepSeek 没有 session/load；Claude 可以 cold load
• bridge_logs / journal 会脱敏，不要把密钥写进 notes
• V1 不管理 Worker 的 model / provider / effort；bridge_run 只选 worker