@miller-tech/uap 1.13.11 → 1.13.13

package/templates/hooks/loop-protection.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# ============================================================
+# UAP Loop Protection & Token Budget Circuit Breaker
+# ============================================================
+# Shared library sourced by all UAP hooks.
+# Tracks hook invocation frequency and detects runaway loops
+# that waste tokens (and money) by emitting the same system
+# reminders, build-gate warnings, or compliance blocks
+# hundreds of times in a single session.
+#
+# MECHANISM:
+#   - Maintains a lightweight state file per session
+#   - Counts hook invocations per type within sliding windows
+#   - Suppresses redundant output after thresholds are hit
+#   - Logs suppressed events for post-mortem analysis
+#   - Provides hard circuit-breaker after extreme loop counts
+#
+# USAGE (source from any hook script):
+#   source "$(dirname "$0")/loop-protection.sh"
+#   if lp_should_suppress "post-tool-use-edit-write"; then
+#     exit 0  # skip output, loop detected
+#   fi
+#   lp_record_invocation "post-tool-use-edit-write"
+#
+# CONFIGURATION (environment variables):
+#   UAP_LP_DISABLED=1           Disable loop protection entirely
+#   UAP_LP_SOFT_LIMIT=15        Warn after N invocations per hook (default: 15)
+#   UAP_LP_HARD_LIMIT=50        Suppress output after N (default: 50)
+#   UAP_LP_CIRCUIT_BREAK=200    Hard stop — emit circuit breaker msg (default: 200)
+#   UAP_LP_WINDOW_SECS=300      Sliding window in seconds (default: 300 = 5 min)
+#   UAP_LP_DEDUP_SECS=5         Min seconds between identical outputs (default: 5)
+# ============================================================
+
+# Guard against re-sourcing
+if [ "${_UAP_LOOP_PROTECTION_LOADED:-}" = "1" ]; then
+  return 0 2>/dev/null || true
+fi
+_UAP_LOOP_PROTECTION_LOADED=1
+
+# --- Configuration ---
+LP_DISABLED="${UAP_LP_DISABLED:-0}"
+LP_SOFT_LIMIT="${UAP_LP_SOFT_LIMIT:-15}"
+LP_HARD_LIMIT="${UAP_LP_HARD_LIMIT:-50}"
+LP_CIRCUIT_BREAK="${UAP_LP_CIRCUIT_BREAK:-200}"
+LP_WINDOW_SECS="${UAP_LP_WINDOW_SECS:-300}"
+LP_DEDUP_SECS="${UAP_LP_DEDUP_SECS:-5}"
+
+# --- State file location ---
+LP_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${FACTORY_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-.}}}"
+LP_STATE_DIR="${LP_PROJECT_DIR}/.uap/loop-protection"
+LP_SESSION_ID="${UAP_SESSION_ID:-${SESSION_ID:-default}}"
+LP_STATE_FILE="${LP_STATE_DIR}/session-${LP_SESSION_ID}.state"
+LP_LOG_FILE="${LP_STATE_DIR}/loop-events.log"
+
+# --- Ensure state directory exists ---
+_lp_init() {
+  if [ "$LP_DISABLED" = "1" ]; then
+    return 0
+  fi
+  mkdir -p "$LP_STATE_DIR" 2>/dev/null || true
+}
+
+# --- Get current epoch seconds (portable) ---
+_lp_now() {
+  date +%s 2>/dev/null || echo "0"
+}
+
+# --- Read counter for a hook type from state file ---
+# Format: hook_type|count|first_ts|last_ts|suppressed_count
+_lp_read_state() {
+  local hook_type="$1"
+  if [ ! -f "$LP_STATE_FILE" ]; then
+    echo "0|0|0|0"
+    return
+  fi
+  local line
+  line=$(grep "^${hook_type}|" "$LP_STATE_FILE" 2>/dev/null | tail -1)
+  if [ -z "$line" ]; then
+    echo "0|0|0|0"
+    return
+  fi
+  echo "$line" | cut -d'|' -f2-5
+}
+
+# --- Write/update counter for a hook type ---
+_lp_write_state() {
+  local hook_type="$1"
+  local count="$2"
+  local first_ts="$3"
+  local last_ts="$4"
+  local suppressed="$5"
+
+  # Atomic update: remove old line, append new
+  if [ -f "$LP_STATE_FILE" ]; then
+    grep -v "^${hook_type}|" "$LP_STATE_FILE" > "${LP_STATE_FILE}.tmp" 2>/dev/null || true
+    mv "${LP_STATE_FILE}.tmp" "$LP_STATE_FILE" 2>/dev/null || true
+  fi
+  echo "${hook_type}|${count}|${first_ts}|${last_ts}|${suppressed}" >> "$LP_STATE_FILE"
+}
+
+# --- Log a loop event for post-mortem ---
+_lp_log_event() {
+  local level="$1"
+  local hook_type="$2"
+  local message="$3"
+  local now
+  now=$(_lp_now)
+  echo "${now}|${level}|${hook_type}|${message}" >> "$LP_LOG_FILE" 2>/dev/null || true
+}
+
+# ============================================================
+# PUBLIC API
+# ============================================================
+
+# Check if a hook invocation should be suppressed.
+# Returns 0 (true/suppress) if the hook has been called too many times.
+# Returns 1 (false/allow) if the hook should proceed normally.
+lp_should_suppress() {
+  local hook_type="${1:-unknown}"
+
+  if [ "$LP_DISABLED" = "1" ]; then
+    return 1  # don't suppress
+  fi
+
+  _lp_init
+
+  local state
+  state=$(_lp_read_state "$hook_type")
+  local count first_ts last_ts suppressed
+  count=$(echo "$state" | cut -d'|' -f1)
+  first_ts=$(echo "$state" | cut -d'|' -f2)
+  last_ts=$(echo "$state" | cut -d'|' -f3)
+  suppressed=$(echo "$state" | cut -d'|' -f4)
+
+  local now
+  now=$(_lp_now)
+
+  # Reset window if first_ts is too old
+  if [ "$first_ts" != "0" ] && [ $((now - first_ts)) -gt "$LP_WINDOW_SECS" ]; then
+    count=0
+    first_ts="$now"
+    suppressed=0
+  fi
+
+  # Dedup: if called within LP_DEDUP_SECS of last call, always suppress
+  if [ "$last_ts" != "0" ] && [ $((now - last_ts)) -lt "$LP_DEDUP_SECS" ]; then
+    suppressed=$((suppressed + 1))
+    _lp_write_state "$hook_type" "$count" "$first_ts" "$now" "$suppressed"
+    return 0  # suppress (dedup)
+  fi
+
+  # Check thresholds
+  if [ "$count" -ge "$LP_CIRCUIT_BREAK" ]; then
+    # Circuit breaker: emit ONE final warning then suppress everything
+    if [ "$suppressed" -eq 0 ] || [ $((count % LP_CIRCUIT_BREAK)) -eq 0 ]; then
+      _lp_log_event "CIRCUIT_BREAK" "$hook_type" "count=${count} in window"
+    fi
+    suppressed=$((suppressed + 1))
+    _lp_write_state "$hook_type" "$count" "$first_ts" "$now" "$suppressed"
+    return 0  # suppress
+  fi
+
+  if [ "$count" -ge "$LP_HARD_LIMIT" ]; then
+    # Hard limit: suppress output, log
+    if [ $((count % 10)) -eq 0 ]; then
+      _lp_log_event "HARD_LIMIT" "$hook_type" "count=${count} suppressed=${suppressed}"
+    fi
+    suppressed=$((suppressed + 1))
+    _lp_write_state "$hook_type" "$count" "$first_ts" "$now" "$suppressed"
+    return 0  # suppress
+  fi
+
+  return 1  # allow
+}
+
+# Record a hook invocation (call AFTER producing output).
+lp_record_invocation() {
+  local hook_type="${1:-unknown}"
+
+  if [ "$LP_DISABLED" = "1" ]; then
+    return 0
+  fi
+
+  _lp_init
+
+  local state
+  state=$(_lp_read_state "$hook_type")
+  local count first_ts last_ts suppressed
+  count=$(echo "$state" | cut -d'|' -f1)
+  first_ts=$(echo "$state" | cut -d'|' -f2)
+  last_ts=$(echo "$state" | cut -d'|' -f3)
+  suppressed=$(echo "$state" | cut -d'|' -f4)
+
+  local now
+  now=$(_lp_now)
+
+  # Reset window if expired
+  if [ "$first_ts" = "0" ] || [ $((now - first_ts)) -gt "$LP_WINDOW_SECS" ]; then
+    count=1
+    first_ts="$now"
+    suppressed=0
+  else
+    count=$((count + 1))
+  fi
+
+  _lp_write_state "$hook_type" "$count" "$first_ts" "$now" "$suppressed"
+
+  # Emit warnings at soft limit
+  if [ "$count" -eq "$LP_SOFT_LIMIT" ]; then
+    _lp_log_event "SOFT_LIMIT" "$hook_type" "count=${count} - approaching rate limit"
+    echo "[UAP-LOOP-PROTECTION] Hook '${hook_type}' has fired ${count} times in ${LP_WINDOW_SECS}s. Output will be suppressed after ${LP_HARD_LIMIT} to prevent token waste." >&2
+  fi
+}
+
+# Get the circuit breaker warning message (for hooks that want to emit it).
+lp_circuit_breaker_message() {
+  local hook_type="${1:-unknown}"
+  local state
+  state=$(_lp_read_state "$hook_type")
+  local count
+  count=$(echo "$state" | cut -d'|' -f1)
+  local suppressed
+  suppressed=$(echo "$state" | cut -d'|' -f4)
+
+  echo "[UAP-CIRCUIT-BREAKER] Hook '${hook_type}' triggered ${count} times (${suppressed} suppressed). This is a runaway loop. Review your approach — repeated hook warnings are consuming tokens without progress."
+}
+
+# Get loop protection stats as a summary string.
+lp_stats() {
+  if [ ! -f "$LP_STATE_FILE" ]; then
+    echo "No loop protection data for this session."
+    return
+  fi
+  echo "=== UAP Loop Protection Stats ==="
+  while IFS='|' read -r hook count first_ts last_ts suppressed; do
+    echo "  ${hook}: ${count} calls, ${suppressed} suppressed"
+  done < "$LP_STATE_FILE"
+  echo "================================="
+}
+
+# Reset state for a specific hook or all hooks.
+lp_reset() {
+  local hook_type="${1:-}"
+  if [ -z "$hook_type" ]; then
+    rm -f "$LP_STATE_FILE" 2>/dev/null || true
+  elif [ -f "$LP_STATE_FILE" ]; then
+    grep -v "^${hook_type}|" "$LP_STATE_FILE" > "${LP_STATE_FILE}.tmp" 2>/dev/null || true
+    mv "${LP_STATE_FILE}.tmp" "$LP_STATE_FILE" 2>/dev/null || true
+  fi
+}

