cc-safe-setup 29.8.0 → 30.0.4

package/examples/verify-after-publish-reminder.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# verify-after-publish-reminder.sh — Remind to verify persisted state after publish commands
+#
+# Solves: "Silent failure" where a publish command reports success but the
+#         content is not actually visible at the destination. Examples observed:
+#         - Zenn GitHub sync rate-limited the article but `git push` reported success
+#         - Tweet auto-tool reported failure while the tweet was actually live in broken form
+#         - Gumroad CDP form-input updated the DOM value but React state was untouched,
+#           so Save click serialized the old state
+#
+# How it works: After the user runs a Bash command that looks like a publish action,
+#   the hook reads the candidate URL from stdout (if visible) and reminds the user to
+#   verify the persisted state through a second channel (re-fetch the public URL, hit
+#   the article API, or inspect the dashboard). The hook does NOT block — it emits a
+#   reminder so the user catches silent-success failures before logging completion.
+#
+# Detected publish patterns:
+#   - git push (anywhere)
+#   - hashnode-publish, qiita-post, zenn-update, hatena-post, tweet-post
+#   - npm publish, cargo publish, pip publish, gh release create
+#   - cdp-bridge eval ... Save changes
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Bash"
+#
+# CONFIG:
+#   CC_PUBLISH_VERIFY_DISABLE=1   # Disable the reminder entirely
+#
+# This is defense-in-depth, not a complete safeguard. The reminder text is logged to
+# the agent's transcript so the agent sees it on the next turn and is prompted to run
+# the verification before claiming success.
+
+set -euo pipefail
+
+[ "${CC_PUBLISH_VERIFY_DISABLE:-0}" = "1" ] && exit 0
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Patterns that indicate a publish-like action
+PUBLISH_PATTERNS='git[[:space:]]+push|hashnode-publish|qiita-post|zenn-update|hatena-post|tweet-post|note-publish|note-update|npm[[:space:]]+publish|cargo[[:space:]]+publish|pip[[:space:]]+publish|twine[[:space:]]+upload|gh[[:space:]]+release[[:space:]]+create|cdp-bridge[[:space:]].*[Ss]ave[[:space:]]+changes'
+
+if ! printf '%s\n' "$COMMAND" | grep -qE "$PUBLISH_PATTERNS"; then
+    exit 0
+fi
+
+# Identify which platform was published to (best effort)
+PLATFORM="unknown"
+case "$COMMAND" in
+    *hashnode-publish*) PLATFORM="Hashnode" ;;
+    *qiita-post*) PLATFORM="Qiita" ;;
+    *zenn-update*|*zenn-cc-book*) PLATFORM="Zenn" ;;
+    *hatena-post*) PLATFORM="hatena" ;;
+    *tweet-post*) PLATFORM="X (Twitter)" ;;
+    *note-publish*|*note-update*) PLATFORM="note" ;;
+    *npm*publish*) PLATFORM="npm" ;;
+    *cargo*publish*) PLATFORM="crates.io" ;;
+    *pip*publish*|*twine*upload*|*twine[[:space:]]upload*) PLATFORM="PyPI" ;;
+    *gh*release*create*) PLATFORM="GitHub Release" ;;
+    *git*push*) PLATFORM="git remote (may trigger downstream publish via GitHub sync)" ;;
+    *Save*changes*) PLATFORM="dashboard (Gumroad / Ko-fi / other SaaS)" ;;
+esac
+
+cat >&2 <<EOF
+=== verify-after-publish-reminder ===
+A publish-like action was just executed against: ${PLATFORM}
+
+The tool's "success" response is not the same as "the content is live and correct".
+
+Before logging this as completed, verify the persisted state through a second channel:
+
+  1. Re-fetch the public URL or page and confirm HTTP 200 + correct content
+  2. Query the platform's API (article API, product API, etc.) for the new state
+  3. Inspect the platform dashboard for any rate-limit, deployment-failure, or "blocked"
+     notification
+
+Common silent-failure modes to check:
+  - Rate-limit rejection (Zenn 24h window, Twitter 4-8h cadence, API throttle 429)
+  - React-controlled input that did not update internal state (DOM looked right,
+    Save serialized old data)
+  - GitHub sync queued but not yet deployed
+  - Cloudflare / anti-bot intercept that hid content from non-logged-in viewers
+
+If verification fails, treat the publish as NOT done and re-attempt — do not log success
+based on the local command return value alone.
+
+(Set CC_PUBLISH_VERIFY_DISABLE=1 to suppress this reminder.)
+EOF
+
+# Non-blocking reminder (exit 0). The text appears in the transcript and reminds the
+# agent on the next turn.
+exit 0

