cc-safe-setup 29.6.37 → 29.6.38

package/2026-03-29

@@ -0,0 +1,2 @@
+Invalid search query "token created: --json number,title,reactionGroups,commentsCount repo:anthropics/claude-code type:issue".
+"" is not a recognized date/time format. Please provide an ISO 8601 date/time value, such as YYYY-MM-DD.

package/COOKBOOK.md

@@ -286,6 +286,40 @@ npx cc-safe-setup --install-example git-show-flag-sanitizer
 
 Install in `.claude/settings.json` as a PreToolUse hook with matcher `Bash`. The hook detects `git show` + `--no-stat`, strips the invalid flag, and returns the corrected command via `updatedInput`. See [#13071](https://github.com/anthropics/claude-code/issues/13071).
 
+## Recipe: Diagnose Token Consumption
+
+If your Max Plan 5-hour limit is exhausting too fast, install these two hooks to track what's consuming tokens:
+
+```bash
+# Log every prompt with timestamps
+npx cc-safe-setup --install-example prompt-usage-logger
+
+# Alert when auto-compaction fires
+npx cc-safe-setup --install-example compact-alert-notification
+```
+
+After a session, check `/tmp/claude-usage-log.txt` for prompt frequency and `/tmp/claude-compact-log.txt` for compaction count. If you see 3+ compactions per session, the compact-rebuild cycle is a major token sink — use manual `/compact` before the threshold.
+
+Quick wins: reduce MCP servers (`claude mcp list`), use `offset`/`limit` on large file reads, trim CLAUDE.md to essentials. If on v2.1.89+, set `"ENABLE_TOOL_SEARCH": "false"` in settings.json `env` to prevent Deferred Tool Loading from breaking the cache prefix ([#41617](https://github.com/anthropics/claude-code/issues/41617)). See also [#41249](https://github.com/anthropics/claude-code/issues/41249), [#41788](https://github.com/anthropics/claude-code/issues/41788), [#40524](https://github.com/anthropics/claude-code/issues/40524).
+
+## Recipe: Protect Session Data
+
+Back up session JSONL files on every start (protects against silent deletion):
+
+```bash
+npx cc-safe-setup --install-example session-backup-on-start
+```
+
+Keeps last 5 timestamped backups in `~/.claude/session-backups/`. Restore with `cp`. See [#41874](https://github.com/anthropics/claude-code/issues/41874).
+
+Back up the full transcript before compaction (protects against rate-limit data loss):
+
+```bash
+npx cc-safe-setup --install-example pre-compact-transcript-backup
+```
+
+Keeps last 3 backups in `~/.claude/compact-backups/`. If compaction fails and your transcript is corrupted, restore from the backup. See [#40352](https://github.com/anthropics/claude-code/issues/40352).
+
 ## Recipe: Disable Auto-Compaction
 
 Power users who manage context manually can block auto-compaction entirely:
@@ -314,3 +348,4 @@ Install as a PreToolUse hook with matcher `WebFetch`. By default allows all doma
 - [Credential Protection](https://yurukusa.github.io/cc-safe-setup/prevent-credential-leak.html)
 - [Troubleshooting](TROUBLESHOOTING.md)
 - [Settings Reference](SETTINGS_REFERENCE.md)
+- **[Hook Design Guide (Zenn Book)](https://zenn.dev/yurukusa/books/6076c23b1cb18b)** — 14 chapters on hook design patterns, testing, and real incident postmortems. Chapter 3 free.

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dw/cc-safe-setup)](https://www.npmjs.com/package/cc-safe-setup)
 [![tests](https://github.com/yurukusa/cc-safe-setup/actions/workflows/test.yml/badge.svg)](https://github.com/yurukusa/cc-safe-setup/actions/workflows/test.yml)
 
-**One command to make Claude Code safe for autonomous operation.** 634 example hooks · 13,835 tests · 1,000+ installs/day · [日本語](docs/README.ja.md)
+**One command to make Claude Code safe for autonomous operation.** 654 example hooks · 14,078 tests · 1,000+ installs/day · [日本語](docs/README.ja.md)
 
 ```bash
 npx cc-safe-setup
@@ -12,6 +12,8 @@ npx cc-safe-setup
 
 Installs 8 safety hooks in ~10 seconds. Blocks `rm -rf /`, prevents pushes to main, catches secret leaks, validates syntax after every edit. Zero dependencies.
 
+> **What's a hook?** A checkpoint that runs before Claude executes a command. Like airport security — it inspects what's about to happen and blocks anything dangerous before it reaches the gate.
+
 [**Getting Started**](https://yurukusa.github.io/cc-safe-setup/getting-started.html) · [**All Tools**](https://yurukusa.github.io/cc-safe-setup/hub.html) · [**Recipes**](https://yurukusa.github.io/cc-safe-setup/recipes.html) · [Validate your settings.json](https://yurukusa.github.io/cc-safe-setup/validator.html) · [**Check your score**](https://yurukusa.github.io/cc-health-check/) (`npx cc-health-check`)
 
 ```
@@ -64,6 +66,8 @@ Claude Code ships with no safety hooks by default. This tool fixes that.
 | **cd+git Auto-Approver** | Permission prompt spam for `cd /path && git log` | [#32985](https://github.com/anthropics/claude-code/issues/32985) [#16561](https://github.com/anthropics/claude-code/issues/16561) |
 | **API Error Alert** | Silent session death from rate limits or API errors — desktop notification + log | |
 
+> 📘 Tokens disappearing too fast? [The practical guide](https://zenn.dev/yurukusa/books/6076c23b1cb18b) covers 10 token consumption patterns (cache corruption, excessive reads, compact cycles) and how to detect them — from 700+ hours of autonomous operation. Chapter 3 free.
+
 Each hook exists because a real incident happened without it.
 
 ### v2.1.85: `if` Field Support
@@ -97,6 +101,28 @@ Override Claude Code's built-in confirmation prompts. These run **after** the bu
 
 Install any of these: `npx cc-safe-setup --install-example <name>`
 
+## Session Protection Hooks
+
+Guards against issues that corrupt sessions or waste tokens silently.
+
+| Hook | What It Solves | Issue |
+|------|---------------|-------|
+| `cch-cache-guard` | Blocks reads of Claude session/billing files that poison prompt cache via `cch=` substitution | [#40652](https://github.com/anthropics/claude-code/issues/40652) |
+| `image-file-validator` | Blocks Read of fake image files (text in .png) that permanently corrupt sessions | [#24387](https://github.com/anthropics/claude-code/issues/24387) |
+| `terminal-state-restore` | Restores Kitty keyboard protocol, cursor, bracketed paste on exit | [#39096](https://github.com/anthropics/claude-code/issues/39096) [#39272](https://github.com/anthropics/claude-code/issues/39272) |
+| `large-read-guard` | Warns before reading large files via `cat`/`less` that waste context tokens | [#41617](https://github.com/anthropics/claude-code/issues/41617) |
+| `prompt-usage-logger` | Logs every prompt with timestamps to track token consumption patterns | [#41249](https://github.com/anthropics/claude-code/issues/41249) |
+| `compact-alert-notification` | Alerts when auto-compaction fires (tracks compact-rebuild cycles that burn tokens) | [#41788](https://github.com/anthropics/claude-code/issues/41788) |
+| `token-budget-guard` | Blocks tool calls when estimated session cost exceeds a configurable threshold | [#38335](https://github.com/anthropics/claude-code/issues/38335) |
+| `session-index-repair` | Rebuilds `sessions-index.json` on exit so `claude --resume` finds all sessions | [#25032](https://github.com/anthropics/claude-code/issues/25032) |
+| `session-backup-on-start` | Backs up session JSONL files on start (protects against silent deletion) | [#41874](https://github.com/anthropics/claude-code/issues/41874) |
+| `working-directory-fence` | Blocks Read/Edit/Write outside CWD (prevents operating on wrong project copy) | [#41850](https://github.com/anthropics/claude-code/issues/41850) |
+| `mcp-warmup-wait` | Waits for MCP servers to initialize on session start (fixes first-turn tool errors) | [#41778](https://github.com/anthropics/claude-code/issues/41778) |
+| `pre-compact-transcript-backup` | Full JSONL backup before compaction (protects against rate-limit data loss) | [#40352](https://github.com/anthropics/claude-code/issues/40352) |
+| `conversation-history-guard` | Blocks access to session JSONL files (prevents 20x cache poisoning) | [#40524](https://github.com/anthropics/claude-code/issues/40524) |
+| `replace-all-guard` | Warns/blocks Edit `replace_all:true` (prevents bulk data corruption) | [#41681](https://github.com/anthropics/claude-code/issues/41681) |
+| `ripgrep-permission-fix` | Auto-fixes vendored ripgrep +x permission on start (fixes broken commands/skills) | [#41933](https://github.com/anthropics/claude-code/issues/41933) |
+
 ## All 49 Commands
 
 | Command | What It Does |
@@ -120,7 +146,7 @@ Install any of these: `npx cc-safe-setup --install-example <name>`
 | `--scan [--apply]` | Tech stack detection |
 | `--export / --import` | Team config sharing |
 | `--verify` | Test each hook |
-| `--install-example <name>` | Install from 564 examples |
+| `--install-example <name>` | Install from 654 examples |
 | `--examples [filter]` | Browse examples by keyword |
 | `--full` | All-in-one setup |
 | `--status` | Check installed hooks |
@@ -403,7 +429,7 @@ See [Issue #1](https://github.com/yurukusa/cc-safe-setup/issues/1) for details.
 
 ## Learn More
 
-- **[Hook Design Guide (Zenn Book)](https://zenn.dev/yurukusa/books/6076c23b1cb18b)** — 14-chapter guide from 700+ hours of autonomous operation. Hook design patterns, testing strategies, real incident postmortems. [Chapter 2 free](https://zenn.dev/yurukusa/books/6076c23b1cb18b/viewer/2-safety-guards)
+- **[Practical Guide (Zenn Book)](https://zenn.dev/yurukusa/books/6076c23b1cb18b)** — Token consumption diagnosis, file loss prevention, autonomous operation safety. 14 chapters from 700+ hours of real incidents. [Chapter 3 free](https://zenn.dev/yurukusa/books/6076c23b1cb18b/viewer/3-code-quality)
 - [Cookbook](COOKBOOK.md) — 26 practical recipes (block, approve, protect, monitor, diagnose)
 - [Official Hooks Reference](https://code.claude.com/docs/en/hooks) — Claude Code hooks documentation
 - [Hooks Cookbook](https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md) — 25 recipes from real GitHub Issues ([interactive version](https://yurukusa.github.io/claude-code-hooks/))
@@ -433,13 +459,38 @@ cc-safe-setup covers Safety Guards (75-100%) and Monitoring (context-monitor). T
 
 No. Each hook runs in ~10ms. They only fire on specific events (before tool use, after edits, on stop). No polling, no background processes.
 
+**Q: My permission patterns don't match compound commands like `cd /path && git status`**
+
+This is a known limitation of Claude Code's permission system ([#16561](https://github.com/anthropics/claude-code/issues/16561), [#28240](https://github.com/anthropics/claude-code/issues/28240)). Permission matching evaluates only the first token (`cd`), not the actual command (`git status`). Use a PreToolUse hook instead — hooks see the full command string and can parse compound commands. See `compound-command-allow.sh` in examples.
+
+**Q: `--dangerously-skip-permissions` still prompts for `.claude/` and `.git/` writes**
+
+Since v2.1.78, protected directories always prompt regardless of permission mode ([#35668](https://github.com/anthropics/claude-code/issues/35668)). Use a PermissionRequest hook to auto-approve specific protected directory operations. See `allow-protected-dirs.sh` in examples.
+
+**Q: `allow: ["Bash(*)"]` overrides my `ask` rules**
+
+`allow` takes precedence over `ask`. If you allow all Bash, ask rules are ignored ([#6527](https://github.com/anthropics/claude-code/issues/6527)). Use PreToolUse hooks to block dangerous commands instead of relying on the ask/allow priority system.
+
+**Still stuck?** See the full [Permission Troubleshooting Flowchart](https://gist.github.com/yurukusa/b64217ffcb908fa309dbfcfa368cd84d) for step-by-step diagnosis.
+
 ## Contributing
 
-Found a false positive? Open an [issue](https://github.com/yurukusa/cc-safe-setup/issues/new?template=false_positive.md). Want a new hook? Open a [feature request](https://github.com/yurukusa/cc-safe-setup/issues/new?template=bug_report.md).
+**Report a problem:** Found a false positive or a bypass? Open an [issue](https://github.com/yurukusa/cc-safe-setup/issues/new). Include the command that was incorrectly blocked/allowed and your OS.
+
+**Request a hook:** Describe the problem you're trying to prevent (not the solution). We'll figure out the hook together.
+
+**Write a hook:** Fork, add your `.sh` file to `examples/`, add tests to `test.sh`, and open a PR. Every hook needs:
+- A comment header explaining what it blocks and why
+- At least 7 test cases (block, allow, empty input, edge cases)
+- `bash -n` syntax validation passing
+
+**Share your experience:** Used cc-safe-setup and have feedback? Open a discussion or comment on any issue. We read everything.
 
-📘 **Want the full story?** [Production guide from 700+ hours of autonomous operation](https://zenn.dev/yurukusa/books/6076c23b1cb18b) — the incidents, fixes, and patterns behind every hook in this tool.
+## Also by yurukusa
 
-If cc-safe-setup saved your project from a destructive command, consider giving it a star — it helps others find this tool.
+- [quiet life](https://yurukusa.github.io/quiet-life/) — Touch the dark. Something alive appears
+- [deep breath](https://yurukusa.github.io/deep-breath/) — Breathe with the light
+- [star moss](https://yurukusa.github.io/star-moss/) — Drag to grow
 
 ## License
 

package/TROUBLESHOOTING.md

@@ -291,9 +291,54 @@ The hook has a strict whitelist. If a command isn't on the list, it passes throu
 - `pip install` (not whitelisted — install `pip-venv-guard` instead)
 - Custom scripts (unknown to the whitelist)
 
+## Token Consumption Too Fast
+
+**Symptom**: Max Plan 5-hour limit exhausted in 1-2 hours. Same usage pattern as before.
+
+**Diagnosis**:
+
+```bash
+# Install token tracking hooks
+npx cc-safe-setup --install-example prompt-usage-logger
+npx cc-safe-setup --install-example compact-alert-notification
+```
+
+After a session, check:
+- `/tmp/claude-usage-log.txt` — how many prompts, how frequently
+- `/tmp/claude-compact-log.txt` — how many auto-compactions fired
+
+**Common causes**:
+
+| Cause | Check | Fix |
+|-------|-------|-----|
+| Too many MCP servers | `claude mcp list` | Remove unused servers |
+| Large CLAUDE.md/MEMORY.md | `wc -c CLAUDE.md` | Move reference content to separate files |
+| Auto-compact cycles | compact-alert count > 3 | Use manual `/compact` before threshold |
+| Large file reads | prompt-usage-log timestamps | Use `offset`/`limit` parameters |
+| Deferred Tool Loading cache miss | Check `ToolSearch` calls in transcript | Set `ENABLE_TOOL_SEARCH=false` in settings.json `env` ([#41617](https://github.com/anthropics/claude-code/issues/41617)) |
+| `--resume` cache prefix breakage | "hi" costs 2-5% quota after resume | Start fresh sessions instead of resuming ([#40524](https://github.com/anthropics/claude-code/issues/40524)) |
+| Session file self-reads (`cch=` header) | Claude reads its own `.jsonl` files | Install `read-budget-guard` to limit large reads ([#40652](https://github.com/anthropics/claude-code/issues/40652)) |
+
+**Disabling Deferred Tool Loading** (v2.1.89+ workaround):
+
+Deferred Tool Loading can break the cache prefix, causing every prompt to rebuild context from scratch. To disable it, add to `.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ENABLE_TOOL_SEARCH": "false"
+  }
+}
+```
+
+This prevents `ToolSearch` deferred loading and preserves the cache prefix across turns. See community discussion in [#41617](https://github.com/anthropics/claude-code/issues/41617).
+
+**Related issues**: [#41249](https://github.com/anthropics/claude-code/issues/41249), [#41788](https://github.com/anthropics/claude-code/issues/41788), [#38335](https://github.com/anthropics/claude-code/issues/38335), [#40524](https://github.com/anthropics/claude-code/issues/40524), [#41617](https://github.com/anthropics/claude-code/issues/41617)
+
 ## Still Stuck?
 
 1. Wrap the hook with debug wrapper: `npx cc-safe-setup --install-example hook-debug-wrapper`
 2. Check `~/.claude/hook-debug.log` for detailed I/O traces
 3. Run `npx cc-safe-setup --doctor` for automated checks
 4. Open an issue: [cc-safe-setup issues](https://github.com/yurukusa/cc-safe-setup/issues)
+5. Read the full guide: **[Hook Design Guide (Zenn Book)](https://zenn.dev/yurukusa/books/6076c23b1cb18b)** — 14 chapters, Chapter 3 free

package/examples/cch-cache-guard.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# cch-cache-guard.sh — Block reads of Claude session files to prevent cache poisoning
+#
+# Solves: When Claude reads its own JSONL session files or proxy logs,
+# the `cch=` billing hash substitution permanently breaks prompt cache
+# for the entire session. Every subsequent turn pays full cache cost.
+#
+# Root cause: The CLI mutates historical tool results by substituting
+# `cch=` billing hashes, invalidating the cache prefix.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+# Related: https://github.com/anthropics/claude-code/issues/40652
+
+INPUT=$(cat)
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$CMD" ] && exit 0
+
+# Block commands that read Claude's own session files or billing logs
+if printf '%s' "$CMD" | grep -qE '\.(jsonl|log)' && \
+   printf '%s' "$CMD" | grep -qiE '(claude|session|billing|transcript)'; then
+    echo '{"decision": "block", "reason": "Blocked: reading Claude session/billing files can poison prompt cache via cch= substitution. Use an external terminal instead."}'
+    exit 0
+fi
+
+exit 0

package/examples/compact-alert-notification.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# ================================================================
+# compact-alert-notification.sh — Warn when compaction is imminent
+# ================================================================
+# PURPOSE:
+#   Context compaction burns tokens to re-summarize the conversation.
+#   This hook alerts you when compaction is about to happen so you
+#   can use /compact or /clear proactively for a cheaper alternative.
+#
+# TRIGGER: Notification
+# MATCHER: ""
+#
+# HOW IT WORKS:
+#   Checks the notification message for compaction-related keywords.
+#   Prints a warning to stderr (shown in the terminal) when detected.
+#
+# WHY THIS MATTERS:
+#   Auto-compact fires at a fixed threshold. Each cycle costs tokens
+#   to summarize. Manual /compact before the threshold lets you
+#   control timing and reduce surprise token consumption.
+#
+# OUTPUT:
+#   Warning message to stderr when compaction is detected.
+#   Always exits 0 (notifications should never block).
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/41249
+#   https://github.com/anthropics/claude-code/issues/17428
+# ================================================================
+
+INPUT=$(cat)
+
+MSG=$(printf '%s' "$INPUT" | jq -r '.message // empty' 2>/dev/null)
+
+if echo "$MSG" | grep -qi "compact"; then
+  echo "⚠ Context approaching limit — compaction imminent. Consider /compact or /clear now." >&2
+fi
+
+exit 0

package/examples/conversation-history-guard.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# ================================================================
+# conversation-history-guard.sh — Block modifications to conversation history
+# ================================================================
+# PURPOSE:
+#   Prevents Claude from reading or modifying its own conversation
+#   history files (.jsonl transcripts). When Claude reads these
+#   files, the `cch=` billing hash substitution permanently
+#   invalidates prompt cache, causing 20x token inflation.
+#   When Claude writes to them, it can corrupt the session.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash|Read|Edit|Write"
+#
+# WHY THIS MATTERS:
+#   Claude Code uses prompt caching to reduce token consumption.
+#   The cache key is based on conversation history content.
+#   If Claude reads its own transcript, the CLI substitutes
+#   billing hashes (cch=), changing the content and invalidating
+#   the cache prefix. This causes every subsequent turn to pay
+#   full price instead of using cached tokens.
+#   Measured impact: cache read ratio drops from 89-99% to 4.3%,
+#   causing ~20x token inflation per turn.
+#
+# WHAT IT BLOCKS:
+#   - Read/cat/head/tail of .claude/projects/*/*.jsonl
+#   - Edit/Write to conversation transcript files
+#   - Bash commands that access session JSONL files
+#
+# CONFIGURATION:
+#   CC_ALLOW_HISTORY_ACCESS=1 — disable this guard
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/40524
+#   https://github.com/anthropics/claude-code/issues/34629
+#   https://github.com/anthropics/claude-code/issues/40652
+#   https://github.com/anthropics/claude-code/issues/41891
+# ================================================================
+
+set -u
+
+[ "${CC_ALLOW_HISTORY_ACCESS:-0}" = "1" ] && exit 0
+
+INPUT=$(cat)
+
+# Check file_path for Read/Edit/Write tools
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+if [ -n "$FILE_PATH" ]; then
+    case "$FILE_PATH" in
+        */.claude/projects/*.jsonl|*/.claude/projects/*/sessions/*.jsonl)
+            printf 'BLOCKED: Accessing conversation history invalidates prompt cache.\n' >&2
+            printf '  File: %s\n' "$FILE_PATH" >&2
+            printf '  Reading session JSONL causes cch= substitution, dropping cache ratio to ~4%%.\n' >&2
+            printf '  Use an external terminal to inspect session files.\n' >&2
+            exit 2
+            ;;
+    esac
+fi
+
+# Check Bash commands
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [ -n "$CMD" ]; then
+    if printf '%s' "$CMD" | grep -qE '\.claude/projects/.*\.jsonl' && \
+       printf '%s' "$CMD" | grep -qE '(cat|head|tail|less|more|grep|jq|read|wc)'; then
+        printf 'BLOCKED: Command accesses conversation history (cache poisoning risk).\n' >&2
+        printf '  Command: %s\n' "$CMD" >&2
+        exit 2
+    fi
+fi
+
+exit 0

package/examples/image-file-validator.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# image-file-validator.sh — Block Read of fake image files that corrupt sessions
+#
+# Solves: When Claude reads a file with an image extension (.png, .jpg, etc.)
+# that isn't actually an image (text, Git LFS pointer, error log), the content
+# gets base64-encoded and sent to the API, causing a 400 error. The corrupt
+# block stays in the JSONL transcript, permanently breaking the session.
+#
+# Uses `file --mime-type` (magic byte detection) to verify the file is
+# actually an image before allowing the Read tool to process it.
+#
+# TRIGGER: PreToolUse  MATCHER: "Read"
+# Related: https://github.com/anthropics/claude-code/issues/24387
+
+INPUT=$(cat)
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+
+# Only check files with image extensions
+case "${FILE,,}" in
+    *.png|*.jpg|*.jpeg|*.gif|*.bmp|*.webp|*.svg|*.ico|*.tiff|*.tif)
+        ;;
+    *)
+        exit 0
+        ;;
+esac
+
+# Verify the file is actually an image using magic bytes
+MIME=$(file --mime-type -b "$FILE" 2>/dev/null)
+case "$MIME" in
+    image/*)
+        # Valid image — allow
+        exit 0
+        ;;
+    *)
+        echo "{\"decision\": \"block\", \"reason\": \"Blocked: ${FILE##*/} has an image extension but is actually ${MIME}. Reading non-image files with image extensions corrupts the session (base64-encoded garbage causes API 400 errors). Rename the file or check its contents in an external terminal.\"}"
+        exit 0
+        ;;
+esac

package/examples/mcp-warmup-wait.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# ================================================================
+# mcp-warmup-wait.sh — Wait for MCP servers to be ready on start
+# ================================================================
+# PURPOSE:
+#   MCP servers take time to initialize after session start.
+#   In Remote Trigger / scheduled sessions, the first turn often
+#   fires before MCP tools are available. This hook adds a brief
+#   delay on SessionStart to let MCP servers spin up.
+#
+# TRIGGER: SessionStart
+# MATCHER: (none)
+#
+# WHY THIS MATTERS:
+#   When Claude Code starts via Remote Trigger or cron, the
+#   first message is sent immediately. MCP servers may not
+#   be connected yet, causing "tool not available" errors
+#   on the first turn. A short warmup delay fixes this.
+#
+# CONFIGURATION:
+#   CC_MCP_WARMUP_SECONDS — seconds to wait (default: 3)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/41778
+#   https://github.com/anthropics/claude-code/issues/35899
+# ================================================================
+
+WARMUP="${CC_MCP_WARMUP_SECONDS:-3}"
+
+# Only wait if MCP servers are configured
+MCP_CONFIG="${HOME}/.claude/settings.json"
+if [ -f "$MCP_CONFIG" ]; then
+    if grep -q '"mcpServers"' "$MCP_CONFIG" 2>/dev/null; then
+        sleep "$WARMUP"
+        printf 'MCP warmup: waited %ds for server initialization\n' "$WARMUP" >&2
+    fi
+fi
+
+exit 0

package/examples/permission-denial-enforcer.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# permission-denial-enforcer.sh — Block alternative write methods after permission denial
+#
+# Solves: After user denies Write permission, Claude circumvents by using
+# Bash commands (pip install --target, path traversal to /tmp, etc.) to
+# achieve the same write operation (#41103)
+#
+# How it works: Tracks when Write/Edit permissions are denied (via a
+# temp file marker). When active, blocks Bash commands that perform
+# write-equivalent operations: package installs, file creation via
+# scripts, redirects to paths outside the project.
+#
+# The marker auto-expires after 5 minutes to avoid permanent lockout.
+#
+# Usage: Add TWO hooks — one PostToolUse to detect denials, one PreToolUse to enforce
+#
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "Write|Edit",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-denial-enforcer.sh" }]
+#     }],
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-denial-enforcer.sh" }]
+#     }]
+#   }
+# }
+#
+# TRIGGER: PostToolUse+PreToolUse  MATCHER: "Write|Edit|Bash"
+
+MARKER="/tmp/.cc-write-denied-$$"
+MARKER_GLOB="/tmp/.cc-write-denied-*"
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+# --- PostToolUse path: detect Write/Edit denial ---
+if [[ "$TOOL" == "Write" || "$TOOL" == "Edit" ]]; then
+    # Check if the tool result indicates denial/block
+    RESULT=$(echo "$INPUT" | jq -r '.tool_result // empty' 2>/dev/null)
+    if echo "$RESULT" | grep -qiE 'denied|rejected|blocked|permission.*denied|user.*denied'; then
+        # Create denial marker with timestamp
+        echo "$(date +%s)" > "$MARKER"
+        echo "Write permission denial detected. Write-equivalent Bash commands will be blocked for 5 minutes." >&2
+    fi
+    exit 0
+fi
+
+# --- PreToolUse path: enforce on Bash ---
+[[ "$TOOL" != "Bash" ]] && exit 0
+
+# Check if any denial marker exists and is recent (< 5 min)
+ACTIVE=0
+for f in $MARKER_GLOB; do
+    [[ -f "$f" ]] || continue
+    CREATED=$(cat "$f" 2>/dev/null)
+    NOW=$(date +%s)
+    AGE=$(( NOW - CREATED ))
+    if [[ "$AGE" -lt 300 ]]; then
+        ACTIVE=1
+        break
+    else
+        rm -f "$f" 2>/dev/null
+    fi
+done
+
+[[ "$ACTIVE" -eq 0 ]] && exit 0
+
+# Denial is active — check for write-equivalent commands
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[[ -z "$CMD" ]] && exit 0
+
+# Block package installs (common bypass vector)
+if echo "$CMD" | grep -qiE 'pip3?\s+install|npm\s+install|gem\s+install|cargo\s+install|go\s+install'; then
+    echo "BLOCKED: Package install blocked — you denied Write permission earlier. Ask the user before retrying." >&2
+    exit 2
+fi
+
+# Block file creation via Python/Node scripts
+if echo "$CMD" | grep -qiE 'python3?\s+.*\.(py|sh)|node\s+.*\.js' && echo "$CMD" | grep -qiE 'create|write|save|output|generate'; then
+    echo "BLOCKED: Script execution that creates files blocked — Write permission was denied." >&2
+    exit 2
+fi
+
+# Block redirect/tee to outside project
+if echo "$CMD" | grep -qiE '>\s*/tmp|>\s*/private|tee\s+/tmp|tee\s+/private|--target='; then
+    echo "BLOCKED: Writing to /tmp or external paths blocked — Write permission was denied." >&2
+    exit 2
+fi
+
+exit 0

package/examples/pre-compact-transcript-backup.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# ================================================================
+# pre-compact-transcript-backup.sh — Backup transcript before compaction
+# ================================================================
+# PURPOSE:
+#   Creates a full copy of the session transcript JSONL before
+#   compaction begins. If compaction fails (rate limit, API error),
+#   the original transcript is preserved and can be restored.
+#
+# TRIGGER: PreCompact
+# MATCHER: (none — PreCompact has no matcher)
+#
+# WHY THIS MATTERS:
+#   Compaction wipes message content from the JSONL transcript
+#   BEFORE the compaction API call succeeds. If the API call
+#   fails (e.g., rate limit), all original content is permanently
+#   lost — the transcript is left with thousands of empty messages
+#   and no compaction summary. This hook ensures a recoverable
+#   backup exists.
+#
+# WHAT IT DOES:
+#   1. Reads transcript_path from stdin JSON
+#   2. Copies the full JSONL file to a backup location
+#   3. Keeps last 3 backups per session to save disk space
+#
+# CONFIGURATION:
+#   CC_COMPACT_BACKUP_DIR — backup directory
+#     (default: ~/.claude/compact-backups)
+#   CC_COMPACT_BACKUP_KEEP — number of backups to keep (default: 3)
+#
+# RECOVERY:
+#   cp ~/.claude/compact-backups/<session-id>/latest.jsonl \
+#      ~/.claude/projects/<project>/sessions/<session>.jsonl
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/40352
+# ================================================================
+
+set -u
+
+INPUT=$(cat)
+
+BACKUP_DIR="${CC_COMPACT_BACKUP_DIR:-${HOME}/.claude/compact-backups}"
+KEEP="${CC_COMPACT_BACKUP_KEEP:-3}"
+
+# Get transcript path from hook input
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+    exit 0
+fi
+
+# Create backup
+BASENAME=$(basename "$TRANSCRIPT" .jsonl)
+DEST_DIR="${BACKUP_DIR}/${BASENAME}"
+mkdir -p "$DEST_DIR"
+
+TIMESTAMP=$(date -u +"%Y%m%d-%H%M%S")
+BACKUP_FILE="${DEST_DIR}/${TIMESTAMP}.jsonl"
+
+cp "$TRANSCRIPT" "$BACKUP_FILE" 2>/dev/null
+
+if [ -f "$BACKUP_FILE" ]; then
+    SIZE=$(du -sh "$BACKUP_FILE" 2>/dev/null | cut -f1)
+    printf 'Pre-compact backup: %s (%s)\n' "$BACKUP_FILE" "$SIZE" >&2
+
+    # Prune old backups
+    ls -1t "$DEST_DIR"/*.jsonl 2>/dev/null | tail -n +$((KEEP + 1)) | xargs rm -f 2>/dev/null
+fi
+
+exit 0