cc-safe-setup 29.7.0 → 29.8.0

package/README.md

@@ -6,7 +6,7 @@
 
 > 🚀 **Launching on [Product Hunt](https://www.producthunt.com/products/cc-safe-setup) — April 21!** Follow us and upvote to support open source safety for AI coding agents.
 
-**One command to make Claude Code safe for autonomous operation.** 700 example hooks · 9,200+ tests · 30K+ total installs · [日本語](docs/README.ja.md)
+**One command to make Claude Code safe for autonomous operation.** 701 example hooks · 9,200+ tests · 30K+ total installs · [日本語](docs/README.ja.md)
 
 ```bash
 npx cc-safe-setup
@@ -16,7 +16,7 @@ Installs 8 safety hooks in ~10 seconds. Blocks `rm -rf /`, prevents pushes to ma
 
 > **What's a hook?** A checkpoint that runs before Claude executes a command. Like airport security — it inspects what's about to happen and blocks anything dangerous before it reaches the gate.
 
-[**Getting Started**](https://yurukusa.github.io/cc-safe-setup/getting-started.html) · [**Hook Selector**](https://yurukusa.github.io/cc-safe-setup/hook-selector.html) · [**Token Checkup**](https://yurukusa.github.io/cc-safe-setup/token-checkup.html) · [**Cache Health**](https://yurukusa.github.io/cc-safe-setup/cache-health.html) · [**Version Check**](https://yurukusa.github.io/cc-safe-setup/version-check.html) · [**CLAUDE.md Analyzer**](https://yurukusa.github.io/cc-safe-setup/claudemd-analyzer.html) · [**All Tools**](https://yurukusa.github.io/cc-safe-setup/hub.html) · [**Recipes**](https://yurukusa.github.io/cc-safe-setup/recipes.html) · [Validate your settings.json](https://yurukusa.github.io/cc-safe-setup/validator.html) · [**Check your score**](https://yurukusa.github.io/cc-health-check/) (`npx cc-health-check`) · [**Safety Audit**](https://yurukusa.github.io/cc-safe-setup/safety-audit.html)
+[**Getting Started**](https://yurukusa.github.io/cc-safe-setup/getting-started.html) · [**Incident Tracker**](https://yurukusa.github.io/cc-safe-setup/incidents.html) · [**Hook Selector**](https://yurukusa.github.io/cc-safe-setup/hook-selector.html) · [**Token Checkup**](https://yurukusa.github.io/cc-safe-setup/token-checkup.html) · [**Cache Health**](https://yurukusa.github.io/cc-safe-setup/cache-health.html) · [**Version Check**](https://yurukusa.github.io/cc-safe-setup/version-check.html) · [**CLAUDE.md Analyzer**](https://yurukusa.github.io/cc-safe-setup/claudemd-analyzer.html) · [**All Tools**](https://yurukusa.github.io/cc-safe-setup/hub.html) · [**Recipes**](https://yurukusa.github.io/cc-safe-setup/recipes.html) · [Validate your settings.json](https://yurukusa.github.io/cc-safe-setup/validator.html) · [**Check your score**](https://yurukusa.github.io/cc-health-check/) (`npx cc-health-check`) · [**Safety Audit**](https://yurukusa.github.io/cc-safe-setup/safety-audit.html)
 
 ```
   cc-safe-setup
@@ -190,7 +190,7 @@ Guards against issues that corrupt sessions or waste tokens silently.
 | `--scan [--apply]` | Tech stack detection |
 | `--export / --import` | Team config sharing |
 | `--verify` | Test each hook |
-| `--install-example <name>` | Install from 700 examples |
+| `--install-example <name>` | Install from 701 examples |
 | `--examples [filter]` | Browse examples by keyword |
 | `--full` | All-in-one setup |
 | `--status` | Check installed hooks |
@@ -495,7 +495,7 @@ See [Issue #1](https://github.com/yurukusa/cc-safe-setup/issues/1) for details.
 
 ## Learn More
 
-- **[Opus 4.7 Survival Guide](https://yurukusa.github.io/cc-safe-setup/opus-47-survival-guide.html)** — 50 known issues (67+ GitHub Issues + CVEs) with fixes: data loss, recursive spawn DoS, billing mismatch, subagent OOM, cache_read anomaly, allowedTools bypass, 1.7x token inflation, classifier failure, thinking summary bugs, 30-min stalls, and more. [`npx cc-safe-setup --opus47`](#-opus-47-crisis-april-2026)
+- **[Opus 4.7 Survival Guide](https://yurukusa.github.io/cc-safe-setup/opus-47-survival-guide.html)** — 61 known issues (76+ GitHub Issues + CVEs) with fixes: data loss, recursive spawn DoS, billing mismatch, subagent OOM, cache_read anomaly, allowedTools bypass, 1.7x token inflation, classifier failure, thinking summary bugs, 30-min stalls, enterprise hooks bypass, and more. [`npx cc-safe-setup --opus47`](#-opus-47-crisis-april-2026)
 - **[Token Book (¥2,500)](https://zenn.dev/yurukusa/books/token-savings-guide)** — Cut token consumption in half. CLAUDE.md optimization, hook-based guards, context management, workflow design. 44,000 words with copy-paste templates. Intro + Ch.1 free. [Details](https://yurukusa.github.io/cc-safe-setup/token-book.html)
 - **[Safety Guide (¥800)](https://zenn.dev/yurukusa/books/6076c23b1cb18b)** — Token consumption diagnosis, file loss prevention, autonomous operation safety. From 800+ hours of real incidents. [Chapter 3 free](https://zenn.dev/yurukusa/books/6076c23b1cb18b/viewer/3-code-quality)
 - **[800 Hours Operation Record (¥800)](https://zenn.dev/yurukusa/books/3c3c3baee85f0a19)** — Non-engineer running Claude Code autonomously for 800 hours. Failures, recovery, revenue reality. [Chapter 2 free](https://zenn.dev/yurukusa/books/3c3c3baee85f0a19/viewer/2-first-failures)

package/examples/compact-circuit-breaker.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# ================================================================
+# compact-circuit-breaker.sh — Prevent auto-compact death spirals
+# ================================================================
+# PURPOSE:
+#   Auto-compact can enter an infinite loop when FileHistory
+#   recovery is degraded — each compaction fails to restore
+#   continuity, triggering the next one immediately. Users have
+#   lost entire overnight token budgets to 15+ consecutive
+#   compactions with zero forward progress (#51088). One incident
+#   recorded 211 compactions in a single session (#24179).
+#
+#   This hook acts as a circuit breaker: it allows normal
+#   compaction but blocks rapid-fire compaction that indicates
+#   a death spiral. After MAX_PER_HOUR compactions, further
+#   attempts are blocked until the window resets.
+#
+# TRIGGER: PreCompact
+# MATCHER: (none — PreCompact has no matcher)
+#
+# DECISION: exit 0 = allow, exit 2 = block
+#
+# CONFIG:
+#   MAX_PER_HOUR — Maximum compactions allowed per hour (default: 3)
+#   MIN_INTERVAL — Minimum seconds between compactions (default: 120)
+#
+# See: https://github.com/anthropics/claude-code/issues/51088
+#      https://github.com/anthropics/claude-code/issues/24179
+# ================================================================
+
+MAX_PER_HOUR="${CC_COMPACT_MAX_PER_HOUR:-3}"
+MIN_INTERVAL="${CC_COMPACT_MIN_INTERVAL:-120}"
+STATE_DIR="/tmp/.cc-compact-circuit-breaker"
+STATE_FILE="$STATE_DIR/compaction-log"
+
+mkdir -p "$STATE_DIR"
+touch "$STATE_FILE"
+
+NOW=$(date +%s)
+ONE_HOUR_AGO=$((NOW - 3600))
+
+# Clean old entries (older than 1 hour)
+if [ -f "$STATE_FILE" ]; then
+  awk -v cutoff="$ONE_HOUR_AGO" '$1 >= cutoff' "$STATE_FILE" > "$STATE_FILE.tmp"
+  mv "$STATE_FILE.tmp" "$STATE_FILE"
+fi
+
+# Count compactions in the last hour
+RECENT_COUNT=$(wc -l < "$STATE_FILE" | tr -d ' ')
+
+# Check minimum interval since last compaction
+LAST_TIME=0
+if [ -s "$STATE_FILE" ]; then
+  LAST_TIME=$(tail -1 "$STATE_FILE")
+fi
+ELAPSED=$((NOW - LAST_TIME))
+
+# Circuit breaker: block if too many compactions
+if [ "$RECENT_COUNT" -ge "$MAX_PER_HOUR" ]; then
+  echo "CIRCUIT BREAKER: $RECENT_COUNT compactions in the last hour (max: $MAX_PER_HOUR). Possible death spiral detected. Start a fresh session instead of compacting." >&2
+  exit 2
+fi
+
+# Cooldown: block if too soon after last compaction
+if [ "$ELAPSED" -lt "$MIN_INTERVAL" ] && [ "$LAST_TIME" -gt 0 ]; then
+  echo "COOLDOWN: Last compaction was ${ELAPSED}s ago (min interval: ${MIN_INTERVAL}s). Wait before compacting again." >&2
+  exit 2
+fi
+
+# Allow compaction and log it
+echo "$NOW" >> "$STATE_FILE"
+exit 0

package/examples/exploration-budget-guard.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# exploration-budget-guard.sh — Stop excessive exploration from draining tokens
+#
+# Solves: #51054 — Claude wastes 20% of weekly allowance exploring files
+#         on a simple task instead of acting. Read/Glob/Grep loops with
+#         no Edit/Write progress.
+#
+# Tracks read-only tool calls (Read, Glob, Grep) per session. After 25
+# consecutive reads without a write, warns. After 40, blocks.
+# Resets when an Edit/Write/Bash(write) occurs.
+#
+# TRIGGER: PreToolUse  MATCHER: "Read|Glob|Grep|Edit|Write"
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+STATE_DIR="/tmp/.cc-exploration-budget"
+mkdir -p "$STATE_DIR"
+
+# Session-scoped state file (keyed by parent PID)
+STATE_FILE="$STATE_DIR/session-$$"
+# Fall back to a shared file if $$ changes between hook calls
+STATE_FILE="$STATE_DIR/exploration-count"
+
+NOW=$(date +%s)
+
+case "$TOOL" in
+  Edit|Write)
+    # Write operation = progress. Reset exploration counter.
+    echo "0 $NOW" > "$STATE_FILE"
+    exit 0
+    ;;
+  Read|Glob|Grep)
+    # Read operation = exploration. Increment counter.
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Read current count
+COUNT=0
+LAST_TIME=0
+if [ -f "$STATE_FILE" ]; then
+    read -r COUNT LAST_TIME < "$STATE_FILE" 2>/dev/null || true
+    # Reset if more than 10 minutes since last call (new task)
+    ELAPSED=$(( NOW - LAST_TIME ))
+    if [ "$ELAPSED" -gt 600 ]; then
+        COUNT=0
+    fi
+fi
+
+COUNT=$(( COUNT + 1 ))
+echo "$COUNT $NOW" > "$STATE_FILE"
+
+WARN_THRESHOLD=25
+BLOCK_THRESHOLD=40
+
+if [ "$COUNT" -ge "$BLOCK_THRESHOLD" ]; then
+    echo "BLOCKED: $COUNT consecutive read operations without writing anything." >&2
+    echo "  You're stuck in an exploration loop — this wastes tokens." >&2
+    echo "  Take action NOW:" >&2
+    echo "  1. Write your solution based on what you've already read" >&2
+    echo "  2. If unsure, make a small change and test it" >&2
+    echo "  3. Ask the user for clarification instead of reading more files" >&2
+    echo "" >&2
+    echo "  Exploration budget: $COUNT/$BLOCK_THRESHOLD (EXCEEDED)" >&2
+    exit 2
+fi
+
+if [ "$COUNT" -ge "$WARN_THRESHOLD" ]; then
+    echo "WARNING: $COUNT consecutive reads without any write." >&2
+    echo "  You may be over-exploring. Consider acting on what you know." >&2
+    echo "  Budget: $COUNT/$BLOCK_THRESHOLD reads before block." >&2
+fi
+
+exit 0

package/examples/thinking-stall-detector.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# thinking-stall-detector.sh — Detect when Claude's thinking phase stalls
+#
+# Solves: #51092 — Sonnet 4.6 thinking ran for 25 minutes, consuming
+#         16M+ tokens. User lost entire token allowance to a single
+#         reasoning phase that never produced output.
+#
+# HOW IT WORKS:
+#   Tracks time between consecutive tool calls. If the gap exceeds
+#   a threshold (default 5 minutes), it means Claude was "thinking"
+#   without taking any action — likely a reasoning stall.
+#
+#   On detection, logs a warning with the stall duration and suggests
+#   the user interrupt with Ctrl+C.
+#
+# WHY THIS MATTERS:
+#   During thinking, tokens are consumed but no hooks fire. This hook
+#   fires on the NEXT tool call after the stall, so it can't prevent
+#   the stall itself — but it alerts the user that one occurred, so
+#   they can watch for it happening again and interrupt early.
+#
+# TRIGGER: PreToolUse  MATCHER: ""
+# Also works as: Notification (fires on status changes)
+#
+# CONFIGURATION:
+#   CC_STALL_WARN_SECS=300    warn after 5-minute gap (default)
+#   CC_STALL_LOG=/tmp/cc-thinking-stalls.log
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+STATE_FILE="/tmp/cc-thinking-stall-last-call"
+LOG_FILE="${CC_STALL_LOG:-/tmp/cc-thinking-stalls.log}"
+WARN_SECS="${CC_STALL_WARN_SECS:-300}"
+
+NOW=$(date +%s)
+
+# Read last tool call timestamp
+LAST=$(cat "$STATE_FILE" 2>/dev/null || echo "$NOW")
+
+# Update timestamp
+echo "$NOW" > "$STATE_FILE"
+
+# Calculate gap
+GAP=$((NOW - LAST))
+
+if [ "$GAP" -ge "$WARN_SECS" ]; then
+    MINUTES=$((GAP / 60))
+    REMAINDER=$((GAP % 60))
+
+    # Log the stall
+    echo "$(date -Iseconds) STALL ${MINUTES}m${REMAINDER}s before tool=$TOOL" >> "$LOG_FILE"
+
+    # Warn the user
+    echo "⚠️ Thinking stall detected: ${MINUTES}m${REMAINDER}s with no tool activity." >&2
+    echo "This may indicate a reasoning loop consuming tokens silently." >&2
+    echo "If this happens again, press Ctrl+C to interrupt." >&2
+    echo "See #51092: 25-minute thinking stall consumed 16M tokens." >&2
+fi
+
+exit 0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cc-safe-setup",
-  "version": "29.7.0",
-  "description": "One command to make Claude Code safe. 700 example hooks + 8 built-in. 56 CLI commands. Token consumption diagnosis. Works with Auto Mode.",
+  "version": "29.8.0",
+  "description": "One command to make Claude Code safe. 701 example hooks + 8 built-in. 56 CLI commands. Token consumption diagnosis. Works with Auto Mode.",
   "main": "index.mjs",
   "bin": {
     "cc-safe-setup": "index.mjs"

package/tests/test-compact-circuit-breaker.sh

@@ -0,0 +1,134 @@
+#!/bin/bash
+# Tests for compact-circuit-breaker.sh
+set -uo pipefail
+
+HOOK="$(dirname "$0")/../examples/compact-circuit-breaker.sh"
+STATE_DIR="/tmp/.cc-compact-circuit-breaker"
+STATE_FILE="$STATE_DIR/compaction-log"
+PASS=0; FAIL=0; TOTAL=0
+
+run_test() {
+  local desc="$1"; shift
+  TOTAL=$((TOTAL + 1))
+  if "$@" 2>/dev/null; then
+    PASS=$((PASS + 1))
+    echo "✅ $desc"
+  else
+    local code=$?
+    if [ "$code" -eq 2 ]; then
+      # exit 2 = block, might be expected
+      FAIL=$((FAIL + 1))
+      echo "❌ $desc (exit $code)"
+    else
+      FAIL=$((FAIL + 1))
+      echo "❌ $desc (exit $code)"
+    fi
+  fi
+}
+
+run_test_blocked() {
+  local desc="$1"; shift
+  TOTAL=$((TOTAL + 1))
+  local code=0
+  "$@" 2>/dev/null || code=$?
+  if [ "$code" -eq 2 ]; then
+    PASS=$((PASS + 1))
+    echo "✅ $desc (correctly blocked)"
+  else
+    FAIL=$((FAIL + 1))
+    echo "❌ $desc (expected block, got exit $code)"
+  fi
+}
+
+cleanup() {
+  rm -rf "$STATE_DIR"
+  mkdir -p "$STATE_DIR"
+}
+
+# Test 1: First compaction should be allowed
+cleanup
+run_test "First compaction allowed" bash "$HOOK"
+
+# Test 2: Second compaction within MIN_INTERVAL should be blocked (cooldown)
+run_test_blocked "Cooldown blocks rapid compaction" bash "$HOOK"
+
+# Test 3: After cooldown, compaction should be allowed
+cleanup
+echo "$(($(date +%s) - 200))" > "$STATE_FILE"
+run_test "Compaction allowed after cooldown" bash "$HOOK"
+
+# Test 4: Circuit breaker triggers after MAX_PER_HOUR
+cleanup
+NOW=$(date +%s)
+for i in $(seq 1 3); do
+  echo "$((NOW - 300 + i * 10))" >> "$STATE_FILE"
+done
+run_test_blocked "Circuit breaker blocks after 3 compactions" bash "$HOOK"
+
+# Test 5: Old entries are cleaned up
+cleanup
+ONE_HOUR_AGO=$(($(date +%s) - 3700))
+for i in $(seq 1 5); do
+  echo "$((ONE_HOUR_AGO - i * 10))" >> "$STATE_FILE"
+done
+run_test "Old entries cleaned, compaction allowed" bash "$HOOK"
+
+# Test 6: Custom MAX_PER_HOUR
+cleanup
+NOW=$(date +%s)
+echo "$((NOW - 200))" > "$STATE_FILE"
+run_test_blocked "Custom MAX_PER_HOUR=1 blocks second" env CC_COMPACT_MAX_PER_HOUR=1 bash "$HOOK"
+
+# Test 7: Custom MIN_INTERVAL
+cleanup
+echo "$(date +%s)" > "$STATE_FILE"
+run_test_blocked "Default MIN_INTERVAL blocks immediate retry" bash "$HOOK"
+
+# Test 8: State directory created if missing
+rm -rf "$STATE_DIR"
+run_test "Creates state directory" bash "$HOOK"
+[ -d "$STATE_DIR" ] && echo "  ↳ State directory exists ✅" || echo "  ↳ State directory missing ❌"
+
+# Test 9: Empty state file handled
+cleanup
+mkdir -p "$STATE_DIR"
+touch "$STATE_FILE"
+run_test "Empty state file handled" bash "$HOOK"
+
+# Test 10: Mixed old and new entries
+cleanup
+NOW=$(date +%s)
+echo "$((NOW - 7200))" >> "$STATE_FILE"  # 2 hours ago (old)
+echo "$((NOW - 7100))" >> "$STATE_FILE"  # old
+echo "$((NOW - 200))" >> "$STATE_FILE"   # recent (1)
+run_test "Mixed entries: old cleaned, recent counted" bash "$HOOK"
+
+# Test 11: Exactly at MAX_PER_HOUR boundary
+cleanup
+NOW=$(date +%s)
+echo "$((NOW - 1800))" >> "$STATE_FILE"
+echo "$((NOW - 900))" >> "$STATE_FILE"
+echo "$((NOW - 200))" >> "$STATE_FILE"
+run_test_blocked "Exactly at MAX=3 boundary blocked" bash "$HOOK"
+
+# Test 12: Error message content
+cleanup
+NOW=$(date +%s)
+for i in $(seq 1 3); do
+  echo "$((NOW - 300 + i * 10))" >> "$STATE_FILE"
+done
+OUTPUT=$(bash "$HOOK" 2>&1 || true)
+TOTAL=$((TOTAL + 1))
+if echo "$OUTPUT" | grep -q "CIRCUIT BREAKER"; then
+  PASS=$((PASS + 1))
+  echo "✅ Error message contains CIRCUIT BREAKER"
+else
+  FAIL=$((FAIL + 1))
+  echo "❌ Error message missing CIRCUIT BREAKER: $OUTPUT"
+fi
+
+cleanup
+
+echo ""
+echo "Results: $PASS/$TOTAL passed, $FAIL failed"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/test-exploration-budget-guard.sh

@@ -0,0 +1,164 @@
+#!/bin/bash
+# Tests for exploration-budget-guard.sh
+set -euo pipefail
+
+HOOK="$(dirname "$0")/../examples/exploration-budget-guard.sh"
+PASS=0
+FAIL=0
+STATE_FILE="/tmp/.cc-exploration-budget/exploration-count"
+
+setup() {
+    rm -f "$STATE_FILE"
+    mkdir -p /tmp/.cc-exploration-budget
+}
+
+run_hook() {
+    echo "$1" | bash "$HOOK" 2>&1 || true
+}
+
+assert_pass() {
+    local desc="$1"
+    local input="$2"
+    output=$(echo "$input" | bash "$HOOK" 2>&1) && rc=0 || rc=$?
+    if [ "$rc" -eq 0 ] && ! echo "$output" | grep -q "WARNING\|BLOCKED"; then
+        PASS=$((PASS + 1))
+        echo "  PASS: $desc"
+    else
+        FAIL=$((FAIL + 1))
+        echo "  FAIL: $desc (expected clean pass, rc=$rc)"
+        echo "    output: $output"
+    fi
+}
+
+assert_warn() {
+    local desc="$1"
+    local input="$2"
+    output=$(echo "$input" | bash "$HOOK" 2>&1) && rc=0 || rc=$?
+    if [ $rc -eq 0 ] && echo "$output" | grep -q "WARNING"; then
+        PASS=$((PASS + 1))
+        echo "  PASS: $desc"
+    else
+        FAIL=$((FAIL + 1))
+        echo "  FAIL: $desc (expected warning, rc=$rc)"
+        echo "    output: $output"
+    fi
+}
+
+assert_block() {
+    local desc="$1"
+    local input="$2"
+    output=$(echo "$input" | bash "$HOOK" 2>&1) && rc=0 || rc=$?
+    if [ $rc -eq 2 ] && echo "$output" | grep -q "BLOCKED"; then
+        PASS=$((PASS + 1))
+        echo "  PASS: $desc"
+    else
+        FAIL=$((FAIL + 1))
+        echo "  FAIL: $desc (expected block, rc=$rc)"
+        echo "    output: $output"
+    fi
+}
+
+READ_INPUT='{"tool_name":"Read","tool_input":{"file_path":"/tmp/test.txt"}}'
+GLOB_INPUT='{"tool_name":"Glob","tool_input":{"pattern":"*.ts"}}'
+GREP_INPUT='{"tool_name":"Grep","tool_input":{"pattern":"foo"}}'
+EDIT_INPUT='{"tool_name":"Edit","tool_input":{"file_path":"/tmp/test.txt","old_string":"a","new_string":"b"}}'
+WRITE_INPUT='{"tool_name":"Write","tool_input":{"file_path":"/tmp/test.txt","content":"hello"}}'
+OTHER_INPUT='{"tool_name":"Bash","tool_input":{"command":"ls"}}'
+
+echo "=== exploration-budget-guard tests ==="
+
+# Test 1: Single read passes
+setup
+assert_pass "single Read passes" "$READ_INPUT"
+
+# Test 2: Non-tracked tool passes
+setup
+assert_pass "Bash is not tracked" "$OTHER_INPUT"
+
+# Test 3: Edit resets counter
+setup
+for i in $(seq 1 20); do
+    echo "$READ_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+echo "$EDIT_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+assert_pass "Read after Edit reset passes" "$READ_INPUT"
+
+# Test 4: Write resets counter
+setup
+for i in $(seq 1 20); do
+    echo "$READ_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+echo "$WRITE_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+assert_pass "Read after Write reset passes" "$READ_INPUT"
+
+# Test 5: Warning at threshold
+setup
+for i in $(seq 1 24); do
+    echo "$READ_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+assert_warn "warns at 25 reads" "$READ_INPUT"
+
+# Test 6: Different read tools count together
+setup
+for i in $(seq 1 8); do
+    echo "$READ_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+    echo "$GLOB_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+    echo "$GREP_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+assert_warn "mixed read tools warn at 25" "$READ_INPUT"
+
+# Test 7: Block at 40
+setup
+for i in $(seq 1 39); do
+    echo "$READ_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+assert_block "blocks at 40 reads" "$READ_INPUT"
+
+# Test 8: Block shows count
+setup
+for i in $(seq 1 41); do
+    echo "$READ_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+output=$(echo "$READ_INPUT" | bash "$HOOK" 2>&1 || true)
+if echo "$output" | grep -q "EXCEEDED"; then
+    PASS=$((PASS + 1))
+    echo "  PASS: block message shows EXCEEDED"
+else
+    FAIL=$((FAIL + 1))
+    echo "  FAIL: block message should show EXCEEDED"
+fi
+
+# Test 9: Timeout reset (simulate 11 min gap)
+setup
+for i in $(seq 1 30); do
+    echo "$READ_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+# Fake old timestamp
+echo "30 $(($(date +%s) - 700))" > "$STATE_FILE"
+assert_pass "resets after 10min gap" "$READ_INPUT"
+
+# Test 10: Glob passes normally
+setup
+assert_pass "single Glob passes" "$GLOB_INPUT"
+
+# Test 11: Grep passes normally
+setup
+assert_pass "single Grep passes" "$GREP_INPUT"
+
+# Test 12: Counter persists across different read tools
+setup
+for i in $(seq 1 10); do
+    echo "$READ_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+for i in $(seq 1 10); do
+    echo "$GLOB_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+for i in $(seq 1 5); do
+    echo "$GREP_INPUT" | bash "$HOOK" >/dev/null 2>&1 || true
+done
+# Count should be 25 now
+assert_warn "warns at 25 mixed reads" "$GREP_INPUT"
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed out of $((PASS + FAIL)) tests"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/test-thinking-stall-detector.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+# Tests for thinking-stall-detector.sh
+set -euo pipefail
+
+HOOK="$(dirname "$0")/../examples/thinking-stall-detector.sh"
+PASS=0
+FAIL=0
+STATE_FILE="/tmp/cc-thinking-stall-last-call"
+LOG_FILE="/tmp/cc-thinking-stalls.log"
+
+setup() {
+    rm -f "$STATE_FILE" "$LOG_FILE"
+}
+
+run_hook() {
+    echo "$1" | CC_STALL_WARN_SECS="${2:-300}" bash "$HOOK" 2>&1 || true
+}
+
+# --- Test 1: First call (no previous state) should not warn ---
+setup
+output=$(echo '{"tool_name":"Read"}' | CC_STALL_WARN_SECS=300 bash "$HOOK" 2>&1) || true
+if echo "$output" | grep -q "stall"; then
+    echo "  FAIL: first call should not warn"
+    FAIL=$((FAIL + 1))
+else
+    echo "  PASS: first call does not warn"
+    PASS=$((PASS + 1))
+fi
+
+# --- Test 2: Quick successive calls should not warn ---
+setup
+echo '{"tool_name":"Read"}' | CC_STALL_WARN_SECS=300 bash "$HOOK" 2>/dev/null || true
+sleep 1
+output=$(echo '{"tool_name":"Write"}' | CC_STALL_WARN_SECS=300 bash "$HOOK" 2>&1) || true
+if echo "$output" | grep -q "stall"; then
+    echo "  FAIL: quick succession should not warn"
+    FAIL=$((FAIL + 1))
+else
+    echo "  PASS: quick succession does not warn"
+    PASS=$((PASS + 1))
+fi
+
+# --- Test 3: Stall detected with low threshold ---
+setup
+echo '{"tool_name":"Read"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>/dev/null || true
+sleep 2
+output=$(echo '{"tool_name":"Bash"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>&1) || true
+if echo "$output" | grep -qi "stall"; then
+    echo "  PASS: stall detected after threshold"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: should have detected stall after 2s with 1s threshold"
+    echo "    output: $output"
+    FAIL=$((FAIL + 1))
+fi
+
+# --- Test 4: Stall is logged to file ---
+setup
+echo '{"tool_name":"Read"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>/dev/null || true
+sleep 2
+echo '{"tool_name":"Edit"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>/dev/null || true
+if [ -f "$LOG_FILE" ] && grep -q "STALL" "$LOG_FILE"; then
+    echo "  PASS: stall logged to file"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: stall not logged to $LOG_FILE"
+    FAIL=$((FAIL + 1))
+fi
+
+# --- Test 5: Log contains tool name ---
+if [ -f "$LOG_FILE" ] && grep -q "tool=Edit" "$LOG_FILE"; then
+    echo "  PASS: log contains tool name"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: log should contain tool=Edit"
+    FAIL=$((FAIL + 1))
+fi
+
+# --- Test 6: Warning mentions issue number ---
+setup
+echo '{"tool_name":"Read"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>/dev/null || true
+sleep 2
+output=$(echo '{"tool_name":"Glob"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>&1) || true
+if echo "$output" | grep -q "51092"; then
+    echo "  PASS: warning references #51092"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: warning should reference #51092"
+    FAIL=$((FAIL + 1))
+fi
+
+# --- Test 7: After stall, next quick call should not warn ---
+setup
+echo '{"tool_name":"Read"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>/dev/null || true
+sleep 2
+echo '{"tool_name":"Edit"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>/dev/null || true
+output=$(echo '{"tool_name":"Write"}' | CC_STALL_WARN_SECS=300 bash "$HOOK" 2>&1) || true
+if echo "$output" | grep -q "stall"; then
+    echo "  FAIL: should not warn on quick follow-up after stall"
+    FAIL=$((FAIL + 1))
+else
+    echo "  PASS: no false positive after stall recovery"
+    PASS=$((PASS + 1))
+fi
+
+# --- Test 8: Hook always exits 0 (never blocks) ---
+setup
+echo '{"tool_name":"Read"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>/dev/null || true
+sleep 2
+echo '{"tool_name":"Bash"}' | CC_STALL_WARN_SECS=1 bash "$HOOK" 2>/dev/null
+rc=$?
+if [ "$rc" -eq 0 ]; then
+    echo "  PASS: hook exits 0 (warn-only, never blocks)"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: hook should always exit 0, got $rc"
+    FAIL=$((FAIL + 1))
+fi
+
+# --- Test 9: Empty tool name handled gracefully ---
+setup
+output=$(echo '{}' | CC_STALL_WARN_SECS=300 bash "$HOOK" 2>&1) || true
+rc=$?
+if [ "$rc" -eq 0 ]; then
+    echo "  PASS: empty tool name handled"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: should handle empty tool name gracefully"
+    FAIL=$((FAIL + 1))
+fi
+
+# --- Test 10: Custom log path ---
+setup
+CUSTOM_LOG="/tmp/cc-stall-custom-test.log"
+rm -f "$CUSTOM_LOG"
+echo '{"tool_name":"Read"}' | CC_STALL_WARN_SECS=1 CC_STALL_LOG="$CUSTOM_LOG" bash "$HOOK" 2>/dev/null || true
+sleep 2
+echo '{"tool_name":"Write"}' | CC_STALL_WARN_SECS=1 CC_STALL_LOG="$CUSTOM_LOG" bash "$HOOK" 2>/dev/null || true
+if [ -f "$CUSTOM_LOG" ] && grep -q "STALL" "$CUSTOM_LOG"; then
+    echo "  PASS: custom log path works"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: custom log path not working"
+    FAIL=$((FAIL + 1))
+fi
+rm -f "$CUSTOM_LOG"
+
+# --- Summary ---
+echo ""
+echo "Results: $PASS passed, $FAIL failed out of $((PASS + FAIL))"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1