cc-safe-setup 29.6.32 → 29.6.36

package/examples/spec-file-scope-guard.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# spec-file-scope-guard.sh — Restrict edits to files mentioned in a spec document
+#
+# Solves: Agent ignoring specification across multiple sessions (#40383).
+#         Claude modifies files not mentioned in the spec, introduces
+#         fabricated data, and drifts from the stated objective.
+#
+# How it works: Reads a spec/requirements file, extracts file paths and
+#   directory names mentioned in it, then blocks Edit/Write to files
+#   outside that scope.
+#
+# Setup:
+#   echo "spec.md" > .claude/spec-file.txt
+#   # Or set CC_SPEC_FILE=spec.md
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit|Write"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+case "$TOOL" in
+  Edit|Write) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+# Find spec file
+SPEC_FILE="${CC_SPEC_FILE:-}"
+if [ -z "$SPEC_FILE" ] && [ -f ".claude/spec-file.txt" ]; then
+    SPEC_FILE=$(head -1 ".claude/spec-file.txt" | tr -d '\n')
+fi
+[ -z "$SPEC_FILE" ] && exit 0
+[ -f "$SPEC_FILE" ] || exit 0
+
+# Extract paths/directories mentioned in spec
+# Matches: path/to/file.ext, src/components/, ./config.ts, etc.
+MENTIONED=$(grep -oE '(\.?/?[a-zA-Z0-9_-]+/)+[a-zA-Z0-9_.-]*' "$SPEC_FILE" | sort -u || true)
+
+if [ -z "$MENTIONED" ]; then
+    # No paths found in spec — don't restrict
+    exit 0
+fi
+
+# Check if the target file matches any mentioned path
+BASENAME=$(basename "$FILE")
+DIRNAME=$(dirname "$FILE")
+
+for path in $MENTIONED; do
+    # Match if file path contains the spec path
+    if echo "$FILE" | grep -qF "$path"; then
+        exit 0
+    fi
+    # Match if basename matches
+    if echo "$BASENAME" | grep -qF "$path"; then
+        exit 0
+    fi
+done
+
+echo "WARNING: Editing file not mentioned in spec ($SPEC_FILE):" >&2
+echo "  File: $FILE" >&2
+echo "  Spec mentions: $(echo "$MENTIONED" | head -5 | tr '\n' ', ')" >&2
+echo "  Stay focused on the specification." >&2
+# Warning only — change to exit 2 to block
+exit 0

package/examples/spring-profile-guard.sh

@@ -1,3 +1,5 @@
+#
+# TRIGGER: PreToolUse  MATCHER: "Edit|Write"
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [[ -z "$COMMAND" ]] && exit 0

package/examples/sql-injection-detect.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+#
+# TRIGGER: PreToolUse  MATCHER: "Edit|Write"
 INPUT=$(cat)
 CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty' 2>/dev/null)
 [ -z "$CONTENT" ] && exit 0

package/examples/subagent-budget-guard.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
 [[ "$TOOL" != "Agent" ]] && exit 0

package/examples/subagent-claudemd-inject.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# subagent-claudemd-inject.sh — Inject CLAUDE.md rules into subagent prompts
+#
+# Solves: Subagents lose CLAUDE.md context since v2.1.84 (#40459).
+#         omitClaudeMd:true strips project instructions from Explore/Plan agents,
+#         causing them to ignore language preferences, environment config, etc.
+#
+# How it works: PreToolUse hook on Agent that appends key CLAUDE.md rules
+#   to the subagent's prompt. Extracts critical rules (marked with SUBAGENT:
+#   prefix in CLAUDE.md) and injects them into the agent description/prompt.
+#
+# Setup: Mark critical rules in CLAUDE.md with "SUBAGENT:" prefix:
+#   ## SUBAGENT: Always respond in Japanese
+#   ## SUBAGENT: Use DEV environment for testing
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" = "Agent" ] || exit 0
+
+# Find CLAUDE.md
+CLAUDEMD=""
+for candidate in "CLAUDE.md" "../CLAUDE.md" "../../CLAUDE.md"; do
+    if [ -f "$candidate" ]; then
+        CLAUDEMD="$candidate"
+        break
+    fi
+done
+[ -n "$CLAUDEMD" ] || exit 0
+
+# Extract SUBAGENT-tagged rules
+RULES=$(grep -iE '^##?\s*SUBAGENT:' "$CLAUDEMD" 2>/dev/null | sed 's/^##\?\s*SUBAGENT:\s*//' | head -10 || true)
+[ -z "$RULES" ] && exit 0
+
+# Inject rules as a system message warning
+echo "REMINDER: Project rules from CLAUDE.md (apply to all subagents):" >&2
+echo "$RULES" | while IFS= read -r rule; do
+    echo "  - $rule" >&2
+done
+
+exit 0

