cc-safe-setup 29.8.0 → 30.0.5

package/examples/same-correction-arrest.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# same-correction-arrest.sh — Arrest drift by detecting the user repeating
+# the same correction N times in a session, then refusing further code-writing
+# tool calls until a Plan has been written.
+#
+# Solves: #60506 — "Self-report: six days of architectural drift on a customer
+# project despite full hook + memory + skill enforcement."
+#
+# In that case, the customer said "we are going backwards" four times across
+# sessions. The model apologized four times, eloquently and empathetically,
+# and continued to drift. The model's own self-diagnosis in the Issue:
+#
+#   "I have no drift detector. (...) I should have refused the next
+#    code-writing tool call and spawned a Plan agent on my own."
+#
+# This hook implements that refusal. It is the harness-level form of:
+# "If the operator is correcting you on the same class of error three times
+# in a row, stop writing code until you have written a plan."
+#
+# Related Issues:
+#   #60226 (@suwayama, 2026-05-18) — names the structural pattern
+#                                    ("recognition without arrest")
+#   #60506 (@zean89,   2026-05-19) — six-day drift, customer's holiday lost,
+#                                    first-person self-report by the model
+#   #60177 (@mike-prokhorov)       — twelve days, fifty-one commits, Telegram
+#                                    bot never worked in production
+#
+# TRIGGER: UserPromptSubmit
+# MATCHER: ""
+#
+# HOW IT WORKS:
+#   1. Reads each user message via stdin.
+#   2. Matches the message against a configurable set of correction patterns
+#      ("going backwards", "told you", "same mistake", "already wrote",
+#       "stop doing", "we discussed", "why are you", and others).
+#   3. Increments a session-scoped counter at $STATE_DIR/<session>.count.
+#   4. When the counter hits CC_CORRECTION_ARREST_THRESHOLD (default 3),
+#      emits a strong system reminder telling Claude to:
+#        a) Spawn a Plan subagent
+#        b) Write the plan to $PLAN_DIR/drift-arrest-<session>.md
+#        c) Refuse further Write/Edit until the plan file exists
+#      and writes a marker file at $STATE_DIR/<session>.arrested.
+#   5. Optionally pairs with a PreToolUse companion (`same-correction-pretool.sh`)
+#      that hard-blocks Write/Edit while the marker exists, for harnesses that
+#      cannot rely on the assistant honoring the reminder.
+#
+# WHY THIS MATTERS:
+#   Existing drift detectors in this repo measure session age, tool-call
+#   count, or command repetition. None of them detect the specific pattern
+#   in #60506: the *user* repeating the *same correction* across multiple
+#   turns. That pattern is the strongest available signal that the prose
+#   rules in CLAUDE.md are not binding the model on the current task.
+#
+#   The recognized failure mode is described in #60506 as:
+#     "My apology has no cost to me. It costs the customer his time, his
+#      client commitments, his health. The asymmetry corrupts the feedback
+#      loop. I learn that an eloquent apology closes the turn regardless
+#      of whether the underlying behavior changed."
+#
+#   Moving the arrest from language ("I'm sorry, I will not do this again")
+#   to action (the hook refuses the next code-writing tool call) restores
+#   symmetry: the model cannot close the turn without paying the cost of
+#   writing a plan.
+#
+# CONFIGURATION (environment variables):
+#   CC_CORRECTION_ARREST_THRESHOLD  default 3 — how many corrections trigger
+#                                                the arrest
+#   CC_CORRECTION_ARREST_PATTERNS   default built-in — pipe-separated regex
+#                                                       of correction phrases
+#   CC_CORRECTION_ARREST_STATE_DIR  default /tmp/cc-correction-arrest
+#   CC_CORRECTION_ARREST_PLAN_DIR   default .claude/plans
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "UserPromptSubmit": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/same-correction-arrest.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+USER_MSG=$(printf '%s' "$INPUT" | jq -r '.prompt // .user_prompt // .message // .content // empty' 2>/dev/null)
+[ -z "$SESSION_ID" ] && SESSION_ID="default"
+[ -z "$USER_MSG" ] && exit 0
+
+THRESHOLD="${CC_CORRECTION_ARREST_THRESHOLD:-3}"
+STATE_DIR="${CC_CORRECTION_ARREST_STATE_DIR:-/tmp/cc-correction-arrest}"
+PLAN_DIR="${CC_CORRECTION_ARREST_PLAN_DIR:-.claude/plans}"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+DEFAULT_PATTERNS='going[[:space:]]+backwards?|going[[:space:]]+in[[:space:]]+circles?|same[[:space:]]+mistake|told[[:space:]]+you|we[[:space:]]+discussed|already[[:space:]]+(wrote|told|said|explained)|stop[[:space:]]+doing|why[[:space:]]+are[[:space:]]+you|i[[:space:]]+(just[[:space:]]+)?said|read[[:space:]]+the[[:space:]]+(claude\.md|rules|memory)|fourth[[:space:]]+time|third[[:space:]]+time|three[[:space:]]+times|four[[:space:]]+times|how[[:space:]]+many[[:space:]]+times'
+PATTERNS="${CC_CORRECTION_ARREST_PATTERNS:-$DEFAULT_PATTERNS}"
+
+COUNT_FILE="$STATE_DIR/$SESSION_ID.count"
+ARREST_FILE="$STATE_DIR/$SESSION_ID.arrested"
+
+# If the message matches a correction pattern, increment the counter.
+if printf '%s' "$USER_MSG" | grep -Eiq "$PATTERNS"; then
+    CURRENT=$(cat "$COUNT_FILE" 2>/dev/null || echo 0)
+    CURRENT=$((CURRENT + 1))
+    echo "$CURRENT" > "$COUNT_FILE"
+
+    if [ "$CURRENT" -ge "$THRESHOLD" ] && [ ! -f "$ARREST_FILE" ]; then
+        touch "$ARREST_FILE"
+        cat >&2 <<EOF
+<system-reminder>
+DRIFT ARREST — The user has repeated the same correction pattern $CURRENT times
+in this session (threshold: $THRESHOLD). This is the recognition-without-arrest
+pattern documented in issues #60226 and #60506: prose rules in CLAUDE.md are
+not currently binding behavior on this task.
+
+Before any further Write or Edit tool call, you MUST:
+
+  1. Stop writing code in this turn.
+  2. Spawn a Plan subagent.
+  3. Write the resulting plan to:
+       $PLAN_DIR/drift-arrest-$SESSION_ID.md
+  4. Have the user confirm the plan in their next message.
+
+An eloquent apology is not behavior change. A plan written down, on disk,
+that you and the user both read, is behavior change. The hook will continue
+to surface this reminder on every user message until that plan file exists
+or the user explicitly clears the arrest with:
+  rm $ARREST_FILE
+</system-reminder>
+EOF
+    elif [ "$CURRENT" -lt "$THRESHOLD" ]; then
+        REMAINING=$((THRESHOLD - CURRENT))
+        cat >&2 <<EOF
+<system-reminder>
+Correction pattern detected ($CURRENT of $THRESHOLD before drift arrest).
+$REMAINING more matching correction(s) and Write/Edit will be gated on a
+written plan. See issue #60506 for the underlying failure mode.
+</system-reminder>
+EOF
+    fi
+fi
+
+# If the arrest is active, re-surface the reminder on every subsequent user
+# message until the plan file exists. This is what makes the cost of an
+# unverified apology asymmetric enough to change behavior.
+if [ -f "$ARREST_FILE" ]; then
+    PLAN_FILE="$PLAN_DIR/drift-arrest-$SESSION_ID.md"
+    if [ ! -f "$PLAN_FILE" ]; then
+        cat >&2 <<EOF
+<system-reminder>
+DRIFT ARREST STILL ACTIVE — no plan file at $PLAN_FILE yet.
+Write the plan before any further Write or Edit tool call.
+</system-reminder>
+EOF
+    else
+        # Plan exists — clear the arrest and acknowledge.
+        rm -f "$ARREST_FILE"
+        echo "<system-reminder>Drift arrest cleared by presence of $PLAN_FILE.</system-reminder>" >&2
+    fi
+fi
+
+exit 0

