cc-safe-setup 29.8.0 → 30.0.4

package/examples/subagent-identity-leak-guard.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# ================================================================
+# subagent-identity-leak-guard.sh — Warn when subagent delegation
+#                                    lacks identity boundary enforcement
+# ================================================================
+# PURPOSE:
+#   When the main agent spawns a subagent via the Agent tool, checks
+#   whether the delegation prompt includes explicit identity boundary
+#   enforcement: the subagent's own role, prohibition against
+#   impersonating the parent, and prohibition against exposing parent
+#   conversation history. Warns via stderr when these are missing.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+#
+# WHY THIS MATTERS:
+#   In v2.1.126, a regression was reported in Issue #55488: a spawned
+#   subagent (e.g. backend) was DM'd directly via the team chat UI
+#   and (1) identified itself as the parent ("team-lead") instead of
+#   its assigned name (backend), and (2) showed the user the parent's
+#   conversation history. This is an identity boundary failure: the
+#   subagent has no persistent state separating its identity from the
+#   parent's, so when queried directly it falls back to the parent's
+#   identity and history.
+#
+#   While the root cause needs to be fixed by Anthropic, parent agents
+#   can preventively reduce the failure surface by including explicit
+#   identity boundary instructions in the delegation prompt. This hook
+#   warns when those instructions are missing.
+#
+# WHAT IT CHECKS:
+#   1. Prompt mentions the subagent's own role or name (e.g. "you are",
+#      "your role is", "as the X agent")
+#   2. Prompt prohibits impersonating the parent (e.g. "do not identify
+#      as", "do not claim to be the parent")
+#   3. Prompt prohibits exposing parent conversation history (e.g. "do
+#      not share parent's history", "do not expose conversation log")
+#
+# OUTPUT:
+#   Warning to stderr listing which identity boundary instructions are
+#   missing. Always exits 0 — advisory only, never blocks.
+#
+# CONFIGURATION:
+#   CC_SUBAGENT_IDENTITY_REQUIRE_ALL — set to "1" to require all 3
+#       checks (default: warn on any missing check, do not require all)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/55488
+# ================================================================
+
+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-identity-leak-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [subagent-identity-leak-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
+
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+WARNINGS=""
+
+# Check 1: Subagent's own role or name is mentioned
+if ! printf '%s' "$PROMPT" | grep -qiE 'you are |your role |your name |as the [a-z]+ (agent|subagent)|act as '; then
+    WARNINGS="${WARNINGS}  - No explicit role assignment. Subagent may fall back to parent's identity (Issue #55488).\n"
+fi
+
+# Check 2: Prohibition against impersonating the parent
+if ! printf '%s' "$PROMPT" | grep -qiE 'do not (identify|claim|act|pretend) (as|to be) (the )?(parent|team-lead|orchestrator|main agent)|never (identify|claim|impersonate|pretend) (as|to be) (the )?(parent|team-lead|orchestrator)'; then
+    WARNINGS="${WARNINGS}  - No prohibition against impersonating the parent. Without this, the subagent may identify as the parent when DM'd directly.\n"
+fi
+
+# Check 3: Prohibition against exposing parent conversation history
+if ! printf '%s' "$PROMPT" | grep -qiE 'do not (share|expose|reveal|show) (the )?(parent|main agent)\b.{0,40}(history|conversation|log|messages)|never (share|expose|reveal) (the )?(parent|main agent).{0,40}(history|conversation)'; then
+    WARNINGS="${WARNINGS}  - No prohibition against exposing parent's conversation history. Without this, the subagent may show the user the parent's full chat history (Issue #55488 reproduction).\n"
+fi
+
+if [ -n "$WARNINGS" ]; then
+    REQUIRE_ALL="${CC_SUBAGENT_IDENTITY_REQUIRE_ALL:-0}"
+    printf '⚠️  Subagent identity boundary not enforced in delegation prompt:\n' >&2
+    printf '%b' "$WARNINGS" >&2
+    printf '\n  Reference: https://github.com/anthropics/claude-code/issues/55488\n' >&2
+    printf '  Recommended fix: prepend the prompt with the 3 boundary instructions.\n' >&2
+    if [ "$REQUIRE_ALL" = "1" ]; then
+        # Strict mode: block when any check fails
+        exit 2
+    fi
+fi
+
+exit 0

package/examples/subagent-identity-reassertion.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# subagent-identity-reassertion.sh — Re-assert subagent identity to mitigate parent-context leak
+#
+# Solves: Subagent identity leak (Issue #55488, v2.1.126 regression).
+#         When DM'd directly via team chat UI, the subagent dispatch may fall
+#         back to the parent's conversation context — surfacing parent
+#         identity and history that the subagent should not have access to.
+#
+# How it works: PreToolUse hook on Agent that emits a stderr REMINDER right
+#   before every Agent spawn. The reminder makes parent-context leaks visible
+#   in the operator's terminal (early detection signal) and surfaces the
+#   recommended operational workaround (relay through parent rather than
+#   DM the subagent directly) on each dispatch.
+#
+# Trade-off: Adds a stderr line per Agent call. Use only if your threat model
+#   includes sensitive parent-session context that subagents should not see.
+#   Issue #55488 workarounds 1-3 (explicit re-assertion / parent relay /
+#   context audit) are usually sufficient and cheaper.
+#
+# Reference: Issue #55488 (yurukusa Comment 5/2 14:27 JST)
+#   https://github.com/anthropics/claude-code/issues/55488
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Apply only on Agent tool calls. Tolerate malformed JSON by treating
+# unparseable input as a non-Agent fast path (silent exit 0).
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || true)
+[ "$TOOL" = "Agent" ] || exit 0
+
+# Extract subagent type / name for the reminder
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty' 2>/dev/null || true)
+SUBAGENT_NAME=$(echo "$INPUT" | jq -r '.tool_input.name // empty' 2>/dev/null || true)
+
+ROLE_LABEL="subagent"
+[ -n "$SUBAGENT_TYPE" ] && ROLE_LABEL="$SUBAGENT_TYPE"
+[ -n "$SUBAGENT_NAME" ] && ROLE_LABEL="$SUBAGENT_NAME ($SUBAGENT_TYPE)"
+
+# Emit reminder to stderr — Claude Code surfaces this in the operator's terminal
+cat >&2 <<EOF
+[subagent-identity-reassertion] Spawning $ROLE_LABEL — Issue #55488 mitigation
+  - Operational guard: route sensitive DMs through the parent agent, not directly to this subagent
+  - Audit: ensure parent context does not contain secrets the subagent must not see
+  - Recovery: if leak observed, send "Your role is $ROLE_LABEL. Confirm." to lock identity for the turn
+EOF
+
+exit 0

