cc-safe-setup 29.8.0 → 30.0.4

package/examples/aup-false-positive-helper.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+# aup-false-positive-helper.sh — Surface the AUP false-positive cluster awareness when Opus models are pinned
+#
+# Background:
+#   Starting mid-May 2026 (acceleration peak 2026-05-21 through 2026-05-27), the Anthropic
+#   server-side Usage Policy classifier began over-triggering on benign Claude Code prompts.
+#   GitHub issue tracker accumulated 25+ open reports in 10 days from independent users:
+#     - #60366 (16r): single-word "hi" greeting blocked
+#     - #62190 (10r): non-deterministic blocks on greetings, coding, "ok"/"yes"
+#     - #61056 (4r), #61638 (3r), #61185 (2r), and 20+ low-reaction reports
+#   github-actions[bot] auto-flagged at least three duplicate chains, confirming the
+#   shape of the cluster at Anthropic's own intake.
+#
+#   Independent reports converge on a clear signature:
+#     - Affected: Opus 4.7, Opus 4.6, Opus 1M context variants
+#     - Unaffected: Sonnet 4.6, Sonnet 4.7
+#     - Languages: false positives observed on English, Russian, Polish, and Spanish
+#     - Domains: kernel security audits, biomedical research, FPGA waveform analysis,
+#       compression algorithm work, and plain greetings — context-independent
+#     - Behavior: non-deterministic on identical input (same prompt blocks one minute,
+#       passes the next), strongly indicating an unstable classifier rather than the
+#       prompt being the cause
+#
+#   The block surfaces as one of two stock error strings:
+#     "API Error: Claude Code is unable to respond to this request, which appears to
+#      violate our Usage Policy (...). This request triggered cyber-related safeguards."
+#   or:
+#     "This request triggered safety guardrails. Rephrase your prompt or rewind to continue."
+#
+#   This is a server-side defect; there is no client-side fix. The hook exists to surface
+#   the four operator-side workarounds when a user is most likely to hit the block (Opus
+#   pinned, false-positive flood window still active).
+#
+#   Reference: https://gist.github.com/yurukusa/4fa4751044be45bd83345601ee79c2db  (4 operator-side paths through the
+#   false-positive flood — model swap, prompt warmup, CVP application, retry harness)
+#
+# What this hook does:
+#   On SessionStart, inspect ANTHROPIC_MODEL and emit a one-line advisory matching one
+#   of four states:
+#     - ANTHROPIC_MODEL unset                                  → silent (default routing)
+#     - ANTHROPIC_MODEL pinned to a Sonnet variant             → silent (unaffected model)
+#     - ANTHROPIC_MODEL pinned to an Opus variant + CC_AUP_FALSE_POSITIVE_HELPER_REMIND=1
+#                                                              → emit one-time advisory
+#     - ANTHROPIC_MODEL pinned to an Opus variant + REMIND unset
+#                                                              → silent (opt-in only)
+#
+#   Silent by default. CC_AUP_FALSE_POSITIVE_HELPER_REMIND=1 opts in to the awareness
+#   note. CC_AUP_FALSE_POSITIVE_HELPER_QUIET=1 suppresses permanently after acknowledgement.
+#
+# When this hook does NOT fire a warning:
+#   - CC_AUP_FALSE_POSITIVE_HELPER_QUIET=1
+#   - ANTHROPIC_MODEL is unset or pinned to a non-Opus model
+#   - CC_AUP_FALSE_POSITIVE_HELPER_REMIND is unset (opt-in only)
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/aup-false-positive-helper.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_AUP_FALSE_POSITIVE_HELPER_QUIET=1    — never emit anything
+#   CC_AUP_FALSE_POSITIVE_HELPER_REMIND=1   — emit advisory when Opus is pinned (opt-in)
+
+# Silence path
+if [ "${CC_AUP_FALSE_POSITIVE_HELPER_QUIET:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Model unset → use default routing, no specific advisory needed
+if [ -z "${ANTHROPIC_MODEL:-}" ]; then
+  exit 0
+fi
+
+# Pinned to a model that is NOT an Opus variant → unaffected by the cluster
+case "$ANTHROPIC_MODEL" in
+  *opus*|*Opus*|*OPUS*) : ;;  # Opus variant — continue to advisory
+  *) exit 0 ;;                # Sonnet, Haiku, or other — silent
+esac
+
+# Opt-in gate: only emit when the user explicitly requested awareness
+if [ "${CC_AUP_FALSE_POSITIVE_HELPER_REMIND:-0}" != "1" ]; then
+  exit 0
+fi
+
+# Opt-in advisory path: ANTHROPIC_MODEL pinned to Opus, user wants the awareness note
+cat >&2 <<EOF
+[aup-false-positive-helper] ANTHROPIC_MODEL is pinned to "$ANTHROPIC_MODEL".
+
+Between 2026-05-18 and the current session window, the Anthropic Usage Policy classifier
+has over-triggered on benign prompts when Opus models (4.7, 4.6, 1M variants) are pinned.
+Sonnet variants are reportedly unaffected. The block surfaces as:
+
+  "API Error: ... This request triggered cyber-related safeguards."
+
+Four operator-side mitigations while the server-side classifier remains unstable:
+
+  1. Swap to Sonnet for sensitive sessions
+       export ANTHROPIC_MODEL=claude-sonnet-4-7
+     (or any Sonnet variant; the cluster signature points to an Opus-specific path)
+
+  2. Warm up the session with project context before security/kernel/research prompts
+     A short context-establishing turn often passes where a cold sensitive prompt blocks
+
+  3. Apply for the Cyber Verification Program (CVP) if your work routinely involves
+     legitimate cyber/kernel/biomedical/FPGA terminology
+       https://www.anthropic.com/legal/cyber-verification-program
+
+  4. The classifier is non-deterministic — a single retry on identical input frequently
+     succeeds. If a benign prompt blocks once, retry before rewording
+
+To suppress this advisory:
+  export CC_AUP_FALSE_POSITIVE_HELPER_QUIET=1
+
+GitHub tracker (25+ independent reports, 2026-05-18 through 2026-05-27):
+  https://github.com/anthropics/claude-code/issues/60366
+  https://github.com/anthropics/claude-code/issues/62190
+EOF
+
+exit 0

