cc-safe-setup 29.7.0 → 30.0.4

package/examples/claude-code-version-pin-advisor.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+# ================================================================
+# claude-code-version-pin-advisor.sh — SessionStart advisory for
+# Cluster 16 (v2.1.154+ messages role 'system' API 400)
+# ================================================================
+# PURPOSE:
+#   Claude Code v2.1.154 onward shipped a request-assembly
+#   regression that serializes `system`-role content from
+#   SessionStart hooks, plugin context, Skill metadata, and
+#   compaction summaries as peer entries inside the `messages[]`
+#   array instead of the top-level `system` field. The Anthropic
+#   Messages API rejects this with `API Error: 400 messages[N].role
+#   must be either 'user' or 'assistant', but got 'system'`.
+#
+#   Four sub-patterns surface this defect:
+#     16A — Custom agents via /agents (Issue #63457)
+#     16B — Strict Anthropic-compatible providers (#63366, #63469)
+#     16C — VS Code extension (#63473, #63510)
+#     16D — Long-lived session context operations (#63396 Variant 1)
+#
+#   The defect lives in code paths the hook layer cannot reach at
+#   request-assembly time. No hook can prevent the 400. The only
+#   workaround is the version pin to v2.1.153.
+#
+#   This hook surfaces the warning at SessionStart so the operator
+#   knows the workaround BEFORE they lose a session to the 400.
+#   It does not block; it advises.
+#
+# DETECTION:
+#   At SessionStart, parse `claude --version` (or read
+#   CLAUDE_CODE_VERSION env var if set) to obtain the running
+#   semver. Compare against the threshold (default 2.1.154). If
+#   at or above, emit an advisory naming the four sub-patterns
+#   and the pin command.
+#
+# TRIGGER: SessionStart
+# MATCHER: (none)
+#
+# OUTPUT:
+#   Advisory only, never blocks. Prints to stderr.
+#
+# CONFIGURATION:
+#   CC_VERSION_PIN_ADVISOR_DISABLE=1    — disable entirely
+#   CC_VERSION_PIN_ADVISOR_QUIET=1      — silence after
+#                                         acknowledgment
+#   CC_VERSION_PIN_ADVISOR_THRESHOLD    — override threshold semver
+#                                         (default "2.1.154")
+#   CC_VERSION_PIN_ADVISOR_CLAUDE_BIN   — override path to claude
+#                                         binary (default: look up
+#                                         on PATH)
+#   CLAUDE_CODE_VERSION                 — if set, the hook uses this
+#                                         instead of calling
+#                                         `claude --version`. Useful
+#                                         for tests and for
+#                                         environments where the
+#                                         binary lookup is slow.
+#
+# RELATED:
+#   Cluster 16 entry in cc-safe-setup cluster-tracker.html
+#   English field guide:
+#     https://gist.github.com/yurukusa/05c120466996734f7bc2ad6d41fdedec
+#   Anchor case for resolution tracking:
+#     https://github.com/anthropics/claude-code/issues/63469
+#
+# DESIGN NOTES:
+#   - The hook does NOT pin the version. The operator decides.
+#     The hook surfaces the advisory so the operator can decide.
+#   - The semver comparison is done in pure bash (no external
+#     dependencies on sort -V or similar). Each component is
+#     compared numerically; suffix tags (e.g. "-beta") are
+#     stripped.
+#   - When the version output is malformed or the binary is
+#     missing, the hook fails open (exit 0 silent). It does NOT
+#     warn that detection failed — that would be a noise source
+#     in environments where Claude Code is invoked through a
+#     wrapper or shim that doesn't expose --version.
+
+set -u
+
+if [ "${CC_VERSION_PIN_ADVISOR_DISABLE:-0}" = "1" ]; then
+    exit 0
+fi
+if [ "${CC_VERSION_PIN_ADVISOR_QUIET:-0}" = "1" ]; then
+    exit 0
+fi
+
+# Consume stdin if provided (SessionStart hooks receive JSON input)
+if [ ! -t 0 ]; then
+    cat >/dev/null 2>&1 || true
+fi
+
+THRESHOLD="${CC_VERSION_PIN_ADVISOR_THRESHOLD:-2.1.154}"
+
+# Obtain running Claude Code version
+detect_version() {
+    # Prefer env var if set (tests, controlled environments)
+    if [ -n "${CLAUDE_CODE_VERSION:-}" ]; then
+        echo "$CLAUDE_CODE_VERSION"
+        return 0
+    fi
+    local claude_bin="${CC_VERSION_PIN_ADVISOR_CLAUDE_BIN:-}"
+    if [ -z "$claude_bin" ]; then
+        claude_bin=$(command -v claude 2>/dev/null || true)
+    fi
+    if [ -z "$claude_bin" ] || [ ! -x "$claude_bin" ]; then
+        return 1
+    fi
+    local out
+    out=$("$claude_bin" --version 2>/dev/null) || return 1
+    # Output format: "2.1.153 (Claude Code)" or similar
+    # Extract the first semver-looking token
+    echo "$out" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n 1
+}
+
+# Compare two semvers: returns 0 if $1 >= $2, 1 otherwise.
+# Strips suffix tags after a dash.
+semver_gte() {
+    local a="${1%%-*}"
+    local b="${2%%-*}"
+    # Validate format - if either is not "N.N.N", treat as not-comparable
+    case "$a" in
+        *[!0-9.]*) return 1 ;;
+        *) ;;
+    esac
+    case "$b" in
+        *[!0-9.]*) return 1 ;;
+        *) ;;
+    esac
+    local IFS=.
+    local -a parts_a parts_b
+    read -ra parts_a <<< "$a"
+    read -ra parts_b <<< "$b"
+    # Compare up to 3 components
+    local i
+    for i in 0 1 2; do
+        local na="${parts_a[$i]:-0}"
+        local nb="${parts_b[$i]:-0}"
+        # Validate each component is numeric
+        case "$na" in
+            ''|*[!0-9]*) na=0 ;;
+        esac
+        case "$nb" in
+            ''|*[!0-9]*) nb=0 ;;
+        esac
+        if [ "$na" -gt "$nb" ]; then
+            return 0
+        elif [ "$na" -lt "$nb" ]; then
+            return 1
+        fi
+    done
+    # Equal — counts as >=
+    return 0
+}
+
+VERSION=$(detect_version)
+if [ -z "$VERSION" ]; then
+    # Fail open: detection failed, do not warn
+    exit 0
+fi
+
+# Compare against threshold; warn only if at or above
+if ! semver_gte "$VERSION" "$THRESHOLD"; then
+    exit 0
+fi
+
+{
+    echo "ADVISORY: Claude Code $VERSION may hit Cluster 16 (API Error 400 messages[].role 'system')."
+    echo "  Four sub-patterns observed since v$THRESHOLD:"
+    echo "    16A — Custom agents via /agents (Issue #63457, clean rollback to 2.1.153 fully resolves)"
+    echo "    16B — Strict Anthropic-compatible providers (#63366, #63469 has-repro)"
+    echo "    16C — VS Code extension (#63473, #63510)"
+    echo "    16D — Long-lived session context operations after compact/clear/model-switch (#63396 Variant 1)"
+    echo "  Workaround (the only path until upstream fix):"
+    echo "    npm install -g @anthropic-ai/claude-code@2.1.153"
+    echo "    export CLAUDE_CODE_DISABLE_AUTO_UPDATE=1   # add to ~/.bashrc or ~/.zshrc"
+    echo "  Anchor case to subscribe for the upstream fix signal:"
+    echo "    https://github.com/anthropics/claude-code/issues/63469"
+    echo "  Field guide (sub-patterns, architectural axis, comparison to Cluster 8 & 13):"
+    echo "    https://gist.github.com/yurukusa/05c120466996734f7bc2ad6d41fdedec"
+    echo "  Silence after acknowledgment: export CC_VERSION_PIN_ADVISOR_QUIET=1"
+} >&2
+
+exit 0

