convez.ai
AgenteAutomaçãoAvançado
Lionad-Morotar

CC Break Dead Loop

Lionad-Morotar/cc-break-dead-loop

Detecta e quebra loops infinitos de agentes em Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent para Claude Code que detecta e interrompe automaticamente loops infinitos — tanto leituras repetidas do mesmo arquivo sem mudanças quanto falhas bash idênticas no agent principal, quanto loops de chamadas de ferramentas em sub-agents. Funciona com duplo mecanismo: hooks de pré e pós-execução para o agent principal + processo watcher persistente para sub-agents.

Instalação

$npx convez-ai Lionad-Morotar/cc-break-dead-loop

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Prevenir leituras repetidas do mesmo arquivo imutável
  • Evitar retry infinito de comandos bash que falham pela mesma razão
  • Interromper loops de ferramentas em sub-agents (teammates)

Veredito

Solução especializada e bem-arquitetada para um problema real em fluxos de agentes complexos. Implementação sofisticada com duplo mecanismo (hooks + watcher) e tratamento robusto de edge cases, mas requer Node.js 18+ e é dirigida a usuários avançados de Claude Code com sub-agents.

README

A tradução para o português deste README ainda está na fila.

cc-break-dead-loop

原本这个插件被我用于 CC + Kimi(K2.5 K2.6 K2.7),但对于此类在线模型,随着其能力变强,不再需要使用此类约束插件。

Claude Code 插件:自动检测并打断 agent 的死循环 —— 主 agent 对同一未改动文件的连续 Read 死循环与同一命令的连续相同失败 Bash 死循环(双 Hook 拦截,2 分钟窗口内判定防误杀定时任务),以及子 agent 的工具调用死循环(watcher 常驻进程扫描)。

问题背景