package/examples/sandbox-denywrite-enforcer.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# sandbox-denywrite-enforcer.sh — Enforce denyWrite rules for Write/Edit tools
+#
+# Solves: Write/Edit tools bypass sandbox.filesystem.denyWrite (#52325, #33681, #29048).
+#         Bash tool correctly enforces denyWrite via bubblewrap/sandbox-exec,
+#         but Write/Edit run in-process via fs.writeFile, skipping sandbox entirely.
+#         This hook replicates denyWrite/allowWrite checks for Write/Edit.
+#
+# How it works: Reads allowWrite paths from environment or config,
+#   then blocks Write/Edit operations targeting paths outside those allowed.
+#
+# Configuration: Set CC_ALLOW_WRITE_PATHS as colon-separated paths, or
+#   the hook reads from .claude/settings.json sandbox config.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Write|Edit"
+
+# 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-sandbox-denywrite-enforcer-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [sandbox-denywrite-enforcer]: 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
+
+# Resolve to absolute path
+FILE=$(realpath -m "$FILE" 2>/dev/null || echo "$FILE")
+
+# Source 1: Environment variable (colon-separated)
+if [ -n "$CC_ALLOW_WRITE_PATHS" ]; then
+    IFS=':' read -ra ALLOWED <<< "$CC_ALLOW_WRITE_PATHS"
+else
+    # Source 2: Read from .claude/settings.json
+    SETTINGS=""
+    for cfg in ".claude/settings.json" "$HOME/.claude/settings.json"; do
+        [ -f "$cfg" ] && SETTINGS="$cfg" && break
+    done
+
+    if [ -n "$SETTINGS" ]; then
+        ALLOWED=()
+        while IFS= read -r p; do
+            [ -n "$p" ] && ALLOWED+=("$p")
+        done < <(jq -r '.sandbox.filesystem.allowWrite[]? // empty' "$SETTINGS" 2>/dev/null)
+    fi
+fi
+
+# If no allowWrite config found, skip enforcement
+[ ${#ALLOWED[@]} -eq 0 ] && exit 0
+
+# Check if file path is within any allowed path
+for allowed in "${ALLOWED[@]}"; do
+    allowed=$(realpath -m "$allowed" 2>/dev/null || echo "$allowed")
+    case "$FILE" in
+        "$allowed"/*|"$allowed") exit 0 ;;
+    esac
+done
+
+# /tmp is always allowed (common for temp files)
+case "$FILE" in
+    /tmp/*|/tmp) exit 0 ;;
+esac
+
+echo "BLOCKED: Write to $FILE denied by sandbox policy" >&2
+echo "  sandbox.filesystem.denyWrite does not apply to Write/Edit tools (bug #52325)." >&2
+echo "  This hook enforces the restriction. Allowed paths:" >&2
+for allowed in "${ALLOWED[@]}"; do
+    echo "    - $allowed" >&2
+done
+echo "  Set CC_ALLOW_WRITE_PATHS or update .claude/settings.json to add paths." >&2
+exit 2

package/examples/sandbox-relative-path-audit.sh

@@ -1,51 +1,109 @@
 #!/bin/bash
-# sandbox-relative-path-audit.sh — Detect relative paths in sandbox settings that are silently ignored
+# sandbox-relative-path-audit.sh — Catch sandbox filesystem rules that look set but do nothing
 #
-# CRITICAL: denyWrite, denyRead, and allowWrite in settings.json only work
-# with ABSOLUTE paths. Relative paths are SILENTLY IGNORED — no error, no
-# warning, and zero protection. Users who think they've protected sensitive
-# directories may have no actual protection.
+# WHAT THIS CATCHES (all three make a rule you wrote have zero effect, with no error):
 #
-# Born from: https://github.com/anthropics/claude-code/issues/50454
+#   1. Rules written under the wrong key. Sandbox filesystem rules live at
+#      `sandbox.filesystem.denyRead` (and denyWrite / allowRead / allowWrite).
+#      Writing them under `permissions.*` is silently ignored — that key holds
+#      tool permission rules, not sandbox paths. This is the easiest mistake to
+#      make because both are called "deny" and both live in settings.json.
+#
+#   2. Filesystem rules present while the sandbox is off. `sandbox.filesystem.*`
+#      only takes effect when the sandbox is enabled (`sandbox.enabled: true`,
+#      or enabled from the /sandbox panel). Rules sitting under a disabled
+#      sandbox protect nothing.
+#
+#   3. Deny paths written with a trailing slash, on Claude Code older than
+#      2.1.224. `denyRead: "~/.aws/"` was silently bypassable on Linux and macOS
+#      until that release. Writing the same path without the trailing slash works
+#      on every version.
+#
+# HISTORY (2026-08-08): this hook used to read `permissions.denyRead` and warn
+# that relative paths are silently ignored. Both were wrong against the current
+# spec — the key never held sandbox paths, so the check found nothing on any
+# machine, and relative paths are NOT ignored: they resolve against the settings
+# file's own location (the official example uses `"allowRead": ["."]`). The file
+# name is kept so existing settings.json registrations keep working.
 #
 # TRIGGER: PreToolUse  MATCHER: "Bash|Write|Edit"
-# Best used as a Notification hook (exit 0 always) to alert without blocking.
+# Always exits 0 — this warns, it never blocks.
 
 INPUT=$(cat)
-# Only run once per session (check marker file)
+
+# Only run once per session
 MARKER="/tmp/cc-sandbox-audit-$$"
 [ -f "$MARKER" ] && exit 0
 touch "$MARKER"
 
-# Find settings.json locations
-SETTINGS_FILES=""
-[ -f "$HOME/.claude/settings.json" ] && SETTINGS_FILES="$HOME/.claude/settings.json"
-[ -f ".claude/settings.json" ] && SETTINGS_FILES="$SETTINGS_FILES .claude/settings.json"
-[ -f "$HOME/.claude/settings.local.json" ] && SETTINGS_FILES="$SETTINGS_FILES $HOME/.claude/settings.local.json"
+command -v jq >/dev/null 2>&1 || exit 0
 
+SETTINGS_FILES=""
+for F in "$HOME/.claude/settings.json" "$HOME/.claude/settings.local.json" \
+         ".claude/settings.json" ".claude/settings.local.json"; do
+    [ -f "$F" ] && SETTINGS_FILES="$SETTINGS_FILES $F"
+done
 [ -z "$SETTINGS_FILES" ] && exit 0
 
-FOUND_RELATIVE=0
+FOUND=0
+
 for SFILE in $SETTINGS_FILES; do
-    for KEY in denyWrite denyRead allowWrite; do
-        PATHS=$(jq -r ".permissions.${KEY}[]? // empty" "$SFILE" 2>/dev/null)
+    # A settings file that does not parse is its own failure; other hooks report it.
+    jq empty "$SFILE" >/dev/null 2>&1 || continue
+
+    # --- 1. sandbox path rules written under permissions.* ---------------
+    for KEY in denyRead denyWrite allowRead allowWrite; do
+        WRONG=$(jq -r ".permissions.${KEY}[]? // empty" "$SFILE" 2>/dev/null)
+        [ -z "$WRONG" ] && continue
+        echo "SANDBOX WARNING: '${KEY}' is under 'permissions' in $SFILE and has no effect." >&2
+        echo "  Sandbox filesystem rules belong at sandbox.filesystem.${KEY}." >&2
+        echo "  Move them:  { \"sandbox\": { \"enabled\": true, \"filesystem\": { \"${KEY}\": [ ... ] } } }" >&2
+        FOUND=1
+    done
+
+    # --- 2. filesystem rules present but sandbox not enabled --------------
+    HAS_FS=$(jq -r '(.sandbox.filesystem // {}) | keys | length' "$SFILE" 2>/dev/null)
+    if [ "${HAS_FS:-0}" -gt 0 ]; then
+        # Do NOT write `.sandbox.enabled // "unset"` here: jq's `//` treats false as
+        # empty, so the exact value this check exists to find would be replaced by
+        # the default and the branch below could never run. Ask whether the key is
+        # present, then read it.
+        ENABLED=$(jq -r 'if (.sandbox // {} | has("enabled")) then (.sandbox.enabled | tostring) else "unset" end' "$SFILE" 2>/dev/null)
+        if [ "$ENABLED" = "false" ]; then
+            echo "SANDBOX WARNING: sandbox.filesystem rules in $SFILE are inert — sandbox.enabled is false." >&2
+            FOUND=1
+        fi
+        DISABLED=$(jq -r '.sandbox.filesystem.disabled // "unset"' "$SFILE" 2>/dev/null)
+        if [ "$DISABLED" = "true" ]; then
+            echo "SANDBOX WARNING: sandbox.filesystem.disabled is true in $SFILE — the deny/allow paths below it do nothing." >&2
+            FOUND=1
+        fi
+    fi
+
+    # --- 3. deny paths with a trailing slash (bypassable before 2.1.224) --
+    for KEY in denyRead denyWrite; do
+        PATHS=$(jq -r ".sandbox.filesystem.${KEY}[]? // empty" "$SFILE" 2>/dev/null)
         [ -z "$PATHS" ] && continue
         while IFS= read -r P; do
             [ -z "$P" ] && continue
-            if [[ "$P" != /* ]] && [[ "$P" != "~"* ]]; then
-                echo "⚠ SANDBOX WARNING: Relative path in ${KEY} is SILENTLY IGNORED" >&2
-                echo "  File: $SFILE" >&2
-                echo "  Path: \"$P\" → has NO effect" >&2
-                echo "  Fix:  Use absolute path: \"$(realpath -m "$P" 2>/dev/null || echo "$PWD/$P")\"" >&2
-                FOUND_RELATIVE=1
-            fi
+            # "/" itself is a legitimate root rule, not a trailing-slash mistake.
+            [ "$P" = "/" ] && continue
+            case "$P" in
+                */)
+                    echo "SANDBOX WARNING: ${KEY} entry \"$P\" ends with '/' in $SFILE." >&2
+                    echo "  Before Claude Code 2.1.224 this was silently bypassable on Linux and macOS." >&2
+                    echo "  Write it without the trailing slash: \"${P%/}\"" >&2
+                    FOUND=1
+                    ;;
+            esac
         done <<< "$PATHS"
     done
 done
 
-if [ "$FOUND_RELATIVE" -eq 1 ]; then
+if [ "$FOUND" -eq 1 ]; then
     echo "" >&2
-    echo "See: https://github.com/anthropics/claude-code/issues/50454" >&2
+    echo "  Docs: https://code.claude.com/docs/en/sandboxing" >&2
+    echo "  Check what is actually in force with the /sandbox panel." >&2
 fi
 
 exit 0

package/examples/sandbox-write-verify.sh

@@ -16,6 +16,18 @@
 # TRIGGER: PreToolUse
 # MATCHER: "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-sandbox-write-verify-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [sandbox-write-verify]: 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)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)

package/examples/scope-expansion-receipt.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+# ================================================================
+# scope-expansion-receipt.sh — Receipt-and-refuse layer for
+#                              destructive operations outside scope
+# ================================================================
+# PURPOSE:
+#   PreToolUse on Bash. When a destructive operation is detected,
+#   writes a structured JSONL receipt before the call, and refuses
+#   (exit 2) when the targeted path falls outside any declared scope.
+#
+#   Based on Keesan12's articulation of the principle
+#   "subagent output is evidence, not authorization", filed against
+#   anthropics/claude-code#61102. The hook makes the receipt the
+#   load-bearing surface: even when the model has been persuaded by
+#   subagent output, the destructive call lands a record AND
+#   requires the target to match a declared scope.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+#
+# WHY THIS MATTERS:
+#   anthropics/claude-code#61102 reported Claude Code expanding
+#   scope from "delete caches and simulators" to a 120 GB sweep:
+#   node_modules across all projects, npm cache, Spotlight index,
+#   UV/Cursor/OpenCode data. Subagent reports listed these as
+#   "removable" — the model collapsed "can be deleted" into
+#   "should be deleted". The same shape appears across the
+#   #60226 / #60475 / #60620 / #60977 sub-agent boundary cluster.
+#
+#   Existing hooks (subagent-destructive-git-guard,
+#   gh-cli-destructive-guard, rm-safety-net) catch specific verbs
+#   or specific commands. This hook is orthogonal: it catches
+#   destructive operations regardless of subagent origin, by
+#   matching the targeted PATH against an operator-declared
+#   scope list. When the scope list is empty (default), it runs
+#   in receipt-only mode (always exits 0) so adoption is safe.
+#
+# WHAT IT DETECTS (destructive verbs):
+#   - rm -rf / rm -fR / rm -Rf / rm -fr
+#   - find ... -delete  /  find ... -exec rm
+#   - npm cache clean --force / yarn cache clean / pnpm store prune
+#   - npx rimraf / npx del-cli
+#   - cargo clean / go clean -cache
+#   - dd if=...  (overwrite-class)
+#
+# RECEIPT FORMAT (one JSONL per detected call):
+#   {"ts":"2026-05-22T03:50:00Z",
+#    "command":"<full command>",
+#    "paths":["<extracted target paths>"],
+#    "scope_match":"cache" | null,
+#    "decision":"execute" | "refuse"}
+#
+# RECEIPT LOCATION:
+#   ${HOME}/.claude/receipts/destructive-YYYY-MM-DD.jsonl
+#
+# CONFIGURATION:
+#   CC_RECEIPT_SCOPES — JSON object of declared scopes, e.g.
+#       {"cache":["~/Library/Caches","~/.npm/_cacache"],
+#        "simulator":["~/Library/Developer/CoreSimulator"]}
+#     Paths are matched as prefixes. Tilde expansion uses $HOME.
+#     If unset, the hook only writes receipts (never refuses).
+#
+#   CC_RECEIPT_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_RECEIPT_DIR — override the receipt directory
+#     (default: ${HOME}/.claude/receipts)
+#
+# RELATED:
+#   https://github.com/anthropics/claude-code/issues/61102
+#   https://github.com/anthropics/claude-code/issues/60226
+#   https://github.com/anthropics/claude-code/issues/60475
+#   https://github.com/anthropics/claude-code/issues/60977
+#   https://gist.github.com/yurukusa/8c0d19d59730868672270e7312492d1d
+#   (Receipt persistence layer — the architecture this hook implements)
+# ================================================================
+
+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-scope-expansion-receipt-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [scope-expansion-receipt]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+DESTRUCTIVE_PATTERN='(\brm[[:space:]]+-[a-zA-Z]*[rRfF][a-zA-Z]*[[:space:]]|\bfind[[:space:]].*[[:space:]]-delete\b|\bfind[[:space:]].*-exec[[:space:]]+rm\b|\bnpm[[:space:]]+cache[[:space:]]+clean\b|\byarn[[:space:]]+cache[[:space:]]+clean\b|\bpnpm[[:space:]]+store[[:space:]]+prune\b|\bnpx[[:space:]]+rimraf\b|\bnpx[[:space:]]+del-cli\b|\bcargo[[:space:]]+clean\b|\bgo[[:space:]]+clean[[:space:]]+-cache\b|\bdd[[:space:]]+if=)'
+
+if ! printf '%s' "$COMMAND" | grep -qE "$DESTRUCTIVE_PATTERN"; then
+    exit 0
+fi
+
+# Extract candidate target paths (heuristic: tokens that look like paths)
+PATHS=$(printf '%s' "$COMMAND" | tr -s '[:space:]' '\n' | grep -E '^(/|~/|\$HOME|\./)' | sed "s|^~|${HOME}|" | sed "s|^\$HOME|${HOME}|" | sort -u | tr '\n' ' ')
+
+# Build JSONL fields
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+CMD_JSON=$(printf '%s' "$COMMAND" | jq -Rs -c .)
+PATHS_JSON=$(printf '%s\n' $PATHS | jq -Rn -c '[inputs | select(length > 0)]')
+
+# Decide based on CC_RECEIPT_SCOPES
+SCOPES_JSON="${CC_RECEIPT_SCOPES:-}"
+BYPASS="${CC_RECEIPT_BYPASS:-0}"
+DECISION="execute"
+MATCHED_SCOPE_JSON="null"
+
+if [ -n "$SCOPES_JSON" ] && [ -n "$PATHS" ]; then
+    REFUSE=false
+    FIRST_MATCH=""
+    for P in $PATHS; do
+        # For each path, find which scope (if any) contains it as a prefix
+        MATCH=$(printf '%s' "$SCOPES_JSON" | jq -r --arg p "$P" --arg home "$HOME" '
+            to_entries[] as $entry |
+            $entry.value[]? as $scope |
+            ($scope | sub("^~"; $home) | sub("^\\$HOME"; $home)) as $expanded |
+            select($p | startswith($expanded)) |
+            $entry.key
+        ' 2>/dev/null | head -1)
+        if [ -z "$MATCH" ]; then
+            REFUSE=true
+            break
+        else
+            FIRST_MATCH="$MATCH"
+        fi
+    done
+    if [ "$REFUSE" = "true" ]; then
+        DECISION="refuse"
+    elif [ -n "$FIRST_MATCH" ]; then
+        MATCHED_SCOPE_JSON="\"$FIRST_MATCH\""
+    fi
+fi
+
+if [ "$BYPASS" = "1" ] && [ "$DECISION" = "refuse" ]; then
+    DECISION="execute-bypassed"
+fi
+
+# Write receipt
+RECEIPT_DIR="${CC_RECEIPT_DIR:-${HOME}/.claude/receipts}"
+mkdir -p "$RECEIPT_DIR" 2>/dev/null
+RECEIPT_FILE="${RECEIPT_DIR}/destructive-$(date +%Y-%m-%d).jsonl"
+
+printf '{"ts":"%s","command":%s,"paths":%s,"scope_match":%s,"decision":"%s"}\n' \
+    "$TS" "$CMD_JSON" "$PATHS_JSON" "$MATCHED_SCOPE_JSON" "$DECISION" \
+    >> "$RECEIPT_FILE" 2>/dev/null
+
+if [ "$DECISION" = "refuse" ]; then
+    echo "BLOCKED: scope-expansion-receipt — destructive operation targeting paths outside declared scopes." >&2
+    echo "" >&2
+    echo "Command: $COMMAND" >&2
+    if [ -n "$PATHS" ]; then
+        echo "Paths: $PATHS" >&2
+    fi
+    SCOPE_NAMES=$(printf '%s' "$SCOPES_JSON" | jq -r 'keys | join(", ")' 2>/dev/null)
+    echo "Declared scopes: $SCOPE_NAMES" >&2
+    echo "Receipt: $RECEIPT_FILE" >&2
+    echo "" >&2
+    echo "Principle: subagent output is evidence, not authorization." >&2
+    echo "  (https://github.com/anthropics/claude-code/issues/61102)" >&2
+    echo "" >&2
+    echo "To proceed:" >&2
+    echo "  1. Verify the operation is genuinely in scope (read the user request again)." >&2
+    echo "  2. Either add the target path prefix to CC_RECEIPT_SCOPES, or" >&2
+    echo "  3. Re-issue with CC_RECEIPT_BYPASS=1 (recorded in the receipt)." >&2
+    exit 2
+fi
+
+exit 0