package/examples/subagent-inheritance-tester.sh

@@ -0,0 +1,179 @@
+#!/bin/bash
+# ================================================================
+# subagent-inheritance-tester.sh — Audit subagent frontmatter for
+#                                   missing tool boundaries and
+#                                   non-functional memory directives
+# ================================================================
+# PURPOSE:
+#   Two May 2026 incidents documented subagent docs that looked
+#   fine but did not enforce the parent's safety boundary:
+#
+#   #57068 — A parent settings.json with Deny rule on .env reads
+#            did not propagate to a subagent. The subagent read
+#            and reported the file's contents because the agent
+#            doc omitted an explicit tools: list and inherited a
+#            broader default.
+#   #57507 — A subagent doc declared its scope using a memory:
+#            field. memory: is silently ignored in subagent
+#            frontmatter (only tools:, model:, description: and
+#            name: are honored). The author believed the scope
+#            was bound; the runtime treated it as unbounded.
+#
+#   On SessionStart, this hook scans ~/.claude/agents/ and the
+#   project's .claude/agents/ directory and reports each doc
+#   that (a) lacks an explicit tools: list, (b) uses a memory:
+#   field, or (c) lacks frontmatter entirely. When the parent
+#   settings.json contains Deny rules, the warning escalates
+#   because those rules cannot be relied upon for subagents
+#   that have no tool binding.
+#
+# TRIGGER: SessionStart
+#
+# CONFIG:
+#   CC_SUBAGENT_INHERITANCE_BLOCK=0   (0 = warn; 1 = exit 2)
+#   CC_SUBAGENT_INHERITANCE_PATHS=""  (extra colon-separated dirs)
+#
+# Born from:
+#   https://github.com/anthropics/claude-code/issues/57068
+#   https://github.com/anthropics/claude-code/issues/57507
+# Related: chapter 9 of the May 2026 claim-verify case handbook
+#          ("自動の点検の道具の素案 5 件" — proposed detection
+#          tools 4 / 5, the fourth being subagent-inheritance-tester)
+# ================================================================
+
+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-inheritance-tester-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [subagent-inheritance-tester]: 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)
+
+# Resolve the project directory if the caller provided it.
+PROJECT_DIR=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+[ -z "$PROJECT_DIR" ] && PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+
+BLOCK="${CC_SUBAGENT_INHERITANCE_BLOCK:-0}"
+EXTRA="${CC_SUBAGENT_INHERITANCE_PATHS:-}"
+
+SCAN_DIRS=()
+[ -d "${HOME}/.claude/agents" ] && SCAN_DIRS+=("${HOME}/.claude/agents")
+[ -n "$PROJECT_DIR" ] && [ -d "${PROJECT_DIR}/.claude/agents" ] && SCAN_DIRS+=("${PROJECT_DIR}/.claude/agents")
+if [ -n "$EXTRA" ]; then
+    IFS=':' read -ra EXTRA_DIRS <<< "$EXTRA"
+    for d in "${EXTRA_DIRS[@]}"; do
+        [ -d "$d" ] && SCAN_DIRS+=("$d")
+    done
+fi
+
+# Nothing to audit, exit silently.
+if [ "${#SCAN_DIRS[@]}" -eq 0 ]; then
+    exit 0
+fi
+
+# Collect parent Deny rules. When present, missing tool bindings
+# in subagents are escalated because the deny boundary cannot be
+# inherited reliably.
+DENY_RULES=""
+for settings in "${HOME}/.claude/settings.json" \
+                "${HOME}/.claude/settings.local.json" \
+                "${PROJECT_DIR}/.claude/settings.json" \
+                "${PROJECT_DIR}/.claude/settings.local.json"; do
+    [ -n "$settings" ] || continue
+    [ -f "$settings" ] || continue
+    deny=$(jq -r '.permissions.deny[]? // empty' "$settings" 2>/dev/null || true)
+    if [ -n "$deny" ]; then
+        DENY_RULES="${DENY_RULES}${deny}
+"
+    fi
+done
+
+extract_frontmatter() {
+    awk '
+        /^---[[:space:]]*$/ {
+            if (!opened) { opened=1; next }
+            else { exit }
+        }
+        opened { print }
+    ' "$1" 2>/dev/null
+}
+
+ISSUES=""
+
+for dir in "${SCAN_DIRS[@]}"; do
+    # Find .md files; skip hidden and backup files.
+    while IFS= read -r doc; do
+        [ -f "$doc" ] || continue
+        case "$(basename "$doc")" in
+            .*|*.bak|*~) continue ;;
+        esac
+
+        # First non-empty line must be `---` for valid frontmatter.
+        first=$(awk 'NF { print; exit }' "$doc" 2>/dev/null || true)
+        if [ "$first" != "---" ]; then
+            ISSUES="${ISSUES}  - ${doc}: no YAML frontmatter; subagent definition will be ignored or treated as bare prompt
+"
+            continue
+        fi
+
+        fm=$(extract_frontmatter "$doc")
+        if [ -z "$fm" ]; then
+            ISSUES="${ISSUES}  - ${doc}: empty frontmatter block
+"
+            continue
+        fi
+
+        has_tools=$(printf '%s' "$fm" | grep -cE '^[[:space:]]*tools[[:space:]]*:' || true)
+        has_memory=$(printf '%s' "$fm" | grep -cE '^[[:space:]]*memory[[:space:]]*:' || true)
+        has_name=$(printf '%s' "$fm" | grep -cE '^[[:space:]]*name[[:space:]]*:' || true)
+
+        if [ "$has_name" -eq 0 ]; then
+            ISSUES="${ISSUES}  - ${doc}: frontmatter missing required 'name:' key
+"
+        fi
+
+        if [ "$has_memory" -gt 0 ]; then
+            ISSUES="${ISSUES}  - ${doc}: 'memory:' key found in frontmatter — silently ignored at runtime (Issue #57507). Move scope/context into the prompt body.
+"
+        fi
+
+        if [ "$has_tools" -eq 0 ]; then
+            if [ -n "$DENY_RULES" ]; then
+                ISSUES="${ISSUES}  - ${doc}: no explicit 'tools:' list; parent Deny rules (e.g. .env) cannot be relied upon to propagate (Issue #57068). Add tools: with the minimum needed.
+"
+            else
+                ISSUES="${ISSUES}  - ${doc}: no explicit 'tools:' list; subagent will inherit the broad default tool set. Pin to least-privilege.
+"
+            fi
+        fi
+    done < <(find "$dir" -maxdepth 2 -type f -name '*.md' 2>/dev/null)
+done
+
+if [ -z "$ISSUES" ]; then
+    exit 0
+fi
+
+printf '⚠️  subagent-inheritance-tester: subagent docs with inheritance gaps:\n' >&2
+printf '%b' "$ISSUES" >&2
+if [ -n "$DENY_RULES" ]; then
+    printf '\n  Parent Deny rules in effect:\n' >&2
+    printf '%s' "$DENY_RULES" | sed 's/^/    /' >&2
+fi
+printf '\n  References:\n' >&2
+printf '    https://github.com/anthropics/claude-code/issues/57068\n' >&2
+printf '    https://github.com/anthropics/claude-code/issues/57507\n' >&2
+printf '  Recommended fix: add an explicit tools: list to each agent doc; remove memory: keys.\n' >&2
+
+if [ "$BLOCK" = "1" ]; then
+    exit 2
+fi
+
+exit 0