三类死循环:

  1. 主 agent Read 死循环:主 agent 在 Read 工具返回 "Wasted call" 或 { type: "file_unchanged" } 时不理解信号,连续重复读取同一文件。
  2. 主 agent Bash 失循环:主 agent 对同一命令连续重试且每次以相同错误秒败(如环境变量/cwd 问题导致命令从未真正执行),反复空转。
  3. 子 agent 工具调用死循环:子 agent(subagent / teammate)陷入连续重复调用同一工具(任意工具,不只是 Read)。子 agent 无视 hook 的 permissionDecision: deny(Claude Code 已知 bug #25000/#34692),无法用常规 Hook 直接阻断。

本插件用双线机制分别处理:

  • 线 1(主 agent):双 Hook(PostToolUse 检测 + PreToolUse 拦截,matcher 覆盖 Read 与 Bash)
  • 线 2(子 agent):watcher 扫描 subagent transcript → 检测死循环 → 经 Stop/PostToolUse:* Hook 引导主 agent 调用 TaskStopTool 终止子 agent

工作原理

线 1:主 agent Read / Bash 死循环(双 Hook)
─────────────────────────────────────
Claude Code (Read 返回 file_unchanged / Bash 返回 Exit code N 失败)
    │
    ▼
PostToolUse:Read|Bash ──→ 检测 wasted call / 相同错误失败 → 计数器 +1
    │   (距上次同指纹调用超过 2 分钟 → 视为新周期,计数重置)
    ▼
PreToolUse:Read|Bash ──→ 检查计数器(先验证窗口,过期计数不拦截)
    │ 达 3 次 → 注入 additionalContext 警告(不代授 allow 权限)
    │ 达 5 次 → deny 阻断 + additionalContext 引导
    ▼
正常调用 / 被阻断


线 2:子 agent 死循环(watcher + 注入)
─────────────────────────────────────
任意 Hook(SessionStart / Stop / PostToolUse:*)──→ 保活 watcher 常驻进程(detached)
    │  心跳新鲜 → 跳过;心跳超时 → (重)启。Setup Hook 仅 --init/--maintenance 特殊触发时生效
    │
    ▼
watcher(每 5s)
    ├─ 扫描 ~/.claude/projects/<proj>/<session>/subagents/agent-*.jsonl
    ├─ 提取最近 20 个 tool_use,检测尾部连续重复 ≥ 5 次
    └─ 写 alerts.json(消失的死循环清理,新增/持续的更新)
    │
    ▼
PostToolUse:* Hook ──→ 读 alerts.json → 注入 additionalContext(引导主 agent 调 TaskStopTool)
Stop Hook ──→ 读 alerts.json → 返回 blockingError(exit 2,强制主 agent 继续 turn 处理告警)

补充缓解:前台同步子代理死循环

线 2 的注入依赖主 agent 的 Stop/PostToolUse hook 触发。但前台同步子代理(run_in_background:false)死循环时,主 agent 阻塞在 Agent 工具里等返回、turn 不结束,hook 不触发——插件够不到主 agent,无法引导调用 TaskStopTool。这是 Claude Code 架构硬限制。本插件对此另补两道缓解:

  • SessionStart 注入:会话启动时给主 agent 一条强制规则,要求所有子代理必须使用 run_in_background:true(后台子代理可被线 2 正常拦截)。
  • watcher 桌面通知:检测到活跃死循环时弹系统通知(macOS osascript / Linux notify-send),提醒用户手动 Esc 中断。设 CC_BREAK_NOTIFY=0 关闭。

核心特性:

  • 双线检测:线 1 处理主 agent Read / Bash 死循环,线 2 处理子 agent 任意工具死循环
  • watcher 常驻进程:detached spawn,心跳保活,崩溃自动重启
  • 绕过 subagent deny 失效:子 agent 死循环由主 agent 经 TaskStopTool 终止,不依赖对子 agent 的 deny
  • 多重检测兼容(线 1):字符串 "Wasted call" / 对象 { type: "file_unchanged" } / JSON.stringify 兜底;Bash 以 Exit code N 首行判失败,响应哈希规范化数字抗时间戳噪声,ESC 中断不计
  • 2 分钟窗口防误杀(线 1):同指纹调用间隔超 2 分钟视为新周期重置计数,低频定时任务(如每 10 分钟一次的相同报警命令)不会被拦截
  • 参数指纹检测(线 2):稳定序列化(对象键排序)生成指纹,键序不同的等价参数视为相同
  • 状态按 project+session+agent 隔离(线 1),告警按 sessionId 过滤隔离(线 2)
  • 多重错误边界:handler try/catch + node-runner graceful fallback + watcher 崩溃自愈,插件 bug 永不阻断正常 Read / 永不阻断 Claude Code 启动

示例

实际项目很少碰到线 1 死循环,以下是线 2 的示例:

  1. 主代理执行工具时发现子代理死循环

  2. 子代理被 StopTask 停止

环境要求

  • Node.js >= 18(ES Module + watcher detached 进程模型需要)
  • Git(可选,用于解析项目名)

安装

# 1. 添加 marketplace(首次使用)
/plugin marketplace add Lionad-Morotar/claude-plugins

# 2. 安装插件
/plugin install cc-break-dead-loop@lionad-morotar

如果你之前按 Lionad-Morotar/cc-break-dead-loop 添加过 marketplace,请先执行 /plugin marketplace remove lionad-morotar,避免与本集市的其他插件(如 cc-flow)冲突。

本插件不会自动修改你的 ~/.claude/CLAUDE.md。Claude Code 的插件机制目前不支持安装时执行脚本或生命周期钩子,因此无法在安装阶段向你的全局 CLAUDE.md 追加规则。如果你希望“子代理必须后台运行”这类规则在所有会话中全局生效,请手动将它复制到 ~/.claude/CLAUDE.md。本插件会通过 SessionStart hook 在每会话启动时注入相同规则,作为无需手动配置的替代方案。

验证安装

重启 Claude Code(新开会话即触发 SessionStart hook,watcher 自动拉起),随后确认常驻进程存活:

cat ~/.data/cc-break-dead-loop/watcher-heartbeat.json   # ts 应在最近 30 秒内(毫秒时间戳)
ps -p $(cat ~/.data/cc-break-dead-loop/watcher.pid)      # 应显示 watcher.mjs 进程

watcher 若中途死亡(睡眠 / OOM / 手动 kill),会在下一次 SessionStart、Stop 或任意工具调用 hook 时自愈重启,无需手动干预。

更新

/plugin update cc-break-dead-loop@lionad-morotar

卸载

/plugin uninstall cc-break-dead-loop@lionad-morotar

开发测试

# 运行全部测试(136 tests,12 files)
npm test                         # = vitest run

# watch 模式(TDD)
npm run test:watch

# 运行单个测试文件
npx vitest run tests/state.test.mjs
npx vitest run tests/watcher.test.mjs
npx vitest run tests/integration.test.mjs

# 按测试名过滤
npx vitest -t "sanitizeName"

# 手动模拟 Hook 输入
echo '{"tool_name":"Read","tool_input":{"file_path":"/a/b"},"tool_response":"Wasted call","session_id":"s","agent_id":"a","cwd":"/tmp"}' | node src/index.mjs post-tool-use

使用 CLAUDE_PLUGIN_ROOT 环境变量

开发时可直接使用项目路径,无需复制:

export CLAUDE_PLUGIN_ROOT=/path/to/cc-break-dead-loop

配置

当前阈值固定为(见 src/config.mjs):

线 1(主 agent Read / Bash):

  • 3 次重复:注入警告(additionalContext,不代授 allow 权限)
  • 5 次重复:deny 阻断 + additionalContext 引导
  • 2 分钟窗口:同指纹调用间隔超 2 分钟视为新周期,计数重置(拦截检查同步验证窗口,deny 不会 sticky)

线 2(子 agent watcher):

  • 滑动窗口:最近 20 个 tool_use
  • 触发阈值:尾部连续重复 5 次
  • 扫描间隔:5000ms
  • 心跳超时(视为死亡需重启):30000ms
  • 桌面通知:检测到活跃死循环时弹系统通知提醒手动中断(设环境变量 CC_BREAK_NOTIFY=0 关闭)

SessionStart 注入(补充缓解):

  • 会话启动时注入子代理使用规则,要求主 agent 必须使用 run_in_background:true

未来版本将支持用户自定义阈值(见 TODOS.md)。

状态数据

状态/告警/进程数据存储在(可由 CC_BREAK_DATA_DIR 覆盖):

~/.data/cc-break-dead-loop/
  ├─ <safe-project-name>/<session-id>/<safe-agent-name>/
  │   └─ state.json              # 线 1:主 agent 调用指纹计数(Read/Bash)
  ├─ alerts.json                 # 线 2:子 agent 死循环告警(watcher 写 / hooks 读)
  ├─ watcher-heartbeat.json      # watcher 心跳({ pid, ts })
  └─ watcher.pid                 # watcher PID(重启时 kill 旧进程)

watcher 扫描的 subagent transcript 位于 ~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl(Claude Code 生成,只读输入)。

可安全删除 ~/.data/cc-break-dead-loop/,插件会在下次使用时自动重建。

架构

cc-break-dead-loop/
├── .claude-plugin/
│   └── plugin.json        # 插件元数据(Claude Code 只从仓库根读取,见「已知限制」)
├── hooks/
│   └── hooks.json         # Hook 注册(Setup + SessionStart + PostToolUse[Read|Bash+*] + PreToolUse[Read|Bash] + Stop)
├── scripts/
│   ├── node-runner.mjs    # Hook 运行时(stdin 收集、Stop exit 2、graceful fallback)
│   ├── setup-check.mjs    # 环境检测 + 启动/保活 watcher
│   └── watcher.mjs        # watcher 常驻进程入口(detached spawn)
├── src/                   # 核心源码(13 模块)
│   ├── index.mjs               # Hook 入口(5 事件分发、Stop 阻断)
│   ├── config.mjs              # 阈值 + 数据目录 + watcher 参数常量
│   ├── handlers.mjs            # 线 1:PostToolUse 检测(Read wasted / Bash 失败)+ PreToolUse 拦截
│   ├── state.mjs               # 线 1:调用指纹计数状态(原子写入,2 分钟窗口)
│   ├── utils.mjs               # 路径安全化 + Git 仓库名解析
│   ├── watcher.mjs             # 线 2:扫描协调(transcript → 检测 → 告警同步)
│   ├── watcherLifecycle.mjs    # 线 2:watcher 进程决策与 spawn
│   ├── alertStore.mjs          # 线 2:告警存储(watcher 写 / hooks 读)
│   ├── deadLoopDetector.mjs    # 线 2:死循环检测算法(稳定序列化指纹)
│   ├── hookInjector.mjs        # 线 2:Hook 注入措辞生成
│   ├── notifier.mjs            # 桌面通知(活跃死循环提醒用户手动中断)
│   ├── sessionStartAdvice.mjs  # SessionStart 注入(引导后台子代理)
│   └── subagentTranscriptReader.mjs # 线 2:subagent jsonl 解析
├── packages/claude-plugins/  # 中心集市仓库(submodule,唯一安装入口)
├── docs/                 # 项目文档
├── tests/                # 测试套件(12 文件,136 用例,Vitest)
├── vitest.config.mjs     # Vitest 配置
├── pnpm-lock.yaml
└── package.json

技术决策

  • 无构建步骤:纯 JavaScript(ES Module),Node.js 直接运行
  • 零运行时依赖:仅 Node.js 内置模块;开发依赖仅 vitest
  • 原子写入:writeFile(tmp) → rename(tmp, dest) 避免并发损坏(state.json、alerts.json 均如此)
  • 多重检测兼容(线 1):字符串 / file_unchanged 对象 / JSON.stringify 兜底
  • 参数精确比较(线 1):=== 直接比较,不规范化 undefined→0
  • 稳定序列化指纹(线 2):对象键排序后 stringify,键序不同的等价参数视为相同
  • watcher detached 常驻进程(线 2):subagent transcript 是事后落盘的 jsonl,Hook 无法实时拿到,常驻进程定时全量扫描
  • 绕过 subagent deny 失效(线 2):子 agent 死循环不直接 deny,改为在主 agent 的 Stop hook 返回 blockingError,引导主 agent 调 TaskStopTool 终止子 agent
  • 告警全量重算 + 增量同步(线 2):每次扫描全量重算死循环集合,对比上次集合,消失的 removeAlert、持续/新增的 addAlert,解决子 agent 被 kill 后告警残留

已知限制

  • 前台同步子代理死循环是架构死结:run_in_background:false 的子代理死循环时主 agent 阻塞、Stop/PostToolUse hook 不触发,线 2 够不到主 agent,无法自动拦截。仅靠 SessionStart 引导 + watcher 桌面通知缓解,最终需用户手动 Esc。
  • 线 2 依赖主 agent 遵循引导:watcher 检测到子 agent 死循环后,通过 Stop hook blockingError + PostToolUse additionalContext 引导主 agent 调用 TaskStopTool。若主 agent 忽略 blockingError,仍可能漏阻断。
  • watcher 检测有延迟:扫描间隔 5s + transcript 落盘延迟,子 agent 死循环最快在数秒后被发现。
  • 每个 subagent 独立计数:线 1 计数器按 agent 隔离,无法跨 agent 累计。
  • 主 agent 场景下 deny 完全有效:线 1 的 deny + additionalContext 双重机制确保主 agent 被可靠阻断。
  • 插件根必须等于仓库根:Claude Code 只在仓库根查找 .claude-plugin/plugin.json 与 hooks/hooks.json,埋进子目录会让插件以「已启用但零 hook 生效」的静默方式失效——watcher 照常运行、告警照常写入,但没有任何 hook 去消费它。自查方式:claude plugin details cc-break-dead-loop@lionad-morotar,出现 Version: unknown + Hooks (0) 即为此故障。
Ver o original no GitHub

Bom para

Relacionados