cc-safe-setup 29.7.0 → 30.0.4

package/examples/multiline-command-approver.sh

@@ -1,14 +1,9 @@
 #!/bin/bash
-# multiline-command-approver.sh — Auto-approve multiline commands by first-line matching
+# multiline-command-approver.sh — Auto-approve multiline commands safely
 #
 # Solves: Auto-approve patterns fail on heredocs and multiline commands
 #         (#11932 — 47 reactions, 29 comments)
 #
-# How it works:
-#   1. Extracts the first line of the command
-#   2. Matches against a whitelist of safe command prefixes
-#   3. If the first line is a safe command, auto-approves the entire command
-#
 # This is needed because Claude Code's built-in pattern matching
 # evaluates the entire multiline string, which breaks on heredocs:
 #   echo 'commit message\n\nCo-Authored-By: ...' > file
@@ -26,15 +21,47 @@
 #     }]
 #   }
 # }
+#
+# Rewritten 2026-08-03. The old version took `head -1` of the command and
+# approved the whole thing when that one line matched a safe prefix. It had two
+# holes, and the second one was the hook's own subject matter:
+#
+#   separators : over the 32 commands it approved bare, appending
+#                `&& sudo rm -rf /var/app`, `; curl http://… | sh` or
+#                `&& git push --force` kept the approval 288/288 times.
+#   newlines   : `cat <<'EOF' > note.txt` on line 1 with a destructive command
+#                on line 2 kept the approval 18/18 times. A hook whose entire
+#                purpose is multiline input was reading one line of it.
+#
+# The control says which repair this needs: the same dangerous commands on
+# their own were approved 0/5 and 0/3 times. It never approved anything — it
+# just never looked past the first line's first command.
+#
+# Reading further is not as simple as splitting on separators here, because the
+# forms this hook exists to rescue put separators and newlines *inside* data:
+# a commit message spanning lines, a heredoc body. So the command is scanned
+# with the quoting state carried across lines, and heredoc bodies are skipped
+# between their opener and their terminator. What is left is the actual command
+# positions, and every one of them has to match a safe prefix.
+#
+# A line that does not qualify gets no decision, which leaves it to the normal
+# permission flow. This hook only ever adds approval; it never blocks.
+#
+# Known limits:
+#   - Command substitution and backticks are refused outright. Their contents
+#     cannot be judged by reading the string.
+#   - Some prefixes below hand execution to an interpreter (`python3 -c`,
+#     `node -e`, `npx`, `curl -s`). Those are a separate problem from the one
+#     fixed here — the granularity of the safe list, not where it looks — and
+#     are measured separately.
+#   - More than one heredoc opened on the same line is refused rather than
+#     guessed at.
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 
-# Extract first line only (handles heredocs, multiline strings)
-FIRST_LINE=$(echo "$COMMAND" | head -1 | sed 's/^[[:space:]]*//')
-
-# Safe command prefixes (first line only)
+# Safe command prefixes. Each command position must match one of these.
 SAFE_PREFIXES=(
     "echo "
     "printf "
@@ -71,19 +98,130 @@ SAFE_PREFIXES=(
     "curl -s"
 )
 
-for prefix in "${SAFE_PREFIXES[@]}"; do
-    if [[ "$FIRST_LINE" == "$prefix"* ]]; then
-        # Auto-approve: first line matches a safe prefix
-        jq -n '{
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "allow",
-                "permissionDecisionReason": "multiline-command-approver: first line matches safe prefix"
-            }
-        }'
-        exit 0
-    fi
+POSITIONS=()
+
+cc_flush() {
+    local t="$1"
+    t="${t#"${t%%[![:space:]]*}"}"
+    t="${t%"${t##*[![:space:]]}"}"
+    [ -z "$t" ] && return 0
+    case "$t" in '#'*) return 0 ;; esac   # a comment is not a command position
+    POSITIONS+=("$t")
+}
+
+# Split the command into command positions, carrying quoting state across lines
+# and skipping heredoc bodies. Returns 1 for anything it will not vouch for.
+cc_scan() {
+    local sq=0 dq=0 seg="" hd_active=0 hd_delim="" hd_dash=0
+    local line i n c nx j d q ch pending_delim="" pending_dash=0 pending_count=0
+
+    while IFS= read -r line; do
+        if [ "$hd_active" -eq 1 ]; then
+            local cand="$line"
+            [ "$hd_dash" -eq 1 ] && cand="${cand#"${cand%%[![:space:]]*}"}"
+            [ "$cand" = "$hd_delim" ] && hd_active=0
+            continue
+        fi
+
+        pending_delim=""; pending_count=0
+        i=0; n=${#line}
+        while [ "$i" -lt "$n" ]; do
+            c="${line:i:1}"
+
+            if [ "$sq" -eq 1 ]; then
+                [ "$c" = "'" ] && sq=0
+                seg+="$c"; i=$((i + 1)); continue
+            fi
+            if [ "$dq" -eq 1 ]; then
+                if [ "$c" = '\' ]; then seg+="${line:i:2}"; i=$((i + 2)); continue; fi
+                [ "$c" = '"' ] && dq=0
+                seg+="$c"; i=$((i + 1)); continue
+            fi
+
+            case "$c" in
+                "'") sq=1; seg+="$c"; i=$((i + 1)) ;;
+                '"') dq=1; seg+="$c"; i=$((i + 1)) ;;
+                '\') seg+="${line:i:2}"; i=$((i + 2)) ;;
+                '`') return 1 ;;
+                '$')
+                    [ "${line:i+1:1}" = "(" ] && return 1
+                    seg+="$c"; i=$((i + 1)) ;;
+                ';'|'&'|'|')
+                    cc_flush "$seg"; seg=""; i=$((i + 1)) ;;
+                '#')
+                    # `#` opens a comment only at the start of a word
+                    if [ -z "${seg//[[:space:]]/}" ] || [ "${line:i-1:1}" = " " ] || [ "${line:i-1:1}" = $'\t' ]; then
+                        i="$n"
+                    else
+                        seg+="$c"; i=$((i + 1))
+                    fi ;;
+                '<')
+                    if [ "${line:i+1:1}" = "<" ]; then
+                        j=$((i + 2)); d=""; q=""
+                        if [ "${line:j:1}" = "-" ]; then pending_dash=1; j=$((j + 1)); else pending_dash=0; fi
+                        while [ "${line:j:1}" = " " ] || [ "${line:j:1}" = $'\t' ]; do j=$((j + 1)); done
+                        ch="${line:j:1}"
+                        if [ "$ch" = "'" ] || [ "$ch" = '"' ]; then q="$ch"; j=$((j + 1)); fi
+                        while [ "$j" -lt "$n" ]; do
+                            ch="${line:j:1}"
+                            if [ -n "$q" ]; then
+                                if [ "$ch" = "$q" ]; then j=$((j + 1)); break; fi
+                            else
+                                case "$ch" in ' '|$'\t'|';'|'&'|'|'|'>'|'<') break ;; esac
+                            fi
+                            d+="$ch"; j=$((j + 1))
+                        done
+                        [ -z "$d" ] && return 1
+                        pending_count=$((pending_count + 1))
+                        [ "$pending_count" -gt 1 ] && return 1
+                        pending_delim="$d"
+                        seg+="<<"; i="$j"
+                    else
+                        seg+="$c"; i=$((i + 1))
+                    fi ;;
+                *) seg+="$c"; i=$((i + 1)) ;;
+            esac
+        done
+
+        if [ "$sq" -eq 1 ] || [ "$dq" -eq 1 ]; then
+            # the newline is part of the string, not the end of a command
+            seg+=$'\n'
+        else
+            cc_flush "$seg"; seg=""
+            if [ -n "$pending_delim" ]; then
+                hd_delim="$pending_delim"; hd_dash="$pending_dash"; hd_active=1
+            fi
+        fi
+    done <<EOF
+$COMMAND
+EOF
+
+    # an unterminated quote means the string was not what it looked like
+    { [ "$sq" -eq 1 ] || [ "$dq" -eq 1 ]; } && return 1
+    # an unterminated heredoc swallows the rest of the input as body. bash does
+    # treat it as data, so approving would not actually be wrong — but that
+    # rests on a subtlety, and refusing costs nothing.
+    [ "$hd_active" -eq 1 ] && return 1
+    cc_flush "$seg"
+    return 0
+}
+
+cc_scan || exit 0
+[ "${#POSITIONS[@]}" -eq 0 ] && exit 0
+
+for seg in "${POSITIONS[@]}"; do
+    matched=0
+    for prefix in "${SAFE_PREFIXES[@]}"; do
+        if [[ "$seg" == "$prefix"* ]]; then matched=1; break; fi
+    done
+    [ "$matched" -eq 1 ] || exit 0
 done
 
