cc-safe-setup 29.6.37 → 29.6.39

package/examples/pre-compact-transcript-backup.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# ================================================================
+# pre-compact-transcript-backup.sh — Backup transcript before compaction
+# ================================================================
+# PURPOSE:
+#   Creates a full copy of the session transcript JSONL before
+#   compaction begins. If compaction fails (rate limit, API error),
+#   the original transcript is preserved and can be restored.
+#
+# TRIGGER: PreCompact
+# MATCHER: (none — PreCompact has no matcher)
+#
+# WHY THIS MATTERS:
+#   Compaction wipes message content from the JSONL transcript
+#   BEFORE the compaction API call succeeds. If the API call
+#   fails (e.g., rate limit), all original content is permanently
+#   lost — the transcript is left with thousands of empty messages
+#   and no compaction summary. This hook ensures a recoverable
+#   backup exists.
+#
+# WHAT IT DOES:
+#   1. Reads transcript_path from stdin JSON
+#   2. Copies the full JSONL file to a backup location
+#   3. Keeps last 3 backups per session to save disk space
+#
+# CONFIGURATION:
+#   CC_COMPACT_BACKUP_DIR — backup directory
+#     (default: ~/.claude/compact-backups)
+#   CC_COMPACT_BACKUP_KEEP — number of backups to keep (default: 3)
+#
+# RECOVERY:
+#   cp ~/.claude/compact-backups/<session-id>/latest.jsonl \
+#      ~/.claude/projects/<project>/sessions/<session>.jsonl
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/40352
+# ================================================================
+
+set -u
+
+INPUT=$(cat)
+
+BACKUP_DIR="${CC_COMPACT_BACKUP_DIR:-${HOME}/.claude/compact-backups}"
+KEEP="${CC_COMPACT_BACKUP_KEEP:-3}"
+
+# Get transcript path from hook input
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+    exit 0
+fi
+
+# Create backup
+BASENAME=$(basename "$TRANSCRIPT" .jsonl)
+DEST_DIR="${BACKUP_DIR}/${BASENAME}"
+mkdir -p "$DEST_DIR"
+
+TIMESTAMP=$(date -u +"%Y%m%d-%H%M%S")
+BACKUP_FILE="${DEST_DIR}/${TIMESTAMP}.jsonl"
+
+cp "$TRANSCRIPT" "$BACKUP_FILE" 2>/dev/null
+
+if [ -f "$BACKUP_FILE" ]; then
+    SIZE=$(du -sh "$BACKUP_FILE" 2>/dev/null | cut -f1)
+    printf 'Pre-compact backup: %s (%s)\n' "$BACKUP_FILE" "$SIZE" >&2
+
+    # Prune old backups
+    ls -1t "$DEST_DIR"/*.jsonl 2>/dev/null | tail -n +$((KEEP + 1)) | xargs rm -f 2>/dev/null
+fi
+
+exit 0

package/examples/prompt-usage-logger.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# ================================================================
+# prompt-usage-logger.sh — Log every prompt with timestamps
+# ================================================================
+# PURPOSE:
+#   Track when and what you send to Claude, so you can correlate
+#   prompts with token usage on the billing dashboard.
+#   Helps diagnose unexpectedly fast token consumption.
+#
+# TRIGGER: UserPromptSubmit
+# MATCHER: ""
+#
+# HOW IT WORKS:
+#   Reads the prompt from stdin JSON, truncates to first 100 chars,
+#   and appends a timestamped line to a log file.
+#   After a session, compare timestamps with your usage dashboard
+#   to identify which interactions consumed the most tokens.
+#
+# CONFIGURATION:
+#   CC_PROMPT_LOG=/tmp/claude-usage-log.txt  (default log path)
+#
+# OUTPUT:
+#   Passes through original input on stdout (required for
+#   UserPromptSubmit hooks).
+#
+# EXAMPLE LOG:
+#   12:34:56 prompt=Read the file src/main.ts and explain the error handling
+#   12:35:23 prompt=Fix the bug in the validateInput function
+#
+# SEE ALSO:
+#   cost-tracker.sh (PostToolUse-based cost estimation)
+#   daily-usage-tracker.sh (daily aggregation)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/41249
+#   https://github.com/anthropics/claude-code/issues/38335
+#   https://github.com/anthropics/claude-code/issues/16157
+# ================================================================
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+LOG_FILE="${CC_PROMPT_LOG:-/tmp/claude-usage-log.txt}"
+
+# Extract first 100 chars of the prompt
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.prompt | .[0:100]' 2>/dev/null || echo "(parse error)")
+
+# Append timestamped entry
+echo "$(date -u +%H:%M:%S) prompt=$PROMPT" >> "$LOG_FILE"
+
+# Pass through original input (required for UserPromptSubmit)
+printf '%s\n' "$INPUT"

package/examples/read-only-mode.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# read-only-mode.sh — Block all file modifications and destructive commands
+#
+# Solves: Claude Code making unauthorized changes during test-only or
+# audit-only tasks, even when CLAUDE.md says "no changes" (#41063)
+#
+# Why a hook instead of CLAUDE.md: CLAUDE.md instructions are advisory —
+# the model can ignore them under pressure (e.g., when it finds a bug
+# and instinctively wants to fix it). Hooks are enforced at the process
+# level and cannot be bypassed.
+#
+# Toggle: Set CLAUDE_READONLY=1 to enable, unset to disable
+#   export CLAUDE_READONLY=1   # enable read-only mode
+#   unset CLAUDE_READONLY      # disable
+#
+# Usage: Add to settings.json as a PreToolUse hook
+#
+# {
+#   "hooks": {
+#     "PreToolUse": [
+#       {
+#         "matcher": "Write|Edit|NotebookEdit",
+#         "hooks": [{ "type": "command", "command": "~/.claude/hooks/read-only-mode.sh" }]
+#       },
+#       {
+#         "matcher": "Bash",
+#         "hooks": [{ "type": "command", "command": "~/.claude/hooks/read-only-mode.sh" }]
+#       }
+#     ]
+#   }
+# }
+#
+# TRIGGER: PreToolUse  MATCHER: "Write|Edit|NotebookEdit|Bash"
+
+# Only active when CLAUDE_READONLY=1
+[[ "${CLAUDE_READONLY:-}" != "1" ]] && exit 0
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+# Block all file write tools
+case "$TOOL" in
+    Write|Edit|NotebookEdit)
+        echo "BLOCKED: Read-only mode is active. Document this in your report instead of modifying files." >&2
+        exit 2
+        ;;
+esac
+
+# For Bash, block destructive commands but allow reads
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[[ -z "$CMD" ]] && exit 0
+
+# Allow read-only commands
+if echo "$CMD" | grep -qE '^\s*(ls|cat|head|tail|less|more|wc|find|grep|rg|ag|git\s+(log|show|diff|status|branch)|pwd|echo|printf|date|whoami|env|which|type|file|stat|du|df|uname|hostname|id|test|true|false|\[)'; then
+    exit 0
+fi
+
+# Block database mutations
+if echo "$CMD" | grep -qiE '\b(ALTER|DROP|TRUNCATE|INSERT|UPDATE|DELETE|CREATE|GRANT|REVOKE)\b'; then
+    echo "BLOCKED: Read-only mode — database mutations are not allowed. Document the needed change in your report." >&2
+    exit 2
+fi
+
+# Block Docker/service mutations
+if echo "$CMD" | grep -qiE 'docker\s+(restart|stop|rm|build|compose\s+up)|systemctl\s+(start|stop|restart|enable|disable)|service\s+\S+\s+(start|stop|restart)'; then
+    echo "BLOCKED: Read-only mode — service mutations are not allowed. Document the needed change in your report." >&2
+    exit 2
+fi
+
+# Block file writes via shell
+if echo "$CMD" | grep -qE '(>\s|>>|tee\s|mv\s|cp\s|rm\s|mkdir\s|rmdir\s|chmod\s|chown\s|ln\s|touch\s|sed\s+-i|install\s|pip\s+install|npm\s+(install|publish|unpublish)|yarn\s+add|apt\s+install|brew\s+install)'; then
+    echo "BLOCKED: Read-only mode — file/package modifications are not allowed. Document what needs to change in your report." >&2
+    exit 2
+fi
+
+# Allow everything else (mostly read commands)
+exit 0

package/examples/replace-all-guard.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# ================================================================
+# replace-all-guard.sh — Warn when Edit uses replace_all: true
+# ================================================================
+# PURPOSE:
+#   The Edit tool's replace_all parameter replaces ALL occurrences
+#   of old_string in a file. This is extremely dangerous for data
+#   files where the same string appears in different contexts
+#   (e.g., column names, values, SQL). A single replace_all can
+#   corrupt dozens of lines in ways that are hard to detect.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit"
+#
+# WHY THIS MATTERS:
+#   Claude frequently uses replace_all as a shortcut instead of
+#   making targeted single-line edits. In code files this is
+#   usually safe, but in data/config/SQL files it causes silent
+#   corruption — correct values are overwritten along with the
+#   intended target.
+#
+# WHAT IT DOES:
+#   Checks if the Edit tool input has replace_all: true. If so,
+#   warns via stderr. In strict mode (CC_BLOCK_REPLACE_ALL=1),
+#   blocks the operation entirely.
+#
+# CONFIGURATION:
+#   CC_BLOCK_REPLACE_ALL=1 — block replace_all operations (default: warn only)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/41681
+# ================================================================
+
+set -u
+
+INPUT=$(cat)
+
+REPLACE_ALL=$(printf '%s' "$INPUT" | jq -r '.tool_input.replace_all // false' 2>/dev/null)
+
+if [ "$REPLACE_ALL" = "true" ]; then
+    FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // "unknown"' 2>/dev/null)
+    OLD=$(printf '%s' "$INPUT" | jq -r '.tool_input.old_string // "" | .[0:60]' 2>/dev/null)
+
+    if [ "${CC_BLOCK_REPLACE_ALL:-0}" = "1" ]; then
+        printf 'BLOCKED: replace_all=true on %s\n' "$FILE" >&2
+        printf 'Pattern: "%s"\n' "$OLD" >&2
+        printf 'replace_all replaces ALL occurrences. Use targeted single edits instead.\n' >&2
+        exit 2
+    fi
+
+    printf '\n⚠ replace_all=true detected on %s\n' "$FILE" >&2
+    printf '  Pattern: "%s"\n' "$OLD" >&2
+    printf '  This replaces ALL occurrences. Verify this is intentional.\n\n' >&2
+fi
+
+exit 0

package/examples/ripgrep-permission-fix.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# ================================================================
+# ripgrep-permission-fix.sh — Auto-fix ripgrep execute permission on start
+# ================================================================
+# PURPOSE:
+#   After Claude Code upgrades, the vendored ripgrep binary
+#   sometimes loses its execute permission (installed as 644
+#   instead of 755). This silently breaks custom commands,
+#   skills discovery, and file search. This hook auto-fixes
+#   the permission on every session start.
+#
+# TRIGGER: SessionStart
+# MATCHER: (none)
+#
+# WHY THIS MATTERS:
+#   Claude Code uses ripgrep internally to scan .claude/commands/
+#   and .claude/skills/ for .md files. Without execute permission,
+#   it silently returns empty results, making all custom commands
+#   and skills invisible. Multiple users hit this on v2.1.88/89.
+#
+# WHAT IT DOES:
+#   Finds the vendored ripgrep binary and adds +x if missing.
+#   No-op if ripgrep already has execute permission.
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/41933
+#   https://github.com/anthropics/claude-code/issues/41882
+#   https://github.com/anthropics/claude-code/issues/41243
+# ================================================================
+
+# Find the Claude Code installation directory
+CLAUDE_BIN=$(command -v claude 2>/dev/null)
+[ -z "$CLAUDE_BIN" ] && exit 0
+
+# Resolve symlinks to find the actual installation
+CLAUDE_REAL=$(readlink -f "$CLAUDE_BIN" 2>/dev/null || realpath "$CLAUDE_BIN" 2>/dev/null)
+[ -z "$CLAUDE_REAL" ] && exit 0
+
+CLAUDE_DIR=$(dirname "$CLAUDE_REAL")
+
+# Search for vendored ripgrep
+for rg_path in \
+    "${CLAUDE_DIR}/../vendor/ripgrep/"*/rg \
+    "${CLAUDE_DIR}/../lib/node_modules/@anthropic-ai/claude-code/vendor/ripgrep/"*/rg \
+    "$(npm root -g 2>/dev/null)/@anthropic-ai/claude-code/vendor/ripgrep/"*/rg; do
+
+    # Expand glob
+    for rg in $rg_path; do
+        [ -f "$rg" ] || continue
+
+        if [ ! -x "$rg" ]; then
+            chmod +x "$rg" 2>/dev/null
+            printf 'Fixed ripgrep permission: %s\n' "$rg" >&2
+        fi
+    done
+done
+
+exit 0

