🔁 Break Dead Loop

简介

Break Dead Loop 是一个 Claude Code 插件，自动检测并打断两类 agent 死循环：主 agent 对同一未改动文件的连续 Read，以及子 agent 连续重复调用同一工具。

原本是给 CC + Kimi（K2.5 ~ K2.7）准备的。现在模型能力上来了，这类约束插件基本用不到，留档自用。

为什么要两条线

两类死循环的拦截难度不一样：

• 主 agent Read 死循环：Read 返回 file_unchanged 时模型不理解信号，继续重读。Hook 能直接拦，好处理
• 子 agent 工具死循环：子 agent 会无视 Hook 的 permissionDecision: deny（Claude Code 已知 bug #25000/#34692），常规 Hook 拦不住

所以插件分两条线。线 1 用双 Hook：PostToolUse 检测 wasted call 并计数，PreToolUse 检查计数器，到 3 次注入警告，到 5 次直接 deny。 线 2 起一个 watcher 常驻进程，每 5 秒扫一遍子 agent 的 transcript，发现尾部连续重复调用同一工具 ≥ 5 次就写 alerts.json， 再经 Stop / PostToolUse Hook 引导主 agent 调 TaskStop 终止它。绕过对子 agent 的 deny，从根上避开那个 bug。

参数指纹用的是稳定序列化（对象键排序），键序不同的等价参数视为同一次调用。状态按 project + session + agent 隔离，告警按 sessionId 过滤。

安装

# 添加 marketplace（首次）
/plugin marketplace add Lionad-Morotar/claude-plugins

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

已知限制

前台同步子代理（run_in_background: false）死循环时，主 agent 阻塞在 Agent 工具里等返回，turn 不结束，Hook 不触发，插件够不到主 agent。这是架构硬限制，只能缓解：

• SessionStart 注入规则，要求子代理一律后台运行，让线 2 能正常拦截
• watcher 检测到活跃死循环时弹桌面通知，提醒手动 Esc 中断（设 CC_BREAK_NOTIFY=0 关闭）

插件自身加了多重错误边界：handler try/catch、watcher 崩溃自愈。插件出 bug 不会阻断正常 Read，也不会影响 Claude Code 启动。

https://github.com/Lionad-Morotar/cc-break-dead-loop