package/examples/subagent-context-size-guard.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# subagent-context-size-guard.sh — Warn on thin subagent prompts
+#
+# Solves: Subagents get spawned with minimal context, leading to
+#         poor results because they lack necessary background (#40929).
+#         The parent agent assumes shared context, but each subagent
+#         starts fresh.
+#
+# How it works: Checks Agent tool's prompt parameter length.
+#   If under 100 characters, warns that the prompt may be too thin
+#   for a standalone agent to work effectively.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+
+set -euo pipefail
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
+
+[ -z "$PROMPT" ] && exit 0
+
+LEN=${#PROMPT}
+if [ "$LEN" -lt 100 ]; then
+  echo "WARNING: Agent prompt is only ${LEN} chars. Subagents start with zero context — include enough background for them to work independently." >&2
+fi
+exit 0

package/examples/subagent-tool-call-limiter.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# subagent-tool-call-limiter.sh — Limit total tool calls per session
+#
+# Solves: Subagents making unbounded tool calls (#36727).
+#         One user reported 234 tool calls in 1.5 hours from a single subagent.
+#         Existing rate limiters check frequency, not total count.
+#
+# How it works: PreToolUse hook (all tools) that increments a counter file.
+#   When CC_MAX_TOOL_CALLS (default 200) is reached, blocks further calls.
+#
+# TRIGGER: PreToolUse
+# MATCHER: ""
+
+set -euo pipefail
+
+MAX_CALLS="${CC_MAX_TOOL_CALLS:-200}"
+COUNTER_FILE="/tmp/claude-tool-call-counter-$$"
+
+# Use session-based counter (PID of parent process)
+PPID_FILE="/tmp/claude-tool-call-counter-${PPID:-0}"
+[ -f "$PPID_FILE" ] && COUNTER_FILE="$PPID_FILE"
+
+# Initialize or read counter
+if [ -f "$COUNTER_FILE" ]; then
+  COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+else
+  COUNT=0
+  COUNTER_FILE="$PPID_FILE"
+fi
+
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+# Check limit
+if [ "$COUNT" -gt "$MAX_CALLS" ]; then
+  echo "BLOCKED: Tool call limit reached ($COUNT/$MAX_CALLS)." >&2
+  echo "This session has made $COUNT tool calls (limit: $MAX_CALLS)." >&2
+  echo "Consider starting a new session or increasing CC_MAX_TOOL_CALLS." >&2
+  exit 2
+fi
+
+# Warn at 80%
+WARN_AT=$((MAX_CALLS * 80 / 100))
+if [ "$COUNT" -eq "$WARN_AT" ]; then
+  echo "WARNING: $COUNT/$MAX_CALLS tool calls used (80%). Consider wrapping up." >&2
+fi
+
+exit 0

package/examples/svelte-lint-on-edit.sh

@@ -1,3 +1,5 @@
+#
+# TRIGGER: PostToolUse  MATCHER: "Edit|Write"
 INPUT=$(cat)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
 [[ -z "$FILE" ]] && exit 0

package/examples/swift-build-on-edit.sh

@@ -17,6 +17,8 @@
 #   }
 # }
 # ================================================================
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)

