cc-safe-setup 29.7.0 → 30.0.4

package/examples/cowork-hook-absence-warner.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+# ================================================================
+# cowork-hook-absence-warner.sh — Warn CLI operators with a non-trivial
+#                                 ~/.claude/settings.json hook stack
+#                                 that the Cowork sandbox silently
+#                                 drops every one of those hooks
+# ================================================================
+# PURPOSE:
+#   Cluster 11 sub-pattern 11E (Hook surface absence) documents that
+#   the Cowork sandbox does not fire any hook defined in
+#   ~/.claude/settings.json. The operator-side defense surface that
+#   14-day-active 1,582+ cc-safe-setup users rely on (UserPromptSubmit,
+#   Stop, PostToolUse, PreToolUse, SessionStart) is silently inert
+#   once the operator switches to a Cowork session.
+#
+#   Cluster 11 axis 11E issues:
+#     #63360 — Cowork: Support Claude Code hooks (~/.claude/settings.json
+#              — UserPromptSubmit, Stop, etc.) — feature request, 2026-05-28
+#     #63047 — Plugin PostToolUse hooks still silently skip in Claude
+#              Desktop / Cowork (re-filing closed #51904) — re-filing
+#              with 7+ weeks of additional evidence, 2026-05-28
+#     #51904 — original report, auto-closed for inactivity
+#     #51281 — April 2026, French — auto-closed
+#     #27398 — February 2026 — auto-closed as duplicate
+#
+#   The operator who installed a serious hook stack on the CLI surface
+#   for cluster-1-19 defense will, on switching to Cowork, lose all of
+#   that defense without any visible signal. This hook runs at
+#   SessionStart on the CLI side, reads the operator's hook stack from
+#   ~/.claude/settings.json, and — when the stack is non-trivial — once
+#   per calendar day surfaces a stderr advisory: "your N hooks do not
+#   fire in Cowork; here are the three operator-side workarounds."
+#
+#   The hook does NOT block. The advisory is a one-shot per calendar
+#   day so multi-session-per-day operators are not nagged repeatedly.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+# EXIT:    0 (always; advisory only)
+#
+# SETUP:
+#   {
+#     "hooks": {
+#       "SessionStart": [
+#         { "matcher": "",
+#           "hooks": [
+#             { "type": "command",
+#               "command": "bash ~/path/to/cowork-hook-absence-warner.sh"
+#             }
+#           ]
+#         }
+#       ]
+#     }
+#   }
+#
+# CONFIGURATION:
+#   CC_COWORK_WARNER_DISABLE=1     — silence the hook entirely
+#   CC_COWORK_WARNER_STATE_DIR=PATH — override state dir
+#                                     (default $HOME/.claude)
+#   CC_COWORK_WARNER_DATE=YYYY-MM-DD — date override (tests only)
+#   CC_COWORK_WARNER_SETTINGS=PATH — settings file path override
+#                                    (default $HOME/.claude/settings.json)
+#   CC_COWORK_WARNER_MIN_HOOKS=N  — min hook count to trigger advisory
+#                                   (default 1)
+#
+# RELATED CLUSTER 11 SHIPPED TOOLS:
+#   - cowork-claudemd-helper.sh    (standalone, addresses 11A #62859)
+#   - cowork-claude-md-load-checker.sh (CLI-side, addresses 11A #62859)
+#   - cowork-fuse-staleness-watcher.sh (CLI-side, addresses 11A #62932)
+#   - cowork-model-picker-advisor.sh (CLI-side, addresses 11C #62949)
+#
+# WHAT THIS HOOK ADDS:
+#   The four shipped tools above address 11A and 11C. 11E (hook
+#   surface absence) was not covered until this hook. The defense
+#   surface for 11E is "warn the operator who has the most to lose"
+#   — the operator whose CLI hook stack carries real defense value.
+# ================================================================
+
+set -uo pipefail
+
+[ "${CC_COWORK_WARNER_DISABLE:-0}" = "1" ] && exit 0
+
+SETTINGS="${CC_COWORK_WARNER_SETTINGS:-${HOME}/.claude/settings.json}"
+STATE_DIR="${CC_COWORK_WARNER_STATE_DIR:-${HOME}/.claude}"
+MIN_HOOKS="${CC_COWORK_WARNER_MIN_HOOKS:-1}"
+
+# If no settings file, the operator has no hook stack to lose.
+[ ! -f "$SETTINGS" ] && exit 0
+
+# Count hooks across all event types. We count the leaf commands, not
+# the matcher entries, so {"Stop":[{"matcher":"","hooks":[a,b,c]}]}
+# correctly reports 3 hooks (not 1 matcher).
+HOOK_COUNT=$(jq -r '
+    (.hooks // {})
+    | [.SessionStart, .UserPromptSubmit, .Stop, .PreToolUse, .PostToolUse, .PreCompact, .Notification]
+    | map(. // [])
+    | map([.[]? | .hooks // [] | .[]?] | length)
+    | add
+' "$SETTINGS" 2>/dev/null)
+
+# If jq failed or returned non-numeric, exit silently.
+case "$HOOK_COUNT" in
+    ''|*[!0-9]*) exit 0 ;;
+esac
+
+# Below the threshold → not worth warning about.
+[ "$HOOK_COUNT" -lt "$MIN_HOOKS" ] && exit 0
+
+# One-shot per calendar day.
+TODAY="${CC_COWORK_WARNER_DATE:-}"
+if [ -z "$TODAY" ]; then
+    TODAY=$(date '+%Y-%m-%d' 2>/dev/null) || exit 0
+fi
+
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+STATE_FILE="$STATE_DIR/cowork-hook-absence-warner.last"
+
+if [ -f "$STATE_FILE" ]; then
+    LAST_DATE=$(head -1 "$STATE_FILE" 2>/dev/null)
+    if [ "$LAST_DATE" = "$TODAY" ]; then
+        exit 0
+    fi
+fi
+
+# Stamp the state file BEFORE emitting (crash-mid-emit doesn't re-fire).
+printf '%s\n' "$TODAY" > "$STATE_FILE" 2>/dev/null || true
+
+cat >&2 <<EOF
+
+[cowork-hook-absence-warner] NOTE: your ${HOOK_COUNT} CLI hooks do not
+fire in the Cowork sandbox.
+
+Cluster 11 sub-pattern 11E (Hook surface absence) — issues #63360 and
+#63047 (re-filing of #51904) — documents that Cowork's GUI sandbox is
+a different distribution surface than the CLI or Desktop, and
+~/.claude/settings.json hooks are silently inert in it. Your
+${HOOK_COUNT} configured hooks (across SessionStart, UserPromptSubmit,
+Stop, PreToolUse, PostToolUse, PreCompact, Notification) will not
+provide defense when you switch to a Cowork session.
+
+Three operator-side workarounds:
+
+  1. **Delay Cowork adoption for hook-dependent workflows.** If your
+     hook stack carries real defense value (cluster-1/9/13/19 type
+     coverage), continue using the CLI for that work until upstream
+     #63360 lands.
+
+  2. **Manual execution at Cowork boundaries.** For each hook your
+     CLI workflow relies on, document the manual equivalent you'll
+     run before and after a Cowork session (the cowork-claudemd-helper
+     standalone script is the model for this — manual replication of
+     what the SessionStart hook would have done).
+
+  3. **CLI-only for sensitive operations.** Restrict Cowork to
+     low-defense-value tasks (read-only exploration, documentation
+     review, etc.) and keep code execution / destructive ops / cost-
+     sensitive work in the CLI where your hooks apply.
+
+This reminder fires once per calendar day. To silence it:
+  export CC_COWORK_WARNER_DISABLE=1
+
+Tracked at https://github.com/yurukusa/cc-safe-setup/blob/main/docs/cluster-tracker.html
+(Cluster 11, sub-pattern 11E).
+
+EOF
+
+exit 0

package/examples/cowork-model-picker-advisor.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# cowork-model-picker-advisor.sh — Surface the Cowork Sonnet 4.6 [1m] silent
+# default at SessionStart so CLI users do not accidentally burn usage credits
+#
+# Solves: #62949 — Claude Cowork Desktop only presents a single Sonnet 4.6
+#         option in the model picker. It silently defaults to the 1M context
+#         variant, which requires usage credits even on a fresh session at
+#         low plan usage on Max (5x). The documented behavior — separate
+#         `sonnet` and `sonnet[1m]` entries — is missing in Cowork. CLI
+#         users can use `--model` to force standard 200K context; Cowork
+#         users have no workaround until the picker is fixed. Related:
+#         #61869, #62100, #61692.
+#
+#         Also covers #62199 — the same silent 1M default reaches the plain
+#         CLI and the VS Code extension, where CLAUDE_CODE_DISABLE_1M_CONTEXT=1
+#         is reported NOT to be respected. For users already mid-session
+#         draining their 5h/weekly limit, the reliable fix is the in-session
+#         `/model claude-opus-4-7` (or any non-[1m] model), not just the
+#         launch-time `--model`.
+#
+# WHO THIS PROTECTS:
+#   CLI users who:
+#     - leave ANTHROPIC_MODEL unset and may inherit the same silent 1M
+#       default Cowork enforces;
+#     - explicitly set ANTHROPIC_MODEL to a 1m variant and want a reminder
+#       that this consumes usage credits separately from the plan;
+#     - also use Cowork on the same machine and benefit from a clear
+#       articulation of the picker bug + the CLI-only workaround.
+#
+# HOW IT WORKS:
+#   On SessionStart:
+#     1. Check $ANTHROPIC_MODEL.
+#     2. If unset or contains "1m" / "[1m]" / "1M", print stderr block:
+#          - explains #62949 and the silent 1M default
+#          - explains how to force standard 200K context via --model
+#          - links related issues
+#     3. If set to a non-1m model, print a one-line confirmation (suppressible
+#        with CC_COWORK_MODEL_QUIET=1).
+#   Always exit 0 (advisory).
+#
+# TRIGGER: SessionStart  MATCHER: ""
+#
+# CONFIGURATION:
+#   CC_COWORK_MODEL_QUIET=1       suppress the confirmation line for safe models
+#   CC_COWORK_MODEL_LOG=path      append model-check events (default off)
+#   CC_COWORK_MODEL_FORCE_WARN=1  always show the full warning regardless of env
+#
+# USAGE:
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "hooks": [{
+#         "type": "command",
+#         "command": "~/.claude/hooks/cowork-model-picker-advisor.sh"
+#       }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat 2>/dev/null || true)
+
+MODEL="${ANTHROPIC_MODEL:-}"
+
+is_1m_variant=0
+if [ -z "$MODEL" ]; then
+    is_1m_variant=1  # unset means we may inherit Cowork's silent 1M default
+elif echo "$MODEL" | grep -qiE '(\[1m\]|-1m|_1m|1m$|1M)'; then
+    is_1m_variant=1
+fi
+
+if [ -n "${CC_COWORK_MODEL_FORCE_WARN:-}" ]; then
+    is_1m_variant=1
+fi
+
+if [ "$is_1m_variant" -eq 1 ]; then
+    cat >&2 <<EOF
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[cowork-model-picker-advisor] SessionStart — model exposure check
+ANTHROPIC_MODEL='${MODEL:-(unset)}'
+
+Addresses #62949: Claude Cowork Desktop silently defaults to Sonnet 4.6
+[1m] (1M context). The picker shows only one Sonnet 4.6 option; the
+standard 200K context variant is NOT selectable. The 1M variant requires
+usage credits separately from Max-plan inclusion, so a Cowork session
+at ~9% plan usage can still trip:
+
+  API Error: Usage credits required for 1M context
+
+CLI workaround (Cowork has none until the picker is fixed):
+  --model claude-sonnet-4-6      # forces standard 200K context
+  --model claude-haiku-4-5       # smaller, plan-included
+  Or: export ANTHROPIC_MODEL=claude-sonnet-4-6 in your shell init.
+
+The same silent 1M default also hits the plain CLI and the VS Code
+extension, not only Cowork (#62199). CLAUDE_CODE_DISABLE_1M_CONTEXT=1 is
+reported NOT to be respected by the VS Code extension, so if you are
+already inside a session and watching the 5h/weekly limit drain, the
+reliable fix is the in-session command (no restart needed):
+  /model claude-opus-4-7         # switches immediately; any non-[1m] model
+
+Related issues: #62199 #61869 #62100 #61692
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EOF
+else
+    if [ -z "${CC_COWORK_MODEL_QUIET:-}" ]; then
+        echo "[cowork-model-picker-advisor] ANTHROPIC_MODEL=${MODEL} — standard context, not 1m. No usage-credit risk from #62949." >&2
+    fi
+fi
+
+if [ -n "${CC_COWORK_MODEL_LOG:-}" ]; then
+    mkdir -p "$(dirname "$CC_COWORK_MODEL_LOG")" 2>/dev/null
+    echo "$(date -Iseconds) model=${MODEL:-unset} is_1m=${is_1m_variant}" >> "$CC_COWORK_MODEL_LOG"
+fi
+
+exit 0

package/examples/credential-exfil-guard.sh

@@ -9,6 +9,7 @@
 #   find / -name "*.token" -o -name "*credentials*"
 #   cat ~/.ssh/id_rsa
 #   printenv | grep SECRET
+#   env | grep JIRA        (warns — an env dump piped to grep prints values even when the term is not a secret keyword, #69053)
 #   cat /etc/shadow
 #
 # Usage: Add to settings.json as a PreToolUse hook
@@ -24,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-credential-exfil-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [credential-exfil-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)
 
@@ -35,6 +48,16 @@ if echo "$COMMAND" | grep -qiE '(env|printenv|set)\s*\|.*grep.*\b(token|secret|k
     exit 2
 fi
 
+# Pattern 1b: env/printenv piped to grep by a NON-secret term still dumps the
+# matching live VALUES. In #69053, `env | grep JIRA` dumped JIRA_API_TOKEN — the
+# filter term ("JIRA") is not a secret keyword so Pattern 1 misses it, and it is
+# not a bare dump so Pattern 7 misses it, so it passed silently. Warn (not block)
+# to stay consistent with Pattern 7 and avoid over-blocking benign `env | grep PATH`.
+if echo "$COMMAND" | grep -qiE '(env|printenv|set)\s*\|.*grep'; then
+    echo "WARNING: piping an environment dump to grep prints the matching live values into the transcript/API; if a matched variable holds a token it is now exposed (#69053). To find where a credential is configured, grep config files for the variable NAME instead of dumping environment values." >&2
+    exit 0
+fi
+
 # Pattern 2: find searching for credential files
 if echo "$COMMAND" | grep -qiE 'find\s.*-name\s.*\*?(token|secret|credential|password|\.key|\.pem|\.p12|\.pfx|\.keystore|\.jks|\.env)'; then
     echo "BLOCKED: Credential hunting via file system search" >&2
@@ -42,7 +65,13 @@ if echo "$COMMAND" | grep -qiE 'find\s.*-name\s.*\*?(token|secret|credential|pas
 fi
 
 # Pattern 3: Direct access to known credential locations
-if echo "$COMMAND" | grep -qE 'cat\s+(~|/home|/root)/.ssh/(id_|authorized_keys|known_hosts|config)'; then
+# 2026-08-30: the home alternation used to be (~|/home|/root), which only matches
+#   when /.ssh follows /home directly. Real paths carry a username segment
+#   (/home/alice/.ssh/id_rsa), so the tilde form was blocked while the expanded
+#   form walked straight through - measured on this machine, rc=2 vs rc=0 for the
+#   same file. Whether an agent writes the tilde or the expanded path is arbitrary,
+#   so a guard that only sees one of them is a coin flip.
+if echo "$COMMAND" | grep -qE 'cat\s+(~|/home/[^/[:space:]]+|/Users/[^/[:space:]]+|/root|/home|/Users)/\.ssh/(id_|authorized_keys|known_hosts|config)'; then
     echo "BLOCKED: Direct SSH credential access" >&2
     exit 2
 fi
@@ -54,7 +83,7 @@ if echo "$COMMAND" | grep -qE 'cat\s+(/etc/shadow|/etc/gshadow|/etc/passwd)'; th
 fi
 
 # Pattern 5: AWS/cloud credential files
-if echo "$COMMAND" | grep -qE 'cat\s+(~|/home|/root)/\.(aws|gcloud|azure|kube)/(credentials|config|token)'; then
+if echo "$COMMAND" | grep -qE 'cat\s+(~|/home/[^/[:space:]]+|/Users/[^/[:space:]]+|/root|/home|/Users)/\.(aws|gcloud|azure|kube)/(credentials|config|token)'; then
     echo "BLOCKED: Cloud provider credential access" >&2
     exit 2
 fi
@@ -73,15 +102,47 @@ if echo "$COMMAND" | grep -qE '^\s*(env|printenv|set)\s*$'; then
 fi
 
 # Pattern 8: curl/wget posting credential files
-if echo "$COMMAND" | grep -qiP 'curl\s.*-d\s+@[^\s]*(\.env|\.pem|\.key|credentials|\.ssh/id_)|wget\s.*--post-file[= ][^\s]*(\.env|\.pem|\.key|credentials|\.ssh/id_)'; then
+# Uses -E, not -P: BSD grep (macOS) rejects -P outright, which made this block
+# exit 0 and let the upload through. \s/\S are Perl-only, so they are written as
+# POSIX classes here.
+if echo "$COMMAND" | grep -qiE 'curl[[:space:]].*-d[[:space:]]+@[^[:space:]]*(\.env|\.pem|\.key|credentials|\.ssh/id_)|wget[[:space:]].*--post-file[= ][^[:space:]]*(\.env|\.pem|\.key|credentials|\.ssh/id_)'; then
     echo "BLOCKED: Credential file exfiltration via HTTP upload" >&2
     exit 2
 fi
 
 # Pattern 9: Piping credential files to curl/wget
-if echo "$COMMAND" | grep -qiP 'cat\s+[^\s]*(\.env|\.pem|\.key|credentials|\.ssh/id_)\S*\s*\|.*curl|cat\s+[^\s]*(\.env|\.pem|\.key|credentials|\.ssh/id_)\S*\s*\|.*wget'; then
+if echo "$COMMAND" | grep -qiE 'cat[[:space:]]+[^[:space:]]*(\.env|\.pem|\.key|credentials|\.ssh/id_)[^[:space:]]*[[:space:]]*\|.*curl|cat[[:space:]]+[^[:space:]]*(\.env|\.pem|\.key|credentials|\.ssh/id_)[^[:space:]]*[[:space:]]*\|.*wget'; then
     echo "BLOCKED: Credential file piped to HTTP client" >&2
     exit 2
 fi
 
+# Pattern 10: macOS keychain extraction of a known secret token (#65350 —
+# a plugin shipped `security find-generic-password -s ANTHROPIC_AUTH_TOKEN -w`
+# in skill files to silently exfiltrate the user's Anthropic token). Require
+# the -w flag (prints the raw secret) AND a high-signal secret service name,
+# so reading a non-secret keychain item (e.g. a wifi password) is not blocked.
+if echo "$COMMAND" | grep -qiE 'security\s+find-(generic|internet)-password' \
+   && echo "$COMMAND" | grep -qE '(^|[[:space:]])-w([[:space:]]|$)' \
+   && echo "$COMMAND" | grep -qiE 'ANTHROPIC|OPENAI|AUTH[_-]?TOKEN|API[_-]?KEY|ACCESS[_-]?TOKEN|[_-]SECRET|OAUTH|GITHUB[_-]?TOKEN|(^|[^a-z])secret([^a-z]|$)'; then
+    echo "BLOCKED: macOS keychain extraction of a secret token (security find-generic-password -w of a credential)" >&2
+    exit 2
+fi
+
+# Pattern 11: keychain secret piped straight into a network client.
+if echo "$COMMAND" | grep -qiE 'security\s+find-(generic|internet)-password' \
+   && echo "$COMMAND" | grep -qiE '\|[[:space:]]*(curl|wget|nc|ncat|telnet)([[:space:]]|$)'; then
+    echo "BLOCKED: keychain secret piped to a network client (possible exfiltration)" >&2
+    exit 2
+fi
+
+# Pattern 12: a secret-named env var piped into a network client as data.
+# Legit auth uses a header (-H "Authorization: Bearer $TOKEN") where the pipe,
+# if any, goes to a parser like jq — not to the network client — so this only
+# fires when the secret value itself is piped straight to curl/wget/nc.
+if echo "$COMMAND" | grep -qE '\$\{?[A-Za-z_]*(TOKEN|SECRET|API[_-]?KEY|PASSWORD|CREDENTIAL|AUTH)[A-Za-z_]*' \
+   && echo "$COMMAND" | grep -qiE '\|[[:space:]]*(curl|wget|nc|ncat|telnet)([[:space:]]|$)'; then
+    echo "BLOCKED: secret environment variable piped to a network client (possible exfiltration)" >&2
+    exit 2
+fi
+
 exit 0

package/examples/credential-file-cat-guard.sh

@@ -21,13 +21,29 @@
 #
 # 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-credential-file-cat-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [credential-file-cat-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
 
 # Known credential files that contain tokens/passwords
-CRED_FILES='\.netrc|\.npmrc|\.yarnrc\.yml|\.cargo/credentials|\.docker/config\.json|\.kube/config|\.config/gh/hosts\.yml|\.nuget/NuGet\.Config|\.m2/settings\.xml|\.gradle/gradle\.properties|\.pypirc|\.gem/credentials|\.config/pip/pip\.conf|\.bowerrc|\.composer/auth\.json'
+
+# .git-credentials holds "https://user:token@host" in plain text, which makes it
+# the highest-value file on most dev machines. It was missing from this list
+# while .pypirc and .npmrc were covered - measured 2026-08-29 on CC 2.1.246.
+CRED_FILES='\.git-credentials|\.netrc|\.npmrc|\.yarnrc\.yml|\.cargo/credentials|\.docker/config\.json|\.kube/config|\.config/gh/hosts\.yml|\.nuget/NuGet\.Config|\.m2/settings\.xml|\.gradle/gradle\.properties|\.pypirc|\.gem/credentials|\.config/pip/pip\.conf|\.bowerrc|\.composer/auth\.json'
 
 # Block cat/head/tail/less/more/grep reading credential files
 if echo "$COMMAND" | grep -qE "(cat|head|tail|less|more|bat)\s+[^\|;]*($CRED_FILES)"; then

package/examples/cron-create-receipt.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+# ================================================================
+# cron-create-receipt.sh — Log every CronCreate registration
+# ================================================================
+# PURPOSE:
+#   When the model calls CronCreate, write a receipt file so the
+#   operator can later audit which cron jobs were registered and
+#   compare against actual fire events.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "CronCreate"
+#
+# WHY THIS MATTERS:
+#   CronCreate registration is silent by default — no log entry is
+#   produced. When session-scoped cron jobs silently miss fires
+#   (issue #62036, #51296, #56108), operators need the registration
+#   list to compare against actual fire timestamps. Without this
+#   receipt, the registration side of the audit is invisible.
+#
+#   Pair with the prompt-side receipt pattern (touch on each fire)
+#   to produce a full audit:
+#     Registration count (this hook) vs fire count (touch receipts)
+#
+# WHAT IT WRITES:
+#   ~/.claude/state/crons/registered/<timestamp>-<seq>.json
+#   Each receipt contains:
+#     - registered_at: ISO 8601 timestamp
+#     - cron_expression: the cron spec (e.g. "40 * * * *")
+#     - recurring: boolean
+#     - prompt_excerpt: first 200 chars of the prompt (truncated)
+#     - tool_output_excerpt: first 200 chars of the response
+#
+# DEFENSIVE BEHAVIOR:
+#   - Always exits 0 (advisory only, never blocks)
+#   - Skips silently if state directory cannot be created
+#   - Skips silently if jq is missing
+#   - Truncates prompt to 200 chars to keep receipt file size bounded
+#
+# CONFIGURATION (environment variables):
+#   CC_CRON_RECEIPT_DISABLE=1   skip the hook entirely
+#   CC_CRON_RECEIPT_DIR=...     override the state directory
+#   CC_CRON_RECEIPT_EXCERPT_LEN truncation length (default 200)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/62036  (ulogan, 2026-05-24)
+#   https://github.com/anthropics/claude-code/issues/56108  (one-shot queue)
+#   https://github.com/anthropics/claude-code/issues/51296  (never fires)
+#
+# RELATED PUBLIC RESOURCES:
+#   https://gist.github.com/yurukusa/a56f858169688b264510ed1c07181e65  (structural analysis)
+#   https://gist.github.com/yurukusa/42b6da4c53a836ac3aa809f463da45be  (scheduled-routine-watchdog.sh)
+# ================================================================
+
+set -u
+
+# Skip if disabled
+if [ "${CC_CRON_RECEIPT_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
+
+INPUT=$(cat)
+
+STATE_DIR="${CC_CRON_RECEIPT_DIR:-$HOME/.claude/state/crons/registered}"
+EXCERPT_LEN="${CC_CRON_RECEIPT_EXCERPT_LEN:-200}"
+
+# Create state directory; skip silently on failure (read-only fs, etc.)
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+
+# Extract fields defensively
+CRON_EXPR=$(printf '%s' "$INPUT" | jq -r '.tool_input.cron // empty' 2>/dev/null)
+
+# Skip if no cron expression — the hook only fires on CronCreate but
+# defensive check guards against malformed input
+if [ -z "$CRON_EXPR" ]; then
+  exit 0
+fi
+
+RECURRING=$(printf '%s' "$INPUT" | jq -r '.tool_input.recurring // false' 2>/dev/null)
+PROMPT_RAW=$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
+RESULT_RAW=$(printf '%s' "$INPUT" | jq -r '.tool_result // empty' 2>/dev/null)
+
+# Truncate to bounded length
+PROMPT_EXCERPT=$(printf '%s' "$PROMPT_RAW" | head -c "$EXCERPT_LEN")
+RESULT_EXCERPT=$(printf '%s' "$RESULT_RAW" | head -c "$EXCERPT_LEN")
+
+# Generate unique receipt filename: timestamp + 4-char random suffix
+TS=$(date -u '+%Y%m%dT%H%M%SZ')
+SEQ=$(printf '%04x' "$RANDOM" 2>/dev/null || echo "0000")
+RECEIPT_FILE="$STATE_DIR/$TS-$SEQ.json"
+
+# Compose receipt JSON via jq for safe quoting
+jq -n \
+  --arg registered_at "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" \
+  --arg cron_expression "$CRON_EXPR" \
+  --argjson recurring "$RECURRING" \
+  --arg prompt_excerpt "$PROMPT_EXCERPT" \
+  --arg tool_output_excerpt "$RESULT_EXCERPT" \
+  '{
+    registered_at: $registered_at,
+    cron_expression: $cron_expression,
+    recurring: $recurring,
+    prompt_excerpt: $prompt_excerpt,
+    tool_output_excerpt: $tool_output_excerpt
+  }' > "$RECEIPT_FILE" 2>/dev/null || exit 0
+
+# Always exit 0 — advisory only, never blocks CronCreate
+exit 0

package/examples/cron-modification-guard.sh

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