cc-safe-setup 29.8.0 → 30.0.4

package/examples/opus48-thinking-wedge-advisor.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# opus48-thinking-wedge-advisor.sh — Warn when a mid-conversation model swap
+#                                   from Opus 4.7 to Opus 4.8 is about to hit
+#                                   the Cluster 13 Axis G hard 400.
+#
+# Solves: Cluster 13 Axis G — Opus 4.7 → Opus 4.8 mid-conversation model swap
+#         produces a hard 400 ("thinking blocks must remain as original
+#         response") that strip-on-retry does not recover from. The signature
+#         of a thinking block generated by 4.7 is computed against the 4.7
+#         reasoning state; 4.8's resume path applies a stricter validation
+#         that rejects the 4.7-signed block even when the text is preserved
+#         verbatim. Unlike Cluster 13A (signature/text mismatch, soft 400),
+#         13G is structural: the only known full fix is staying on 4.7.
+#
+# Issues addressed: #63607 (Opus 4.8 incompatibility, "must remain as
+#         original response" phrasing), #63606, #63612, #63412 (Opus 4.8
+#         on long tool-heavy chats; 4.7 unaffected). Field guide on the
+#         seven-pattern split: https://github.com/anthropics/claude-code/issues/63147#issuecomment-4580358273
+#
+# How it works: Notification hook. Reads the model name from the event body
+#   (falling back to $CLAUDE_MODEL). Compares to the model recorded on the
+#   previous Notification. When the transition matches "Opus 4.7 → Opus 4.8"
+#   AND the current session transcript carries the empty-text + signed
+#   thinking block shape (the precondition for the 4.8 strict validation to
+#   trip), emits a stderr advisory naming sub-pattern 13G, the four central
+#   issues, and the only known full-fix path (stay on 4.7 + 2.1.152).
+#
+#   The hook NEVER blocks — exit 0 always. The advisory is calibrated to a
+#   transition shape that the operator can act on before the next API call.
+#
+# Differentiation from model-version-change-alert.sh:
+#   The general alert fires on any model change. This hook fires only on the
+#   13G transition shape (4.7 → 4.8 + signed thinking blocks in transcript)
+#   and articulates the specific failure mode and workaround. The two hooks
+#   are complementary; running both gives general visibility plus 13G-specific
+#   guidance.
+#
+# Environment variables:
+#   CC_CLUSTER_13G_DISABLE=1         — disable advisory entirely
+#   CC_CLUSTER_13G_VERBOSE=1         — include sample signature lengths
+#   CC_CLUSTER_13G_TRANSCRIPT        — override transcript path (test)
+#   CC_CLUSTER_13G_HISTORY_FILE      — override model history file (test)
+#   CC_CLUSTER_13G_FORCE=1           — fire regardless of source (test)
+#
+# TRIGGER: Notification
+# MATCHER: "" (filters event internally)
+
+set -uo pipefail
+
+INPUT=$(cat)
+[ "${CC_CLUSTER_13G_DISABLE:-0}" = "1" ] && exit 0
+
+# Resolve current model from event body or environment.
+BODY_MODEL=$(printf '%s' "$INPUT" | jq -r '.model // empty' 2>/dev/null)
+CURRENT_MODEL="${BODY_MODEL:-${CLAUDE_MODEL:-}}"
+[ -z "$CURRENT_MODEL" ] && exit 0
+
+# History file persists the last observed model across hook invocations.
+HISTORY_FILE="${CC_CLUSTER_13G_HISTORY_FILE:-/tmp/cc-cluster-13g-model-history}"
+PREV_MODEL=$(cat "$HISTORY_FILE" 2>/dev/null || true)
+
+# Always record current model on exit (fail-open if we cannot write).
+record_current_model() {
+    printf '%s' "$CURRENT_MODEL" > "$HISTORY_FILE" 2>/dev/null || true
+}
+trap record_current_model EXIT
+
+# Require a previous observation to detect a transition.
+[ -z "$PREV_MODEL" ] && exit 0
+
+# Same model — no transition.
+[ "$PREV_MODEL" = "$CURRENT_MODEL" ] && exit 0
+
+# Identify the 13G transition: Opus 4.7 series → Opus 4.8 series.
+# Accept any string containing "opus-4-7" / "opus-4-8" (case-insensitive)
+# to match both API model IDs and Claude Code's internal naming.
+is_opus_47() {
+    printf '%s' "$1" | grep -qiE 'opus[-_. ]*4[-_. ]*7'
+}
+is_opus_48() {
+    printf '%s' "$1" | grep -qiE 'opus[-_. ]*4[-_. ]*8'
+}
+
+if [ "${CC_CLUSTER_13G_FORCE:-0}" != "1" ]; then
+    is_opus_47 "$PREV_MODEL" || exit 0
+    is_opus_48 "$CURRENT_MODEL" || exit 0
+fi
+
+# Precondition for 13G to fire on the next API call: the transcript carries
+# signed thinking blocks emitted by the prior model. If there are no signed
+# thinking blocks, the swap may complete cleanly and the advisory is noise.
+LATEST="${CC_CLUSTER_13G_TRANSCRIPT:-}"
+if [ -z "$LATEST" ]; then
+    PROJ_DIR="${CC_PROJECT_DIR:-$PWD}"
+    SLUG=$(printf '%s' "$PROJ_DIR" | sed 's|/|-|g')
+    TRANSCRIPT_DIR="${HOME}/.claude/projects/${SLUG}"
+    [ -d "$TRANSCRIPT_DIR" ] || exit 0
+    LATEST=$(ls -t "$TRANSCRIPT_DIR"/*.jsonl 2>/dev/null | head -1)
+fi
+[ -n "$LATEST" ] || exit 0
+[ -r "$LATEST" ] || exit 0
+
+# Scan for any signed thinking block (text empty or non-empty — the 13G
+# trigger is the 4.7-computed signature itself, independent of whether the
+# text was emptied to "" as in 13A).
+SCAN=$(jq -rR 'fromjson? | select(.type == "assistant") | .message.content[]? | select(.type == "thinking" and ((.signature // "") | length) > 0) | (.signature | length)' "$LATEST" 2>/dev/null || true)
+[ -z "$SCAN" ] && exit 0
+
+COUNT=$(printf '%s\n' "$SCAN" | grep -c .)
+SIG_SAMPLE=$(printf '%s' "$SCAN" | head -3 | tr '\n' ' ')
+
+{
+    echo "[opus48-thinking-wedge-advisor] Cluster 13G transition detected."
+    echo ""
+    echo "  Previous model: $PREV_MODEL"
+    echo "  Current model:  $CURRENT_MODEL"
+    echo "  Transcript:     $LATEST"
+    echo "  Signed thinking block(s) carried from prior model: ${COUNT}"
+    echo ""
+    echo "The next API call may hit the hard 400:"
+    echo "    \`thinking\` or \`redacted_thinking\` blocks in the latest assistant"
+    echo "    message must remain as they were in the original response."
+    echo ""
+    echo "This 400 differs from the Cluster 13A wedge: strip-on-retry does NOT"
+    echo "recover, because the 4.7-computed signature is structurally rejected"
+    echo "by the 4.8 validation path. The session cannot continue on 4.8 once"
+    echo "this fires."
+    echo ""
+    echo "Recommended actions:"
+    echo "  - Switch back to Opus 4.7 with /model and continue on this session."
+    echo "  - For 4.8 work, start a fresh session without prior 4.7-signed blocks."
+    echo "  - Pinning Claude Code to 2.1.152 avoids the related Cluster 13F"
+    echo "    context-ops failure that 13G frequently compounds with."
+    echo ""
+    echo "Reference: https://github.com/anthropics/claude-code/issues/63607"
+    echo "Related: https://github.com/anthropics/claude-code/issues/63147#issuecomment-4580358273"
+    if [ "${CC_CLUSTER_13G_VERBOSE:-0}" = "1" ]; then
+        echo ""
+        echo "(first 3 signature lengths: ${SIG_SAMPLE})"
+    fi
+} >&2
+
+exit 0

package/examples/output-credential-scan.sh

@@ -17,7 +17,7 @@ STDOUT=$(echo "$INPUT" | jq -r '.tool_result.stdout // empty' 2>/dev/null)
 [ -z "$STDOUT" ] && exit 0
 
 # Check for common credential patterns in output
-if echo "$STDOUT" | grep -qiE '(sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|AKIA[A-Z0-9]{16}|xox[bpsa]-[a-zA-Z0-9-]+|eyJ[a-zA-Z0-9_-]+\.eyJ)'; then
+if echo "$STDOUT" | grep -qiE '((^|[^A-Za-z0-9])sk-[A-Za-z0-9_-]{20,}|ghp_[a-zA-Z0-9]{36}|AKIA[A-Z0-9]{16}|xox[bpsa]-[a-zA-Z0-9-]+|eyJ[a-zA-Z0-9_-]+\.eyJ)'; then
     echo "⚠ Possible credential detected in command output!" >&2
     echo "  This output may contain API keys, tokens, or secrets." >&2
     echo "  Avoid sharing this output or committing it to version control." >&2

package/examples/output-secret-mask.sh

@@ -1,16 +1,31 @@
 #!/bin/bash
-# output-secret-mask.sh — Mask secrets in tool output before Claude sees them
+# output-secret-mask.sh — Warn when tool output looks like it contained a secret
 #
 # Solves: Commands like `env`, `printenv`, `cat .env` expose secrets in tool output.
 #         Claude then has secrets in its context window, increasing leak risk.
-#         This hook masks secret values in PostToolUse output.
 #
-# How it works: PostToolUse hook that scans tool output for secret patterns
-#               and replaces them with [MASKED]. The masked output is what
-#               Claude sees in its context.
+# CORRECTION 2026-08-13 — read this before relying on the name.
+#   This file used to claim it "masks secret values" and that "the masked output
+#   is what Claude sees in its context". It never did that. `[MASKED]` appeared
+#   only in this comment; there is no substitution anywhere in the body, and
+#   running it against a real key produces one line on stderr and nothing else.
+#   The name promised a control that did not exist, which is worse than no hook:
+#   someone reads "output-secret-mask", installs it, and believes secrets are
+#   being stripped out of the context window. They are not.
 #
-# Note: This hook modifies the tool output that Claude receives.
-#       The actual command output is unchanged on disk/terminal.
+#   The premise is also not implementable at this event. PostToolUse fires
+#   *after* the tool result exists; it validates output, it does not rewrite what
+#   the model already received (see SETTINGS_REFERENCE.md, PostToolUse row).
+#   So this hook has been corrected to describe what it does, rather than
+#   implementing a promise the event cannot keep.
+#
+# What it actually does: scans the tool result for secret-shaped strings and
+#   writes one warning to stderr. Detection only. The secret is already in the
+#   context by the time this runs.
+#
+# What to use instead, if you need the secret to never reach the context:
+#   block the command before it runs (a PreToolUse guard on `env` / `printenv` /
+#   `cat .env`), or keep secrets out of files the agent reads at all.
 #
 # Usage: Add to settings.json as a PostToolUse hook
 #
@@ -37,8 +52,15 @@ NEEDS_MASK=false
 echo "$OUTPUT" | grep -qE 'AKIA[0-9A-Z]{16}' && NEEDS_MASK=true
 # GitHub tokens
 echo "$OUTPUT" | grep -qE '(ghp_|gho_|ghs_|ghr_)[A-Za-z0-9_]{20,}' && NEEDS_MASK=true
-# OpenAI/Anthropic keys
-echo "$OUTPUT" | grep -qE 'sk-[A-Za-z0-9_-]{20,}' && NEEDS_MASK=true
+# OpenAI/Anthropic keys.
+# The prefix has to START a token. Without the left boundary this also fired on
+# ordinary English words that end in "sk" before a separator — task-, ask-,
+# risk-, disk-, desk- — so any path built from one of those, followed by twenty
+# more word characters, was reported as a leaked key. The same defect was fixed
+# in write-secret-guard.sh on 2026-08-13. A warning that cries on ordinary
+# output is a warning people learn to ignore, so precision matters here as much
+# as coverage.
+echo "$OUTPUT" | grep -qE '(^|[^A-Za-z0-9_-])sk-[A-Za-z0-9_-]{20,}' && NEEDS_MASK=true
 # Slack tokens
 echo "$OUTPUT" | grep -qE '(xoxb-|xoxp-)[0-9A-Za-z-]{20,}' && NEEDS_MASK=true
 # Generic secrets in env output (KEY=value pattern with high-entropy value)

package/examples/output-token-spike-detector.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+# output-token-spike-detector.sh — alert when per-request output_tokens spikes above baseline
+#
+# Why: Cluster 23 candidate (Opus 4.8 effort-budget regression) documents that
+#      Opus 4.8 under effort=medium can spend 40-50k output tokens on hidden
+#      thinking for a routine coding turn — Issue #64153 anchor (46,433 output
+#      tokens / 22m 43s of thinking on a small rename-impact scan, transcript
+#      stop_reason=end_turn so this completed normally, not a retry / not an
+#      API 400). The reporter explicitly compares: Opus 4.6 / Opus 4.7 do NOT
+#      show this magnitude for comparable routine work. Five independent filings
+#      so far (#64153 / #64152 / #64143 / #64102 / #63455).
+#
+#      This is structurally distinct from Cluster 4 (Pro Max quota) which is
+#      server-side cache_creation_input_tokens inflation — Cluster 23 candidate
+#      is output_tokens magnitude. #64153's transcript shows cache_creation
+#      4,054 vs output 46,433, the opposite ratio of Cluster 4's signature.
+#      So Cluster 4's hooks (cache-creation-drift-detector etc.) do not catch
+#      Cluster 23 candidate directly.
+#
+#      Routine coding turns should sit at 1-5k output tokens; 10× above that is
+#      the operator-side signal that the model is burning hidden-thinking budget
+#      out of proportion to the visible work. This hook emits a one-line stderr
+#      warning when the current request's output_tokens exceeds the trailing-
+#      window mean by a configurable multiplier (default 3.0, higher than the
+#      cache-creation drift threshold because output_tokens naturally varies
+#      more across turns).
+#
+# Event: PostToolUse  MATCHER: "" (all tools)
+# Action: Read output_tokens from the PostToolUse payload (or the last assistant
+#         turn in the transcript as fallback). Append to a rolling JSONL log.
+#         Compute the mean of the last N nonzero samples. If the current value
+#         exceeds threshold * mean, emit a warning to stderr with the Opus 4.7
+#         fallback path. Advisory only (exit 0); does not block.
+#
+# Configuration (all optional):
+#   CC_OUTPUT_SPIKE_LOG          Log path (default: ~/.cache/cc-safe-setup/output-token-spike.jsonl)
+#   CC_OUTPUT_SPIKE_THRESHOLD    Multiplier for alert (default: 3.0 = 3× above mean)
+#   CC_OUTPUT_SPIKE_MIN_HISTORY  Minimum samples before alerting (default: 20)
+#   CC_OUTPUT_SPIKE_WINDOW       Trailing window size for mean (default: 200 samples)
+#   CC_OUTPUT_SPIKE_FLOOR        Absolute minimum (default: 10000) — never alert below this
+#                                even at threshold ratio, to suppress noise on small turns
+#   CC_OUTPUT_SPIKE_SILENT       Set to "1" to suppress stderr (still logs)
+#
+# Inspect the log:
+#   tail -50 ~/.cache/cc-safe-setup/output-token-spike.jsonl
+#   jq -s 'map(.out_tokens) | add / length' ~/.cache/cc-safe-setup/output-token-spike.jsonl
+#
+# The registration was missing from this header. The installer reads TRIGGER
+# and MATCHER from here and falls back to PreToolUse / Bash when both are
+# absent, so this hook was being registered at a moment where the field it
+# reads is always empty: it installed, it appeared in the settings, and it
+# did nothing. Measured 2026-08-04 across examples/: 14 files were like this.
+# TRIGGER: PostToolUse
+# MATCHER: ""
+
+set -u
+
+LOG="${CC_OUTPUT_SPIKE_LOG:-${HOME}/.cache/cc-safe-setup/output-token-spike.jsonl}"
+THRESHOLD="${CC_OUTPUT_SPIKE_THRESHOLD:-3.0}"
+MIN_HISTORY="${CC_OUTPUT_SPIKE_MIN_HISTORY:-20}"
+WINDOW="${CC_OUTPUT_SPIKE_WINDOW:-200}"
+FLOOR="${CC_OUTPUT_SPIKE_FLOOR:-10000}"
+SILENT="${CC_OUTPUT_SPIKE_SILENT:-0}"
+
+mkdir -p "$(dirname "$LOG")" 2>/dev/null
+
+INPUT=$(cat)
+
+# Extract output_tokens from the PostToolUse payload (path varies by tool).
+OUT_TOKENS=$(printf '%s' "$INPUT" | jq -r '.tool_response.usage.output_tokens // empty' 2>/dev/null)
+
+# Fallback: read the last assistant turn's usage from the transcript.
+if [ -z "$OUT_TOKENS" ]; then
+  TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+  if [ -n "$TRANSCRIPT" ] && [ -r "$TRANSCRIPT" ]; then
+    LAST_USAGE=$(tac "$TRANSCRIPT" 2>/dev/null | grep -m1 '"usage"' || true)
+    if [ -n "$LAST_USAGE" ]; then
+      OUT_TOKENS=$(printf '%s' "$LAST_USAGE" | \
+        jq -r '.message.usage.output_tokens // .usage.output_tokens // empty' 2>/dev/null)
+    fi
+  fi
+fi
+
+# No usable measurement — exit quietly (this is the common case for many tools).
+if [ -z "$OUT_TOKENS" ] || [ "$OUT_TOKENS" = "0" ] || [ "$OUT_TOKENS" = "null" ]; then
+  exit 0
+fi
+
+# Validate the value is a positive integer.
+case "$OUT_TOKENS" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Try to capture the model name too — useful for distinguishing Opus 4.7 vs 4.8 in logs.
+MODEL=$(printf '%s' "$INPUT" | jq -r '.tool_response.model // .model // empty' 2>/dev/null)
+if [ -z "$MODEL" ] && [ -n "${TRANSCRIPT:-}" ] && [ -r "${TRANSCRIPT:-}" ]; then
+  MODEL=$(tac "$TRANSCRIPT" 2>/dev/null | grep -m1 '"model"' | jq -r '.message.model // .model // empty' 2>/dev/null || true)
+fi
+MODEL="${MODEL:-unknown}"
+
+# Append this sample to the rolling log as a JSONL line.
+printf '{"ts":"%s","session":"%s","model":"%s","out_tokens":%s}\n' "$TS" "$SESSION_ID" "$MODEL" "$OUT_TOKENS" >> "$LOG"
+
+# How many historical samples do we have so far? (Includes the line we just appended.)
+SAMPLE_COUNT=$(wc -l < "$LOG" 2>/dev/null | tr -d ' ')
+SAMPLE_COUNT="${SAMPLE_COUNT:-0}"
+
+# Need at least MIN_HISTORY samples before we trust the baseline.
+if [ "$SAMPLE_COUNT" -lt "$MIN_HISTORY" ]; then
+  exit 0
+fi
+
+# Compute the mean of the trailing window (excluding the just-written sample).
+# We exclude the current sample so the alert compares "this" against "the past".
+TAIL_LINES=$((WINDOW + 1))
+MEAN=$(tail -n "$TAIL_LINES" "$LOG" 2>/dev/null | head -n -1 | \
+  jq -s 'if length > 0 then (map(.out_tokens) | add / length) else 0 end' 2>/dev/null)
+
+# If the baseline mean is invalid or zero, skip (defensive).
+if [ -z "$MEAN" ] || [ "$MEAN" = "0" ] || [ "$MEAN" = "null" ]; then
+  exit 0
+fi
+
+# Compute ratio = OUT_TOKENS / MEAN. Use awk because bash lacks float arithmetic.
+RATIO=$(awk -v c="$OUT_TOKENS" -v m="$MEAN" 'BEGIN { if (m > 0) printf "%.3f", c/m; else print "0" }')
+EXCEEDS=$(awk -v r="$RATIO" -v t="$THRESHOLD" 'BEGIN { print (r > t) ? 1 : 0 }')
+
+# Suppress noise: even at threshold ratio, do not alert below the absolute floor.
+# A 3× spike from 1k → 3k is normal variance; a 3× spike from 5k → 15k matters.
+ABOVE_FLOOR=$(awk -v c="$OUT_TOKENS" -v f="$FLOOR" 'BEGIN { print (c > f) ? 1 : 0 }')
+
+if [ "$EXCEEDS" = "1" ] && [ "$ABOVE_FLOOR" = "1" ] && [ "$SILENT" != "1" ]; then
+  # Format the baseline mean as an integer for the human-readable output.
+  MEAN_INT=$(awk -v m="$MEAN" 'BEGIN { printf "%d", m }')
+  PCT=$(awk -v r="$RATIO" 'BEGIN { printf "%d", (r - 1) * 100 }')
+  echo "NOTICE: output_tokens=${OUT_TOKENS} (model=${MODEL}) is ${PCT}% above your trailing-${WINDOW}-sample baseline (~${MEAN_INT})." >&2
+  echo "        Possible Cluster 23 candidate signal (Opus 4.8 effort-budget regression, see #64153 / #64152 / #64143)." >&2
+  echo "        Mitigations: switch via '/model claude-opus-4-7', set effort=low for routine turns, or audit with:" >&2
+  echo "        jq -s 'map(.out_tokens) | sort | .[length/2]' ${LOG}" >&2
+fi
+
+exit 0

package/examples/package-json-guard.sh

@@ -1,6 +1,18 @@
 #!/bin/bash
 #
 # 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-package-json-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [package-json-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 if echo "$COMMAND" | grep -qE '\brm\b.*package\.json'; then

package/examples/package-lock-frozen.sh

@@ -9,6 +9,18 @@
 # TRIGGER: PreToolUse
 # MATCHER: "Edit|Write"
 
+# 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-package-lock-frozen-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [package-lock-frozen]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty' 2>/dev/null)
 [ -z "$FILE" ] && exit 0

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