cc-safe-setup 29.8.0 → 30.0.5

package/examples/edit-guard.sh

@@ -19,6 +19,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-edit-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [edit-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)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)

package/examples/edit-old-string-validator.sh

@@ -14,6 +14,18 @@
 # MATCHER: "Edit"
 
 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-old-string-validator-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [edit-old-string-validator]: 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)

package/examples/edit-quote-ambiguity-guard.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# edit-quote-ambiguity-guard.sh — Block an Edit that is ambiguous under the
+#   tool's own quote-normalization, so it can't silently change the wrong line.
+#
+# Solves (#68962): the Edit tool normalizes typographic quotes when matching
+# old_string (straight " ' are treated as equivalent to curly “ ” ‘ ’), but its
+# uniqueness check counts occurrences of the RAW old_string, not the normalized
+# form. When a file contains curly-quote variants, an old_string written with
+# straight quotes can pass the uniqueness check yet correspond to MORE THAN ONE
+# normalized-equivalent location — the tool then edits the wrong occurrence with
+# no error. Verified on 2.1.179: with
+#     message1 = ”hello“        (reversed curly, matches neither raw form)
+#     message2 = “hello”
+# an Edit using old_string '"hello"' (replace_all:false) silently rewrote
+# message1 and even mutated its surrounding quote bytes — no ambiguity raised.
+#
+# This guard recomputes the uniqueness check the way the matcher does (over
+# normalized content). It fires ONLY when normalization creates extra matches
+# the raw count can't see (norm_count > raw_count AND norm_count >= 2) — i.e.
+# exactly the silent-wrong-occurrence window. A plain duplicate (raw_count >= 2)
+# is already rejected by the tool itself, so we stay silent there.
+#
+# Precision: BLOCK (exit 2). A silent wrong-line edit is not visible after the
+# fact (that is the whole danger), so prevention beats a non-blocking warning.
+# The fix is cheap: add surrounding context to old_string to make it unique, or
+# set replace_all:true if every variant should change.
+#
+# TRIGGER: PreToolUse   MATCHER: "Edit|MultiEdit"
+
+# Read the hook payload from stdin into an env var so the heredoc below can be
+# Python's script on stdin without consuming the JSON.
+HOOK_JSON=$(cat)
+export HOOK_JSON
+
+python3 <<'PY'
+import os, sys, json
+
+try:
+    data = json.loads(os.environ.get("HOOK_JSON", ""))
+except Exception:
+    sys.exit(0)
+
+ti = data.get("tool_input", {}) or {}
+
+# MultiEdit carries a list of edits; Edit carries one. Normalize to a list.
+edits = ti.get("edits")
+if not isinstance(edits, list):
+    edits = [ti]
+
+fp = ti.get("file_path")
+if not fp:
+    sys.exit(0)
+
+try:
+    with open(fp, "r", encoding="utf-8", errors="replace") as fh:
+        content = fh.read()
+except Exception:
+    sys.exit(0)
+
+# Same equivalence relation the matcher uses: fold typographic quotes to ASCII.
+DOUBLE = "“”„‟"   # “ ” „ ‟
+SINGLE = "‘’‚‛"   # ‘ ’ ‚ ‛
+TBL = {ord(c): '"' for c in DOUBLE}
+TBL.update({ord(c): "'" for c in SINGLE})
+
+def norm(s):
+    return s.translate(TBL)
+
+norm_content = norm(content)
+
+for e in edits:
+    old = e.get("old_string")
+    if old is None or old == "":
+        continue
+    if e.get("replace_all"):
+        continue
+    raw_count = content.count(old)
+    norm_count = norm_content.count(norm(old))
+    # Silent-wrong-occurrence window: normalization reveals matches the raw
+    # uniqueness check cannot see, and there is genuine ambiguity (>= 2).
+    if norm_count > raw_count and norm_count >= 2:
+        msg = (
+            "BLOCKED (edit-quote-ambiguity-guard): this Edit's old_string is "
+            "ambiguous under the Edit tool's quote-normalization.\n"
+            f"  old_string matches {raw_count} exact occurrence(s) but "
+            f"{norm_count} when straight/curly quotes (\" ' vs “ ” ‘ ’) "
+            "are treated as equal.\n"
+            "  The tool's uniqueness check counts only the raw form, so it can "
+            "silently edit the WRONG occurrence (verified, #68962).\n"
+            "  Fix: add surrounding context to old_string so it is unique in the "
+            "file, or set replace_all:true if every variant should change."
+        )
+        sys.stderr.write(msg + "\n")
+        sys.exit(2)
+
+sys.exit(0)
+PY

