cc-safe-setup 29.7.0 → 30.0.4

package/examples/dispatch-allowlist-preflight.sh

@@ -0,0 +1,301 @@
+#!/bin/bash
+# ================================================================
+# dispatch-allowlist-preflight.sh — Pre-flight MCP tool allowlist
+#                                   propagation check for background
+#                                   sub-agent dispatches
+# ================================================================
+# PURPOSE:
+#   PreToolUse on Agent. When a sub-agent is dispatched with
+#   run_in_background=true and the dispatch prompt references one or
+#   more MCP tools (mcp__*), checks whether the parent's allowlist
+#   covers those tools and emits a loud warning (or refuses) when the
+#   known inheritance bug shape applies. Converts the silent stall
+#   into an observable signal *before* the sub-agent process hangs
+#   on the MCP permission gate with no UI surface.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+#
+# WHY THIS MATTERS:
+#   Issue #61315 (mitselek, 2026-05-21) reported a background sub-agent
+#   silently stalling on an MCP permission gate. The sub-agent process
+#   stays alive, recognizes the permission gate, but emits no
+#   notification, no log line, no error. The parent CLI receives no
+#   permission prompt. The PO has no surface to approve. Two observed
+#   stalls: 28 min (Session 10, never recovered, sub-agent dropped)
+#   and 58 min (Session 11, recovered only when an unrelated PO action
+#   surfaced a different pending permission, which unblocked the
+#   sub-agent).
+#
+#   Root cause: the parent's allowlist (project-scoped
+#   .claude/settings.local.json or user-scoped ~/.claude/settings.json
+#   permissions.allow) does not propagate to sub-agents dispatched
+#   via the Agent tool with run_in_background=true. The structural
+#   parent is recognition-without-arrest (#60226): the permission
+#   gate fires inside the sub-agent (recognition), but the parent's
+#   expectation of progress is not arrested (no UI surface, no idle
+#   signal). The cluster: #61315, #32402 (Write tool variant), #38859
+#   (Bash + bypassPermissions variant), #47339 (enhancement request),
+#   #51288 (root-cause umbrella), #56686 (Read path variant).
+#
+#   This hook moves the failure mode from silent stall to loud
+#   refusal (or warning) at the dispatch boundary. Sibling of
+#   dispatch-receipt.sh (#61167 phantom-agent prevention) and
+#   post-edit-disk-verify.sh (#61303 silent persist failure).
+#
+# WHAT IT CHECKS:
+#   1. tool_input is an Agent dispatch with subagent_type and prompt
+#   2. tool_input contains run_in_background=true (heuristic check;
+#      foreground dispatches are not vulnerable to the silent-stall
+#      shape because the user sees the parent CLI directly)
+#   3. The prompt references at least one MCP tool (regex: mcp__*)
+#   4. The parent's allowlist (project + user settings) covers each
+#      referenced MCP tool
+#
+# DECISION:
+#   - If no MCP tools referenced: exit 0 (no risk).
+#   - If MCP tools referenced AND not in parent's allowlist: warn
+#     loudly to stderr (the dispatch would stall on the permission
+#     gate even at the parent scope; in strict mode, refuse).
+#   - If MCP tools referenced AND in parent's allowlist: warn that
+#     the parent's allowlist does NOT propagate to the sub-agent
+#     (the known #61315 inheritance bug shape), and document the
+#     mitigation paths.
+#
+# OUTPUT:
+#   Receipt JSONL at ${CC_DISPATCH_RECEIPT_DIR:-~/.claude/receipts}/
+#   dispatch-preflight-YYYY-MM-DD.jsonl with:
+#     ts, subagent_type, prompt_hash, prompt_length,
+#     mcp_tools_referenced, parent_allowlist_coverage, decision
+#
+# CONFIGURATION:
+#   CC_DISPATCH_PREFLIGHT_MODE — one of:
+#     "warn" (default): exit 0, warn to stderr
+#     "refuse":         exit 2 when MCP tools referenced (loud refusal)
+#     "off":            exit 0, no warnings, only writes receipt
+#
+#   CC_DISPATCH_RECEIPT_DIR — override the receipt directory
+#     (default: ~/.claude/receipts)
+#
+#   CC_PROJECT_SETTINGS_PATH — override the project-scoped settings
+#     path (default: ${CLAUDE_PROJECT_DIR:-${PWD}}/.claude/
+#     settings.local.json)
+#
+#   CC_USER_SETTINGS_PATH — override the user-scoped settings path
+#     (default: ${HOME}/.claude/settings.json)
+#
+# AUDIT QUERY:
+#   To find all dispatches that hit the inheritance-bug shape over
+#   the last 7 days:
+#     find ~/.claude/receipts -name 'dispatch-preflight-*.jsonl' \
+#       -mtime -7 -exec cat {} \; | \
+#       jq -c 'select(.mcp_tools_referenced | length > 0)'
+#
+#   To correlate stalled sub-agents with their dispatch receipts,
+#   join on (ts, subagent_type, prompt_hash) against session
+#   transcripts.
+#
+# RELATED:
+#   https://github.com/anthropics/claude-code/issues/61315
+#   https://github.com/anthropics/claude-code/issues/32402
+#   https://github.com/anthropics/claude-code/issues/38859
+#   https://github.com/anthropics/claude-code/issues/47339
+#   https://github.com/anthropics/claude-code/issues/51288
+#   https://github.com/anthropics/claude-code/issues/56686
+#   https://github.com/anthropics/claude-code/issues/60226
+#   https://gist.github.com/yurukusa/8c0d19d59730868672270e7312492d1d
+#   (Receipt-Persistence Layer architecture)
+# ================================================================
+
+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-dispatch-allowlist-preflight-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [dispatch-allowlist-preflight]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+# Parse dispatch payload. Tolerate missing fields — a Task call with
+# no subagent_type or no prompt is malformed upstream; refusing here
+# would create false-positive friction without audit value.
+SUBAGENT_TYPE=$(printf '%s' "$INPUT" | jq -r '.tool_input.subagent_type // empty' 2>/dev/null)
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
+RUN_BG=$(printf '%s' "$INPUT" | jq -r '.tool_input.run_in_background // false' 2>/dev/null)
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+if [ -z "$SUBAGENT_TYPE" ] && [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+# Default subagent_type when omitted (Claude Code uses general-purpose).
+[ -z "$SUBAGENT_TYPE" ] && SUBAGENT_TYPE="general-purpose"
+
+MODE="${CC_DISPATCH_PREFLIGHT_MODE:-warn}"
+
+# Extract MCP tool references from the prompt.
+# Pattern: mcp__<server>__<tool> — server and tool both alphanumeric/_/-
+# Use grep with -oE; the regex is conservative to avoid false matches
+# against code snippets that contain mcp__ in non-tool contexts.
+MCP_REFS=$(printf '%s' "$PROMPT" | grep -oE 'mcp__[a-zA-Z0-9_-]+(__[a-zA-Z0-9_-]+)?' 2>/dev/null | sort -u)
+if [ -n "$MCP_REFS" ]; then
+    MCP_REF_COUNT=$(printf '%s\n' "$MCP_REFS" | grep -c '.')
+else
+    MCP_REF_COUNT=0
+fi
+
+# Compute prompt hash and length (PHI-safe: never store the prompt).
+PROMPT_LEN=$(printf '%s' "$PROMPT" | wc -c | tr -d ' ')
+PROMPT_HASH=$(printf '%s' "$PROMPT" | sha256sum 2>/dev/null | awk '{print $1}')
+[ -z "$PROMPT_HASH" ] && PROMPT_HASH="$(printf '%s' "$PROMPT" | shasum -a 256 2>/dev/null | awk '{print $1}')"
+
+# Schema v2 — read the operator's verbatim UserPromptSubmit text from the
+# companion log written by examples/userprompt-submit-receipt.sh, if any.
+# This lets the receipt corpus answer MAST 2.6 (Action-Reasoning Mismatch)
+# operationally — the executed argv vs the operator's articulated scope
+# at the prompt boundary — distinct from the LLM-judge labelled definition
+# of reasoning-vs-action mismatch. The architecture rationale is at:
+#   https://github.com/anthropics/claude-code/issues/61102#issuecomment-4514215413
+# When the companion log is absent, the fields are written as null so the
+# corpus stays joinable on the rest of the schema.
+ARTICULATED_HASH_JSON="null"
+ARTICULATED_LEN_JSON="null"
+COMPANION_LOG="${CC_DISPATCH_RECEIPT_DIR:-${HOME}/.claude/receipts}/userprompt-submit-$(date +%Y-%m-%d).jsonl"
+if [ -f "$COMPANION_LOG" ]; then
+    # The companion writes one JSONL entry per UserPromptSubmit event.
+    # The most recent entry within the current session is the closest
+    # articulated scope for this dispatch.
+    LAST_USERPROMPT=$(tail -1 "$COMPANION_LOG" 2>/dev/null)
+    if [ -n "$LAST_USERPROMPT" ]; then
+        ART_HASH=$(printf '%s' "$LAST_USERPROMPT" | jq -r '.prompt_hash // empty' 2>/dev/null)
+        ART_LEN=$(printf '%s' "$LAST_USERPROMPT" | jq -r '.prompt_length // empty' 2>/dev/null)
+        [ -n "$ART_HASH" ] && ARTICULATED_HASH_JSON="\"$ART_HASH\""
+        [ -n "$ART_LEN" ] && ARTICULATED_LEN_JSON="$ART_LEN"
+    fi
+fi
+
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+TYPE_JSON=$(printf '%s' "$SUBAGENT_TYPE" | jq -Rs -c .)
+
+# Read parent's allowlist (project + user scopes).
+PROJ_SETTINGS="${CC_PROJECT_SETTINGS_PATH:-${CLAUDE_PROJECT_DIR:-${PWD}}/.claude/settings.local.json}"
+USER_SETTINGS="${CC_USER_SETTINGS_PATH:-${HOME}/.claude/settings.json}"
+
+read_allowlist() {
+    local file="$1"
+    [ -f "$file" ] || return
+    jq -r '.permissions.allow[]?' "$file" 2>/dev/null
+}
+
+PARENT_ALLOW=$( { read_allowlist "$PROJ_SETTINGS"; read_allowlist "$USER_SETTINGS"; } | sort -u)
+
+# Build per-tool coverage report.
+COVERAGE_JSON="[]"
+DECISION="execute"
+UNCOVERED_REFS=""
+COVERED_REFS=""
+
+if [ "$MCP_REF_COUNT" -gt 0 ] && [ -n "$MCP_REFS" ]; then
+    # Build coverage JSON: array of {tool, covered: bool}
+    COVERAGE_PARTS=""
+    while IFS= read -r ref; do
+        [ -z "$ref" ] && continue
+        # An allowlist entry matches if it equals the ref, OR if it's
+        # a prefix glob (rare in MCP context).
+        if printf '%s\n' "$PARENT_ALLOW" | grep -Fxq "$ref" 2>/dev/null; then
+            COVERED="true"
+            COVERED_REFS="${COVERED_REFS}${ref}\n"
+        else
+            COVERED="false"
+            UNCOVERED_REFS="${UNCOVERED_REFS}${ref}\n"
+        fi
+        REF_JSON=$(printf '%s' "$ref" | jq -Rs -c .)
+        COVERAGE_PARTS="${COVERAGE_PARTS}{\"tool\":${REF_JSON},\"parent_covered\":${COVERED}},"
+    done <<EOF
+$MCP_REFS
+EOF
+    COVERAGE_PARTS=$(printf '%s' "$COVERAGE_PARTS" | sed 's/,$//')
+    COVERAGE_JSON="[${COVERAGE_PARTS}]"
+fi
+
+# Build MCP refs JSON array.
+if [ "$MCP_REF_COUNT" -gt 0 ]; then
+    REFS_JSON=$(printf '%s' "$MCP_REFS" | jq -Rs -c 'split("\n") | map(select(length > 0))')
+else
+    REFS_JSON="[]"
+fi
+
+# Decision logic.
+# - off: no decision noise (still writes receipt)
+# - warn (default): warn but exit 0
+# - refuse: exit 2 when MCP refs found
+if [ "$MCP_REF_COUNT" -gt 0 ] && [ "$RUN_BG" = "true" ] && [ "$MODE" = "refuse" ]; then
+    DECISION="refuse"
+fi
+
+# Write receipt.
+RECEIPT_DIR="${CC_DISPATCH_RECEIPT_DIR:-${HOME}/.claude/receipts}"
+mkdir -p "$RECEIPT_DIR" 2>/dev/null
+RECEIPT_FILE="${RECEIPT_DIR}/dispatch-preflight-$(date +%Y-%m-%d).jsonl"
+
+printf '{"ts":"%s","subagent_type":%s,"run_in_background":%s,"prompt_hash":"%s","prompt_length":%s,"articulated_scope_hash":%s,"articulated_scope_length":%s,"mcp_tools_referenced":%s,"coverage":%s,"decision":"%s","schema_version":2}\n' \
+    "$TS" "$TYPE_JSON" "$RUN_BG" "$PROMPT_HASH" "$PROMPT_LEN" "$ARTICULATED_HASH_JSON" "$ARTICULATED_LEN_JSON" "$REFS_JSON" "$COVERAGE_JSON" "$DECISION" \
+    >> "$RECEIPT_FILE" 2>/dev/null
+
+# Emit warnings / refusal output.
+if [ "$MCP_REF_COUNT" -gt 0 ] && [ "$RUN_BG" = "true" ] && [ "$MODE" != "off" ]; then
+    if [ "$DECISION" = "refuse" ]; then
+        SEVERITY="BLOCKED"
+    else
+        SEVERITY="WARNING"
+    fi
+    {
+        printf '%s: dispatch-allowlist-preflight — background sub-agent dispatch references MCP tool(s).\n' "$SEVERITY"
+        printf '\n'
+        printf 'Sub-agent: %s (run_in_background=true)\n' "$SUBAGENT_TYPE"
+        printf 'MCP tool(s) referenced in prompt:\n'
+        printf '%s\n' "$MCP_REFS" | sed 's/^/  - /'
+        printf '\n'
+        if [ -n "$COVERED_REFS" ]; then
+            printf 'In parent allowlist (will NOT propagate to sub-agent — issue #61315):\n'
+            printf '%b' "$COVERED_REFS" | sed 's/^/  - /' | grep -v '^  - $' || true
+            printf '\n'
+        fi
+        if [ -n "$UNCOVERED_REFS" ]; then
+            printf 'NOT in parent allowlist (sub-agent will hit silent permission gate):\n'
+            printf '%b' "$UNCOVERED_REFS" | sed 's/^/  - /' | grep -v '^  - $' || true
+            printf '\n'
+        fi
+        printf 'Receipt: %s\n' "$RECEIPT_FILE"
+        printf '\n'
+        printf 'Why this matters: a background sub-agent that hits a permission gate stalls\n'
+        printf '  silently — no UI surface in the parent CLI, no idle notification, no log line.\n'
+        printf '  Observed stalls: 28 min (#61315 Session 10, dropped) and 58 min (Session 11).\n'
+        printf '\n'
+        printf 'Mitigations (in order of preference):\n'
+        printf '  1. Inline the MCP tool result into the parent and pass the result via prompt,\n'
+        printf '     instead of dispatching a sub-agent that needs the MCP tool itself.\n'
+        printf '  2. If the sub-agent must invoke the tool, dispatch it foreground (no\n'
+        printf '     run_in_background=true) so the permission prompt surfaces in the parent CLI.\n'
+        printf '  3. Establish a heartbeat contract: instruct the sub-agent to send a SendMessage\n'
+        printf '     ping within 60s of dispatch and every 5 min thereafter. The absence of a\n'
+        printf '     ping past the deadline is an observable stall signal.\n'
+        printf '\n'
+        printf 'Set CC_DISPATCH_PREFLIGHT_MODE=off to silence this warning (receipt is still written).\n'
+        printf 'Set CC_DISPATCH_PREFLIGHT_MODE=refuse to block dispatches that match this shape.\n'
+        printf 'Reference: https://github.com/anthropics/claude-code/issues/61315\n'
+    } >&2
+fi
+
+if [ "$DECISION" = "refuse" ]; then
+    exit 2
+fi
+
+exit 0

package/examples/dispatch-liveness-watchdog.sh

@@ -0,0 +1,216 @@
+#!/bin/bash
+# dispatch-liveness-watchdog.sh — Surface in-flight sub-agent dispatches that
+# have been running longer than a configurable threshold, so operators see
+# the hang before they have to kill the session at the OS level.
+#
+# Solves: #61405 ("Subagent delegation lacks timeout, monitoring, and abort
+# controls — caused 12+ hour session hang"). The harness has no built-in
+# timeout primitive for Agent-tool dispatches; this hook is the operator-
+# side proxy that surfaces the hang at the next UserPromptSubmit so the
+# operator has a visible signal rather than having to notice that nothing
+# is happening.
+#
+# This is *symptom surfacing*, not root cause fixing. The full repair (a
+# real timeout / abort primitive in the harness) has to land at the Agent-
+# tool layer. The hook just makes the symptom observable at a point the
+# operator already looks (the next prompt they type).
+#
+# Architecture:
+#   * PreToolUse  + matcher "Agent": writes a per-dispatch state file under
+#     ~/.claude/state/dispatch-watchdog/<session>/<unix-timestamp>-<rand>.
+#   * PostToolUse + matcher "Agent": removes the OLDEST state file in the
+#     session's directory (FIFO assumption — dispatches that complete in
+#     order have their state files retired in order; out-of-order completion
+#     simply causes the wrong file to be retired but the in-flight count
+#     stays accurate, which is what the advisory cares about).
+#   * UserPromptSubmit: lists state files older than the threshold and
+#     emits an advisory naming each (with elapsed wall-clock) so the
+#     operator sees the hang.
+#
+# Companion to:
+#   * #61102's PR #281 scope-expansion-receipt.sh (sub-pattern 4 defense)
+#   * #61315's PR #286 dispatch-allowlist-preflight.sh (sub-pattern 2 prevention)
+#   * #61107's PR #275 route-handler-body-emptiness-gate.sh (sub-pattern 1 defense)
+#
+# This hook addresses sub-pattern 3 (absence of observation and control) in
+# the four-sub-pattern decomposition documented at
+# https://gist.github.com/yurukusa/9857a9ed407696ba8483b354917ff161
+#
+# TRIGGER: PreToolUse, PostToolUse, UserPromptSubmit
+# MATCHER (for the two ToolUse events): "Agent"
+#
+# CONFIGURATION (environment variables):
+#   CC_DISPATCH_WATCHDOG_THRESHOLD_SEC   default 1800 (30 minutes)
+#   CC_DISPATCH_WATCHDOG_STATE_DIR       default ~/.claude/state/dispatch-watchdog
+#   CC_DISPATCH_WATCHDOG_DISABLE         "1" → skip entirely
+#   CC_DISPATCH_WATCHDOG_MODE            "strict" → exit 2 when stale
+#                                        dispatches are present (default:
+#                                        advisory / exit 0)
+#
+# USAGE (settings.json — three registrations of the same hook):
+#   {
+#     "hooks": {
+#       "PreToolUse": [{
+#         "matcher": "Agent",
+#         "hooks": [{ "type": "command", "command": "~/.claude/hooks/dispatch-liveness-watchdog.sh" }]
+#       }],
+#       "PostToolUse": [{
+#         "matcher": "Agent",
+#         "hooks": [{ "type": "command", "command": "~/.claude/hooks/dispatch-liveness-watchdog.sh" }]
+#       }],
+#       "UserPromptSubmit": [{
+#         "matcher": "",
+#         "hooks": [{ "type": "command", "command": "~/.claude/hooks/dispatch-liveness-watchdog.sh" }]
+#       }]
+#     }
+#   }
+
+set -uo pipefail
+
+# Read stdin first so the upstream writer never sees EPIPE/141, even when the
+# watchdog is disabled.
+# 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-dispatch-liveness-watchdog-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [dispatch-liveness-watchdog]: 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_DISPATCH_WATCHDOG_DISABLE:-0}" = "1" ] && exit 0
+[ -z "$INPUT" ] && exit 0
+
+# Identify which event we are servicing. Claude Code's hook input includes
+# hook_event_name in newer versions; we infer when it's not present.
+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_TOOL_INPUT=$(printf '%s' "$INPUT" | jq -r 'has("tool_input")' 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_TOOL_INPUT" = "true" ]; then
+        EVENT="PreToolUse"
+    elif [ "$HAS_PROMPT" = "true" ]; then
+        EVENT="UserPromptSubmit"
+    else
+        exit 0
+    fi
+fi
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // .session // "default"' 2>/dev/null)
+[ -z "$SESSION_ID" ] && SESSION_ID="default"
+# Sanitize session id for filesystem use (alnum + dash + underscore only).
+SESSION_ID=$(printf '%s' "$SESSION_ID" | tr -c 'A-Za-z0-9_-' '_' | head -c 64)
+
+STATE_ROOT="${CC_DISPATCH_WATCHDOG_STATE_DIR:-$HOME/.claude/state/dispatch-watchdog}"
+SESSION_DIR="$STATE_ROOT/$SESSION_ID"
+THRESHOLD="${CC_DISPATCH_WATCHDOG_THRESHOLD_SEC:-1800}"
+
+mkdir -p "$SESSION_DIR" 2>/dev/null || exit 0
+
+case "$EVENT" in
+    PreToolUse)
+        # Only track Agent dispatches.
+        if [ "$TOOL_NAME" != "Agent" ]; then
+            exit 0
+        fi
+        TS=$(date +%s)
+        # 6-byte random to disambiguate concurrent dispatches at the same second.
+        RAND=$(od -An -N6 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n' || echo "0000")
+        STATE_FILE="$SESSION_DIR/${TS}-${RAND}"
+        # Capture a short summary of the dispatch for the advisory.
+        SUMMARY=$(printf '%s' "$INPUT" | jq -r '
+            (.tool_input.subagent_type // "")
+            + " | "
+            + ((.tool_input.description // .tool_input.prompt // "")[0:120] | gsub("\n"; " "))
+        ' 2>/dev/null)
+        printf '%s\n' "${SUMMARY:-(no summary)}" > "$STATE_FILE" 2>/dev/null
+        exit 0
+        ;;
+    PostToolUse)
+        if [ "$TOOL_NAME" != "Agent" ]; then
+            exit 0
+        fi
+        # Remove the oldest state file for this session. FIFO assumption;
+        # see header comment.
+        OLDEST=$(ls -1tr "$SESSION_DIR" 2>/dev/null | head -1)
+        if [ -n "$OLDEST" ]; then
+            rm -f "$SESSION_DIR/$OLDEST" 2>/dev/null
+        fi
+        exit 0
+        ;;
+    UserPromptSubmit)
+        NOW=$(date +%s)
+        STALE_COUNT=0
+        # Build a list of stale dispatches.
+        STALE_LINES=""
+        if [ -d "$SESSION_DIR" ]; then
+            for f in "$SESSION_DIR"/*; do
+                [ -f "$f" ] || continue
+                BASENAME=$(basename "$f")
+                START_TS=${BASENAME%%-*}
+                # Skip if filename is not parseable as a timestamp.
+                case "$START_TS" in
+                    ''|*[!0-9]*) continue ;;
+                esac
+                ELAPSED=$((NOW - START_TS))
+                if [ "$ELAPSED" -ge "$THRESHOLD" ]; then
+                    STALE_COUNT=$((STALE_COUNT + 1))
+                    SUMMARY=$(head -c 200 "$f" 2>/dev/null | head -1)
+                    HUMAN_ELAPSED=$(printf '%dm %ds' $((ELAPSED / 60)) $((ELAPSED % 60)))
+                    STALE_LINES="${STALE_LINES}  - started ${HUMAN_ELAPSED} ago: ${SUMMARY:-(no summary)}"$'\n'
+                fi
+            done
+        fi
+
+        if [ "$STALE_COUNT" -eq 0 ]; then
+            exit 0
+        fi
+
+        HUMAN_THRESHOLD=$(printf '%dm' $((THRESHOLD / 60)))
+        {
+            echo "<system-reminder>"
+            echo "STALE SUB-AGENT DISPATCH(ES) — ${STALE_COUNT} Agent-tool dispatch(es)"
+            echo "have been running longer than the watchdog threshold (${HUMAN_THRESHOLD})"
+            echo "without a corresponding PostToolUse signal:"
+            echo ""
+            printf '%s' "$STALE_LINES"
+            echo ""
+            echo "Sub-agent dispatches in Claude Code have no built-in timeout, monitoring,"
+            echo "or abort affordance (anthropics/claude-code#61405). The harness will wait"
+            echo "indefinitely for the dispatch to return; a hung dispatch will block the"
+            echo "session until the operator force-kills it at the OS level."
+            echo ""
+            echo "Operator-side options:"
+            echo "  1. Wait, if the dispatch is plausibly still progressing."
+            echo "  2. Identify the OS-level process (\`ps\` / Task Manager) and SIGKILL it."
+            echo "     Note: this will lose in-flight state in the parent session too."
+            echo "  3. Adjust CC_DISPATCH_WATCHDOG_THRESHOLD_SEC if your normal dispatches"
+            echo "     legitimately run longer than ${HUMAN_THRESHOLD}."
+            echo ""
+            echo "To clear the watchdog state (after force-killing a hung dispatch):"
+            echo "  rm -f ${SESSION_DIR}/*"
+            echo ""
+            echo "To disable this watchdog entirely, set"
+            echo "CC_DISPATCH_WATCHDOG_DISABLE=1 in your environment."
+            echo "</system-reminder>"
+        } >&2
+
+        if [ "${CC_DISPATCH_WATCHDOG_MODE:-advisory}" = "strict" ]; then
+            exit 2
+        fi
+        exit 0
+        ;;
+    *)
+        exit 0
+        ;;
+esac