---
name: loom-bridge
description: |
  在当前 Claude Code 会话挂起 CodexLoom→Claude Code 实时执行桥:persistent Monitor 双流监听
  CodexLoom 消息(comms.ndjson + agent 线程 userMessage),捕获 `claude-code:` 任务简报,
  spawn subagent 执行,以 `claude-code-result:` 回帖。Use when 用户说 /loom-bridge、挂桥、
  接 codexloom 任务、监听 loom、bridge waiting、把这个会话变成执行桥。
  Exclude:CodexLoom 服务本体的配置/重启、Codex model provider 配置、把桥固化为系统服务。
metadata:
  owner: Peng Xiao
  validated: 2026-08-05(三轮闭环:协议公告→自测任务→结果回帖,误报两类已修)
---

Copyright (c) 2026 Peng Xiao

# loom-bridge — CodexLoom → Claude Code 执行桥

CodexLoom 的 Codex agent 受 sandbox 限制(实测:worktree 内 `git add` 被拒
`index.lock: Operation not permitted`),需要完整仓库权限或项目技能的执行由本桥承接。
桥 = 本会话的一个 persistent Monitor(等待期 0 token)+ 任务处理纪律。

## 前置探活

```bash
curl -s -m 3 localhost:4870/api/version | head -c 80   # CodexLoom 实例在跑
ls ~/.codex-loom/comms.ndjson ~/.codex-loom/events/     # 数据流存在
```

任一失败:报告用户,不挂桥。

## 挂桥

用 Monitor 工具(persistent: true),command 如下(过滤逻辑在脚本里,勿内联复制):

```bash
tail -n 0 -F ~/.codex-loom/comms.ndjson ~/.codex-loom/events/*.ndjson 2>/dev/null \
  | python3 ~/.claude/skills/loom-bridge/scripts/monitor_filter.py
```

description 建议:`loom-bridge:claude-code 任务监听(双流)`。
挂好后告知用户:桥已上线,等待期零消耗,事件即唤醒。

## 任务处理循环(每个 Monitor 事件)

1. 解析事件行四字段:任务详情 / 契约引用 / 工作路径 / 验收标准。
2. **缺字段**:用 `scripts/loom_send.py` 回帖点名缺口,要求补发,本轮结束。不猜。
3. **齐全**:spawn 一个一次性 subagent 执行(模型分层:实现类 Sonnet、难调试 Opus、
   机械活 Haiku,绝不 Fable)。简报必须自包含——把四字段原文 + 相关文件路径写进
   subagent prompt;subagent 与 CodexLoom 线程零共享上下文。
4. 验证后回帖:`claude-code-result:` 前缀 + commit hash / 测试结果 / 一段摘要。
   回帖正文不得出现裸 `claude-code:` 字样(防自触发)。
5. 主会话只保留事件行与结果摘要,过程细节留在 subagent。

## 消息协议(与三个 agent Profile 中的约定一致)

任务方(agent 或 Owner)发消息,正文含:

```
claude-code: <一句话任务>
- 任务详情: <做什么、边界>
- 契约引用: <commit/文档路径>
- 工作路径: <绝对路径 + 分支>
- 验收标准: <怎么算完成>
```

回帖工具:

```bash
python3 ~/.claude/skills/loom-bridge/scripts/loom_send.py --topic <topic_id> "<text>"
# topic_id 缺省读 env LOOM_TOPIC;409 自动重试(responsible agent 忙)
```

## 已知坑(均为 2026-08-05 实测)

1. **Owner 的 topic send 不进 comms.ndjson**——只落 responsible agent 线程的
   userMessage。双流监听即为此而设,不可退回单看 comms。
2. **投递的 userMessage 附带 `<loom_context>` 编译上下文**,内含历史消息,历史里的
   marker 会误触发。过滤脚本先截 `<loom_context` 再匹配,勿移除该逻辑。
3. **topic send 409 = responsible agent 正在 turn 中**,10 秒间隔重试即可,非错误。
4. **谈论协议本身也会触发**——给 agent 的指令里写出带冒号的完整 marker 即命中过滤器
   (2026-08-05 实测误触发)。指代协议时写"claude-code 前缀"(无冒号)或"桥协议"。

## 执行边界

- 不 push 远端、不动 cloud 资源、不做生产发布——这些回帖说明后转 Owner。
- 破坏性/不可逆操作:回帖要求 Owner 明示授权,不代批。
- Monitor 随会话存活;会话结束桥停,新会话重新 /loom-bridge 挂起。
- 同会话不重复挂:先 TaskStop 旧 Monitor 再挂新的。