loop-guard

Pi extension that detects and prevents LLM looping behavior in real-time across tool calls, thinking blocks, and streaming output.

Why

LLMs can get stuck in repetitive loops: calling the same tool with the same arguments, repeating identical reasoning, or producing stagnant output. This wastes tokens, time, and can cause agents to run indefinitely without making progress.

loop-guard watches for these patterns and escalates progressively:

1. Hint — Inject a system prompt nudge to steer the model off its current path
2. Block — Reject the tool call or abort streaming with a strong corrective message
3. Terminate — Stop the agent entirely after persistent looping

Detection Modes

Tool Call Loops

Detects three patterns in tool calls:

| Pattern | Description | |---------|-------------| | Exact repeat | Same tool + identical arguments called consecutively | | Fuzzy repeat | Same tool with similar arguments (Jaccard similarity) | | Cycle | Repeating sequence of different tools (e.g. read → edit → read → edit) |

Thinking Loops (Streaming)

Detects repetitive reasoning in real-time during streaming:

| Pattern | Description | |---------|-------------| | Consecutive | N consecutive similar lines (exact match or n-gram similarity) | | Density | High repetition density in a sliding window (mode-based) |

Uses a two-stage escalation within a single prompt: warn on first detection, abort on second. This avoids false positives from legitimate repetitive output (e.g. listing items).

Thinking Loops (Post-Hoc)

At message_end, analyzes complete thinking blocks for repetitive patterns using n-gram similarity across a sliding window.

Result Stagnation

Detects when the same tool returns identical results repeatedly, indicating the agent is stuck in a non-productive cycle.

Installation

Drop this directory into your Pi extensions folder:

~/.pi/agent/extensions/loop-guard/

Pi loads it automatically on startup. You'll see loop-guard: active in the notification log.

Usage

Commands

| Command | Description | |---------|-------------| | /loop-guard reset | Clear all detection counters and allow the agent to continue | | /loop-guard config | Open interactive config menu to adjust thresholds | | /loop-guard | Same as config (opens menu) |

Configuration

Run /loop-guard config to pick a setting and edit it. Key fields:

Tool Call Detection

| Field | Default | Description | |-------|---------|-------------| | toolCallWindow | 5 | Recent tool calls to scan | | exactRepeatThreshold | 2 | Consecutive identical calls before flagging | | fuzzySimilarityThreshold | 0.85 | Jaccard similarity threshold (0.0–1.0) | | cycleLength | 2 | Tools in a repeating cycle pattern | | cycleRepetitions | 2 | Times a cycle must repeat | | cycleSimilarityThreshold | 0.7 | Argument similarity for cycle confirmation |

Thinking Loop Detection

| Field | Default | Description | |-------|---------|-------------| | thinkingWindow | 3 | Recent thinking blocks to compare (post-hoc) | | thinkingSimilarityThreshold | 0.8 | N-gram similarity threshold (post-hoc) | | thinkingMinLength | 100 | Min chars to analyze (shorter blocks skipped) |

Streaming Detection

| Field | Default | Description | |-------|---------|-------------| | consecutiveThreshold | 4 | Consecutive similar lines to trigger | | densityThreshold | 0.75 | Repetition density to trigger | | densityWindow | 100 | Sliding window size for density | | lineSimilarityThreshold | 0.85 | N-gram threshold for near-identical lines | | maxBufferSize | 10240 | Chunk buffer cap in bytes | | escalationTurns | 2 | Loop detections per prompt before abort |

Result Stagnation

| Field | Default | Description | |-------|---------|-------------| | resultStagnationThreshold | 3 | Consecutive identical results before flagging |

Escalation

| Field | Default | Description | |-------|---------|-------------| | hintAfter | 1 | Detections before system prompt hint | | blockAfter | 2 | Detections before blocking | | blockBeforeTerminate | 3 | Blocked calls before termination | | maxTurns | null | Hard turn limit (null = unlimited) |

Architecture

index.ts              Extension entry point, wires Pi events to trackers
├── tool-tracker.ts   Detects exact, fuzzy, and cycle patterns in tool calls
├── thinking-tracker.ts  Streaming + post-hoc thinking loop detection
├── result-tracker.ts   Detects identical results from the same tool
├── escalation.ts     Multi-level escalation (hint → block → terminate)
├── similarity.ts     Jaccard + n-gram similarity utilities
└── config.ts         Config schema, defaults, /loop-guard command

Event Flow

session_start  →  reset all trackers
agent_start    →  reset thinking tracker (full)
message_start  →  reset thinking tracker (per-message)
message_update →  onChunk() / onThinkingEnd() (streaming detection)
tool_call      →  toolTracker.check() → escalate if loop found
tool_result    →  resultTracker.check() → escalate if stagnant
message_end    →  thinkingTracker.check() (post-hoc detection)
turn_end       →  max turns safety net

Testing

npm test

88 tests covering all detection modes, escalation paths, similarity algorithms, and edge cases.