-# No match — pass through (no opinion)
+jq -n '{
+    "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "allow",
+        "permissionDecisionReason": "multiline-command-approver: every command position matches a safe prefix"
+    }
+}'
 exit 0

package/examples/nested-background-agent-guard.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# nested-background-agent-guard.sh — Refuse background agent spawns from inside a sub-agent
+#
+# Why: Issue #73829 (2026-07-04, desktop app, 0 comments when filed) is the canonical
+#      report. An intermediate background agent spawned *further* background agents
+#      instead of doing the sub-topics inline. A grandchild then re-invoked itself with
+#      filler no-ops ("checked current time", "Monitor timed out", "no-op while waiting")
+#      for 6.5 hours instead of quiescing. Once the intermediate agent's session ended,
+#      the top-level session had no handle on its descendants: TaskStop/TaskOutput
+#      returned "No task found" while the panel still showed them running. Several
+#      hundred USD burned, and restarting the app was the only way to clear it.
+#
+#      The recursion only compounds because a *sub*-agent is allowed to spawn
+#      *background* agents at all. That is the one layer a client-side hook can gate
+#      deterministically, so that is what this hook does.
+#
+# ★2026-08-01: this got worse by default. Claude Code 2.1.219 changed nested subagent
+#      spawning from depth 1 to **depth 3 by default**:
+#
+#        "Subagents can now spawn nested subagents up to depth 3 by default (was 1);
+#         set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to disable nesting"
+#
+#      Two consequences for anyone running unattended:
+#        - The blast radius of the #73829 shape tripled without anyone changing a setting.
+#        - Guards that cap the *number* of concurrent subagents do not see this at all.
+#          If each level spawns only a few, the count stays under the threshold while the
+#          depth keeps growing. Depth and width are different axes; this hook is the depth one.
+#
+# Why existing cc-safe-setup hooks miss this exact shape:
+#   - nested-spawn-inflight-guard.sh / max-subagent-count.sh / subagent-budget-guard.sh
+#     all bound how many subagents are in flight. None of them read whether the *current*
+#     run is itself a sub-agent, so none of them can tell depth 1 from depth 3.
+#   - background-cost-launch-guard.sh reads the Bash tool's run_in_background parameter.
+#     It never sees Agent/Task dispatches.
+#
+# What this does: on PreToolUse for Agent/Task/SendMessage, if run_in_background is true
+# AND the current session is already a sub-agent (CLAUDE_CODE_CHILD_SESSION is set),
+# it BLOCKS (exit 2). Foreground agents inside a sub-agent pass. Background agents from
+# the top-level session pass. Only the nesting case is refused.
+#
+# Verified on 2026-07-04 against three inputs, and re-verified 2026-08-01 with the
+# regression tests in tests/:
+#   (a) run_in_background:true + CLAUDE_CODE_CHILD_SESSION set  -> exit 2 (blocked)
+#   (b) run_in_background:true + variable unset (top level)     -> exit 0 (allowed)
+#   (c) foreground agent inside a sub-agent                     -> exit 0 (allowed)
+#
+# ★Limitation, stated plainly: CLAUDE_CODE_CHILD_SESSION is set inside spawned agent
+# sessions on the CLI (confirmed while examining transcript inheritance in #73848).
+# The desktop app was NOT confirmed to set it identically. Verify on your build first
+# with a trivial printenv hook before relying on this.
+#
+# ★This does not recover already-orphaned tasks. They are app-managed tasks, not OS
+# processes you can kill, and the spawning session is gone. The real fixes are
+# provider-side: descendants should stay inspectable/stoppable from the root, and an
+# agent awaiting children should quiesce rather than emit filler tool calls.
+#
+# Opt out:   CC_NESTED_BG_AGENT_GUARD_DISABLE=1
+#
+# TRIGGER: PreToolUse   MATCHER: "Agent|Task|SendMessage"
+# settings.json:
+# { "hooks": { "PreToolUse": [{ "matcher": "Agent|Task|SendMessage",
+#   "hooks": [{ "type": "command",
+#     "command": "~/.claude/hooks/nested-background-agent-guard.sh" }] }] } }
+
+set -uo pipefail
+
+[ "${CC_NESTED_BG_AGENT_GUARD_DISABLE:-0}" = "1" ] && exit 0
+
+INPUT="$(cat)"
+
+# jq が無い環境で黙って素通りしないこと。2026-07-27 に、配っていた17本が
+# jq 不在で沈黙して素通りしていた(遮断すべき14通りが3環境すべてで0/14)。
+# 「検査する対象が無かった」と「検査する道具が無かった」を混同しないため、
+# ここでは通すが必ず声を出す。どれも無い環境で遮断を選ぶと全ツール呼び出しが
+# 止まって Claude Code が使えなくなるので、fail-open + 警告にする。
+if ! command -v jq >/dev/null 2>&1; then
+    echo "nested-background-agent-guard: jq not found — cannot inspect this dispatch, passing through unchecked." >&2
+    exit 0
+fi
+
+TOOL="$(printf '%s\n' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)"
+case "$TOOL" in
+    Agent|Task|SendMessage) ;;
+    *) exit 0 ;;
+esac
+
+BG="$(printf '%s\n' "$INPUT" | jq -r '.tool_input.run_in_background // false' 2>/dev/null)"
+[ "$BG" = "true" ] || exit 0
+
+# 親(top-level)からの背景の生成は通す。止めたいのは入れ子の側だけ。
+[ -n "${CLAUDE_CODE_CHILD_SESSION:-}" ] || exit 0
+
+cat >&2 <<'MSG'
+Blocked: a sub-agent tried to spawn a background agent.
+
+Issue #73829: nested background agents orphan and loop. Once the intermediate
+agent's session ends, TaskStop/TaskOutput return "No task found" while the tasks
+keep running and burning tokens — 6.5 hours and several hundred USD in the
+original report.
+
+Since Claude Code 2.1.219 the default nesting depth is 3 (was 1), so this shape
+now has three levels to compound through instead of one.
+
+Do one of these instead:
+  - Do the sub-topics inline in this sub-agent (no further dispatch).
+  - Spawn background agents only from the top-level session, where TaskStop works.
+  - If you genuinely need nesting, cap it first: CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1
+MSG
+exit 2

