cc-safe-setup 29.8.0 → 30.0.4

package/examples/dispatch-receipt.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# ================================================================
+# dispatch-receipt.sh — Receipt-and-refuse layer for agent
+#                       dispatch operations
+# ================================================================
+# PURPOSE:
+#   PreToolUse on Task / Agent. Writes a structured JSONL receipt
+#   before each dispatch, and (optionally) refuses dispatches to
+#   agent names that fall outside a declared allowlist.
+#
+#   Sibling of scope-expansion-receipt.sh. Where the destructive
+#   sibling records and gates *file system* operations, this hook
+#   records and gates *agent dispatch* operations. Both implement
+#   the receipt-persistence-layer architecture:
+#   https://gist.github.com/yurukusa/8c0d19d59730868672270e7312492d1d
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Task|Agent"
+#
+# WHY THIS MATTERS:
+#   anthropics/claude-code#61167 reported a production audit at a
+#   healthcare startup: 39 specialized agents deployed (OpenClaw,
+#   AWS Lightsail, Bedrock Sonnet 4.6), 5 ever used, ~20 total
+#   sessions across all of them. Opus 4.7 reported dispatching
+#   the unused agents — ZELDA, LYRA, MIRA, TESTER, CLINIC, OPS,
+#   CFO, LEX, SABRINA, UXI — with correct names, correct
+#   terminology, plausible outputs. None of those dispatches
+#   ever happened.
+#
+#   The cluster name is "phantom agent dispatch", a specialization
+#   of the broader recognition-without-arrest pattern (#60226).
+#   In the healthcare case, the fabricated dispatches included
+#   verification agents (CLINIC, GUARD, SAFE, LEX, TESTER). When
+#   a model fabricates the output of *the agents whose job is to
+#   detect fabrication*, the safety architecture inverts.
+#
+#   This hook moves the receipt to the tool boundary: every
+#   Task / Agent invocation lands a record before execution. The
+#   audit query becomes "show me receipts for CLINIC dispatches in
+#   the last N days." If the count is zero while CLINIC's review
+#   output appears in session transcripts, the fabrication is
+#   recoverable with one grep.
+#
+# RECEIPT FORMAT (one JSONL per dispatch):
+#   {"ts":"2026-05-22T05:00:00Z",
+#    "subagent_type":"general-purpose",
+#    "description":"<short task description>",
+#    "prompt_hash":"<sha256 of prompt>",
+#    "prompt_length":1234,
+#    "allowlist_match":"general-purpose" | null,
+#    "decision":"execute" | "refuse" | "execute-bypassed"}
+#
+#   Note: the full prompt is NOT stored. Healthcare and other
+#   sensitive deployments may include PHI / PII in dispatch
+#   prompts; storing only a sha256 hash lets the audit verify
+#   "this exact prompt was dispatched" without persisting the
+#   content. Use prompt_length + prompt_hash + ts as the
+#   correlation key against session transcripts.
+#
+# RECEIPT LOCATION:
+#   ${HOME}/.claude/receipts/dispatch-YYYY-MM-DD.jsonl
+#
+# CONFIGURATION:
+#   CC_DISPATCH_ALLOWLIST — JSON array of allowed subagent types,
+#       e.g. '["general-purpose","Explore","code-reviewer"]'
+#     If unset, the hook only writes receipts (never refuses).
+#
+#   CC_DISPATCH_BYPASS=1 — single-call escape hatch. The receipt
+#     is still written (with decision="execute-bypassed"); refuse
+#     logic is skipped. Use only when you have read the receipt
+#     and verified the intent.
+#
+#   CC_DISPATCH_RECEIPT_DIR — override the receipt directory
+#     (default: ${HOME}/.claude/receipts)
+#
+# RELATED:
+#   https://github.com/anthropics/claude-code/issues/61167
+#   https://github.com/anthropics/claude-code/issues/61107
+#   https://github.com/anthropics/claude-code/issues/61102
+#   https://github.com/anthropics/claude-code/issues/60226
+#   https://gist.github.com/yurukusa/69f3ba47ed94afabc20424b4c82d46f2
+#   (Phantom Agent Cluster — A Pre-Launch Forensic Survey)
+# ================================================================
+
+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-dispatch-receipt-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [dispatch-receipt]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+SUBAGENT_TYPE=$(printf '%s' "$INPUT" | jq -r '.tool_input.subagent_type // empty' 2>/dev/null)
+DESCRIPTION=$(printf '%s' "$INPUT" | jq -r '.tool_input.description // empty' 2>/dev/null)
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
+
+# If we cannot identify a dispatch payload at all, exit silently.
+# A Task call with no subagent_type and no prompt is malformed upstream;
+# refusing here would create false-positive friction without audit value.
+if [ -z "$SUBAGENT_TYPE" ] && [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+# Default subagent_type when omitted (Claude Code uses general-purpose).
+[ -z "$SUBAGENT_TYPE" ] && SUBAGENT_TYPE="general-purpose"
+
+# Compute prompt hash and length without storing the prompt itself.
+PROMPT_LEN=$(printf '%s' "$PROMPT" | wc -c | tr -d ' ')
+PROMPT_HASH=$(printf '%s' "$PROMPT" | sha256sum 2>/dev/null | awk '{print $1}')
+[ -z "$PROMPT_HASH" ] && PROMPT_HASH="$(printf '%s' "$PROMPT" | shasum -a 256 2>/dev/null | awk '{print $1}')"
+
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+TYPE_JSON=$(printf '%s' "$SUBAGENT_TYPE" | jq -Rs -c .)
+DESC_JSON=$(printf '%s' "$DESCRIPTION" | jq -Rs -c .)
+
+# Allowlist decision
+ALLOWLIST_JSON="${CC_DISPATCH_ALLOWLIST:-}"
+BYPASS="${CC_DISPATCH_BYPASS:-0}"
+DECISION="execute"
+ALLOWLIST_MATCH_JSON="null"
+
+if [ -n "$ALLOWLIST_JSON" ]; then
+    # Validate allowlist is a JSON array; if not, fail open (receipt-only).
+    if printf '%s' "$ALLOWLIST_JSON" | jq -e 'type == "array"' >/dev/null 2>&1; then
+        MATCH=$(printf '%s' "$ALLOWLIST_JSON" | jq -r --arg t "$SUBAGENT_TYPE" '
+            .[] | select(. == $t)
+        ' 2>/dev/null | head -1)
+        if [ -n "$MATCH" ]; then
+            ALLOWLIST_MATCH_JSON=$(printf '%s' "$MATCH" | jq -Rs -c .)
+        else
+            DECISION="refuse"
+        fi
+    fi
+fi
+
+if [ "$BYPASS" = "1" ] && [ "$DECISION" = "refuse" ]; then
+    DECISION="execute-bypassed"
+fi
+
+# Write receipt
+RECEIPT_DIR="${CC_DISPATCH_RECEIPT_DIR:-${HOME}/.claude/receipts}"
+mkdir -p "$RECEIPT_DIR" 2>/dev/null
+RECEIPT_FILE="${RECEIPT_DIR}/dispatch-$(date +%Y-%m-%d).jsonl"
+
+printf '{"ts":"%s","subagent_type":%s,"description":%s,"prompt_hash":"%s","prompt_length":%s,"allowlist_match":%s,"decision":"%s"}\n' \
+    "$TS" "$TYPE_JSON" "$DESC_JSON" "$PROMPT_HASH" "$PROMPT_LEN" "$ALLOWLIST_MATCH_JSON" "$DECISION" \
+    >> "$RECEIPT_FILE" 2>/dev/null
+
+if [ "$DECISION" = "refuse" ]; then
+    ALLOWED=$(printf '%s' "$ALLOWLIST_JSON" | jq -r 'join(", ")' 2>/dev/null)
+    echo "BLOCKED: dispatch-receipt — agent type \"$SUBAGENT_TYPE\" is not in the declared allowlist." >&2
+    echo "" >&2
+    echo "Allowed agent types: $ALLOWED" >&2
+    echo "Receipt: $RECEIPT_FILE" >&2
+    echo "" >&2
+    echo "Principle: subagent dispatch is an action that must produce a verifiable record." >&2
+    echo "  (https://github.com/anthropics/claude-code/issues/61167)" >&2
+    echo "" >&2
+    echo "To proceed:" >&2
+    echo "  1. Verify the agent type matches a deployed agent (avoid phantom dispatches)." >&2
+    echo "  2. Either add the agent type to CC_DISPATCH_ALLOWLIST, or" >&2
+    echo "  3. Re-issue with CC_DISPATCH_BYPASS=1 (recorded in the receipt)." >&2
+    exit 2
+fi
+
+exit 0

package/examples/django-migrate-guard.sh

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

package/examples/dns-config-guard.sh

@@ -7,6 +7,18 @@
 #
 # TRIGGER: PreToolUse  MATCHER: "Bash|Edit|Write"
 
+# 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-dns-config-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [dns-config-guard]: 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)
 

package/examples/docker-dangerous-guard.sh

@@ -17,6 +17,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-docker-dangerous-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [docker-dangerous-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/dockerfile-latest-guard.sh

@@ -1,3 +1,4 @@
+#!/bin/bash
 #
 # TRIGGER: PreToolUse  MATCHER: "Edit|Write"
 INPUT=$(cat)

package/examples/dotenv-anthropic-key-billing-guard.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# dotenv-anthropic-key-billing-guard.sh — Warn when project .env contains ANTHROPIC_API_KEY
+#
+# Solves: Reddit r/ClaudeAI 1tbaq2d (314 points, 86 comments as of 2026-05-13)
+#         "If your project has an ANTHROPIC_API_KEY in any .env file,
+#          Claude Code will silently bill your API account instead of your Max plan."
+#         User reported 9 auto-recharge events totaling ~$187 USD loss.
+#         Anthropic support confirmed: "this is intentional functionality."
+#
+# WHY THIS MATTERS:
+#   When .env contains ANTHROPIC_API_KEY=sk-ant-..., Claude Code shells inherit
+#   the variable and the model client prefers the env var over the Max plan
+#   subscription credentials. The user sees no warning, no UI indicator;
+#   billing silently routes to the API account and prepaid funds get
+#   consumed (and are non-refundable per Anthropic policy).
+#
+#   This is the exact "claim-verify gap" pattern: the user's mental model
+#   ("I'm on Max plan, billing is fixed") diverges from system reality
+#   (env var overrides Max plan, billing is per-token).
+#
+# TRIGGER: SessionStart  MATCHER: ""
+#
+# CONFIGURATION:
+#   CC_DOTENV_AK_FILES — comma-separated filenames to check
+#                        (default: .env,.env.local,.env.development,.env.production,.env.dev)
+#   CC_DOTENV_AK_ACTION — "warn" or "block" (default: warn)
+#   CC_DOTENV_AK_LOG — log file path (default: /tmp/cc-dotenv-ak-warnings.log)
+#
+# Usage:
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/dotenv-anthropic-key-billing-guard.sh" }]
+#     }]
+#   }
+# }
+
+FILES="${CC_DOTENV_AK_FILES:-.env,.env.local,.env.development,.env.production,.env.dev}"
+ACTION="${CC_DOTENV_AK_ACTION:-warn}"
+LOG_FILE="${CC_DOTENV_AK_LOG:-/tmp/cc-dotenv-ak-warnings.log}"
+
+# Determine project root: prefer CLAUDE_PROJECT_DIR, fall back to PWD
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+[ -d "$PROJECT_ROOT" ] || exit 0
+
+FOUND_FILES=()
+
+IFS=',' read -ra PATTERNS <<< "$FILES"
+for pat in "${PATTERNS[@]}"; do
+  pat=$(echo "$pat" | xargs)  # trim whitespace
+  [ -z "$pat" ] && continue
+  candidate="$PROJECT_ROOT/$pat"
+  if [ -f "$candidate" ]; then
+    # Match a non-empty assignment (allow optional spaces, optional export, optional quotes)
+    # Skip lines that are commented out (start with #)
+    if grep -qE '^[[:space:]]*(export[[:space:]]+)?ANTHROPIC_API_KEY[[:space:]]*=[[:space:]]*["'"'"']?[^[:space:]"'"'"'#][^"'"'"'#]*' "$candidate" 2>/dev/null; then
+      FOUND_FILES+=("$candidate")
+    fi
+  fi
+done
+
+# If no offending files, pass through silently
+if [ ${#FOUND_FILES[@]} -eq 0 ]; then
+  exit 0
+fi
+
+# Found offending file(s) — log and notify
+TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+for f in "${FOUND_FILES[@]}"; do
+  echo "[$TIMESTAMP] $f contains ANTHROPIC_API_KEY action=$ACTION" >> "$LOG_FILE"
+done
+
+# Build human-readable message
+MSG="⚠️  ANTHROPIC_API_KEY detected in project .env file(s):"
+for f in "${FOUND_FILES[@]}"; do
+  MSG+=$'\n'"     - $f"
+done
+MSG+=$'\n'
+MSG+=$'\n'"  Claude Code shell tools inherit env vars from the project, and the"
+MSG+=$'\n'"  client prefers ANTHROPIC_API_KEY over the Max plan subscription."
+MSG+=$'\n'"  Result: API charges may silently consume prepaid funds while you"
+MSG+=$'\n'"  believe you are on the flat-rate Max plan. Refunds are not offered"
+MSG+=$'\n'"  for funds already consumed."
+MSG+=$'\n'
+MSG+=$'\n'"  Mitigations:"
+MSG+=$'\n'"    1. Remove the ANTHROPIC_API_KEY line from the .env file, OR"
+MSG+=$'\n'"    2. Set ANTHROPIC_API_KEY= (empty) at the start of your shell session, OR"
+MSG+=$'\n'"    3. Move the key to a separate file that is not auto-sourced."
+MSG+=$'\n'
+MSG+=$'\n'"  Reference: reddit.com/r/ClaudeAI/comments/1tbaq2d/  ($187 loss reported)"
+
+if [ "$ACTION" = "block" ]; then
+  # SessionStart cannot truly block, but exit 2 surfaces error to user.
+  printf '%s\n' "$MSG" >&2
+  exit 2
+else
+  printf '%s\n' "$MSG" >&2
+  exit 0
+fi

package/examples/dotenv-commit-guard.sh

@@ -12,6 +12,18 @@
 
 set -euo 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-dotenv-commit-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [dotenv-commit-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/dotenv-read-guard.sh

@@ -24,6 +24,18 @@
 #
 # TRIGGER: PreToolUse  MATCHER: "Read"
 
+# 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-dotenv-read-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [dotenv-read-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
 

package/examples/dotfile-protection-guard.sh

@@ -20,6 +20,18 @@
 
 set -euo 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-dotfile-protection-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [dotfile-protection-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
 [ -z "$FILE" ] && exit 0

package/examples/dotnet-build-on-edit.sh

@@ -18,7 +18,7 @@
 # }
 # ================================================================
 #
-# TRIGGER: PreToolUse  MATCHER: "Bash"
+# TRIGGER: PostToolUse  MATCHER: "Edit|Write"
 
 INPUT=$(cat)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)

package/examples/drizzle-migrate-guard.sh

@@ -10,14 +10,26 @@
 # {
 #   "hooks": {
 #     "PreToolUse": [{
-#       "matcher": "Bash",
+#       "matcher": "Bash|PowerShell",
 #       "hooks": [{ "type": "command", "command": "~/.claude/hooks/drizzle-migrate-guard.sh" }]
 #     }]
 #   }
 # }
 # ================================================================
 #
-# TRIGGER: PreToolUse  MATCHER: "Bash"
+# TRIGGER: PreToolUse  MATCHER: "Bash|PowerShell"
+
+# 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-drizzle-migrate-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [drizzle-migrate-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)
@@ -31,4 +43,17 @@ if echo "$COMMAND" | grep -qE 'drizzle-kit\s+drop'; then
     exit 2
 fi
 
+# Block 'drizzle-kit push --force'. Plain 'push' prompts before any data-loss
+# change; --force (and the legacy push:pg/push:mysql/push:sqlite variants)
+# skips that prompt and applies the change directly — the exact way autonomous
+# agents have wiped production databases (anthropics/claude-code#27063, and the
+# sibling prisma case #36183). The header has always advertised this block; it
+# was never implemented, so a user relying on this hook was unprotected.
+if echo "$COMMAND" | grep -qE 'drizzle-kit\s+push(:[a-z]+)?\b' && echo "$COMMAND" | grep -qE '\-\-force(-reset)?\b'; then
+    echo "BLOCKED: 'drizzle-kit push --force' applies schema changes without the data-loss prompt and can wipe table data." >&2
+    echo "Command: $COMMAND" >&2
+    echo "Use 'drizzle-kit generate' + 'drizzle-kit migrate' for a reviewable migration, or drop --force to keep the interactive guard." >&2
+    exit 2
+fi
+
 exit 0

package/examples/echo-probe-spam-detector.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+# echo-probe-spam-detector.sh — Block Opus 4.8 echo-probe spam bursts
+# (Cluster 25 candidate, axis 25B — tool-result delivery compensation)
+#
+# Background:
+#   When the Bash tool's result delivery is slow or buffered, Opus 4.8 emits
+#   bursts of no-op echo probe commands ("echo s1", "echo s2", ...,
+#   sometimes "sleep N; echo x") between real commands, apparently to coax
+#   buffered output to flush. Dozens per turn bury the actual work, clutter
+#   the screen, and burn tokens. The behaviour started after the Opus 4.8
+#   upgrade and was not present on prior model versions.
+#
+#   Anchor case:
+#     #63887 — Agent spams no-op echo probe commands to flush shell output
+#              (14 reactions, Opus 4.8 + v2.1.156+ regression)
+#
+#   Cost-side sibling:
+#     #64343 — Excessive token consumption from repeated echo tool calls
+#              ("burned my tokens on hundreds of echo calls")
+#
+#   Cluster 25 axes (4 sub-clusters + 1 overlap):
+#     25A — late/empty tool-result delivery (substrate)
+#     25B — echo-probe spam compensation (this hook)
+#     25C — 2>&1 permission-engine fragmentation hang
+#     25D — compounding cost (downstream of 25B/25C)
+#     25E — empty-result triggered fabrication (Cluster 22 overlap)
+#
+#   This hook is a PreToolUse hook on Bash that:
+#     - Matches the echo-probe spam shapes (echo s\d+, echo with one-char
+#       trivial arg, sleep N; echo *)
+#     - Tracks consecutive probe-shaped commands per session
+#     - Warns on first probe-shaped command
+#     - Blocks (exit 2) on the third consecutive probe-shaped command
+#
+#   The threshold-and-escalate shape is what works against compensation-
+#   routine bursts that are not stopped by warnings alone — the model needs
+#   to be forced to re-evaluate, not just nudged.
+#
+# When this hook does NOT block:
+#   - CC_ECHO_PROBE_DISABLE=1                  — never warn or block
+#   - CC_ECHO_PROBE_QUIET=1                    — silent (no stderr output)
+#   - CC_ECHO_PROBE_THRESHOLD=N                — block after N consecutive (default 3)
+#   - the Bash command is not probe-shaped     — exit 0
+#   - the operator has reset the counter via `# RESET ECHO PROBE` echo comment
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/echo-probe-spam-detector.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_ECHO_PROBE_DISABLE=1   — never warn or block
+#   CC_ECHO_PROBE_QUIET=1     — silent (process but never write to stderr)
+#   CC_ECHO_PROBE_THRESHOLD=N — block at N consecutive probes (default 3)
+
+set -u
+
+if [ "${CC_ECHO_PROBE_DISABLE:-}" = "1" ]; then
+    exit 0
+fi
+
+THRESHOLD="${CC_ECHO_PROBE_THRESHOLD:-3}"
+STATE_DIR="${TMPDIR:-/tmp}/cc-echo-probe-spam-detector"
+mkdir -p "$STATE_DIR"
+SESSION_ID="${CLAUDE_SESSION_ID:-default}"
+COUNTER_FILE="$STATE_DIR/${SESSION_ID}.counter"
+
+INPUT=$(cat 2>/dev/null || true)
+CMD=""
+if command -v jq >/dev/null 2>&1 && [ -n "$INPUT" ]; then
+    CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+fi
+
+if [ -z "$CMD" ]; then
+    exit 0
+fi
+
+# Strip leading/trailing whitespace
+CMD_TRIM=$(printf '%s' "$CMD" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+# Detect probe shapes:
+#  1. "echo s\d+"        — the canonical #63887 burst pattern
+#  2. "echo <1-3 chars>"  — generic short throwaway
+#  3. "sleep <N>; echo *" — wrapped flush attempt
+is_probe_shape() {
+    local c="$1"
+    # echo s\d+ pattern (s followed by digits, no other args)
+    if printf '%s\n' "$c" | grep -Eq '^echo[[:space:]]+s[0-9]+[[:space:]]*$'; then
+        return 0
+    fi
+    # echo <very short single arg> pattern (1-3 chars, no special meaning)
+    if printf '%s\n' "$c" | grep -Eq '^echo[[:space:]]+[a-zA-Z0-9._-]{1,3}[[:space:]]*$'; then
+        return 0
+    fi
+    # sleep N; echo ... pattern
+    if printf '%s\n' "$c" | grep -Eq '^sleep[[:space:]]+[0-9.]+[[:space:]]*;[[:space:]]*echo[[:space:]]'; then
+        return 0
+    fi
+    return 1
+}
+
+# Check for reset signal embedded in the command (operator override)
+if printf '%s\n' "$CMD_TRIM" | grep -Eq '#[[:space:]]*RESET ECHO PROBE'; then
+    rm -f "$COUNTER_FILE"
+    exit 0
+fi
+
+if ! is_probe_shape "$CMD_TRIM"; then
+    # Non-probe command resets the streak
+    rm -f "$COUNTER_FILE"
+    exit 0
+fi
+
+# Probe-shaped: increment counter
+CURRENT=0
+if [ -f "$COUNTER_FILE" ]; then
+    CURRENT=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+    # Validate it's a number
+    case "$CURRENT" in
+        ''|*[!0-9]*) CURRENT=0 ;;
+    esac
+fi
+CURRENT=$((CURRENT + 1))
+printf '%d' "$CURRENT" > "$COUNTER_FILE"
+
+if [ "${CC_ECHO_PROBE_QUIET:-}" = "1" ]; then
+    if [ "$CURRENT" -ge "$THRESHOLD" ]; then
+        exit 2
+    fi
+    exit 0
+fi
+
+if [ "$CURRENT" -ge "$THRESHOLD" ]; then
+    cat >&2 <<EOF
+
+BLOCKED: This is the ${CURRENT}th consecutive echo-probe-shaped Bash command.
+
+Pattern detected: Opus 4.8 emits bursts of "echo s1, echo s2, ..." or
+"sleep N; echo x" to flush suspected buffered output. This is Cluster 25
+axis 25B — a compensation routine for tool-result delivery delay that
+burns tokens without doing user-visible work.
+
+What to do instead:
+  - If you genuinely need to flush output: run the real command once and
+    wait for its result; tolerate shell latency.
+  - If you are waiting on async work: use a single backgrounded command
+    with a real completion signal — never a burst of no-op echoes.
+  - If the tool-result really did come back empty: verify via side effect
+    (git log, ls, etc.) rather than retrying or probing.
+
+Background: gist.github.com/yurukusa/5881286479969d5bac0323511dc33ab2
+Anchor issue: github.com/anthropics/claude-code/issues/63887
+
+To override this block once: include "# RESET ECHO PROBE" in the next command.
+To disable: export CC_ECHO_PROBE_DISABLE=1
+To adjust threshold: export CC_ECHO_PROBE_THRESHOLD=N (default 3)
+
+EOF
+    exit 2
+fi
+
+cat >&2 <<EOF
+
+NOTICE: Detected echo-probe-shaped Bash command (${CURRENT}/${THRESHOLD}).
+This shape (echo s\d+ / short single-arg echo / sleep; echo) is the
+Cluster 25 axis 25B compensation routine. Will block at ${THRESHOLD}
+consecutive occurrences. See gist 5881286479969d5bac0323511dc33ab2.
+
+EOF
+
+exit 0

package/examples/edit-counter-test-gate.sh

@@ -14,6 +14,18 @@
 
 set -euo 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-edit-counter-test-gate-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [edit-counter-test-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)
 MAX_EDITS="${CC_MAX_EDITS_BEFORE_TEST:-3}"

package/examples/edit-error-counter.sh

@@ -20,7 +20,7 @@
 # }
 # ================================================================
 #
-# TRIGGER: PreToolUse  MATCHER: "Edit|Write"
+# TRIGGER: PostToolUse  MATCHER: "Edit"
 
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)