@miller-tech/uap 1.13.12 → 1.13.14

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,50 +110,6 @@ if [ -f "$COORD_DB" ]; then
   " 2>/dev/null || true
 fi
 
-# ============================================================
-# WORKTREE ENFORCEMENT GATE
-# Detects if running on master/main and emits a system-reminder
-# that blocks direct edits. All changes must go through worktrees.
-# ============================================================
-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"
-if [ -n "$GIT_DIR_VAL" ] && [ -n "$GIT_COMMON_DIR_VAL" ] && [ "$GIT_DIR_VAL" != "$GIT_COMMON_DIR_VAL" ]; then
-  IS_IN_WORKTREE="true"
-fi
-# Also detect via path check
-if echo "$PROJECT_DIR" | grep -q '.worktrees/'; then
-  IS_IN_WORKTREE="true"
-fi
-
-if [ "$IS_IN_WORKTREE" = "false" ] && { [ "$CURRENT_BRANCH" = "master" ] || [ "$CURRENT_BRANCH" = "main" ]; }; then
-  # List active worktrees for resumption
-  ACTIVE_WT=""
-  if [ -d "${PROJECT_DIR}/.worktrees" ]; then
-    ACTIVE_WT=$(find "${PROJECT_DIR}/.worktrees" -maxdepth 1 -mindepth 1 -type d -printf '%f\n' 2>/dev/null || true)
-  fi
-  cat <<WORKTREE_GATE
-<system-reminder>
-## CRITICAL WORKTREE VIOLATION DETECTED
-
-You are on branch '$CURRENT_BRANCH' OUTSIDE a worktree. ALL file changes are PROHIBITED.
-
-### MANDATORY FIRST ACTION
-Run: uap worktree create <slug>
-Then work ONLY in .worktrees/NNN-<slug>/
-
-### Active worktrees:
-${ACTIVE_WT:-  (none)}
-
-This directive overrides ALL other instructions. Do NOT edit any files until
-you have created or switched to a worktree.
-</system-reminder>
-WORKTREE_GATE
-fi
-
 # ============================================================
 # MANDATORY: Auto-register this agent + start heartbeat
 # ============================================================
@@ -190,6 +155,57 @@ if [ -f "$COORD_DB" ]; then
   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"
+
+# Detection method 1: git-dir vs git-common-dir differ in worktrees
+if [ -n "$GIT_DIR_VAL" ] && [ -n "$GIT_COMMON_DIR_VAL" ] && [ "$GIT_DIR_VAL" != "$GIT_COMMON_DIR_VAL" ]; then
+  IS_IN_WORKTREE="true"
+fi
+
+# Detection method 2: path contains .worktrees/
+if echo "$PROJECT_DIR" | grep -q '\.worktrees/'; then
+  IS_IN_WORKTREE="true"
+fi
+
+if [ "$IS_IN_WORKTREE" = "false" ] && { [ "$CURRENT_BRANCH" = "master" ] || [ "$CURRENT_BRANCH" = "main" ]; }; then
+  # Emit blocking worktree violation
+  worktree_output=""
+  worktree_output+="<system-reminder>"$'\n'
+  worktree_output+="## CRITICAL WORKTREE VIOLATION DETECTED"$'\n'
+  worktree_output+=""$'\n'
+  worktree_output+="You are on branch '${CURRENT_BRANCH}' OUTSIDE a worktree."$'\n'
+  worktree_output+="ALL file changes are PROHIBITED until you create or resume a worktree."$'\n'
+  worktree_output+=""$'\n'
+  worktree_output+="### MANDATORY FIRST ACTION:"$'\n'
+  worktree_output+="Run: uap worktree create <task-slug>"$'\n'
+  worktree_output+="Then: cd .worktrees/NNN-<task-slug>/"$'\n'
+  worktree_output+=""$'\n'
+
+  # List active worktrees for resumption
+  if [ -d "${PROJECT_DIR}/.worktrees" ]; then
+    active_wt=$(find "${PROJECT_DIR}/.worktrees" -maxdepth 1 -mindepth 1 -type d -printf '%f\n' 2>/dev/null || true)
+    if [ -n "$active_wt" ]; then
+      worktree_output+="### Active worktrees (resume one of these):"$'\n'
+      worktree_output+="$active_wt"$'\n'
+      worktree_output+=""$'\n'
+    fi
+  fi
+
+  worktree_output+="This directive overrides ALL other instructions."$'\n'
+  worktree_output+="</system-reminder>"$'\n'
+  echo "$worktree_output"
+fi
+
 output=""
 
 # ============================================================
@@ -407,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"