cc-safe-setup 29.7.0 → 30.0.4

package/examples/session-persistence-verifier.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+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-session-persistence-verifier-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [session-persistence-verifier]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+if [ "${CC_PERSISTENCE_CHECK_DISABLE:-0}" = "1" ]; then
+    exit 0
+fi
+INPUT=$(cat 2>/dev/null || echo '{}')
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+if [ -z "$SESSION_ID" ]; then
+    exit 0
+fi
+SESSION_DIR="${CC_PERSISTENCE_CHECK_DIR:-${HOME}/.claude/projects}"
+JSONL_FILE=""
+if [ -d "$SESSION_DIR" ]; then
+    JSONL_FILE=$(find "$SESSION_DIR" -maxdepth 3 -name "${SESSION_ID}.jsonl" -type f 2>/dev/null | head -1)
+fi
+REQUIRED_REGEX="${CC_PERSISTENCE_REQUIRED:-\"type\":\"(queue-operation|user|assistant)\"}"
+if [ -z "$JSONL_FILE" ] || [ ! -f "$JSONL_FILE" ]; then
+    if [ "${CC_PERSISTENCE_STRICT:-0}" = "1" ]; then
+        cat >&2 << EOF
+[session-persistence-verifier] Session JSONL file not found for session ${SESSION_ID}.
+The harness may not be persisting this conversation to disk. If this is unexpected:
+  1. Back up the in-memory transcript NOW (copy/paste from sidebar to a file)
+  2. Check ~/.claude/projects/ for the expected file path
+  3. If on 2.1.144/2.1.145, consider downgrading to 2.1.143 (see #60984)
+  4. If on the native installer era (2.1.168-2.1.170), a separate write-path
+     break is reported (#66486, partially patched in 2.1.170; #66734). It can
+     hit interactive sessions while spawned/headless sessions persist fine, and
+     can outlive an on-disk binary upgrade because the broken state lives in a
+     long-running process. Fully quit ALL Claude Code instances and relaunch --
+     a fresh launch has restored persistence per those reports.
+CC_PERSISTENCE_CHECK_DISABLE=1 to skip this check.
+EOF
+        exit 2
+    fi
+    exit 0
+fi
+if [ ! -s "$JSONL_FILE" ]; then
+    cat >&2 << EOF
+[session-persistence-verifier] Session JSONL file is empty: ${JSONL_FILE}
+This matches a JSONL writer regression. Two reported windows:
+  - #60984 (2.1.144/2.1.145): downgrade to 2.1.143 (last-known-good).
+  - #66486 / #66734 (native installer era, 2.1.168-2.1.170): the break can
+    outlive an on-disk binary upgrade because it lives in a long-running
+    process; fully quit ALL Claude Code instances and relaunch.
+  1. Back up the in-memory transcript NOW (copy/paste from sidebar to a file)
+  2. Verify your version: claude --version
+  3. Apply the matching fix above for your version window
+  4. A mirror backup of ~/.claude/projects/**/*.jsonl (size-comparison skip)
+     preserves transcripts before an empty file can overwrite them
+CC_PERSISTENCE_CHECK_DISABLE=1 to skip this check.
+EOF
+    exit 2
+fi
+if ! grep -qE "$REQUIRED_REGEX" "$JSONL_FILE" 2>/dev/null; then
+    has_ai_title=$(grep -c '"type":"ai-title"' "$JSONL_FILE" 2>/dev/null || echo 0)
+    line_count=$(wc -l < "$JSONL_FILE" 2>/dev/null || echo 0)
+    cat >&2 << EOF
+[session-persistence-verifier] Session JSONL contains no message content: ${JSONL_FILE}
+Found ${line_count} lines, of which ${has_ai_title} are ai-title entries.
+Missing event types: queue-operation, user, assistant.
+This is a metadata-only stub: the file exists but holds no conversation. Two
+reported windows produce this shape:
+  - #60984 (2.1.144/2.1.145): JSONL writer broken; downgrade to 2.1.143.
+  - #66486 / #66734 (native installer era, 2.1.168-2.1.170): interactive
+    sessions stub out while spawned/headless sessions persist fine, and the
+    break can outlive an on-disk binary upgrade (it lives in a long-running
+    process). Fully quit ALL Claude Code instances and relaunch; a fresh launch
+    has restored persistence per those reports.
+Sidebar history for this session will appear empty.
+Action items (do this before exiting):
+  1. Back up the in-memory transcript NOW (copy/paste from sidebar to a file)
+  2. Verify your version: claude --version
+  3. Apply the matching fix above for your version window
+  4. A mirror backup of ~/.claude/projects/**/*.jsonl (size-comparison skip)
+     preserves transcripts before a stub can overwrite them
+CC_PERSISTENCE_CHECK_DISABLE=1 to skip this check.
+CC_PERSISTENCE_REQUIRED='custom-regex' to override the required event types.
+EOF
+    exit 2
+fi
+exit 0

package/examples/session-plugin-pin-watch.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# ================================================================
+# session-plugin-pin-watch.sh — Detect when a marketplace plugin's pinned hooks silently die
+# ================================================================
+# PURPOSE:
+#   A running session's plugin hooks are pinned to the plugin version's
+#   install path at session start. When a marketplace plugin is updated
+#   mid-session, re-materialization removes that old versioned path, so the
+#   pinned hook commands become unreachable and silently stop firing — no
+#   error, no warning (anthropics/claude-code#73952). Recovery is
+#   /reload-plugins or a restart, but nothing tells you the hooks died.
+#
+# HOW IT WORKS:
+#   settings.json hooks are NOT plugin-pinned (they are read from
+#   settings.json, which re-materialization never touches), so they keep
+#   firing and can watch for the plugin-level failure. Register this one
+#   script on TWO events:
+#     - SessionStart: snapshot the plugin version dirs that exist now.
+#     - PreToolUse:   if any snapshotted dir has since vanished, the
+#                     session's pinned hooks for that plugin are dead -> warn
+#                     (and suggest /reload-plugins). State is refreshed after
+#                     a warning so it only re-warns on the NEXT disappearance.
+#   The warning is emitted via {"systemMessage": ...} so it surfaces to the
+#   user without blocking the session.
+#
+# TRIGGER: SessionStart, and PreToolUse
+# MATCHER: PreToolUse "*" (any tool call acts as the heartbeat)
+#
+# CONFIGURATION:
+#   CC_PLUGIN_WATCH_GLOB — glob for your plugin's versioned install dirs.
+#                          Default: $HOME/.claude/plugins/*/*/* (a guess;
+#                          point it at your actual cache layout).
+# ================================================================
+set -uo pipefail
+
+WATCH_GLOB="${CC_PLUGIN_WATCH_GLOB:-$HOME/.claude/plugins/*/*/*}"
+input=$(cat)
+event=$(printf '%s' "$input" | jq -r '.hook_event_name // empty' 2>/dev/null)
+sid=$(printf '%s' "$input" | jq -r '.session_id // "nosid"' 2>/dev/null)
+state="${HOME}/.claude/plugin-pin-watch/${sid}.paths"
+mkdir -p "$(dirname "$state")"
+
+# Expand the glob and keep only directories that actually exist, one per line.
+list_dirs() {
+    local g="$1" p
+    # shellcheck disable=SC2086
+    for p in $g; do [ -d "$p" ] && printf '%s\n' "$p"; done
+}
+
+case "$event" in
+    SessionStart)
+        list_dirs "$WATCH_GLOB" | sort -u > "$state"
+        exit 0
+        ;;
+    *)
+        [ -f "$state" ] || exit 0
+        missing=""
+        while IFS= read -r d; do
+            [ -n "$d" ] && [ ! -d "$d" ] && missing="${missing}\n  - ${d}"
+        done < "$state"
+        if [ -n "$missing" ]; then
+            msg="⚠ A plugin version dir present at session start is gone. Marketplace re-materialization may have silently killed this session's pinned hooks (#73952). Run /reload-plugins to rebind, or restart. Missing:$(printf '%b' "$missing")"
+            jq -cn --arg m "$msg" '{systemMessage:$m}'
+            list_dirs "$WATCH_GLOB" | sort -u > "$state"
+        fi
+        exit 0
+        ;;
+esac

