cc-safe-setup 29.7.0 → 30.0.4

package/examples/api-key-in-url-guard.sh

@@ -18,6 +18,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-api-key-in-url-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [api-key-in-url-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)
 
@@ -27,7 +39,11 @@ COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 echo "$COMMAND" | grep -qE '\b(curl|wget|http|fetch)\b' || exit 0
 
 # Check for API key patterns in URLs
-if echo "$COMMAND" | grep -qiP '[?&](api[_-]?key|token|secret|password|auth|access[_-]?key|client[_-]?secret)=[^$\s&"'\'']{8,}'; then
+# -P は GNU 拡張で、macOS の BSD grep では grep 自体がエラーになる。
+# この条件は遮断（exit 2）の唯一の入口なので、偽になると鍵つきURLが素通しになる。
+# 実測: `curl "https://example.com/v1?api_key=…"` を渡すと -P ありは 2、無しは 0 だった。
+# \s を [:space:] に置き換えれば POSIX の拡張正規表現で同じことができる。
+if echo "$COMMAND" | grep -qiE '[?&](api[_-]?key|token|secret|password|auth|access[_-]?key|client[_-]?secret)=[^$[:space:]&"'\'']{8,}'; then
     echo "BLOCKED: API key detected in URL query parameter." >&2
     echo "" >&2
     echo "Command: $(echo "$COMMAND" | head -1)" >&2

package/examples/api-rate-limit-guard.sh

@@ -27,7 +27,42 @@
 # }
 # ================================================================
 
