cc-safe-setup 29.7.0 → 30.0.4

package/examples/proxy-capture-suggester.sh

@@ -0,0 +1,159 @@
+#!/bin/bash
+# proxy-capture-suggester.sh — Surface HTTPS proxy capture path for compliance-bound operators
+#
+# Background:
+#   v2.1.150+ injects server-side strings into the system prompt via two cached channels:
+#   the bootstrap API `client_data` field and the GrowthBook `tengu_heron_brook` flag.
+#   The opt-out env vars (CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, DISABLE_GROWTHBOOK=1)
+#   close the injection channel going forward, and cache-residue-detector.sh prompts
+#   removal of pre-opt-out cached values. Neither produces a reconstructible audit trail
+#   of what the agent was instructed at the time of any logged action.
+#
+#   For operators in regulated industries (financial services, healthcare, government,
+#   defense) the audit trail gap is the structural concern. The opt-outs answer
+#   "stop trusting Anthropic with the prompt", but compliance frameworks (SOX, HIPAA,
+#   FedRAMP, PCI-DSS, EU AI Act Article 12) also require "produce the exact prompt that
+#   was sent for any logged tool execution within the retention window".
+#
+#   The only operator-side path to that audit trail is HTTPS proxy capture: an MITM
+#   proxy between the Claude Code client and api.anthropic.com that records the full
+#   request body of every API call. Anthropic does not provide a first-party audit
+#   export; the proxy capture path is the workaround.
+#
+#   Reference: https://github.com/anthropics/claude-code/issues/62061 (46+ reactions)
+#              https://gist.github.com/yurukusa/03839b3c3f88e1cce38fb0f2c127544d (v2.1.150 audit paths)
+#
+# What this hook does:
+#   On SessionStart, when CC_PROXY_CAPTURE_SUGGESTER_ENABLE=1 is set, inspect the
+#   environment for an active HTTPS proxy configuration. If none is present, emit a
+#   one-time advisory naming three audit-grade proxy tools with concrete invocation,
+#   the CA-trust step required for TLS termination, and the env-var bridge that wires
+#   Claude Code's API client into the proxy.
+#
+#   The hook is opt-in. Most operators do not need an audit trail and would not
+#   benefit from running an MITM proxy locally; it adds attack surface, latency, and
+#   maintenance overhead. The advisory only fires when an operator has explicitly
+#   declared compliance intent via the opt-in env var.
+#
+# When this hook does NOT fire:
+#   - CC_PROXY_CAPTURE_SUGGESTER_ENABLE is unset or set to 0 (the default)
+#   - CC_PROXY_CAPTURE_SUGGESTER_QUIET=1 (silenced after acknowledgement)
+#   - An HTTPS proxy is already active (HTTPS_PROXY / https_proxy / ALL_PROXY contains a value)
+#
+# When this hook DOES fire (default behavior with ENABLE=1):
+#   - SessionStart and no HTTPS_PROXY-family env var is set → emit the four-tool advisory
+#   - SessionStart and a proxy IS set but ANTHROPIC_LOG_DIR is unset → emit a shorter
+#     advisory pointing out that proxy capture is active but no local log sink is configured
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/proxy-capture-suggester.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_PROXY_CAPTURE_SUGGESTER_ENABLE=1   — opt in to the advisory (default off)
+#   CC_PROXY_CAPTURE_SUGGESTER_QUIET=1    — silence permanently after acknowledgement
+#
+# Privacy: the hook reads only the names of standard proxy env vars (HTTPS_PROXY,
+# https_proxy, ALL_PROXY, NO_PROXY, ANTHROPIC_LOG_DIR). It never reads, transmits, or
+# logs the values themselves.
+
+set -u
+
+# Silenced permanently after acknowledgement
+if [ "${CC_PROXY_CAPTURE_SUGGESTER_QUIET:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Opt-in: silent unless the operator explicitly declared compliance intent
+if [ "${CC_PROXY_CAPTURE_SUGGESTER_ENABLE:-0}" != "1" ]; then
+  exit 0
+fi
+
+# Check for an active HTTPS proxy (uppercase or lowercase, plus ALL_PROXY)
+PROXY_ACTIVE=0
+for var in HTTPS_PROXY https_proxy ALL_PROXY all_proxy; do
+  # shellcheck disable=SC1083
+  eval val="\${$var:-}"
+  if [ -n "${val:-}" ]; then
+    PROXY_ACTIVE=1
+    break
+  fi
+done
+
+if [ "$PROXY_ACTIVE" = "1" ]; then
+  # Proxy is active. Check whether an audit log sink is configured.
+  if [ -z "${ANTHROPIC_LOG_DIR:-}" ]; then
+    cat >&2 <<'EOF'
+[proxy-capture-suggester] HTTPS proxy is active but ANTHROPIC_LOG_DIR is unset.
+  Compliance-grade audit trails require a stable on-disk sink for the captured
+  request bodies. Configure one before relying on the proxy capture for evidence:
+
+    export ANTHROPIC_LOG_DIR="$HOME/.claude/api-audit-log"
+    mkdir -p "$ANTHROPIC_LOG_DIR"
+
+  mitmproxy: --save-stream-file "$ANTHROPIC_LOG_DIR/$(date -u +%Y%m%dT%H%M%SZ).flow"
+  Burp Suite: Project options -> HTTP -> Logging -> Requests -> file in $ANTHROPIC_LOG_DIR
+  Charles: Tools -> Auto Save -> directory in $ANTHROPIC_LOG_DIR, format .chlsj
+
+  Silence this advisory once configured:
+    export CC_PROXY_CAPTURE_SUGGESTER_QUIET=1
+EOF
+  fi
+  exit 0
+fi
+
+# No proxy active — emit the full four-tool advisory.
+cat >&2 <<'EOF'
+[proxy-capture-suggester] Compliance audit intent declared (CC_PROXY_CAPTURE_SUGGESTER_ENABLE=1)
+but no HTTPS proxy is configured. Without one, you cannot reconstruct the system prompt that
+was sent at the time of any logged tool execution. The v2.1.150 server-side injection channel
+(GrowthBook tengu_heron_brook + bootstrap client_data) is acknowledged-intentional by Anthropic;
+opt-out env vars close the channel going forward but produce no audit trail.
+
+Four operator-side proxy options that terminate TLS and record the full request body:
+
+  1. mitmproxy (free, scriptable, recommended for compliance pipelines)
+       brew install mitmproxy            # macOS
+       pipx install mitmproxy            # Linux
+     Start:
+       mitmproxy --mode regular --listen-port 8080 \
+                 --save-stream-file "$HOME/.claude/api-audit-log/$(date -u +%Y%m%dT%H%M%SZ).flow"
+     Bridge:
+       export HTTPS_PROXY=http://127.0.0.1:8080
+       export SSL_CERT_FILE="$HOME/.mitmproxy/mitmproxy-ca-cert.pem"
+     Verify: a single Claude Code prompt should produce a .flow file with the request body.
+
+  2. Burp Suite Community (free, GUI, common in enterprise pen-test contexts)
+     Proxy listener: 127.0.0.1:8080. Configure HTTPS_PROXY as above. Export the Burp CA cert
+     and set SSL_CERT_FILE to its path. Project options -> HTTP -> Logging -> Requests for
+     persistent capture.
+
+  3. Charles Proxy (commercial, $50, GUI, common on macOS dev workstations)
+     Default listener 127.0.0.1:8888. Tools -> Auto Save for persistent capture. Trust the
+     Charles root certificate via Charles -> Help -> SSL Proxying.
+
+  4. Anthropic SDK direct logging (free, lightweight, no proxy)
+     Set ANTHROPIC_LOG=debug to dump every request to stderr; redirect stderr to a file
+     and rotate. This captures less metadata than a proper proxy (no response timing, no
+     TLS handshake detail) but produces a request-body audit trail with no MITM overhead.
+
+The four paths above produce an audit trail that pairs with cache-residue-detector.sh
+(closes the cache gap) and server-side-prompt-injection-detector.sh (warns on missing
+opt-outs). Together these three hooks cover the v2.1.150 audit surface for operators in
+regulated industries.
+
+Silence this advisory after configuring a proxy:
+  export CC_PROXY_CAPTURE_SUGGESTER_QUIET=1
+
+References:
+  https://github.com/anthropics/claude-code/issues/62061  (v2.1.150 injection report, 46+ reactions)
+  https://gist.github.com/yurukusa/03839b3c3f88e1cce38fb0f2c127544d  (four audit paths writeup)
+EOF
+
+exit 0

package/examples/public-artefact-socratic-narrowing.sh

@@ -0,0 +1,232 @@
+#!/bin/bash
+# public-artefact-socratic-narrowing.sh — Inject a Socratic-narrowing prompt
+# at the public-artefact emission boundary, asking the agent to re-engage the
+# gradient on decisions in the artefact before it ships.
+#
+# Solves: #60226 (the structural-parent frame) — recognition-without-arrest at
+# the public-artefact emission boundary, as operationalized in @beq00000's
+# clean-state worked example (#60226, 2026-05-19 comment).
+#
+# In that comment, seven instances of recognition-without-arrest surfaced in a
+# single non-drifted session. Three of the seven were caught at the public-
+# artefact emission boundary by the operator's Socratic-narrowing intervention:
+#
+#   "The form: not 'is this wrong' (binary question, eliciting binary defence),
+#    but 'is this verifiable / already-documented / what-would-actually-need-
+#    attention look like' (gradient question, forcing the model to re-engage
+#    the rank ordering the original output had flattened). The first form gets
+#    defended; the second gets re-decided."
+#
+# The operator-language form is implementable as session discipline today, but
+# the gate fires only when the operator is present and noticing. This hook is
+# the tooling-side form: PreToolUse on the public-artefact emission tools
+# injects a Socratic-narrowing reminder at the boundary so the agent re-engages
+# the gradient regardless of whether the operator is watching this turn.
+#
+# The hook deliberately does not check what the artefact says. Recognition-
+# without-arrest cannot be solved by content classification (that is the
+# failure mode being addressed). The gate's only job is to force one more
+# pass over the artefact with the gradient framing applied. The agent's
+# re-emission is what does the work.
+#
+# Related Issues / Reports:
+#   #60226 (@suwayama, 2026-05-18) — recognition-without-arrest framework
+#                  comment thread → @beq00000 2026-05-19 clean-state worked
+#                  example with seven instances and the Socratic-narrowing
+#                  mitigation
+#   #60188 (@suwayama)             — binary-collapse subhypothesis; the
+#                                    Socratic form re-introduces the gradient
+#   #60506 (@zean89,   2026-05-19) — six-day drift across PR-body emissions
+#                                    that survived multiple operator passes
+#
+# TRIGGER: PreToolUse
+# MATCHER: Bash|Write|Edit
+#
+# HOW IT WORKS:
+#   1. Reads PreToolUse input via stdin.
+#   2. For Bash, matches the command against public-artefact emission patterns
+#      (gh pr create/edit, gh issue create/comment, gh release create,
+#      git commit -m '<long>', git tag -a, etc.).
+#   3. For Write/Edit, matches the target path against public-artefact paths
+#      (.github/, CHANGELOG.md, README*.md, docs/, sales-page*.md, etc.).
+#   4. If the artefact body / file content is below a length threshold
+#      (default 200 chars), allows it through silently — short artefacts are
+#      not where the binary-collapse failure surfaces.
+#   5. Computes a content hash of the artefact body. If the same hash was
+#      seen within the cache window (default 600s), allows through — the
+#      agent has already re-engaged the gradient on this content.
+#   6. Otherwise emits a Socratic-narrowing system-reminder via stderr and
+#      exits 2, blocking the emission until the agent re-emits.
+#
+# The hash-based cache is what makes the gate non-infinite. After the agent
+# re-emits with the gradient applied (different content → new hash → re-fired
+# once), or after deliberately re-emitting the same content (operator-
+# approved → hash matches → passes through), the artefact ships.
+#
+# CONFIGURATION (environment variables):
+#   CC_SOCRATIC_DISABLE             set to "1" to disable the gate entirely
+#   CC_SOCRATIC_STATE_DIR           default /tmp/cc-socratic-cache
+#   CC_SOCRATIC_BODY_MIN_CHARS      default 200 — artefacts shorter than this
+#                                                  are not gated
+#   CC_SOCRATIC_CACHE_TTL_SECONDS   default 600 — how long a hash counts as
+#                                                  "already re-engaged"
+#   CC_SOCRATIC_BASH_PATTERNS       default built-in — regex of Bash commands
+#   CC_SOCRATIC_FILE_PATTERNS       default built-in — regex of file paths
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "PreToolUse": [{
+#         "matcher": "Bash|Write|Edit",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/public-artefact-socratic-narrowing.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-public-artefact-socratic-narrowing-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [public-artefact-socratic-narrowing]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+[ "${CC_SOCRATIC_DISABLE:-0}" = "1" ] && exit 0
+
+# OPT-IN: this gate blocks every public-artefact emission (commits, PRs, docs
+# edits) on first pass, which is high friction as a default. It is therefore
+# off unless explicitly enabled. Set CC_SOCRATIC_ENABLE=1 to turn it on.
+[ "${CC_SOCRATIC_ENABLE:-0}" = "1" ] || exit 0
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+STATE_DIR="${CC_SOCRATIC_STATE_DIR:-/tmp/cc-socratic-cache}"
+BODY_MIN_CHARS="${CC_SOCRATIC_BODY_MIN_CHARS:-200}"
+CACHE_TTL="${CC_SOCRATIC_CACHE_TTL_SECONDS:-600}"
+
+DEFAULT_BASH_PATTERNS='gh[[:space:]]+pr[[:space:]]+(create|edit)|gh[[:space:]]+issue[[:space:]]+(create|comment)|gh[[:space:]]+release[[:space:]]+create|gh[[:space:]]+gist[[:space:]]+create|git[[:space:]]+commit[[:space:]]+.*-m|git[[:space:]]+tag[[:space:]]+-a|git[[:space:]]+notes[[:space:]]+add'
+DEFAULT_FILE_PATTERNS='(^|/)\.github/|(^|/)CHANGELOG(\.[a-z]+)?|(^|/)README[^/]*$|(^|/)docs?/|(^|/)sales-page|(^|/)launch-|(^|/)RELEASE|(^|/)NOTICE|(^|/)CITATION'
+
+BASH_PATTERNS="${CC_SOCRATIC_BASH_PATTERNS:-$DEFAULT_BASH_PATTERNS}"
+FILE_PATTERNS="${CC_SOCRATIC_FILE_PATTERNS:-$DEFAULT_FILE_PATTERNS}"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+# Extract tool name and input from the PreToolUse payload
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // .tool // empty' 2>/dev/null)
+[ -z "$TOOL_NAME" ] && exit 0
+
+ARTEFACT_BODY=""
+ARTEFACT_KIND=""
+
+case "$TOOL_NAME" in
+    Bash)
+        CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+        [ -z "$CMD" ] && exit 0
+        # Does the command match a public-artefact emission pattern?
+        printf '%s' "$CMD" | grep -Eiq "$BASH_PATTERNS" || exit 0
+        ARTEFACT_BODY="$CMD"
+        ARTEFACT_KIND="bash-command"
+        ;;
+    Write)
+        FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+        [ -z "$FILE_PATH" ] && exit 0
+        printf '%s' "$FILE_PATH" | grep -Eiq "$FILE_PATTERNS" || exit 0
+        ARTEFACT_BODY=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null)
+        ARTEFACT_KIND="file-write:$FILE_PATH"
+        ;;
+    Edit)
+        FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+        [ -z "$FILE_PATH" ] && exit 0
+        printf '%s' "$FILE_PATH" | grep -Eiq "$FILE_PATTERNS" || exit 0
+        ARTEFACT_BODY=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null)
+        ARTEFACT_KIND="file-edit:$FILE_PATH"
+        ;;
+    *)
+        exit 0
+        ;;
+esac
+
+# Below threshold → not where the failure surfaces
+BODY_LEN=${#ARTEFACT_BODY}
+if [ "$BODY_LEN" -lt "$BODY_MIN_CHARS" ]; then
+    exit 0
+fi
+
+# Hash the artefact body. If we have seen this hash recently, the agent has
+# already had one Socratic-narrowing pass on it — allow through.
+HASH=$(printf '%s' "$ARTEFACT_BODY" | sha256sum 2>/dev/null | awk '{print $1}')
+[ -z "$HASH" ] && exit 0
+
+CACHE_FILE="$STATE_DIR/$HASH"
+NOW=$(date +%s)
+
+if [ -f "$CACHE_FILE" ]; then
+    CACHED_AT=$(cat "$CACHE_FILE" 2>/dev/null || echo 0)
+    AGE=$((NOW - CACHED_AT))
+    if [ "$AGE" -lt "$CACHE_TTL" ]; then
+        # Same content within window → agent has re-engaged → ship it
+        exit 0
+    fi
+fi
+
+# Record the hash so the re-emission passes through
+echo "$NOW" > "$CACHE_FILE"
+
+# Best-effort cache eviction: drop entries older than 24h
+find "$STATE_DIR" -type f -mmin +1440 -delete 2>/dev/null || true
+
+# Emit the Socratic-narrowing reminder and block the emission once
+cat >&2 <<EOF
+<system-reminder>
+PUBLIC-ARTEFACT EMISSION BOUNDARY — about to emit $ARTEFACT_KIND
+($BODY_LEN chars). This is the boundary at which three of seven instances of
+recognition-without-arrest surfaced in @beq00000's clean-state worked example
+on #60226 (2026-05-19).
+
+Before this artefact ships, re-engage the gradient on each decision in it.
+The Socratic-narrowing form (per @beq00000) is the one that works:
+
+  Not "is any of this wrong?" — that question elicits binary defence and
+  the model defends the artefact as emitted.
+
+  Instead, ask of each list / each claim / each register choice in the
+  artefact:
+    (a) What is the gradient this decision sits on?
+        e.g. item-substantiveness, public-appropriateness, verifiable-vs-
+        speculative, novel-vs-already-documented, gradient-flag-quality.
+    (b) Which items in the artefact collapse into the substantive end of
+        the gradient on second-pass review? Which collapse into the trivial
+        end?
+    (c) Reproduce the artefact with the gradient applied — keep what
+        survives, drop or rephrase what does not.
+
+Then re-emit. If the re-emitted artefact is structurally different from this
+one, that is the gate working. If the re-emitted artefact is byte-identical
+to this one and you have considered the gradient and stand by every decision,
+re-running the same command within ${CACHE_TTL}s will ship it (the hash
+matches and the gate passes through).
+
+To disable this gate intentionally (for low-stakes commits, automated tooling,
+non-public artefacts mis-classified as public), set CC_SOCRATIC_DISABLE=1 in
+your environment, or refine CC_SOCRATIC_BASH_PATTERNS / CC_SOCRATIC_FILE_PATTERNS
+to exclude the false-positive class.
+
+Underlying mechanism (per @suwayama #60188): binary-collapse of decisions
+that should sit on a gradient. The reminder above is the operator-language
+intervention promoted to a tooling-side gate; the gradient framing is what
+makes it work, not the blocking.
+</system-reminder>
+EOF
+
+exit 2

package/examples/public-repo-push-guard.sh

@@ -17,6 +17,18 @@
 
 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-public-repo-push-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [public-repo-push-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/push-requires-test-pass.sh

@@ -27,6 +27,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-push-requires-test-pass-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [push-requires-test-pass]: 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)
 

package/examples/quota-anomaly-detector.sh

@@ -0,0 +1,173 @@
+#!/bin/bash
+# quota-anomaly-detector.sh — alert when token consumption rate diverges from your personal baseline
+#
+# Why: The Pro Max quota anomaly cluster (#16157 / #38335 / #45756 / #41788 / #29579
+#      / #19673 / cumulative ~1,600 reactions) reports the same operator-side symptom:
+#      the quota empties materially faster than the same workflow used to consume it,
+#      sometimes within minutes of the session starting. Four issues name a runtime
+#      version or date boundary (2026-03-23 / v2.1.89 / v2.1.100 / 2.1.1) so the
+#      shift is version-correlated.
+#
+#      cache-creation-drift-detector.sh catches the *per-request* server-side
+#      inflation documented in #46917, but it cannot see the cross-request picture:
+#      a session that fires 40 small requests in 10 minutes burns the same quota as
+#      one large request, and only the rolling rate exposes it. This hook fills that
+#      gap by tracking total tokens-per-minute against a personal trailing baseline.
+#
+#      Composes with cache-creation-drift-detector (per-request) and the existing
+#      session-quota-tracker.sh (raw tool-call count, no token weight).
+#
+# Event: PostToolUse  MATCHER: "" (all tools)
+# Action: Sum input_tokens + output_tokens + cache_read_input_tokens +
+#         cache_creation_input_tokens from the PostToolUse payload (or last
+#         assistant turn in the transcript as fallback). Append a timestamped
+#         sample to a rolling JSONL log. Compute the operator's tokens-per-minute
+#         over the trailing window. If the current window's rate exceeds the
+#         trailing baseline by a configurable multiplier, emit a one-line stderr
+#         warning. Advisory only (exit 0); does not block.
+#
+# Configuration (all optional):
+#   CC_QUOTA_ANOMALY_LOG          Log path (default: ~/.cache/cc-safe-setup/quota-anomaly.jsonl)
+#   CC_QUOTA_ANOMALY_THRESHOLD    Multiplier for alert (default: 1.5 = 50% above baseline rate)
+#   CC_QUOTA_ANOMALY_MIN_HISTORY  Minimum samples before alerting (default: 30)
+#   CC_QUOTA_ANOMALY_WINDOW_MIN   Current-rate window in minutes (default: 10)
+#   CC_QUOTA_ANOMALY_BASELINE_MIN Baseline window in minutes (default: 1440 = 24h)
+#   CC_QUOTA_ANOMALY_SILENT       Set to "1" to suppress stderr (still logs)
+#
+# Inspect the log:
+#   tail -50 ~/.cache/cc-safe-setup/quota-anomaly.jsonl
+#   jq -s 'map(.total) | add' ~/.cache/cc-safe-setup/quota-anomaly.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_QUOTA_ANOMALY_LOG:-${HOME}/.cache/cc-safe-setup/quota-anomaly.jsonl}"
+THRESHOLD="${CC_QUOTA_ANOMALY_THRESHOLD:-1.5}"
+MIN_HISTORY="${CC_QUOTA_ANOMALY_MIN_HISTORY:-30}"
+WINDOW_MIN="${CC_QUOTA_ANOMALY_WINDOW_MIN:-10}"
+BASELINE_MIN="${CC_QUOTA_ANOMALY_BASELINE_MIN:-1440}"
+SILENT="${CC_QUOTA_ANOMALY_SILENT:-0}"
+
+mkdir -p "$(dirname "$LOG")" 2>/dev/null
+
+INPUT=$(cat)
+
+extract_total() {
+  # $1 = jq path prefix to usage object
+  local prefix="$1"
+  printf '%s' "$INPUT" | jq -r --arg p "$prefix" '
+    def num(x): if (x | type) == "number" then x else 0 end;
+    ($p | split(".") | map(select(length > 0))) as $path |
+    (getpath($path)) as $u |
+    if $u == null then empty
+    else
+      (num($u.input_tokens) + num($u.output_tokens) +
+       num($u.cache_read_input_tokens) + num($u.cache_creation_input_tokens))
+    end
+  ' 2>/dev/null
+}
+
+# Try PostToolUse payload first.
+TOTAL=$(extract_total ".tool_response.usage")
+
+# Fallback: read the last assistant turn's usage from the transcript.
+if [ -z "$TOTAL" ] || [ "$TOTAL" = "0" ]; then
+  TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+  if [ -n "$TRANSCRIPT" ] && [ -r "$TRANSCRIPT" ]; then
+    LAST_USAGE_LINE=$(tac "$TRANSCRIPT" 2>/dev/null | grep -m1 '"usage"' || true)
+    if [ -n "$LAST_USAGE_LINE" ]; then
+      TOTAL=$(printf '%s' "$LAST_USAGE_LINE" | jq -r '
+        def num(x): if (x | type) == "number" then x else 0 end;
+        (.message.usage // .usage // null) as $u |
+        if $u == null then empty
+        else
+          (num($u.input_tokens) + num($u.output_tokens) +
+           num($u.cache_read_input_tokens) + num($u.cache_creation_input_tokens))
+        end
+      ' 2>/dev/null)
+    fi
+  fi
+fi
+
+# No usable measurement.
+if [ -z "$TOTAL" ] || [ "$TOTAL" = "0" ] || [ "$TOTAL" = "null" ]; then
+  exit 0
+fi
+
+# Validate positive integer.
+case "$TOTAL" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)
+NOW_EPOCH=$(date -u +%s)
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Append sample.
+printf '{"ts":"%s","epoch":%s,"session":"%s","total":%s}\n' \
+  "$TS" "$NOW_EPOCH" "$SESSION_ID" "$TOTAL" >> "$LOG"
+
+# Need MIN_HISTORY samples before trusting the baseline.
+SAMPLE_COUNT=$(wc -l < "$LOG" 2>/dev/null | tr -d ' ')
+SAMPLE_COUNT="${SAMPLE_COUNT:-0}"
+if [ "$SAMPLE_COUNT" -lt "$MIN_HISTORY" ]; then
+  exit 0
+fi
+
+# Compute current window sum and baseline window sum.
+WINDOW_CUTOFF=$((NOW_EPOCH - WINDOW_MIN * 60))
+BASELINE_CUTOFF=$((NOW_EPOCH - BASELINE_MIN * 60))
+
+# Read once, compute both sums and counts.
+SUMS=$(awk -v wc="$WINDOW_CUTOFF" -v bc="$BASELINE_CUTOFF" '
+  /"epoch":/ {
+    # Extract epoch and total via simple field parse (matches our writer format).
+    match($0, /"epoch":[0-9]+/)
+    e = substr($0, RSTART+8, RLENGTH-8) + 0
+    match($0, /"total":[0-9]+/)
+    t = substr($0, RSTART+8, RLENGTH-8) + 0
+    if (e >= bc) {
+      bs += t; bn++
+      if (e >= wc) { ws += t; wn++ }
+    }
+  }
+  END { printf "%d %d %d %d", ws, wn, bs, bn }
+' "$LOG" 2>/dev/null)
+
+WINDOW_SUM=$(echo "$SUMS" | awk '{print $1}')
+WINDOW_N=$(echo "$SUMS" | awk '{print $2}')
+BASELINE_SUM=$(echo "$SUMS" | awk '{print $3}')
+BASELINE_N=$(echo "$SUMS" | awk '{print $4}')
+
+# Need enough activity in both windows.
+if [ "${WINDOW_N:-0}" -lt 2 ] || [ "${BASELINE_N:-0}" -lt "$MIN_HISTORY" ]; then
+  exit 0
+fi
+
+# Compute rates: tokens per minute in each window.
+RATIO=$(awk -v ws="$WINDOW_SUM" -v wm="$WINDOW_MIN" \
+            -v bs="$BASELINE_SUM" -v bm="$BASELINE_MIN" '
+  BEGIN {
+    wr = ws / wm
+    br = bs / bm
+    if (br > 0) printf "%.3f", wr / br; else print "0"
+  }')
+EXCEEDS=$(awk -v r="$RATIO" -v t="$THRESHOLD" 'BEGIN { print (r > t) ? 1 : 0 }')
+
+if [ "$EXCEEDS" = "1" ] && [ "$SILENT" != "1" ]; then
+  WIN_RATE=$(awk -v ws="$WINDOW_SUM" -v wm="$WINDOW_MIN" 'BEGIN { printf "%d", ws/wm }')
+  BASE_RATE=$(awk -v bs="$BASELINE_SUM" -v bm="$BASELINE_MIN" 'BEGIN { printf "%d", bs/bm }')
+  PCT=$(awk -v r="$RATIO" 'BEGIN { printf "%d", (r - 1) * 100 }')
+  echo "NOTICE: token consumption rate ~${WIN_RATE} tok/min over last ${WINDOW_MIN}min is ${PCT}% above your ${BASELINE_MIN}min baseline (~${BASE_RATE} tok/min)." >&2
+  echo "        Pro Max quota anomaly cluster: anthropics/claude-code #16157 / #38335 / #45756." >&2
+  echo "        Inspect ${LOG} or set CC_QUOTA_ANOMALY_SILENT=1 to suppress." >&2
+fi
+
+exit 0

package/examples/quota-reset-audit.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# quota-reset-audit.sh — weekly quota reset cluster logger (Incident 9)
+# Why: On 2026-04-23 users reported /usage showing quota available while
+#      sessions were being rate-limited. Client-side vs server-side
+#      timezone handling of the weekly reset diverged. The dashboard's
+#      resets_at value is the only ground truth available to users, and
+#      a log of resets_at at each session start is the only way to prove
+#      "the dashboard said X, the actual reset happened Y."
+# Event: SessionStart
+# Action: Capture /usage --json at session start. Log the timestamp,
+#         resets_at, and percent-used to ~/.claude/logs/usage-audit.log.
+#         If /usage is unavailable (pre-v2.1.118) log a placeholder so the
+#         session never fails because of the hook.
+
+set -u
+
+LOG_DIR="${HOME}/.claude/logs"
+LOG_FILE="${LOG_DIR}/usage-audit.log"
+mkdir -p "$LOG_DIR" 2>/dev/null
+
+INPUT=$(cat 2>/dev/null || true)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)
+
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+fetch_usage() {
+  # Prefer the claude CLI subcommand when available (v2.1.118+ shipped
+  # /usage with --json output). Fall back to `claude usage --json` which
+  # some earlier builds exposed. If neither works, return empty.
+  local out=""
+  if command -v claude >/dev/null 2>&1; then
+    out=$(timeout 5 claude /usage --json 2>/dev/null || true)
+    if [ -z "$out" ] || ! printf '%s' "$out" | jq -e . >/dev/null 2>&1; then
+      out=$(timeout 5 claude usage --json 2>/dev/null || true)
+    fi
+  fi
+  printf '%s' "$out"
+}
+
+USAGE_JSON=$(fetch_usage)
+
+if [ -z "$USAGE_JSON" ] || ! printf '%s' "$USAGE_JSON" | jq -e . >/dev/null 2>&1; then
+  printf '%s\t%s\t%s\t%s\t%s\n' \
+    "$TS" "$SESSION_ID" "unavailable" "unavailable" "unavailable" \
+    >> "$LOG_FILE"
+  exit 0
+fi
+
+# Expected /usage fields vary by CC version. Pull common ones defensively.
+RESETS_AT=$(printf '%s' "$USAGE_JSON" | jq -r '.weekly.resets_at // .resets_at // .weeklyResetsAt // "unknown"' 2>/dev/null)
+PCT_USED=$(printf '%s' "$USAGE_JSON" | jq -r '.weekly.percent_used // .percent_used // .weeklyPercentUsed // "unknown"' 2>/dev/null)
+TIER=$(printf '%s' "$USAGE_JSON" | jq -r '.tier // .plan // "unknown"' 2>/dev/null)
+
+printf '%s\t%s\t%s\t%s\t%s\n' \
+  "$TS" "$SESSION_ID" "$TIER" "$RESETS_AT" "$PCT_USED" \
+  >> "$LOG_FILE"
+
+exit 0