cc-safe-setup 29.7.0 → 30.0.4

package/examples/settings-hooks-key-restorer.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# settings-hooks-key-restorer.sh — Detect silent loss of top-level `hooks` key in settings.json
+# Trigger: SessionStart
+# Matcher: (none — runs on every session start)
+#
+# Issue #59870 — when the user accepts a new permission, Claude Code rewrites
+# `~/.claude/settings.json` and silently drops the top-level `hooks` key.
+# Other top-level keys (`permissions`, `model`, etc.) are preserved.
+# Tools that register PreToolUse/PostToolUse/Stop hooks via settings.json
+# then "stop working" mid-session with no warning.
+#
+# This hook runs at SessionStart, compares the current settings.json against
+# the most recent backup, and warns if the `hooks` key has disappeared.
+# The hook does NOT auto-restore; auto-restoration risks reintroducing
+# stale or wrong hooks. Instead it prints the restoration command for
+# the user to verify and apply.
+#
+# Companion to settings-integrity-monitor.sh (which tracks hash-level changes
+# but does not specialize on the hooks-key disappearance pattern).
+#
+# TRIGGER: SessionStart  MATCHER: ""
+
+SETTINGS="${CLAUDE_SETTINGS_FILE:-$HOME/.claude/settings.json}"
+BACKUP_DIR="$HOME/.claude/settings-backups"
+
+# Exit silently if settings.json doesn't exist
+[ -f "$SETTINGS" ] || exit 0
+
+# Exit silently if no backups exist yet
+[ -d "$BACKUP_DIR" ] || exit 0
+
+# Exit silently if settings.json is malformed (a separate hook handles that)
+if ! jq -e . "$SETTINGS" >/dev/null 2>&1; then
+    exit 0
+fi
+
+# Check current settings.json has hooks key
+CURRENT_HAS_HOOKS=$(jq 'has("hooks")' "$SETTINGS" 2>/dev/null || echo "false")
+
+# If current still has hooks, nothing to do
+if [ "$CURRENT_HAS_HOOKS" = "true" ]; then
+    CURRENT_HOOK_COUNT=$(jq '[.hooks | to_entries[].value[].hooks[]?] | length' "$SETTINGS" 2>/dev/null || echo "0")
+    # Even if hooks key is present, warn if count is 0 (the key exists but has been emptied)
+    if [ "$CURRENT_HOOK_COUNT" = "0" ]; then
+        echo "⚠ settings.json has 'hooks' key but it is empty. If you registered hooks via settings.json, they may have been silently removed." >&2
+        echo "  See https://github.com/anthropics/claude-code/issues/59870 for the silent-drop pattern." >&2
+    fi
+    exit 0
+fi
+
+# Current does NOT have hooks key. Look at backups for the most recent one with hooks.
+LATEST_BACKUP=""
+if [ -f "$BACKUP_DIR/settings.json.latest" ]; then
+    LATEST_HAS_HOOKS=$(jq 'has("hooks")' "$BACKUP_DIR/settings.json.latest" 2>/dev/null || echo "false")
+    if [ "$LATEST_HAS_HOOKS" = "true" ]; then
+        LATEST_BACKUP="$BACKUP_DIR/settings.json.latest"
+    fi
+fi
+
+if [ -z "$LATEST_BACKUP" ] && [ -f "$BACKUP_DIR/settings.json.baseline" ]; then
+    BASELINE_HAS_HOOKS=$(jq 'has("hooks")' "$BACKUP_DIR/settings.json.baseline" 2>/dev/null || echo "false")
+    if [ "$BASELINE_HAS_HOOKS" = "true" ]; then
+        LATEST_BACKUP="$BACKUP_DIR/settings.json.baseline"
+    fi
+fi
+
+# If no backup with hooks exists, the user never had hooks in settings.json. Exit silently.
+if [ -z "$LATEST_BACKUP" ]; then
+    exit 0
+fi
+
+# Hooks were present in a prior backup but are now gone. Warn and suggest restoration.
+PRIOR_HOOK_COUNT=$(jq '[.hooks | to_entries[].value[].hooks[]?] | length' "$LATEST_BACKUP" 2>/dev/null || echo "?")
+
+cat >&2 <<EOF
+⚠ SILENT HOOKS LOSS DETECTED
+
+settings.json no longer contains the top-level 'hooks' key, but the most
+recent backup ($LATEST_BACKUP) had $PRIOR_HOOK_COUNT hook entries.
+
+This matches issue #59870: when Claude Code rewrites settings.json after a
+permission grant, it silently drops the top-level 'hooks' key. Other keys
+(permissions, model, etc.) are preserved.
+
+To restore the hooks key from the backup, run:
+
+  jq -s '.[0] + {hooks: .[1].hooks}' "$SETTINGS" "$LATEST_BACKUP" > /tmp/settings-restored.json && \\
+    mv /tmp/settings-restored.json "$SETTINGS"
+
+Then verify with:
+
+  jq '.hooks | keys' "$SETTINGS"
+
+If the restored hooks are stale, edit the backup file before running the merge.
+This hook does NOT auto-restore to avoid reintroducing wrong hooks.
+
+EOF
+
+exit 0