package/templates/hooks/post-compact.sh

@@ -5,6 +5,15 @@
 # Always exits 0 (never blocks).
 set -euo pipefail
 
+# --- Loop Protection: suppress if compaction is happening in rapid succession ---
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${HOOK_DIR}/loop-protection.sh" ]; then
+  source "${HOOK_DIR}/loop-protection.sh"
+  if lp_should_suppress "post-compact"; then
+    exit 0
+  fi
+fi
+
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${FACTORY_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-.}}}"
 DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
 COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"
@@ -108,4 +117,9 @@ fi
 
 output+="</system-reminder>"$'\n'
 
+# --- Record invocation for loop tracking ---
+if type lp_record_invocation &>/dev/null; then
+  lp_record_invocation "post-compact"
+fi
+
 echo "$output"

package/templates/hooks/post-tool-use-edit-write.sh

@@ -6,6 +6,16 @@
 # Always exits 0 (never blocks).
 set -euo pipefail
 
+# --- Loop Protection: suppress output if firing too fast ---
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${HOOK_DIR}/loop-protection.sh" ]; then
+  source "${HOOK_DIR}/loop-protection.sh"
+  if lp_should_suppress "post-tool-edit-write"; then
+    cat > /dev/null  # drain stdin
+    exit 0
+  fi
+fi
+
 # Read tool input from stdin (JSON)
 INPUT=$(cat)
 
