cc-safe-setup 29.7.0 → 30.0.4

package/examples/cross-product-mcp-spawn-detector.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+# ================================================================
+# cross-product-mcp-spawn-detector.sh — Warn when MCP server spawn
+#                                       configs exist in cross-product
+#                                       state paths outside Claude Code
+# ================================================================
+# PURPOSE:
+#   On session start, scans known cross-product application-support
+#   paths (where Claude Desktop or other Anthropic products store
+#   plugin metadata) for .mcp.json files that contain user-blocklisted
+#   plugin names. If found, warns that those MCP servers will spawn
+#   on the next Claude Code session regardless of any
+#   `enabledPlugins: false` or `blocklist.json` state in
+#   ~/.claude/, because the spawn loader reads from the cross-product
+#   path as a separate surface.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# WHY THIS MATTERS:
+#   Issue #58806 documented a case where a user disabled a plugin
+#   ("nimble") via every config knob Claude Code exposes — disabling
+#   it in settings, removing it from installed_plugins.json, adding it
+#   to blocklist.json, removing its cache directory — and the plugin
+#   kept spawning its MCP server (and opening OAuth tabs in the
+#   browser) on every session start.
+#
+#   Root cause: Claude Desktop's RPM plugin install path
+#     ~/Library/Application Support/Claude/local-agent-mode-sessions/
+#       <session-uuid-1>/<session-uuid-2>/rpm/plugin_<ULID>/.mcp.json
+#   is read by Claude Code as a separate spawn surface, and none of
+#   the ~/.claude/ config knobs gate that read. The user only found
+#   the path after three sessions of manual investigation.
+#
+#   This is a structurally different problem from a single-loader
+#   gate bug: it is a cross-product state leakage where one product's
+#   state files affect another product's runtime spawn decisions. The
+#   underlying fix has to come from Anthropic (unify plugin state, or
+#   make `claude-code mcp list` reflect the full source-path set).
+#   Until then, the operator-side mitigation is to detect the
+#   presence of blocklisted plugin spawn configs before the session
+#   starts using them.
+#
+#   This hook does that detection. A one-shot `find … rm` is
+#   point-in-time and gets defeated the next time Claude Desktop
+#   recreates the session directory under a fresh UUID. Running the
+#   same scan at every Claude Code SessionStart closes the recurrence
+#   window.
+#
+# WHAT IT CHECKS:
+#   For each path in the candidate cross-product roots
+#   (macOS / Linux / Windows-via-WSL), if the path exists, finds all
+#   .mcp.json files and greps for any plugin name in the user's
+#   blocklist (configured via CC_CROSS_PRODUCT_BLOCKLIST, comma- or
+#   newline-separated). Reports every match.
+#
+# OUTPUT:
+#   For each match: the blocked plugin name and the .mcp.json path
+#   that will spawn it. Exits 0 by default (advisory). If
+#   CC_CROSS_PRODUCT_REQUIRE_CLEAN=1 is set, exits 2 to block the
+#   session until the operator removes the stale spawn config.
+#
+# CONFIGURATION:
+#   CC_CROSS_PRODUCT_BLOCKLIST
+#     Comma- or newline-separated plugin name fragments to match
+#     against .mcp.json contents. Empty (the default) means the hook
+#     skips entirely — opt-in only, so installations without a
+#     blocklist incur no startup cost or false positives.
+#     Example: CC_CROSS_PRODUCT_BLOCKLIST="nimble,wix,serena"
+#
+#   CC_CROSS_PRODUCT_REQUIRE_CLEAN
+#     Set to "1" to exit 2 (block) when any match is found. Default
+#     is exit 0 (advisory).
+#
+#   CC_CROSS_PRODUCT_EXTRA_ROOTS
+#     Newline-separated extra paths to scan in addition to the
+#     built-in macOS / Linux / WSL candidates. Useful for non-default
+#     install locations.
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/58806
+#   https://github.com/anthropics/claude-code/issues/58520
+# ================================================================
+
+set -u
+
+BLOCKLIST_RAW="${CC_CROSS_PRODUCT_BLOCKLIST:-}"
+if [ -z "$BLOCKLIST_RAW" ]; then
+    # Opt-in: no blocklist configured, skip silently.
+    exit 0
+fi
+
+# Normalize blocklist: replace commas and whitespace runs with newlines, drop empties.
+BLOCKLIST=$(printf '%s' "$BLOCKLIST_RAW" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | grep -v '^$' || true)
+if [ -z "$BLOCKLIST" ]; then
+    exit 0
+fi
+
+# Build candidate cross-product roots.
+CANDIDATE_ROOTS=""
+add_root() {
+    [ -n "$1" ] || return 0
+    CANDIDATE_ROOTS="${CANDIDATE_ROOTS}${1}
+"
+}
+
+# macOS: Claude Desktop application-support tree.
+add_root "$HOME/Library/Application Support/Claude/local-agent-mode-sessions"
+add_root "$HOME/Library/Application Support/Claude/plugins"
+
+# Linux: XDG config / data trees.
+add_root "${XDG_CONFIG_HOME:-$HOME/.config}/Claude/local-agent-mode-sessions"
+add_root "${XDG_CONFIG_HOME:-$HOME/.config}/Claude/plugins"
+add_root "${XDG_DATA_HOME:-$HOME/.local/share}/Claude/local-agent-mode-sessions"
+add_root "${XDG_DATA_HOME:-$HOME/.local/share}/Claude/plugins"
+
+# Windows via WSL: APPDATA / LOCALAPPDATA exposed through /mnt/c.
+if [ -n "${APPDATA:-}" ]; then
+    add_root "$APPDATA/Claude/local-agent-mode-sessions"
+    add_root "$APPDATA/Claude/plugins"
+fi
+if [ -n "${LOCALAPPDATA:-}" ]; then
+    add_root "$LOCALAPPDATA/Claude/local-agent-mode-sessions"
+    add_root "$LOCALAPPDATA/Claude/plugins"
+fi
+
+# Operator-specified extras.
+if [ -n "${CC_CROSS_PRODUCT_EXTRA_ROOTS:-}" ]; then
+    while IFS= read -r extra; do
+        add_root "$extra"
+    done <<EOF
+${CC_CROSS_PRODUCT_EXTRA_ROOTS}
+EOF
+fi
+
+# Scan each existing root for .mcp.json files containing any blocked name.
+MATCHES=""
+while IFS= read -r root; do
+    [ -n "$root" ] || continue
+    [ -d "$root" ] || continue
+
+    # Iterate every .mcp.json under this root.
+    while IFS= read -r -d '' mcpfile; do
+        # Iterate every blocked name.
+        while IFS= read -r name; do
+            [ -n "$name" ] || continue
+            if grep -qF -- "$name" "$mcpfile" 2>/dev/null; then
+                MATCHES="${MATCHES}  - blocked plugin '${name}' is spawnable from: ${mcpfile}
+"
+            fi
+        done <<EOF
+${BLOCKLIST}
+EOF
+    done < <(find "$root" -type f -name '.mcp.json' -print0 2>/dev/null)
+done <<EOF
+${CANDIDATE_ROOTS}
+EOF
+
+if [ -n "$MATCHES" ]; then
+    printf '⚠️  Cross-product MCP spawn config detected (Issue #58806):\n' >&2
+    printf '%s' "$MATCHES" >&2
+    printf '\n  These files live outside ~/.claude/ and are read by Claude Code as a\n' >&2
+    printf '  separate spawn surface. Disabling the plugin via enabledPlugins / blocklist /\n' >&2
+    printf '  installed_plugins.json in ~/.claude/ will NOT prevent the next session from\n' >&2
+    printf '  spawning the MCP server from the path above.\n' >&2
+    printf '\n  Mitigations:\n' >&2
+    printf '    1. Remove the .mcp.json (or the enclosing plugin_ directory) listed above.\n' >&2
+    printf '    2. Set MCP_REMOTE_NO_OPEN=1 in this shell to neutralize browser-open behavior\n' >&2
+    printf '       if removal is not yet possible.\n' >&2
+    printf '    3. Add a PreToolUse hook matching mcp__<plugin-prefix>* to refuse calls.\n' >&2
+    printf '\n  Reference: https://github.com/anthropics/claude-code/issues/58806\n' >&2
+
+    if [ "${CC_CROSS_PRODUCT_REQUIRE_CLEAN:-0}" = "1" ]; then
+        exit 2
+    fi
+fi
+
+exit 0

