cc-safe-setup 29.8.0 → 30.0.5

package/examples/stop-hook-sigterm-wrapper.sh

@@ -0,0 +1,182 @@
+#!/bin/bash
+# ================================================================
+# stop-hook-sigterm-wrapper.sh — Wrap the claude CLI so an
+#   external supervisor can distinguish "completed" from "killed
+#   mid-work" when SIGTERM (e.g. `timeout` exit code 124) bypasses
+#   the configured Stop hook.
+# ================================================================
+# PURPOSE:
+#   Issue #64017 documents a class where SIGTERM termination of
+#   the claude process (typically by a wrapper enforcing an
+#   execution timeout) kills the CLI without firing the configured
+#   Stop hook. Any state the Stop hook was responsible for writing
+#   is left stale — it still reflects the previous run — so a
+#   supervisor reading that file cannot tell "completed" apart
+#   from "killed mid-work."
+#
+#   The reporter's own band-aid was an outer wrapper that observes
+#   the wrapped command's exit code and writes its own termination
+#   marker before reading any hook output. This script ships a
+#   clean, parseable version of that band-aid: it wraps the claude
+#   invocation, traps SIGTERM/SIGINT, and writes a JSON state file
+#   on every transition (running, completed, killed-sigterm,
+#   killed-sigint, killed-timeout, killed-sigkill, error). The
+#   supervisor reads the state file and can decisively
+#   differentiate the termination cause.
+#
+#   This is not a fix for the upstream Stop-hook-on-SIGTERM gap.
+#   It is the operator-side workaround that lets supervisors stop
+#   misattributing prior-run completion summaries to current
+#   killed runs.
+#
+# CLUSTER:
+#   Candidate cluster #21 — Plugin lifecycle integrity gap
+#   Sub-axis 21D — signal gap (Stop hook silent on SIGTERM, #64017).
+#
+# USAGE:
+#   1. Place this script on PATH (e.g. ~/bin/claude-wrapped.sh)
+#   2. Optionally alias claude='/path/to/stop-hook-sigterm-wrapper.sh'
+#   3. Or invoke directly: stop-hook-sigterm-wrapper.sh -p "your prompt"
+#   4. Supervisor reads $CC_STOP_SIGTERM_MARKER_DIR/state.json after
+#      the wrapped invocation completes (or is killed)
+#
+#   The state file is JSON, one line per state transition:
+#     {"state":"running","timestamp":"2026-05-31T10:00:00+0900","pid":12345}
+#     {"state":"completed","timestamp":"2026-05-31T10:30:00+0900","exit_code":0,"duration_s":1800}
+#
+#   States:
+#     running         — claude was launched, no termination signal yet
+#     completed       — claude exited with code 0
+#     killed-sigterm  — claude received SIGTERM (exit 143)
+#     killed-sigint   — claude received SIGINT / Ctrl-C (exit 130)
+#     killed-timeout  — wrapper saw exit 124 from `timeout` wrapper above us
+#     killed-sigkill  — claude exited with 137 (SIGKILL, cannot be trapped)
+#     error           — claude exited with any other non-zero code
+#
+# ENV:
+#   CC_STOP_SIGTERM_MARKER_DIR   default $HOME/.claude/run-state
+#   CC_STOP_SIGTERM_WRAPPER_CMD  default "claude" (override for testing or alt CLI path)
+#   CC_STOP_SIGTERM_DISABLE      non-empty → wrapper passes through without writing markers
+# ================================================================
+
+set -u
+
+# Disable pass-through
+if [ -n "${CC_STOP_SIGTERM_DISABLE:-}" ]; then
+    exec "${CC_STOP_SIGTERM_WRAPPER_CMD:-claude}" "$@"
+fi
+
+# No-op when invoked with no args. The cc-safe-setup CI smoke-tests every
+# example/*.sh by piping an empty stdin and expecting exit 0 — this wrapper
+# is invoked with claude's CLI arguments, never with stdin alone, so a no-args
+# invocation is unambiguously the smoke-test path.
+if [ $# -eq 0 ]; then
+    exit 0
+fi
+
+MARKER_DIR="${CC_STOP_SIGTERM_MARKER_DIR:-$HOME/.claude/run-state}"
+WRAPPED_CMD="${CC_STOP_SIGTERM_WRAPPER_CMD:-claude}"
+STATE_FILE="$MARKER_DIR/state.json"
+
+mkdir -p "$MARKER_DIR" 2>/dev/null || {
+    # If we cannot create the marker dir, fall back to pass-through
+    exec "$WRAPPED_CMD" "$@"
+}
+
+# Portable ISO 8601 timestamp with timezone
+timestamp() {
+    if date +%Y-%m-%dT%H:%M:%S%z >/dev/null 2>&1; then
+        date +%Y-%m-%dT%H:%M:%S%z
+    else
+        date -u +%Y-%m-%dT%H:%M:%SZ
+    fi
+}
+
+write_state() {
+    local state="$1"
+    local extra="$2"
+    local now
+    now=$(timestamp)
+    local payload="{\"state\":\"$state\",\"timestamp\":\"$now\",\"pid\":$$"
+    if [ -n "$extra" ]; then
+        payload="$payload,$extra"
+    fi
+    payload="$payload}"
+    # Atomic write: rename from temp
+    local tmp
+    tmp=$(mktemp "$MARKER_DIR/.state.json.XXXXXX" 2>/dev/null) || {
+        # mktemp failed; best-effort direct write
+        printf '%s\n' "$payload" > "$STATE_FILE" 2>/dev/null
+        return
+    }
+    printf '%s\n' "$payload" > "$tmp"
+    mv -f "$tmp" "$STATE_FILE" 2>/dev/null
+}
+
+# Track start time for duration calculation on exit
+START_S=$(date +%s)
+
+# Initial state: running
+write_state "running" ""
+
+# Trap signals — write the killed state before exiting. We re-raise
+# the same signal so the parent supervisor still sees the normal
+# 128+N exit code, preserving wait() semantics.
+on_sigterm() {
+    local elapsed=$(( $(date +%s) - START_S ))
+    write_state "killed-sigterm" "\"exit_code\":143,\"duration_s\":$elapsed"
+    # Kill the child if still alive
+    if [ -n "${CLAUDE_PID:-}" ] && kill -0 "$CLAUDE_PID" 2>/dev/null; then
+        kill -TERM "$CLAUDE_PID" 2>/dev/null
+    fi
+    exit 143
+}
+on_sigint() {
+    local elapsed=$(( $(date +%s) - START_S ))
+    write_state "killed-sigint" "\"exit_code\":130,\"duration_s\":$elapsed"
+    if [ -n "${CLAUDE_PID:-}" ] && kill -0 "$CLAUDE_PID" 2>/dev/null; then
+        kill -INT "$CLAUDE_PID" 2>/dev/null
+    fi
+    exit 130
+}
+trap on_sigterm TERM
+trap on_sigint INT
+
+# Launch the wrapped command in background so we can wait() and trap.
+# Pass through all args verbatim.
+"$WRAPPED_CMD" "$@" &
+CLAUDE_PID=$!
+
+# Wait for completion. `wait` is interrupted by trapped signals.
+wait "$CLAUDE_PID"
+EXIT_CODE=$?
+
+# Compute duration
+ELAPSED=$(( $(date +%s) - START_S ))
+
+# Map exit code to state
+case $EXIT_CODE in
+    0)
+        write_state "completed" "\"exit_code\":0,\"duration_s\":$ELAPSED"
+        ;;
+    124)
+        # `timeout` parent exit code — wrapped command was killed by
+        # an outer `timeout` wrapper.
+        write_state "killed-timeout" "\"exit_code\":124,\"duration_s\":$ELAPSED"
+        ;;
+    130)
+        write_state "killed-sigint" "\"exit_code\":130,\"duration_s\":$ELAPSED"
+        ;;
+    137)
+        # SIGKILL cannot be trapped, but we can record it post-mortem.
+        write_state "killed-sigkill" "\"exit_code\":137,\"duration_s\":$ELAPSED"
+        ;;
+    143)
+        write_state "killed-sigterm" "\"exit_code\":143,\"duration_s\":$ELAPSED"
+        ;;
+    *)
+        write_state "error" "\"exit_code\":$EXIT_CODE,\"duration_s\":$ELAPSED"
+        ;;
+esac
+
+exit $EXIT_CODE