package/examples/symlink-protect.sh

@@ -0,0 +1,12 @@
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+[[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]] && exit 0
+if [ -L "$FILE" ]; then
+    TARGET=$(readlink -f "$FILE")
+    echo "NOTE: Redirecting write from symlink $FILE → $TARGET" >&2
+    echo "{\"updatedInput\":{\"file_path\":\"$TARGET\"}}"
+    exit 1
+fi
+exit 0

package/examples/system-message-workaround.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# system-message-workaround.sh — Ensure hook warnings reach both user and model
+#
+# Solves: PreToolUse/PostToolUse systemMessage silently dropped (#40380).
+#         When a hook returns only systemMessage (without hookSpecificOutput),
+#         the warning is invisible to both user and model.
+#
+# How it works: Template hook that demonstrates the correct pattern for
+#   sending warnings that are visible. Uses stderr for user visibility
+#   AND hookSpecificOutput.systemMessage for model context injection.
+#
+# Usage: Copy and adapt this pattern for your custom warn hooks.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Example: warn on dangerous-looking but not blocked commands
+WARNING=""
+
+if echo "$COMMAND" | grep -qE 'DROP\s+TABLE|TRUNCATE\s+TABLE'; then
+    WARNING="Database destructive operation detected: $COMMAND"
+elif echo "$COMMAND" | grep -qE 'curl.*-X\s*(DELETE|PUT|PATCH)'; then
+    WARNING="Destructive HTTP method detected: $COMMAND"
+fi
+
+if [ -n "$WARNING" ]; then
+    # Method 1: stderr — always visible to the user in terminal
+    echo "⚠ WARNING: $WARNING" >&2
+
+    # Method 2: hookSpecificOutput with systemMessage — visible to model
+    # This is the workaround for #40380: include hookSpecificOutput
+    # to ensure the systemMessage is actually processed
+    cat << ENDJSON
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","decision":"allow","systemMessage":"WARNING: $WARNING. Proceed with caution."}}
+ENDJSON
+fi
+
+exit 0

package/examples/system-package-guard.sh

@@ -21,6 +21,8 @@
 #   }
 # }
 # ================================================================
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/temp-file-cleanup-stop.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# temp-file-cleanup-stop.sh — Clean up tmpclaude-* files on session end
+#
+# Solves: Claude Code creates tmpclaude-{hash}-cwd temporary
+#         files in the working directory but doesn't clean them
+#         up after the session ends (#17720). These accumulate
+#         over time and clutter the project.
+#
+# How it works: On Stop event, finds and removes all
+#   tmpclaude-*-cwd files in the current directory and /tmp.
+#   Only removes files matching the exact pattern to avoid
+#   deleting user files.
+#
+# TRIGGER: Stop
+# MATCHER: ""
+
+set -euo pipefail
+
+# Clean up tmpclaude-* files in current directory
+find . -maxdepth 1 -name "tmpclaude-*-cwd" -type f -delete 2>/dev/null || true
+
+# Also clean up in /tmp
+find /tmp -maxdepth 1 -name "tmpclaude-*" -type f -mmin +60 -delete 2>/dev/null || true
+
+# Clean up any .claude-tmp-* files too
+find . -maxdepth 1 -name ".claude-tmp-*" -type f -delete 2>/dev/null || true
+
+exit 0

package/examples/temp-file-cleanup.sh

@@ -21,6 +21,8 @@
 # }
 
 # Count before cleanup
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 COUNT=$(find /tmp -maxdepth 1 -name "claude-*" -type f 2>/dev/null | wc -l)
 
 if [ "$COUNT" -eq 0 ]; then

