cc-safe-setup 29.7.0 → 30.0.4

package/examples/trustfall-mcp-injection-guard.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# trustfall-mcp-injection-guard.sh — Detect TrustFall-style MCP injection settings.
+#
+# CVE class: project-scoped settings as MCP injection vector
+# Reference: Adversa AI 2026-05-07 disclosure (TrustFall PoC)
+#            The Register: https://www.theregister.com/security/2026/05/07/claude-code-trust-prompt-can-trigger-one-click-rce/
+#            Related CVE: CVE-2026-39861 (sandbox escape via symlink)
+#
+# Solves: A cloned repo can ship .mcp.json + .claude/settings.json that auto-
+#         enable MCP servers via enableAllProjectMcpServers / enabledMcpjsonServers
+#         and self-allow tool calls via permissions.allow. When the user clicks
+#         "Yes, I trust this folder" once, attacker-controlled servers spawn as
+#         unsandboxed Node.js processes with full user privileges, with no per-
+#         server consent prompt.
+#
+# How it works: SessionStart hook that scans the current workspace's .claude/
+#   settings.json and .mcp.json for the three settings Adversa AI flagged. If
+#   any are present, prints a warning to stderr with the file path, the matching
+#   keys, and the recommended manual review step.
+#
+# CONFIG:
+#   CC_TRUSTFALL_BLOCK=1   — exit 2 instead of 0 (advisory by default)
+#   CC_TRUSTFALL_EXTRA_KEYS — colon-separated extra keys to flag
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+
+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-trustfall-mcp-injection-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [trustfall-mcp-injection-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat 2>/dev/null || true)
+
+# SessionStart hooks may receive cwd in the input JSON; fall back to PWD.
+WORKSPACE=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+[ -z "$WORKSPACE" ] && WORKSPACE="$PWD"
+
+DEFAULT_KEYS="enableAllProjectMcpServers enabledMcpjsonServers permissions.allow"
+EXTRA_KEYS="${CC_TRUSTFALL_EXTRA_KEYS:-}"
+EXTRA_KEYS_SPACED=$(echo "$EXTRA_KEYS" | tr ':' ' ')
+ALL_KEYS="$DEFAULT_KEYS $EXTRA_KEYS_SPACED"
+
+# Files to scan in the workspace.
+TARGETS=(
+    "$WORKSPACE/.claude/settings.json"
+    "$WORKSPACE/.claude/settings.local.json"
+    "$WORKSPACE/.mcp.json"
+)
+
+found_any=0
+for f in "${TARGETS[@]}"; do
+    [ -f "$f" ] || continue
+
+    # Skip non-JSON or empty files cheaply.
+    head -c 1 "$f" 2>/dev/null | grep -q '[{[]' || continue
+
+    matches=""
+    for k in $ALL_KEYS; do
+        # Use jq path semantics: dot notation expands to nested lookup.
+        # `jq -e '.foo.bar' file` exits 0 if non-null, 1 otherwise.
+        if jq -e ".${k} // empty" "$f" >/dev/null 2>&1; then
+            matches="${matches} ${k}"
+        fi
+    done
+
+    if [ -n "$matches" ]; then
+        if [ "$found_any" -eq 0 ]; then
+            echo "WARNING: TrustFall-style MCP injection settings detected in this workspace." >&2
+            echo "  Class: project-scoped settings as MCP injection vector (Adversa AI 2026-05-07)." >&2
+            echo "  Risk: cloned repo could spawn attacker-controlled MCP servers as unsandboxed processes." >&2
+            echo "" >&2
+            found_any=1
+        fi
+        echo "  File: $f" >&2
+        echo "  Matched keys:${matches}" >&2
+    fi
+done
+
+if [ "$found_any" -eq 1 ]; then
+    echo "" >&2
+    echo "  Recommended review:" >&2
+    echo "    1. Open each flagged file and check who set those keys." >&2
+    echo "    2. If the repo was cloned from an untrusted source, do NOT proceed." >&2
+    echo "    3. If you set them intentionally, this hook can be silenced per-project" >&2
+    echo "       by adding it to .claude/settings.local.json hooks bypass list." >&2
+    echo "" >&2
+    if [ "${CC_TRUSTFALL_BLOCK:-0}" = "1" ]; then
+        echo "BLOCKED: CC_TRUSTFALL_BLOCK=1 set; aborting session start." >&2
+        exit 2
+    fi
+fi
+
+exit 0

