ypollak2/llm-router

🔒 Stuck Pattern Prevention System

Version 5.6.0 eliminates the deadlock scenario where Claude gets trapped investigating routing enforcement. This release implements a comprehensive 6-point prevention system in the enforce-route hook.

What's Fixed

The Problem: In v5.5.1, when routing enforcement was triggered:

• Claude would attempt to investigate (read hooks, grep config)
• The enforce-route hook would block investigation tools
• No escape path existed → session deadlock

The Solution: 6-point prevention system prevents this entirely:

1. Early file-op detection — Marks session as 'coding' on first Read/Glob/Grep/LS, allowing investigation without violations
2. Violation counter — After 2 violations, auto-downgrades enforcement to soft mode (escape path)
3. Auto-pivot mechanism — Automatically switches from hard to soft enforcement to prevent infinite loops
4. Loop detection — Detects 3+ same-tool calls in 120s and warns explicitly
5. State visibility — Enforcement messages show routing window countdown
6. Mandatory escalation — Clear messaging (🔴 Violation 2+, ⏰ ROUTING WINDOW CLOSING)

Migration

pip install --upgrade claude-code-llm-router
llm-router install  # Redeploy updated enforce-route hook

Technical Details

• Hook progression: v9 (baseline) → v10 (HIGH priority fixes) → v11 (MEDIUM) → v12 (LOW)
• No breaking changes; all existing routing behavior preserved
• Backwards compatible: existing .env and config files work unchanged
• All 940+ tests passing with new prevention system
• Zero false positives: investigation instinct is explicitly allowed

What's New

Enforce-Route Hook v12 includes:

• _violation_counter_path() — Persistent violation tracking
• _detect_investigation_loop() — Pattern detection in tool history
• Early file-operation detection (line ~310)
• Auto-pivot logic (line ~330)
• Enhanced error messages with escalation warnings

See CHANGELOG.md for detailed feature list.

This release makes llm-router production-safe. Nobody will get stuck. Multiple escape mechanisms ensure smooth recovery from any routing scenario.