pi-loop-breaker

Forked from: https://github.com/apetersson/pi-loop-breaker

A lightweight Pi extension that detects repeated tool-call loops and triggers graceful shutdown.

This is especially useful when using weaker/dumber models that are more prone to getting stuck in repetitive tool loops.

Behavior

• Tracks a failure signature based on:
  • tool name
  • tool input (for bash, exact command text)
  • first line of tool error text
• Once the same failure repeats N times (REPEAT_TOOL_FAIL_THRESHOLD, default 4):
  • emits an error notification
  • calls ctx.shutdown()
  • blocks subsequent tool calls while shutdown is pending
• Tracks repeated successful tool signatures (tool name + input).
• Once the same successful command repeats M times (REPEAT_TOOL_SUCCESS_THRESHOLD, default 10):
  • emits an error notification
  • calls ctx.shutdown()
  • blocks subsequent tool calls while shutdown is pending
• Before either shutdown threshold is reached, it can emit a steer warning once per repeated-signature streak at W repetitions (REPEAT_TOOL_WARN_ONLY_THRESHOLD, default 3):
  • emits a warning notification
  • injects a steer message into the agent stream:
    • [Warning] Potential tool loop detected. Stop for a second and try something else or the next X will terminate this run.

Warn-Only Mode

Set REPEAT_TOOL_WARN_ONLY=true to enable warnings without shutdown. In this mode:

• Warnings are emitted at the REPEAT_TOOL_WARN_ONLY_THRESHOLD
• The loop breaker never engages (never calls ctx.shutdown())
• REPEAT_TOOL_FAIL_THRESHOLD and REPEAT_TOOL_SUCCESS_THRESHOLD are ignored

Example:

REPEAT_TOOL_WARN_ONLY=true REPEAT_TOOL_WARN_ONLY_THRESHOLD=2

Load

• Global auto-discovery:
  • ~/.pi/agent/extensions/loop-breaker/index.ts
• Package mode:
  • this folder is a standalone Pi package (pi.extensions points to ./extensions)

Test

pnpm test