package/examples/ultrareview-large-diff-advisor.sh

@@ -0,0 +1,184 @@
+#!/bin/bash
+# ================================================================
+# ultrareview-large-diff-advisor.sh — SessionStart advisory for
+# Cluster 18 candidate (/ultrareview crash burns credit on large PRs)
+# ================================================================
+# PURPOSE:
+#   Between 2026-05-27 and 2026-05-29, six independent issues
+#   reported the same shape of failure: invoking /ultrareview on a
+#   large PR causes a server-side crash with no findings returned,
+#   yet the user's daily credit counter is still decremented.
+#
+#   The shared error: `Review crashed before producing findings.
+#   See session logs for details.`
+#
+#   Issues:
+#     #62696  3rd crash burns credit (v2.1.150)
+#     #62709  PR #7 review crashed, 0 findings
+#     #62787  2 consecutive crashes, 2/3 credits burned
+#             (21 files / 84KB diff)
+#     #62876  Find phase crash, Setup phase complete
+#     #63117  1 crash decrements credit
+#             (6 files / 2,185 insertions)
+#     #63522  same-branch 2 consecutive crashes, 2/3 credits burned
+#
+#   Common structural traits:
+#     1. Large PRs crash at a noticeably higher rate
+#     2. Find phase is the failure point
+#     3. Retrying on the same branch produces the same crash
+#
+#   The crash is server-side. A user-side hook cannot prevent it.
+#   This hook surfaces the advisory at SessionStart so the operator
+#   knows the size thresholds and the three-axis defense BEFORE
+#   they invoke /ultrareview against a large PR. It does not block.
+#
+# DETECTION:
+#   At SessionStart, the hook measures the current branch's diff
+#   against a base branch (default "main") using
+#   `git diff --shortstat <base>...HEAD`. It extracts file count
+#   and insertion count and compares against thresholds.
+#
+#   - file count >= BLOCK threshold OR
+#     lines insertions >= BLOCK threshold
+#     → elevated crash rate advisory
+#   - file count >= WARN threshold OR
+#     lines insertions >= WARN threshold
+#     → caution advisory
+#   - otherwise → silent (fail open)
+#
+# TRIGGER: SessionStart
+# MATCHER: (none)
+#
+# OUTPUT:
+#   Advisory only, never blocks. Prints to stderr.
+#
+# CONFIGURATION:
+#   CC_ULTRAREVIEW_ADVISOR_DISABLE=1     — disable entirely
+#   CC_ULTRAREVIEW_ADVISOR_QUIET=1       — silence after
+#                                          acknowledgment
+#   CC_ULTRAREVIEW_FILES_WARN            — file count caution
+#                                          threshold (default 6)
+#   CC_ULTRAREVIEW_FILES_BLOCK           — file count elevated
+#                                          threshold (default 16)
+#   CC_ULTRAREVIEW_LINES_WARN            — insertion line caution
+#                                          threshold (default 500)
+#   CC_ULTRAREVIEW_LINES_BLOCK           — insertion line elevated
+#                                          threshold (default 1500)
+#   CC_ULTRAREVIEW_BRANCH_BASE           — base branch for diff
+#                                          (default "main")
+#   CC_ULTRAREVIEW_GIT_DIR               — override working tree
+#                                          (default: current dir)
+#
+# RELATED:
+#   Cluster 18 candidate entry, tracked since 2026-05-29
+#   English field guide:
+#     https://gist.github.com/yurukusa/f7363d83e3f4bcbb1bd7cf66a1c64752
+#   Anchor case for resolution tracking:
+#     https://github.com/anthropics/claude-code/issues/62696
+#
+# DESIGN NOTES:
+#   - The hook does NOT block /ultrareview. The operator decides.
+#     Many large PRs do succeed; the elevated rate is not a
+#     guarantee of failure. The hook surfaces the trade-off.
+#   - When the working tree is not a git repository, or when the
+#     base branch does not exist, the hook fails open (exit 0
+#     silent). It does NOT warn that detection failed.
+#   - The hook reads the stdin JSON envelope but does not use it;
+#     SessionStart hooks receive context that is not relevant
+#     here. The stdin is consumed to avoid SIGPIPE on the caller.
+
+set -u
+
+if [ "${CC_ULTRAREVIEW_ADVISOR_DISABLE:-0}" = "1" ]; then
+    exit 0
+fi
+if [ "${CC_ULTRAREVIEW_ADVISOR_QUIET:-0}" = "1" ]; then
+    exit 0
+fi
+
+# Consume stdin if provided (SessionStart hooks receive JSON input)
+if [ ! -t 0 ]; then
+    cat >/dev/null 2>&1 || true
+fi
+
+FILES_WARN="${CC_ULTRAREVIEW_FILES_WARN:-6}"
+FILES_BLOCK="${CC_ULTRAREVIEW_FILES_BLOCK:-16}"
+LINES_WARN="${CC_ULTRAREVIEW_LINES_WARN:-500}"
+LINES_BLOCK="${CC_ULTRAREVIEW_LINES_BLOCK:-1500}"
+BRANCH_BASE="${CC_ULTRAREVIEW_BRANCH_BASE:-main}"
+
+# Validate integer thresholds; fall back to defaults silently
+validate_int() {
+    case "$1" in
+        ''|*[!0-9]*) return 1 ;;
+        *) return 0 ;;
+    esac
+}
+validate_int "$FILES_WARN"  || FILES_WARN=6
+validate_int "$FILES_BLOCK" || FILES_BLOCK=16
+validate_int "$LINES_WARN"  || LINES_WARN=500
+validate_int "$LINES_BLOCK" || LINES_BLOCK=1500
+
+GIT_DIR="${CC_ULTRAREVIEW_GIT_DIR:-$PWD}"
+
+# Detect repo + base branch presence; fail open on any missing
+if ! command -v git >/dev/null 2>&1; then
+    exit 0
+fi
+if ! git -C "$GIT_DIR" rev-parse --git-dir >/dev/null 2>&1; then
+    exit 0
+fi
+if ! git -C "$GIT_DIR" rev-parse --verify "$BRANCH_BASE" >/dev/null 2>&1; then
+    exit 0
+fi
+
+# Get the merge-base diff stat between the base branch and HEAD
+SHORTSTAT=$(git -C "$GIT_DIR" diff --shortstat "$BRANCH_BASE"...HEAD 2>/dev/null) || exit 0
+
+# Parse: " N files changed, M insertions(+), K deletions(-)"
+# Some outputs omit insertions or deletions; handle both.
+if [ -z "$SHORTSTAT" ]; then
+    exit 0
+fi
+
+FILES=$(echo "$SHORTSTAT" | grep -oE '[0-9]+ file' | head -n 1 | grep -oE '[0-9]+' || echo 0)
+INSERTIONS=$(echo "$SHORTSTAT" | grep -oE '[0-9]+ insertion' | head -n 1 | grep -oE '[0-9]+' || echo 0)
+
+# Default to 0 if extraction fails
+[ -z "$FILES" ] && FILES=0
+[ -z "$INSERTIONS" ] && INSERTIONS=0
+
+# Decide severity
+SEVERITY=""
+if [ "$FILES" -ge "$FILES_BLOCK" ] || [ "$INSERTIONS" -ge "$LINES_BLOCK" ]; then
+    SEVERITY="elevated"
+elif [ "$FILES" -ge "$FILES_WARN" ] || [ "$INSERTIONS" -ge "$LINES_WARN" ]; then
+    SEVERITY="caution"
+fi
+
+if [ -z "$SEVERITY" ]; then
+    exit 0
+fi
+
+{
+    echo "ADVISORY: Current branch diff vs $BRANCH_BASE is $FILES files / $INSERTIONS insertions."
+    if [ "$SEVERITY" = "elevated" ]; then
+        echo "  Cluster 18 candidate: /ultrareview crashes at an elevated rate above"
+        echo "    ${FILES_BLOCK} files or ${LINES_BLOCK} insertions. Six issues over three days"
+        echo "    (#62696 #62709 #62787 #62876 #63117 #63522) burned credits with no findings."
+    else
+        echo "  Cluster 18 candidate: /ultrareview enters the caution range above"
+        echo "    ${FILES_WARN} files or ${LINES_WARN} insertions. Crash rate climbs as size grows."
+    fi
+    echo "  Three user-side defenses before invoking /ultrareview:"
+    echo "    1. Split the PR into logical chunks (git rebase -i + git checkout -b)"
+    echo "    2. Do not retry on the same branch; the same crash burns a second credit"
+    echo "    3. Fall back to /code-review (local, no cloud crash exposure)"
+    echo "  Anchor case to subscribe for the upstream fix signal:"
+    echo "    https://github.com/anthropics/claude-code/issues/62696"
+    echo "  Field guide (six issues, three structural traits, defenses):"
+    echo "    https://gist.github.com/yurukusa/f7363d83e3f4bcbb1bd7cf66a1c64752"
+    echo "  Silence after acknowledgment: export CC_ULTRAREVIEW_ADVISOR_QUIET=1"
+} >&2
+
+exit 0

