cc-safe-setup 29.7.0 → 30.0.4

package/examples/opus48-routine-task-warning.sh

@@ -0,0 +1,196 @@
+#!/bin/bash
+# opus48-routine-task-warning.sh — Surface the Cluster 23 candidate (Opus 4.8
+# effort-budget regression) at session start for operators running Opus 4.8 on
+# routine coding workflows.
+#
+# Background:
+#   Cluster 23 candidate 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 2026-05-31:
+#     #64153 (anchor, 46k output / 22m43s thinking, macOS 2.1.158)
+#     #64152 (Opus over-engineers simple tasks in agentic/CLI mode)
+#     #64143 (Session limits maxing out without user interaction)
+#     #64102 (excessive token consumption + API disconnects)
+#     #63455 (simple tasks consuming 40-50k tokens)
+#
+#   Four sub-cluster axes:
+#     23A single-turn thinking-budget magnitude (40-50k output on routine work)
+#     23B effort-tier perception mismatch (medium behaves like high/xhigh)
+#     23C operator-attribution gap (operator sees quota burn that was not theirs)
+#     23D over-engineering on simple tasks
+#
+#   Cluster 23 is still a candidate; tracked at cluster-tracker.html pending
+#   full promotion criteria (15+ aggregate reactions or sixth independent
+#   filing surfacing).
+#
+#   Reference:
+#     https://github.com/anthropics/claude-code/issues/64153  (anchor)
+#     Internal research: customer-pain-research-cluster-23-opus48-thinking-cost-2026-05-31.md
+#
+# What this hook does:
+#   On SessionStart, when CC_OPUS48_ROUTINE_WARN=1 is set, emits a stderr
+#   advisory naming the three operator-side mitigations from the Cluster 23
+#   candidate articulation. The hook is fully opt-in — silent by default.
+#   The advisory does not try to detect whether Opus 4.8 is actually the
+#   active model; the SessionStart payload often does not include model
+#   information, and a wrong guess about model identity is worse than a
+#   neutral advisory.
+#
+# Pairs with: output-token-spike-detector.sh (PostToolUse, observes the
+#   per-turn output_tokens magnitude after the fact). The SessionStart
+#   advisory frames the cluster up front; the PostToolUse detector
+#   surfaces specific events.
+#
+# When this hook does NOT emit anything:
+#   - CC_OPUS48_ROUTINE_WARN is unset or empty
+#   - CC_OPUS48_ROUTINE_DISABLE=1
+#   - CC_OPUS48_ROUTINE_QUIET=1
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/opus48-routine-task-warning.sh" }]
+#     }]
+#   }
+# }
+# And in your shell rc, opt in:
+#   export CC_OPUS48_ROUTINE_WARN=1
+#
+# Env vars:
+#   CC_OPUS48_ROUTINE_WARN=1     — opt-in trigger (required to emit)
+#   CC_OPUS48_ROUTINE_DISABLE=1  — never emit (overrides WARN)
+#   CC_OPUS48_ROUTINE_QUIET=1    — silent (overrides WARN)
+#
+# Design notes:
+#   - Opt-in by default. Operators not on Opus 4.8, or operators who do not
+#     run routine coding turns, do not benefit from the advisory.
+#   - No model auto-detection. The SessionStart payload is not guaranteed
+#     to include model identity, and assuming Opus 4.8 when the operator
+#     is on a different model would be a noise event.
+#   - Candidate-cluster framing. The advisory clearly states Cluster 23 is
+#     a candidate (not yet promoted) and links the anchor issue for
+#     verification.
+#   - Never blocks. Exit always 0.
+
+set -u
+
+# Hard disable path
+if [ "${CC_OPUS48_ROUTINE_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Quiet path
+if [ "${CC_OPUS48_ROUTINE_QUIET:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Opt-in gate
+if [ "${CC_OPUS48_ROUTINE_WARN:-0}" != "1" ]; then
+  exit 0
+fi
+
+cat >&2 <<'EOF'
+[opus48-routine-task-warning] Cluster 23 candidate advisory: Opus 4.8 under
+effort=medium can spend 40-50k output tokens on hidden thinking for a routine
+coding turn — a magnitude the anchor reporter explicitly states does NOT occur
+on Opus 4.6 / Opus 4.7 for comparable work.
+
+Five independent filings within the last week document the pattern:
+
+  #64153  (anchor) — medium effort burned 46,433 output tokens / 22m 43s of
+          thinking on a routine rename-impact scan. Transcript:
+          input_tokens 131, cache_read 91,877, cache_creation 4,054,
+          output 46,433, stop_reason end_turn (completed normally,
+          not a retry, not an API 400). macOS 2.1.158.
+
+  #64152  Opus over-engineers simple tasks in agentic/CLI mode, wasting
+          tokens (area:tools + area:model, Linux).
+
+  #64143  Session limits maxing out on their own, without any interaction
+          from user — the operator-visible signal of the underlying budget
+          drain (area:cost + area:mcp).
+
+  #64102  Excessive token consumption mixed with API disconnects.
+
+  #63455  Simple tasks consuming 40-50k tokens.
+
+Four sub-cluster axes:
+
+  23A  Single-turn thinking-budget magnitude (40-50k output tokens on
+       routine work where 1-5k would be the expected baseline).
+  23B  Effort-tier perception mismatch: "medium effort behaved much
+       closer to a high/xhigh thinking budget" per the anchor reporter.
+  23C  Operator-attribution gap: the operator sees quota burn that was
+       not their action, intersection with Cluster 4 (Pro Max quota
+       anomaly).
+  23D  Over-engineering on simple tasks: the model elaborates approaches
+       that the visible work does not require.
+
+This is independent from Cluster 22 (Opus 4.8 pre-execution fabrication).
+Cluster 22 is the correctness hazard (model asserts tool-output values
+before tools return); Cluster 23 candidate is the cost hazard (model
+burns 10× the expected hidden-thinking budget for the same routine
+work). Same version window (v2.1.156-v2.1.158, Opus 4.8 default),
+possibly the same root cause manifesting in two distinct surface
+failures.
+
+It is also independent from Cluster 4 (Pro Max quota anomaly), which
+is server-side cache_creation_input_tokens inflation. Cluster 23
+candidate is output_tokens growth — #64153's transcript shows
+cache_creation 4,054 vs output 46,433, the opposite ratio of Cluster
+4's signature. So Cluster 4's defense hooks (cache-creation-drift-
+detector.sh etc.) do not catch Cluster 23 candidate directly; they
+catch it indirectly only as it accumulates into session-rate anomalies.
+
+Three operator-side mitigations:
+
+  1) Switch to Opus 4.7 (/model claude-opus-4-7)
+     The reporter's own comparison: Opus 4.6 and 4.7 do not show this
+     magnitude on comparable routine work. This is full cluster
+     elimination — no per-turn measurement or threshold tuning needed.
+
+  2) Set effort=low for routine coding turns
+     The anchor signal is that medium effort behaves like high/xhigh.
+     Explicit effort=low constrains the thinking budget regardless of
+     whether the underlying calibration regression has been fixed.
+
+  3) Periodic audit of output_tokens magnitude
+     Run on your transcript directory:
+       jq -s 'map(.message.usage.output_tokens // 0) | sort | .[length/2]' \
+         ~/.claude/projects/**/recent.jsonl
+     Routine coding turns should produce 1-5k output tokens. A median
+     above 10k is the Cluster 23 candidate signal — pair with the
+     companion hook output-token-spike-detector.sh (PostToolUse,
+     surfaces per-turn spikes in real time).
+
+Companion hook (recommended pairing):
+  examples/output-token-spike-detector.sh
+  PostToolUse, rolling-window comparison of output_tokens against
+  trailing baseline, fires above 3× the recent mean and above a
+  configurable absolute floor (default 10000) to suppress noise on
+  small turns.
+
+This is a candidate cluster — full Cluster 23 promotion happens when
+cumulative reactions cross 15 or a sixth independent filing surfaces.
+The cc-safe-setup tracker (cluster-tracker.html) records the current
+state.
+
+To silence this advisory once you have applied the relevant mitigations:
+  unset CC_OPUS48_ROUTINE_WARN
+  # or
+  export CC_OPUS48_ROUTINE_QUIET=1
+
+References:
+  https://github.com/anthropics/claude-code/issues/64153  (anchor)
+  https://github.com/anthropics/claude-code/issues/64152  (over-engineering)
+  https://github.com/anthropics/claude-code/issues/64143  (silent quota drain)
+EOF
+
+exit 0

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