pi-loop-guard

A pi extension that detects runaway agent loops and stops them before they burn tokens.

It watches the behaviour a model actually exposes — tool calls, tool errors, and final assistant responses — and breaks the loop when a repeat pattern appears. Long but productive runs are never interrupted.

• 한국어 문서

Install

pi install npm:@wkqco33/pi-loop-guard

Try it without installing:

pi -e npm:@wkqco33/pi-loop-guard

Reload a running pi session with /reload, or restart pi.

What it detects

Signal	Pattern	Default	Action
Repeated tool call	A A A	3 in a row	block + abort
Repeating tool cycle	A B A B A B, A B C A B C …	3 full cycles (cycle length ≤ 3)	block + abort
Window tool frequency	A … A … A … A (interleaved)	4 in 10-call window	block + abort
Repeated tool error	same error 3× in a row	3 in a row	abort
Repeated assistant response	identical text 3× in a row	3 in a row	abort
Turn count	> 12 turns in a run	12	warn only
Elapsed time	> 180 s in a run	180 s	warn only

Tool calls are compared by tool name and a deterministic serialization of the arguments, so read(a.ts) and read(b.ts) are different calls.

Error keys are normalized (digits collapsed, UUIDs, timestamps, and hex pointers masked), so dynamic tokens share a key.

Turn count and elapsed time are deliberately soft: a long run that keeps making progress is allowed to finish. Only genuine repeat patterns hard-stop.

Modes

Mode	Behaviour
on (default)	Report and hard-stop loops
observe	Report loops but never block or abort — use this first on a new machine
off	Disabled entirely, including the system-prompt hint

Start with observe for a few days, then switch to on once you trust the signal on your workloads.

Commands

/loop-guard           show current status
/loop-guard status    same as above
/loop-guard inspect   show recent tool call history
/loop-guard on        enable blocking
/loop-guard off       disable
/loop-guard observe   report only, never block
/loop-guard reset     reset the current run's counters and tripped flag

Configuration

Config file

Create .pi/loop-guard.json in your project (or ~/.pi/loop-guard.json globally). Project settings override global settings.

{
 "mode": "on",
 "locale": "en",
 "maxTurns": 12,
 "turnTimeoutMs": 180000,
 "repeatToolThreshold": 3,
 "repeatErrorThreshold": 3,
 "repeatAssistantThreshold": 3,
 "cycleRepeats": 3,
 "maxCycleLength": 3,
 "repeatFrequencyThreshold": 4,
 "frequencyWindowSize": 10,
 "ignoreTools": ["sleep"],
 "toolThresholdOverrides": { "bash": 2 }
}

"enabled": false is accepted as an alias for "mode": "off".

Environment variables

Environment variables override the config file.

export PI_LOOP_GUARD_MODE=on            # on | off | observe
export PI_LOOP_GUARD_LOCALE=en          # en | ko
export PI_LOOP_GUARD_MAX_TURNS=12
export PI_LOOP_GUARD_TURN_TIMEOUT_MS=180000
export PI_LOOP_GUARD_REPEAT_TOOL=3
export PI_LOOP_GUARD_REPEAT_ERROR=3
export PI_LOOP_GUARD_REPEAT_ASSISTANT=3
export PI_LOOP_GUARD_CYCLE_REPEATS=3
export PI_LOOP_GUARD_MAX_CYCLE_LENGTH=3
export PI_LOOP_GUARD_REPEAT_FREQUENCY=4
export PI_LOOP_GUARD_FREQUENCY_WINDOW=10
export PI_LOOP_GUARD_IGNORE_TOOLS=sleep,wait
export PI_LOOP_GUARD_TOOL_OVERRIDES="bash=2,read=5"

A stricter setup:

export PI_LOOP_GUARD_REPEAT_TOOL=2
export PI_LOOP_GUARD_REPEAT_ERROR=2
export PI_LOOP_GUARD_REPEAT_ASSISTANT=2

Precedence

built-in defaults  <  config file  <  environment variables  <  /loop-guard command

How it works

1. before_agent_start appends a short "don't loop, report blockers" hint to the system prompt.
2. tool_call records a digested toolName + stableJson(input) signature and checks for consecutive repeats and repeating cycles.
3. tool_execution_end tracks consecutive identical failures; any success clears the streak.
4. message_end compares finalized assistant text.
5. turn_start and a periodic timer emit soft warnings only.
6. On a hard stop the run is aborted and the tool call is blocked with { block: true, terminate: true }.
7. agent_settled and session_shutdown clear timers and counters.

The detector itself (src/detector.ts) is pure and has no pi dependency, which is why it is exhaustively unit-tested.

Safety

• Runs with the same privileges as the pi process.
• Never writes session content or API keys to disk or to logs.
• Only counts and hashes in memory; nothing is persisted.
• Hard-stops can interrupt a legitimate retry, so observe is the recommended starting mode.
• Turn/time limits never stop a run on their own.

Development

npm install
npm run verify        # typecheck + format:check + tests
npm run coverage      # 100% line coverage on src/
npm run bench         # hot-path micro-benchmarks
npm run pack:check

Tests use the Node.js built-in test runner with native TypeScript type-stripping — no test framework dependency. Contributors and agents must follow AGENTS.md.

License

MIT © wkqco33