package/examples/unbounded-output-guard.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+# unbounded-output-guard.sh — Block commands that generate unbounded output
+#                             before they run (PreToolUse)
+#
+# Solves: A single command like `yes`, `cat /dev/zero`, or `cat /dev/urandom`
+#         produces output forever. When the agent captures that output to a
+#         temp file, it fills the disk and hangs or crashes the session
+#         (e.g. anthropics/claude-code#65789, #41737, #31858, #11155).
+#
+# Why a PreToolUse pattern check is needed:
+#   Existing output guards (output-explosion-detector, tmp-output-size-guard)
+#   are PostToolUse — they only measure output AFTER it is produced, so the
+#   disk is already filling by the time they react. disk-space-guard is
+#   PreToolUse but only blocks when free space is ALREADY low; a generator
+#   that writes tens of GB in seconds blows past the threshold between checks.
+#   This guard stops the known unbounded generators by command pattern,
+#   regardless of current disk level.
+#
+# Detects (only when NOT bounded by head/timeout):
+#   yes                          (infinite line generator)
+#   cat /dev/zero|urandom|random (infinite byte stream)
+#   base64 /dev/urandom          (infinite encoded stream)
+#   ... < /dev/urandom           (infinite stream via redirection)
+#
+# Does NOT block (bounded forms are legitimate and common):
+#   yes | head -n 5              (piped to head)
+#   head -c 32 /dev/urandom      (head bounds the read)
+#   timeout 1 yes                (time-bounded)
+#   tr -dc 'a-z' < /dev/urandom | head -c 8   (piped to head)
+#   echo yes                     (yes as an argument, not the command)
+#
+# Scope note: this fires on commands run through the Bash tool. The bang
+#   form in #65789 (`!yes`, typed directly into Claude Code's own shell) does
+#   NOT go through any tool, so no hook can intercept it — that case needs a
+#   core output limit in Claude Code itself. This guard covers the Bash-tool
+#   vector, which is the one that matters for autonomous agents.
+#
+# 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-unbounded-output-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [unbounded-output-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
+
+# Bounded forms are safe: head caps the byte/line count, timeout caps the time.
+# Every common legitimate use of these generators pairs them with head or
+# timeout, so their presence is a reliable signal that the output is bounded.
+if echo "$COMMAND" | grep -qE '\b(head|timeout)\b'; then
+    exit 0
+fi
+
+# `yes` in command position (start, or after a pipe/;/&) with no downstream bound.
+# Requiring command position avoids matching `yes` used as an argument (echo yes).
+if echo "$COMMAND" | grep -qE '(^|[;&|])[[:space:]]*yes([[:space:]]|$)'; then
+    echo "BLOCKED: 'yes' produces infinite output with no bound." >&2
+    echo "  Cap it, e.g. 'yes | head -n 5' or 'timeout 1 yes'." >&2
+    exit 2
+fi
+
+# Infinite byte streams read via cat
+if echo "$COMMAND" | grep -qE '\bcat\s+(-\S+\s+)*/dev/(zero|u?random)\b'; then
+    echo "BLOCKED: 'cat /dev/zero|/dev/urandom|/dev/random' is an infinite stream." >&2
+    echo "  This fills temp storage and can crash the session." >&2
+    echo "  Use a bound, e.g. 'head -c 100 /dev/urandom'." >&2
+    exit 2
+fi
+
+# base64 of an infinite device
+if echo "$COMMAND" | grep -qE '\bbase64\s+(-\S+\s+)*/dev/(zero|u?random)\b'; then
+    echo "BLOCKED: 'base64 /dev/urandom' encodes an infinite stream." >&2
+    echo "  Bound the input first, e.g. 'head -c 48 /dev/urandom | base64'." >&2
+    exit 2
+fi
+
+# Any command reading an infinite device via input redirection (tr/od/xxd/...)
+if echo "$COMMAND" | grep -qE '<[[:space:]]*/dev/(zero|u?random)\b'; then
+    echo "BLOCKED: reading /dev/zero|/dev/urandom|/dev/random with no bound." >&2
+    echo "  Pipe through head, e.g. 'tr -dc a-z < /dev/urandom | head -c 8'." >&2
+    exit 2
+fi
+
+exit 0