package/examples/settings-json-health-check.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# settings-json-health-check.sh — settings corruption guard (Incident 10)
+# Why: A malformed settings.json can silently break the session (hook
+#      definitions ignored, permissions reset to defaults) and the built-in
+#      /doctor diagnostic can be dismissed by the user, leaving no warning.
+#      This hook runs at SessionStart, validates both user-level and
+#      project-level settings.json as JSON, writes a dated backup if a file
+#      fails to parse, and exits non-zero so Claude Code refuses to proceed
+#      with a broken configuration.
+# Event: SessionStart
+# Action: jq parse both settings files. If either fails: backup + refuse.
+#         If /doctor has been dismissed recently: warn on stderr (does not
+#         refuse the session, only reminds the user).
+#
+# Environment:
+#   CC_SKIP_DOCTOR_CHECK=1        suppress the /doctor dismissed warning
+#   SETTINGS_HEALTH_USER_PATH     override (default ~/.claude/settings.json)
+#   SETTINGS_HEALTH_PROJECT_PATH  override (default ./.claude/settings.json)
+
+set -u
+
+USER_SETTINGS="${SETTINGS_HEALTH_USER_PATH:-${HOME}/.claude/settings.json}"
+PROJECT_SETTINGS="${SETTINGS_HEALTH_PROJECT_PATH:-./.claude/settings.json}"
+
+INPUT=$(cat 2>/dev/null)   # consume stdin if piped; SessionStart may or may not pipe
+
+backup_and_warn() {
+  local path="$1"
+  local backup="${path}.broken.$(date +%Y%m%d-%H%M%S)"
+  cp -p "$path" "$backup" 2>/dev/null && \
+    echo "⚠ settings-json-health-check: $path failed to parse, backup written to $backup" >&2
+  echo "  Fix or restore before continuing. Claude Code will not read a broken settings file." >&2
+}
+
+RC=0
+
+for path in "$USER_SETTINGS" "$PROJECT_SETTINGS"; do
+  if [ -s "$path" ]; then
+    if ! jq -e '.' "$path" >/dev/null 2>&1; then
+      backup_and_warn "$path"
+      RC=2
+    fi
+  fi
+done
+
+# Check for /doctor dismissal. Several CC versions record this in a sentinel
+# file at ~/.claude/doctor-dismissed.* — pattern varies, so we match any
+# file matching the prefix and warn if one was written in the last 30 days.
+if [ "${CC_SKIP_DOCTOR_CHECK:-0}" != "1" ]; then
+  DISMISSED=$(find "${HOME}/.claude" -maxdepth 2 -name 'doctor-dismissed*' -mtime -30 -print 2>/dev/null | head -1)
+  if [ -n "$DISMISSED" ]; then
+    echo "ℹ settings-json-health-check: /doctor diagnostic has been dismissed ($DISMISSED)" >&2
+    echo "  Run /doctor again to see current diagnostics, or set CC_SKIP_DOCTOR_CHECK=1 to silence this notice." >&2
+  fi
+fi
+
+exit "$RC"