package/examples/terminal-state-restore.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# terminal-state-restore — restore terminal to clean state on session exit
+# Fixes: bracketed paste mode, application cursor keys, cursor visibility,
+#        line wrapping, Kitty keyboard protocol left enabled after exit.
+# Event: Notification (matcher: "stop")
+# Related: https://github.com/anthropics/claude-code/issues/39272
+
+# Reset bracketed paste mode
+printf '\e[?2004l'
+# Reset application cursor keys to normal mode
+printf '\e[?1l'
+# Ensure cursor is visible
+printf '\e[?25h'
+# Re-enable line wrapping
+printf '\e[?7h'
+# Disable Kitty keyboard protocol (if enabled)
+printf '\e[>0u' 2>/dev/null
+# Reset character set to default
+printf '\e(B'
+# Restore default SGR (color/style reset)
+printf '\e[0m'
+
+exit 0

package/examples/test-after-edit.sh

@@ -21,6 +21,8 @@
 #   }
 # }
 # ================================================================
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)

package/examples/test-before-commit.sh

@@ -1,18 +1,17 @@
 #!/bin/bash
-COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
-echo "$COMMAND" | grep -qE '^\s*git\s+commit' || exit 0
-RECENT=0
-TIMEOUT=${CC_TEST_TIMEOUT:-600}
-NOW=$(date +%s)
-for marker in coverage/.last-run.json test-results .nyc_output junit.xml; do
-    [ -e "$marker" ] || continue
-    MTIME=$(stat -c %Y "$marker" 2>/dev/null || echo 0)
-    [ $((NOW - MTIME)) -lt "$TIMEOUT" ] && RECENT=1 && break
-done
-if [ "$RECENT" -eq 0 ]; then
-    echo "BLOCKED: No recent test results (within $((TIMEOUT/60)) min)" >&2
-    echo "Run your test suite first, then commit." >&2
-    exit 2
+STATE="/tmp/cc-tests-ran-$$"
+if echo "$COMMAND" | grep -qE '^\s*(npm\s+test|npx\s+jest|pytest|python\s+-m\s+pytest|cargo\s+test|go\s+test|make\s+test|bundle\s+exec\s+rspec|mix\s+test)'; then
+    echo "1" > "$STATE"
+    exit 0
+fi
+if echo "$COMMAND" | grep -qE '^\s*git\s+commit'; then
+    if [ ! -f "$STATE" ] || [ "$(cat "$STATE" 2>/dev/null)" != "1" ]; then
+        echo "WARNING: No test commands detected since last commit." >&2
+        echo "  Run tests before committing to verify your changes." >&2
+    fi
+    rm -f "$STATE"
 fi
 exit 0

package/examples/test-before-push.sh

@@ -23,6 +23,8 @@
 #
 # The "if" field (v2.1.85+) eliminates process spawning for non-push commands.
 # Without "if", the hook still works — it checks internally and exits early.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/test-exit-code-verify.sh

@@ -17,6 +17,8 @@
 #
 # Why stderr: PostToolUse hook stderr is shown to Claude as feedback.
 # This forces Claude to acknowledge test failures instead of fabricating results.
+#
+# TRIGGER: PostToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 

package/examples/timeout-guard.sh

@@ -15,6 +15,8 @@
 #     }]
 #   }
 # }
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/timezone-guard.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 if echo "$COMMAND" | grep -qE "TZ=|--timezone" && ! echo "$COMMAND" | grep -q "UTC"; then echo "NOTE: Non-UTC timezone in command" >&2; fi