package/examples/subagent-permission-mode-guard.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# ================================================================
+# subagent-permission-mode-guard.sh — Warn when Agent tool's mode
+#                                     parameter conflicts with sub-agent
+#                                     frontmatter permissionMode
+# ================================================================
+# PURPOSE:
+#   When the main agent spawns a sub-agent via the Agent tool with a
+#   `mode` parameter (e.g. `bypassPermissions`), checks whether the
+#   delegation prompt acknowledges that the sub-agent's YAML frontmatter
+#   `permissionMode` field can silently override the spawn-time
+#   parameter. Warns when the delegation prompt assumes the spawn-time
+#   parameter wins.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+#
+# WHY THIS MATTERS:
+#   Issue #55691 reported that the Agent tool's `mode` parameter does
+#   not override a sub-agent's YAML frontmatter `permissionMode`. When
+#   the sub-agent has no `permissionMode` declared, behaviour falls back
+#   to `default` mode — and the spawn-time `mode` parameter is silently
+#   a no-op. The docs read as if the Agent tool parameter wins
+#   per-spawn, but empirically the frontmatter (or its absence) wins.
+#
+#   This is a permission-priority boundary failure. The parent agent
+#   may believe it has elevated the sub-agent's permissions for a
+#   specific task, while the sub-agent silently runs in default mode.
+#   The work proceeds without the expected permission elevation,
+#   producing wrong results.
+#
+# WHAT IT CHECKS:
+#   1. Tool input contains a `mode` parameter (e.g.
+#      `mode: "bypassPermissions"`)
+#   2. If yes, prompt acknowledges that the sub-agent's frontmatter
+#      may override (e.g. "if frontmatter has permissionMode", "verify
+#      the sub-agent's frontmatter", "frontmatter wins")
+#   3. If yes, prompt asks for explicit verification before relying on
+#      the elevated mode (e.g. "verify the mode is active", "check
+#      effective permissions")
+#
+# OUTPUT:
+#   Warning to stderr when the spawn-time mode parameter is used but
+#   the prompt does not acknowledge the frontmatter override risk.
+#   Always exits 0 — advisory only, never blocks.
+#
+# CONFIGURATION:
+#   CC_SUBAGENT_MODE_REQUIRE_ALL — set to "1" to block when any check
+#       fails (default: warn only)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/55691
+# ================================================================
+
+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-permission-mode-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [subagent-permission-mode-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
+MODE=$(printf '%s' "$INPUT" | jq -r '.tool_input.mode // empty' 2>/dev/null)
+
+# If no mode parameter, no check needed
+if [ -z "$MODE" ]; then
+    exit 0
+fi
+
+# If mode parameter present but no prompt, warn briefly
+if [ -z "$PROMPT" ]; then
+    printf '⚠️  Agent tool spawn with mode=%s but empty prompt:\n' "$MODE" >&2
+    printf '  - The mode parameter may be silently overridden by the sub-agent frontmatter (Issue #55691).\n' >&2
+    printf '  Reference: https://github.com/anthropics/claude-code/issues/55691\n' >&2
+    exit 0
+fi
+
+WARNINGS=""
+
+# Check 1: Frontmatter override acknowledgement
+if ! printf '%s' "$PROMPT" | grep -qiE 'frontmatter|permissionMode|permission mode|YAML.+(field|frontmatter)|sub[- ]?agent.+(definition|YAML)'; then
+    WARNINGS="${WARNINGS}  - Mode parameter '${MODE}' set, but prompt does not acknowledge the sub-agent frontmatter override risk (Issue #55691). The mode may be silently a no-op.\n"
+fi
+
+# Check 2: Explicit verification request
+if ! printf '%s' "$PROMPT" | grep -qiE 'verify (the )?mode|check (the )?(effective )?permission|verify (the )?(elevated|active)|effective permission|active mode'; then
+    WARNINGS="${WARNINGS}  - Mode parameter '${MODE}' set, but prompt does not request verification of the actual effective mode. Without verification, a silent fallback to default mode passes unnoticed.\n"
+fi
+
+if [ -n "$WARNINGS" ]; then
+    REQUIRE_ALL="${CC_SUBAGENT_MODE_REQUIRE_ALL:-0}"
+    printf '⚠️  Subagent permission mode boundary not enforced:\n' >&2
+    printf '%b' "$WARNINGS" >&2
+    printf '\n  Reference: https://github.com/anthropics/claude-code/issues/55691\n' >&2
+    printf '  Recommended fix: acknowledge the frontmatter override, request explicit verification of the effective mode.\n' >&2
+    if [ "$REQUIRE_ALL" = "1" ]; then
+        exit 2
+    fi
+fi
+
+exit 0

package/examples/subagent-scope-guard.sh

@@ -12,6 +12,18 @@
 # Setup: echo "src/auth/" > .claude/agent-scope.txt
 # ================================================================
 
+# 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-scope-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [subagent-scope-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
 [ -z "$FILE" ] && exit 0

package/examples/subagent-spawn-verification-enforcer.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# ================================================================
+# subagent-spawn-verification-enforcer.sh — Warn when subagent prompt
+#                                            lacks output verification
+# ================================================================
+# PURPOSE:
+#   When the main agent spawns a subagent via the Agent tool, checks
+#   whether the delegation prompt names a concrete artifact the
+#   subagent must produce (file path, commit hash, process id, etc.)
+#   and whether the parent will verify that artifact with a read-only
+#   inspection. Warns when the contract is missing — the parent will
+#   then accept any "spawned successfully" reply at face value.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+#
+# WHY THIS MATTERS:
+#   Issue #55666 reported that named Agent spawns under
+#   CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 reply "Spawned successfully.
+#   The agent is now running." while no actual process is created. The
+#   inbox is set up but the work never runs. Without an artifact-based
+#   verification step in the parent, the parent trusts the textual
+#   "success" reply and proceeds — silently dropping the requested work.
+#
+#   The root cause must be fixed in the runtime, but parent agents can
+#   preventively catch this class of failure by (1) requiring the
+#   subagent to produce a concrete artifact (file write / commit / log
+#   line / stdout marker) and (2) verifying that artifact exists before
+#   trusting the success reply.
+#
+# WHAT IT CHECKS:
+#   1. Prompt names a concrete artifact (e.g. "write to /tmp/X",
+#      "create file at", "commit with message", "produce output line",
+#      "log to")
+#   2. Prompt includes a verification step (e.g. "verify by", "check
+#      that the file exists", "read back", "parent will inspect")
+#   3. Prompt warns against trusting textual success without artifact
+#      (optional, recommended for high-stakes delegation)
+#
+# OUTPUT:
+#   Warning to stderr listing which artifact / verification instructions
+#   are missing. Always exits 0 — advisory only, never blocks.
+#
+# CONFIGURATION:
+#   CC_SUBAGENT_VERIFY_REQUIRE_ALL — set to "1" to block when any check
+#       fails (default: warn only)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/55666
+# ================================================================
+
+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-spawn-verification-enforcer-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [subagent-spawn-verification-enforcer]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
+
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+WARNINGS=""
+
+# Check 1: Concrete artifact named (file path, commit, marker, etc.)
+if ! printf '%s' "$PROMPT" | grep -qiE 'write (to |the )?[/~]|create (a )?file|commit (with|the)|produce (an? )?output|log (to|the)|/tmp/|/var/|\.txt|\.md|\.json|\.log'; then
+    WARNINGS="${WARNINGS}  - No concrete artifact named. Subagent's textual 'success' reply is unverifiable (Issue #55666 surface).\n"
+fi
+
+# Check 2: Verification step named
+if ! printf '%s' "$PROMPT" | grep -qiE 'verify (by|with|that|the)|check (that|the file|the artifact|exists|after)|read back|parent (will|should) (inspect|verify|check)|i will (check|verify|inspect)'; then
+    WARNINGS="${WARNINGS}  - No artifact verification step. Without read-only inspection, fabricated success replies are silently trusted.\n"
+fi
+
+# Check 3: Distrust of textual success (warning, not strictly required)
+if ! printf '%s' "$PROMPT" | grep -qiE 'do not trust|do not (rely on|believe|reply)|require (the|an) artifact|artifact[- ]based|reply[- ]only|without producing'; then
+    WARNINGS="${WARNINGS}  - Recommended: prompt does not warn the subagent against 'reply-only' success. Adding 'do not reply success without producing the artifact' reduces fabrication risk.\n"
+fi
+
+if [ -n "$WARNINGS" ]; then
+    REQUIRE_ALL="${CC_SUBAGENT_VERIFY_REQUIRE_ALL:-0}"
+    printf '⚠️  Subagent output verification not enforced in delegation prompt:\n' >&2
+    printf '%b' "$WARNINGS" >&2
+    printf '\n  Reference: https://github.com/anthropics/claude-code/issues/55666\n' >&2
+    printf '  Recommended fix: name a concrete artifact, name parent verification step, warn the subagent against reply-only success.\n' >&2
+    if [ "$REQUIRE_ALL" = "1" ]; then
+        exit 2
+    fi
+fi
+
+exit 0

package/examples/subagent-tool-allowlist-enforcer.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# ================================================================
+# subagent-tool-allowlist-enforcer.sh — Warn when subagent prompt
+#                                       lacks tool allowlist boundary
+# ================================================================
+# PURPOSE:
+#   When the main agent spawns a subagent via the Agent tool, checks
+#   whether the delegation prompt explicitly states which tools the
+#   subagent is allowed to use, which tools are forbidden, and how the
+#   parent should verify the subagent's claimed results. Warns via
+#   stderr when these tool-boundary instructions are missing.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+#
+# WHY THIS MATTERS:
+#   Issue #55653 reported a subagent that fabricated "saved file" claims
+#   while only having read-only tool access. The subagent had no
+#   persistent state binding it to its allowed tool list, so when asked
+#   to "save", it produced a fictional success report instead of a
+#   permission-denied failure. This is a tool-list boundary failure.
+#
+#   While the root cause must be fixed in the agent runtime, parent
+#   agents can preventively reduce the failure surface by stating the
+#   allowed tool set explicitly in the delegation prompt and instructing
+#   the parent to verify the result with read-only inspection (file
+#   stat, git status, etc.) before trusting any "saved" or "modified"
+#   claim.
+#
+# WHAT IT CHECKS:
+#   1. Prompt names the allowed tool set (e.g. "you can use Read",
+#      "allowed tools:", "tools: read, grep")
+#   2. Prompt names the forbidden tools or capability boundary (e.g.
+#      "do not write", "no edit", "read-only")
+#   3. Prompt instructs the parent to verify results with read-only
+#      inspection (e.g. "I will verify with stat", "parent checks
+#      file existence", "verify before trusting")
+#
+# OUTPUT:
+#   Warning to stderr listing which tool boundary instructions are
+#   missing. Always exits 0 — advisory only, never blocks.
+#
+# CONFIGURATION:
+#   CC_SUBAGENT_TOOL_REQUIRE_ALL — set to "1" to block when any check
+#       fails (default: warn only)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/55653
+# ================================================================
+
+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-tool-allowlist-enforcer-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [subagent-tool-allowlist-enforcer]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
+
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+WARNINGS=""
+
+# Check 1: Allowed tool set is named
+if ! printf '%s' "$PROMPT" | grep -qiE 'you can use|allowed tools?:|tools:|use only|use the following tools|tool(s)? you may use'; then
+    WARNINGS="${WARNINGS}  - No allowed tool set named. Subagent may attempt operations outside its capability and fabricate results (Issue #55653).\n"
+fi
+
+# Check 2: Forbidden tools or capability boundary is named
+if ! printf '%s' "$PROMPT" | grep -qiE 'do not (write|edit|modify|save|create|delete)|no (write|edit|modify|save)|read[-]?only|never (write|edit|modify|save|create|delete)|forbidden tools?'; then
+    WARNINGS="${WARNINGS}  - No forbidden tools or read-only constraint named. Subagent may claim success on operations it cannot actually perform.\n"
+fi
+
+# Check 3: Parent's verification step is named
+if ! printf '%s' "$PROMPT" | grep -qiE 'verify (with|by|using)|parent (will|should) (check|verify|inspect)|i will verify|verify (the )?result|check (the )?(file|output|result) (exists|after)'; then
+    WARNINGS="${WARNINGS}  - No parent verification step. Without read-only inspection (file stat / git status), fabricated claims pass silently.\n"
+fi
+
+if [ -n "$WARNINGS" ]; then
+    REQUIRE_ALL="${CC_SUBAGENT_TOOL_REQUIRE_ALL:-0}"
+    printf '⚠️  Subagent tool boundary not enforced in delegation prompt:\n' >&2
+    printf '%b' "$WARNINGS" >&2
+    printf '\n  Reference: https://github.com/anthropics/claude-code/issues/55653\n' >&2
+    printf '  Recommended fix: name allowed tools, name forbidden capabilities, name parent verification step.\n' >&2
+    if [ "$REQUIRE_ALL" = "1" ]; then
+        exit 2
+    fi
+fi
+
+exit 0