package/examples/stop-transcript-write-health.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# ================================================================
+# stop-transcript-write-health.sh — Detect a silently stalled or reverted transcript
+# ================================================================
+# PURPOSE:
+#   Claude Code writes the conversation to
+#   ~/.claude/projects/<slug>/<session-id>.jsonl as the session runs.
+#   Some failures stop that write silently: an account switch can revert
+#   the live file to an older snapshot and then never write again, with no
+#   error shown (anthropics/claude-code#73937). The session keeps working,
+#   so the loss is invisible until you diff line counts by hand.
+#
+# HOW IT WORKS:
+#   Stop fires after every completed turn and its input carries
+#   `transcript_path`. That is the natural "a turn's worth of lines should
+#   have just been written" checkpoint. This hook records the transcript's
+#   line count and mtime per session_id, and on the next Stop:
+#     - line count + mtime unchanged since last turn  -> the turn was NOT
+#       persisted (silent save-stop) -> warn.
+#     - line count shrank                             -> the file was
+#       reverted to an older snapshot -> warn.
+#   The warning is emitted via {"systemMessage": ...} so it surfaces to the
+#   user without blocking the session. It only detects; it does not replace
+#   an independent content backup.
+#
+# TRIGGER: Stop
+# MATCHER: (none — Stop has no tool matcher)
+#
+# CONFIGURATION:
+#   none
+# ================================================================
+set -uo pipefail
+
+input=$(cat)
+tp=$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null)
+sid=$(printf '%s' "$input" | jq -r '.session_id // "nosid"' 2>/dev/null)
+
+# No transcript path / unreadable -> nothing to check.
+[ -z "$tp" ] && exit 0
+[ ! -f "$tp" ] && exit 0
+
+state_dir="${HOME}/.claude/transcript-health"
+mkdir -p "$state_dir"
+state_file="${state_dir}/${sid}.state"
+
+cur_lines=$(wc -l < "$tp" 2>/dev/null | tr -d ' ')
+cur_mtime=$(stat -c %Y "$tp" 2>/dev/null || stat -f %m "$tp" 2>/dev/null)
+
+warn=""
+if [ -f "$state_file" ]; then
+    read -r prev_lines prev_mtime < "$state_file"
+    if [ "${cur_lines:-0}" -lt "${prev_lines:-0}" ]; then
+        warn="⚠ transcript reverted (${prev_lines}→${cur_lines} lines). The live file may have been replaced with an older snapshot (account switch / #73937). Check your recovery point before continuing."
+    elif [ "${cur_lines:-0}" -eq "${prev_lines:-0}" ] && [ "${cur_mtime:-0}" -eq "${prev_mtime:-0}" ]; then
+        warn="⚠ the last turn was NOT persisted to ${tp} (line count and mtime unchanged since the previous turn). Saves may have silently stopped (#73937). This turn may exist only in memory — take an independent backup and restart."
+    fi
+fi
+
+printf '%s %s\n' "${cur_lines:-0}" "${cur_mtime:-0}" > "$state_file"
+
+if [ -n "$warn" ]; then
+    jq -cn --arg m "$warn" '{systemMessage:$m}'
+fi
+exit 0