+# 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-api-rate-limit-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [api-rate-limit-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
+__CC_HOOK_INPUT="$INPUT"
+# --- セッション識別子でファイルを分ける (2026-08-09 修正) ---
+# 旧実装は "$$" を使っていたが、$$ はこのスクリプト自身のPIDで呼び出しごとに変わるため、
+# 状態が一度も持続しなかった(実測: 200回呼ぶとファイルが200個でき、中身は全部 1)。
+__CC_SID=""
+if [ -n "${__CC_HOOK_INPUT:-}" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    __CC_SID=$(printf '%s' "$__CC_HOOK_INPUT" | jq -r '.session_id // .sessionId // empty' 2>/dev/null)
+  fi
+  if [ -z "$__CC_SID" ] && command -v python3 >/dev/null 2>&1; then
+    __CC_SID=$(printf '%s' "$__CC_HOOK_INPUT" | python3 -c 'import sys,json
+try:
+    d=json.load(sys.stdin); print(d.get("session_id") or d.get("sessionId") or "")
+except Exception: print("")' 2>/dev/null)
+  fi
+fi
+if [ -n "$__CC_SID" ]; then
+  __CC_KEY=$(printf '%s' "$__CC_SID" | tr -c 'A-Za-z0-9_-' '_' | cut -c1-64)
+else
+  __CC_KEY="nosession-$(date +%Y%m%d)"
+fi
+# --- ここまで ---
+
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 
@@ -37,7 +72,7 @@ echo "$COMMAND" | grep -qE '^\s*(curl|wget|http|https)\s' || exit 0
 # Configurable minimum interval (milliseconds)
 MIN_INTERVAL_MS="${CC_API_RATE_LIMIT_MS:-1000}"
 
-TIMESTAMP_FILE="/tmp/.cc-api-rate-limit-$$"
+TIMESTAMP_FILE="/tmp/.cc-api-rate-limit-$__CC_KEY"
 NOW_MS=$(date +%s%N | cut -b1-13 2>/dev/null || date +%s)
 
 if [ -f "$TIMESTAMP_FILE" ]; then

package/examples/api-rate-limit-tracker.sh

@@ -20,6 +20,18 @@
 #   }
 # }
 
+# 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-api-rate-limit-tracker-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [api-rate-limit-tracker]: 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/articulated-scope-capture.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# ============================================================================
+# articulated-scope-capture.sh — Capture user prompt's sha256 + byte length
+# as the operator-instrumented Mode 2.6 (Action-Reasoning Mismatch) primitive
+# ============================================================================
+# PURPOSE: pair with scope-expansion-receipt.sh (PR #282, destructive-bash
+#   boundary) and dispatch-receipt.sh (PR #283, agent-dispatch boundary) by
+#   recording the *user's* verbatim instruction's hash + length at
+#   UserPromptSubmit time. The pair `(articulated_scope_hash, paths_argv)` is
+#   the operator-instrumented MAST 2.6 measurement primitive:
+#     - Mode 2.6 = "did the executed action stay within the user's
+#       articulated scope?"
+#     - The receipt corpus answers this directly by joining on session_id +
+#       articulated_scope_hash, without storing either side's raw text.
+#
+# WHY: yurukusa schema-v2 sketch at
+#   https://github.com/anthropics/claude-code/issues/61102#issuecomment-4514215413
+# proposes adding articulated_scope_hash + articulated_scope_length to the
+# receipt fields. This hook is the prompt-side companion that writes those
+# fields independently — joinable to PR #282/#283 receipts via session_id.
+#
+# WHY (cluster context): the effective_arrest_rate = gate_installation_rate ×
+# gate_recall decomposition (waitdeadai
+# https://github.com/anthropics/claude-code/issues/61102#issuecomment-4513977211)
+# requires the *gate_installation_rate* factor to be observable from
+# operator-side substrate. The destructive-bash and dispatch receipts measure
+# the tool-call side; this hook measures the user-prompt side. Joined, they
+# answer "did the operator's stated scope match the executed action?" at the
+# deployed-cohort level — the §6.2 measurement gap of the
+# ianymu/recognition-without-arrest synthesis writeup.
+#
+# PHI / SECRET SAFETY: only the sha256 and byte length are persisted; the
+# raw prompt text is NEVER written to the receipt file. The hash is the
+# correlation key against same-session destructive-bash and dispatch
+# receipts. For healthcare-deployed cohorts (per @nvst18's OpenClaw case at
+# #61167), this is the same PHI-safety property PR #283 chose for the
+# dispatched-prompt hashing.
+#
+# TRIGGER: UserPromptSubmit
+# MATCHER: ""
+#
+# CONFIGURATION (environment variables):
+#   CC_RECEIPT_DIR                    receipts directory (default
+#                                       ~/.claude/receipts)
+#   CC_ARTICULATED_SCOPE_DISABLE      set to "1" to disable capture entirely
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "UserPromptSubmit": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/articulated-scope-capture.sh"
+#         }]
+#       }]
+#     }
+#   }
+#
+# Related Issues / PRs:
+#   #61102 (@Awis13, @yurukusa, @Keesan12, @waitdeadai) — Mode 2.6+3.3
+#     composition + receipt-persistence-layer schema v2 proposal
+#   #61167 (@nvst18) — healthcare verification-agent fabrication; PHI-safety
+#     motivation for hash-only persistence
+#   PR #282 — scope-expansion-receipt (destructive-bash boundary)
+#   PR #283 — dispatch-receipt (agent-dispatch boundary)
+#
+# Joinable to those receipts via session_id + articulated_scope_hash.
+# ============================================================================
+
+INPUT=$(cat)
+
+# Empty input → exit 0 per CONTRIBUTING convention
+[ -z "$INPUT" ] && exit 0
+
+# Disable switch for operator opt-out
+[ "${CC_ARTICULATED_SCOPE_DISABLE:-0}" = "1" ] && exit 0
+
+# Extract user prompt from UserPromptSubmit hook JSON
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)
+[ -z "$PROMPT" ] && exit 0
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# sha256 over the verbatim prompt; never persists the raw text
+HASH=$(printf '%s' "$PROMPT" | sha256sum 2>/dev/null | awk '{print $1}')
+LEN=$(printf '%s' "$PROMPT" | wc -c | tr -d ' ')
+
+RECEIPT_DIR="${CC_RECEIPT_DIR:-$HOME/.claude/receipts}"
+mkdir -p "$RECEIPT_DIR"
+
+DATE=$(date -u +"%Y-%m-%d")
+OUT="${RECEIPT_DIR}/articulated-scope-${DATE}.jsonl"
+
+# JSONL line: matches the shape of PR #282/#283 receipts so receipts-aggregate
+# can consume both via a single iterator
+printf '{"ts":"%s","session_id":"%s","articulated_scope_hash":"%s","articulated_scope_length":%s,"boundary_type":"user_prompt_submit"}\n' \
+    "$TS" "$SESSION_ID" "$HASH" "$LEN" >> "$OUT"
+
+exit 0

package/examples/askuserquestion-autonomy-gate.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# askuserquestion-autonomy-gate.sh — Block AskUserQuestion in autonomy mode
+#
+# Solves: Claude blocking /goal mode or overnight autonomous runs indefinitely
+# by invoking AskUserQuestion to ask the operator whether to proceed
+# (anthropics/claude-code#61337). Recognition-without-arrest at the
+# PreToolUse-AskUserQuestion lifecycle event.
+#
+# The model recognizes an autonomous-operation constraint
+# (e.g. "operate autonomously, never ask questions"), articulates a reason
+# why the current task is hard enough to warrant asking anyway, then invokes
+# AskUserQuestion. With no operator present, the session blocks indefinitely.
+#
+# This hook arrests AskUserQuestion calls when CC_AUTONOMY_MODE=1 is set.
+# The stderr message gives the model a defensible next action so it does not
+# loop retrying the same blocked tool call.
+#
+# Modes:
+#   CC_AUTONOMY_MODE=0 (default): advisory only, no blocking
+#   CC_AUTONOMY_MODE=1: blocking, exit 2, structured stderr explanation
+#   CC_AUTONOMY_MODE_RECEIPT_DIR: directory for blocked-call receipts
+#     (default: ~/.claude/receipts)
+#
+# Usage: Add to settings.json as a PreToolUse hook matching AskUserQuestion
+#
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "AskUserQuestion",
+#       "hooks": [{
+#         "type": "command",
+#         "command": "~/.claude/hooks/askuserquestion-autonomy-gate.sh"
+#       }]
+#     }]
+#   }
+# }
+#
+# Then in any shell that runs /goal overnight or autonomous tasks:
+#   export CC_AUTONOMY_MODE=1
+#
+# TRIGGER: PreToolUse  MATCHER: "AskUserQuestion"
+
+set -u
+
+# 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-askuserquestion-autonomy-gate-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [askuserquestion-autonomy-gate]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+# Only act on AskUserQuestion tool calls
+[[ "$TOOL" != "AskUserQuestion" ]] && exit 0
+
+# Advisory mode by default: observe but do not block
+if [[ "${CC_AUTONOMY_MODE:-0}" != "1" ]]; then
+  exit 0
+fi
+
+# In autonomy mode: write a receipt, then block
+RECEIPT_DIR="${CC_AUTONOMY_MODE_RECEIPT_DIR:-$HOME/.claude/receipts}"
+mkdir -p "$RECEIPT_DIR" 2>/dev/null || true
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+RECEIPT_FILE="$RECEIPT_DIR/autonomy-blocked-$(date -u +%Y-%m-%d).jsonl"
+
+# Extract question summary for the receipt (hash only — never the full prompt
+# text, to keep PHI-safe per cc-safe-setup convention).
+QUESTION=$(echo "$INPUT" | jq -r '.tool_input.question // .tool_input.prompt // empty' 2>/dev/null)
+QUESTION_HASH=""
+QUESTION_LEN=0
+if [[ -n "$QUESTION" ]]; then
+  QUESTION_HASH=$(printf '%s' "$QUESTION" | sha256sum 2>/dev/null | awk '{print $1}')
+  QUESTION_LEN=$(printf '%s' "$QUESTION" | wc -c | tr -d ' ')
+fi
+
+# Append the receipt (best-effort; never block on receipt failure)
+{
+  printf '{"ts":"%s","event":"askuserquestion_blocked","question_hash":"%s","question_length":%s,"autonomy_mode":1}\n' \
+    "$TS" "$QUESTION_HASH" "$QUESTION_LEN"
+} >> "$RECEIPT_FILE" 2>/dev/null || true
+
+# Block the tool call with a stderr message that gives the model a next action
+cat >&2 <<'EOF'
+AskUserQuestion is blocked in autonomy mode (CC_AUTONOMY_MODE=1).
+The operator is not present and cannot answer.
+
+You must either (a) make a defensible default choice and document it inline,
+or (b) write a stop-with-explanation note in the working memo (e.g.
+./.claude/autonomy-blocks.md) and proceed to the next task in the goal queue.
+
+Do not retry AskUserQuestion in this turn. The same call will be blocked again.
+EOF
+
+exit 2

package/examples/attachment-traversal-guard.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# ================================================================
+# attachment-traversal-guard.sh — Block @../ attachment bypass
+# ================================================================
+# PURPOSE:
+#   Block the `@../path` attachment syntax that bypasses
+#   `permissions.deny` rules by reaching file content through
+#   the harness's attachment-preprocessing pipeline rather than
+#   the `Read`-tool authorization point.
+#
+#   Reported case (anthropics/claude-code#61148, v2.1.146):
+#     settings.json: { "permissions": { "deny": ["Read(**/Security/**)"] } }
+#     workspace:    D:\TestProject\Library.Devices
+#     target:       D:\TestProject\Library\Security\KeyIV.cs  (outside workspace)
+#
+#     Read D:\...\KeyIV.cs              → Blocked ✓
+#     Read @Library\Security\KeyIV.cs   → Blocked ✓ (workspace attachment)
+#     Read @..\Library\Security\KeyIV.cs → BYPASSED ✗
+#
+#   The attachment-preprocessing pipeline normalizes `@../`
+#   before the permission check runs, so the resolved path
+#   never reaches the `Read`-tool authorization point. PreToolUse
+#   hooks on `Read` also do not fire (per the reporter's
+#   independent verification).
+#
+#   This UserPromptSubmit hook intercepts the literal `@../`
+#   pattern in the raw user prompt before the harness expands
+#   the attachment, closing the bypass surface on the operator
+#   side while a runtime fix is pending.
+#
+# TRIGGER: UserPromptSubmit  MATCHER: ""
+#
+# BEHAVIOR:
+#   - Reads the user prompt from stdin (`.prompt` field).
+#   - If the prompt contains `@../` or `@..\` (Windows-style),
+#     blocks with exit 2 and an explanatory stderr message.
+#   - In advisory mode (CC_ATTACHMENT_TRAVERSAL_BLOCK=0),
+#     warns but does not block.
+#   - Does NOT match `@./` (current-directory attachment, which
+#     stays inside workspace and is enforced by the standard
+#     deny rule).
+#
+# CONFIG:
+#   CC_ATTACHMENT_TRAVERSAL_BLOCK=1  (1 = block, 0 = warn-only; default 1)
+#   CC_ATTACHMENT_TRAVERSAL_ALLOW_REGEX=""  (allow paths matching this regex)
+#
+# REFERENCES:
+#   - anthropics/claude-code#61148 — original report
+#   - RUSE Surface 1 articulation: synonymous edges of the same
+#     deny-rule outcome reached through a parallel pipeline.
+#
+# DEPENDENCIES:
+#   - jq (for parsing the hook input JSON)
+#
+# LIMITATIONS:
+#   - Detects the literal `@../` pattern in the prompt text.
+#     Does not catch obfuscated variants (e.g., `@..%2F`,
+#     `@%2E%2E/`) — those are not known to be expanded by the
+#     attachment preprocessor at time of writing but should be
+#     added to the regex if a reproduction surfaces.
+#   - Cannot defend against file content already injected into
+#     context by a previous prompt in the same session.
+# ================================================================
+
+# 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-attachment-traversal-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [attachment-traversal-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || true)
+[ -z "$PROMPT" ] && exit 0
+
+BLOCK_MODE="${CC_ATTACHMENT_TRAVERSAL_BLOCK:-1}"
+ALLOW_REGEX="${CC_ATTACHMENT_TRAVERSAL_ALLOW_REGEX:-}"
+
+# Match @../ or @..\ at any position in the prompt
+TRAVERSAL_REGEX='@\.\.[/\\]'
+
+if echo "$PROMPT" | grep -qE "$TRAVERSAL_REGEX"; then
+  # If allow-regex is set and matches the offending segment, permit.
+  if [ -n "$ALLOW_REGEX" ] && echo "$PROMPT" | grep -qE "$ALLOW_REGEX"; then
+    exit 0
+  fi
+
+  cat >&2 <<EOF
+attachment-traversal-guard: blocked @../ attachment syntax.
+
+  This prompt contains the @../ attachment pattern, which bypasses
+  permissions.deny rules by reaching file content through the
+  attachment-preprocessing pipeline rather than the Read-tool
+  authorization point.
+
+  See anthropics/claude-code#61148 for the reproduction.
+
+  If you intentionally need to attach a parent-directory file:
+    1. Disable this hook for the session, or
+    2. Set CC_ATTACHMENT_TRAVERSAL_ALLOW_REGEX to a pattern that
+       matches the specific parent-directory file you intend to
+       attach (e.g., '@\\.\\./allowed/specific\\.txt').
+
+  To convert this hook to warn-only mode:
+    CC_ATTACHMENT_TRAVERSAL_BLOCK=0
+EOF
+
+  if [ "$BLOCK_MODE" = "1" ]; then
+    exit 2
+  fi
+fi
+
+exit 0

package/examples/aup-block-pattern-logger.sh

@@ -0,0 +1,161 @@
+#!/bin/bash
+# aup-block-pattern-logger.sh — Persist Usage Policy classifier blocks across sessions
+#
+# Background:
+#   Starting 2026-05-18, the Anthropic server-side Usage Policy classifier began
+#   over-triggering on benign Claude Code prompts. The block surfaces as one of two
+#   stock error strings in tool output:
+#     "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."
+#
+#   The classifier is non-deterministic and shifts over time. 25+ open issues filed
+#   between 2026-05-18 and 2026-05-27 across English, Russian, Polish, and Spanish
+#   input. The operator has no first-class way to:
+#     - reconstruct which sessions hit the block and on what model,
+#     - build evidence for a CVP application showing block frequency,
+#     - notice when the classifier shifts (drop in block rate / rise after an update).
+#
+#   The partner hook aup-false-positive-helper.sh surfaces the four operator-side
+#   workarounds at SessionStart. This logger pairs with it by recording each block
+#   event PostToolUse, so the operator can review block history later.
+#
+#   Reference: https://gist.github.com/yurukusa/4fa4751044be45bd83345601ee79c2db
+#
+# What this hook does:
+#   On PostToolUse, scan tool output for AUP-block patterns. When a block is
+#   detected, append one line to a persistent log:
+#     TIMESTAMP|MODEL|TOOL|PATTERN_KIND|EXCERPT
+#   Default log path: ~/.claude/aup-block-history.log
+#
+#   Pattern kinds emitted:
+#     cyber-safeguards   — "triggered cyber-related safeguards"
+#     usage-policy       — "violate our Usage Policy"
+#     safety-guardrails  — "triggered safety guardrails"
+#     rephrase-rewind    — "Rephrase your prompt or rewind to continue"
+#     usage-policy-api   — "API Error: ... unable to respond"  (fallback)
+#
+#   By default, a one-line stderr advisory prints the running block count for the
+#   current ANTHROPIC_MODEL (or "default-routing" when unset). Silent when no
+#   block is detected.
+#
+# When this hook does NOT log or warn:
+#   - CC_AUP_BLOCK_LOGGER_DISABLE=1
+#   - tool output is empty or unparseable
+#   - no AUP block pattern matched
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/aup-block-pattern-logger.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_AUP_BLOCK_LOGGER_DISABLE=1        — never log, never warn
+#   CC_AUP_BLOCK_LOGGER_QUIET=1          — log silently (no stderr advisory)
+#   CC_AUP_BLOCK_LOG_PATH=<path>         — override default log path
+#   CC_AUP_BLOCK_LOGGER_MAX_LINES=<n>    — log rotation threshold (default 500)
+#
+# Output schema (one line per block):
+#   ISO8601_UTC | ANTHROPIC_MODEL or "default-routing" | TOOL_NAME | PATTERN_KIND | up-to-120-char excerpt
+#
+# Privacy: only the pattern kind and a short excerpt are recorded. No prompt content,
+# no tool input, no file paths beyond the tool name. The excerpt is the matched line.
+#
+# 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
+
+# Disable path
+if [ "${CC_AUP_BLOCK_LOGGER_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+# Extract tool name and output; fall back to grep if jq is missing.
+if command -v jq >/dev/null 2>&1; then
+  TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+  OUTPUT=$(printf '%s' "$INPUT" | jq -r '.tool_output // .tool_response // empty' 2>/dev/null || echo "")
+else
+  TOOL=$(printf '%s' "$INPUT" | grep -oE '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*"([^"]*)"$/\1/')
+  OUTPUT="$INPUT"
+fi
+
+[ -z "$OUTPUT" ] && exit 0
+[ -z "$TOOL" ] && TOOL="unknown-tool"
+
+# Match patterns in priority order. The first match wins so the recorded kind is
+# the most specific signal available.
+PATTERN_KIND=""
+EXCERPT=""
+match_pattern() {
+  local label="$1"
+  local regex="$2"
+  local line
+  line=$(printf '%s' "$OUTPUT" | grep -iE "$regex" | head -1)
+  if [ -n "$line" ]; then
+    PATTERN_KIND="$label"
+    EXCERPT=$(printf '%s' "$line" | tr -d '|\n\r' | head -c 120)
+    return 0
+  fi
+  return 1
+}
+
+match_pattern "cyber-safeguards"  "triggered cyber-related safeguards" \
+  || match_pattern "safety-guardrails" "triggered safety guardrails" \
+  || match_pattern "rephrase-rewind"   "Rephrase your prompt or rewind to continue" \
+  || match_pattern "usage-policy"      "violate our Usage Policy" \
+  || match_pattern "usage-policy-api"  "API Error.*unable to respond to this request"
+
+# No match → silent exit (the overwhelming common case).
+[ -z "$PATTERN_KIND" ] && exit 0
+
+LOG_PATH="${CC_AUP_BLOCK_LOG_PATH:-$HOME/.claude/aup-block-history.log}"
+LOG_DIR=$(dirname "$LOG_PATH")
+mkdir -p "$LOG_DIR" 2>/dev/null || exit 0
+
+MODEL="${ANTHROPIC_MODEL:-default-routing}"
+TIMESTAMP=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+
+# Append; never block on log failure.
+printf '%s|%s|%s|%s|%s\n' "$TIMESTAMP" "$MODEL" "$TOOL" "$PATTERN_KIND" "$EXCERPT" >> "$LOG_PATH" 2>/dev/null || true
+
+# Rotate when the log exceeds the configured threshold. Keep the most recent half.
+MAX_LINES="${CC_AUP_BLOCK_LOGGER_MAX_LINES:-500}"
+if [ -f "$LOG_PATH" ]; then
+  CURRENT_LINES=$(wc -l < "$LOG_PATH" 2>/dev/null || echo 0)
+  if [ "$CURRENT_LINES" -gt "$MAX_LINES" ] 2>/dev/null; then
+    KEEP=$((MAX_LINES / 2))
+    [ "$KEEP" -lt 1 ] && KEEP=1
+    tail -n "$KEEP" "$LOG_PATH" > "${LOG_PATH}.tmp" 2>/dev/null && mv "${LOG_PATH}.tmp" "$LOG_PATH" 2>/dev/null || true
+  fi
+fi
+
+# Stderr advisory unless explicitly silenced. Show the running count for the
+# current model so the operator notices when frequency rises.
+if [ "${CC_AUP_BLOCK_LOGGER_QUIET:-0}" != "1" ]; then
+  MODEL_COUNT=$(grep -c "|${MODEL}|" "$LOG_PATH" 2>/dev/null || echo 0)
+  cat >&2 <<EOF
+[aup-block-pattern-logger] Usage Policy block detected (kind=$PATTERN_KIND, tool=$TOOL).
+  Model: $MODEL    Cumulative blocks logged for this model: $MODEL_COUNT
+  Log: $LOG_PATH
+  Workarounds: enable CC_AUP_FALSE_POSITIVE_HELPER_REMIND=1 with aup-false-positive-helper.sh,
+    or swap to a Sonnet variant (export ANTHROPIC_MODEL=claude-sonnet-4-7) for sensitive prompts.
+  Silence this advisory: export CC_AUP_BLOCK_LOGGER_QUIET=1
+EOF
+fi
+
+exit 0