package/examples/claude-md-reinjector.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+# claude-md-reinjector.sh — Re-inject CLAUDE.md to counter instruction drift
+#
+# Solves: #49244 — Opus 4.6 quality regression starting ~April 15, 2026.
+#         Users report Claude Code ignoring CLAUDE.md instructions, failing
+#         to update memory files, and making repeated mistakes.
+#
+#         Root cause (community-documented): Claude Code wraps CLAUDE.md in
+#         a framing that marks it as "may or may not be relevant", which
+#         reduces its salience after ~50+ tool calls as the conversation
+#         grows. Reported by Microsoft research manager, Fortune, The Register
+#         (April 2026).
+#
+# HOW IT WORKS:
+#   Counts tool calls per session. Every N calls (default 50), prints the
+#   project's CLAUDE.md to stderr. Claude Code reads PreToolUse stderr as
+#   additional context, so this effectively re-injects the instructions
+#   at a cadence the user controls.
+#
+#   Prints a short header marking the injection as a hook-triggered reminder,
+#   so Claude treats the content as an explicit re-statement of rules rather
+#   than part of the current file being edited.
+#
+# WHY THIS MATTERS:
+#   Without re-injection, long sessions drift: Claude "forgets" that the
+#   project bans comments, forgets the test command, forgets naming rules.
+#   The user then has to re-paste CLAUDE.md manually — burning their own
+#   tokens on work the hook can do deterministically.
+#
+# TRIGGER: PreToolUse  MATCHER: ""
+#
+# CONFIGURATION:
+#   CC_MD_REINJECT_EVERY=50       re-inject every N tool calls (default 50)
+#   CC_MD_REINJECT_PATH=path      override CLAUDE.md search (default auto)
+#   CC_MD_REINJECT_MAX_CHARS=2000 truncate long CLAUDE.md (default 2000 chars)
+#   CC_MD_REINJECT_LOG=path       append injection events (default off)
+#
+# SEARCH ORDER for CLAUDE.md:
+#   1. $CC_MD_REINJECT_PATH (if set)
+#   2. $PWD/CLAUDE.md
+#   3. git repo root CLAUDE.md (if inside a git repo)
+#   4. $HOME/CLAUDE.md
+#   5. $HOME/.claude/CLAUDE.md
+
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "default"' 2>/dev/null)
+[ -z "$SESSION_ID" ] && SESSION_ID="default"
+
+EVERY="${CC_MD_REINJECT_EVERY:-50}"
+MAX_CHARS="${CC_MD_REINJECT_MAX_CHARS:-2000}"
+STATE_DIR="/tmp/cc-md-reinject"
+COUNT_FILE="$STATE_DIR/${SESSION_ID}.count"
+
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+# Increment counter
+COUNT=$(cat "$COUNT_FILE" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNT_FILE"
+
+# Only fire on the N-th, 2N-th, 3N-th ... call
+if [ "$((COUNT % EVERY))" -ne 0 ]; then
+    exit 0
+fi
+
+# Locate CLAUDE.md
+find_claude_md() {
+    if [ -n "${CC_MD_REINJECT_PATH:-}" ]; then
+        # Explicit override: respect it. If missing, skip silently (no fallback).
+        [ -f "$CC_MD_REINJECT_PATH" ] && echo "$CC_MD_REINJECT_PATH"
+        return 0
+    fi
+    if [ -f "./CLAUDE.md" ]; then
+        echo "./CLAUDE.md"; return 0
+    fi
+    # Walk up to find git repo root
+    dir="$PWD"
+    while [ "$dir" != "/" ]; do
+        if [ -f "$dir/CLAUDE.md" ]; then
+            echo "$dir/CLAUDE.md"; return 0
+        fi
+        if [ -d "$dir/.git" ]; then
+            break
+        fi
+        dir=$(dirname "$dir")
+    done
+    if [ -f "$HOME/CLAUDE.md" ]; then
+        echo "$HOME/CLAUDE.md"; return 0
+    fi
+    if [ -f "$HOME/.claude/CLAUDE.md" ]; then
+        echo "$HOME/.claude/CLAUDE.md"; return 0
+    fi
+    return 1
+}
+
+MD_FILE=$(find_claude_md)
+if [ -z "$MD_FILE" ]; then
+    # No CLAUDE.md to re-inject — silently skip
+    exit 0
+fi
+
+# Read and truncate
+CONTENT=$(head -c "$MAX_CHARS" "$MD_FILE")
+ACTUAL_SIZE=$(wc -c < "$MD_FILE")
+
+# Print re-injection to stderr (Claude reads this as pre-tool context)
+cat >&2 <<EOF
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[claude-md-reinjector] Tool call #${COUNT} — re-injecting ${MD_FILE}
+Addresses #49244: Claude Code drifting from CLAUDE.md after long sessions.
+These are the rules you already agreed to follow. Re-read and comply.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+${CONTENT}
+EOF
+
+if [ "$ACTUAL_SIZE" -gt "$MAX_CHARS" ]; then
+    echo "" >&2
+    echo "[...truncated at ${MAX_CHARS} chars of ${ACTUAL_SIZE}. Full file: ${MD_FILE}]" >&2
+fi
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" >&2
+
+# Optional log
+if [ -n "${CC_MD_REINJECT_LOG:-}" ]; then
+    mkdir -p "$(dirname "$CC_MD_REINJECT_LOG")" 2>/dev/null
+    echo "$(date -Iseconds) session=${SESSION_ID} count=${COUNT} file=${MD_FILE} size=${ACTUAL_SIZE}" >> "$CC_MD_REINJECT_LOG"
+fi
+
+exit 0

package/examples/claude-md-size-monitor.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# ================================================================
+# claude-md-size-monitor.sh — Warn when CLAUDE.md exceeds the token budget
+# ================================================================
+# 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)
+TOKEN_BUDGET="${CC_CLAUDE_MD_TOKEN_BUDGET:-5000}"
+CHARS_PER_TOKEN="${CC_CLAUDE_MD_CHARS_PER_TOKEN:-3.5}"
+if [ -n "${CC_CLAUDE_MD_FILES:-}" ]; then
+    IFS=':' read -ra MD_FILES <<< "$CC_CLAUDE_MD_FILES"
+else
+    MD_FILES=(
+        "$HOME/.claude/CLAUDE.md"
+        ".claude/CLAUDE.md"
+        "./CLAUDE.md"
+    )
+fi
+FINDINGS=()
+TOTAL_TOKENS=0
+for file in "${MD_FILES[@]}"; do
+    [ -f "$file" ] || continue
+    [ -r "$file" ] || continue
+    CHARS=$(wc -c < "$file" 2>/dev/null | tr -d ' ')
+    [ -z "$CHARS" ] && continue
+    [ "$CHARS" -eq 0 ] && continue
+    TOKENS=$(awk -v c="$CHARS" -v cpt="$CHARS_PER_TOKEN" 'BEGIN { printf "%d", c / cpt }')
+    FINDINGS+=("$file|$CHARS|$TOKENS")
+    TOTAL_TOKENS=$((TOTAL_TOKENS + TOKENS))
+done
+[ ${#FINDINGS[@]} -eq 0 ] && exit 0
+[ "$TOTAL_TOKENS" -le "$TOKEN_BUDGET" ] && exit 0
+OVERAGE=$((TOTAL_TOKENS - TOKEN_BUDGET))
+MSG="DETECTED: CLAUDE.md token budget exceeded.
+Total estimated tokens across all CLAUDE.md files: $TOTAL_TOKENS (budget: $TOKEN_BUDGET, overage: $OVERAGE).
+Every Claude Code session loads these files at startup. The cost is paid on every tool call in the session.
+Per-file breakdown:"
+for finding in "${FINDINGS[@]}"; do
+    IFS='|' read -r path chars tokens <<< "$finding"
+    MSG="$MSG
+  - $path: $chars chars, ~$tokens tokens"
+done
+MSG="$MSG
+Suggested actions:
+  1. Read https://github.com/anthropics/claude-code/issues/42796 for the community discussion of CLAUDE.md token costs.
+  2. Move project-specific instructions to ./.claude/CLAUDE.md and leave global preferences in ~/.claude/CLAUDE.md.
+  3. Convert long examples into separate files referenced by URL rather than inlined.
+  4. Increase the budget if intentional: set CC_CLAUDE_MD_TOKEN_BUDGET=$TOTAL_TOKENS to silence this warning.
+This hook is advisory only. The session continues normally."
+jq -n --arg msg "$MSG" '
+{
+    "hookSpecificOutput": {
+        "hookEventName": "SessionStart",
+        "additionalContext": $msg
+    }
+}'
+exit 0

package/examples/claude-update-budget-guard.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+# claude-update-budget-guard.sh — warn/block `claude update` when 5h quota is tight
+#
+# Solves: #52890 (opened 2026-04-24, v2.1.98, platform:macos, labels area:cost).
+#         A single `claude update` invocation consumed ~7% of the 5-hour budget
+#         and ~3% of the weekly budget on a Max 20x plan — silently. The burn
+#         compounds with Marketplace 404s and 429 retry storms that the user
+#         sees in their logs. Anthropic has not commented on the issue at the
+#         time this hook was written.
+#
+# Event: PreToolUse   Matcher: Bash
+# Action: When a Bash tool call invokes `claude update` / `claude self-update`,
+#         read the remaining 5-hour quota from `claude /usage --json`
+#         (Claude Code >= 2.1.118). If the remaining percentage is below
+#         CLAUDE_UPDATE_BUDGET_THRESHOLD (default 30), either warn (default)
+#         or block (exit 2) — depending on CLAUDE_UPDATE_BUDGET_MODE.
+#         If `/usage --json` is unavailable (earlier version or error), emit
+#         a version-agnostic warning and fall through.
+#
+# Configuration:
+#   CLAUDE_UPDATE_BUDGET_THRESHOLD  percent (default 30). Below this, take action.
+#   CLAUDE_UPDATE_BUDGET_MODE       warn | block (default warn — never breaks CC)
+#   CLAUDE_UPDATE_USAGE_CMD         override probe command (for tests)
+#
+# Exit codes:
+#   0  allow (with warning printed to stderr if threshold crossed)
+#   2  block (only when MODE=block and threshold crossed)
+
+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-claude-update-budget-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [claude-update-budget-guard]: 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)
+
+# Non-Bash tools: nothing to do.
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" != "Bash" ] && exit 0
+
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$CMD" ] && exit 0
+
+# Detect `claude update` / `claude self-update`. Require `claude` as a
+# whole command word so `./claude-update-smart.sh` / `my-claude update` / a
+# commit message mentioning "claude update" don't trigger us.
+if ! printf '%s' "$CMD" | grep -qE '(^|[;&|[:space:]])claude([[:space:]]+[^;&|]*)?[[:space:]]+(update|self-update)(\b|$)'; then
+  exit 0
+fi
+
+THRESHOLD="${CLAUDE_UPDATE_BUDGET_THRESHOLD:-30}"
+MODE="${CLAUDE_UPDATE_BUDGET_MODE:-warn}"
+PROBE="${CLAUDE_UPDATE_USAGE_CMD:-claude /usage --json}"
+
+# Probe remaining quota. Older CC versions (<=2.1.117) do not ship `/usage`;
+# any non-zero exit or non-JSON output means "unknown — warn and continue".
+USAGE_JSON=$(eval "$PROBE" 2>/dev/null || true)
+REMAINING_PCT=""
+if [ -n "$USAGE_JSON" ]; then
+  # Accept several plausible shapes from /usage --json. Real field names may
+  # shift across CC releases; we try the common ones and stop at the first hit.
+  for path in \
+    '.five_hour.remaining_percent' \
+    '.fiveHour.remainingPercent' \
+    '.sessions."5h".remaining_percent' \
+    '.quota.fiveHour.percent_remaining' \
+    '.limits."5h".percent_remaining'; do
+    val=$(printf '%s' "$USAGE_JSON" | jq -r "$path // empty" 2>/dev/null)
+    if [ -n "$val" ] && [ "$val" != "null" ]; then
+      REMAINING_PCT="$val"
+      break
+    fi
+  done
+fi
+
+BANNER='⚠ claude-update-budget-guard: Issue #52890'
+REF='https://github.com/anthropics/claude-code/issues/52890'
+
+if [ -z "$REMAINING_PCT" ]; then
+  {
+    echo "$BANNER"
+    echo "  Cannot read /usage --json (Claude Code < 2.1.118 or probe failed)."
+    echo "  \`claude update\` has been reported to burn ~7% of the 5h budget"
+    echo "  on a single invocation. Consider running the command from a"
+    echo "  separate shell rather than from inside an active CC session."
+    echo "  Ref: $REF"
+  } >&2
+  exit 0
+fi
+
+# Compare with threshold using awk (handles floats).
+CROSSED=$(awk -v r="$REMAINING_PCT" -v t="$THRESHOLD" 'BEGIN { print (r+0 < t+0) ? 1 : 0 }')
+
+if [ "$CROSSED" = "1" ]; then
+  {
+    echo "$BANNER"
+    echo "  5-hour quota remaining: ${REMAINING_PCT}% (threshold: ${THRESHOLD}%)."
+    echo "  \`claude update\` can consume ~7% of the 5h budget in one call."
+    echo "  Running it now may trigger your hard quota limit."
+    echo "  Suggested: skip until the next 5h reset, or run from outside CC."
+    echo "  Ref: $REF"
+  } >&2
+  if [ "$MODE" = "block" ]; then
+    exit 2
+  fi
+  exit 0
+fi
+
+# Quota OK — still post an informational note so the user sees the cost.
+{
+  echo "$BANNER (info)"
+  echo "  5h quota remaining: ${REMAINING_PCT}% — above threshold."
+  echo "  Note: this single update is expected to burn ~7% of your 5h budget."
+} >&2
+exit 0

package/examples/claude-update-smart.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# claude-update-smart.sh — skip 226 MB tarball download when already up-to-date
+# Why: `claude update` downloads the full ~226 MB release tarball on every
+#      invocation, even when the installed version is already latest (Issue
+#      #51243, opened 2026-04-20, platform:wsl, status:open). A typical
+#      connection sees ~30 s wall time per update check and silently burns
+#      metered bandwidth.
+# Fix: Before calling `claude update`, query the npm registry (~2 KB response)
+#      for the latest version. If the installed `claude --version` matches,
+#      exit 0 with "up to date" message and skip the download entirely. Cache
+#      the registry lookup for 1 h to avoid repeated small queries.
+# Install:
+#   cp examples/claude-update-smart.sh ~/bin/claude-update  # shadow the real one
+#   chmod +x ~/bin/claude-update
+# Or alias in your shell rc:
+#   alias claude-update='bash ~/path/to/claude-update-smart.sh'
+#
+# Environment overrides (for tests and offline use):
+#   CLAUDE_UPDATE_SMART_LOCAL=x.y.z    force-reported local version
+#   CLAUDE_UPDATE_SMART_LATEST=x.y.z   force-reported latest version
+#   CLAUDE_UPDATE_SMART_CACHE=<path>   override cache location
+#   CLAUDE_UPDATE_SMART_TTL=<seconds>  override cache TTL (default 3600)
+#   CLAUDE_UPDATE_SMART_NO_EXEC=1      print the decision but do not call `claude update`
+
+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-claude-update-smart-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [claude-update-smart]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+CACHE="${CLAUDE_UPDATE_SMART_CACHE:-${HOME}/.cache/claude-update-smart.json}"
+TTL="${CLAUDE_UPDATE_SMART_TTL:-3600}"
+
+mkdir -p "$(dirname "$CACHE")" 2>/dev/null
+
+# Early bailout: if `claude` CLI is not installed at all and no LOCAL override is
+# in scope, the hook has nothing to do. Common in CI runners and dev containers
+# without Claude Code installed. The `${VAR+x}` test distinguishes "unset" (no
+# scope) from "set to empty" (test fixtures asserting exit-127 fallback).
+if ! command -v claude >/dev/null 2>&1 && [ -z "${CLAUDE_UPDATE_SMART_LOCAL+x}" ]; then
+  echo "claude-update-smart: claude CLI not installed (advisory: nothing to update)" >&2
+  exit 0
+fi
+
+# Resolve LOCAL version.
+if [ -n "${CLAUDE_UPDATE_SMART_LOCAL:-}" ]; then
+  LOCAL="$CLAUDE_UPDATE_SMART_LOCAL"
+else
+  LOCAL=$(claude --version 2>/dev/null | awk '{print $1}')
+fi
+
+if [ -z "${LOCAL:-}" ]; then
+  echo "claude-update-smart: 'claude' not found or --version failed; falling through" >&2
+  if [ "${CLAUDE_UPDATE_SMART_NO_EXEC:-0}" = "1" ]; then
+    exit 127
+  fi
+  exec claude update "$@"
+fi
+
+# Resolve LATEST version (cache → npm → GitHub Releases).
+LATEST=""
+if [ -n "${CLAUDE_UPDATE_SMART_LATEST:-}" ]; then
+  LATEST="$CLAUDE_UPDATE_SMART_LATEST"
+else
+  NOW=$(date +%s)
+  CACHED_TIME=$(stat -c %Y "$CACHE" 2>/dev/null || echo 0)
+  AGE=$((NOW - CACHED_TIME))
+  if [ -s "$CACHE" ] && [ "$AGE" -lt "$TTL" ]; then
+    LATEST=$(jq -r '.latest // empty' "$CACHE" 2>/dev/null)
+  fi
+  if [ -z "$LATEST" ]; then
+    LATEST=$(npm view @anthropic-ai/claude-code version 2>/dev/null | tr -d '[:space:]')
+  fi
+  if [ -z "$LATEST" ]; then
+    LATEST=$(curl -s --max-time 5 https://api.github.com/repos/anthropics/claude-code/releases/latest \
+             | jq -r '.tag_name // empty' 2>/dev/null | sed 's/^v//')
+  fi
+  if [ -n "$LATEST" ]; then
+    printf '{"latest":"%s","checked_at":%s}\n' "$LATEST" "$NOW" > "$CACHE" 2>/dev/null
+  fi
+fi
+
+if [ -z "$LATEST" ]; then
+  echo "claude-update-smart: could not determine latest version (no network?); falling through" >&2
+  if [ "${CLAUDE_UPDATE_SMART_NO_EXEC:-0}" = "1" ]; then
+    echo "decision=fallthrough local=$LOCAL latest=unknown"
+    exit 2
+  fi
+  exec claude update "$@"
+fi
+
+if [ "$LOCAL" = "$LATEST" ]; then
+  echo "Claude Code is up to date ($LOCAL) — skipped 226 MB download (see #51243)"
+  if [ "${CLAUDE_UPDATE_SMART_NO_EXEC:-0}" = "1" ]; then
+    echo "decision=skip local=$LOCAL latest=$LATEST"
+  fi
+  exit 0
+fi
+
+echo "Update available: $LOCAL → $LATEST — running 'claude update'..."
+if [ "${CLAUDE_UPDATE_SMART_NO_EXEC:-0}" = "1" ]; then
+  echo "decision=update local=$LOCAL latest=$LATEST"
+  exit 0
+fi
+exec claude update "$@"

package/examples/claudeignore-enforce-guard.sh

@@ -13,6 +13,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-claudeignore-enforce-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [claudeignore-enforce-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)