package/examples/tmp-output-size-guard.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# tmp-output-size-guard.sh — Monitor and warn about large tmp output files
+#
+# Solves: Task .output files in /tmp grow unbounded (95GB+) filling disk
+#         (#39909). Subagent output aggregation can create multi-GB files.
+#
+# How it works: Notification/SessionStart hook that checks /tmp for large
+#   Claude Code output files and warns if any exceed a threshold.
+#   Also provides a cleanup command suggestion.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# Usage:
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/tmp-output-size-guard.sh" }]
+#     }]
+#   }
+# }
+
+# Configurable threshold in MB
+THRESHOLD_MB="${CC_TMP_THRESHOLD_MB:-500}"
+
+# Find Claude Code tmp directories
+TMP_BASE="/tmp/claude-$(id -u)"
+[ -d "/private/tmp/claude-$(id -u)" ] && TMP_BASE="/private/tmp/claude-$(id -u)"
+[ ! -d "$TMP_BASE" ] && exit 0
+
+# Find files over threshold
+LARGE_FILES=$(find "$TMP_BASE" -name "*.output" -size "+${THRESHOLD_MB}M" 2>/dev/null)
+[ -z "$LARGE_FILES" ] && exit 0
+
+TOTAL_SIZE=$(echo "$LARGE_FILES" | xargs du -sh 2>/dev/null | awk '{sum+=$1} END {print sum}')
+FILE_COUNT=$(echo "$LARGE_FILES" | wc -l | tr -d ' ')
+
+echo "⚠ Found $FILE_COUNT large task output file(s) in $TMP_BASE (>${THRESHOLD_MB}MB each):" >&2
+echo "$LARGE_FILES" | while read f; do
+    SIZE=$(du -sh "$f" 2>/dev/null | cut -f1)
+    echo "  $SIZE  $(basename "$f")" >&2
+done
+echo "" >&2
+echo "To clean up: find $TMP_BASE -name '*.output' -size +${THRESHOLD_MB}M -delete" >&2
+
+exit 0

package/examples/todo-check.sh

@@ -14,6 +14,8 @@
 #     }]
 #   }
 # }
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/todo-deadline-warn.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# ================================================================
+# todo-deadline-warn.sh — Warn about expired TODO deadlines in edited files
+# ================================================================
+# PURPOSE:
+#   TODOs with dates (e.g., "TODO(2026-03-01): fix this") are often
+#   forgotten. When Claude edits a file containing expired TODOs,
+#   this hook warns so they can be addressed while the file is open.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Edit|Write"
+#
+# DECISION: Advisory only (exit 0). Warns via stderr.
+# ================================================================
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+
+# Skip non-code files
+case "$FILE" in
+    *.md|*.txt|*.json|*.yaml|*.yml|*.toml|*.xml|*.html|*.css) exit 0 ;;
+esac
+
+TODAY=$(date +%Y-%m-%d)
+EXPIRED=0
+
+# Find TODO/FIXME/HACK with dates like TODO(2026-03-01) or TODO 2026-03-01
+while IFS= read -r line; do
+    # Extract date from patterns like TODO(2026-01-15) or FIXME 2026-01-15
+    DATE=$(echo "$line" | grep -oE '(TODO|FIXME|HACK|XXX)\s*\(?\s*[0-9]{4}-[0-9]{2}-[0-9]{2}' | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}')
+    if [ -n "$DATE" ] && [[ "$DATE" < "$TODAY" ]]; then
+        if [ "$EXPIRED" -eq 0 ]; then
+            echo "⚠ Expired TODOs in $(basename "$FILE"):" >&2
+        fi
+        LINENUM=$(echo "$line" | cut -d: -f1)
+        CONTENT=$(echo "$line" | cut -d: -f2- | sed 's/^[[:space:]]*//')
+        echo "  L${LINENUM}: $CONTENT (expired: $DATE)" >&2
+        EXPIRED=$((EXPIRED + 1))
+    fi
+done < <(grep -n -E '(TODO|FIXME|HACK|XXX).*[0-9]{4}-[0-9]{2}-[0-9]{2}' "$FILE" 2>/dev/null)
+
+if [ "$EXPIRED" -gt 0 ]; then
+    echo "  $EXPIRED expired TODO(s) — consider resolving while editing this file." >&2
+fi
+
+exit 0

