cc-safe-setup 29.8.0 → 30.0.5

package/examples/home-critical-bash-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-home-critical-bash-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [home-critical-bash-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
@@ -38,7 +50,11 @@ fi
 
 # Check for truncation via redirect (> ~/.bashrc or : > ~/.bashrc)
 if echo "$COMMAND" | grep -qE ">\s*(${HOME_DIR}|\~)/\."; then
-    TARGET=$(echo "$COMMAND" | grep -oP ">\s*\K(${HOME_DIR}|~)/\.[^\s;|&]+")
+    # -P は GNU 拡張。BSD grep では TARGET が空になり、下の「重要な設定ファイルを切り詰める」
+    # 検査だけが静かに消える。\K の代わりに > から一致させて前置きを落とす。
+    TARGET=$(echo "$COMMAND" \
+        | grep -oE ">[[:space:]]*(${HOME_DIR}|~)/\.[^[:space:];|&]+" \
+        | sed -E 's/^>[[:space:]]*//')
     if echo "$TARGET" | grep -qE "$CRITICAL"; then
         echo "BLOCKED: Truncating critical home directory file" >&2
         echo "Command: $COMMAND" >&2

package/examples/hook-debug-wrapper.sh

@@ -26,8 +26,12 @@
 #
 # LOG LOCATION: ~/.claude/hook-debug.log
 #
-# TRIGGER: Any (wraps any hook)
-# MATCHER: Any
+# TRIGGER: none
+# MATCHER: none
+#   This wraps another hook rather than being registered on its own. Register it
+#   under whatever event and matcher that hook already uses. There is no `Any`
+#   event: an unknown key under `hooks` is ignored without a warning, so a hook
+#   registered under one sits in the config looking installed and never runs.
 # ================================================================
 
 HOOK_SCRIPT="$1"

package/examples/hook-self-disable-detector.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# hook-self-disable-detector.sh — Detect when previously-active hooks have been silently removed
+# Trigger: SessionStart
+# Matcher: (empty — runs once at every session start)
+#
+# Background: Claude Code sessions can edit settings.json and remove hooks
+# that were previously active. Over weeks of accumulation this can silently
+# disable safeguards. One documented case: a Claude Code session disabled
+# its own early-detection hook, and 193 GB of WSL bloat accumulated before
+# the operator noticed. See drafts/active/2026-05-16-self-disabled-safeguard-wsl-bloat.md
+# in cc-loop for the source incident.
+#
+# This hook complements settings-integrity-monitor.sh:
+#   settings-integrity-monitor: warns when settings.json checksum changes
+#   hook-self-disable-detector: warns which specific hooks were removed
+#
+# Behavior:
+#   1. On every SessionStart, capture the current set of (event, matcher, command) triples
+#      from ~/.claude/settings.json and .claude/settings.json.
+#   2. Compare against the most recent snapshot in ~/.claude/.hook-state-snapshots/.
+#   3. If a hook present in the previous snapshot is missing from the current state,
+#      print a warning to stderr listing which event/matcher/command was removed.
+#   4. Save the current state as a new snapshot regardless.
+#
+# Environment overrides (mainly for tests):
+#   CC_HOOK_STATE_DIR     — directory for snapshots (default: $HOME/.claude/.hook-state-snapshots)
+#   CC_USER_SETTINGS      — user settings.json path (default: $HOME/.claude/settings.json)
+#   CC_PROJECT_SETTINGS   — project settings.json path (default: .claude/settings.json)
+#   CC_HOOK_DISABLE_QUIET — if "1", suppress the informational first-run message
+
+set -u
+
+STATE_DIR="${CC_HOOK_STATE_DIR:-$HOME/.claude/.hook-state-snapshots}"
+USER_SETTINGS="${CC_USER_SETTINGS:-$HOME/.claude/settings.json}"
+PROJECT_SETTINGS="${CC_PROJECT_SETTINGS:-.claude/settings.json}"
+QUIET="${CC_HOOK_DISABLE_QUIET:-0}"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+
+# Extract the (event, matcher, command) triples from a settings.json file.
+# Each line is "<event>|<matcher>|<command>". Missing fields become empty strings.
+extract_hooks() {
+    local file="$1"
+    [ -f "$file" ] || return 0
+    jq -r '
+        (.hooks // {})
+        | to_entries[]
+        | .key as $event
+        | .value[]?
+        | ($event + "|" + (.matcher // "") + "|" + ((.hooks // [])[]? | (.command // "")))
+    ' "$file" 2>/dev/null
+}
+
+# Build current state: lines prefixed with origin (user/project) for clarity.
+CURRENT=$(
+    {
+        extract_hooks "$USER_SETTINGS" | sed 's/^/user|/'
+        extract_hooks "$PROJECT_SETTINGS" | sed 's/^/project|/'
+    } | sort -u
+)
+
+# Locate the most recent prior snapshot (lexicographic timestamp order) and
+# read its contents BEFORE writing the new snapshot, so the comparison is not
+# polluted by the file we are about to create.
+PREV_SNAPSHOT=$(ls -1 "$STATE_DIR"/snapshot-*.txt 2>/dev/null | sort | tail -n 1)
+PREVIOUS=""
+if [ -n "$PREV_SNAPSHOT" ] && [ -f "$PREV_SNAPSHOT" ]; then
+    PREVIOUS=$(cat "$PREV_SNAPSHOT" 2>/dev/null)
+fi
+
+# Use nanosecond precision so rapid successive invocations get distinct files.
+NEW_SNAPSHOT="$STATE_DIR/snapshot-$(date +%Y%m%d-%H%M%S-%N).txt"
+printf '%s\n' "$CURRENT" > "$NEW_SNAPSHOT"
+
+if [ -z "$PREV_SNAPSHOT" ]; then
+    if [ "$QUIET" != "1" ]; then
+        COUNT=$(printf '%s' "$CURRENT" | grep -c '^' || true)
+        echo "ℹ hook-self-disable-detector: first run, snapshot of $COUNT hook entries saved." >&2
+    fi
+    exit 0
+fi
+
+# Lines that were in the previous snapshot but are missing from the current state.
+REMOVED=$(comm -23 <(printf '%s\n' "$PREVIOUS" | sort -u) <(printf '%s\n' "$CURRENT" | sort -u) | grep -v '^$' || true)
+
+if [ -n "$REMOVED" ]; then
+    REMOVED_COUNT=$(printf '%s\n' "$REMOVED" | grep -c '^' || true)
+    echo "⚠ hook-self-disable-detector: $REMOVED_COUNT hook entries were active in the previous session but are absent now." >&2
+    echo "  This can mask self-disabled safeguards. Review each entry:" >&2
+    printf '%s\n' "$REMOVED" | while IFS='|' read -r origin event matcher command; do
+        # Truncate command to keep the warning readable.
+        short_cmd=$(printf '%s' "$command" | head -c 120)
+        echo "    [$origin] event=$event matcher='$matcher' command='$short_cmd'" >&2
+    done
+    echo "  Previous snapshot: $PREV_SNAPSHOT" >&2
+    echo "  Current snapshot:  $NEW_SNAPSHOT" >&2
+fi
+
+exit 0

package/examples/hook-stdout-sanitizer.sh

@@ -16,8 +16,12 @@
 #
 # Or use as a template for writing safe hooks.
 #
-# TRIGGER: Any (wrapper for other hooks)
-# MATCHER: Any
+# TRIGGER: none
+# MATCHER: none
+#   This wraps another hook rather than being registered on its own. Register it
+#   under whatever event and matcher that hook already uses. There is no `Any`
+#   event: an unknown key under `hooks` is ignored without a warning, so a hook
+#   registered under one sits in the config looking installed and never runs.
 
 TARGET_HOOK="$1"
 shift

package/examples/hook-tamper-guard.sh

@@ -27,6 +27,18 @@
 #   }
 # }
 
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-hook-tamper-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [hook-tamper-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/image-dimension-guard.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# image-dimension-guard.sh — Block Read of oversized images that trigger a costly retry loop
+#
+# Solves: When Claude reads/attaches an image whose dimensions exceed the API
+# limit (2000px per side for many-image requests), the API returns a
+# 400 invalid_request_error. Claude Code silently removes the image and then
+# RETRIES (observed 41x in #65636). Each retry mutates the conversation prefix,
+# which invalidates the prompt cache: cache reads collapse and the whole
+# context is re-written to the cache every turn, inflating session cost ~35x
+# (one such loop was ~66% of a session's total cost).
+#
+# This checks an image's pixel dimensions BEFORE the Read tool sends it and
+# blocks (or warns) when a side exceeds the limit, so the loop never starts.
+# Dimensions are read from the file header with no external dependency
+# (PNG/JPEG/GIF/BMP); it falls back to ImageMagick `identify` for other
+# formats. It FAILS OPEN when dimensions cannot be determined, so it never
+# breaks a normal Read.
+#
+# Complements image-file-validator.sh, which blocks FAKE images (wrong MIME);
+# this one blocks REAL images that are simply too large.
+#
+# TRIGGER: PreToolUse  MATCHER: "Read"
+# Config:
+#   CC_IMAGE_DIM_LIMIT=2000   max px per side (2000 = many-image API limit; raise to 8000 for single-image-only workflows)
+#   CC_IMAGE_DIM_GUARD=block  block | warn | off
+# Related: https://github.com/anthropics/claude-code/issues/65636
+
+INPUT=$(cat)
+
+MODE="${CC_IMAGE_DIM_GUARD:-block}"
+[ "$MODE" = "off" ] && exit 0
+LIMIT="${CC_IMAGE_DIM_LIMIT:-2000}"
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+
+# Only raster formats have a pixel cap that triggers this 400 (skip svg/ico).
+case "${FILE,,}" in
+    *.png|*.jpg|*.jpeg|*.gif|*.bmp|*.webp|*.tiff|*.tif) ;;
+    *) exit 0 ;;
+esac
+
+# Read "W H" from the file header with no hard dependency.
+DIMS=$(python3 - "$FILE" 2>/dev/null <<'PY'
+import sys, struct
+def dims(path):
+    with open(path, 'rb') as f:
+        head = f.read(26)
+        if head[:8] == b'\x89PNG\r\n\x1a\n':
+            w, h = struct.unpack('>II', head[16:24]); return w, h
+        if head[:6] in (b'GIF87a', b'GIF89a'):
+            w, h = struct.unpack('<HH', head[6:10]); return w, h
+        if head[:2] == b'BM':
+            w, h = struct.unpack('<ii', head[18:26]); return abs(w), abs(h)
+        if head[:2] == b'\xff\xd8':  # JPEG: scan SOF markers
+            f.seek(2)
+            while True:
+                b = f.read(1)
+                if not b: break
+                if b != b'\xff': continue
+                marker = f.read(1)
+                while marker == b'\xff': marker = f.read(1)
+                if not marker: break
+                m = marker[0]
+                if m in (0xd8, 0xd9) or 0xd0 <= m <= 0xd7: continue
+                seg = f.read(2)
+                if len(seg) < 2: break
+                length = struct.unpack('>H', seg)[0]
+                if m in (0xc0,0xc1,0xc2,0xc3,0xc5,0xc6,0xc7,0xc9,0xca,0xcb,0xcd,0xce,0xcf):
+                    data = f.read(5)
+                    if len(data) < 5: break
+                    h, w = struct.unpack('>HH', data[1:5]); return w, h
+                f.seek(length - 2, 1)
+    return None
+try:
+    r = dims(sys.argv[1])
+    if r: print(r[0], r[1])
+except Exception:
+    pass
+PY
+)
+
+# Fallback for formats the header parser skips (e.g. WEBP/TIFF).
+if [ -z "$DIMS" ] && command -v identify >/dev/null 2>&1; then
+    DIMS=$(identify -format '%w %h' "$FILE[0]" 2>/dev/null | head -1)
+fi
+
+# Fail open if dimensions are unknown — never break a normal Read.
+[ -z "$DIMS" ] && exit 0
+W=$(printf '%s' "$DIMS" | awk '{print $1}')
+H=$(printf '%s' "$DIMS" | awk '{print $2}')
+case "$W" in ''|*[!0-9]*) exit 0;; esac
+case "$H" in ''|*[!0-9]*) exit 0;; esac
+
+MAX="$W"; [ "$H" -gt "$W" ] && MAX="$H"
+[ "$MAX" -le "$LIMIT" ] && exit 0
+
+BASE="${FILE##*/}"
+MSG="${BASE} is ${W}x${H}px, exceeding the ${LIMIT}px per-side API limit for many-image requests. Sending it returns a 400 error; Claude Code then silently strips the image and retries (observed 41x in #65636), which invalidates the prompt cache and can inflate session cost ~35x. Resize it first, e.g. 'convert ${BASE} -resize ${LIMIT}x${LIMIT} small-${BASE}' (ImageMagick) or 'sips -Z ${LIMIT} ${BASE}' (macOS), then read the smaller copy. Set CC_IMAGE_DIM_LIMIT to change the threshold, CC_IMAGE_DIM_GUARD=warn to only warn, or =off to disable."
+
+if [ "$MODE" = "warn" ]; then
+    echo "image-dimension-guard: $MSG" >&2
+    exit 0
+fi
+
+# block (default): emit a structured block decision (exit 0, like image-file-validator).
+jq -n --arg r "$MSG" '{decision: "block", reason: $r}'
+exit 0

package/examples/iteration-quality-degradation-detector.sh

@@ -0,0 +1,170 @@
+#!/bin/bash
+# iteration-quality-degradation-detector.sh — Warn when the same file is being edited repeatedly across turns
+#
+# Solves: anthropics/claude-code#61989 — Codex (GPT-5.5) reviews Opus 4.7's code,
+#   each fix cycle produces new errors instead of converging. A simple shell script
+#   (193 lines) accumulates errors across review cycles instead of stabilizing.
+#
+# Structural observation: when the model is competent in a single turn but the
+# multi-turn fix loop diverges, the surface marker is *the same file being edited
+# repeatedly within a short window*. The hook does not judge code quality (it
+# can't); it surfaces the iteration pattern so the operator can interrupt before
+# more cycles accumulate.
+#
+# How it works:
+#   PostToolUse hook on Edit/Write/MultiEdit appends a receipt to per-session state.
+#   UserPromptSubmit hook reads recent receipts (default: last 30 minutes), counts
+#   per-file edits, and emits an advisory if any file exceeds the threshold
+#   (default: 3 edits in the window).
+#
+# This is the Cluster-1 hook from the 2026-05-25 customer pain audit
+# (~/ops/customer-pain-audit-2026-05-25-post-launch-cluster.md). Cluster 1 names
+# the iteration-cycle quality degradation pattern that is new in the May 2026
+# issue corpus and not covered by existing cc-safe-setup hooks.
+#
+# TRIGGER: PostToolUse + UserPromptSubmit
+# MATCHER: "Edit|Write|MultiEdit" for PostToolUse, "" for UserPromptSubmit
+#
+# Usage (settings.json):
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "Edit|Write|MultiEdit",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/iteration-quality-degradation-detector.sh" }]
+#     }],
+#     "UserPromptSubmit": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/iteration-quality-degradation-detector.sh" }]
+#     }]
+#   }
+# }
+#
+# Configuration:
+#   CC_ITERATION_DETECTOR_DISABLE=1 — skip entirely
+#   CC_ITERATION_DETECTOR_THRESHOLD=3 — edits per file before advisory fires (default 3)
+#   CC_ITERATION_DETECTOR_WINDOW_SEC=1800 — time window in seconds (default 30 min)
+#   CC_ITERATION_DETECTOR_STATE_DIR=~/.claude/state/iteration-degradation
+#   CC_ITERATION_DETECTOR_MODE=strict — exit 2 on UserPromptSubmit (default advisory exits 0)
+
+# Read stdin first to avoid EPIPE on disable
+# 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-iteration-quality-degradation-detector-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [iteration-quality-degradation-detector]: 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)
+
+[ "${CC_ITERATION_DETECTOR_DISABLE:-0}" = "1" ] && exit 0
+[ -z "$INPUT" ] && exit 0
+
+THRESHOLD="${CC_ITERATION_DETECTOR_THRESHOLD:-3}"
+WINDOW_SEC="${CC_ITERATION_DETECTOR_WINDOW_SEC:-1800}"
+STATE_DIR_BASE="${CC_ITERATION_DETECTOR_STATE_DIR:-$HOME/.claude/state/iteration-degradation}"
+
+# Determine event
+EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // empty' 2>/dev/null)
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+HAS_TOOL_RESPONSE=$(printf '%s' "$INPUT" | jq -r 'has("tool_response")' 2>/dev/null)
+HAS_PROMPT=$(printf '%s' "$INPUT" | jq -r 'has("prompt") or has("user_prompt") or has("submitted_prompt")' 2>/dev/null)
+
+if [ -z "$EVENT" ]; then
+    if [ "$HAS_TOOL_RESPONSE" = "true" ]; then
+        EVENT="PostToolUse"
+    elif [ "$HAS_PROMPT" = "true" ]; then
+        EVENT="UserPromptSubmit"
+    else
+        exit 0
+    fi
+fi
+
+# Sanitize session ID for filesystem use
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // .session // "default"' 2>/dev/null)
+[ -z "$SESSION_ID" ] && SESSION_ID="default"
+SESSION_ID=$(printf '%s' "$SESSION_ID" | tr -c 'A-Za-z0-9_-' '_' | head -c 64)
+
+SESSION_DIR="$STATE_DIR_BASE/$SESSION_ID"
+mkdir -p "$SESSION_DIR" 2>/dev/null || true
+LOG_FILE="$SESSION_DIR/edits.log"
+
+if [ "$EVENT" = "PostToolUse" ]; then
+    # Only track Edit/Write/MultiEdit
+    case "$TOOL_NAME" in
+        Edit|Write|MultiEdit) ;;
+        *) exit 0 ;;
+    esac
+
+    FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+    [ -z "$FILE_PATH" ] && exit 0
+
+    TS=$(date +%s)
+    # Append: timestamp<TAB>file_path (file_path may contain spaces but no tabs typically)
+    printf '%s\t%s\n' "$TS" "$FILE_PATH" >> "$LOG_FILE" 2>/dev/null
+
+    # Prune old entries to keep the log bounded (older than 24 hours)
+    if [ -f "$LOG_FILE" ]; then
+        CUTOFF=$((TS - 86400))
+        awk -F'\t' -v cut="$CUTOFF" '$1 >= cut { print }' "$LOG_FILE" > "$LOG_FILE.tmp" 2>/dev/null && mv "$LOG_FILE.tmp" "$LOG_FILE" 2>/dev/null
+    fi
+    exit 0
+fi
+
+if [ "$EVENT" = "UserPromptSubmit" ]; then
+    [ ! -f "$LOG_FILE" ] && exit 0
+
+    NOW=$(date +%s)
+    CUTOFF=$((NOW - WINDOW_SEC))
+
+    # Count edits per file within the window
+    HOT_FILES=$(awk -F'\t' -v cut="$CUTOFF" -v thr="$THRESHOLD" '
+        $1 >= cut { count[$2]++ }
+        END {
+            for (f in count) {
+                if (count[f] >= thr) {
+                    printf "%d\t%s\n", count[f], f
+                }
+            }
+        }
+    ' "$LOG_FILE" 2>/dev/null | sort -rn | head -5)
+
+    [ -z "$HOT_FILES" ] && exit 0
+
+    # Format minutes for human readability
+    HUMAN_WINDOW=$((WINDOW_SEC / 60))
+
+    cat >&2 <<EOF
+<system-reminder>
+iteration-quality-degradation-detector observed repeated edits to the same file(s) within the last ${HUMAN_WINDOW} minutes.
+
+Files at or above the threshold (${THRESHOLD} edits):
+$(printf '%s' "$HOT_FILES" | awk -F'\t' '{ printf "  %s edits: %s\n", $1, $2 }')
+
+This pattern matches the iteration-cycle quality degradation reported in
+anthropics/claude-code#61989: each fix cycle produces new errors instead of
+converging. If you are in a multi-turn fix loop with a cross-model reviewer
+(Codex reviewing Opus, or similar), consider interrupting:
+
+  - Stop, read the full file once, and ask "what is the root cause?"
+  - Revert to a known-good commit and re-approach with a single-pass strategy
+  - Switch reviewer model (different model may have different blind spots)
+  - Clear the iteration counter: rm -f ${LOG_FILE}
+
+Configuration: CC_ITERATION_DETECTOR_THRESHOLD=N (default 3),
+CC_ITERATION_DETECTOR_WINDOW_SEC=N (default 1800).
+</system-reminder>
+EOF
+
+    # Strict mode blocks; default advisory exits 0
+    if [ "${CC_ITERATION_DETECTOR_MODE:-advisory}" = "strict" ]; then
+        exit 2
+    fi
+    exit 0
+fi
+
+exit 0

package/examples/java-compile-on-edit.sh

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

package/examples/k8s-production-guard.sh

@@ -12,10 +12,22 @@
 #   CC_K8S_PROD_NAMESPACES="production:prod:default" (colon-separated)
 #
 # 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-k8s-production-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [k8s-production-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/kill-process-guard.sh

@@ -18,6 +18,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-kill-process-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [kill-process-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/kubernetes-guard.sh

@@ -1,6 +1,18 @@
 #!/bin/bash
 # kubernetes-guard.sh — Block destructive kubectl commands
-# 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-kubernetes-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [kubernetes-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
 if echo "$COMMAND" | grep -qE '\bkubectl\s+delete\s+(namespace|ns|node)\b'; then

package/examples/laravel-artisan-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-laravel-artisan-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [laravel-artisan-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/large-file-guard.sh

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

package/examples/log-truncation-guard.sh

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