package/examples/settings-regression-tester.sh

@@ -0,0 +1,188 @@
+#!/bin/bash
+# ================================================================
+# settings-regression-tester.sh — Detect Claude Code version
+#                                  bumps that may have silently
+#                                  reset permission rules
+# ================================================================
+# PURPOSE:
+#   Two May 2026 incidents documented permission-side regressions
+#   that surfaced only after a routine Claude Code version bump:
+#
+#   #57491 — After v2.1.128, Allow rules in settings.json that had
+#            been auto-approving for weeks (Bash(npm:*) and similar)
+#            began re-prompting on every invocation. The settings
+#            file was unchanged; the runtime's interpretation
+#            had drifted.
+#   #57486 — After the same bump, persistent memory: directives
+#            that had been auto-loaded on previous sessions stopped
+#            being referenced after auto-compaction. The user
+#            assumed the configuration was still in effect.
+#
+#   Both incidents share a structural cause: the user's settings
+#   were authored against version N, the runtime upgraded to N+1
+#   silently, and the settings interpretation drifted. The user
+#   has no signal that re-verification is needed.
+#
+#   On SessionStart, this hook records the current Claude Code
+#   version and a hash of settings.json. On subsequent sessions,
+#   if the version has changed since the last recorded run, it
+#   warns the operator to re-confirm that Allow rules and memory:
+#   directives still take effect as expected. State is kept under
+#   ~/.claude/version-state.json.
+#
+# TRIGGER: SessionStart
+#
+# CONFIG:
+#   CC_SETTINGS_REGRESSION_BLOCK=0   (0 = warn; 1 = exit 2)
+#   CC_SETTINGS_REGRESSION_STATE=""  (override state file path;
+#                                     default: ~/.claude/version-state.json)
+#
+# Born from:
+#   https://github.com/anthropics/claude-code/issues/57491
+#   https://github.com/anthropics/claude-code/issues/57486
+# Related: chapter 9 of the May 2026 claim-verify case handbook
+#          ("自動の点検の道具の素案 5 件" — proposed detection
+#          tools 5 / 5, the fifth being settings-regression-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-settings-regression-tester-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [settings-regression-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)
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+[ -z "$CWD" ] && CWD="${CLAUDE_PROJECT_DIR:-}"
+
+BLOCK="${CC_SETTINGS_REGRESSION_BLOCK:-0}"
+STATE_FILE="${CC_SETTINGS_REGRESSION_STATE:-${HOME}/.claude/version-state.json}"
+
+# Resolve `claude --version`. If unavailable (CI test, broken PATH),
+# fall back to environment override; on total failure exit silently.
+CURRENT_VERSION="${CC_SETTINGS_REGRESSION_VERSION_OVERRIDE:-}"
+if [ -z "$CURRENT_VERSION" ]; then
+    if command -v claude >/dev/null 2>&1; then
+        CURRENT_VERSION=$(claude --version 2>/dev/null | head -n 1 | awk '{print $1}' || true)
+    fi
+fi
+[ -z "$CURRENT_VERSION" ] && exit 0
+
+# Hash the active settings.json files (user + project, each level).
+hash_file() {
+    [ -f "$1" ] || return 0
+    sha256sum "$1" 2>/dev/null | awk '{print $1}'
+}
+
+USER_SETTINGS="${HOME}/.claude/settings.json"
+USER_LOCAL="${HOME}/.claude/settings.local.json"
+PROJ_SETTINGS=""
+PROJ_LOCAL=""
+if [ -n "$CWD" ]; then
+    PROJ_SETTINGS="${CWD}/.claude/settings.json"
+    PROJ_LOCAL="${CWD}/.claude/settings.local.json"
+fi
+
+USER_HASH=$(hash_file "$USER_SETTINGS")
+USER_LOCAL_HASH=$(hash_file "$USER_LOCAL")
+PROJ_HASH=$(hash_file "$PROJ_SETTINGS")
+PROJ_LOCAL_HASH=$(hash_file "$PROJ_LOCAL")
+
+# Read prior state if present.
+PRIOR_VERSION=""
+if [ -f "$STATE_FILE" ]; then
+    PRIOR_VERSION=$(jq -r '.version // empty' "$STATE_FILE" 2>/dev/null || true)
+fi
+
+# Always update state at the end of this run, even when nothing
+# changes — this keeps the state file fresh and prevents the warning
+# from firing on every session forever.
+write_state() {
+    mkdir -p "$(dirname "$STATE_FILE")" 2>/dev/null
+    jq -n \
+        --arg v "$CURRENT_VERSION" \
+        --arg t "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" \
+        --arg uh "$USER_HASH" \
+        --arg ul "$USER_LOCAL_HASH" \
+        --arg ph "$PROJ_HASH" \
+        --arg pl "$PROJ_LOCAL_HASH" \
+        '{version:$v, recorded:$t, hashes:{user:$uh, user_local:$ul, project:$ph, project_local:$pl}}' \
+        > "$STATE_FILE" 2>/dev/null || true
+}
+
+# First-ever run: record state and exit silently. Do not warn on
+# the very first session because there is nothing to compare against.
+if [ -z "$PRIOR_VERSION" ]; then
+    write_state
+    exit 0
+fi
+
+# Same version: nothing to flag. Refresh the state's recorded
+# timestamp and exit.
+if [ "$PRIOR_VERSION" = "$CURRENT_VERSION" ]; then
+    write_state
+    exit 0
+fi
+
+# Version changed. Build a list of representative Allow rules to
+# remind the operator to re-verify.
+collect_allow_rules() {
+    local f="$1"
+    [ -f "$f" ] || return 0
+    jq -r '.permissions.allow[]? // empty' "$f" 2>/dev/null | head -n 6
+}
+
+ALLOW_SAMPLE=$(
+    {
+        collect_allow_rules "$USER_SETTINGS"
+        collect_allow_rules "$USER_LOCAL"
+        collect_allow_rules "$PROJ_SETTINGS"
+        collect_allow_rules "$PROJ_LOCAL"
+    } | sort -u | head -n 6
+)
+
+# Detect memory: directives that may need re-loading after the bump.
+MEMORY_HITS=""
+for f in "$USER_SETTINGS" "$USER_LOCAL" "$PROJ_SETTINGS" "$PROJ_LOCAL"; do
+    [ -n "$f" ] || continue
+    [ -f "$f" ] || continue
+    if grep -qE '"memory"[[:space:]]*:' "$f" 2>/dev/null; then
+        MEMORY_HITS="${MEMORY_HITS}    ${f}\n"
+    fi
+done
+
+printf '⚠️  settings-regression-tester: Claude Code version changed (%s -> %s).\n' "$PRIOR_VERSION" "$CURRENT_VERSION" >&2
+printf '  Permission rules and memory directives can drift silently across\n' >&2
+printf '  version bumps (Issues #57491, #57486). Re-verify before relying.\n' >&2
+
+if [ -n "$ALLOW_SAMPLE" ]; then
+    printf '\n  Active Allow rules to re-confirm:\n' >&2
+    printf '%s\n' "$ALLOW_SAMPLE" | sed 's/^/    - /' >&2
+fi
+
+if [ -n "$MEMORY_HITS" ]; then
+    printf '\n  memory directives present (may need re-loading post-compact):\n' >&2
+    printf '%b' "$MEMORY_HITS" >&2
+fi
+
+printf '\n  References:\n' >&2
+printf '    https://github.com/anthropics/claude-code/issues/57491\n' >&2
+printf '    https://github.com/anthropics/claude-code/issues/57486\n' >&2
+printf '  Recommended fix: run a representative tool (e.g. Bash(npm:test)) and confirm it auto-approves;\n' >&2
+printf '  open a fresh session and verify memory: directives are referenced before continuing.\n' >&2
+
+write_state
+
+if [ "$BLOCK" = "1" ]; then
+    exit 2
+fi
+
+exit 0