@@ -35,4 +45,9 @@ if [ ! -f "${BACKUP_DIR}/${RELATIVE_PATH}" ] 2>/dev/null; then
   fi
 fi
 
+# --- Record invocation for loop tracking ---
+if type lp_record_invocation &>/dev/null; then
+  lp_record_invocation "post-tool-edit-write"
+fi
+
 exit 0

package/templates/hooks/pre-compact.sh

@@ -7,6 +7,15 @@
 # Fails safely - never blocks the agent.
 set -euo pipefail
 
+# --- Loop Protection: suppress if compaction is looping ---
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${HOOK_DIR}/loop-protection.sh" ]; then
+  source "${HOOK_DIR}/loop-protection.sh"
+  if lp_should_suppress "pre-compact"; then
+    exit 0
+  fi
+fi
+
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${FACTORY_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-.}}}"
 DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
 COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"

package/templates/hooks/pre-tool-use-bash.sh

@@ -5,6 +5,12 @@
 # Enforces: iac-pipeline-enforcement, worktree-enforcement, git safety policies.
 set -euo pipefail
 
+# --- Loop Protection: track frequency of blocking events ---
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${HOOK_DIR}/loop-protection.sh" ]; then
+  source "${HOOK_DIR}/loop-protection.sh"
+fi
+
 # Read tool input from stdin (JSON)
 INPUT=$(cat)
 