package/examples/token-budget-per-task.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# token-budget-per-task.sh — Track and warn on per-task token usage
+#
+# Solves: A single task consuming the entire daily token budget.
+#         Without visibility into per-task costs, users don't realize
+#         until they hit rate limits.
+#
+# How it works: PostToolUse hook that estimates tokens per tool call
+#   and tracks cumulative usage. Warns at configurable thresholds.
+#
+# CONFIG:
+#   CC_TOKEN_WARN_THRESHOLD=50000 (warn at this many tokens)
+#   CC_TOKEN_BLOCK_THRESHOLD=200000 (block at this many tokens)
+#
+# TRIGGER: PostToolUse
+# MATCHER: ""
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ -z "$TOOL" ] && exit 0
+
+COUNTER_FILE="/tmp/claude-token-budget-${PPID:-0}"
+WARN="${CC_TOKEN_WARN_THRESHOLD:-50000}"
+BLOCK="${CC_TOKEN_BLOCK_THRESHOLD:-200000}"
+
+# Rough token estimates per tool call
+case "$TOOL" in
+    Bash) TOKENS=500 ;;
+    Read) TOKENS=2000 ;;
+    Edit|Write) TOKENS=1000 ;;
+    Glob|Grep) TOKENS=300 ;;
+    Agent) TOKENS=5000 ;;
+    *) TOKENS=200 ;;
+esac
+
+# Add result size estimate
+RESULT_LEN=$(echo "$INPUT" | jq -r '.tool_result // "" | length' 2>/dev/null || echo 0)
+TOKENS=$((TOKENS + RESULT_LEN / 4))  # ~4 chars per token
+
+# Update counter
+TOTAL=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+TOTAL=$((TOTAL + TOKENS))
+echo "$TOTAL" > "$COUNTER_FILE"
+
+if [ "$TOTAL" -ge "$BLOCK" ]; then
+    echo "TOKEN BUDGET: ~${TOTAL} tokens used in this task (limit: ${BLOCK})." >&2
+    echo "Consider breaking this into smaller tasks." >&2
+    # Warning only — change to exit 2 to block
+elif [ "$TOTAL" -ge "$WARN" ]; then
+    echo "TOKEN BUDGET: ~${TOTAL} tokens used (warning threshold: ${WARN})." >&2
+fi
+
+exit 0

package/examples/token-spike-alert.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# token-spike-alert.sh — Alert on abnormal token consumption per turn
+#
+# Solves: Users report 10-20% of their 5-hour quota consumed by
+#         a single lightweight question (#40524, #38029, #40881).
+#         Cache invalidation causes full context re-processing,
+#         spiking token usage without user awareness.
+#
+# How it works: Tracks tool call count per session via a counter
+#   file. If more than MAX_TOOLS_PER_TURN tool calls happen in
+#   rapid succession (within 30 seconds), warns about possible
+#   runaway behavior that could spike token usage.
+#
+# TRIGGER: PostToolUse
+# MATCHER: ""
+
+set -euo pipefail
+
+COUNTER_FILE="/tmp/claude-token-spike-$$"
+MAX_TOOLS_PER_BURST="${MAX_TOOLS_PER_BURST:-15}"
+
+# Get current timestamp
+NOW=$(date +%s)
+
+# Read last timestamp and count
+if [ -f "$COUNTER_FILE" ]; then
+  LAST_TS=$(head -1 "$COUNTER_FILE" 2>/dev/null || echo "0")
+  COUNT=$(tail -1 "$COUNTER_FILE" 2>/dev/null || echo "0")
+else
+  LAST_TS=0
+  COUNT=0
+fi
+
+# If within 30-second burst window
+DELTA=$((NOW - LAST_TS))
+if [ "$DELTA" -lt 30 ]; then
+  COUNT=$((COUNT + 1))
+else
+  COUNT=1
+fi
+
+# Save state
+echo "$NOW" > "$COUNTER_FILE"
+echo "$COUNT" >> "$COUNTER_FILE"
+
+# Alert if burst detected
+if [ "$COUNT" -ge "$MAX_TOOLS_PER_BURST" ]; then
+  echo "WARNING: $COUNT tool calls in ${DELTA}s burst. Possible runaway behavior — check token consumption." >&2
+fi
+
+exit 0