Coding 工具 · 总览

把完成事件接入 bluebell

bluebell 提供通用完成事件协议，不提供固定“支持工具”名单。你负责选择工具当前版本的完成信号，bluebell 负责后续保存与通知。

通用边界

适配器只负责转换事件

  1. 读取工具回调
  2. →
  3. 选择完成事件
  4. →
  5. 生成稳定身份
  6. →
  7. 调用 bluebellctl

工具适配脚本不访问 CloudKit、不连接 Watch，也不决定设备如何震动。它只把当前工具的完成事件交给 bluebell。

完成语义

不要把“发生了事件”当作“工作完成”

信号能否直接当作完成
等待用户批准不能；Agent 仍可能继续。
一次工具调用结束不能；这通常只是当前轮次的一步。
子任务结束通常不能；主任务可能仍在运行。
交互式进程退出不能作为通用规则；会话可能被手动关闭或异常退出。
厂商定义的 turn complete / Stop / idle可作为候选，但必须核对当前版本以及子会话、继续执行和重试语义。

推荐顺序

先本机，后多设备

  1. 保持 bluebell Mac 运行。

    从客户端复制当前 CLI 路径。

  2. 运行 bluebellctl 的 --local 测试。

    确认最近提醒出现，先隔离 CloudKit 与设备通知问题。

  3. 记录一次真实工具回调。

    核对字段、发生次数、主会话与子会话差异，不读取或上传不必要的对话内容。

  4. 接入适配脚本，并继续使用 --local。

    执行一轮真实任务，确认只产生一条逻辑完成。

  5. 固定 dedupeKey 后移除 --local。

    开启 Mac 总推送并观察发送队列，再验证真实设备。

当前示例

按工具查看适配方法

01Claude Code使用 Stop hook，通过 stdin 读取回调 JSON。→02Codex CLI使用 notify 的 agent-turn-complete JSON 参数。→03Codex 客户端为本机任务配置 Stop Hook，读取会话与轮次身份。→04OpenCode使用 plugin event，处理 session.idle 与消息身份。→05Pi使用 extension 的 agent_settled，在自动续跑结束后提醒。→

旧版本

迁移旧 Bluebell hook 时先备份

新版不会自动修改或删除旧版曾写入的工具配置。请先备份配置文件，只移除明确属于 Bluebell 旧 helper、plugin 或 extension 的条目，保留同一事件上的其他 hooks。

迁移完成后使用客户端显示的真实 bluebellctl 路径重新接入。不要因为看到历史来源名，就认为对应工具仍是内置支持或已经安装。