package/examples/shell-config-truncation-guard.sh

@@ -24,6 +24,18 @@
 #   }
 # }
 
+# 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-shell-config-truncation-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [shell-config-truncation-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
 

package/examples/shell-wrapper-guard.sh

@@ -16,6 +16,18 @@
 #
 # TRIGGER: PreToolUse  MATCHER: "Bash"
 
+# 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-shell-wrapper-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [shell-wrapper-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0

package/examples/skill-cumulative-size-detector.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# skill-cumulative-size-detector.sh — Detect cumulative skill descriptions size
+#                                     approaching the silent-drop threshold
+#
+# Solves: Issue #59921 — Skill descriptions silently dropped from system prompt
+#         above some cumulative-size threshold. The user enables many skills,
+#         the system prompt size grows past an undocumented threshold, and
+#         some skill descriptions are silently omitted from the active context.
+#         The user cannot tell which skills are active versus dropped from
+#         within a running session.
+#
+# How it works: SessionStart hook that walks both user-scope (~/.claude/skills)
+#               and project-scope (.claude/skills) directories, sums the byte
+#               counts of every SKILL.md description, and emits an advisory
+#               warning when the cumulative total approaches or exceeds the
+#               observed silent-drop threshold. Read-only; never modifies
+#               any skill content.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# Tunables:
+#   CC_SKILL_SIZE_WARN_BYTES        — soft warning threshold (default 25000)
+#   CC_SKILL_SIZE_HARD_BYTES        — hard warning threshold (default 50000)
+#   CC_SKILL_SIZE_DISABLE_WARNING=1 — suppress all warnings
+#
+# Exit: always 0 (advisory). Output goes to stderr.
+
+set -uo pipefail
+
+if [ "${CC_SKILL_SIZE_DISABLE_WARNING:-0}" = "1" ]; then
+    exit 0
+fi
+
+WARN_BYTES="${CC_SKILL_SIZE_WARN_BYTES:-25000}"
+HARD_BYTES="${CC_SKILL_SIZE_HARD_BYTES:-50000}"
+
+# Absorb the SessionStart JSON without depending on its fields.
+read -r -d '' _INPUT < /dev/stdin 2>/dev/null || true
+
+# Helper: append every SKILL.md byte count under a base directory.
+count_skill_bytes() {
+    local base="$1"
+    local total=0
+    local count=0
+    [ -d "$base" ] || { printf '%d %d\n' 0 0; return 0; }
+    while IFS= read -r -d '' file; do
+        local size
+        size=$(wc -c < "$file" 2>/dev/null || printf '0')
+        total=$((total + size))
+        count=$((count + 1))
+    done < <(find "$base" -mindepth 1 -maxdepth 3 -type f -name 'SKILL.md' -print0 2>/dev/null)
+    printf '%d %d\n' "$total" "$count"
+}
+
+USER_BASE="${HOME}/.claude/skills"
+read -r USER_BYTES USER_COUNT <<< "$(count_skill_bytes "$USER_BASE")"
+
+PROJECT_BASE=".claude/skills"
+read -r PROJECT_BYTES PROJECT_COUNT <<< "$(count_skill_bytes "$PROJECT_BASE")"
+
+TOTAL_BYTES=$((USER_BYTES + PROJECT_BYTES))
+TOTAL_COUNT=$((USER_COUNT + PROJECT_COUNT))
+
+if [ "$TOTAL_BYTES" -lt "$WARN_BYTES" ]; then
+    exit 0
+fi
+
+LEVEL="WARN"
+if [ "$TOTAL_BYTES" -ge "$HARD_BYTES" ]; then
+    LEVEL="HARD"
+fi
+
+{
+    echo "[$LEVEL] Cumulative skill description size approaches silent-drop threshold."
+    echo ""
+    echo "  user scope    ($USER_BASE): ${USER_BYTES} bytes across ${USER_COUNT} SKILL.md files"
+    echo "  project scope ($PROJECT_BASE): ${PROJECT_BYTES} bytes across ${PROJECT_COUNT} SKILL.md files"
+    echo "  cumulative total: ${TOTAL_BYTES} bytes across ${TOTAL_COUNT} skills"
+    echo ""
+    echo "  soft warning threshold: ${WARN_BYTES} bytes"
+    echo "  hard warning threshold: ${HARD_BYTES} bytes"
+    echo ""
+    echo "  Issue #59921: Skill descriptions silently dropped from system prompt"
+    echo "                above an undocumented cumulative-size threshold."
+    echo "                The user cannot tell which skills are active versus"
+    echo "                dropped from within a running session."
+    echo ""
+    if [ "$LEVEL" = "HARD" ]; then
+        echo "  Some skill descriptions are very likely already being silently dropped."
+    else
+        echo "  Some skill descriptions may be silently dropped in this session."
+    fi
+    echo "  Recommended actions to confirm scope and recover the dropped skills:"
+    echo "    1. Run /skills to list which skills the model can currently see."
+    echo "    2. Cross-check against ls $USER_BASE $PROJECT_BASE to find the gap."
+    echo "    3. Disable rarely-used skills (move them out of the skills/ tree)"
+    echo "       until the cumulative total falls below the warning threshold."
+    echo ""
+    echo "  Suppress this warning: CC_SKILL_SIZE_DISABLE_WARNING=1"
+    echo "  Adjust thresholds:     CC_SKILL_SIZE_WARN_BYTES / CC_SKILL_SIZE_HARD_BYTES"
+} >&2
+
+exit 0

