cc-safe-setup 29.8.0 → 30.0.5

package/examples/multi-vendor-concurrent-warner.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# ================================================================
+# multi-vendor-concurrent-warner.sh — Warn when another AI coding
+#   CLI (Codex, Gemini, Cursor, Aider, Amp, ...) is running at the
+#   same time as Claude Code, so concurrent edits to the same repo
+#   do not silently collide.
+# ================================================================
+# PURPOSE:
+#   A growing number of operators run several AI coding tools in
+#   parallel — Claude Code plus Codex, Gemini CLI, Cursor's agent,
+#   Aider, Amp, and others — pointed at the same repository. Two
+#   failure modes follow, and neither tool can see the other:
+#     1. Conflicting edits. Two agents edit the same file; one
+#        overwrites the other, or the repo lands in a broken state
+#        (reported: dozens of type errors after a parallel run).
+#     2. Cost is invisible. Each vendor bills separately; the
+#        combined spend across tools is not shown in any one tool,
+#        and parallel runs multiply it (operators report 3-5x).
+#
+#   Every other concurrency hook in cc-safe-setup bounds Claude
+#   Code's OWN subagents (max-concurrent-agents, parallel-edit-guard,
+#   subagent-budget-guard, ...). None of them can see a SEPARATE
+#   vendor's process. This hook fills that gap: at session start it
+#   checks the process table for other AI CLIs and, if it finds one,
+#   prints a one-time advisory so the operator coordinates scope and
+#   watches combined cost.
+#
+# UPSTREAM / CONTEXT:
+#   The multi-vendor parallel-operation pattern (Claude Code + Codex
+#   + Gemini + Grok) is a real and growing operator workflow. This
+#   hook is advisory only — it never blocks and never inspects the
+#   other tool; it only notes that it is running.
+#
+# TRIGGER: SessionStart   (also safe as PreToolUse)
+#
+# CONFIGURATION (env vars):
+#   CC_MULTI_VENDOR_PROCS    Space-separated process names to treat
+#                            as other AI CLIs. Default covers the
+#                            common ones. Claude's own process is
+#                            never matched.
+#   CC_MULTI_VENDOR_PS       Override the command used to list
+#                            process names (default: ps -eo comm=).
+#   CC_MULTI_VENDOR_PS_OUTPUT  Pre-supplied process listing (tests).
+# ================================================================
+
+set -u
+
+# Read and discard stdin (hook protocol); this hook does not use it.
+cat > /dev/null 2>&1 || true
+
+DEFAULT_PROCS="codex gemini cursor-agent cursor-agent-cli aider amp ampcode grok cline continue goose qwen"
+PROCS="${CC_MULTI_VENDOR_PROCS:-$DEFAULT_PROCS}"
+
+# Obtain the list of running process names.
+if [ -n "${CC_MULTI_VENDOR_PS_OUTPUT:-}" ]; then
+    PS_LIST="$CC_MULTI_VENDOR_PS_OUTPUT"
+else
+    PS_CMD="${CC_MULTI_VENDOR_PS:-ps -eo comm=}"
+    PS_LIST="$($PS_CMD 2>/dev/null)"
+fi
+
+[ -z "$PS_LIST" ] && exit 0
+
+# Match each candidate as a whole basename token so "cursor-agent"
+# does not match unrelated names. We compare against the basename of
+# each process entry to tolerate full paths in some ps formats.
+FOUND=""
+while IFS= read -r raw; do
+    [ -z "$raw" ] && continue
+    name="${raw##*/}"          # basename
+    name="${name%% *}"          # strip args if present
+    for p in $PROCS; do
+        if [ "$name" = "$p" ]; then
+            case " $FOUND " in
+                *" $p "*) : ;;          # already recorded
+                *) FOUND="$FOUND $p" ;;
+            esac
+        fi
+    done
+done <<EOF
+$PS_LIST
+EOF
+
+FOUND="${FOUND# }"
+[ -z "$FOUND" ] && exit 0
+
+MSG="DETECTED: another AI coding CLI appears to be running alongside Claude Code: ${FOUND}.
+Running multiple AI tools against the same repository at once has two failure modes that neither tool can see on its own:
+  - Conflicting edits: two agents change the same file; one silently overwrites the other, or the repo lands half-edited.
+  - Combined cost is invisible: each vendor bills separately, so no single tool shows your total spend, and parallel runs multiply it.
+Operator-side mitigations:
+  1. Give each tool a disjoint scope (different directories or files) and commit frequently so collisions surface in git, not at runtime.
+  2. Track spend per vendor separately; assume the combined monthly cost, not any single tool's number.
+  3. Prefer a clear lead tool for edits and use the others for read-only review while both are live.
+This hook is advisory only — it does not read or stop the other tool. The session continues normally."
+
+if command -v jq > /dev/null 2>&1; then
+    jq -n --arg msg "$MSG" '
+    {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": $msg
+        }
+    }'
+else
+    echo "$MSG" >&2
+fi
+exit 0