package/examples/nested-spawn-inflight-guard.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+# nested-spawn-inflight-guard.sh — Refuse Task/SendMessage dispatch when too many subagents are already in flight
+#
+# Why: Issue #62193 (fdpr-H, 2026-05-25 — 3,079 bash subprocesses spawned in 17s,
+#      hard reboot required) and the 2026-05-29 follow-up from @allenfu000 (Windows,
+#      v2.1.156, Opus 4.8 ultracode workflow — subagents spawning nested PowerShell
+#      until OOM, taking down two other Claude Code windows alongside) are the two
+#      canonical reproductions of Cluster 1's nested-spawn sub-pattern: uncapped
+#      fan-out at the orchestration layer rather than inside a single tool call.
+#
+#      Two existing cc-safe-setup hooks address the same architectural surface
+#      with different approaches:
+#
+#        - max-concurrent-agents.sh uses a /tmp counter file that increments on
+#          dispatch but never decrements — relies on file-age expiry (10 min) to
+#          reset. Over-counts on the rebound path (counter persists after agents
+#          complete), under-counts on burst recovery (file mtime resets the
+#          window for unrelated samples).
+#
+#        - subagent-budget-guard.sh uses a per-line timestamp tracker in
+#          ~/.claude/active-agents with a 30-minute "active" window. Same
+#          time-window approximation; same dual error mode.
+#
+#      Both also match only the legacy tool_name "Agent", missing the modern
+#      "Task" and "SendMessage" dispatcher entry points.
+#
+#      This hook reads the actual transcript at dispatch time, counts in-flight
+#      subagents (tool_use entries with no matching tool_result), and refuses
+#      the new dispatch when the count exceeds the configured budget. Because
+#      the count comes from the transcript itself, there is no stale-state
+#      window and no counter to leak.
+#
+# Event: PreToolUse  MATCHER: "Task|Agent|SendMessage"
+# Action: Scan the transcript for tool_use entries whose name matches the
+#         dispatcher family (Task / Agent / SendMessage). Subtract those that
+#         already have a tool_result with the same tool_use_id. If the
+#         remaining count (in-flight) >= CC_NESTED_SPAWN_BUDGET, exit 2 with
+#         a stderr advisory naming the budget, the counted in-flight ids,
+#         and the override path. Otherwise exit 0.
+#
+# Configuration (all optional):
+#   CC_NESTED_SPAWN_BUDGET     Max concurrent in-flight subagents (default: 5)
+#   CC_NESTED_SPAWN_DISABLE    Set to "1" to bypass entirely (escape hatch)
+#   CC_NESTED_SPAWN_LOOKBACK   Number of trailing transcript lines to scan
+#                              (default: 2000; raise for very long sessions)
+#
+# Override one specific dispatch (clear after the call to re-arm):
+#   CC_NESTED_SPAWN_OVERRIDE=1 claude ...
+#
+# Reading the in-flight set (manual inspection):
+#   jq -c 'select(.message.content[]?.type=="tool_use" and
+#                 (.message.content[].name|test("Task|Agent|SendMessage")))' \
+#     ~/.claude/projects/*/SESSION.jsonl
+
+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-nested-spawn-inflight-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [nested-spawn-inflight-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+BUDGET="${CC_NESTED_SPAWN_BUDGET:-5}"
+LOOKBACK="${CC_NESTED_SPAWN_LOOKBACK:-2000}"
+DISABLE="${CC_NESTED_SPAWN_DISABLE:-0}"
+OVERRIDE="${CC_NESTED_SPAWN_OVERRIDE:-0}"
+
+# Escape hatches: disable entirely, or override one specific call.
+if [ "$DISABLE" = "1" ] || [ "$OVERRIDE" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+
+# Only act when the tool being dispatched is itself a subagent dispatcher.
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+case "$TOOL" in
+  Task|Agent|SendMessage) ;;
+  *) exit 0 ;;
+esac
+
+# Locate the transcript. Without it we can't measure in-flight state — fail open.
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+if [ -z "$TRANSCRIPT" ] || [ ! -r "$TRANSCRIPT" ]; then
+  exit 0
+fi
+
+# Sanity-check the budget; nonsense values fail open.
+case "$BUDGET" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+case "$LOOKBACK" in
+  ''|*[!0-9]*) LOOKBACK=2000 ;;
+esac
+
+# Collect dispatched ids (tool_use entries with name in the dispatcher family)
+# and resolved ids (tool_result entries) from the trailing window of the
+# transcript. The set difference is the in-flight set.
+#
+# Two transcript shapes are common:
+#   - {"message": {"content": [...]}}              (assistant turns + user turns)
+#   - {"type":"tool_use","id":"...","name":"..."}  (some hook payload echoes)
+#
+# We accept both. jq extracts the union by trying each path.
+ANALYSIS=$(tail -n "$LOOKBACK" "$TRANSCRIPT" 2>/dev/null | \
+  jq -rs '
+    def extract_tool_use:
+      (.message.content // [.])[] |
+      select(type == "object" and .type == "tool_use") |
+      select(.name | test("^(Task|Agent|SendMessage)$"; "")) |
+      .id // empty;
+    def extract_tool_result:
+      (.message.content // [.])[] |
+      select(type == "object" and .type == "tool_result") |
+      .tool_use_id // empty;
+
+    . as $rows |
+    ($rows | map(extract_tool_use) | flatten | map(select(. != ""))) as $dispatched |
+    ($rows | map(extract_tool_result) | flatten | map(select(. != ""))) as $resolved |
+    ($dispatched - $resolved) as $inflight |
+    {
+      inflight_count: ($inflight | length),
+      inflight_ids: $inflight
+    } |
+    @json
+  ' 2>/dev/null)
+
+# If the jq pipeline failed, fail open — never block on hook bugs.
+if [ -z "$ANALYSIS" ]; then
+  exit 0
+fi
+
+INFLIGHT_COUNT=$(printf '%s' "$ANALYSIS" | jq -r '.inflight_count // 0' 2>/dev/null)
+case "$INFLIGHT_COUNT" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+
+# If at or above the budget, the new dispatch would push us into runaway territory.
+# Refuse with a stderr advisory.
+if [ "$INFLIGHT_COUNT" -ge "$BUDGET" ]; then
+  IDS=$(printf '%s' "$ANALYSIS" | jq -r '.inflight_ids | join(", ")' 2>/dev/null)
+  cat >&2 <<EOF
+BLOCKED: ${INFLIGHT_COUNT} subagent(s) already in flight (budget: ${BUDGET}).
+  In-flight ids: ${IDS}
+  This dispatch would push the count to $((INFLIGHT_COUNT + 1)). Wait for one
+  or more to complete (tool_result) before dispatching another, or raise the
+  budget via CC_NESTED_SPAWN_BUDGET=N for legitimate fan-out workloads.
+
+  To allow this specific call without changing the budget:
+    CC_NESTED_SPAWN_OVERRIDE=1 (clears after the next dispatch)
+  To disable the guard entirely:
+    CC_NESTED_SPAWN_DISABLE=1
+
+  Root cause, if you never wanted nesting: subagents spawning subagents is
+  opt-out at the source.
+    CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1
+  Set it explicitly rather than relying on the default. Verified in 2.1.220 by
+  reading the shipped binary: the depth default is fetched from a remote config
+  and only falls back to the built-in 3 when that fetch yields nothing, so the
+  changelog's "default is 3" is a fallback, not a guarantee. The two sibling
+  caps are plain constants by contrast (concurrent 20, per-session 200).
+
+  Why this guard exists: Issue #62193 (3,079 bash subprocesses in 17s, hard
+  reboot) and the 2026-05-29 Windows follow-up (ultracode subagents spawning
+  PowerShell until two other Claude Code windows crashed). Cluster 1
+  (Sub-Agent Observability) nested-spawn sub-pattern.
+  See: https://github.com/yurukusa/cc-safe-setup/blob/main/docs/cluster-tracker.html#cluster-soh
+EOF
+  exit 2
+fi
+
+exit 0

package/examples/network-exfil-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-network-exfil-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [network-exfil-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/network-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-network-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [network-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/network-interface-guard.sh

@@ -13,6 +13,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-network-interface-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [network-interface-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/nextjs-env-guard.sh

@@ -21,7 +21,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/no-any-typescript.sh

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

package/examples/no-ask-human.sh

@@ -23,6 +23,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-no-ask-human-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [no-ask-human]: 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/no-base64-exfil.sh

@@ -7,6 +7,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-no-base64-exfil-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [no-base64-exfil]: 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