package/templates/hooks/pre-tool-use-edit-write.sh

@@ -5,6 +5,12 @@
 # Enforces: worktree-file-guard, worktree-enforcement policies.
 set -euo pipefail
 
+# --- Loop Protection: track frequency of blocking events ---
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${HOOK_DIR}/loop-protection.sh" ]; then
+  source "${HOOK_DIR}/loop-protection.sh"
+fi
+
 # Read tool input from stdin (JSON)
 INPUT=$(cat)
 
@@ -40,5 +46,9 @@ if echo "$FILE_PATH" | grep -q '\.worktrees/'; then
 fi
 
 # BLOCK: path is outside worktrees and not exempt
+# Record the block event for loop detection
+if type lp_record_invocation &>/dev/null; then
+  lp_record_invocation "pre-tool-edit-block"
+fi
 echo '{"decision":"block","reason":"WORKTREE POLICY VIOLATION: File path is outside .worktrees/. All edits must target files inside a worktree. Run: uap worktree create <slug> then edit files in .worktrees/NNN-<slug>/. See policies/worktree-file-guard.md"}' >&2
 exit 2

package/templates/hooks/session-start.sh

@@ -5,6 +5,15 @@
 # Fails safely - never blocks the agent.
 set -euo pipefail
 
+# --- Loop Protection ---
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${HOOK_DIR}/loop-protection.sh" ]; then
+  source "${HOOK_DIR}/loop-protection.sh"
+  if lp_should_suppress "session-start"; then
+    exit 0
+  fi
+fi
+
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${FACTORY_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-.}}}"
 DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
 COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"
@@ -101,12 +110,59 @@ if [ -f "$COORD_DB" ]; then
   " 2>/dev/null || true
 fi
 