package/examples/multi-window-auth-drift-detector.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+# multi-window-auth-drift-detector.sh — Detect on-disk credentials drift mid-session
+# (Cluster 19 candidate, axis 19E — multi-window /account state inconsistency)
+#
+# Background:
+#   Cluster 19 axis 19E documents a class of authentication failures unique to
+#   operators running multiple Claude Code windows in parallel. The structural
+#   shape: Window A authenticates with Account X and starts a long session.
+#   While Window A is mid-session, Window B either (a) logs in with Account Y,
+#   (b) logs out, or (c) re-authenticates — any action that rewrites the
+#   on-disk credential store. Window A keeps working from the cached in-memory
+#   token, but `/account` in Window A now reports "Not authenticated" while
+#   the same dialog's USAGE panel still shows real quota consumption.
+#
+#   Anchor case: #62790 — "/account shows 'Not authenticated' in older windows
+#   after another window logs in/out, while Usage bars still populate".
+#
+#   The contradiction is observable: same dialog, "Not authenticated" + live
+#   session quota bars. The operator does not know if their next substantive
+#   tool call will succeed or fail.
+#
+#   This hook is a PostToolUse advisory that fires when:
+#     - the credentials file has been modified since the session start, AND
+#     - the operator has not already seen the advisory in this session
+#
+#   The advisory does not block the tool call. It surfaces the drift so the
+#   operator can run /account, decide whether the in-memory auth is still the
+#   intended account, and re-auth deliberately if needed.
+#
+#   Reference:
+#     https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f (auth cluster field guide)
+#
+# Why a hook helps:
+#   Without the advisory, the failure mode is: Window A operator continues
+#   working, hits a 401 mid-task hours later, loses the in-flight work. With
+#   the advisory, the operator learns at the next tool call that the on-disk
+#   credentials have drifted, and can verify deliberately rather than discover
+#   the lapse during a costly task.
+#
+# When this hook does NOT emit anything:
+#   - CC_AUTH_DRIFT_DISABLE=1
+#   - CC_AUTH_DRIFT_QUIET=1
+#   - no credentials file exists at any known path
+#   - the credentials file mtime is older than the session start
+#   - the advisory has already fired in this session
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/multi-window-auth-drift-detector.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_AUTH_DRIFT_DISABLE=1          — never emit
+#   CC_AUTH_DRIFT_QUIET=1            — silent (process but never write to stderr)
+#   CC_AUTH_DRIFT_CRED_FILE=<path>   — credentials file path override (tests)
+#   CC_AUTH_DRIFT_SESSION_START=<ep> — session start epoch override (tests)
+#   CC_AUTH_DRIFT_STATE_DIR=<path>   — one-shot state dir override (default ~/.claude/state)
+#   CC_AUTH_DRIFT_SESSION_ID=<id>    — session id override (tests)
+#
+# Design notes:
+#   - Opt-out. The advisory is specific (credentials file changed since
+#     session start) and the cost of a missed advisory (silent 401 mid-task)
+#     exceeds the cost of a false positive (one stderr advisory the operator
+#     dismisses).
+#   - One-shot per session. The advisory fires once. Further drifts in the
+#     same session do not re-fire — the operator already knows.
+#   - Never blocks. Exit always 0. The auth recovery is operator-action.
+#   - Looks at multiple known credential file paths. The exact path varies
+#     across Claude Code versions and platforms; the hook checks each in
+#     order and uses the first that exists.
+
+set -u
+
+if [[ "${CC_AUTH_DRIFT_DISABLE:-0}" = "1" ]]; then
+    exit 0
+fi
+
+CRED_FILE="${CC_AUTH_DRIFT_CRED_FILE:-}"
+if [[ -z "$CRED_FILE" ]]; then
+    for candidate in \
+        "$HOME/.config/claude/auth.json" \
+        "$HOME/.config/anthropic/configs/default.json" \
+        "$HOME/.claude/credentials.json" \
+        "$HOME/.claude/.credentials.json"; do
+        if [[ -f "$candidate" ]]; then
+            CRED_FILE="$candidate"
+            break
+        fi
+    done
+fi
+
+if [[ -z "$CRED_FILE" ]] || [[ ! -f "$CRED_FILE" ]]; then
+    exit 0
+fi
+
+STATE_DIR="${CC_AUTH_DRIFT_STATE_DIR:-$HOME/.claude/state}"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+SESSION_ID="${CC_AUTH_DRIFT_SESSION_ID:-${CLAUDE_SESSION_ID:-default}}"
+GUARD_FILE="$STATE_DIR/auth-drift-${SESSION_ID}.fired"
+START_FILE="$STATE_DIR/auth-drift-${SESSION_ID}.start"
+
+if [[ -f "$GUARD_FILE" ]]; then
+    exit 0
+fi
+
+# Read or record session start epoch. The first hook firing of a session
+# records the start time; subsequent firings compare the credentials mtime
+# against it.
+SESSION_START="${CC_AUTH_DRIFT_SESSION_START:-}"
+if [[ -z "$SESSION_START" ]]; then
+    if [[ -f "$START_FILE" ]]; then
+        SESSION_START=$(cat "$START_FILE" 2>/dev/null)
+    fi
+    if [[ -z "$SESSION_START" ]] || ! [[ "$SESSION_START" =~ ^[0-9]+$ ]]; then
+        date +%s > "$START_FILE" 2>/dev/null
+        exit 0
+    fi
+fi
+
+# Get credentials file mtime in epoch seconds. Linux uses stat -c %Y;
+# macOS uses stat -f %m. Try both for portability.
+CRED_MTIME=$(stat -c %Y "$CRED_FILE" 2>/dev/null)
+if [[ -z "$CRED_MTIME" ]] || ! [[ "$CRED_MTIME" =~ ^[0-9]+$ ]]; then
+    CRED_MTIME=$(stat -f %m "$CRED_FILE" 2>/dev/null)
+fi
+if [[ -z "$CRED_MTIME" ]] || ! [[ "$CRED_MTIME" =~ ^[0-9]+$ ]]; then
+    exit 0
+fi
+
+# If credentials were not modified since the session started, no drift.
+if (( CRED_MTIME <= SESSION_START )); then
+    exit 0
+fi
+
+# Drift detected. Mark one-shot guard.
+touch "$GUARD_FILE" 2>/dev/null
+
+if [[ "${CC_AUTH_DRIFT_QUIET:-0}" = "1" ]]; then
+    exit 0
+fi
+
+GAP=$(( CRED_MTIME - SESSION_START ))
+
+cat >&2 <<EOF
+
+────────────────────────────────────────────────────────────────────
+  Auth advisory — Cluster 19 axis 19E (multi-window drift)
+────────────────────────────────────────────────────────────────────
+  Credentials file modified ${GAP}s after this session started:
+    ${CRED_FILE}
+
+  The Cluster 19 axis 19E pattern: when another Claude Code window
+  logs in/out or re-authenticates, this window's in-memory token may
+  silently diverge from on-disk state. /account in this window can
+  report "Not authenticated" while the USAGE quota bars still show
+  live consumption. The next substantive tool call may 401 mid-task.
+
+  Anchor case: #62790.
+
+  Recommended check before the next costly tool call:
+
+    /account
+
+  If "Auth method" reports "Not authenticated" but USAGE bars are
+  populated, the in-memory token is stale. Close all Claude Code
+  windows, then re-authenticate in a single window and start fresh
+  sessions — re-using the existing window will re-surface the drift.
+
+  Field guide: https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f
+
+  (This advisory fires once per session. To disable:
+   export CC_AUTH_DRIFT_DISABLE=1)
+────────────────────────────────────────────────────────────────────
+
+EOF
+
+exit 0

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