cc-safe-setup 29.7.0 → 30.0.4

package/examples/skill-truncation-detector.sh

@@ -0,0 +1,154 @@
+#!/bin/bash
+# skill-truncation-detector.sh — Restore the Skill-listing truncation
+# warning that v2.1.144 silently removed.
+#
+# Solves: v2.1.144 (2026-05-19) release note —
+#   "Skill-listing truncation is no longer shown as a startup notification
+#    — run /doctor for the full breakdown."
+#
+# The change moved the truncation signal from passive (visible at startup,
+# user is told) to active (user has to remember to run /doctor). The three
+# concrete failure modes the old startup notice surfaced — skill-count
+# crossing the limit, name collisions, malformed frontmatter — all now go
+# silent by default.
+#
+# This hook fires on SessionStart, scans the user's skill directories for
+# the same three failure modes, and emits a system-reminder when any are
+# detected. Effectively restores the v2.1.143-and-earlier behavior at the
+# hook layer.
+#
+# This is the "recognition-without-arrest" pattern's *opposite* failure mode:
+# the harness used to surface a recognition signal, and now refuses to. The
+# hook re-surfaces it.
+#
+# Related Issues:
+#   #60226 (@suwayama, 2026-05-18) — recognition-without-arrest framework
+#   Anthropic v2.1.144 release notes (2026-05-19) — the notification removal
+#
+# TRIGGER: SessionStart
+# MATCHER: (none)
+#
+# CONFIGURATION (environment variables):
+#   CC_SKILL_COUNT_THRESHOLD  default 80 — warn when skills exceed this count
+#   CC_SKILL_DIRS             default "~/.claude/skills" — colon-separated
+#                                                  list of skill directories
+#                                                  to scan
+#   CC_SKILL_TRUNCATION_DISABLE  set to "1" to disable the detector
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "SessionStart": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/skill-truncation-detector.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+set -uo pipefail
+
+[ "${CC_SKILL_TRUNCATION_DISABLE:-0}" = "1" ] && exit 0
+
+THRESHOLD="${CC_SKILL_COUNT_THRESHOLD:-80}"
+DEFAULT_DIRS="${HOME}/.claude/skills"
+SKILL_DIRS="${CC_SKILL_DIRS:-$DEFAULT_DIRS}"
+LOG_DIR="${HOME}/.claude/logs"
+mkdir -p "$LOG_DIR" 2>/dev/null
+
+INPUT=$(cat 2>/dev/null || true)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+[ -z "$SESSION_ID" ] && SESSION_ID="unknown-$(date +%s)"
+
+# Once per session, even if multiple SessionStart hooks fire.
+WARN_LOG="$LOG_DIR/skill-truncation-warned-$SESSION_ID"
+[ -f "$WARN_LOG" ] && exit 0
+
+# Collect skill files. Each skill is a directory containing SKILL.md, per
+# the standard layout used by Anthropic and most plugin authors.
+SKILL_FILES=()
+IFS=':' read -ra DIRS <<< "$SKILL_DIRS"
+for dir in "${DIRS[@]}"; do
+    dir="${dir/#\~/$HOME}"
+    [ -d "$dir" ] || continue
+    while IFS= read -r f; do
+        SKILL_FILES+=("$f")
+    done < <(find "$dir" -maxdepth 3 -name "SKILL.md" 2>/dev/null)
+done
+
+SKILL_COUNT=${#SKILL_FILES[@]}
+
+# Check 1: skill count near or above threshold
+COUNT_WARNING=""
+if [ "$SKILL_COUNT" -ge "$THRESHOLD" ]; then
+    COUNT_WARNING="Skill count is $SKILL_COUNT, at or above the configured threshold of $THRESHOLD. Some skills may be truncated from the system context."
+fi
+
+# Check 2: name collisions. Read the `name:` field from frontmatter of each
+# skill file. Multiple skills with the same name will collide at registration.
+declare -A NAMES_SEEN
+COLLISION_LIST=""
+MALFORMED_LIST=""
+for f in "${SKILL_FILES[@]}"; do
+    # Extract name from YAML frontmatter (between first two --- lines).
+    NAME=$(awk '/^---$/{c++; next} c==1 && /^name:/{sub(/^name:[[:space:]]*/, ""); print; exit}' "$f" 2>/dev/null | tr -d '"' | tr -d "'" | xargs)
+    if [ -z "$NAME" ]; then
+        # No name field, no frontmatter, or unreadable. Skill registration
+        # falls back to directory name in some versions; in others it fails
+        # silently. Either way, this is a failure mode the old notice
+        # surfaced.
+        MALFORMED_LIST="${MALFORMED_LIST}  - ${f/#$HOME/~}: no 'name:' field in frontmatter
+"
+        continue
+    fi
+    if [ -n "${NAMES_SEEN[$NAME]:-}" ]; then
+        COLLISION_LIST="${COLLISION_LIST}  - '$NAME': ${NAMES_SEEN[$NAME]/#$HOME/~} and ${f/#$HOME/~}
+"
+    else
+        NAMES_SEEN[$NAME]="$f"
+    fi
+done
+
+# If no findings, exit silently. (The hook is a tripwire; absence of
+# finding is the common case and should not be noisy.)
+if [ -z "$COUNT_WARNING" ] && [ -z "$COLLISION_LIST" ] && [ -z "$MALFORMED_LIST" ]; then
+    : > "$WARN_LOG"
+    exit 0
+fi
+
+# Build the system-reminder.
+{
+    echo "<system-reminder>"
+    echo "SKILL-LISTING TRUNCATION DETECTOR — restoring the startup signal"
+    echo "that v2.1.144 silently removed."
+    echo ""
+    if [ -n "$COUNT_WARNING" ]; then
+        echo "* COUNT: $COUNT_WARNING"
+        echo ""
+    fi
+    if [ -n "$COLLISION_LIST" ]; then
+        echo "* NAME COLLISIONS (one of the colliding skills will not load):"
+        printf '%s' "$COLLISION_LIST"
+        echo ""
+    fi
+    if [ -n "$MALFORMED_LIST" ]; then
+        echo "* MALFORMED FRONTMATTER (skills without a 'name:' field):"
+        printf '%s' "$MALFORMED_LIST"
+        echo ""
+    fi
+    echo "Run \`/doctor\` for the full Claude Code report on skill"
+    echo "registration. Fix the listed items above to ensure all skills"
+    echo "register correctly."
+    echo ""
+    echo "To silence this detector intentionally, set"
+    echo "CC_SKILL_TRUNCATION_DISABLE=1 in your environment."
+    echo "</system-reminder>"
+} >&2
+
+# Mark warned so we don't double-fire in this session.
+: > "$WARN_LOG"
+
+# SessionStart hooks should not block; we surface the info and exit 0.
+exit 0

package/examples/skills-context-recorder.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+# skills-context-recorder.sh — Record active skill at each user prompt for hook integration
+#
+# Background:
+#   Claude Code's Skills feature (v2.x) does not expose which skill is active
+#   during a given tool call to PreToolUse / PostToolUse hooks. Issue #62108
+#   asks for an `active_skill` field in hook input. Issue #62078 asks for an
+#   env var exposing the current skill name. Neither is implemented.
+#
+#   The workaround is to record skill activations operator-side. When a user
+#   invokes a skill via `/<skill-name>` at the start of their prompt, this hook
+#   captures the name and persists it to a per-session log. Other hooks can
+#   read the log to know the most recent skill in the current session — the
+#   closest operator-side approximation of the active_skill field.
+#
+#   The hook also captures auto-loaded skills mentioned in the prompt via
+#   `[skill: name]` markers (some skills inject this on activation, others
+#   don't — this is best-effort and pairs with the slash-command path).
+#
+#   Reference:
+#     #62108 — active_skill field request (PreToolUse hook input)
+#     #62078 — env var request for current skill name
+#     Skills cluster field guide: https://gist.github.com/yurukusa/d00b2d32505ef67572baacbd6fad3d77
+#
+# What this hook does:
+#   On UserPromptSubmit, parse the prompt's first non-blank line for one of:
+#     - `/<skill-name>` at column 0 (canonical slash-command invocation)
+#     - `[skill: <skill-name>]` or `<skill name="...">` markers (skill self-announce)
+#   When matched, append a 4-field pipe-delimited record to a per-session log:
+#     TIMESTAMP_ISO8601 | SESSION_ID | SOURCE | SKILL_NAME
+#   where SOURCE is `slash` (slash command), `marker` (in-prompt marker), or
+#   `manual` (operator override via env var CC_ACTIVE_SKILL).
+#
+#   Default log: ~/.claude/skills-context.log (session-tagged in the SESSION_ID field).
+#   Companion helper script (cc-active-skill) at the bottom of this file's docs
+#   can be sourced to read "current skill for session X" from any other hook.
+#
+# When this hook does NOT record:
+#   - CC_SKILLS_CONTEXT_RECORDER_DISABLE=1
+#   - The user prompt does not contain a recognizable skill invocation pattern
+#   - The user prompt is empty or unparseable
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "UserPromptSubmit": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/skills-context-recorder.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_SKILLS_CONTEXT_RECORDER_DISABLE=1   — never log
+#   CC_SKILLS_CONTEXT_RECORDER_QUIET=1     — log silently (no stderr advisory)
+#   CC_SKILLS_CONTEXT_LOG_PATH=<path>      — override default log location
+#   CC_SKILLS_CONTEXT_MAX_LINES=<n>        — log rotation threshold (default 1000)
+#   CC_ACTIVE_SKILL=<name>                 — operator override; recorded as source=manual
+#
+# Reading the log from another hook (workaround for the missing active_skill field):
+#   most_recent_skill_for_session() {
+#     local session_id="$1"
+#     local log="${CC_SKILLS_CONTEXT_LOG_PATH:-$HOME/.claude/skills-context.log}"
+#     grep "|${session_id}|" "$log" 2>/dev/null | tail -1 | awk -F'|' '{print $4}'
+#   }
+#
+# Privacy: the hook records skill names only (no prompt content, no tool args).
+# Skill names are human-chosen identifiers — typically short ASCII strings.
+#
+# The registration was missing from this header. The installer reads TRIGGER
+# and MATCHER from here and falls back to PreToolUse / Bash when both are
+# absent, so this hook was being registered at a moment where the field it
+# reads is always empty: it installed, it appeared in the settings, and it
+# did nothing. Measured 2026-08-04 across examples/: 14 files were like this.
+# TRIGGER: UserPromptSubmit
+# MATCHER: ""
+
+set -u
+
+# Disable path
+if [ "${CC_SKILLS_CONTEXT_RECORDER_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+# Extract user prompt and session ID. Fall back to grep when jq is missing so the
+# hook stays useful in minimal environments.
+if command -v jq >/dev/null 2>&1; then
+  USER_PROMPT=$(printf '%s' "$INPUT" | jq -r '.user_prompt // .prompt // empty' 2>/dev/null || echo "")
+  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || echo "")
+else
+  USER_PROMPT=$(printf '%s' "$INPUT" | sed -n 's/.*"user_prompt"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+  [ -z "$USER_PROMPT" ] && USER_PROMPT=$(printf '%s' "$INPUT" | sed -n 's/.*"prompt"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+  SESSION_ID=$(printf '%s' "$INPUT" | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+fi
+
+[ -z "$SESSION_ID" ] && SESSION_ID="no-session-id"
+
+# Determine source and skill name. Priority: manual override → slash command →
+# in-prompt marker. First match wins.
+SOURCE=""
+SKILL=""
+
+# 1. Operator override via CC_ACTIVE_SKILL env var
+if [ -n "${CC_ACTIVE_SKILL:-}" ]; then
+  SOURCE="manual"
+  SKILL="$CC_ACTIVE_SKILL"
+fi
+
+# 2. Slash command at start of first non-blank line. Leading whitespace on the
+# first line is tolerated; the slash must be the first non-blank character.
+if [ -z "$SKILL" ] && [ -n "$USER_PROMPT" ]; then
+  FIRST_LINE=$(printf '%s' "$USER_PROMPT" | awk 'NF{print; exit}')
+  TRIMMED=$(printf '%s' "$FIRST_LINE" | sed 's/^[[:space:]]*//')
+  if printf '%s' "$TRIMMED" | grep -qE '^/[A-Za-z][A-Za-z0-9_:-]*'; then
+    SKILL=$(printf '%s' "$TRIMMED" | grep -oE '^/[A-Za-z][A-Za-z0-9_:-]*' | sed 's|^/||' | head -c 64)
+    SOURCE="slash"
+  fi
+fi
+
+# 3. In-prompt marker (best-effort)
+if [ -z "$SKILL" ] && [ -n "$USER_PROMPT" ]; then
+  MARKER=$(printf '%s' "$USER_PROMPT" | grep -oE '\[skill:[[:space:]]*[A-Za-z][A-Za-z0-9_-]+\]' | head -1)
+  if [ -n "$MARKER" ]; then
+    SKILL=$(printf '%s' "$MARKER" | sed -E 's/\[skill:[[:space:]]*([A-Za-z][A-Za-z0-9_-]+)\]/\1/' | head -c 64)
+    SOURCE="marker"
+  fi
+fi
+
+# Strip pipe characters and newlines as a schema-preservation guard. Skill names
+# are normally ASCII identifiers so this is a defensive measure.
+SKILL=$(printf '%s' "$SKILL" | tr -d '|\n\r')
+SESSION_ID=$(printf '%s' "$SESSION_ID" | tr -d '|\n\r' | head -c 80)
+
+# No skill detected → silent exit (the common case)
+[ -z "$SKILL" ] && exit 0
+
+LOG_PATH="${CC_SKILLS_CONTEXT_LOG_PATH:-$HOME/.claude/skills-context.log}"
+LOG_DIR=$(dirname "$LOG_PATH")
+mkdir -p "$LOG_DIR" 2>/dev/null || exit 0
+
+TIMESTAMP=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+printf '%s|%s|%s|%s\n' "$TIMESTAMP" "$SESSION_ID" "$SOURCE" "$SKILL" >> "$LOG_PATH" 2>/dev/null || true
+
+# Rotate when the log exceeds the configured threshold. Keep the most recent half
+# so the workaround stays useful for cross-session lookback.
+MAX_LINES="${CC_SKILLS_CONTEXT_MAX_LINES:-1000}"
+if [ -f "$LOG_PATH" ]; then
+  CURRENT_LINES=$(wc -l < "$LOG_PATH" 2>/dev/null || echo 0)
+  if [ "$CURRENT_LINES" -gt "$MAX_LINES" ] 2>/dev/null; then
+    KEEP=$((MAX_LINES / 2))
+    [ "$KEEP" -lt 1 ] && KEEP=1
+    tail -n "$KEEP" "$LOG_PATH" > "${LOG_PATH}.tmp" 2>/dev/null && mv "${LOG_PATH}.tmp" "$LOG_PATH" 2>/dev/null || true
+  fi
+fi
+
+# Stderr advisory: one line summarizing the recorded activation. Silent when
+# explicitly muted. Keeps the operator aware that the workaround is in effect
+# without flooding the terminal.
+if [ "${CC_SKILLS_CONTEXT_RECORDER_QUIET:-0}" != "1" ]; then
+  printf '[skills-context-recorder] recorded skill=%s source=%s session=%s\n' \
+    "$SKILL" "$SOURCE" "${SESSION_ID:0:12}" >&2
+fi
+
+exit 0

package/examples/skills-load-verifier.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# ================================================================
+# skills-load-verifier.sh — Warn when a SKILL.md cannot be loaded
+# ================================================================
+# PURPOSE:
+#   This hook reports at session start via hookSpecificOutput /
+#   additionalContext. Without the TRIGGER header below, the
+#   installer registered it under the default PreToolUse/Bash,
+#   so it fired on every Bash call and never ran at session start.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+# ================================================================
+
+set -u
+INPUT=$(cat)
+MIN_DESC_LEN="${CC_SKILLS_MIN_DESC_LEN:-10}"
+if [ -n "${CC_SKILLS_DIRS:-}" ]; then
+    IFS=':' read -ra SKILLS_DIRS <<< "$CC_SKILLS_DIRS"
+else
+    SKILLS_DIRS=(
+        "$HOME/.claude/skills"
+        ".claude/skills"
+    )
+fi
+FINDINGS=()
+for skills_root in "${SKILLS_DIRS[@]}"; do
+    [ -d "$skills_root" ] || continue
+    for skill_dir in "$skills_root"/*; do
+        [ -d "$skill_dir" ] || continue
+        skill_name_from_dir=$(basename "$skill_dir")
+        skill_md="$skill_dir/SKILL.md"
+        if [ ! -f "$skill_md" ]; then
+            FINDINGS+=("$skill_dir: missing SKILL.md (directory present but no SKILL.md file)")
+            continue
+        fi
+        if [ ! -r "$skill_md" ]; then
+            FINDINGS+=("$skill_md: unreadable (permission or dangling symlink)")
+            continue
+        fi
+        first_line=$(head -n 1 "$skill_md" 2>/dev/null || echo "")
+        if [ "$first_line" != "---" ]; then
+            FINDINGS+=("$skill_md: missing YAML frontmatter (file does not start with ---)")
+            continue
+        fi
+        frontmatter=$(awk '/^---$/{c++; next} c==1{print} c>=2{exit}' "$skill_md" 2>/dev/null)
+        if [ -z "$frontmatter" ]; then
+            FINDINGS+=("$skill_md: empty or unterminated frontmatter block")
+            continue
+        fi
+        name=$(printf '%s\n' "$frontmatter" | grep -E '^name:[[:space:]]*' | head -n 1 | sed -E 's/^name:[[:space:]]*//; s/[[:space:]]+$//; s/^["'\'']//; s/["'\'']$//')
+        if [ -z "$name" ]; then
+            FINDINGS+=("$skill_md: missing or empty 'name' field in frontmatter")
+            continue
+        fi
+        description=$(printf '%s\n' "$frontmatter" | grep -E '^description:[[:space:]]*' | head -n 1 | sed -E 's/^description:[[:space:]]*//; s/[[:space:]]+$//; s/^["'\'']//; s/["'\'']$//')
+        if [ -z "$description" ]; then
+            FINDINGS+=("$skill_md: missing or empty 'description' field in frontmatter")
+            continue
+        fi
+        desc_len=${#description}
+        if [ "$desc_len" -lt "$MIN_DESC_LEN" ]; then
+            FINDINGS+=("$skill_md: 'description' too short ($desc_len chars, minimum $MIN_DESC_LEN) — will likely be skipped or surface poorly")
+            continue
+        fi
+        if [ "$name" != "$skill_name_from_dir" ]; then
+            FINDINGS+=("$skill_md: 'name: $name' does not match directory name '$skill_name_from_dir' (slash command will use the frontmatter name, not the directory)")
+            continue
+        fi
+    done
+done
+[ ${#FINDINGS[@]} -eq 0 ] && exit 0
+MSG="DETECTED: Skills configured but malformed in a way that will silently fail to load.
+Each Skill below has a structural problem that the Claude Code runtime does not surface as an error. The session proceeds without the Skill, and the model loses access to its slash command and instructions without any warning. Common causes: incomplete copy-paste from documentation, hand-edited frontmatter, missing SKILL.md after directory rename.
+Findings:"
+for finding in "${FINDINGS[@]}"; do
+    MSG="$MSG
+  - $finding"
+done
+MSG="$MSG
+To fix each finding: open the SKILL.md file, ensure the frontmatter has the form
+  ---
+  name: <kebab-case-name-matching-directory>
+  description: <one-sentence summary, at least $MIN_DESC_LEN chars>
+  ---
+After fixing, restart the session to verify the Skill loads. See related issues:
+  https://github.com/anthropics/claude-code/issues/62421 (settings-side fabrication)
+  https://github.com/anthropics/claude-code/issues/62049 (paths field silent no-op)"
+jq -n --arg msg "$MSG" '
+{
+    "hookSpecificOutput": {
+        "hookEventName": "SessionStart",
+        "additionalContext": $msg
+    }
+}'
+exit 0

package/examples/skills-settings-validator.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# ================================================================
+# skills-settings-validator.sh — Detect fabricated Skills-related
+# settings fields in settings.json with no validation
+# ================================================================
+# PURPOSE:
+#   Issue #62421 documents Claude Code accepting non-existent
+#   Skills-related settings fields (e.g. `disabledSkills`) without
+#   validation. A sub-agent or operator writes the fabricated field
+#   into ~/.claude/settings.json or .claude/settings.local.json;
+#   the write succeeds, restart succeeds, the targeted skills
+#   remain active. Silent no-op.
+#
+#   The runtime has no schema validation for settings.json, so
+#   typos, hallucinated fields, and out-of-date examples all
+#   produce the same silent acceptance. Operators discover the
+#   non-effect by trial-and-error, often after many sessions.
+#
+# DETECTION:
+#   At SessionStart, scan settings.json and settings.local.json
+#   for top-level keys matching common Skills-fabrication patterns:
+#     - disabledSkills, enabledSkills (the canonical fabrication)
+#     - skillsConfig, skillConfig, skillsSettings
+#     - skillRouting, skillFilter, skillAllowlist, skillDenylist
+#     - excludeSkills, includeSkills, allowedSkills, deniedSkills
+#   These are the names sub-agents most commonly invent when asked
+#   to "disable a skill" via settings.json. None exist in the
+#   actual Claude Code schema.
+#
+# TRIGGER: SessionStart
+# MATCHER: (none)
+#
+# OUTPUT:
+#   When fabricated fields detected: a system-reminder via
+#   hookSpecificOutput.additionalContext warning the model and
+#   operator that the fields will be silently ignored, and
+#   listing them by source file.
+#
+# CONFIGURATION:
+#   CC_SKILLS_SETTINGS_FILES    — colon-separated list of settings
+#                                 files to scan. Default scans
+#                                 ~/.claude/settings.json,
+#                                 ~/.claude/settings.local.json,
+#                                 .claude/settings.json,
+#                                 .claude/settings.local.json
+#   CC_SKILLS_EXTRA_PATTERNS    — additional space-separated field
+#                                 names to flag as fabricated.
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/62421
+# ================================================================
+
+set -u
+
+# Default fabricated-field patterns. Additional patterns can be
+# added via CC_SKILLS_EXTRA_PATTERNS.
+FABRICATED_FIELDS=(
+    disabledSkills
+    enabledSkills
+    skillsConfig
+    skillConfig
+    skillsSettings
+    skillRouting
+    skillFilter
+    skillAllowlist
+    skillDenylist
+    excludeSkills
+    includeSkills
+    allowedSkills
+    deniedSkills
+)
+
+if [ -n "${CC_SKILLS_EXTRA_PATTERNS:-}" ]; then
+    for pat in $CC_SKILLS_EXTRA_PATTERNS; do
+        FABRICATED_FIELDS+=("$pat")
+    done
+fi
+
+# Discover settings files. Default scans both global and project
+# scope, both regular and local variants.
+if [ -n "${CC_SKILLS_SETTINGS_FILES:-}" ]; then
+    IFS=':' read -ra SETTINGS_FILES <<< "$CC_SKILLS_SETTINGS_FILES"
+else
+    SETTINGS_FILES=(
+        "$HOME/.claude/settings.json"
+        "$HOME/.claude/settings.local.json"
+        ".claude/settings.json"
+        ".claude/settings.local.json"
+    )
+fi
+
+# Detection. For each file that exists, jq-read its top-level
+# keys and check for any fabricated-field match.
+FINDINGS=()
+for file in "${SETTINGS_FILES[@]}"; do
+    [ -f "$file" ] || continue
+    # Skip if not valid JSON.
+    jq empty "$file" 2>/dev/null || continue
+    # Read top-level keys.
+    KEYS=$(jq -r 'keys[]' "$file" 2>/dev/null || echo "")
+    for key in $KEYS; do
+        for fab in "${FABRICATED_FIELDS[@]}"; do
+            if [ "$key" = "$fab" ]; then
+                FINDINGS+=("$file: $key")
+            fi
+        done
+    done
+done
+
+# Exit clean if nothing fabricated.
+[ ${#FINDINGS[@]} -eq 0 ] && exit 0
+
+# Build the warning message.
+MSG="DETECTED: Skills-related settings fields with no schema definition (will be silently ignored).
+
+These fields do not exist in the Claude Code settings schema. Writing them produces no error and no effect — the targeted skills remain active regardless. Common cause: a sub-agent invented the field name when asked to disable a skill via settings.json (issue #62421).
+
+Findings:"
+for finding in "${FINDINGS[@]}"; do
+    MSG="$MSG
+  - $finding"
+done
+
+MSG="$MSG
+
+To actually disable a skill, remove or rename the SKILL.md file from the skill directory. To filter at runtime, use a PreToolUse hook that checks active context rather than relying on a non-existent settings field. See:
+  https://github.com/anthropics/claude-code/issues/62421"
+
+# Emit as JSON system-reminder so it surfaces to both the operator
+# (stderr fallback) and the model (additionalContext).
+jq -n --arg msg "$MSG" '
+{
+    "hookSpecificOutput": {
+        "hookEventName": "SessionStart",
+        "additionalContext": $msg
+    }
+}'
+
+exit 0

package/examples/sonnet-45-deprecation-helper.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# sonnet-45-deprecation-helper.sh — Surface model lifecycle awareness when Claude.ai removes Sonnet 4.5
+#
+# Background:
+#   In late May 2026, Anthropic removed Sonnet 4.5 (claude-sonnet-4-5-20250929) from the
+#   Claude.ai chat UI dropdown, defaulting users to Sonnet 4.6. Users who relied on 4.5
+#   for creative writing, instruction following, or its specific conversational tone
+#   reported widespread dissatisfaction (r/ClaudeAI thread "Sonnet 4.5 is gone for me"
+#   accumulated 75+ upvotes / 98+ comments; the companion thread "Sonnet 4.5 disappeared?
+#   Claude 4.8 soon?" reached 41+ upvotes / 44+ comments within 24 hours).
+#
+#   Crucially, Sonnet 4.5 is NOT retired from the underlying APIs — it remains accessible
+#   on api.anthropic.com, AWS Bedrock, and GCP Vertex for at least 12 months under
+#   Anthropic's stated deprecation policy. The "disappearance" is a surface decision
+#   (Claude.ai UI), not a model retirement. Claude Code users can recover 4.5 access by
+#   pinning the model explicitly via the ANTHROPIC_MODEL env var or the --model flag.
+#
+#   Reference: https://gist.github.com/yurukusa/29d9c3ba62aa514450ba04fccc566161
+#   (5 operator-side paths to keep using Sonnet 4.5)
+#
+# What this hook does:
+#   On SessionStart, inspect ANTHROPIC_MODEL and emit a one-line advisory matching one
+#   of four states:
+#     - ANTHROPIC_MODEL pinned to a 4.5 variant     → silent (user has explicit pin)
+#     - ANTHROPIC_MODEL pinned to a 4.6+ variant    → silent (user has explicit pin)
+#     - ANTHROPIC_MODEL unset and CC_SONNET_45_HELPER_REMIND=1 → emit awareness note
+#     - ANTHROPIC_MODEL unset and CC_SONNET_45_HELPER_REMIND unset → silent (default off)
+#
+#   The reminder is opt-in via CC_SONNET_45_HELPER_REMIND=1 to avoid noise for users
+#   who don't care about model pinning. Once acknowledged, set CC_SONNET_45_HELPER_QUIET=1
+#   to suppress permanently.
+#
+# When this hook does NOT fire a warning:
+#   - CC_SONNET_45_HELPER_QUIET=1
+#   - ANTHROPIC_MODEL is explicitly set to any value (treated as deliberate)
+#   - CC_SONNET_45_HELPER_REMIND is unset (opt-in only)
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/sonnet-45-deprecation-helper.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_SONNET_45_HELPER_QUIET=1   — never emit anything
+#   CC_SONNET_45_HELPER_REMIND=1  — emit reminder when ANTHROPIC_MODEL unset (opt-in)
+
+# Silence path
+if [ "${CC_SONNET_45_HELPER_QUIET:-0}" = "1" ]; then
+  exit 0
+fi
+
+# If ANTHROPIC_MODEL is explicitly set, the user has made a deliberate choice. Stay silent.
+if [ -n "${ANTHROPIC_MODEL:-}" ]; then
+  exit 0
+fi
+
+# If the user did not opt in to reminders, stay silent.
+if [ "${CC_SONNET_45_HELPER_REMIND:-0}" != "1" ]; then
+  exit 0
+fi
+
+# Opt-in reminder path: ANTHROPIC_MODEL unset and user wants the awareness note.
+cat >&2 <<'EOF'
+[sonnet-45-deprecation-helper] ANTHROPIC_MODEL is unset; your session will use the default model selected by Claude Code (currently routes to Sonnet 4.6 family).
+
+To pin Sonnet 4.5 explicitly (still available on the API for at least 12 months):
+  export ANTHROPIC_MODEL=claude-sonnet-4-5-20250929
+
+To pin Sonnet 4.6 explicitly (current default; suppresses this reminder):
+  export ANTHROPIC_MODEL=claude-sonnet-4-6
+
+To suppress this reminder without pinning:
+  export CC_SONNET_45_HELPER_QUIET=1
+
+Background: Sonnet 4.5 was removed from the Claude.ai chat UI in late May 2026 but remains
+available on the Anthropic API, AWS Bedrock, and GCP Vertex AI. See:
+https://gist.github.com/yurukusa/29d9c3ba62aa514450ba04fccc566161
+EOF
+
+exit 0

package/examples/spec-file-scope-guard.sh

@@ -18,6 +18,18 @@
 
 set -euo pipefail
 
+# 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-spec-file-scope-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [spec-file-scope-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/spring-profile-guard.sh

@@ -1,3 +1,4 @@
+#!/bin/bash
 #
 # TRIGGER: PreToolUse  MATCHER: "Edit|Write"
 INPUT=$(cat)