package/examples/skill-description-drop-detector.sh

@@ -0,0 +1,148 @@
+#!/bin/bash
+# ================================================================
+# skill-description-drop-detector.sh — Detect silent SKILL.md
+# description drops above cumulative-size threshold
+# ================================================================
+# PURPOSE:
+#   Issue #59921 documents Claude Code v2.1.143 silently dropping
+#   the `description:` field from individual SKILL.md entries in
+#   the available-skills section of the system prompt when the
+#   cumulative size of all skill descriptions exceeds an internal
+#   threshold. The skill name stays in the list, but the description
+#   is replaced with nothing — silently degrading auto-trigger
+#   precision for the affected skills.
+#
+#   The reporter verified the drop is cumulative: editing one
+#   SKILL.md to add ~800 chars caused a different skill's
+#   description to silently disappear.
+#
+#   Operators have no way to detect this from outside the session.
+#   The skill appears installed; the model just stops triggering
+#   it correctly.
+#
+# DETECTION:
+#   At SessionStart, count the SKILL.md files in the user's
+#   ~/.claude/skills/ and any plugin SKILL.md directories. Compute
+#   the cumulative size of `description:` fields. If the total
+#   exceeds a threshold (default 50000 chars, matching reporter's
+#   ~153 skill threshold), emit a warning to operator surfaces.
+#
+# TRIGGER: SessionStart
+# MATCHER: (none)
+#
+# OUTPUT:
+#   When threshold exceeded: a system-reminder via
+#   hookSpecificOutput.additionalContext warning the model that
+#   some skill descriptions may have been silently dropped and
+#   advising it to verify auto-trigger behavior.
+#
+# CONFIGURATION:
+#   CC_SKILL_DESC_THRESHOLD     — total description size threshold
+#                                 in chars (default: 50000).
+#   CC_SKILL_DESC_DIRS          — colon-separated list of directories
+#                                 to scan. Default scans
+#                                 ~/.claude/skills/ plus any
+#                                 directory in ~/.claude/plugins/
+#                                 containing a SKILL.md.
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/59921
+# ================================================================
+
+set -u
+
+THRESHOLD="${CC_SKILL_DESC_THRESHOLD:-50000}"
+
+# Discover skill directories. Default scans:
+# 1. ~/.claude/skills/*/SKILL.md
+# 2. ~/.claude/plugins/*/SKILL.md (plugin-shipped skills)
+if [ -n "${CC_SKILL_DESC_DIRS:-}" ]; then
+    IFS=':' read -ra SKILL_DIRS <<< "$CC_SKILL_DESC_DIRS"
+else
+    SKILL_DIRS=()
+    [ -d "$HOME/.claude/skills" ] && SKILL_DIRS+=("$HOME/.claude/skills")
+    [ -d "$HOME/.claude/plugins" ] && SKILL_DIRS+=("$HOME/.claude/plugins")
+fi
+
+[ ${#SKILL_DIRS[@]} -eq 0 ] && exit 0
+
+# Find every SKILL.md across the directories.
+SKILL_FILES=()
+for dir in "${SKILL_DIRS[@]}"; do
+    [ -d "$dir" ] || continue
+    while IFS= read -r f; do
+        SKILL_FILES+=("$f")
+    done < <(find "$dir" -name "SKILL.md" -type f 2>/dev/null)
+done
+
+[ ${#SKILL_FILES[@]} -eq 0 ] && exit 0
+
+SKILL_COUNT=${#SKILL_FILES[@]}
+TOTAL_DESC_SIZE=0
+SKILLS_WITH_DESC=0
+SKILLS_WITHOUT_DESC=0
+
+# For each SKILL.md, extract the description: field from YAML
+# frontmatter and sum the lengths.
+for f in "${SKILL_FILES[@]}"; do
+    # Extract description: field. It can be a single-line or
+    # folded-block. Single-line case is most common.
+    desc=$(awk '
+        /^---$/ { count++; next }
+        count == 1 && /^description:/ {
+            sub(/^description:[ \t]*/, "")
+            sub(/^"/, ""); sub(/"$/, "")
+            sub(/^'\''/, ""); sub(/'\''$/, "")
+            print
+            exit
+        }
+    ' "$f" 2>/dev/null)
+
+    if [ -n "$desc" ]; then
+        SKILLS_WITH_DESC=$((SKILLS_WITH_DESC + 1))
+        len=${#desc}
+        TOTAL_DESC_SIZE=$((TOTAL_DESC_SIZE + len))
+    else
+        SKILLS_WITHOUT_DESC=$((SKILLS_WITHOUT_DESC + 1))
+    fi
+done
+
+# Below threshold. No warning.
+if [ "$TOTAL_DESC_SIZE" -lt "$THRESHOLD" ]; then
+    exit 0
+fi
+
+# Above threshold. Emit a warning via hookSpecificOutput.
+WARNING="===== SKILL DESCRIPTION CUMULATIVE-SIZE WARNING =====
+Found ${SKILL_COUNT} SKILL.md file(s) totaling ${TOTAL_DESC_SIZE} chars in
+description fields (threshold: ${THRESHOLD}).
+
+Per Issue #59921, Claude Code v2.1.143 silently drops the description: field
+from individual skill entries in the available-skills section when the
+cumulative description size exceeds an internal threshold. The skill name
+stays visible; the description is replaced with nothing. Auto-trigger
+precision degrades for affected skills, but the operator has no visible
+signal that this is happening.
+
+Recommended verification:
+  1. Inspect the available-skills section of this session's system prompt.
+  2. For each skill name without a description, read the corresponding
+     SKILL.md file directly and confirm description: is well-formed.
+  3. If well-formed descriptions are silently empty in the prompt, you are
+     hitting the threshold. Mitigation: shorten descriptions of less-used
+     skills, or split into smaller plugin groups.
+
+Skills with description: ${SKILLS_WITH_DESC}
+Skills without description: ${SKILLS_WITHOUT_DESC}
+===== END WARNING ====="
+
+jq -n \
+    --arg ctx "$WARNING" \
+    '{
+        hookSpecificOutput: {
+            hookEventName: "SessionStart",
+            additionalContext: $ctx
+        }
+    }'
+
+exit 0