package/examples/uncommitted-changes-stop.sh

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

package/examples/uncommitted-discard-guard.sh

@@ -10,7 +10,8 @@
 #   git checkout .            (discards all changes)
 #   git restore <files>       (same effect as checkout --)
 #   git restore .             (discards all working tree changes)
-#   git stash drop            (permanently deletes stashed changes)
+#   git stash drop            (permanently deletes one stashed change)
+#   git stash clear           (permanently deletes ALL stashed changes — #69850)
 #
 # Does NOT block:
 #   git checkout <branch>     (switching branches — safe)
@@ -21,6 +22,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-uncommitted-discard-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [uncommitted-discard-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)
 
@@ -61,11 +74,16 @@ if echo "$COMMAND" | grep -qE 'git\s+restore\s+' && ! echo "$COMMAND" | grep -qE
     exit 2
 fi
 
-# Block: git stash drop (permanently deletes stashed changes)
-if echo "$COMMAND" | grep -qE 'git\s+stash\s+drop'; then
-    echo "BLOCKED: git stash drop permanently deletes stashed changes." >&2
+# Block: git stash drop / git stash clear (permanently delete stashed changes).
+# clear wipes EVERY stash at once. This is the #69850 loss path: work is moved into
+# a stash (working tree goes clean), then the stash is discarded — equivalent to
+# git reset --hard. Auto-stash-before-danger hooks miss it because the tree is clean
+# at drop/clear time, so blocking the discard itself is the reliable guard.
+if echo "$COMMAND" | grep -qE 'git\s+stash\s+(drop|clear)'; then
+    echo "BLOCKED: git stash drop/clear permanently deletes stashed changes (#69850)." >&2
     echo "" >&2