package/examples/daemon-zombie-worker-surfacer.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# ================================================================
+# daemon-zombie-worker-surfacer.sh — Surface orphaned / zombie
+# background workers at session start via `claude daemon status`.
+# ================================================================
+# PURPOSE:
+#   Detect background workers that are still registered (and may still
+#   be consuming tokens) from PRIOR sessions, and surface them at the
+#   start of a new session — when the operator can actually act.
+#
+# WHY THIS MATTERS:
+#   Background subagents/workers can keep running after the operator
+#   stops them. The "Background tasks" panel showing "Stopped" is not
+#   always terminal, and the zombie state is INVISIBLE unless you run
+#   `claude daemon status`. Real reports:
+#     #66339 — two background subagents resurrected after being stopped
+#              multiple times, ran 21+ hours, consumed ~160k tokens,
+#              burned a 4-hour usage limit and triggered overage charges;
+#              deleting the PARENT session was the only thing that stopped
+#              them.
+#     #66358 — after an auto-update the daemon orphaned the prior version's
+#              workers (control-key version skew): alive but unreachable.
+#   The harness fix is provider-side. This hook is the operator-side
+#   detector: it runs `claude daemon status` at session start and, if any
+#   workers are still registered or a version skew is present, surfaces an
+#   advisory so the operator can inspect (`claude agents --json`) or restart.
+#
+# TRIGGER: SessionStart
+# MATCHER: "" (SessionStart has no matcher)
+# DECISION CONTROL: none — advisory only, non-blocking, fail-open.
+#
+# CONFIGURATION (environment variables):
+#   CC_DAEMON_SURFACER_DISABLE   set "1" to disable the hook entirely
+#   CC_DAEMON_STATUS_TIMEOUT     seconds to wait for `claude daemon status`
+#                                (default 8)
+#   CC_DAEMON_STATUS_CMD         override the status command (used by tests
+#                                to inject canned output)
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "SessionStart": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/daemon-zombie-worker-surfacer.sh"
+#         }]
+#       }]
+#     }
+#   }
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/66339
+#   https://github.com/anthropics/claude-code/issues/66358
+# ================================================================
+
+set -uo pipefail
+
+[ "${CC_DAEMON_SURFACER_DISABLE:-0}" = "1" ] && exit 0
+
+TIMEOUT="${CC_DAEMON_STATUS_TIMEOUT:-8}"
+
+# Obtain the daemon status text. Tests inject canned output via
+# CC_DAEMON_STATUS_CMD; otherwise call the real CLI (fail-open if absent).
+if [ -n "${CC_DAEMON_STATUS_CMD:-}" ]; then
+    STATUS=$(eval "$CC_DAEMON_STATUS_CMD" 2>/dev/null)
+else
+    command -v claude >/dev/null 2>&1 || exit 0
+    STATUS=$(timeout "$TIMEOUT" claude daemon status 2>/dev/null)
+fi
+
+# Empty output (timeout, error, no such subcommand) → fail-open silently.
+[ -z "$STATUS" ] && exit 0
+
+# Background-worker count. The status prints a line such as:
+#   bg workers:   8 running (control.sock), 8 in roster.json
+#   bg workers:   0 in roster.json (control unreachable)
+# Take the largest integer on the "bg workers:" line as the count.
+WORKER_LINE=$(printf '%s\n' "$STATUS" | grep -iE 'bg workers:' | head -1)
+WORKERS=$(printf '%s' "$WORKER_LINE" | grep -oE '[0-9]+' | sort -nr | head -1)
+WORKERS="${WORKERS:-0}"
+
+# Version skew = workers orphaned by an auto-update, locked to an old
+# control key (e.g. "5 from a different CLI version").
+SKEW_LINE=$(printf '%s\n' "$STATUS" | grep -iE 'from a different (CLI )?version' | head -1)
+SKEW=$(printf '%s' "$SKEW_LINE" | grep -oE '[0-9]+' | head -1)
+SKEW="${SKEW:-0}"
+
+# Healthy / common case: nothing registered, no skew → silent no-op.
+if [ "$WORKERS" -eq 0 ] && [ "$SKEW" -eq 0 ]; then
+    exit 0
+fi
+
+DETAIL=""
+[ "$WORKERS" -gt 0 ] && DETAIL="${DETAIL}  - ${WORKERS} background worker(s) still registered (from a prior session).\n"
+[ "$SKEW" -gt 0 ] && DETAIL="${DETAIL}  - ${SKEW} of them are from a different CLI version — orphaned by an auto-update, alive but unreachable.\n"
+
+cat >&2 <<EOF
+<system-reminder>
+BACKGROUND WORKER CHECK — possible zombie / orphaned background work detected.
+
+$(printf '%b' "$DETAIL")
+Background workers can keep running (and consuming tokens) after you stop them
+— the "Background tasks" panel showing "Stopped" is not always terminal
+(#66339: ~160k tokens burned over 21h after repeated stops; #66358: auto-update
+orphans). If you did NOT intend these to be running:
+
+  1. Inspect them:        claude agents --json
+  2. The stop that worked in #66339 was deleting the PARENT session — the
+     panel "Stop" alone did not stop them.
+  3. Orphans from a version skew (#66358) cannot be re-attached; restart the
+     daemon / Claude Code fully to clear them.
+
+Advisory only — nothing is blocked. Set CC_DAEMON_SURFACER_DISABLE=1 to silence.
+</system-reminder>
+EOF
+
+exit 0

package/examples/daily-cost-guard.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# ================================================================
+# daily-cost-guard.sh — Track per-day API-equivalent token cost
+#                      and warn / block when the daily budget is
+#                      exceeded
+# ================================================================
+# PURPOSE:
+#   Anthropic's billing dashboard reflects with a multi-day delay,
+#   so it cannot serve as a real-time spend guard. This hook reads
+#   the actual usage data from the transcript file on every Stop
+#   event, accumulates an API-equivalent cost estimate per day, and
+#   warns at a soft threshold or signals when the daily budget is
+#   exceeded.
+#
+#   Solves the May 2026 r/ClaudeAI report (735 points): an operator
+#   left a 30-minute polling loop running overnight and woke up to
+#   approximately $6,000 in cost because each polling iteration
+#   re-sent an 800K-token conversation history without cache benefit
+#   (loop interval > 5-minute cache TTL).
+#
+# TRIGGER: Stop
+# MATCHER: ""
+#
+# WHY THIS MATTERS:
+#   The hook runs once per turn at conversation end (zero per-turn
+#   latency). It reads the transcript file to find the most recent
+#   message.usage block, computes API-equivalent cost using
+#   Sonnet 4.6 pricing, and writes a daily JSONL log. The daily
+#   total accumulates across multiple sessions on the same date.
+#
+#   Subscription-plan users are not billed by API rate; the cost
+#   estimate is a proxy for actual token consumption. Use it to
+#   detect anomalous spend before the dashboard catches up.
+#
+# WHAT IT CHECKS:
+#   1. Reads transcript_path from Stop hook input
+#   2. Extracts the most recent message.usage block (input, output,
+#      cache_read, cache_creation)
+#   3. Computes Sonnet 4.6 API-equivalent cost for that turn
+#   4. Appends the turn cost to today's JSONL log
+#   5. Sums today's log to get the daily total
+#   6. Warns at soft threshold, signals at daily limit
+#
+# OUTPUT:
+#   Soft warning (exit 0) at WARN_THRESHOLD_USD.
+#   Daily-limit-exceeded signal (exit 0 by default, exit 2 with
+#   CC_DAILY_COST_BLOCK=1) at DAILY_LIMIT_USD.
+#
+# CONFIGURATION:
+#   CC_DAILY_LIMIT_USD       — daily budget cap (default $5.00)
+#   CC_DAILY_WARN_USD        — soft warning threshold (default $3.50)
+#   CC_DAILY_COST_BLOCK      — set to "1" to exit 2 (signal context)
+#                              when daily limit is exceeded; default
+#                              is advisory (exit 0)
+#   CC_DAILY_COST_LOG_DIR    — log directory (default
+#                              ~/.claude/cost-log)
+#   CC_DAILY_COST_MODEL      — pricing model (default "sonnet"; set
+#                              to "opus" to use Opus 4.7 rates 5x
+#                              higher)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/47049
+#   r/ClaudeAI 2026-05-01 "$6000 overnight" report
+# ================================================================
+
+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-daily-cost-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [daily-cost-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+DAILY_LIMIT_USD="${CC_DAILY_LIMIT_USD:-5.00}"
+WARN_THRESHOLD_USD="${CC_DAILY_WARN_USD:-3.50}"
+LOG_DIR="${CC_DAILY_COST_LOG_DIR:-${HOME}/.claude/cost-log}"
+MODEL="${CC_DAILY_COST_MODEL:-sonnet}"
+
+# Pricing tables (USD per 1M tokens) as of 2026-05
+case "$MODEL" in
+    opus)
+        # Opus 4.7: input $15 / output $75 / cache write $18.75 / cache read $1.50
+        P_IN=15
+        P_OUT=75
+        P_CW=18.75
+        P_CR=1.50
+        ;;
+    sonnet|*)
+        # Sonnet 4.6: input $3 / output $15 / cache write $3.75 / cache read $0.30
+        P_IN=3
+        P_OUT=15
+        P_CW=3.75
+        P_CR=0.30
+        ;;
+esac
+
+mkdir -p "${LOG_DIR}"
+TODAY=$(date +%Y-%m-%d)
+LOG_FILE="${LOG_DIR}/${TODAY}.jsonl"
+
+INPUT=$(cat)
+
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+    exit 0
+fi
+
+# Extract the most recent message.usage block
+LATEST_USAGE=$(grep -h '"usage"' "$TRANSCRIPT_PATH" 2>/dev/null \
+    | tail -1 \
+    | jq -r '.message.usage // empty' 2>/dev/null || true)
+
+if [ -z "$LATEST_USAGE" ]; then
+    exit 0
+fi
+
+TURN_INPUT=$(printf '%s' "$LATEST_USAGE" | jq -r '.input_tokens // 0' 2>/dev/null || echo 0)
+TURN_OUTPUT=$(printf '%s' "$LATEST_USAGE" | jq -r '.output_tokens // 0' 2>/dev/null || echo 0)
+TURN_CACHE_READ=$(printf '%s' "$LATEST_USAGE" | jq -r '.cache_read_input_tokens // 0' 2>/dev/null || echo 0)
+TURN_CACHE_WRITE=$(printf '%s' "$LATEST_USAGE" | jq -r '.cache_creation_input_tokens // 0' 2>/dev/null || echo 0)
+
+COST_USD=$(awk -v i="$TURN_INPUT" -v o="$TURN_OUTPUT" -v cr="$TURN_CACHE_READ" -v cw="$TURN_CACHE_WRITE" \
+              -v pi="$P_IN" -v po="$P_OUT" -v pcr="$P_CR" -v pcw="$P_CW" '
+BEGIN {
+    printf "%.6f\n", (i * pi + o * po + cw * pcw + cr * pcr) / 1000000
+}')
+
+printf '{"ts":"%s","turn_cost_usd":%s,"input":%s,"output":%s,"cache_read":%s,"cache_write":%s,"model":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$COST_USD" "$TURN_INPUT" "$TURN_OUTPUT" "$TURN_CACHE_READ" "$TURN_CACHE_WRITE" "$MODEL" \
+    >> "$LOG_FILE"
+
+# Sum today's entries to get the daily total
+TODAY_TOTAL=$(awk -F'"turn_cost_usd":' 'NF>1 {split($2, a, ","); sum += a[1]} END {printf "%.4f", sum+0}' "$LOG_FILE")
+
+# Threshold checks
+if awk "BEGIN {exit !($TODAY_TOTAL >= $DAILY_LIMIT_USD)}"; then
+    cat >&2 <<EOF
+🛑 daily-cost-guard: 当日累計が想定上限を超えました
+  当日累計: \$${TODAY_TOTAL}
+  想定上限: \$${DAILY_LIMIT_USD}
+  ログ: ${LOG_FILE}
+  原因の確認まで作業を止めることをお勧めします。
+  Reference: https://github.com/anthropics/claude-code/issues/47049
+EOF
+    if [ "${CC_DAILY_COST_BLOCK:-0}" = "1" ]; then
+        exit 2
+    fi
+elif awk "BEGIN {exit !($TODAY_TOTAL >= $WARN_THRESHOLD_USD)}"; then
+    cat >&2 <<EOF
+⚠ daily-cost-guard: 当日累計が警告閾値に達しました
+  当日累計: \$${TODAY_TOTAL}
+  警告閾値: \$${WARN_THRESHOLD_USD}
+  想定上限: \$${DAILY_LIMIT_USD}
+EOF
+fi
+
+exit 0

package/examples/dangerous-pip-flag-guard.sh

@@ -19,6 +19,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-dangerous-pip-flag-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [dangerous-pip-flag-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/db-connect-guard.sh

@@ -24,7 +24,19 @@
 #   psql (local connection)
 #   prisma generate (code generation, not DB change)
 #
-# 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-db-connect-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [db-connect-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/denied-action-retry-guard.sh

@@ -13,6 +13,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-denied-action-retry-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [denied-action-retry-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)
 COMMAND=""

package/examples/deny-bypass-detector.sh

@@ -33,6 +33,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-deny-bypass-detector-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [deny-bypass-detector]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 DENY_LOG="/tmp/cc-deny-bypass-log"
 mkdir -p "$(dirname "$DENY_LOG")" 2>/dev/null || true