cc-safe-setup 29.8.0 → 30.0.5

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

package/examples/quoted-flag-approver.sh

@@ -10,7 +10,7 @@
 # trigger a confirmation prompt even when they match allowlist patterns.
 #
 # This PermissionRequest hook auto-approves these prompts when:
-# 1. The base command is in a safe list
+# 1. Every command position is in a safe list
 # 2. The only "issue" is quoted characters in flag values
 #
 # TRIGGER: PermissionRequest
@@ -25,6 +25,25 @@
 #     }]
 #   }
 # }
+#
+# Fixed 2026-08-03. The safe list held bare command *words* — `git`, `curl`,
+# `chmod`, `sed`, `node`, `python3`, `npx` — and a word says nothing about what
+# the command does. `git commit -m "fix"` and `git push --force origin main`
+# have the same first word.
+#
+# Measured against the shipped copy, over 20 destructive or credential-reading
+# commands with no separator in them at all: **15 were approved**, among them
+# `git push --force`, `git reset --hard`, `git clean -fdx`, `chmod -R 777 /`,
+# `curl … | sh`, `node -e '…rmSync…'` and `cat ~/.aws/credentials`.
+#
+# This is a different defect from the first-command-position one repaired in
+# #937/#940/#941/#942/#943/#947, and mixing the two would produce a number that
+# looks right and is not: nothing here was hiding past a separator. The
+# granularity of the list was the problem. (The first-position defect was here
+# too, and is fixed in the same pass.)
+#
+# Known limit: quotes are not parsed when splitting, so a separator inside a
+# quoted string ends a segment early. That errs toward fewer approvals.
 
 INPUT=$(cat)
 
@@ -36,16 +55,86 @@ echo "$MESSAGE" | grep -qi "quoted characters in flag" || exit 0
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 
-# Safe base commands — customize for your project
-SAFE_COMMANDS="git|npm|npx|bun|yarn|pnpm|docker|make|cargo|go|pip|python3|node|tsc|eslint|prettier|jest|vitest|pytest|curl|wget|rsync|tar|zip|unzip|cp|mv|mkdir|cat|echo|grep|find|ls|chmod|sed|awk"
+# A substitution or backtick carries a command no string-level read can see.
+# This hook is about quoted flag values, not substitution, so it refuses them.
+case "$COMMAND" in
+    *'$('*|*'`'*) exit 0 ;;
+esac
+
+# Command words that carry no destructive form of their own. Anything that
+# takes code as an argument (`node -e`, `python3 -c`, `npx`) or fetches and runs
+# (`curl`, `wget`) is deliberately absent: for those the word says nothing.
+cc_base_ok() {
+    case "$1" in
+        cat|head|tail|less|more|wc|file|stat|du|df|ls|tree|\
+        which|whereis|type|realpath|readlink|basename|dirname|\
+        grep|rg|ag|ack|sort|uniq|tr|cut|column|nl|rev|awk|\
+        echo|printf|true|false|pwd|date|uname|hostname|whoami|id|\
+        jq|yq|cd|\
+        tsc|eslint|prettier|jest|vitest|pytest)
+            return 0 ;;
+    esac
+    return 1
+}
+
+# Build tool subcommands that neither destroy history nor run fetched code.
+# One line on purpose: inside single quotes a trailing backslash is a literal
+# backslash-newline, not a continuation, and the pattern silently stops matching.
+CC_SUBCMD_RE='^[[:space:]]*(git[[:space:]]+(status|log|diff|show|add|commit|branch|remote|describe|rev-parse|blame|shortlog|ls-files|ls-tree|fetch|stash[[:space:]]+(list|push|save))|npm[[:space:]]+(test|run|ci|ls|view|outdated)|yarn[[:space:]]+(test|run|info|why)|pnpm[[:space:]]+(test|run|list|why)|bun[[:space:]]+(test|run)|cargo[[:space:]]+(build|test|check|fmt|clippy|tree)|go[[:space:]]+(build|test|vet|fmt|list)|docker[[:space:]]+(ps|images|logs|inspect|version|info)|make[[:space:]]+[A-Za-z0-9_.-]+|pip[[:space:]]+(list|show|freeze)|python3[[:space:]]+-m[[:space:]]+(pytest|unittest|pip[[:space:]]+(list|show|freeze)))([[:space:]]|$)'
+
+cc_subcommand_ok() {
+    printf '%s' "$1" | grep -qE "$CC_SUBCMD_RE"
+}
+
+cc_segment_base() {
+    printf '%s' "$1" \
+        | sed -E 's/^[[:space:]]+//; s/^([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*//' \
+        | awk '{print $1}' \
+        | sed 's|.*/||'
+}
+
+# `git branch` reads; `git branch -D main` deletes one. Same first two words.
+CC_GIT_DESTRUCTIVE_RE='^[[:space:]]*git[[:space:]]+(branch|tag)[[:space:]]+-([dDmM]|-delete|-move)([[:space:]]|$)'
+
+cc_segment_ok() {
+    local seg="$1" base
+    base=$(cc_segment_base "$seg")
+    [ -z "$base" ] && return 1
+
+    if [ "$base" = "find" ]; then
+        printf '%s' "$seg" \
+            | grep -qE '(^|[[:space:]])-(delete|exec|execdir|ok|okdir|fprintf?|fls|fprint0)([[:space:]]|$)' \
+            && return 1
+        return 0
+    fi
+    if [ "$base" = "sed" ]; then
+        printf '%s' "$seg" | grep -qE '(^|[[:space:]])-[a-zA-Z]*i' && return 1
+        return 0
+    fi
+
+    cc_base_ok "$base" && return 0
+    printf '%s' "$seg" | grep -qE "$CC_GIT_DESTRUCTIVE_RE" && return 1
+    cc_subcommand_ok "$seg" && return 0
+    return 1
+}
+
+# A redirection writes a file, whatever the command word says.
+case "$COMMAND" in
+    *'>'*) exit 0 ;;
+esac
 
-# Extract base command (first word, ignoring env vars and path)
-BASE_CMD=$(echo "$COMMAND" | sed 's/^[A-Z_]*=[^ ]* //' | awk '{print $1}' | sed 's|.*/||')
+IDX=0
+while IFS= read -r SEG; do
+    SEG="${SEG#"${SEG%%[![:space:]]*}"}"
+    SEG="${SEG%"${SEG##*[![:space:]]}"}"
+    [ -z "$SEG" ] && continue
+    cc_segment_ok "$SEG" || exit 0
+    IDX=$((IDX + 1))
+done <<EOF
+$(printf '%s' "$COMMAND" | tr ';&|' '\n\n\n')
+EOF
 
-if echo "$BASE_CMD" | grep -qE "^($SAFE_COMMANDS)$"; then
-  echo '{"permissionDecision":"allow"}'
-  exit 0
-fi
+[ "$IDX" -eq 0 ] && exit 0
 
-# Unknown command — let the prompt through
+echo '{"permissionDecision":"allow"}'
 exit 0

package/examples/rails-migration-guard.sh

@@ -19,6 +19,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-rails-migration-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [rails-migration-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)