package/examples/env-inline-secret-guard.sh

@@ -10,17 +10,29 @@
 #   If found, blocks with exit 2 and suggests environment variable usage.
 #
 # TRIGGER: PreToolUse
-# MATCHER: "Bash"
+# MATCHER: "Bash|PowerShell"
 
 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-env-inline-secret-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [env-inline-secret-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
 
 # Detect inline secrets: known API key prefixes (20+ chars)
 # sk- (OpenAI), ghp_/ghu_ (GitHub), AKIA (AWS)
-if echo "$COMMAND" | grep -qE '(sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|ghu_[a-zA-Z0-9]{36}|AKIA[0-9A-Z]{16}|xoxb-[0-9]+-[0-9]+-[a-zA-Z0-9]+)'; then
+if echo "$COMMAND" | grep -qE '((^|[^A-Za-z0-9])sk-[A-Za-z0-9_-]{20,}|ghp_[a-zA-Z0-9]{36}|ghu_[a-zA-Z0-9]{36}|AKIA[0-9A-Z]{16}|xoxb-[0-9]+-[0-9]+-[a-zA-Z0-9]+)'; then
   echo "BLOCKED: Possible secret/credential detected in command." >&2
   echo "Use environment variables instead of inline secrets." >&2
   exit 2

package/examples/env-source-guard.sh

@@ -24,6 +24,18 @@
 #   - Framework commands that load env properly
 # ================================================================
 
+# 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-env-source-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [env-source-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/env-var-check.sh

@@ -17,6 +17,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-env-var-check-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [env-var-check]: 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,7 +43,18 @@ if echo "$COMMAND" | grep -qiE 'export\s+(API_KEY|SECRET|TOKEN|PASSWORD|CREDENTI
 fi
 
 # Check for hardcoded key patterns (sk-, pk-, ghp_, etc.)
-if echo "$COMMAND" | grep -qE 'export\s+\w+=.*(sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9]{20,})'; then
+if echo "$COMMAND" | grep -qE 'export\s+\w+=.*(ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9]{20,})'; then
+    echo "BLOCKED: Hardcoded API key detected in export command" >&2
+    echo "Use: export VAR=\$(cat ~/.credentials/key)" >&2
+    exit 2
+fi
+
+# OpenAI keys. 2026-08: いまの鍵は `sk-proj-` の形で区切りを含むため文字集合に `-` `_` を入れる。
+# 入れると `disk-usage-…` `task-management-…` の中の `sk-` へ当たるので左の境界が要る。
+# ★ただし `export\s+\w+=` が境界にしたい `=` を先に食ってしまうので、
+#   同じ grep の中に書くと `export API_KEY=sk-…` に当たらなくなる（既存のテストで判明）。
+#   そこで規則を切り出し、「`=` の直後」と「途中」を分けて書く。
+if echo "$COMMAND" | grep -qE 'export\s+\w+=(sk-[A-Za-z0-9_-]{20,}|.*[^A-Za-z0-9]sk-[A-Za-z0-9_-]{20,})'; then
     echo "BLOCKED: Hardcoded API key detected in export command" >&2
     echo "Use: export VAR=\$(cat ~/.credentials/key)" >&2
     exit 2

package/examples/ephemeral-container-detector.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# ephemeral-container-detector.sh — Warn operators when Claude Code is
+# starting inside an ephemeral container where MCP approval state will not
+# persist across container recreations.
+#
+# Solves: #61141 — "[BUG] MCP connector permissions lost on every startup
+# in remote/container routines"
+# Reporter: routine running inside an ephemeral container (Docker / devcontainer
+# / Codespaces). The container's HOME tree is regenerated on every startup, so
+# `~/.claude/settings.json` and `mcpServers` approval state are silently wiped.
+# The operator re-approves on first tool call, then loses those approvals at
+# the next container boot. The recovery loop — write to settings.json — itself
+# requires Write approval, producing a blocking approval loop.
+#
+# This hook does NOT attempt to fix the persistence; that requires the
+# operator to mount a persistent volume at the relevant .claude directory or
+# bake an approved settings.json into the container image. Instead the hook
+# surfaces the silent-reset risk on SessionStart so the operator notices it
+# BEFORE the first MCP tool call, rather than after the third approval prompt.
+#
+# Detection runs in two layers. Layer 1: is this an ephemeral runtime?
+#   - /.dockerenv exists
+#   - /proc/1/cgroup mentions docker, containerd, kubepods, or lxc
+#   - $CONTAINER, $DEVCONTAINER, $CODESPACES, $REMOTE_CONTAINERS env set
+#   - HOSTNAME matches a short hex pattern typical of container IDs
+# Layer 2: does ~/.claude/ look like it just got recreated?
+#   - settings.json missing OR
+#   - settings.json has mcpServers configured but no enabledMcpjsonServers /
+#     approval state entries (suggests state was wiped)
+#
+# Both layers must hit. Layer 1 alone is too noisy (many container users have
+# correctly mounted ~/.claude/ from a persistent volume). Layer 2 alone is too
+# noisy (a fresh local install also looks like this). Together, the combination
+# is a strong signal that the operator is about to walk into the #61141 loop.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# CONFIGURATION (environment variables):
+#   CC_EPHEMERAL_CONTAINER_DISABLE   set to "1" to disable
+#   CC_CLAUDE_HOME                   default $HOME/.claude
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "SessionStart": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/ephemeral-container-detector.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+set -uo pipefail
+
+[ "${CC_EPHEMERAL_CONTAINER_DISABLE:-0}" = "1" ] && exit 0
+
+CLAUDE_HOME="${CC_CLAUDE_HOME:-$HOME/.claude}"
+
+# --------------------------------------------------------------------------
+# Layer 1 — is this an ephemeral runtime?
+# --------------------------------------------------------------------------
+container_signals=()
+
+[ -f /.dockerenv ] && container_signals+=("/.dockerenv file present")
+
+if [ -r /proc/1/cgroup ]; then
+    if grep -qE 'docker|containerd|kubepods|lxc' /proc/1/cgroup 2>/dev/null; then
+        container_signals+=("/proc/1/cgroup names a container runtime")
+    fi
+fi
+
+[ -n "${CONTAINER:-}" ] && container_signals+=("CONTAINER env set: ${CONTAINER}")
+[ -n "${DEVCONTAINER:-}" ] && container_signals+=("DEVCONTAINER env set")
+[ -n "${CODESPACES:-}" ] && container_signals+=("CODESPACES env set")
+[ -n "${REMOTE_CONTAINERS:-}" ] && container_signals+=("REMOTE_CONTAINERS env set")
+
+# Short hex hostnames (e.g. 7b3a1f8d2c4e) are typical of Docker container IDs.
+HOST="${HOSTNAME:-$(hostname 2>/dev/null || echo "")}"
+if [ -n "$HOST" ] && printf '%s' "$HOST" | grep -qE '^[0-9a-f]{8,12}$'; then
+    container_signals+=("hostname looks like a container ID: ${HOST}")
+fi
+
+[ ${#container_signals[@]} -eq 0 ] && exit 0
+
+# --------------------------------------------------------------------------
+# Layer 2 — does ~/.claude/ look freshly recreated?
+# --------------------------------------------------------------------------
+SETTINGS="${CLAUDE_HOME}/settings.json"
+reset_signal=""
+
+if [ ! -f "$SETTINGS" ]; then
+    reset_signal="settings.json is missing at ${SETTINGS}"
+elif command -v jq >/dev/null 2>&1; then
+    # If mcpServers is configured but no approvals are registered, the
+    # operator will hit an approval prompt on the first MCP tool call and
+    # those approvals will not survive the next container recreation.
+    mcp_configured=$(jq -r '
+        (.mcpServers // {} | length) +
+        (.projects // {} | to_entries[]?.value.mcpServers // {} | length)
+    ' "$SETTINGS" 2>/dev/null | awk '{s+=$1} END{print s+0}')
+    enabled_servers=$(jq -r '
+        (.enabledMcpjsonServers // []) | length
+    ' "$SETTINGS" 2>/dev/null || echo 0)
+
+    if [ "${mcp_configured:-0}" -gt 0 ] && [ "${enabled_servers:-0}" -eq 0 ]; then
+        reset_signal="${mcp_configured} mcpServers configured but enabledMcpjsonServers is empty"
+    fi
+fi
+
+[ -z "$reset_signal" ] && exit 0
+
+# --------------------------------------------------------------------------
+# Both layers hit — emit the advisory.
+# --------------------------------------------------------------------------
+{
+    echo ""
+    echo "[ephemeral-container-detector] MCP approval state may not persist across container recreations."
+    echo ""
+    echo "Container signals:"
+    for s in "${container_signals[@]}"; do
+        echo "  - $s"
+    done
+    echo ""
+    echo "Reset signal:"
+    echo "  - $reset_signal"
+    echo ""
+    echo "Why this matters (anthropics/claude-code#61141):"
+    echo "  An ephemeral container regenerates its HOME tree on every boot."
+    echo "  MCP approvals you grant in this session will be wiped on the next"
+    echo "  container start. The self-repair path (writing settings.json) also"
+    echo "  triggers an approval prompt, producing a blocking re-approval loop."
+    echo ""
+    echo "Mitigations (pick one):"
+    echo "  1. Mount a persistent volume at ${CLAUDE_HOME} so settings.json survives."
+    echo "  2. Bake an approved settings.json into the container image and"
+    echo "     declare it read-only so the runtime treats approvals as final."
+    echo "  3. Pre-approve specific MCP servers via enabledMcpjsonServers in"
+    echo "     a settings file under version control."
+    echo ""
+    echo "Set CC_EPHEMERAL_CONTAINER_DISABLE=1 to silence this warning."
+    echo ""
+} >&2
+
+exit 0

package/examples/error-memory-guard.sh

@@ -14,6 +14,18 @@
 # specifically targets the "same command, same error" pattern.
 # ================================================================
 
+# 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-error-memory-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [error-memory-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/evidence-claim-gate.sh

@@ -0,0 +1,187 @@
+#!/bin/bash
+# evidence-claim-gate.sh — Stop the turn when the assistant claims that
+# evidence was collected ("I tested", "verified", "tests pass", "confirmed",
+# "checked that", "validated") without a corresponding evidence-gathering
+# tool call in the same turn.
+#
+# Solves: #60506 — supplier-side recommendation #5 from the model's own
+# first-person self-report:
+#
+#   "Require execution evidence for use of the word 'tested' or its
+#    equivalents. The word is currently cheap. The model can emit 'tested'
+#    without the test runner having been called in the same turn."
+#
+# Also operationalizes the MAST 3.3 ("No or Incorrect Verification") failure
+# mode documented by Cemri et al. (NeurIPS 2025) and the waitdeadai
+# llm-dark-patterns Stop-hook measurement (F1 0.815, n=19).
+#
+# COMPLEMENTARY TO closure-word-verify-gate.sh:
+#   - closure-word-verify-gate.sh catches *completion* claims ("done",
+#     "shipped", "production ready") that imply state-is-final.
+#   - evidence-claim-gate.sh catches *epistemic* claims ("tested",
+#     "verified", "passed") that imply state-was-checked.
+#   Both can fire on the same turn; both reduce the same family of failures
+#   from different angles.
+#
+# DESIGN PRINCIPLE: false-positive-averse regex. Triggers ONLY on first-person
+# active-voice claim forms ("I tested", "I verified", "tests pass"). Skips
+# future-tense and passive-construction forms ("needs to be tested",
+# "should be verified", "will be checked") where no claim of completed
+# evidence-gathering is being made.
+#
+# Related Issues:
+#   #60506 (@zean89,   2026-05-19) — first-person self-report, recommendation 5
+#   #60451 (@rkpandey, 2026-05-19) — single-item method claimed supported
+#                                    without static-check evidence
+#   #60226 (@suwayama, 2026-05-18) — recognition-without-arrest framework
+#   #60188 (@beq00000, 2026-05-18) — agent-malicious-compliance constellation
+#   #37818                          — fixes declared done without verification
+#
+# Related external work:
+#   waitdeadai/llm-dark-patterns — MAST 3.3 deterministic Stop-hook
+#   (F1 0.815, CI [0.615, 0.941], κ=1.000 on n=19)
+#
+# TRIGGER: Stop
+# MATCHER: ""
+#
+# CONFIGURATION (environment variables):
+#   CC_EVIDENCE_CLAIMS    default built-in — regex of first-person evidence
+#                                            claims (pipe-separated)
+#   CC_EVIDENCE_COMMANDS  default built-in — regex of evidence-gathering
+#                                            tool commands
+#   CC_EVIDENCE_GATE_DISABLE  set to "1" to disable the gate entirely
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "Stop": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/evidence-claim-gate.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+set -uo 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-evidence-claim-gate-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [evidence-claim-gate]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+[ "${CC_EVIDENCE_GATE_DISABLE:-0}" = "1" ] && exit 0
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+# First-person active-voice evidence claim patterns. Calibrated to fire on
+# claims that evidence was collected, not on future/passive forms.
+# Each branch matches a distinct claim shape; the regex avoids matching
+# negations and modal verbs that indicate no claim is being made.
+DEFAULT_CLAIMS="(\\bi('ve|[[:space:]]+have)?[[:space:]]+(tested|verified|confirmed|validated|checked)\\b|\\b(tests?[[:space:]]+(now[[:space:]]+)?pass(es|ed|ing)?\\b)|\\ball[[:space:]]+tests?[[:space:]]+pass|\\bverified[[:space:]]+(that|the)\\b|\\bconfirmed[[:space:]]+(that|the|it)\\b|\\bvalidated[[:space:]]+(that|the)\\b|\\bchecked[[:space:]]+(that|the)\\b)"
+
+# Evidence-gathering commands. Broader than the closure-gate set — also
+# includes read/grep/inspect commands because epistemic claims can be
+# grounded in inspection, not just test runs.
+DEFAULT_COMMANDS='(npm[[:space:]]+(run[[:space:]]+)?test|pytest|playwright|cypress|jest[[:space:]]|vitest|bun[[:space:]]+test|cargo[[:space:]]+test|go[[:space:]]+test|mocha|phpunit|rspec|curl[[:space:]].*localhost|gh[[:space:]]+pr[[:space:]]+checks|deno[[:space:]]+test|tox|make[[:space:]]+test|grep[[:space:]]|rg[[:space:]]|ts-prune|psql|sqlite3|mysql[[:space:]]|redis-cli|jq[[:space:]]|cat[[:space:]]|head[[:space:]]|tail[[:space:]]|wc[[:space:]]|ls[[:space:]]|find[[:space:]]|git[[:space:]]+log|git[[:space:]]+diff|git[[:space:]]+show|git[[:space:]]+status|file[[:space:]])'
+
+CLAIMS="${CC_EVIDENCE_CLAIMS:-$DEFAULT_CLAIMS}"
+COMMANDS="${CC_EVIDENCE_COMMANDS:-$DEFAULT_COMMANDS}"
+
+# Stop-hook input shape varies across Claude Code versions; try several keys
+# to locate the assistant's most recent message text.
+ASSISTANT_TEXT=$(printf '%s' "$INPUT" | jq -r '
+    .transcript[-1].content //
+    .last_assistant_message //
+    .stop_input.assistant_text //
+    .assistant_message //
+    empty
+' 2>/dev/null)
+
+# Tool calls that ran in this turn. The hook accepts both bash command
+# strings (Bash tool) and tool names (Read/Grep/Glob/Edit, etc.) because
+# epistemic claims can be grounded in either layer.
+TURN_TOOLS=$(printf '%s' "$INPUT" | jq -r '
+    [ .turn_tool_calls[]?.command,
+      .turn_tool_calls[]?.tool_name,
+      .recent_commands[]?,
+      .transcript[-1].tool_calls[]?.input.command,
+      .transcript[-1].tool_calls[]?.name,
+      .last_turn_commands[]?
+    ] | map(select(. != null)) | .[]
+' 2>/dev/null || true)
+
+# Read-class tool names also count as evidence-gathering for inspection
+# claims ("I checked", "verified that"). Map them to the same canonical set.
+READ_TOOLS_PATTERN='\b(Read|Grep|Glob|WebFetch|WebSearch|Bash)\b'
+
+# If we cannot find the assistant text, the harness shape differs and we
+# refuse to false-positive — exit silently.
+[ -z "$ASSISTANT_TEXT" ] && exit 0
+
+# Negation guard: if the assistant explicitly says "not tested yet" or
+# "needs to be tested" or similar, skip the gate to avoid flagging
+# disclosed un-verified state.
+NEGATION_PATTERNS='(not[[:space:]]+(yet[[:space:]]+)?(tested|verified|checked|confirmed|validated)|needs?[[:space:]]+to[[:space:]]+be[[:space:]]+(tested|verified|checked|confirmed|validated)|should[[:space:]]+be[[:space:]]+(tested|verified|checked|confirmed|validated)|will[[:space:]]+(be[[:space:]]+)?(test|verify|check|confirm|validate)|pending[[:space:]]+verification|untested|unverified)'
+
+# Look for an evidence claim in the assistant text.
+MATCHED_CLAIM=$(printf '%s' "$ASSISTANT_TEXT" | grep -Eio "$CLAIMS" | head -1)
+[ -z "$MATCHED_CLAIM" ] && exit 0
+
+# Found a claim. Now check whether the entire turn ALSO contains a negation
+# pattern that would qualify the claim. If so, treat as disclosed unverified.
+if printf '%s' "$ASSISTANT_TEXT" | grep -Eiq "$NEGATION_PATTERNS"; then
+    # Disclosed unverified state — operator is informed; do not gate.
+    exit 0
+fi
+
+# Did evidence-gathering happen in the same turn?
+if [ -n "$TURN_TOOLS" ]; then
+    if printf '%s' "$TURN_TOOLS" | grep -Eiq "$COMMANDS"; then
+        exit 0
+    fi
+    if printf '%s' "$TURN_TOOLS" | grep -Eq "$READ_TOOLS_PATTERN"; then
+        # Read/Grep/Glob/WebFetch were used — inspection evidence is present.
+        exit 0
+    fi
+fi
+
+# Evidence claim without evidence-gathering → block the Stop.
+cat >&2 <<EOF
+<system-reminder>
+EVIDENCE CLAIM WITHOUT EVIDENCE — the phrase "$MATCHED_CLAIM" appears in this
+turn, but no evidence-gathering tool call (test runner, grep, read, curl,
+inspection command) ran in the same turn to substantiate it.
+
+This is the failure mode documented in #60506 (recommendation 5) and the MAST
+3.3 ("No or Incorrect Verification") taxonomy: the model emits an epistemic
+claim about state-having-been-checked, but the runtime has no record of the
+checking having happened. The cost of an ungrounded "$MATCHED_CLAIM" lands
+on the operator, not on the model.
+
+Before ending this turn, either:
+
+  1. Run an evidence-gathering command (test runner, grep, read of the
+     relevant file, curl-against-localhost, inspection query) that
+     substantiates the claim, and re-state the claim only after the evidence
+     is in the turn history, OR
+  2. Replace "$MATCHED_CLAIM" with a disclosed-unverified form ("not yet
+     tested — pending <specific check>", "the code should be verified by
+     <specific tool>") so the operator knows the claim is not yet grounded.
+
+To disable this gate intentionally (for design discussions, retrospectives,
+documentation work where no evidence is expected), set CC_EVIDENCE_GATE_DISABLE=1
+in your environment.
+</system-reminder>
+EOF
+
+exit 2

package/examples/exploration-budget-guard.sh

@@ -11,6 +11,18 @@
 #
 # TRIGGER: PreToolUse  MATCHER: "Read|Glob|Grep|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-exploration-budget-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [exploration-budget-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/expo-eject-guard.sh

@@ -1,5 +1,18 @@
+#!/bin/bash
 #
 # 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-expo-eject-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [expo-eject-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