package/examples/session-backup-on-start.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# ================================================================
+# session-backup-on-start.sh — Backup session JSONL files on start
+# ================================================================
+# PURPOSE:
+#   Creates a timestamped backup of all session JSONL files when
+#   a new session starts. Protects against silent deletion of
+#   session data by the desktop app or unexpected corruption.
+#
+# TRIGGER: SessionStart
+# MATCHER: (none — SessionStart has no matcher)
+#
+# WHY THIS MATTERS:
+#   The Claude Code desktop app has been observed silently deleting
+#   session JSONL files while leaving subagent directories intact.
+#   Without backups, entire conversation histories are lost with
+#   no way to recover them.
+#
+# WHAT IT DOES:
+#   1. Finds the project session directory
+#   2. Copies all .jsonl files to a timestamped backup directory
+#   3. Keeps only the last 5 backups to avoid disk bloat
+#
+# CONFIGURATION:
+#   CC_SESSION_BACKUP_DIR — backup location (default: ~/.claude/session-backups)
+#   CC_SESSION_BACKUP_KEEP — number of backups to keep (default: 5)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/41874
+# ================================================================
+
+set -u
+
+BACKUP_DIR="${CC_SESSION_BACKUP_DIR:-${HOME}/.claude/session-backups}"
+KEEP="${CC_SESSION_BACKUP_KEEP:-5}"
+
+# Find the current project's session directory
+CWD=$(pwd)
+PROJECT_NAME=$(printf '%s' "$CWD" | sed 's|/|-|g; s|^-||')
+SESSION_DIR="${HOME}/.claude/projects/${PROJECT_NAME}"
+
+if [ ! -d "$SESSION_DIR" ]; then
+    exit 0
+fi
+
+# Check if there are JSONL files to back up
+JSONL_COUNT=$(find "$SESSION_DIR" -maxdepth 1 -name "*.jsonl" -type f 2>/dev/null | wc -l)
+if [ "$JSONL_COUNT" -eq 0 ]; then
+    exit 0
+fi
+
+# Create timestamped backup
+TIMESTAMP=$(date -u +"%Y%m%d-%H%M%S")
+DEST="${BACKUP_DIR}/${PROJECT_NAME}/${TIMESTAMP}"
+mkdir -p "$DEST"
+
+# Copy JSONL files (not subdirectories — those are subagent sessions)
+cp "$SESSION_DIR"/*.jsonl "$DEST/" 2>/dev/null
+
+BACKED_UP=$(find "$DEST" -name "*.jsonl" -type f 2>/dev/null | wc -l)
+
+# Prune old backups (keep last N)
+PARENT="${BACKUP_DIR}/${PROJECT_NAME}"
+if [ -d "$PARENT" ]; then
+    ls -1dt "$PARENT"/*/ 2>/dev/null | tail -n +$((KEEP + 1)) | xargs rm -rf 2>/dev/null
+fi
+
+if [ "$BACKED_UP" -gt 0 ]; then
+    printf 'Session backup: %d JSONL files saved to %s\n' "$BACKED_UP" "$DEST" >&2
+fi
+
+exit 0