+# ============================================================
+# MANDATORY: Auto-register this agent + start heartbeat
+# ============================================================
+AGENT_ID="claude-${SESSION_ID:-$(head -c 6 /dev/urandom | od -An -tx1 | tr -d ' \n')}"
+AGENT_NAME="claude-code"
+
+if [ -f "$COORD_DB" ]; then
+  # Register this agent
+  sqlite3 "$COORD_DB" "
+    INSERT OR REPLACE INTO agent_registry (id, name, session_id, status, capabilities, started_at, last_heartbeat)
+    VALUES ('${AGENT_ID}', '${AGENT_NAME}', '${AGENT_ID}', 'active', '[]', datetime('now'), datetime('now'));
+  " 2>/dev/null || true
+
+  # Check for other active agents and their work
+  OTHER_AGENTS=$(sqlite3 "$COORD_DB" "
+    SELECT id || ': ' || COALESCE(current_task, 'idle')
+    FROM agent_registry
+    WHERE status='active' AND id != '${AGENT_ID}'
+    ORDER BY last_heartbeat DESC LIMIT 5;
+  " 2>/dev/null || true)
+
+  ACTIVE_WORK=$(sqlite3 "$COORD_DB" "
+    SELECT agent_id || ' -> ' || resources
+    FROM work_announcements
+    WHERE completed_at IS NULL
+    ORDER BY announced_at DESC LIMIT 5;
+  " 2>/dev/null || true)
+fi
+
+# Export agent ID for downstream tools
+export UAP_AGENT_ID="${AGENT_ID}"
+
+# Start background heartbeat (every 30s, auto-stops when shell exits)
+if [ -f "$COORD_DB" ]; then
+  (
+    while true; do
+      sleep 30
+      sqlite3 "$COORD_DB" "UPDATE agent_registry SET last_heartbeat=datetime('now') WHERE id='${AGENT_ID}';" 2>/dev/null || break
+    done
+  ) &
+  HEARTBEAT_PID=$!
+  # Ensure heartbeat stops and agent deregisters on exit
+  trap "kill $HEARTBEAT_PID 2>/dev/null; sqlite3 \"$COORD_DB\" \"UPDATE agent_registry SET status='completed' WHERE id='${AGENT_ID}';\" 2>/dev/null" EXIT
+fi
+
 # ============================================================
 # WORKTREE ENFORCEMENT GATE
 # Detects if running on master/main outside a worktree and
 # emits a blocking system-reminder to prevent direct edits.
 # ============================================================
 CURRENT_BRANCH=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null || echo "unknown")
+
+# Detect worktree via git-dir vs git-common-dir comparison
 GIT_DIR_VAL=$(git -C "$PROJECT_DIR" rev-parse --git-dir 2>/dev/null || echo "")
 GIT_COMMON_DIR_VAL=$(git -C "$PROJECT_DIR" rev-parse --git-common-dir 2>/dev/null || echo "")
 IS_IN_WORKTREE="false"
@@ -150,51 +206,6 @@ if [ "$IS_IN_WORKTREE" = "false" ] && { [ "$CURRENT_BRANCH" = "master" ] || [ "$
   echo "$worktree_output"
 fi
 
-# ============================================================
-# MANDATORY: Auto-register this agent + start heartbeat
-# ============================================================
-AGENT_ID="claude-${SESSION_ID:-$(head -c 6 /dev/urandom | od -An -tx1 | tr -d ' \n')}"
-AGENT_NAME="claude-code"
-
-if [ -f "$COORD_DB" ]; then
-  # Register this agent
-  sqlite3 "$COORD_DB" "
-    INSERT OR REPLACE INTO agent_registry (id, name, session_id, status, capabilities, started_at, last_heartbeat)
-    VALUES ('${AGENT_ID}', '${AGENT_NAME}', '${AGENT_ID}', 'active', '[]', datetime('now'), datetime('now'));
-  " 2>/dev/null || true
-
-  # Check for other active agents and their work
-  OTHER_AGENTS=$(sqlite3 "$COORD_DB" "
-    SELECT id || ': ' || COALESCE(current_task, 'idle')
-    FROM agent_registry
-    WHERE status='active' AND id != '${AGENT_ID}'
-    ORDER BY last_heartbeat DESC LIMIT 5;
-  " 2>/dev/null || true)
-
-  ACTIVE_WORK=$(sqlite3 "$COORD_DB" "
-    SELECT agent_id || ' -> ' || resources
-    FROM work_announcements
-    WHERE completed_at IS NULL
-    ORDER BY announced_at DESC LIMIT 5;
-  " 2>/dev/null || true)
-fi
-
-# Export agent ID for downstream tools
-export UAP_AGENT_ID="${AGENT_ID}"
-
-# Start background heartbeat (every 30s, auto-stops when shell exits)
-if [ -f "$COORD_DB" ]; then
-  (
-    while true; do
-      sleep 30
-      sqlite3 "$COORD_DB" "UPDATE agent_registry SET last_heartbeat=datetime('now') WHERE id='${AGENT_ID}';" 2>/dev/null || break
-    done
-  ) &
-  HEARTBEAT_PID=$!
-  # Ensure heartbeat stops and agent deregisters on exit
-  trap "kill $HEARTBEAT_PID 2>/dev/null; sqlite3 \"$COORD_DB\" \"UPDATE agent_registry SET status='completed' WHERE id='${AGENT_ID}';\" 2>/dev/null" EXIT
-fi
-
 output=""
 
 # ============================================================
@@ -412,4 +423,8 @@ fi
 
 if [ -n "$output" ]; then
   echo "$output"
+  # Record invocation for loop tracking
+  if type lp_record_invocation &>/dev/null; then
+    lp_record_invocation "session-start"
+  fi
 fi

package/templates/hooks/stop.sh

@@ -6,6 +6,15 @@
 # Enforces: completion-gate, mandatory-testing-deployment policies.
 set -euo pipefail
 
+# --- Loop Protection ---
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${HOOK_DIR}/loop-protection.sh" ]; then
+  source "${HOOK_DIR}/loop-protection.sh"
+  if lp_should_suppress "stop"; then
+    exit 0
+  fi
+fi
+
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${FACTORY_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-.}}}"
 DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
 COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"

package/tools/agents/scripts/anthropic_proxy.py

@@ -130,6 +130,11 @@ class SessionMonitor:
     overflow_count: int = 0          # How many context overflow errors caught
     context_history: list = field(default_factory=list)  # Recent token counts
 
+    # --- Token Loop Protection ---
+    tool_call_history: list = field(default_factory=list)  # Recent tool call fingerprints
+    consecutive_forced_count: int = 0   # How many times tool_choice was forced consecutively
+    loop_warnings_emitted: int = 0      # How many loop warnings sent to the model
+
     def record_request(self, estimated_tokens: int):
         """Record an outgoing request's estimated token count."""
         self.total_requests += 1
@@ -213,6 +218,85 @@ class SessionMonitor:
                 turns_str,
             )
 
+    # --- Token Loop Protection Methods ---
+
+    def record_tool_calls(self, tool_names: list[str]):
+        """Record tool call names for loop detection."""
+        fingerprint = "|".join(sorted(tool_names)) if tool_names else ""
+        self.tool_call_history.append(fingerprint)
+        # Keep last 30 entries
+        if len(self.tool_call_history) > 30:
+            self.tool_call_history = self.tool_call_history[-30:]
+
+    def detect_tool_loop(self, window: int = 6) -> tuple[bool, int]:
+        """Detect if the model is stuck in a tool call loop.
+
+        Checks if the last `window` tool call fingerprints are identical.
+        Returns (is_looping, repeat_count).
+        """
+        if len(self.tool_call_history) < window:
+            return False, 0
+
+        recent = self.tool_call_history[-window:]
+        if not recent[0]:
+            return False, 0
+
+        # Check if all recent entries are the same fingerprint
+        if all(fp == recent[0] for fp in recent):
+            # Count total consecutive repeats from the end
+            count = 0
+            target = recent[0]
+            for fp in reversed(self.tool_call_history):
+                if fp == target:
+                    count += 1
+                else:
+                    break
+            return True, count
+
+        return False, 0
+
+    def should_release_tool_choice(self) -> bool:
+        """Determine if tool_choice should be relaxed to 'auto' to break a loop.
+
+        Returns True if the model appears stuck and forcing tool_choice=required
+        is making it worse. Thresholds:
+          - 8+ consecutive forced requests with same tool pattern -> release
+          - 15+ consecutive forced requests regardless -> release
+          - Context utilization > 90% -> release (let model wrap up)
+        """
+        is_looping, repeat_count = self.detect_tool_loop(window=6)
+
+        # Pattern 1: Detected tool call loop
+        if is_looping and repeat_count >= 8:
+            logger.warning(
+                "LOOP BREAKER: Same tool pattern repeated %d times. "
+                "Releasing tool_choice to 'auto'.",
+                repeat_count,
+            )
+            self.loop_warnings_emitted += 1
+            return True
+
+        # Pattern 2: Too many consecutive forced requests
+        if self.consecutive_forced_count >= 15:
+            logger.warning(
+                "LOOP BREAKER: %d consecutive forced tool_choice requests. "
+                "Releasing to 'auto'.",
+                self.consecutive_forced_count,
+            )
+            self.loop_warnings_emitted += 1
+            return True
+
+        # Pattern 3: Context almost full -- let model wrap up naturally
+        if self.get_utilization() >= 0.90:
+            logger.warning(
+                "LOOP BREAKER: Context utilization %.1f%% -- releasing "
+                "tool_choice to let model wrap up.",
+                self.get_utilization() * 100,
+            )
+            return True
+
+        return False
+
 
 session_monitor = SessionMonitor()
 
@@ -684,6 +768,10 @@ def build_openai_request(anthropic_body: dict) -> dict:
         #   - More than 1 message (conversation is in progress)
         #   - Last assistant was text-only (would cause premature stop)
         #   - OR conversation has tool_result messages (active agentic loop)
+        #
+        # LOOP PROTECTION: Release to "auto" if the session monitor detects
+        # a tool call loop (same tools called repeatedly), to prevent
+        # runaway token consumption.
         n_msgs = len(anthropic_body.get("messages", []))
         has_tool_results = any(
             isinstance(m.get("content"), list) and any(
@@ -692,16 +780,47 @@ def build_openai_request(anthropic_body: dict) -> dict:
             )
             for m in anthropic_body.get("messages", [])
         )
-        if _last_assistant_was_text_only(anthropic_body):
+
+        # Record tool calls from the last assistant message for loop detection
+        _record_last_assistant_tool_calls(anthropic_body)
+
+        # Check if loop breaker should override tool_choice
+        if session_monitor.should_release_tool_choice():
+            openai_body["tool_choice"] = "auto"
+            session_monitor.consecutive_forced_count = 0
+            logger.warning("tool_choice set to 'auto' by LOOP BREAKER")
+        elif _last_assistant_was_text_only(anthropic_body):
             openai_body["tool_choice"] = "required"
+            session_monitor.consecutive_forced_count += 1
             logger.info("tool_choice forced to 'required' (last assistant was text-only)")
         elif has_tool_results and n_msgs > 2:
             openai_body["tool_choice"] = "required"
+            session_monitor.consecutive_forced_count += 1
             logger.info("tool_choice forced to 'required' (active agentic loop with tool results)")
+        else:
+            session_monitor.consecutive_forced_count = 0
 
     return openai_body
 
 
+def _record_last_assistant_tool_calls(anthropic_body: dict):
+    """Extract tool call names from the last assistant message and record
+    them in the session monitor for loop detection."""
+    messages = anthropic_body.get("messages", [])
+    tool_names = []
+    for msg in reversed(messages):
+        if msg.get("role") != "assistant":
+            continue
+        content = msg.get("content")
+        if isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "tool_use":
+                    tool_names.append(block.get("name", "unknown"))
+        break
+    if tool_names:
+        session_monitor.record_tool_calls(tool_names)
+
+
 def _last_assistant_was_text_only(anthropic_body: dict) -> bool:
     """Check if the last assistant message in the conversation was text-only
     (no tool_use blocks). This indicates the model may be prematurely ending
@@ -1281,6 +1400,15 @@ async def context_status():
         "overflow_count": session_monitor.overflow_count,
         "prune_threshold": PROXY_CONTEXT_PRUNE_THRESHOLD,
         "recent_history": session_monitor.context_history[-10:],
+        # Loop protection stats
+        "loop_protection": {
+            "consecutive_forced_count": session_monitor.consecutive_forced_count,
+            "loop_warnings_emitted": session_monitor.loop_warnings_emitted,
+            "tool_call_history_len": len(session_monitor.tool_call_history),
+            "is_looping": session_monitor.detect_tool_loop()[0],
+            "loop_repeat_count": session_monitor.detect_tool_loop()[1],
+            "recent_tool_patterns": session_monitor.tool_call_history[-5:],
+        },
     }