Initial commit: pi-loop-guard extension

README.md

@@ -0,0 +1,54 @@
+# pi-loop-guard
+
+Prevents infinite tool call loops in pi by counting tool calls and turns, then aborting the agent when a configurable threshold is exceeded.
+
+## Why?
+
+When the LLM encounters repeated errors (database connection failures, missing API keys, etc.), it can get stuck in an infinite loop of tool calls that all return the same error. This extension detects and stops that pattern.
+
+## Installation
+
+### Via pi package (recommended)
+
+```bash
+pi install git:unraid.local:3003/pi-dev/pi-loop-guard
+```
+
+### Manual
+
+Place in `~/.pi/agent/extensions/` or `.pi/extensions/`:
+
+```bash
+cp -r pi-loop-guard ~/.pi/agent/extensions/pi-loop-guard
+```
+
+## Configuration
+
+Add to `.pi/settings.json` or `~/.pi/agent/settings.json`:
+
+```json
+{
+  "loopGuard": {
+    "maxToolCalls": 50,
+    "maxTurns": 20
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `maxToolCalls` | 50 | Maximum total tool calls before abort |
+| `maxTurns` | 20 | Maximum turns (LLM responses) before abort |
+
+## Behavior
+
+- Counts tool calls across all turns in a session
+- Counts total turns (LLM responses)
+- When either threshold is exceeded, calls `ctx.abort()` to stop the agent
+- Displays an error notification with details
+
+## Example
+
+```
+Loop guard: stopped after 51 tool calls (threshold: 50). Possible infinite loop detected.
+```