package/examples/session-rate-monitor.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+# session-rate-monitor.sh — alert when a single session's token burn rate exceeds an absolute ceiling
+#
+# Why: The Pro Max quota anomaly cluster (#16157 / #38335 / #45756 / #41788 /
+#      #29579 / #19673) repeatedly reports the same scenario: a session that
+#      hits the usage limit within minutes of starting, before the operator
+#      has any chance to see a per-request drift signal or a cross-session
+#      rolling-baseline divergence. The two earlier hooks in this family
+#      need historical samples before they can speak:
+#
+#        - cache-creation-drift-detector.sh needs a 200-sample trailing window
+#          and only triggers on per-request server-side inflation (#46917).
+#        - quota-anomaly-detector.sh needs 30+ samples and a 24-hour baseline
+#          before it has a personal rate to compare against.
+#
+#      Neither catches a brand-new session that burns 100K tokens in the
+#      first five minutes. This hook closes that gap by tracking per-session
+#      elapsed-time and cumulative tokens, then alerting against an absolute
+#      tokens-per-minute ceiling. No baseline required; works from request 1.
+#
+#      Composes with cache-creation-drift-detector (per-request) and
+#      quota-anomaly-detector (cross-session). Three orthogonal signals,
+#      three latencies: per-request → per-session → cross-session.
+#
+# Event: PostToolUse  MATCHER: "" (all tools)
+# Action: Sum input + output + cache_read + cache_creation tokens from each
+#         PostToolUse payload. Maintain per-session state in a small file
+#         keyed by session_id, accumulating start_epoch, total_tokens, and
+#         sample_count. Compute current rate = total_tokens / minutes_elapsed
+#         and emit a one-line stderr warning when it exceeds an absolute
+#         threshold (default 50,000 tok/min). Re-alerts at most once every
+#         N minutes to avoid spam. Advisory only (exit 0); does not block.
+#
+# Configuration (all optional):
+#   CC_SESSION_RATE_DIR          State dir (default: ~/.cache/cc-safe-setup/session-rate)
+#   CC_SESSION_RATE_THRESHOLD    Alert ceiling in tokens/minute (default: 50000)
+#   CC_SESSION_RATE_MIN_SAMPLES  Minimum samples before alerting (default: 5)
+#   CC_SESSION_RATE_MIN_ELAPSED  Minimum session-elapsed seconds before alerting (default: 60)
+#   CC_SESSION_RATE_REPEAT_MIN   Suppress repeat alerts for N minutes (default: 5)
+#   CC_SESSION_RATE_SILENT       Set to "1" to suppress stderr (still tracks)
+#
+# Inspect state:
+#   ls -la ~/.cache/cc-safe-setup/session-rate/
+#   cat ~/.cache/cc-safe-setup/session-rate/<session_id>
+#
+# 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
+
+STATE_DIR="${CC_SESSION_RATE_DIR:-${HOME}/.cache/cc-safe-setup/session-rate}"
+THRESHOLD="${CC_SESSION_RATE_THRESHOLD:-50000}"
+MIN_SAMPLES="${CC_SESSION_RATE_MIN_SAMPLES:-5}"
+MIN_ELAPSED="${CC_SESSION_RATE_MIN_ELAPSED:-60}"
+REPEAT_MIN="${CC_SESSION_RATE_REPEAT_MIN:-5}"
+SILENT="${CC_SESSION_RATE_SILENT:-0}"
+
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+INPUT=$(cat)
+
+# Extract session_id; if missing, we can't track per-session state.
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+if [ -z "$SESSION_ID" ] || [ "$SESSION_ID" = "null" ]; then
+  exit 0
+fi
+
+# Sanitize session_id for use as a filename (allow alnum, dash, underscore).
+SAFE_ID=$(printf '%s' "$SESSION_ID" | tr -c 'A-Za-z0-9_-' '_' | cut -c1-128)
+STATE_FILE="$STATE_DIR/$SAFE_ID"
+
+# Sum the four token fields from PostToolUse payload.
+TOTAL=$(printf '%s' "$INPUT" | jq -r '
+  def num(x): if (x | type) == "number" then x else 0 end;
+  (.tool_response.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)
+
+# 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
+
+if [ -z "$TOTAL" ] || [ "$TOTAL" = "0" ] || [ "$TOTAL" = "null" ]; then
+  exit 0
+fi
+
+case "$TOTAL" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+
+NOW_EPOCH=$(date -u +%s)
+
+# Read existing state or initialize. State format (single line, space-separated):
+#   start_epoch total_tokens sample_count last_alert_epoch
+if [ -f "$STATE_FILE" ]; then
+  read -r START_EPOCH OLD_TOTAL OLD_COUNT LAST_ALERT < "$STATE_FILE" 2>/dev/null
+  START_EPOCH="${START_EPOCH:-$NOW_EPOCH}"
+  OLD_TOTAL="${OLD_TOTAL:-0}"
+  OLD_COUNT="${OLD_COUNT:-0}"
+  LAST_ALERT="${LAST_ALERT:-0}"
+else
+  START_EPOCH="$NOW_EPOCH"
+  OLD_TOTAL=0
+  OLD_COUNT=0
+  LAST_ALERT=0
+fi
+
+NEW_TOTAL=$((OLD_TOTAL + TOTAL))
+NEW_COUNT=$((OLD_COUNT + 1))
+ELAPSED=$((NOW_EPOCH - START_EPOCH))
+
+# Write updated state (preserve LAST_ALERT for now; updated below on alert).
+printf '%s %s %s %s\n' "$START_EPOCH" "$NEW_TOTAL" "$NEW_COUNT" "$LAST_ALERT" > "$STATE_FILE"
+
+# Need enough samples and enough elapsed time before computing a rate.
+if [ "$NEW_COUNT" -lt "$MIN_SAMPLES" ]; then
+  exit 0
+fi
+if [ "$ELAPSED" -lt "$MIN_ELAPSED" ]; then
+  exit 0
+fi
+
+# Compute rate in tokens/minute. Use awk for float division.
+RATE=$(awk -v t="$NEW_TOTAL" -v e="$ELAPSED" 'BEGIN { if (e > 0) printf "%.0f", t * 60 / e; else print "0" }')
+
+# Compare against threshold.
+EXCEEDS=$(awk -v r="$RATE" -v th="$THRESHOLD" 'BEGIN { print (r > th) ? 1 : 0 }')
+if [ "$EXCEEDS" != "1" ]; then
+  exit 0
+fi
+
+# Repeat-alert suppression: only re-alert every REPEAT_MIN minutes.
+SINCE_LAST=$((NOW_EPOCH - LAST_ALERT))
+REPEAT_SEC=$((REPEAT_MIN * 60))
+if [ "$LAST_ALERT" != "0" ] && [ "$SINCE_LAST" -lt "$REPEAT_SEC" ]; then
+  exit 0
+fi
+
+# Record this alert time.
+printf '%s %s %s %s\n' "$START_EPOCH" "$NEW_TOTAL" "$NEW_COUNT" "$NOW_EPOCH" > "$STATE_FILE"
+
+if [ "$SILENT" = "1" ]; then
+  exit 0
+fi
+
+ELAPSED_MIN=$(awk -v e="$ELAPSED" 'BEGIN { printf "%.1f", e / 60 }')
+echo "NOTICE: session burning ~${RATE} tok/min over the first ${ELAPSED_MIN}min (${NEW_TOTAL} tokens, ${NEW_COUNT} requests)." >&2
+echo "        This exceeds the ${THRESHOLD} tok/min ceiling — at this rate a Max-5x daily quota empties fast." >&2
+echo "        Pro Max quota anomaly cluster: anthropics/claude-code #16157 / #38335 / #45756 / #41788." >&2
+echo "        Adjust ceiling with CC_SESSION_RATE_THRESHOLD or silence with CC_SESSION_RATE_SILENT=1." >&2
+
+exit 0

package/examples/session-start-quota-status.sh

@@ -0,0 +1,193 @@
+#!/bin/bash
+# session-start-quota-status.sh — Compute a real-time approximation of the
+# operator's recent token usage from local JSONL transcripts and surface it
+# to Claude Code at session start, so the operator sees their quota
+# posture before issuing the first prompt.
+#
+# Addresses the cluster of issues for which Anthropic does not provide a
+# native dashboard:
+#
+#   #16157 (1470+ comments) — "Instantly hitting usage limits with Max
+#                              subscription"
+#   #38335 (723+ comments)  — "Claude Max plan session limits exhausted
+#                              abnormally fast"
+#   #29579 (150+ comments)  — "Rate limit reached despite Claude Max
+#                              subscription and only 16% usage"
+#
+# The web-search summary from 2026-05 named the gap explicitly:
+#   "There's no official dashboard that shows weekly-cap status in real
+#    time, and this gap is one of the most recurring complaints from
+#    power users in Anthropic forums."
+#
+# This hook is the operator-side stopgap. It reads
+# `~/.claude/projects/*/[session-id].jsonl` files modified in the last
+# 5 hours (rolling-window approximation of the Anthropic 5-hour cap)
+# and the last 7 days (rolling-window approximation of the weekly cap),
+# sums the input/output/cache tokens by model, computes an estimated
+# dollar-cost at standard API rates, and emits a <system-reminder>
+# surfacing the totals.
+#
+# Important caveats — read these before relying on the numbers:
+#
+# 1. Anthropic's real cap is not directly observable from local
+#    transcripts. The hook uses a rolling-window approximation that
+#    correlates with cap consumption but does not equal it.
+# 2. Subscription quota is consumed at SUBSCRIPTION rates, not API
+#    rates. The dollar figures the hook emits are the EQUIVALENT API
+#    cost — useful for comparing against the subscription credit pool
+#    (especially the June-15-and-after Pool 2 credit) but not directly
+#    equal to what the subscription "spent" against the quota.
+# 3. The 5-hour window calculation is wall-clock-based on file mtime,
+#    not based on Anthropic's actual reset timing.
+# 4. The hook is non-blocking. It surfaces information; it does not
+#    refuse the session.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# CONFIGURATION (environment variables):
+#   CC_QUOTA_5H_WARN_USD       default 5.0 — emit a warning if 5-hour
+#                                            equivalent-API-cost exceeds this
+#   CC_QUOTA_WEEKLY_WARN_USD   default 50.0 — same for weekly
+#   CC_QUOTA_PROJECTS_DIR      default ~/.claude/projects — JSONL roots
+#   CC_QUOTA_STATUS_DISABLE    set "1" to disable the hook entirely
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "SessionStart": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/session-start-quota-status.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+set -uo pipefail
+
+[ "${CC_QUOTA_STATUS_DISABLE:-0}" = "1" ] && exit 0
+
+PROJECTS_DIR="${CC_QUOTA_PROJECTS_DIR:-$HOME/.claude/projects}"
+WARN_5H="${CC_QUOTA_5H_WARN_USD:-5.0}"
+WARN_WEEKLY="${CC_QUOTA_WEEKLY_WARN_USD:-50.0}"
+
+[ ! -d "$PROJECTS_DIR" ] && exit 0  # No projects directory → silent no-op.
+
+# Need jq for JSONL parsing; awk for aggregation.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Compute the rolling sums for one window in minutes.
+# Returns lines: "model:input:output:cache_read:cache_write:dollars"
+compute_window() {
+    local window_minutes="$1"
+    local out
+
+    out=$(find "$PROJECTS_DIR" -name '*.jsonl' -mmin "-$window_minutes" 2>/dev/null -exec \
+        jq -r 'select(.message.usage and .message.model) | "\(.message.model)\t\(.message.usage.input_tokens // 0)\t\(.message.usage.output_tokens // 0)\t\(.message.usage.cache_read_input_tokens // 0)\t\(.message.usage.cache_creation_input_tokens // 0)"' {} \; 2>/dev/null \
+        | awk -F'\t' '
+            {
+                model = $1
+                # Bucket model family for rate lookup
+                if (model ~ /opus/) family = "opus"
+                else if (model ~ /sonnet/) family = "sonnet"
+                else if (model ~ /haiku/) family = "haiku"
+                else family = "other"
+
+                i[family] += $2
+                o[family] += $3
+                cr[family] += $4
+                cw[family] += $5
+            }
+            END {
+                # API rates per million tokens (2026 standard pricing).
+                # cache_read is typically 10% of input rate;
+                # cache_creation is typically 25% above input rate (1.25x).
+                # Using simple input/output rates here for the dollar
+                # estimate; cache costs are a refinement.
+                rates_in["opus"] = 15.0;   rates_out["opus"] = 75.0
+                rates_in["sonnet"] = 3.0;  rates_out["sonnet"] = 15.0
+                rates_in["haiku"] = 1.0;   rates_out["haiku"] = 5.0
+                rates_in["other"] = 3.0;   rates_out["other"] = 15.0
+
+                for (f in i) {
+                    # Cost includes cache_read (at 10% of input rate, an
+                    # approximation) and cache_write (at 1.25x input).
+                    cost = (i[f] + cw[f] * 1.25 + cr[f] * 0.1) * rates_in[f] / 1000000.0 \
+                         + o[f] * rates_out[f] / 1000000.0
+                    printf "%s\t%d\t%d\t%d\t%d\t%.4f\n", f, i[f], o[f], cr[f], cw[f], cost
+                }
+            }
+        ')
+    echo "$out"
+}
+
+# 5-hour window (in minutes)
+WINDOW_5H=300
+# 7-day window (in minutes)
+WINDOW_WEEKLY=10080
+
+DATA_5H=$(compute_window "$WINDOW_5H")
+DATA_WEEKLY=$(compute_window "$WINDOW_WEEKLY")
+
+# If both empty, no recent activity — exit silently.
+[ -z "$DATA_5H" ] && [ -z "$DATA_WEEKLY" ] && exit 0
+
+# Compute totals.
+total_5h_cost=$(echo "$DATA_5H" | awk -F'\t' '{s += $6} END {printf "%.2f", s+0}')
+total_weekly_cost=$(echo "$DATA_WEEKLY" | awk -F'\t' '{s += $6} END {printf "%.2f", s+0}')
+
+# Format the per-family breakdown.
+format_data() {
+    local data="$1"
+    [ -z "$data" ] && { echo "  (no activity in this window)"; return; }
+    echo "$data" | awk -F'\t' '
+        {
+            family = $1
+            i = $2; o = $3; cr = $4; cw = $5; cost = $6
+            tot_tokens = i + o + cr + cw
+            printf "  %-7s input %s  output %s  cache_read %s  cache_write %s  est_cost $%.2f\n",
+                family, fmt(i), fmt(o), fmt(cr), fmt(cw), cost
+        }
+        function fmt(n) {
+            if (n >= 1000000) return sprintf("%.1fM", n/1000000)
+            else if (n >= 1000) return sprintf("%.1fk", n/1000)
+            else return sprintf("%d", n)
+        }
+    '
+}
+
+# Determine warning level.
+warn_5h=""
+warn_weekly=""
+if awk -v c="$total_5h_cost" -v t="$WARN_5H" 'BEGIN {exit !(c+0 >= t+0)}'; then
+    warn_5h=" [WARN: above CC_QUOTA_5H_WARN_USD threshold of \$$WARN_5H]"
+fi
+if awk -v c="$total_weekly_cost" -v t="$WARN_WEEKLY" 'BEGIN {exit !(c+0 >= t+0)}'; then
+    warn_weekly=" [WARN: above CC_QUOTA_WEEKLY_WARN_USD threshold of \$$WARN_WEEKLY]"
+fi
+
+# Emit on stderr (SessionStart non-blocking convention).
+cat >&2 <<EOF
+<system-reminder>
+QUOTA STATUS (estimated from local JSONL transcripts; not Anthropic-authoritative)
+
+Last 5 hours — estimated API-equivalent cost: \$${total_5h_cost}${warn_5h}
+$(format_data "$DATA_5H")
+
+Last 7 days — estimated API-equivalent cost: \$${total_weekly_cost}${warn_weekly}
+$(format_data "$DATA_WEEKLY")
+
+Notes:
+- These figures are the equivalent-API cost of your recent token consumption.
+  Compare against your subscription tier's Pool 2 credit (June 15 onward:
+  \$20 Pro / \$100 Max 5x / \$200 Max 20x per month for programmatic usage).
+- The dashboard Anthropic does not yet provide (#16157, #38335, #29579) lives
+  here in the meantime. Set CC_QUOTA_STATUS_DISABLE=1 to silence.
+- Cache cost approximation: cache_read at 10% of input rate, cache_write at
+  1.25x input rate. Refine via CC_QUOTA_* env vars if needed.
+</system-reminder>
+EOF
+
+exit 0

package/examples/session-start-safety-check.sh

@@ -25,6 +25,20 @@
 #   }
 # }
 
+# Verify jq is available BEFORE the git-repo gate, because this concern is not
+# git-specific. Almost every safety hook in this kit parses the tool input with
+# `jq`; when jq is missing, those hooks cannot see the command and most fall
+# through to "allow" (fail-open) — the suite is silently inert while still
+# appearing installed. Surface this loudly at session start so a missing
+# dependency never masquerades as protection. (Fail-open safety hooks: #67917.)
+# Uses only shell builtins, so it works even on a bare PATH.
+if ! command -v jq > /dev/null 2>&1; then
+    echo "⚠ WARNING: jq is not installed, but the safety hooks parse tool input with jq." >&2
+    echo "  Without jq, most blocking hooks fail OPEN (they allow the command instead of" >&2
+    echo "  blocking it), so your safety hooks are effectively inert until jq is installed." >&2
+    echo "  Install:  (Debian/Ubuntu) sudo apt-get install jq    (macOS) brew install jq" >&2
+fi
+
 # Only run in git repos
 git rev-parse --git-dir > /dev/null 2>&1 || exit 0
 
@@ -46,11 +60,49 @@ if [ "$UNPUSHED" -gt 0 ]; then
     WARNINGS=$((WARNINGS + 1))
 fi
 
-# Check for stashes
+# Check for stashes — and specifically surface crash/teleport "auto-stash"
+# entries. When a session crashes or teleports between branches, Claude Code's
+# teardown silently runs `git add` + `git stash push`, so a clean working tree
+# does NOT mean the work was never done — it can be hidden in a stash that other
+# agents/sessions never see. In a shared worktree this is how uncommitted work
+# from research docs and code silently disappears (#66060).
 STASHES=$(git stash list 2>/dev/null | wc -l)
 if [ "$STASHES" -gt 0 ]; then
-    echo "ℹ NOTE: $STASHES stashed changes exist." >&2
-    echo "  Review: git stash list" >&2
+    # The teardown template is "auto-stash: agent <role> (<id>) crashed at <ts>",
+    # so matching "auto-stash" is a high-confidence signal with no false positives
+    # against the default "WIP on <branch>" messages of manual stashes.
+    AUTO_STASHES=$(git stash list 2>/dev/null | grep -cE 'auto-stash|pre-switch' || true)
+    if [ "$AUTO_STASHES" -gt 0 ]; then
+        echo "⚠ WARNING: $AUTO_STASHES of $STASHES stashes are harness auto-stashes (crash/teleport or branch-switch)." >&2
+        # A stash made with --include-untracked has a third parent (the untracked
+        UNTRACKED_STASHES=0
+        N=$(git stash list 2>/dev/null | wc -l)
+        i=0
+        while [ "$i" -lt "$N" ]; do
+            if git rev-parse --verify --quiet "stash@{$i}^3" >/dev/null 2>&1; then
+                UNTRACKED_STASHES=$((UNTRACKED_STASHES + 1))
+            fi
+            i=$((i + 1))
+        done
+        if [ "$UNTRACKED_STASHES" -gt 0 ]; then
+            echo "  ‼ $UNTRACKED_STASHES of these also stashed UNTRACKED files (--include-untracked):" >&2
+            echo "    those local files vanished from the folder; a sync client may have propagated the deletion." >&2
+            echo "    List them:  git stash show --include-untracked 'stash@{N}'" >&2
+        fi
+        echo "  Uncommitted work is hidden here; a clean working tree is NOT proof it was lost (#66060, #66092)." >&2
+        echo "  Inspect:  git stash list   (harness stashes say 'auto-stash' or 'pre-switch')" >&2
+        echo "            git stash show -p 'stash@{N}'" >&2
+        echo "  Recover:  checkout the branch in the stash's 'On <branch>:' label, then" >&2
+        echo "            git stash apply 'stash@{N}'   (apply, not pop — keeps a safety copy)" >&2
+        echo "  Root cause for multi-agent setups: agents sharing one worktree." >&2
+        echo "            Give each agent its own 'git worktree' so a teardown can't reach the others." >&2
+        # Hidden work that looks like a clean tree is a real hazard, so don't let
+        # the all-clear line below claim everything is fine.
+        WARNINGS=$((WARNINGS + 1))
+    else
+        echo "ℹ NOTE: $STASHES stashed changes exist." >&2
+        echo "  Review: git stash list" >&2
+    fi
 fi
 
 if [ "$WARNINGS" -eq 0 ]; then

package/examples/session-summary-stop.sh

@@ -18,7 +18,7 @@
 #   }
 # }
 #
-# TRIGGER: PreToolUse  MATCHER: "Bash"
+# TRIGGER: Stop  MATCHER: ""
 
 INPUT=$(cat)
 

package/examples/session-token-counter.sh

@@ -25,7 +25,7 @@
 #   CC_TOOL_WARN_200  — threshold 2 (default: 200)
 #   CC_TOOL_WARN_500  — threshold 3 (default: 500)
 #
-# TRIGGER: PreToolUse  MATCHER: "Bash"
+# TRIGGER: PostToolUse  MATCHER: ""
 
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)