package/examples/verify-before-commit.sh

@@ -25,6 +25,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-verify-before-commit-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [verify-before-commit]: 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)
 

package/examples/version-bump-detector.sh

@@ -0,0 +1,156 @@
+#!/bin/bash
+# ================================================================
+# version-bump-detector.sh — Detect Claude Code version transitions
+#                            at SessionStart and surface them so the
+#                            operator can correlate quota or behavior
+#                            anomalies with the version change
+# ================================================================
+# PURPOSE:
+#   Claude Code minor versions sometimes ship silent runtime changes
+#   that operators cannot detect from within a session. The existing
+#   version-regression-warner.sh covers a curated list of known-bad
+#   versions; this hook is the dynamic complement — it tells the
+#   operator every time the running CC version changes, regardless
+#   of whether that version is on a known-bad list yet.
+#
+#   The Pro Max quota anomaly cluster on anthropics/claude-code
+#   (~2,200 cumulative reactions across 10 open issues) names four
+#   independent runtime/date boundaries (2026-03-23, v2.1.89,
+#   v2.1.100, 2.1.1) where consumption rate changed silently for
+#   subscribers. When an operator notices "my quota feels off this
+#   week", the first useful question is "did the CC version change
+#   recently?". This hook answers it at session start.
+#
+#   Pairs with the Pro Max Quota Anomaly Operator Field Guide (Gist
+#   158436e88d169406593d55bd84f0d7e9) — Path 5 of the field guide is
+#   "version-bump cross-reference". This hook automates that path.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# OPERATOR-SIDE COMPLEMENT TO:
+#   - version-regression-warner.sh (static known-bad version table)
+#   - cache-creation-drift-detector.sh (per-request token drift)
+#
+# BEHAVIOR:
+#   - First run: records current version, no warning.
+#   - Subsequent run with same version: silent.
+#   - Subsequent run with different version: warns via
+#     hookSpecificOutput.additionalContext with the previous version,
+#     the current version, and pointers to investigate quota drift.
+#   - Maintains a version-history JSONL log for retrospective review.
+#
+# CONFIGURATION (env vars):
+#   CC_VERSION_BUMP_DISABLE   set to "1" to disable entirely
+#   CC_VERSION_BUMP_STATE     state file path (default: ~/.cache/cc-safe-setup/last-cc-version)
+#   CC_VERSION_BUMP_LOG       history log path (default: ~/.cache/cc-safe-setup/cc-version-history.jsonl)
+#   CC_VERSION_BUMP_OVERRIDE  override detected version (testing)
+#
+# Inspect the history:
+#   tail -20 ~/.cache/cc-safe-setup/cc-version-history.jsonl | jq .
+#   jq -s 'map(.version) | unique' ~/.cache/cc-safe-setup/cc-version-history.jsonl
+#
+# RELATED ISSUES (the Pro Max quota anomaly cluster):
+#   https://github.com/anthropics/claude-code/issues/16157
+#   https://github.com/anthropics/claude-code/issues/38335
+#   https://github.com/anthropics/claude-code/issues/46917
+#   https://github.com/anthropics/claude-code/issues/45756
+#   https://github.com/anthropics/claude-code/issues/41788
+# ================================================================
+
+set -u
+
+[ "${CC_VERSION_BUMP_DISABLE:-0}" = "1" ] && exit 0
+
+STATE="${CC_VERSION_BUMP_STATE:-${HOME}/.cache/cc-safe-setup/last-cc-version}"
+LOG="${CC_VERSION_BUMP_LOG:-${HOME}/.cache/cc-safe-setup/cc-version-history.jsonl}"
+
+mkdir -p "$(dirname "$STATE")" 2>/dev/null
+mkdir -p "$(dirname "$LOG")" 2>/dev/null
+
+# Detect the running Claude Code version. Allow override for tests.
+if [ -n "${CC_VERSION_BUMP_OVERRIDE:-}" ]; then
+    CURRENT="$CC_VERSION_BUMP_OVERRIDE"
+else
+    if ! command -v claude >/dev/null 2>&1; then
+        exit 0
+    fi
+    CURRENT=$(claude --version 2>/dev/null \
+        | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' \
+        | head -n 1)
+fi
+
+# If we couldn't detect a version, exit silently.
+if [ -z "$CURRENT" ]; then
+    exit 0
+fi
+
+# Validate the version looks like semver-ish.
+case "$CURRENT" in
+    [0-9]*.[0-9]*.[0-9]*) ;;
+    *) exit 0 ;;
+esac
+
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Read the previously-recorded version. If the state file doesn't
+# exist yet, this is the first run — record and exit silently.
+if [ ! -f "$STATE" ]; then
+    echo "$CURRENT" > "$STATE"
+    printf '{"ts":"%s","version":"%s","event":"first_run"}\n' "$TS" "$CURRENT" >> "$LOG"
+    exit 0
+fi
+
+PREVIOUS=$(cat "$STATE" 2>/dev/null | tr -d '[:space:]')
+
+# Same version as last session — silent.
+if [ "$CURRENT" = "$PREVIOUS" ]; then
+    exit 0
+fi
+
+# Different version — record the transition and warn.
+echo "$CURRENT" > "$STATE"
+printf '{"ts":"%s","version":"%s","previous":"%s","event":"version_bump"}\n' \
+    "$TS" "$CURRENT" "$PREVIOUS" >> "$LOG"
+
+WARNING="===== CLAUDE CODE VERSION BUMP DETECTED =====
+Previous session: ${PREVIOUS}
+Current session:  ${CURRENT}
+
+Some CC versions ship silent runtime changes that operators cannot
+detect from within a session. The Pro Max quota anomaly cluster on
+anthropics/claude-code names four such version/date boundaries
+(2026-03-23, v2.1.89, v2.1.100, 2.1.1).
+
+If you notice unexpected quota consumption, cache_creation token
+counts, or behavior changes in this session vs. recent sessions,
+the version change is a candidate cause. Investigation paths:
+
+- Snapshot a representative \`claude --print\` invocation and compare
+  cache_creation_input_tokens against your trailing baseline. The
+  cache-creation-drift-detector.sh hook automates this comparison.
+- Run \`bunx ccusage daily\` for the last 7 days to spot per-day
+  variance correlated with the bump.
+- Check the Claude Code release notes for ${CURRENT} at
+  https://docs.anthropic.com/en/release-notes for documented changes.
+
+Operator field guide (Path 5 of the Pro Max Quota Anomaly guide):
+https://gist.github.com/yurukusa/158436e88d169406593d55bd84f0d7e9
+===== END VERSION BUMP NOTICE ====="
+
+# Emit hookSpecificOutput so it surfaces at session start.
+if command -v jq >/dev/null 2>&1; then
+    jq -n \
+        --arg ctx "$WARNING" \
+        '{
+            hookSpecificOutput: {
+                hookEventName: "SessionStart",
+                additionalContext: $ctx
+            }
+        }'
+else
+    # Fallback: write to stderr if jq isn't available.
+    echo "$WARNING" >&2
+fi
+
+exit 0

package/examples/version-regression-warner.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# ================================================================
+# version-regression-warner.sh — Surface known silent regressions
+# for the currently-running Claude Code version on SessionStart
+# ================================================================
+# PURPOSE:
+#   Some Claude Code minor versions ship documented or community-
+#   reported silent regressions that operators cannot detect from
+#   within a session. By the time an operator notices the regression,
+#   they've often spent significant time on a workflow that was
+#   broken at startup.
+#
+#   This hook checks the current `claude --version` against a small
+#   table of known-bad versions and surfaces the relevant regression
+#   set at SessionStart, with mitigation guidance per regression.
+#
+#   The table is small on purpose. The bar for inclusion is
+#   "documented silent failure with no in-session error or warning"
+#   — the operator's worst class of bug.
+#
+# TRIGGER: SessionStart
+# MATCHER: (none)
+#
+# CURRENT KNOWN-BAD VERSIONS (2026-05-17):
+#
+#   v2.1.143:
+#     - Issue #59918: --resume with -p containing full history
+#       returns empty response. Mitigation: downgrade to v2.1.138,
+#       or pass only the latest user message in -p on resume.
+#     - Issue #59921: SKILL.md description fields silently dropped
+#       above cumulative-size threshold. Mitigation: shorten
+#       descriptions or split skills into smaller plugin groups.
+#     - Issue #59942: OTel `query_source` attribute silently empty
+#       since 2026-05-13 in both claude-code CLI and Cowork.
+#       Mitigation: monitor per-attribute empty-rate metrics for
+#       sudden jumps.
+#
+#   v2.1.141:
+#     - Issue #59042: streaming-stall regression after v2.1.140 fix.
+#     - Issue #59047: unhandled-case banner on every conversational
+#       turn.
+#
+# CONFIGURATION:
+#   CC_VERSION_WARNER_DISABLE — set to 1 to disable entirely
+#   CC_VERSION_WARNER_VERSION — override detected version (testing)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/59918
+#   https://github.com/anthropics/claude-code/issues/59921
+#   https://github.com/anthropics/claude-code/issues/59942
+#   https://github.com/anthropics/claude-code/issues/59042
+#   https://github.com/anthropics/claude-code/issues/59047
+# ================================================================
+
+set -u
+
+[ "${CC_VERSION_WARNER_DISABLE:-0}" = "1" ] && exit 0
+
+# Detect the running Claude Code version. Allow override for tests.
+if [ -n "${CC_VERSION_WARNER_VERSION:-}" ]; then
+    VERSION="$CC_VERSION_WARNER_VERSION"
+else
+    if ! command -v claude >/dev/null 2>&1; then
+        exit 0
+    fi
+    # `claude --version` typically outputs something like
+    # "2.1.143 (Claude Code)" or "claude-code v2.1.143". We just
+    # want the semver. Strip everything that is not [0-9.] and
+    # take the first match.
+    VERSION=$(claude --version 2>/dev/null \
+        | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' \
+        | head -n 1)
+fi
+
+[ -z "$VERSION" ] && exit 0
+
+# Build the warning text only if the version matches a known-bad
+# version. Add new entries here as silent regressions are documented.
+WARNING=""
+
+case "$VERSION" in
+    "2.1.143")
+        WARNING="===== KNOWN SILENT REGRESSIONS IN v2.1.143 =====
+You are running Claude Code v2.1.143, which has three documented
+silent regressions that operators cannot detect from within a
+session. Each is listed with its mitigation.
+
+1. Issue #59918 — \`--resume\` with full \`-p\` history returns
+   empty response. No error, just finish_reason:stop with empty
+   delta. Mitigation: downgrade to v2.1.138, or pass only the
+   latest user message in -p on resume (not full history).
+
+2. Issue #59921 — SKILL.md description fields silently dropped
+   from the available-skills system reminder when cumulative
+   description size exceeds an internal threshold. Mitigation:
+   if you have >100 skills, shorten descriptions or split into
+   smaller plugin groups. Cross-check installed-vs-visible
+   descriptions in your system prompt.
+
+3. Issue #59942 — OTel \`query_source\` attribute silently empty
+   on \`api_request\` events and \`cost.usage\` / \`token.usage\`
+   counter metrics since 2026-05-13, in both claude-code CLI and
+   Cowork. Same shape as the v2.1.122 \`cost_usd\` drop. If you
+   rely on \`query_source\` for cost allocation, monitor your
+   pipeline's per-attribute empty-rate.
+
+These regressions do not surface in-session. If your workflow
+touches resume + -p, large skill collections, or OTel-based cost
+allocation, verify behavior before relying on it.
+===== END WARNING ====="
+        ;;
+    "2.1.141")
+        WARNING="===== KNOWN REGRESSIONS IN v2.1.141 =====
+You are running Claude Code v2.1.141, shipped a few hours after
+v2.1.140's documented silent-failure fixes. Two regressions of the
+same shape surfaced immediately:
+
+1. Issue #59042 — streaming-stall regression.
+
+2. Issue #59047 — unhandled-case banner on every conversational
+   turn.
+
+Consider upgrading to a later patch version or pinning v2.1.138 if
+this version's behavior blocks your workflow.
+===== END WARNING ====="
+        ;;
+    *)
+        # No known-bad regressions for this version.
+        exit 0
+        ;;
+esac
+
+[ -z "$WARNING" ] && exit 0
+
+jq -n \
+    --arg ctx "$WARNING" \
+    '{
+        hookSpecificOutput: {
+            hookEventName: "SessionStart",
+            additionalContext: $ctx
+        }
+    }'
+
+exit 0

package/examples/vue-lint-on-edit.sh

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

package/examples/warn-cron-cost-trap.sh

@@ -0,0 +1,173 @@
+#!/bin/bash
+# ================================================================
+# warn-cron-cost-trap.sh — Warn on cost-trap scheduled tasks
+# ================================================================
+# PURPOSE:
+#   When the model calls CronCreate with a SHORT fire interval AND
+#   recurring=true, emit a cost warning. Short-interval recurring
+#   schedules are a silent money trap: every fire re-loads the whole
+#   conversation as a fresh full turn, so the per-fire cost climbs
+#   roughly quadratically with the number of fires in a session.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "CronCreate"
+#
+# WHY THIS MATTERS:
+#   A recurring CronCreate does not run cheaply in the background.
+#   Each fire is a complete turn that re-reads the accumulated
+#   conversation history, so cost per fire grows as the session
+#   grows. A */5 (every 5 min) recurring job left running overnight
+#   can fire ~200 times, each one more expensive than the last.
+#   Issue #74547 reports ~USD 500 burned by an 11-minute recurring
+#   schedule that did nothing but poll an empty directory 88 times
+#   in 16 hours. The registration itself is silent — nothing warns
+#   the operator that the interval times the growing context equals
+#   a quadratic bill.
+#
+#   This hook is advisory. It never blocks CronCreate; it prints a
+#   one-time warning so the operator can widen the interval, set
+#   recurring=false, or move the poll to an external scheduler that
+#   does not re-load the conversation each fire.
+#
+# WHAT IT CHECKS:
+#   Parses .tool_input.cron and .tool_input.recurring. It derives the
+#   smallest gap (in minutes) between consecutive fires from the
+#   MINUTE field of the cron expression — the field that actually
+#   drives short intervals:
+#     *            -> 1 minute   (fires every minute)
+#     */N or .../N -> N minutes  (step)
+#     a,b,c,...    -> smallest consecutive gap, with 60-wraparound
+#     A-B (range)  -> 1 minute (fires every minute within the range)
+#     single value -> 60 minutes (fires at most hourly -> safe)
+#   Warns unless recurring is explicitly false, AND the derived interval is
+#   below the threshold (default 15 minutes). An omitted recurring defaults
+#   to recurring, so the omitted short-interval case is included.
+#
+# DEFENSIVE BEHAVIOR:
+#   - Always exits 0 (advisory only, never blocks)
+#   - Skips silently if jq is missing
+#   - Skips silently if no cron expression is present
+#   - Treats an unparseable minute field as safe (no false alarm)
+#
+# CONFIGURATION (environment variables):
+#   CC_CRON_COST_TRAP_DISABLE=1        skip the hook entirely
+#   CC_CRON_COST_TRAP_THRESHOLD_MIN=N  interval below N warns (default 15)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/74547  (~USD 500 no-op polling spend)
+#
+# PAIR WITH:
+#   cron-create-receipt.sh   (logs every registration for later audit)
+#   daily-cost-guard.sh      (tracks accumulated spend)
+#
+# TRIGGER: PostToolUse  MATCHER: "CronCreate"
+# ================================================================
+
+set -u
+
+# Skip if disabled
+if [ "${CC_CRON_COST_TRAP_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Skip if jq is missing — we cannot parse tool_input without it
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+THRESHOLD="${CC_CRON_COST_TRAP_THRESHOLD_MIN:-15}"
+# Numeric guard on the threshold
+case "$THRESHOLD" in
+  ''|*[!0-9]*) THRESHOLD=15 ;;
+esac
+
+INPUT=$(cat)
+
+CRON_EXPR=$(printf '%s' "$INPUT" | jq -r '.tool_input.cron // empty' 2>/dev/null)
+# Take the raw value: do NOT use jq's // default here. jq's // returns the
+# right-hand side when the left is null OR false, so `recurring // false`
+# would collapse an explicit `false` into the default and misfire.
+RECURRING=$(printf '%s' "$INPUT" | jq -r '.tool_input.recurring' 2>/dev/null)
+
+# Nothing to do if there is no cron expression
+[ -z "$CRON_EXPR" ] && exit 0
+
+# Only recurring schedules have the compounding trap. Exclude a schedule ONLY
+# when recurring is explicitly false (a genuine one-shot fire). When recurring
+# is omitted, CronCreate defaults to recurring, so an omitted short-interval
+# registration — the most dangerous form — must still be caught.
+[ "$RECURRING" = "false" ] && exit 0
+
+# Extract the minute field (first whitespace-separated field)
+MINUTE=$(printf '%s' "$CRON_EXPR" | awk '{print $1}')
+[ -z "$MINUTE" ] && exit 0
+
+# Derive the smallest interval (in minutes) between consecutive fires
+# from the minute field alone. This is the practical driver of the trap.
+INTERVAL=$(printf '%s' "$MINUTE" | awk '
+  {
+    f = $0
+    # Step form: anything containing "/N" fires every N minutes
+    if (f ~ /\//) {
+      n = f
+      sub(/.*\//, "", n)
+      if (n ~ /^[0-9]+$/ && n+0 > 0) { print n+0; next }
+    }
+    # Every minute
+    if (f == "*") { print 1; next }
+    # Comma list of explicit minutes: smallest consecutive gap with wraparound
+    if (f ~ /,/) {
+      n = split(f, parts, ",")
+      cnt = 0
+      for (i = 1; i <= n; i++) {
+        v = parts[i]
+        if (v ~ /^[0-9]+$/) { vals[cnt++] = v+0 }
+      }
+      if (cnt < 2) { print 60; next }
+      # simple insertion sort
+      for (i = 1; i < cnt; i++) {
+        key = vals[i]; j = i - 1
+        while (j >= 0 && vals[j] > key) { vals[j+1] = vals[j]; j-- }
+        vals[j+1] = key
+      }
+      mingap = 60
+      for (i = 1; i < cnt; i++) {
+        gap = vals[i] - vals[i-1]
+        if (gap < mingap) mingap = gap
+      }
+      wrap = (60 - vals[cnt-1]) + vals[0]
+      if (wrap < mingap) mingap = wrap
+      if (mingap < 1) mingap = 1
+      print mingap; next
+    }
+    # Range without step (e.g. 0-30) fires every minute within the range,
+    # so its interval is 1 minute — one of the most expensive forms.
+    if (f ~ /^[0-9]+-[0-9]+$/) { print 1; next }
+    # Single value -> at most once per hour -> safe
+    print 60
+  }
+')
+
+# Guard: if awk produced nothing numeric, treat as safe
+case "$INTERVAL" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+
+if [ "$INTERVAL" -lt "$THRESHOLD" ]; then
+  cat >&2 <<EOF
+[warn-cron-cost-trap] COST TRAP: recurring CronCreate fires about every ${INTERVAL} min.
+  cron: "$CRON_EXPR"  recurring: true
+  Each fire re-loads the whole conversation as a fresh full turn, so per-fire
+  cost grows with the session — the total climbs roughly quadratically with the
+  number of fires. Left overnight, a short-interval recurring job can fire
+  hundreds of times, each one more expensive than the last (issue #74547 burned
+  ~USD 500 polling an empty directory 88 times in 16 hours).
+  Fixes: widen the interval (>= ${THRESHOLD} min), set recurring=false for a
+  one-shot, or move the poll to an external scheduler that does not re-load the
+  conversation each fire.
+  Set CC_CRON_COST_TRAP_DISABLE=1 to suppress this warning.
+EOF
+fi
+
+# Always exit 0 — advisory only, never blocks CronCreate
+exit 0

package/examples/webfetch-runaway-guard.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+# webfetch-runaway-guard.sh — Cap a runaway sequence of WebFetch tool calls that burns cost
+#
+# Solves: When a research subagent is told to gather many sources, denying a
+# single WebFetch is treated as "skip this one" rather than "stop and
+# summarize" — so the agent moves to the next URL and keeps fetching. In #65684
+# this ran ~98 WebFetch calls (~$1.15) before the user force-killed it with
+# Ctrl+C, and the context from the earlier fetches was lost because the agent
+# never paused to synthesize.
+#
+# Existing hooks miss this exact shape:
+#   - loop-detector.sh keys on the *same* command repeating; a runaway fetches
+#     a *different* URL each call, so it never matches.
+#   - api-rate-limit-tracker.sh matches Bash curl/wget/http; the WebFetch *tool*
+#     is a separate tool, not a Bash command.
+#   - session-rate-monitor.sh is advisory token-rate only and never blocks.
+#   - webfetch-domain-allow.sh is the opposite purpose (auto-approve allowlist).
+#
+# This counts WebFetch *tool* calls in a rolling time window (per session) and,
+# once the count crosses a threshold, blocks with a message telling the model to
+# stop fetching and summarize what it already has — the behavior the operator
+# wanted when they started denying calls. A hard block (not just a warning) is
+# what actually caps the spend, since the runaway already ignored the denials.
+#
+# Defaults are generous so ordinary research is untouched: it takes 50 fetches
+# inside 5 minutes to block. The window ages out on its own, so once the model
+# summarizes and stops, the next genuine research run starts from zero.
+#
+# TRIGGER: PreToolUse  MATCHER: "WebFetch"
+# Config (all optional):
+#   CC_WEBFETCH_RUNAWAY_GUARD=block   block | warn | off
+#   CC_WEBFETCH_RUNAWAY_BLOCK=50      block once this many fetches fall inside the window
+#   CC_WEBFETCH_RUNAWAY_WARN=30       warn (stderr, non-blocking) at this many
+#   CC_WEBFETCH_RUNAWAY_WINDOW=300    rolling window in seconds
+#   CC_WEBFETCH_RUNAWAY_DIR           state dir (default: /tmp/cc-webfetch-runaway)
+# Related: https://github.com/anthropics/claude-code/issues/65684
+
+INPUT=$(cat)
+
+MODE="${CC_WEBFETCH_RUNAWAY_GUARD:-block}"
+[ "$MODE" = "off" ] && exit 0
+
+# Only act on the WebFetch tool. Fail open on anything unexpected.
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" != "WebFetch" ] && exit 0
+
+BLOCK_AT="${CC_WEBFETCH_RUNAWAY_BLOCK:-50}"
+WARN_AT="${CC_WEBFETCH_RUNAWAY_WARN:-30}"
+WINDOW="${CC_WEBFETCH_RUNAWAY_WINDOW:-300}"
+case "$BLOCK_AT" in ''|*[!0-9]*) exit 0;; esac
+case "$WARN_AT" in ''|*[!0-9]*) exit 0;; esac
+case "$WINDOW" in ''|*[!0-9]*) exit 0;; esac
+
+# Key state per session so one session's research never trips another's guard.
+SID=$(printf '%s' "$INPUT" | jq -r '.session_id // "default"' 2>/dev/null)
+case "$SID" in ''|*[!A-Za-z0-9_-]*) SID="default";; esac
+
+STATE_DIR="${CC_WEBFETCH_RUNAWAY_DIR:-/tmp/cc-webfetch-runaway}"
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+STATE="$STATE_DIR/$SID"
+
+NOW=$(date +%s)
+CUTOFF=$((NOW - WINDOW))
+
+# Record this call, then keep only timestamps inside the window.
+echo "$NOW" >> "$STATE" 2>/dev/null
+if [ -f "$STATE" ]; then
+    awk -v c="$CUTOFF" '$1 ~ /^[0-9]+$/ && $1 >= c' "$STATE" > "$STATE.tmp" 2>/dev/null && mv "$STATE.tmp" "$STATE" 2>/dev/null
+fi
+
+COUNT=$(wc -l < "$STATE" 2>/dev/null | tr -d ' ')
+case "$COUNT" in ''|*[!0-9]*) exit 0;; esac
+
+MINS=$((WINDOW / 60))
+MSG="This is WebFetch call ${COUNT} within ${MINS} min. A research loop is fetching URL after URL without pausing to synthesize — in #65684 this reached ~98 fetches (~\$1.15) before it was force-killed, and the earlier results were wasted. Stop fetching now and write your answer from the sources you already have; open another fetch only if a specific gap remains. To allow a deeper sweep, raise CC_WEBFETCH_RUNAWAY_BLOCK, set CC_WEBFETCH_RUNAWAY_GUARD=warn to only warn, or =off to disable. State resets after ${WINDOW}s of no fetches: ${STATE}"
+
+if [ "$COUNT" -ge "$BLOCK_AT" ]; then
+    if [ "$MODE" = "warn" ]; then
+        echo "webfetch-runaway-guard: $MSG" >&2
+        exit 0
+    fi
+    # block (default): structured decision so the model sees the reason.
+    jq -n --arg r "$MSG" '{decision: "block", reason: $r}'
+    exit 0
+elif [ "$COUNT" -ge "$WARN_AT" ]; then
+    echo "webfetch-runaway-guard: WebFetch call ${COUNT} within ${MINS} min — consider summarizing what you have before fetching more (#65684). Blocks at ${BLOCK_AT}." >&2
+fi
+
+exit 0