package/examples/aup-large-tool-output-warner.sh

@@ -0,0 +1,282 @@
+#!/bin/bash
+# aup-large-tool-output-warner.sh — Warn before Bash commands that may produce large
+# sensitive-looking outputs that can trigger the Cluster 9 Usage Policy classifier
+#
+# Background:
+#   Cluster 9 (Usage Policy classifier over-trigger) has a known trigger surface that
+#   the first four defense hooks do not address: a single tool result containing a
+#   large volume of security-shaped content (IP blocklists, firewall rules, packet
+#   captures, kernel log dumps) can flip the classifier even when the surrounding
+#   conversation is unambiguously benign.
+#
+#   Direct evidence from issue #61185 (filipghoulin, 2026-05-23):
+#     "What triggered it: A lab-review skill dispatched a sub-agent that ran
+#      `cat /etc/banip/banip.blocklist` on an OpenWRT router. The blocklist has
+#      ~17,000 entries. That volume of content in a single tool result, combined
+#      with the security shape of the content, appears to have flipped the
+#      classifier into a permanent block state for the whole session."
+#
+#   Reference: ~/ops/customer-pain-cluster-9-secondary-pains-2026-05-30.md (axis 4)
+#
+#   The first three hooks address awareness, evidence collection, and session-start
+#   model swap. The fourth hook (aup-retry-loop-guard.sh) breaks intra-session retry
+#   cycles. None of them act *before* the offending tool call: by the time the
+#   classifier has fired on the large output, the session is already wedged and
+#   compact / clear may themselves block (see #61185 k33bs report). The only place
+#   to address this trigger surface is the PreToolUse boundary.
+#
+# What this hook does:
+#   On PreToolUse for the Bash tool, parse the proposed command. When the command
+#   shape matches one of the five well-known large-output patterns AND the path or
+#   command target carries a security-shaped sentinel (blocklist, firewall, iptables,
+#   denylist, allowlist, banlist, ipset, etc. — or sits under a known security path
+#   like /etc/banip/, /var/log/, /proc/net/), emit a non-blocking stderr advisory
+#   recommending a narrower variant.
+#
+#   The hook never blocks the command. Exit is always 0. The advisory is informational
+#   — the operator can ignore it and continue. The point is to put the recommendation
+#   in front of the operator BEFORE the large output exists, not after the session is
+#   already wedged.
+#
+# Detection categories (intentionally narrow to keep false-positive rate low):
+#   A) `cat <path>` where path is under /etc/banip/, /var/log/, or ends in .blocklist
+#      / .denylist / .allowlist / .banlist / .iplist / .firewall / iptables-save
+#   B) `find <broad_path>` without `head`, `tail`, `-print -quit`, or `-quit`
+#      (broad recursion on security-shaped paths)
+#   C) `journalctl` without `-n`, `--lines`, or `--since` (full system log dump)
+#   D) `dmesg` without a pipe to head/tail/wc/grep with a follow-up size cap
+#   E) `grep -r` / `grep -R` on a security-shaped path without a pipe to head/tail
+#
+#   Plus a separate strong-signal path: ANY command (Bash or otherwise) whose
+#   argument string contains a sentinel substring from a curated security-content
+#   wordlist gets a sentinel-only advisory, on top of the category match.
+#
+# When this hook does NOT emit anything:
+#   - CC_AUP_LARGE_OUTPUT_WARNER_DISABLE=1
+#   - CC_AUP_LARGE_OUTPUT_WARNER_QUIET=1
+#   - tool_name is not "Bash" (other tools are not parsed by this hook)
+#   - command is missing, empty, or unreadable
+#   - command already includes a size-cap pipe (head, tail, -n NNN, etc.)
+#   - the same command pattern already fired an advisory in this session
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/aup-large-tool-output-warner.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_AUP_LARGE_OUTPUT_WARNER_DISABLE=1     — never emit
+#   CC_AUP_LARGE_OUTPUT_WARNER_QUIET=1       — silent
+#   CC_AUP_LARGE_OUTPUT_WARNER_STATE_DIR=<p> — one-shot state dir (default $HOME/.claude)
+#   CC_AUP_LARGE_OUTPUT_WARNER_SESSION_ID=<id> — session id override (tests / automation)
+#
+# Design notes:
+#   - PreToolUse only. The classifier fires on the *output* of the tool call, so by
+#     the time PostToolUse runs the damage is done. The advisory has to land before
+#     the command executes.
+#   - Never blocks. The hook recommends a narrower variant but the operator may have
+#     a legitimate reason for the full output (audit, evidence collection, etc.).
+#   - One-shot per (session, pattern_hash). If the operator runs `cat
+#     /etc/banip/banip.blocklist` three times in a session, only the first call
+#     triggers the advisory. This prevents the hook from becoming its own noise loop.
+#   - Conservative category set. Five patterns rather than fifteen. A false positive
+#     here doesn't break anything (the command still runs), but it does add cognitive
+#     load. The set covers #61185's pattern plus the four closest neighbors from
+#     #60366's comment chain.
+#   - Sentinel wordlist is the high-confidence path. When the command target itself
+#     contains "blocklist" / "iptables-save" / etc., the advisory fires even if the
+#     command shape isn't on the five-category list — because the sentinel itself
+#     carries the cluster-9 trigger signature regardless of how the file is read.
+
+set -u
+
+# Disable path
+if [ "${CC_AUP_LARGE_OUTPUT_WARNER_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Quiet path
+if [ "${CC_AUP_LARGE_OUTPUT_WARNER_QUIET:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Read PreToolUse JSON payload from stdin
+INPUT=$(cat 2>/dev/null) || exit 0
+[ -n "$INPUT" ] || exit 0
+
+# Parse tool_name and command via jq when available; fall back to grep heuristics.
+TOOL_NAME=""
+COMMAND=""
+if command -v jq >/dev/null 2>&1; then
+  TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+  COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+else
+  # Best-effort fallback when jq is unavailable. Match "tool_name": "Bash" and
+  # "command": "..." in the JSON payload. This is intentionally lenient — the
+  # detection categories below double-check the command shape.
+  TOOL_NAME=$(printf '%s' "$INPUT" | grep -oE '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*"tool_name"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/')
+  COMMAND=$(printf '%s' "$INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*"command"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/')
+fi
+
+# Only act on Bash
+[ "$TOOL_NAME" = "Bash" ] || exit 0
+[ -n "$COMMAND" ] || exit 0
+
+# Skip if the command already has a size-cap somewhere in the pipeline.
+# Common cap shapes: `| head -N`, `| tail -N`, `head -N <file>`, `tail -N <file>`,
+# `find ... -print -quit`, `find ... -quit`, `journalctl -n N`, `journalctl --lines N`,
+# `journalctl --since ...`, `grep ... | head`, `dmesg | head`, `wc -l`.
+if printf '%s' "$COMMAND" | grep -qE '(\|[[:space:]]*head\b|\|[[:space:]]*tail\b|head[[:space:]]+-n[[:space:]]+[0-9]+|tail[[:space:]]+-n[[:space:]]+[0-9]+|head[[:space:]]+-[0-9]+|tail[[:space:]]+-[0-9]+|-print[[:space:]]+-quit\b|[[:space:]]-quit\b|--lines[[:space:]]+[0-9]+|[[:space:]]-n[[:space:]]+[0-9]+|--since\b|\|[[:space:]]*wc\b|^[[:space:]]*wc\b|^[[:space:]]*grep[[:space:]]+-c\b)'; then
+  exit 0
+fi
+
+# Sentinel wordlist for security-shaped content. Case-insensitive substring match
+# against the full command string. These are the substrings that, by themselves,
+# strongly indicate the classifier will see the output as "security-shaped."
+SENTINEL=""
+case " $(printf '%s' "$COMMAND" | tr '[:upper:]' '[:lower:]') " in
+  *blocklist*)   SENTINEL="blocklist" ;;
+  *denylist*)    SENTINEL="denylist" ;;
+  *banlist*)     SENTINEL="banlist" ;;
+  *iplist*)      SENTINEL="iplist" ;;
+  *iptables-save*) SENTINEL="iptables-save" ;;
+  *ipset[[:space:]]save*) SENTINEL="ipset save" ;;
+  */etc/banip/*) SENTINEL="/etc/banip/" ;;
+  */etc/fail2ban/*) SENTINEL="/etc/fail2ban/" ;;
+  */var/log/auth*) SENTINEL="/var/log/auth*" ;;
+  */var/log/secure*) SENTINEL="/var/log/secure*" ;;
+  *firewall.conf*) SENTINEL="firewall.conf" ;;
+esac
+
+# Category match. Even without a sentinel, the following shapes are likely to
+# produce large outputs that look security-shaped to the classifier.
+CATEGORY=""
+CATEGORY_DESC=""
+if printf '%s' "$COMMAND" | grep -qE '^[[:space:]]*cat[[:space:]]+(/etc/banip/|/var/log/|/proc/net/)'; then
+  CATEGORY="A"
+  CATEGORY_DESC="cat on a security-shaped system path"
+elif printf '%s' "$COMMAND" | grep -qE '^[[:space:]]*cat[[:space:]]+[^|]*\.(blocklist|denylist|allowlist|banlist|iplist|firewall)([[:space:]]|$)'; then
+  CATEGORY="A"
+  CATEGORY_DESC="cat on a security-shaped file extension"
+elif printf '%s' "$COMMAND" | grep -qE '(^|[[:space:];&|])find[[:space:]]+(/etc/banip/|/var/log/|/proc/net/|/etc/fail2ban/)'; then
+  CATEGORY="B"
+  CATEGORY_DESC="find recursing under a security-shaped path"
+elif printf '%s' "$COMMAND" | grep -qE '(^|[[:space:];&|])journalctl([[:space:]]|$)'; then
+  CATEGORY="C"
+  CATEGORY_DESC="journalctl without a line/since cap"
+elif printf '%s' "$COMMAND" | grep -qE '(^|[[:space:];&|])dmesg([[:space:]]|$)'; then
+  CATEGORY="D"
+  CATEGORY_DESC="dmesg without a size cap"
+elif printf '%s' "$COMMAND" | grep -qE '(^|[[:space:];&|])grep[[:space:]]+(-r|-R|--recursive)[[:space:]]+(.*)(/etc/banip/|/var/log/|/proc/net/|/etc/fail2ban/)'; then
+  CATEGORY="E"
+  CATEGORY_DESC="grep -r/-R on a security-shaped path"
+fi
+
+# If neither a sentinel nor a category match, the command is out of scope.
+if [ -z "$SENTINEL" ] && [ -z "$CATEGORY" ]; then
+  exit 0
+fi
+
+# One-shot per (session, pattern_hash). Pattern hash = first 40 chars of command
+# stripped of timestamps and whitespace runs. This keeps the same pattern from
+# firing twice in a row (e.g. operator runs the same cat three times) while still
+# allowing a different pattern (cat foo.blocklist vs cat bar.denylist) to fire.
+STATE_DIR="${CC_AUP_LARGE_OUTPUT_WARNER_STATE_DIR:-$HOME/.claude}"
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+STATE_FILE="$STATE_DIR/aup-large-tool-output-warner.fired"
+
+SESSION_ID="${CC_AUP_LARGE_OUTPUT_WARNER_SESSION_ID:-}"
+if [ -z "$SESSION_ID" ]; then
+  SESSION_ID="${CLAUDECODE_SESSION_ID:-}"
+fi
+if [ -z "$SESSION_ID" ] && command -v tty >/dev/null 2>&1; then
+  TTY_PATH=$(tty 2>/dev/null)
+  if [ -n "$TTY_PATH" ] && [ "$TTY_PATH" != "not a tty" ]; then
+    SESSION_ID=$(printf '%s' "$TTY_PATH" | tr '/' '_')
+  fi
+fi
+[ -n "$SESSION_ID" ] || SESSION_ID="ppid-${PPID:-0}"
+
+# Pattern hash: collapse whitespace, take first 60 chars.
+PATTERN_HASH=$(printf '%s' "$COMMAND" | tr -s '[:space:]' ' ' | cut -c1-60 | tr ' /' '__')
+FIRED_KEY="${SESSION_ID}::${PATTERN_HASH}"
+
+if [ -f "$STATE_FILE" ] && grep -Fq -- "$FIRED_KEY" "$STATE_FILE" 2>/dev/null; then
+  exit 0
+fi
+
+# Bound the state file to ~100 lines to avoid unbounded growth.
+if [ -f "$STATE_FILE" ]; then
+  tail -n 100 "$STATE_FILE" > "${STATE_FILE}.tmp" 2>/dev/null \
+    && mv "${STATE_FILE}.tmp" "$STATE_FILE" 2>/dev/null || true
+fi
+printf '%s\n' "$FIRED_KEY" >> "$STATE_FILE" 2>/dev/null || true
+
+# Compose the advisory.
+ADVISORY_REASON=""
+if [ -n "$SENTINEL" ] && [ -n "$CATEGORY" ]; then
+  ADVISORY_REASON="security-content sentinel \"$SENTINEL\" + $CATEGORY_DESC"
+elif [ -n "$SENTINEL" ]; then
+  ADVISORY_REASON="security-content sentinel \"$SENTINEL\" in the command"
+else
+  ADVISORY_REASON="$CATEGORY_DESC"
+fi
+
+# Trim command excerpt for the advisory (avoid dumping a 500-char one-liner).
+CMD_EXCERPT=$(printf '%s' "$COMMAND" | cut -c1-120)
+if [ "${#COMMAND}" -gt 120 ]; then
+  CMD_EXCERPT="${CMD_EXCERPT}..."
+fi
+
+cat >&2 <<EOF
+[aup-large-tool-output-warner] About to run a Bash command that may produce a
+large security-shaped output. Trigger: $ADVISORY_REASON.
+
+Command excerpt:
+  $CMD_EXCERPT
+
+Why this matters:
+  Cluster 9 (Usage Policy classifier over-trigger) has fired on tool results
+  carrying high-volume security-shaped content even when the surrounding
+  conversation is benign. Issue #61185 documents a session-wedging block
+  triggered by a single \`cat /etc/banip/banip.blocklist\` returning ~17,000
+  IP entries — after which /compact and /clear also blocked, leaving no
+  recovery path within the session.
+
+The command is NOT being blocked. This is an advisory only — the operator may
+have a legitimate reason for the full output (audit trail, evidence package,
+forensics). If a summary is sufficient, narrower variants reduce the trigger
+surface without losing the answer:
+
+  Line count only:    wc -l <path>
+  First N lines:      head -200 <path>
+  Last N lines:       tail -200 <path>
+  Matching subset:    grep -c <pattern> <path>     (count only)
+                      grep -E <pattern> <path> | head -200
+  journalctl:         journalctl --since "1 hour ago" -n 200
+  find:               find <path> -type f | head -200
+  dmesg:              dmesg | tail -200
+
+For multi-thousand-entry blocklists, prefer the count + a sampled head/tail
+over the full dump.
+
+To silence this advisory for the current session only:
+  export CC_AUP_LARGE_OUTPUT_WARNER_QUIET=1
+
+Related hooks (already active in this defense suite):
+  aup-false-positive-helper.sh — SessionStart awareness, 4 operator-side options
+  aup-block-pattern-logger.sh  — PostToolUse evidence collection
+  aup-retry-loop-guard.sh      — PostToolUse intra-session retry breaker
+  model-swap-suggester.sh      — SessionStart cross-session swap recommendation
+
+GitHub references:
+  https://github.com/anthropics/claude-code/issues/60366  (cluster anchor)
+  https://github.com/anthropics/claude-code/issues/61185  (large-output trigger)
+EOF
+
+exit 0

package/examples/aup-retry-loop-guard.sh

@@ -0,0 +1,229 @@
+#!/bin/bash
+# aup-retry-loop-guard.sh — Detect retry-loop pattern during Cluster 9 blocks and recommend exit
+#
+# Background:
+#   Cluster 9 (Usage Policy classifier over-trigger) has a secondary failure mode that the
+#   first three defense hooks do not address: even when an operator has been blocked and is
+#   actively retrying the same input (the non-deterministic classifier sometimes passes on
+#   retry — see #60366, #62190), each retry burns transcript context. For paying users on
+#   Pro / Max quota, the retry loop drains the daily quota faster than the productive work
+#   would have, leading to the "session quota MAX reached early" symptom.
+#
+#   Direct evidence from issue #61664 (Japanese paid user, 2026-05-23):
+#     "ブロック発生時も context/credit は消費される"
+#     "ブロック→巻き戻し→同じ処理の再実行 で context を浪費"
+#     "昨日まで丸 1 日使っても使用量上限に達しなかったが、本日は早々に MAX に到達"
+#
+#   The first three hooks address awareness (helper), evidence collection (logger), and
+#   session-start swap recommendations (suggester). None of them break a retry loop that
+#   is already in progress within a single session.
+#
+#   Reference: ~/ops/customer-pain-cluster-9-secondary-pains-2026-05-30.md (axis 1)
+#
+# What this hook does:
+#   On PostToolUse, read the aup-block-history.log (written by aup-block-pattern-logger.sh)
+#   and check whether the last N blocks within a short window (default 5 minutes) all
+#   targeted the same tool. When that pattern is detected, emit a non-blocking stderr
+#   advisory recommending one of two cycle-breaking actions:
+#     - `/exit` to end the session before more context is burned, then restart with Sonnet
+#     - immediate `export ANTHROPIC_MODEL=claude-sonnet-4-7` for the current session
+#
+#   Distinct from model-swap-suggester (SessionStart, 60-min window): retry-loop-guard
+#   runs PostToolUse, looks at a 5-min window, and addresses the intra-session retry
+#   cycle that burns context — not the cross-session model selection decision.
+#
+# When this hook does NOT emit anything:
+#   - CC_AUP_RETRY_LOOP_GUARD_DISABLE=1
+#   - CC_AUP_RETRY_LOOP_GUARD_QUIET=1
+#   - aup-block log missing, empty, or unreadable
+#   - Fewer than threshold blocks in the configured window
+#   - Blocks in window span multiple tools (single-tool retry loop is the diagnostic signal)
+#   - The current advisory has already fired within the same session (one-shot per session)
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/aup-retry-loop-guard.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_AUP_RETRY_LOOP_GUARD_DISABLE=1         — never emit
+#   CC_AUP_RETRY_LOOP_GUARD_QUIET=1           — silent
+#   CC_AUP_RETRY_LOOP_GUARD_THRESHOLD=<n>     — block count threshold (default 3)
+#   CC_AUP_RETRY_LOOP_GUARD_WINDOW_MIN=<n>    — lookback window in minutes (default 5)
+#   CC_AUP_RETRY_LOOP_GUARD_TARGET=<model>    — target Sonnet model (default claude-sonnet-4-7)
+#   CC_AUP_RETRY_LOOP_GUARD_STATE_DIR=<path>  — one-shot state directory (default $HOME/.claude)
+#   CC_AUP_RETRY_LOOP_GUARD_SESSION_ID=<id>   — session identifier override for one-shot logic
+#   CC_AUP_BLOCK_LOG_PATH=<path>              — log path (shared with logger; default $HOME/.claude/aup-block-history.log)
+#
+# Design notes:
+#   - Single-tool restriction: the diagnostic for a retry loop is "same tool, same kind, in
+#     a short window." A burst of blocks across different tools is more consistent with a
+#     general session sensitivity than a retry cycle, and breaking the session for the
+#     latter is more disruptive than helpful.
+#   - One-shot per session: the advisory fires at most once per session. The state file
+#     lives in $CC_AUP_RETRY_LOOP_GUARD_STATE_DIR/aup-retry-loop-guard.lock with the
+#     session PID. Subsequent invocations from the same session see the lock and stay
+#     silent so the advisory doesn't become its own noise loop.
+#   - Never blocks. All failure paths exit 0 — a corrupt log or missing date utility
+#     cannot break the tool call cycle.
+
+set -u
+
+# Disable path
+if [ "${CC_AUP_RETRY_LOOP_GUARD_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Quiet path
+if [ "${CC_AUP_RETRY_LOOP_GUARD_QUIET:-0}" = "1" ]; then
+  exit 0
+fi
+
+LOG_PATH="${CC_AUP_BLOCK_LOG_PATH:-$HOME/.claude/aup-block-history.log}"
+[ -f "$LOG_PATH" ] || exit 0
+[ -r "$LOG_PATH" ] || exit 0
+[ -s "$LOG_PATH" ] || exit 0
+
+THRESHOLD="${CC_AUP_RETRY_LOOP_GUARD_THRESHOLD:-3}"
+WINDOW_MIN="${CC_AUP_RETRY_LOOP_GUARD_WINDOW_MIN:-5}"
+TARGET="${CC_AUP_RETRY_LOOP_GUARD_TARGET:-claude-sonnet-4-7}"
+STATE_DIR="${CC_AUP_RETRY_LOOP_GUARD_STATE_DIR:-$HOME/.claude}"
+
+case "$THRESHOLD" in
+  ''|*[!0-9]*) THRESHOLD=3 ;;
+esac
+case "$WINDOW_MIN" in
+  ''|*[!0-9]*) WINDOW_MIN=5 ;;
+esac
+
+NOW=$(date -u '+%s' 2>/dev/null) || exit 0
+CUTOFF=$((NOW - WINDOW_MIN * 60))
+
+ts_to_epoch() {
+  local ts="$1"
+  date -u -d "$ts" '+%s' 2>/dev/null \
+    || date -j -u -f '%Y-%m-%dT%H:%M:%SZ' "$ts" '+%s' 2>/dev/null
+}
+
+# Collect blocks in window. The log schema is:
+#   ISO8601_UTC | MODEL | TOOL | PATTERN_KIND | EXCERPT
+# We track the tools that fired in the window. If all in-window blocks targeted the same
+# tool and there are at least THRESHOLD of them, the pattern is a retry loop.
+COUNT=0
+UNIQUE_TOOLS=""
+LAST_TOOL=""
+LAST_KIND=""
+while IFS='|' read -r LOG_TS _LOG_MODEL LOG_TOOL LOG_KIND _LOG_EXCERPT; do
+  [ -z "$LOG_TS" ] && continue
+  [ -z "$LOG_TOOL" ] && continue
+  LOG_EPOCH=$(ts_to_epoch "$LOG_TS")
+  [ -z "$LOG_EPOCH" ] && continue
+  case "$LOG_EPOCH" in
+    *[!0-9]*) continue ;;
+  esac
+  if [ "$LOG_EPOCH" -ge "$CUTOFF" ] 2>/dev/null; then
+    COUNT=$((COUNT + 1))
+    LAST_TOOL="$LOG_TOOL"
+    LAST_KIND="$LOG_KIND"
+    case "$UNIQUE_TOOLS" in
+      *"|$LOG_TOOL|"*) : ;;
+      *) UNIQUE_TOOLS="${UNIQUE_TOOLS}|${LOG_TOOL}|" ;;
+    esac
+  fi
+done < "$LOG_PATH"
+
+if [ "$COUNT" -lt "$THRESHOLD" ] 2>/dev/null; then
+  exit 0
+fi
+
+# Count unique tools. Multi-tool bursts are not retry loops.
+TOOL_COUNT=$(printf '%s' "$UNIQUE_TOOLS" | tr -cd '|' | wc -c)
+TOOL_COUNT=$((TOOL_COUNT / 2))
+if [ "$TOOL_COUNT" -ne 1 ] 2>/dev/null; then
+  exit 0
+fi
+
+# One-shot per session. Session identifier resolution, in order of preference:
+#   1. CC_AUP_RETRY_LOOP_GUARD_SESSION_ID env var (explicit override; tests, automation)
+#   2. CLAUDECODE_SESSION_ID env var (Claude Code may export this in the future)
+#   3. Controlling tty path (stable across child shells in an interactive session)
+#   4. PPID fallback (last resort; less stable across subshell hops)
+SESSION_ID="${CC_AUP_RETRY_LOOP_GUARD_SESSION_ID:-}"
+if [ -z "$SESSION_ID" ]; then
+  SESSION_ID="${CLAUDECODE_SESSION_ID:-}"
+fi
+if [ -z "$SESSION_ID" ] && command -v tty >/dev/null 2>&1; then
+  TTY_PATH=$(tty 2>/dev/null)
+  if [ -n "$TTY_PATH" ] && [ "$TTY_PATH" != "not a tty" ]; then
+    SESSION_ID=$(printf '%s' "$TTY_PATH" | tr '/' '_')
+  fi
+fi
+if [ -z "$SESSION_ID" ]; then
+  SESSION_ID="ppid-${PPID:-0}"
+fi
+
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+STATE_FILE="$STATE_DIR/aup-retry-loop-guard.lock"
+
+if [ -f "$STATE_FILE" ]; then
+  PRIOR=$(cat "$STATE_FILE" 2>/dev/null | head -1)
+  if [ "$PRIOR" = "$SESSION_ID" ]; then
+    exit 0
+  fi
+fi
+
+# Trim stale entries: keep only the most recent 10 session IDs to bound the file.
+if [ -f "$STATE_FILE" ]; then
+  tail -n 10 "$STATE_FILE" > "${STATE_FILE}.tmp" 2>/dev/null \
+    && mv "${STATE_FILE}.tmp" "$STATE_FILE" 2>/dev/null || true
+fi
+printf '%s\n' "$SESSION_ID" >> "$STATE_FILE" 2>/dev/null || true
+
+# Emit the advisory. The recommendation tier is:
+#   1. `/exit` immediately to stop burning context, then restart fresh with Sonnet pinned.
+#   2. If you must continue this session, swap the model in-place; the same prompt may
+#      pass on Sonnet without retry.
+cat >&2 <<EOF
+[aup-retry-loop-guard] Retry-loop pattern detected: $COUNT Usage Policy block(s) on
+tool "$LAST_TOOL" within the last $WINDOW_MIN minute(s). Pattern kind: $LAST_KIND.
+
+This shape — same tool, same block, repeated within a short window — is the retry-loop
+signature reported in issue #61664: each retry consumes session context, even when the
+attempt itself blocks. Pro / Max quota holders report hitting their daily quota MAX in
+hours instead of a full day during this loop.
+
+Recommended cycle-breaker (pick one):
+
+  Option A — exit and restart fresh (safest for quota)
+    1. /exit
+    2. export ANTHROPIC_MODEL=$TARGET
+    3. claude  # new session, no inherited context, Sonnet path
+
+  Option B — swap in-place (continues current session)
+    export ANTHROPIC_MODEL=$TARGET
+    # the next prompt may pass; Sonnet is unaffected by the Cluster 9 signature
+
+The Cluster 9 classifier is non-deterministic, so retrying identical input on the same
+Opus pin sometimes works — but the context cost per retry typically exceeds the value
+of the eventual successful turn. Breaking the cycle now preserves more daily quota for
+productive work.
+
+Related hooks (already active in this defense suite):
+  aup-false-positive-helper.sh — generic awareness at session start
+  aup-block-pattern-logger.sh  — evidence shape recorded at $LOG_PATH
+  model-swap-suggester.sh      — session-start swap recommendation (60-min window)
+
+To silence this advisory for the current session only:
+  export CC_AUP_RETRY_LOOP_GUARD_QUIET=1
+
+GitHub references:
+  https://github.com/anthropics/claude-code/issues/60366  (cluster anchor)
+  https://github.com/anthropics/claude-code/issues/61664  (retry-loop quota burn)
+EOF
+
+exit 0