CC Break Dead Loop
Lionad-Morotar/cc-break-dead-loop
Detecta e quebra loops infinitos de agentes em Claude Code
Ver no GitHubAgent 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-loop1 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
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 常驻进程扫描)。
问题背景
三类死循环:
- 主 agent Read 死循环:主 agent 在 Read 工具返回
"Wasted call"或{ type: "file_unchanged" }时不理解信号,连续重复读取同一文件。 - 主 agent Bash 失循环:主 agent 对同一命令连续重试且每次以相同错误秒败(如环境变量/cwd 问题导致命令从未真正执行),反复空转。
- 子 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 的示例:
主代理执行工具时发现子代理死循环
子代理被 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)即为此故障。