package/examples/strict-allowlist.sh

@@ -18,6 +18,18 @@
 #   "Immutable session manifest with allowlist-only enforcement"
 # ================================================================
 
+# 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-strict-allowlist-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [strict-allowlist]: 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
 
@@ -65,24 +77,54 @@ DEFAULT
     echo "Edit it to customize permitted commands." >&2
 fi
 
-# Check command against allowlist
-ALLOWED=0
-while IFS= read -r pattern; do
-    # Skip comments and empty lines
-    [[ "$pattern" =~ ^[[:space:]]*# ]] && continue
-    [[ -z "$pattern" ]] && continue
-
-    if echo "$COMMAND" | grep -qE "$pattern"; then
-        ALLOWED=1
-        break
-    fi
-done < "$ALLOWLIST"
+# One line can chain several commands. The shipped patterns are anchored with
+# "^", so matching them against the whole line only ever inspects the first
+# word: an approved command followed by "&&" and anything at all was approved.
+# For a denylist that is a gap; for an allowlist it means the list stops
+# enforcing after the first segment, which is the whole feature. Claude Code
+# closed the same class of hole in its own permission checking (2.1.216,
+# "Fixed Bash permission checking for compound statements").
+#
+# So: split on the operators that begin a new command and require EVERY segment
+# to match a pattern. One unapproved segment blocks the line.
+SEGMENTS=$(printf '%s' "$COMMAND" | sed -E 's/(\|\||&&|[;|&])/\n/g')
 
-if [ "$ALLOWED" -eq 0 ]; then
-    echo "BLOCKED: Command not in allowlist." >&2
+# Command substitution executes text that never appears as a segment, so
+# splitting cannot vet it. Refuse rather than guess.
+if printf '%s' "$COMMAND" | grep -qE '\$\(|`'; then
+    echo "BLOCKED: command substitution is not allowed by the allowlist." >&2
     echo "Command: $COMMAND" >&2
-    echo "Add a matching pattern to $ALLOWLIST to permit." >&2
     exit 2
 fi
 
+while IFS= read -r SEGMENT; do
+    # sed leaves an empty field where a two-character operator was split
+    [[ -z "${SEGMENT//[[:space:]]/}" ]] && continue
+
+    # "ls; pwd" splits into "ls" and " pwd". The shipped patterns are anchored
+    # with "^" and no leading \s*, so the space would make the second segment
+    # fail to match and block a perfectly approved chain. Trim before matching.
+    SEGMENT=$(printf '%s' "$SEGMENT" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')
+
+    ALLOWED=0
+    while IFS= read -r pattern; do
+        # Skip comments and empty lines
+        [[ "$pattern" =~ ^[[:space:]]*# ]] && continue
+        [[ -z "$pattern" ]] && continue
+
+        if printf '%s' "$SEGMENT" | grep -qE "$pattern"; then
+            ALLOWED=1
+            break
+        fi
+    done < "$ALLOWLIST"
+
+    if [ "$ALLOWED" -eq 0 ]; then
+        echo "BLOCKED: Command not in allowlist." >&2
+        echo "Command: $COMMAND" >&2
+        echo "Unapproved segment: $SEGMENT" >&2
+        echo "Add a matching pattern to $ALLOWLIST to permit." >&2
+        exit 2
+    fi
+done <<< "$SEGMENTS"
+
 exit 0

package/examples/strip-coauthored-by.sh

@@ -1,9 +1,21 @@
 #!/bin/bash
-# strip-coauthored-by.sh — Remove or warn about Co-Authored-By trailers
+# strip-coauthored-by.sh — Warn about (or block) unwanted commit-message trailers
 #
-# Solves: Claude auto-appending Co-Authored-By to every commit without
-# user consent. 489 commits branded without the user wanting it.
-# See: https://github.com/anthropics/claude-code/issues/29999
+# Solves two trailers Claude appends to commits without the user asking:
+#   1. Co-Authored-By: ...Claude/Anthropic — branding without consent.
+#      See: https://github.com/anthropics/claude-code/issues/29999
+#   2. Claude-Session: https://claude.ai/code/session_<id> — leaks a PRIVATE
+#      session identifier into commit history, which is published to public
+#      repos. Data minimisation should apply by default.
+#      See: https://github.com/anthropics/claude-code/issues/69669
+#
+# Mechanism: this is a PreToolUse hook, which can BLOCK a tool call (exit 2)
+# but cannot rewrite it — so it cannot silently strip the trailer. Instead it
+# bounces the commit back so the model removes the trailer before committing.
+#   - Session-id leak: blocked by default (exit 2) — it is a privacy issue.
+#   - Co-Authored-By:  warn-only (exit 0) — it is a preference, user decides.
+# Note: only the `git commit -m "<msg>"` form carries the message in the
+# command string. Commits via an editor or `-F <file>` are not visible here.
 #
 # TRIGGER: PreToolUse
 # MATCHER: Bash
@@ -22,19 +34,47 @@
 #   }
 # }
 #
-# Config: CC_ALLOW_COAUTHOR=1 to allow (default: 0 = block/warn)
+# Config:
+#   CC_ALLOW_COAUTHOR=1         allow Co-Authored-By trailers (default: 0 = warn)
+#   CC_ALLOW_SESSION_TRAILER=1  allow the session-id URL trailer (default: 0 = block)
+
+# 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-strip-coauthored-by-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [strip-coauthored-by]: 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
 
-# Only check git commit commands
-echo "$COMMAND" | grep -qE '^\s*git\s+commit' || exit 0
+# Only inspect git commit commands. Match at the start or after a chaining
+# operator (so `cd repo && git commit ...` is covered too).
+echo "$COMMAND" | grep -qE '(^|[;&|[:space:]])git[[:space:]]+commit' || exit 0
+
+# 1. Private session-id leak — block by default (privacy issue).
+#    The harness emits `Claude-Session: https://claude.ai/code/session_<id>`.
+if echo "$COMMAND" | grep -qiE 'claude\.ai/code/session|Claude-Session:'; then
+    if [ "${CC_ALLOW_SESSION_TRAILER:-0}" != "1" ]; then
+        echo "✖ Blocked: commit message contains a private Claude session URL" >&2
+        echo "  (Claude-Session: https://claude.ai/code/session_...)." >&2
+        echo "  This publishes a private session identifier to your repo history." >&2
+        echo "  Remove that trailer from the commit message, then retry." >&2
+        echo "  Set CC_ALLOW_SESSION_TRAILER=1 to allow it. See issue #69669." >&2
+        exit 2
+    fi
+fi
 
-# Check if Co-Authored-By is in the commit message
-if echo "$COMMAND" | grep -qiE 'Co-Authored-By.*Claude\|Co-Authored-By.*Anthropic\|Co-Authored-By.*noreply@anthropic'; then
+# 2. Co-Authored-By branding — warn only (the user decides).
+if echo "$COMMAND" | grep -qiE 'Co-Authored-By.*(Claude|Anthropic|noreply@anthropic)'; then
     if [ "${CC_ALLOW_COAUTHOR:-0}" = "1" ]; then
-        exit 0  # User explicitly allows
+        exit 0
     fi
     echo "⚠ Co-Authored-By trailer detected in commit message" >&2
     echo "  Set CC_ALLOW_COAUTHOR=1 to allow, or remove the trailer." >&2

package/examples/subagent-blast-radius-guard.sh

@@ -0,0 +1,184 @@
+#!/bin/bash
+# ================================================================
+# subagent-blast-radius-guard.sh — Surface and gate the files a
+#   sub-agent actually writes, at the moment it writes them
+# ================================================================
+# PURPOSE:
+#   Existing sub-agent hooks in this repo (subagent-scope-validator,
+#   subagent-tool-allowlist-enforcer, subagent-boundary-precheck,
+#   subagent-destructive-git-guard, ...) all fire on the PARENT's
+#   PreToolUse for the Agent/Task tool. They inspect the delegation
+#   PROMPT and nudge the operator to state boundaries before the
+#   sub-agent starts. None of them see what the sub-agent then
+#   actually does. Once the sub-agent is running, its individual
+#   Write/Edit calls are unguarded at the execution layer.
+#
+#   This hook closes that gap. It fires on the sub-agent's own
+#   Write/Edit calls and keys off the `agent_id` / `agent_type`
+#   fields that Claude Code adds to the PreToolUse payload for
+#   sub-agent-originated tool calls (verified on v2.1.161: a
+#   sub-agent's Write call carries agent_id+agent_type; the main
+#   thread's calls do not). When agent_id is present, the write
+#   came from a sub-agent, and this hook can surface it or block it
+#   — without ever touching the human-supervised main agent's writes.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit|Write"
+#
+# WHY THIS MATTERS:
+#   #65152 (2026-06-03) — a sub-agent asked only to "run these two
+#   shell commands" autonomously used Write/Edit on 15 files,
+#   including production database migration files, and the operator
+#   only discovered the blast radius after the fact. The same shape
+#   recurs in #63356 and #45108: a narrowly-scoped delegation turns
+#   into a wide, partly-irreversible set of writes, and there is no
+#   per-write signal the operator sees in time to intervene.
+#
+#   The fix the parent-side nudge hooks cannot provide is a signal
+#   (or a stop) at the instant the sub-agent writes a high-blast
+#   file. That is what this hook adds.
+#
+# WHAT IT DOES:
+#   * Main-thread writes (no agent_id): exit 0 immediately. This hook
+#     deliberately never interferes with the supervised main agent.
+#   * Sub-agent writes (agent_id present): apply CC_SUBAGENT_WRITE_GUARD:
+#       off       — do nothing (exit 0).
+#       warn      — (default) warn on a "flagged" write (sensitive
+#                   path, or outside the allowlist when one is set);
+#                   silent on ordinary writes. Always exit 0.
+#       warn-all  — warn on EVERY sub-agent write (full blast-radius
+#                   visibility). Always exit 0.
+#       block     — exit 2 (block) on a flagged write; ordinary
+#                   sub-agent writes pass silently.
+#
+#   A write is "flagged" when it matches the high-blast sensitive
+#   pattern (migrations, IaC state, .env / secrets, prod config, DB
+#   schema, lockfiles, CI workflows) OR — if CC_SUBAGENT_WRITE_ALLOW
+#   is set — when it falls outside every allowed path prefix.
+#
+# CONFIG:
+#   CC_SUBAGENT_WRITE_GUARD     off | warn (default) | warn-all | block
+#   CC_SUBAGENT_WRITE_ALLOW     space/colon-separated path prefixes the
+#                               sub-agent may write under (e.g.
+#                               "src/feature-x/ docs/"). Writes outside
+#                               all prefixes are flagged. Match is a
+#                               literal prefix on the file_path Claude
+#                               passes (usually an absolute cwd path).
+#   CC_SUBAGENT_WRITE_SENSITIVE extra ERE appended (alternation) to the
+#                               built-in sensitive pattern.
+#
+# DESIGN NOTES (why these defaults):
+#   * Default is warn, not block: blocking a sub-agent mid-run can
+#     wedge legitimate fan-out work and break headless/CI. Visibility
+#     of the dangerous writes is the safe default; blocking is opt-in,
+#     matching memory-write-guard's opt-in philosophy.
+#   * Fail-open on malformed input / missing jq: a safety hook must
+#     never be the thing that breaks the session.
+#   * Edit|Write only (not Bash): destructive Bash by anyone is already
+#     covered by rm-safety-net / destructive-guard / git guards
+#     regardless of agent_id. The genuinely uncovered gap is the
+#     sub-agent's structured file writes.
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/65152
+#   https://github.com/anthropics/claude-code/issues/63356
+#   https://github.com/anthropics/claude-code/issues/45108
+# ================================================================
+
+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-subagent-blast-radius-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [subagent-blast-radius-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+MODE="${CC_SUBAGENT_WRITE_GUARD:-warn}"
+[ "$MODE" = "off" ] && exit 0
+
+# agent_id is present only for sub-agent-originated tool calls. No
+# agent_id => main-thread write => never our concern.
+AGENT_ID=$(printf '%s' "$INPUT" | jq -r '.agent_id // empty' 2>/dev/null)
+[ -z "$AGENT_ID" ] && exit 0
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+AGENT_TYPE=$(printf '%s' "$INPUT" | jq -r '.agent_type // empty' 2>/dev/null)
+[ -z "$AGENT_TYPE" ] && AGENT_TYPE="subagent"
+
+# High-blast / hard-to-reverse destinations a narrowly-scoped sub-agent
+# should not be silently rewriting.
+SENSITIVE_ERE='(^|/)migrations?/|(^|/)migrate/|\.tf$|\.tfstate|(^|/)terraform/|(^|/)\.env|secrets?\.(ya?ml|json|env)|(^|/)credentials|(^|/)(prod|production)\.(ya?ml|yml|json|env|toml)|(^|/)config/(prod|production)|schema\.(sql|prisma|rb)$|(^|/)db/schema|(^|/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|poetry\.lock|Gemfile\.lock)$|(^|/)\.github/workflows/|(^|/)\.gitlab-ci\.yml$'
+if [ -n "${CC_SUBAGENT_WRITE_SENSITIVE:-}" ]; then
+    SENSITIVE_ERE="${SENSITIVE_ERE}|${CC_SUBAGENT_WRITE_SENSITIVE}"
+fi
+
+is_sensitive=0
+if printf '%s' "$FILE" | grep -qE "$SENSITIVE_ERE"; then
+    is_sensitive=1
+fi
+
+# Allowlist: if set, a write outside every prefix is out-of-scope.
+out_of_scope=0
+REASON=""
+if [ -n "${CC_SUBAGENT_WRITE_ALLOW:-}" ]; then
+    out_of_scope=1
+    # Split on whitespace and colons.
+    OLD_IFS="$IFS"; IFS=': '
+    for prefix in $CC_SUBAGENT_WRITE_ALLOW; do
+        [ -z "$prefix" ] && continue
+        case "$FILE" in
+            "$prefix"*) out_of_scope=0 ;;
+        esac
+    done
+    IFS="$OLD_IFS"
+fi
+
+flagged=0
+if [ "$is_sensitive" -eq 1 ]; then
+    flagged=1
+    REASON="high-blast path (migration / IaC / secret / prod config / schema / lockfile / CI)"
+fi
+if [ "$out_of_scope" -eq 1 ]; then
+    flagged=1
+    if [ -n "$REASON" ]; then
+        REASON="$REASON; outside CC_SUBAGENT_WRITE_ALLOW"
+    else
+        REASON="outside CC_SUBAGENT_WRITE_ALLOW ($CC_SUBAGENT_WRITE_ALLOW)"
+    fi
+fi
+
+SHORT_ID=$(printf '%s' "$AGENT_ID" | cut -c1-8)
+
+emit_warn() {
+    echo "subagent-blast-radius-guard: sub-agent [$AGENT_TYPE#$SHORT_ID] is writing $FILE${1:+ — $1}" >&2
+}
+
+case "$MODE" in
+    warn-all)
+        if [ "$flagged" -eq 1 ]; then emit_warn "$REASON"; else emit_warn ""; fi
+        exit 0
+        ;;
+    block)
+        if [ "$flagged" -eq 1 ]; then
+            echo "BLOCKED: sub-agent [$AGENT_TYPE#$SHORT_ID] attempted to write $FILE" >&2
+            echo "Reason: $REASON." >&2
+            echo "A narrowly-delegated sub-agent should not write this. Re-delegate with an explicit scope, write it from the supervised main thread, or set CC_SUBAGENT_WRITE_GUARD=warn to allow with a warning." >&2
+            exit 2
+        fi
+        exit 0
+        ;;
+    *)  # warn (default)
+        [ "$flagged" -eq 1 ] && emit_warn "$REASON"
+        exit 0
+        ;;
+esac