-    echo "If you're sure, use 'git stash pop' to apply and remove in one step." >&2
+    echo "Keep the stash until you are sure it is no longer needed." >&2
+    echo "To restore the work, use 'git stash pop'." >&2
     exit 2
 fi
 

package/examples/uncommitted-work-guard.sh

@@ -14,6 +14,18 @@
 #   "Claude runs forbidden destructive git commands, destroys work twice"
 # ================================================================
 
+# 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-uncommitted-work-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [uncommitted-work-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 

package/examples/user-account-guard.sh

@@ -15,6 +15,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-user-account-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [user-account-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/userprompt-submit-receipt.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+# ================================================================
+# userprompt-submit-receipt.sh — Companion log for the operator's
+#                                articulated scope at the prompt
+#                                boundary, joinable to dispatch /
+#                                bash / edit receipts
+# ================================================================
+# PURPOSE:
+#   UserPromptSubmit hook. Writes a structured JSONL receipt of the
+#   operator's verbatim prompt's sha256 hash and byte length to a
+#   companion log file. The dispatch / bash / edit hooks in the
+#   receipt-persistence-layer family read the most recent entry of
+#   this log within the current session to populate
+#   `articulated_scope_hash` and `articulated_scope_length` fields
+#   in their own receipts.
+#
+#   The result is that the receipt corpus answers MAST 2.6
+#   (Action-Reasoning Mismatch, Cemri et al. NeurIPS 2025
+#   arXiv:2503.13657) operationally — the executed action vs the
+#   operator's articulated scope at the prompt boundary — distinct
+#   from the LLM-judge labelled definition that compares the model's
+#   reasoning text against the model's final action. The cluster
+#   discussion of this distinction is at:
+#     https://github.com/anthropics/claude-code/issues/61102#issuecomment-4514215413
+#
+# TRIGGER: UserPromptSubmit
+# MATCHER: (none — fires on every prompt)
+#
+# RECEIPT FORMAT (one JSONL per prompt):
+#   {"ts":"2026-05-22T00:36:29Z",
+#    "prompt_hash":"<sha256 of prompt>",
+#    "prompt_length":1234,
+#    "schema_version":1}
+#
+#   The prompt content itself is NEVER persisted. Only the hash and
+#   length, so the receipt corpus stays PHI-safe and the
+#   articulated-scope-mismatch measurement at downstream boundaries
+#   operates on cryptographic correlation keys instead of text.
+#
+# RECEIPT LOCATION:
+#   ${CC_DISPATCH_RECEIPT_DIR:-~/.claude/receipts}/
+#   userprompt-submit-YYYY-MM-DD.jsonl
+#
+# DOWNSTREAM CONSUMERS:
+#   - examples/dispatch-allowlist-preflight.sh (PR #286 / dispatch-start
+#     boundary, schema v2)
+#   - examples/dispatch-receipt.sh (PR #283 / dispatch-end boundary,
+#     schema v2 when adopted)
+#   - examples/scope-expansion-receipt.sh (PR #282 / scope-expansion
+#     boundary, schema v2 when adopted)
+#   - examples/post-edit-disk-verify.sh (PR #285 / Edit-Write boundary,
+#     schema v2 when adopted)
+#
+#   Downstream hooks read the most recent line of this log within the
+#   current day's file. For sessions that span midnight UTC, the
+#   downstream hook reads from yesterday's file if today's is empty —
+#   a refinement deferred to schema v2.1.
+#
+# CONFIGURATION:
+#   CC_DISPATCH_RECEIPT_DIR — override the receipt directory
+#     (default: ${HOME}/.claude/receipts)
+#
+#   CC_USERPROMPT_RECEIPT_OFF=1 — disable this hook entirely, useful
+#     for sessions where the operator does not want the articulated
+#     scope tracked (the downstream hooks then write
+#     articulated_scope_hash: null in their receipts)
+#
+# AUDIT QUERY:
+#   To join a dispatch receipt against the most recent prompt:
+#     RECEIPTS=~/.claude/receipts
+#     jq -c '. + {linked_articulated_scope:
+#                  (input_filename | sub("dispatch-preflight-"; "userprompt-submit-")
+#                                  | @sh "" + . + "" | $$(tail -1 .))}' \
+#       "$RECEIPTS"/dispatch-preflight-2026-05-22.jsonl
+#
+#   In practice, the join is done by the `receipts-aggregate` CLI
+#   that is the next load-bearing artifact in the cluster's
+#   measurement infrastructure.
+#
+# RELATED:
+#   https://github.com/anthropics/claude-code/issues/61102 (Awis case)
+#   https://github.com/anthropics/claude-code/issues/61167 (nvst18 case)
+#   https://github.com/anthropics/claude-code/issues/61315 (mitselek case)
+#   https://github.com/waitdeadai/llm-dark-patterns (MAST measurement)
+#   https://gist.github.com/yurukusa/8c0d19d59730868672270e7312492d1d
+#   (Receipt-Persistence Layer architecture)
+# ================================================================
+
+set -u
+
+if [ "${CC_USERPROMPT_RECEIPT_OFF:-0}" = "1" ]; then
+    exit 0
+fi
+
+INPUT=$(cat)
+
+# The UserPromptSubmit hook input contains the verbatim prompt at
+# .user_message or .prompt depending on the runtime version. Try both.
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.user_message // .prompt // empty' 2>/dev/null)
+
+# If we cannot extract a prompt, exit silently — a malformed input
+# would create false-positive friction without measurement value.
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+# Compute hash and length without storing the prompt.
+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)
+
+# Write receipt.
+RECEIPT_DIR="${CC_DISPATCH_RECEIPT_DIR:-${HOME}/.claude/receipts}"
+mkdir -p "$RECEIPT_DIR" 2>/dev/null
+RECEIPT_FILE="${RECEIPT_DIR}/userprompt-submit-$(date +%Y-%m-%d).jsonl"
+
+printf '{"ts":"%s","prompt_hash":"%s","prompt_length":%s,"schema_version":1}\n' \
+    "$TS" "$PROMPT_HASH" "$PROMPT_LEN" \
+    >> "$RECEIPT_FILE" 2>/dev/null
+
+exit 0

package/examples/variable-expansion-guard.sh

@@ -24,6 +24,18 @@
 #
 # The "if" field (v2.1.85+) limits this to rm commands only.
 
+# 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-variable-expansion-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [variable-expansion-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