package/examples/session-index-repair.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# ================================================================
+# session-index-repair.sh — Rebuild sessions-index.json on exit
+# ================================================================
+# PURPOSE:
+#   Fixes stale/missing sessions-index.json files that cause
+#   `claude --resume` to show old or missing sessions. Runs on
+#   session Stop to rebuild the index from actual JSONL files.
+#
+# TRIGGER: Stop
+# MATCHER: (none — Stop has no matcher)
+#
+# WHY THIS MATTERS:
+#   Claude Code writes session data to JSONL files but sometimes
+#   fails to update sessions-index.json. Without the index,
+#   `claude --resume` can't find recent sessions. This hook
+#   scans for JSONL files and rebuilds the index.
+#
+# OUTPUT:
+#   Updated sessions-index.json in the current project directory.
+#   Status message to stderr.
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/25032
+# ================================================================
+
+set -u
+
+# Find the project sessions directory
+PROJECT_DIR="${HOME}/.claude/projects"
+
+if [ ! -d "$PROJECT_DIR" ]; then
+    exit 0
+fi
+
+# Get current working directory's project hash
+# Claude Code uses the cwd path (with slashes replaced by dashes) as the project dir name
+CWD=$(pwd)
+# Convert path to Claude's project directory naming scheme
+PROJECT_NAME=$(printf '%s' "$CWD" | sed 's|/|-|g; s|^-||')
+SESSION_DIR="${PROJECT_DIR}/${PROJECT_NAME}"
+
+if [ ! -d "$SESSION_DIR" ]; then
+    exit 0
+fi
+
+INDEX_FILE="${SESSION_DIR}/sessions-index.json"
+
+# Build index from JSONL files
+ENTRIES="["
+FIRST=true
+
+for jsonl in "${SESSION_DIR}"/*.jsonl; do
+    [ -f "$jsonl" ] || continue
+
+    # Extract session info from the JSONL filename and content
+    BASENAME=$(basename "$jsonl")
+    MTIME=$(stat -c '%Y' "$jsonl" 2>/dev/null || stat -f '%m' "$jsonl" 2>/dev/null)
+
+    # Try to get the session title from custom-title entries
+    TITLE=$(grep -o '"type":"custom-title","title":"[^"]*"' "$jsonl" 2>/dev/null | tail -1 | sed 's/.*"title":"//; s/"//')
+    if [ -z "$TITLE" ]; then
+        # Fallback: use first user message as title
+        TITLE=$(head -20 "$jsonl" | grep -o '"role":"user"' -m1 >/dev/null && head -20 "$jsonl" | jq -r 'select(.message.role == "user") | .message.content | .[0:60]' 2>/dev/null | head -1)
+    fi
+    [ -z "$TITLE" ] && TITLE="(untitled)"
+
+    if [ "$FIRST" = true ]; then
+        FIRST=false
+    else
+        ENTRIES="${ENTRIES},"
+    fi
+
+    ENTRIES="${ENTRIES}{\"file\":\"${BASENAME}\",\"title\":\"${TITLE}\",\"mtime\":${MTIME:-0}}"
+done
+
+ENTRIES="${ENTRIES}]"
+
+# Write the index
+printf '%s' "$ENTRIES" | jq '.' > "$INDEX_FILE" 2>/dev/null
+
+if [ -f "$INDEX_FILE" ]; then
+    COUNT=$(printf '%s' "$ENTRIES" | jq 'length' 2>/dev/null)
+    printf 'sessions-index.json rebuilt: %s sessions indexed\n' "${COUNT:-0}" >&2
+fi
+
+exit 0

package/examples/subagent-error-detector.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# ================================================================
+# subagent-error-detector.sh — Detect failed subagent results
+# ================================================================
+# PURPOSE:
+#   When a subagent returns, checks whether the result contains
+#   API error indicators (529 Overloaded, 500 Internal, timeout).
+#   Warns via stderr so the main agent doesn't silently accept
+#   error results as valid work.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Agent"
+#
+# WHY THIS MATTERS:
+#   API 529 "Overloaded" errors silently kill parallel subagents.
+#   The agent reports "completion" but the result is just an error
+#   string. Without detection, the main agent accepts the error
+#   as a valid response and continues — losing all subagent work.
+#
+# WHAT IT CHECKS:
+#   - 529 Overloaded errors
+#   - 500/502/503 API errors
+#   - Timeout indicators
+#   - Empty or suspiciously short results
+#
+# OUTPUT:
+#   Warning to stderr when subagent result looks like an error.
+#   Always exits 0 — advisory only.
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/41911
+# ================================================================
+
+set -u
+
+INPUT=$(cat)
+
+# Extract the tool result (subagent's returned output)
+RESULT=$(printf '%s' "$INPUT" | jq -r '.tool_result // empty' 2>/dev/null)
+
+if [ -z "$RESULT" ]; then
+    exit 0
+fi
+
+WARNINGS=""
+
+# Check for API error patterns
+if printf '%s' "$RESULT" | grep -qiE '529.*overloaded|overloaded_error'; then
+    WARNINGS="${WARNINGS}  - ⛔ 529 Overloaded error detected — subagent hit API rate limit\n"
+fi
+
+if printf '%s' "$RESULT" | grep -qiE '500 Internal|502 Bad Gateway|503 Service Unavailable'; then
+    WARNINGS="${WARNINGS}  - ⛔ Server error detected in subagent result\n"
+fi
+
+if printf '%s' "$RESULT" | grep -qiE 'timeout|timed out|ETIMEDOUT|ECONNRESET'; then
+    WARNINGS="${WARNINGS}  - ⚠ Timeout detected in subagent result\n"
+fi
+
+# Check for suspiciously short results (< 50 chars often means error)
+RESULT_LEN=${#RESULT}
+if [ "$RESULT_LEN" -lt 50 ]; then
+    WARNINGS="${WARNINGS}  - ⚠ Subagent result is only ${RESULT_LEN} chars — may be an error, not real work\n"
+fi
+
+if [ -n "$WARNINGS" ]; then
+    printf '\n⚠ Subagent result quality check:\n' >&2
+    printf '%b' "$WARNINGS" >&2
+    printf 'The subagent may have failed. Verify the result before using it.\n' >&2
+    printf 'Consider re-running the subagent or doing the work directly.\n\n' >&2
+fi
+
+exit 0

package/examples/subagent-scope-validator.sh

@@ -1,49 +1,73 @@
 #!/bin/bash
-# subagent-scope-validator.sh — Validate subagent task scope before launch
-#
-# Solves: Main agent's subagent delegation produces poor scoping (#40339).
-#         Subagents are launched with vague prompts, missing context,
-#         and no result verification criteria.
-#
-# How it works: PreToolUse hook on "Agent" that checks the prompt
-#   for minimum scope requirements:
-#   1. Prompt must be longer than 50 characters (not just "do X")
-#   2. Must contain file paths or specific identifiers
-#   3. Warns if no success criteria are mentioned
+# ================================================================
+# subagent-scope-validator.sh — Warn on vague subagent delegation
+# ================================================================
+# PURPOSE:
+#   When the main agent spawns a subagent, checks whether the
+#   delegation prompt includes sufficient context: file paths,
+#   specific questions, and adequate length. Warns via stderr
+#   when the delegation looks vague — the #1 cause of poor
+#   subagent results.
 #
 # TRIGGER: PreToolUse
 # MATCHER: "Agent"
+#
+# WHY THIS MATTERS:
+#   The main agent often delegates with vague prompts like
+#   "investigate the auth flow" instead of "read src/auth/login.ts
+#   lines 45-80 and trace how the JWT is validated." Vague prompts
+#   produce shallow, incorrect subagent results. This hook catches
+#   it before the subagent wastes a context window.
+#
+# WHAT IT CHECKS:
+#   1. Prompt length (< 100 chars is almost always too vague)
+#   2. Presence of file paths (subagents need specific files)
+#   3. Presence of actionable verbs (read, check, verify, find, grep)
+#
+# OUTPUT:
+#   Warning to stderr when delegation looks vague.
+#   Always exits 0 — advisory only, never blocks.
+#
+# CONFIGURATION:
+#   CC_SUBAGENT_MIN_PROMPT_LEN — minimum prompt length (default: 100)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/40339
+# ================================================================
+
+set -u
 
 INPUT=$(cat)
-TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
-[ "$TOOL" != "Agent" ] && exit 0
 
-PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
-[ -z "$PROMPT" ] && exit 0
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
 
-PROMPT_LEN=${#PROMPT}
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+MIN_LEN="${CC_SUBAGENT_MIN_PROMPT_LEN:-100}"
 WARNINGS=""
 
-# Check 1: Minimum prompt length
-if [ "$PROMPT_LEN" -lt 50 ]; then
-    WARNINGS="${WARNINGS}\n  - Prompt is only ${PROMPT_LEN} chars. Subagents need detailed context (50+ chars recommended)"
+# Check 1: Prompt length
+PROMPT_LEN=${#PROMPT}
+if [ "$PROMPT_LEN" -lt "$MIN_LEN" ]; then
+    WARNINGS="${WARNINGS}  - Prompt is only ${PROMPT_LEN} chars (minimum recommended: ${MIN_LEN})\n"
 fi
 
-# Check 2: Contains specific identifiers (files, functions, paths)
-if ! echo "$PROMPT" | grep -qE '/[a-zA-Z]|\.ts|\.py|\.js|\.md|\.json|\.sh|function |class |def |const |let |var '; then
-    WARNINGS="${WARNINGS}\n  - No file paths or code identifiers found. Subagent may lack context"
+# Check 2: File paths present?
+if ! printf '%s' "$PROMPT" | grep -qE '(/[a-zA-Z0-9_.-]+){2,}|\.[a-z]{1,4}\b|src/|lib/|test/|docs/'; then
+    WARNINGS="${WARNINGS}  - No file paths detected. Subagents need specific files to read.\n"
 fi
 
-# Check 3: Success criteria
-if ! echo "$PROMPT" | grep -qiE 'verify|confirm|test|check|ensure|must|should|expect|return|report'; then
-    WARNINGS="${WARNINGS}\n  - No success criteria detected. Consider adding verification steps"
+# Check 3: Actionable verbs?
+if ! printf '%s' "$PROMPT" | grep -qiE '\b(read|check|verify|find|grep|search|look at|examine|trace|compare|analyze)\b'; then
+    WARNINGS="${WARNINGS}  - No actionable verbs found. Tell the subagent exactly what to do.\n"
 fi
 
-# Output warnings (don't block — just inform)
 if [ -n "$WARNINGS" ]; then
-    echo "⚠ Subagent scope review:" >&2
-    echo -e "$WARNINGS" >&2
-    echo "  Prompt preview: $(echo "$PROMPT" | head -c 100)..." >&2
+    printf '\n⚠ Subagent delegation quality check:\n' >&2
+    printf '%b' "$WARNINGS" >&2
+    printf 'Tip: Include specific file paths, line ranges, and what a complete answer looks like.\n\n' >&2
 fi
 
 exit 0