cc-safe-setup 29.7.0 → 30.0.4

package/examples/parallel-batch-size-limiter.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# ================================================================
+# parallel-batch-size-limiter.sh — Surface large parallel batches
+# ================================================================
+# PURPOSE:
+#   The companion to parallel-cascade-detector.sh (which fires
+#   POST-cascade). This PRE-batch hook detects when a single
+#   assistant turn is firing many tool calls in quick succession
+#   (within a configurable batch window) and warns the operator
+#   BEFORE the batch can cascade.
+#
+#   Why: a single failed tool call in a parallel batch cancels every
+#   sibling call (Issue #64059 / #64052 / #64047). Larger batches
+#   have larger cascade blast-radius. Capping batch size from the
+#   operator side keeps cascade radius small while the upstream
+#   "fan-out, continue on partial failure" semantic is still pending.
+#
+# DETECTION MODEL:
+#   PreToolUse fires per tool call. Same-batch parallel calls fire in
+#   quick succession (default within 500ms). This hook records each
+#   call's timestamp; on each new fire, it counts calls in the rolling
+#   batch window and warns when the count crosses a configurable
+#   threshold.
+#
+# CLUSTER:
+#   Candidate cluster #20 — parallel tool batch cancellation cascade
+#   Same cluster as parallel-cascade-detector.sh (PostToolUse companion).
+#
+# TRIGGER: PreToolUse  MATCHER: ""
+#
+# ENV:
+#   CC_PARALLEL_BATCH_LIMITER_THRESHOLD     default 6  (warn at 6+ siblings)
+#   CC_PARALLEL_BATCH_LIMITER_WINDOW_MS     default 500
+#   CC_PARALLEL_BATCH_LIMITER_DISABLE       non-empty → silent
+#   CC_PARALLEL_BATCH_LIMITER_QUIET         non-empty → silent
+#   CC_PARALLEL_BATCH_LIMITER_STATE_DIR     default /tmp/cc-parallel-batch
+# ================================================================
+
+set -u
+
+# Disable / quiet
+if [ -n "${CC_PARALLEL_BATCH_LIMITER_DISABLE:-}" ] || [ -n "${CC_PARALLEL_BATCH_LIMITER_QUIET:-}" ]; then
+    exit 0
+fi
+
+THRESHOLD="${CC_PARALLEL_BATCH_LIMITER_THRESHOLD:-6}"
+WINDOW_MS="${CC_PARALLEL_BATCH_LIMITER_WINDOW_MS:-500}"
+STATE_DIR="${CC_PARALLEL_BATCH_LIMITER_STATE_DIR:-/tmp/cc-parallel-batch}"
+LOG_FILE="$STATE_DIR/batch.log"
+WARN_FILE="$STATE_DIR/last-warn"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+
+# Read input (don't fail if jq missing — just exit silently)
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+# Current time in milliseconds (portable across GNU and BSD date)
+NOW_MS=$(date +%s%3N 2>/dev/null)
+if [ -z "$NOW_MS" ] || [ "${#NOW_MS}" -lt 13 ]; then
+    # macOS / BSD date doesn't support %N — fall back to seconds * 1000
+    NOW_S=$(date +%s)
+    NOW_MS=$((NOW_S * 1000))
+fi
+
+# Record this fire
+printf '%s\n' "$NOW_MS" >> "$LOG_FILE"
+
+# Compute cutoff (NOW - WINDOW_MS)
+CUTOFF=$((NOW_MS - WINDOW_MS))
+
+# Count events in window and prune old entries
+COUNT=0
+TMP_LOG=$(mktemp)
+while IFS= read -r ts; do
+    # Skip malformed entries
+    case "$ts" in
+        ''|*[!0-9]*) continue ;;
+    esac
+    if [ "$ts" -ge "$CUTOFF" ] 2>/dev/null; then
+        printf '%s\n' "$ts" >> "$TMP_LOG"
+        COUNT=$((COUNT + 1))
+    fi
+done < "$LOG_FILE"
+mv "$TMP_LOG" "$LOG_FILE" 2>/dev/null
+
+# Warn only when threshold is freshly crossed (debounce repeat warnings within
+# the same batch — checking last-warn timestamp).
+if [ "$COUNT" -ge "$THRESHOLD" ]; then
+    LAST_WARN=0
+    if [ -f "$WARN_FILE" ]; then
+        LAST_WARN=$(cat "$WARN_FILE" 2>/dev/null || echo 0)
+    fi
+    # Only warn if last warning was outside the current batch window
+    if [ "$LAST_WARN" -lt "$CUTOFF" ] 2>/dev/null; then
+        printf '%s' "$NOW_MS" > "$WARN_FILE"
+        cat >&2 <<EOF
+
+⚠️  Large parallel batch detected: $COUNT tool calls in the last ${WINDOW_MS}ms.
+
+What this means:
+  A single failed tool call in this batch will cancel every sibling
+  call with "Cancelled: parallel tool call X errored" (Issue #64059
+  / #64052 / #64047). Larger batches have larger cascade radius.
+  The model may then misattribute the cascade to a user interrupt
+  and fabricate user statements that never happened.
+
+Recommended:
+  Cap parallel batches at N=3-5 in CLAUDE.md guidance.
+  Common non-fatal triggers to keep OUT of parallel batches:
+    - git with potentially-invalid revisions (exit 128)
+    - curl probes expected to return 404
+    - pkill with nothing matching (exit 144)
+
+Tracking: cc-safe-setup candidate cluster #20.
+Defense companion: parallel-cascade-detector.sh (PostToolUse).
+EOF
+    fi
+fi
+
+exit 0

package/examples/parallel-cascade-detector.sh

@@ -0,0 +1,116 @@
+#!/bin/bash
+# ================================================================
+# parallel-cascade-detector.sh — Detect parallel-batch cascade
+# ================================================================
+# PURPOSE:
+#   When Claude Code sends parallel tool calls in a single assistant
+#   turn and one of them errors, all sibling calls are cancelled with
+#   "Cancelled: parallel tool call X errored" — even when the failure
+#   is non-fatal (exit 144 from pkill, expected 404 from curl,
+#   invalid git revision, etc.).
+#
+#   Two problems:
+#   1. The whole batch's compute is wasted (40-100K tokens / cascade).
+#   2. The cancellation message is indistinguishable from a user
+#      interrupt, so the model itself can misattribute the cascade
+#      to user action and fabricate user statements ("You're right
+#      to stop me…") — see Issue #64047.
+#
+#   This hook counts cascade events in a rolling time window and
+#   warns when the count crosses a configurable threshold. It does
+#   NOT prevent cascades (the policy is upstream) — it surfaces them
+#   so operators can recognize the pattern and restructure batches.
+#
+# CLUSTER:
+#   Candidate cluster #20 — parallel tool batch cancellation cascade
+#   3 independent reports on 2026-05-30:
+#   - #64059 (enrico2468) - confirmed behavior across long sessions
+#   - #64052 (omar16100) - minimal reproduction on v2.1.158
+#   - #64047 (snichols) - the indistinguishability + fabrication
+#
+# TRIGGER: PostToolUse  MATCHER: ""
+#
+# ENV:
+#   CC_PARALLEL_CASCADE_THRESHOLD   default 5
+#   CC_PARALLEL_CASCADE_WINDOW_SEC  default 60
+#   CC_PARALLEL_CASCADE_DISABLE     non-empty → silent
+#   CC_PARALLEL_CASCADE_QUIET       non-empty → silent
+#   CC_PARALLEL_CASCADE_STATE_DIR   default /tmp/cc-parallel-cascade
+# ================================================================
+
+set -u
+
+# Disable / quiet
+if [ -n "${CC_PARALLEL_CASCADE_DISABLE:-}" ] || [ -n "${CC_PARALLEL_CASCADE_QUIET:-}" ]; then
+    exit 0
+fi
+
+THRESHOLD="${CC_PARALLEL_CASCADE_THRESHOLD:-5}"
+WINDOW_SEC="${CC_PARALLEL_CASCADE_WINDOW_SEC:-60}"
+STATE_DIR="${CC_PARALLEL_CASCADE_STATE_DIR:-/tmp/cc-parallel-cascade}"
+LOG_FILE="$STATE_DIR/events.log"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+
+INPUT=$(cat)
+
+# Extract tool_response (cancellation message lives here)
+RESPONSE=$(printf '%s' "$INPUT" | jq -r '.tool_response // .tool_result // empty' 2>/dev/null)
+
+# Some Claude Code versions wrap tool_response as an object; try common nested fields
+if [ -z "$RESPONSE" ]; then
+    RESPONSE=$(printf '%s' "$INPUT" | jq -r '.tool_response.output // .tool_response.error // .tool_response.text // empty' 2>/dev/null)
+fi
+
+# If no response at all, nothing to count
+[ -z "$RESPONSE" ] && exit 0
+
+# Detect the cascade signature
+# Pattern: "Cancelled: parallel tool call X errored" (case-insensitive on cancelled)
+if printf '%s' "$RESPONSE" | grep -qiE 'Cancelled:[[:space:]]+parallel tool call[[:space:]]+.*errored'; then
+    NOW=$(date +%s)
+    # Append event timestamp
+    printf '%s\n' "$NOW" >> "$LOG_FILE"
+
+    # Compute cutoff
+    CUTOFF=$((NOW - WINDOW_SEC))
+
+    # Count events within window and rewrite log to prune old entries
+    COUNT=0
+    TMP_LOG=$(mktemp)
+    while IFS= read -r ts; do
+        if [ "$ts" -ge "$CUTOFF" ] 2>/dev/null; then
+            printf '%s\n' "$ts" >> "$TMP_LOG"
+            COUNT=$((COUNT + 1))
+        fi
+    done < "$LOG_FILE"
+    mv "$TMP_LOG" "$LOG_FILE" 2>/dev/null
+
+    # Warn at threshold
+    if [ "$COUNT" -ge "$THRESHOLD" ]; then
+        cat >&2 <<EOF
+
+⚠️  Parallel-batch cascade detected: $COUNT cancellation events in the last ${WINDOW_SEC}s.
+
+What this means:
+  A single failed tool call in a parallel batch cancels every sibling
+  call with "Cancelled: parallel tool call X errored". The model can
+  misattribute these cancellations to a user interrupt and may
+  fabricate user statements that never happened. See Issue #64047
+  for a worked example (25-call cascade → 2-hour fabricated user
+  state, zero actual user input).
+
+Operator-side mitigation today:
+  1. Reduce parallel batch size to N=3-5 via CLAUDE.md guidance.
+  2. Audit transcripts:
+       grep -c "parallel tool call.*errored" ~/.claude/projects/*/recent.jsonl
+  3. Avoid git / curl / pkill in parallel batches when the
+     failure-on-empty case is common — they are the 3 most-cited
+     cascade triggers in the cluster reports (#64059 / #64052 / #64047).
+
+Tracking: cc-safe-setup candidate cluster #20.
+EOF
+    fi
+fi
+
+exit 0

package/examples/partial-view-claim-arrest.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# partial-view-claim-arrest.sh — Stop the turn when the model claims about
+# the whole file after Read returned a "PARTIAL view" notice.
+#
+# Solves: v2.1.145 (2026-05-19) — "Improved the Read tool to return a
+# truncated first page with a PARTIAL view notice instead of a hard error
+# when a whole-file read exceeds the token limit."
+#
+# The release-note change replaced a hard error (which forced the model to
+# branch) with a partial success + warning notice (which lets the model
+# proceed if it doesn't gate on the notice). The PARTIAL view notice is
+# recognized in the cognition layer but does not reliably propagate to the
+# claim layer: the model emits whole-file claims after seeing only the
+# first page.
+#
+# This hook fires on Stop, inspects the same-turn Read tool outputs for a
+# PARTIAL view notice, and refuses the Stop (exit 2 + system-reminder) if
+# the assistant's response in that same turn contains a whole-file claim.
+#
+# Scoped phrasing exempts: when the model says "the first N lines" or
+# "based on the first page" or "from what I have seen so far", the claim
+# is correctly scoped to the partial view and the hook does not fire.
+#
+# Companion to closure-word-verify-gate.sh (which catches "done" without
+# verification). closure-word-verify-gate.sh covers the action axis;
+# partial-view-claim-arrest.sh covers the partial-context axis. Together
+# they cover two of the three layers of the recognition-without-arrest
+# constellation (#60226).
+#
+# Related Issues:
+#   #60226 (@suwayama, 2026-05-18) — recognition-without-arrest framework
+#   Anthropic v2.1.145 release notes (2026-05-19) — the PARTIAL view change
+#   #60188 (@suwayama)            — binary-collapse sub-hypothesis (a
+#                                   gradient signal — N% of file shown —
+#                                   collapsing to a binary read/not-read
+#                                   in the claim layer)
+#
+# TRIGGER: Stop
+# MATCHER: ""
+#
+# CONFIGURATION (environment variables):
+#   CC_PARTIAL_VIEW_NOTICES   default built-in — regex for the notice
+#                                                  pattern emitted by Read
+#   CC_WHOLE_FILE_CLAIMS      default built-in — regex for whole-file
+#                                                  claim phrases
+#   CC_SCOPED_PHRASING        default built-in — regex for safe phrasing
+#                                                  that exempts the claim
+#   CC_PARTIAL_GATE_DISABLE   set to "1" to disable the gate entirely
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "Stop": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/partial-view-claim-arrest.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+set -uo pipefail
+
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-partial-view-claim-arrest-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [partial-view-claim-arrest]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+[ "${CC_PARTIAL_GATE_DISABLE:-0}" = "1" ] && exit 0
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+# Default patterns. CC_* env vars override.
+# PARTIAL view notice: Read tool result contains the literal marker.
+DEFAULT_NOTICES='PARTIAL[[:space:]]+view|truncated[[:space:]]+first[[:space:]]+page|file[[:space:]]+was[[:space:]]+truncated|showing[[:space:]]+first[[:space:]][0-9]+[[:space:]]+lines[[:space:]]+of'
+
+# Whole-file claim phrases. Used in the model's response after the notice.
+DEFAULT_CLAIMS='\b(the[[:space:]]+entire[[:space:]]+file|the[[:space:]]+whole[[:space:]]+file|the[[:space:]]+complete[[:space:]]+(contents|file)|reviewed[[:space:]]+the[[:space:]]+entire|read[[:space:]]+the[[:space:]]+entire|all[[:space:]]+of[[:space:]]+the[[:space:]]+(imports|functions|definitions|exports)|every[[:space:]]+(function|line|method|definition)[[:space:]]+in[[:space:]]+(the|this)[[:space:]]+file|the[[:space:]]+file[[:space:]]+contains[[:space:]]+everything|all[[:space:]]+files[[:space:]]+were[[:space:]]+read|read[[:space:]]+the[[:space:]]+whole)\b'
+
+# Scoped phrasing that exempts. The model said "first N lines" or "based on
+# the first page" — the claim is correctly scoped to partial view.
+DEFAULT_SCOPED='\b(the[[:space:]]+first[[:space:]][0-9]+[[:space:]]+lines|based[[:space:]]+on[[:space:]]+the[[:space:]]+first[[:space:]]+page|from[[:space:]]+what[[:space:]]+I[[:space:]]+have[[:space:]]+(seen|read)[[:space:]]+so[[:space:]]+far|the[[:space:]]+visible[[:space:]]+portion|the[[:space:]]+partial[[:space:]]+view|partial[[:space:]]+read|truncated[[:space:]]+content|only[[:space:]]+the[[:space:]]+first|need[[:space:]]+to[[:space:]]+read[[:space:]]+the[[:space:]]+rest)\b'
+
+NOTICES="${CC_PARTIAL_VIEW_NOTICES:-$DEFAULT_NOTICES}"
+CLAIMS="${CC_WHOLE_FILE_CLAIMS:-$DEFAULT_CLAIMS}"
+SCOPED="${CC_SCOPED_PHRASING:-$DEFAULT_SCOPED}"
+
+# Stop-hook input shape varies across Claude Code versions; try several keys
+# for assistant text and tool results.
+ASSISTANT_TEXT=$(printf '%s' "$INPUT" | jq -r '
+    .transcript[-1].content //
+    .last_assistant_message //
+    .stop_input.assistant_text //
+    .assistant_message //
+    empty
+' 2>/dev/null)
+
+# Tool results in the same turn (Read tool outputs we want to scan for
+# PARTIAL view notices). Multiple harness shapes are tried.
+TURN_TOOL_RESULTS=$(printf '%s' "$INPUT" | jq -r '
+    [ .turn_tool_results[]?.content,
+      .turn_tool_calls[]?.result,
+      .transcript[-1].tool_results[]?.content,
+      .recent_tool_results[]?,
+      .last_turn_tool_results[]?
+    ] | map(select(. != null)) | .[]
+' 2>/dev/null || true)
+
+# If we cannot find the assistant text, the harness shape differs and we
+# refuse to false-positive — exit silently.
+[ -z "$ASSISTANT_TEXT" ] && exit 0
+
+# Check for PARTIAL view notice in the same-turn tool results.
+if [ -z "$TURN_TOOL_RESULTS" ] || ! printf '%s' "$TURN_TOOL_RESULTS" | grep -Eiq "$NOTICES"; then
+    # No PARTIAL view notice was emitted this turn — nothing to gate.
+    exit 0
+fi
+
+# PARTIAL view present. Did the assistant make a whole-file claim?
+if ! printf '%s' "$ASSISTANT_TEXT" | grep -Eiq "$CLAIMS"; then
+    # No whole-file claim — the model gated correctly.
+    exit 0
+fi
+
+# Whole-file claim present. Did the assistant also scope it correctly?
+# Scoped phrasing in the same response exempts the claim.
+if printf '%s' "$ASSISTANT_TEXT" | grep -Eiq "$SCOPED"; then
+    # The model scoped its claim. Allow the Stop.
+    exit 0
+fi
+
+# PARTIAL view + whole-file claim + no scoped phrasing → block the Stop.
+MATCHED_CLAIM=$(printf '%s' "$ASSISTANT_TEXT" | grep -Eio "$CLAIMS" | head -1)
+MATCHED_NOTICE=$(printf '%s' "$TURN_TOOL_RESULTS" | grep -Eio "$NOTICES" | head -1)
+
+cat >&2 <<EOF
+<system-reminder>
+PARTIAL VIEW + WHOLE-FILE CLAIM — the Read tool returned "$MATCHED_NOTICE"
+this turn (the file exceeded the token limit and only the first page was
+returned), but the assistant's response makes a whole-file claim:
+"$MATCHED_CLAIM".
+
+This is the v2.1.145 soft-upgrade failure surface: the harness replaced a
+hard error (which forced the model to branch) with a partial success notice
+that is recognized but does not reliably bind the claim layer.
+
+Before ending this turn, do one of:
+
+  1. Re-read the rest of the file with an explicit offset (Read with
+     offset=N where N is past the truncation point), then re-state the
+     claim with full coverage, OR
+  2. Replace the whole-file claim with a scoped phrasing — "the first N
+     lines of <file>" or "based on the visible portion" or "from what I
+     have seen so far" — so the operator knows the claim is limited to
+     the partial view, OR
+  3. Acknowledge explicitly that the rest of the file has not been read
+     and ask the operator whether to continue with the partial coverage.
+
+To disable this gate intentionally (for documentation work where partial
+file references are acceptable), set CC_PARTIAL_GATE_DISABLE=1 in your
+environment.
+</system-reminder>
+EOF
+
+exit 2

package/examples/path-deny-bash-guard.sh

@@ -17,6 +17,18 @@
 # TRIGGER: PreToolUse
 # MATCHER: "Bash"
 
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-path-deny-bash-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [path-deny-bash-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0

package/examples/path-traversal-guard.sh

@@ -18,6 +18,18 @@
 #
 # TRIGGER: PreToolUse  MATCHER: "Bash"
 
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-path-traversal-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [path-traversal-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 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)

package/examples/per-prompt-token-cap.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+# ================================================================
+# per-prompt-token-cap.sh — Detect single-prompt quota burnout
+# ================================================================
+# PURPOSE:
+#   Detect when a single user prompt is consuming an outsized
+#   fraction of the 5-hour quota. The May 2026 cluster around
+#   Issue #56297 documented eight reports where one prompt drove
+#   the 5-hour quota to 100% before any output was produced.
+#   The pattern is invisible to session-cumulative budget guards
+#   (token-budget-guard, daily-cost-guard) and to rapid-tool-call
+#   detectors (token-spike-alert) because the prompt may make
+#   only a handful of tool calls while consuming millions of
+#   input tokens via re-reads, sub-agent invocations, or long
+#   thinking chains.
+#
+#   This hook reads the session transcript for the boundary of
+#   the most recent user prompt and sums the input_tokens across
+#   the assistant turns that have followed. If the sum exceeds
+#   PER_PROMPT_TOKEN_CAP, the hook emits a warning to stderr.
+#
+# TRIGGER: PostToolUse  MATCHER: ""
+#
+# CONFIG:
+#   PER_PROMPT_TOKEN_CAP=1000000   (warn at 1M input tokens)
+#   PER_PROMPT_TOKEN_BLOCK=0       (0 = warn-only; set positive to block)
+#
+# Born from: https://github.com/anthropics/claude-code/issues/56297
+#   plus #56276 #56293 #56292 #56265 #56259 #56252 #56239
+#   (May 5 2026 cluster — 8 issues filed in a 6-hour window)
+# ================================================================
+
+set -euo pipefail
+
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-per-prompt-token-cap-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [per-prompt-token-cap]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+WARN_CAP="${PER_PROMPT_TOKEN_CAP:-1000000}"
+BLOCK_CAP="${PER_PROMPT_TOKEN_BLOCK:-0}"
+
+# Read JSON input from stdin (hook input format)
+INPUT=$(cat)
+
+# Extract transcript_path from the hook input
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+
+# If no transcript path, exit silently (no measurement possible)
+[ -z "$TRANSCRIPT" ] && exit 0
+[ ! -f "$TRANSCRIPT" ] && exit 0
+
+# Walk the transcript backward to find the boundary of the latest user prompt.
+# The transcript is JSONL where each line is one turn. We sum input_tokens
+# from assistant turns occurring after the most recent user turn.
+#
+# tac reverses lines so we encounter the latest entries first; we accumulate
+# input_tokens from assistant lines and stop when we hit a user line.
+#
+# Schema reference: each line has .type ("user"|"assistant"|"system"|...)
+# and assistant lines have .message.usage.input_tokens (cache_creation +
+# cache_read + raw input). We sum the total input load.
+
+CURRENT_PROMPT_TOKENS=$(tac "$TRANSCRIPT" 2>/dev/null | awk '
+  BEGIN { sum = 0 }
+  {
+    # Stop when we encounter the most recent user turn
+    if ($0 ~ /"type"[[:space:]]*:[[:space:]]*"user"/) { exit }
+    # Sum input_tokens from assistant turns after the latest user turn
+    if ($0 ~ /"type"[[:space:]]*:[[:space:]]*"assistant"/) {
+      # Extract input_tokens, cache_creation_input_tokens, cache_read_input_tokens
+      n = match($0, /"input_tokens"[[:space:]]*:[[:space:]]*[0-9]+/)
+      if (n > 0) {
+        s = substr($0, n)
+        match(s, /[0-9]+/)
+        sum += substr(s, RSTART, RLENGTH) + 0
+      }
+      n = match($0, /"cache_creation_input_tokens"[[:space:]]*:[[:space:]]*[0-9]+/)
+      if (n > 0) {
+        s = substr($0, n)
+        match(s, /[0-9]+/)
+        sum += substr(s, RSTART, RLENGTH) + 0
+      }
+      n = match($0, /"cache_read_input_tokens"[[:space:]]*:[[:space:]]*[0-9]+/)
+      if (n > 0) {
+        s = substr($0, n)
+        match(s, /[0-9]+/)
+        sum += substr(s, RSTART, RLENGTH) + 0
+      }
+    }
+  }
+  END { print sum }
+')
+
+# If awk produced an empty or invalid value, treat as zero
+[ -z "$CURRENT_PROMPT_TOKENS" ] && CURRENT_PROMPT_TOKENS=0
+case "$CURRENT_PROMPT_TOKENS" in
+  *[!0-9]*) CURRENT_PROMPT_TOKENS=0 ;;
+esac
+
+# Block path: if BLOCK_CAP set and exceeded, emit blocking message and exit 2
+if [ "$BLOCK_CAP" -gt 0 ] && [ "$CURRENT_PROMPT_TOKENS" -gt "$BLOCK_CAP" ]; then
+  echo "BLOCKED: per-prompt-token-cap: this prompt consumed ${CURRENT_PROMPT_TOKENS} input tokens, exceeding the block cap of ${BLOCK_CAP}." >&2
+  echo "  Pattern matches the May 2026 #56297 cluster (single prompt burns 5-hour quota before output)." >&2
+  echo "  To proceed: end the current session with /clear and start a fresh prompt with narrower scope." >&2
+  echo "  To raise the cap: export PER_PROMPT_TOKEN_BLOCK=<higher value>." >&2
+  exit 2
+fi
+
+# Warn path: if cap exceeded, emit a non-blocking warning
+if [ "$CURRENT_PROMPT_TOKENS" -gt "$WARN_CAP" ]; then
+  echo "WARNING: per-prompt-token-cap: this prompt has consumed ${CURRENT_PROMPT_TOKENS} input tokens, exceeding the warn cap of ${WARN_CAP}." >&2
+  echo "  This is the May 2026 #56297 cluster pattern (single prompt burns quota before output)." >&2
+  echo "  Consider /clear and restart with a narrower scope. Run /usage --json to confirm 5-hour quota state." >&2
+fi
+
+exit 0

package/examples/permission-audit-log.sh

@@ -26,7 +26,7 @@
 #   # Top commands:
 #   cat ~/.claude/tool-usage.jsonl | jq -s '[.[] | select(.tool=="Bash")] | group_by(.command | split(" ")[0]) | map({cmd: .[0].command | split(" ")[0], count: length}) | sort_by(-.count) | .[:20]'
 #
-# TRIGGER: PreToolUse  MATCHER: "Bash"
+# TRIGGER: PostToolUse  MATCHER: ""
 
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)

package/examples/permission-denial-enforcer.sh

@@ -29,6 +29,18 @@
 #
 # TRIGGER: PostToolUse+PreToolUse  MATCHER: "Write|Edit|Bash"
 
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-permission-denial-enforcer-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [permission-denial-enforcer]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 MARKER="/tmp/.cc-write-denied-$$"
 MARKER_GLOB="/tmp/.cc-write-denied-*"