cc-safe-setup 29.8.0 → 30.0.4

package/README.md

@@ -1,618 +1,525 @@
 # cc-safe-setup
+**[日本語の README はこちら / Japanese README](docs/README.ja.md)**
 
-[![npm version](https://img.shields.io/npm/v/cc-safe-setup)](https://www.npmjs.com/package/cc-safe-setup)
-[![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 add safety hooks to [Claude Code](https://docs.claude.com/en/docs/claude-code). It installs a set of `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, and `SubagentStop` hooks that stop destructive or irreversible operations *before* they run, and that surface silent failures.
 
-> 🚀 **Launching on [Product Hunt](https://www.producthunt.com/products/cc-safe-setup) — April 21!** Follow us and upvote to support open source safety for AI coding agents.
-
-**One command to make Claude Code safe for autonomous operation.** 701 example hooks · 9,200+ tests · 30K+ total installs · [日本語](docs/README.ja.md)
-
-```bash
-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 npm dependencies. Hooks use [`jq`](https://jqlang.github.io/jq/) at runtime (`brew install jq` / `apt install jq`).
-
-> **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) · [**Incident Tracker**](https://yurukusa.github.io/cc-safe-setup/incidents.html) · [**Hook Selector**](https://yurukusa.github.io/cc-safe-setup/hook-selector.html) · [**Token Checkup**](https://yurukusa.github.io/cc-safe-setup/token-checkup.html) · [**Cache Health**](https://yurukusa.github.io/cc-safe-setup/cache-health.html) · [**Version Check**](https://yurukusa.github.io/cc-safe-setup/version-check.html) · [**CLAUDE.md Analyzer**](https://yurukusa.github.io/cc-safe-setup/claudemd-analyzer.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`) · [**Safety Audit**](https://yurukusa.github.io/cc-safe-setup/safety-audit.html)
-
-```
-  cc-safe-setup
-  Make Claude Code safe for autonomous operation
-
-  Prevents real incidents (from GitHub Issues):
-  ✗ rm -rf permanently destroyed ~50 GB / 1,500 files (#49129) ← April 2026
-  ✗ Auto mode approved ~/.ssh deletion — all SSH keys gone (#49554)
-  ✗ ~/.git-credentials PATs deleted without confirmation (#49539)
-  ✗ rm -rf deleted 3,467 files (~7 GB) without confirmation (#46058)
-  ✗ rm -rf deleted entire user directory via NTFS junction (#36339)
-  ✗ Remove-Item -Recurse -Force destroyed unpushed source (#37331)
-  ✗ Entire Mac filesystem deleted during cleanup (#36233)
-  ✗ Untested code pushed to main at 3am
-  ✗ Force-push rewrote shared branch history
-  ✗ API keys committed to public repos via git add .
-  ✗ Syntax errors cascading through 30+ files
-  ✗ Sessions losing all context with no warning
-  ✗ CLAUDE.md rules silently ignored after context compaction
-  ✗ Claude ran destructive DDL on production database (#46684)
-  ✗ AI executed delete/kill operations on production environment (#46650)
-  ✗ Subagents ignoring all CLAUDE.md rules since v2.1.84 (#40459)
-
-  Hooks to install:
-
-  ● Destructive Command Blocker
-  ● Branch Push Protector
-  ● Post-Edit Syntax Validator
-  ● Context Window Monitor
-  ● Bash Comment Stripper
-  ● cd+git Auto-Approver
-  ● Secret Leak Prevention
-
-  Install all 8 safety hooks? [Y/n] Y
-
-  ✓ Done. 8 safety hooks installed.
-```
-
-## Why This Exists
-
-A user [lost 3,467 files (~7 GB)](https://github.com/anthropics/claude-code/issues/46058) when Claude ran `rm -rf` on their data directory without confirmation. Another [lost their entire C:\Users directory](https://github.com/anthropics/claude-code/issues/36339) when `rm -rf` followed NTFS junctions. Another [lost all source code](https://github.com/anthropics/claude-code/issues/37331) when Claude ran `Remove-Item -Recurse -Force *` on a repo. One user's Claude [ran destructive DDL on a production database](https://github.com/anthropics/claude-code/issues/46684) when asked only to investigate. Another had Claude [execute delete and kill operations on production systems](https://github.com/anthropics/claude-code/issues/46650). Others had untested code pushed to main at 3am. API keys got committed via `git add .`. Syntax errors cascaded through 30+ files before anyone noticed. And [CLAUDE.md rules get silently dropped](https://github.com/anthropics/claude-code/issues/6354) after context compaction — your instructions vanish mid-session.
-
-One user [analyzed 6,852 sessions](https://github.com/anthropics/claude-code/issues/42796) and found the Read:Edit ratio dropped from 6.6 to 2.0 — Claude editing files it never read jumped from 6% to 34%. That issue has over 2,100 reactions. The `read-before-edit` example hook catches this pattern before damage happens.
-
-In April 2026, [$1,446 was transferred without authorization](https://github.com/anthropics/claude-code/issues/46828) when Claude moved funds between exchange accounts. A user [lost $367 and got their account suspended](https://github.com/anthropics/claude-code/issues/47046) from a Claude-generated script. [Physical coordinates were uploaded to a public website](https://github.com/anthropics/claude-code/issues/46910) despite 17 sessions of "no PII" in CLAUDE.md. And [deny rules can be bypassed with 50+ subcommands](https://adversa.ai/blog/claude-code-security-bypass-deny-rules-disabled/).
-
-Claude Code ships with no safety hooks by default. This tool fixes that. ([Standalone guard script](https://gist.github.com/yurukusa/87f51b97bb655357dd148b66109d0c14) for quick setup | [Database protection hooks](https://gist.github.com/yurukusa/ad27e541769992e9e0cd15c1b487a1d2) | [Credential protection hooks](https://gist.github.com/yurukusa/7292ead735df0aa673f0485eba5587f3) | [Fabrication detection hook](https://gist.github.com/yurukusa/03f4bbbab61f7ddf31049cc28a01d0d9) | [Security vulnerability hooks](https://gist.github.com/yurukusa/81f79ae6d760b27c17f2cd642ea846d7))
-
-**Works with Auto Mode.** Claude Code's [Auto Mode sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) provides container-level isolation. cc-safe-setup adds process-level hooks as defense-in-depth — catching destructive commands even outside sandboxed environments.
-
-**Works with subagents.** Since v2.1.84, subagents and teammates [don't receive CLAUDE.md](https://github.com/anthropics/claude-code/issues/40459) — your project rules are silently skipped. Hooks operate at the process level, but [subagent tool calls may bypass PreToolUse hooks](https://github.com/anthropics/claude-code/issues/21460) in some configurations. As defense-in-depth, cc-safe-setup installs hooks at the user level (`~/.claude/settings.json`). The `subagent-claudemd-inject` example hook re-injects critical rules into subagent prompts.
-
-### 🚨 Opus 4.7 Crisis (April 2026)
-
-Opus 4.7 broke auto mode's safety classifier — it was [hardcoded to Opus 4.6](https://github.com/anthropics/claude-code/issues/49618). **If you use auto mode with Opus 4.7, dangerous commands run without the built-in safety check.** In 3 days: [50 GB permanently deleted](https://github.com/anthropics/claude-code/issues/49129), [~/.ssh wiped](https://github.com/anthropics/claude-code/issues/49554), [git credentials destroyed](https://github.com/anthropics/claude-code/issues/49539), [shell configs truncated to 0 bytes](https://github.com/anthropics/claude-code/issues/49615). Users report [4x token consumption](https://github.com/anthropics/claude-code/issues/49541) from silent model switches.
-
-**One command to fix it:**
-
-```bash
-npx cc-safe-setup --opus47
+```sh
+npx github:yurukusa/cc-safe-setup
 ```
 
-Installs 4 hooks targeting known Opus 4.7 regressions. [Full details →](https://yurukusa.github.io/cc-safe-setup/opus-47-survival-guide.html) · [Emergency Defense Kit (Gist)](https://gist.github.com/yurukusa/6747ea655cc5c374a1ec9ed4fba027e4) · [Safety Scanner](https://yurukusa.github.io/cc-safe-setup/opus47-scanner.html)
-
-## What Gets Installed
-
-| Hook | Prevents | Related Issues |
-|------|----------|----------------|
-| **Destructive Guard** | `rm -rf /`, `git reset --hard`, `git clean -fd`, `git checkout --force`, `sudo` + destructive, PowerShell `Remove-Item -Recurse -Force`, `rd /s /q`, NFS mount detection | [#46058](https://github.com/anthropics/claude-code/issues/46058) [#36339](https://github.com/anthropics/claude-code/issues/36339) [#36640](https://github.com/anthropics/claude-code/issues/36640) [#37331](https://github.com/anthropics/claude-code/issues/37331) |
-| **Branch Guard** | Pushes to main/master + force-push (`--force`) on all branches | |
-| **Secret Guard** | `git add .env`, credential files, `git add .` with .env present | [#6527](https://github.com/anthropics/claude-code/issues/6527) |
-| **Syntax Check** | Python, Shell, JSON, YAML, JS errors after edits | |
-| **Context Monitor** | Session state loss from context window overflow (40%→25%→20%→15% warnings) | |
-| **Comment Stripper** | Bash comments breaking permission allowlists | [#29582](https://github.com/anthropics/claude-code/issues/29582) |
-| **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 | |
-
-Each hook exists because a real incident happened without it.
-
-### Free diagnostic tools
-
-| Tool | What it does |
-|------|-------------|
-| **[Token Checkup](https://yurukusa.github.io/cc-safe-setup/token-checkup.html)** | 5 questions → find where your tokens are going (30 seconds) |
-| **[Security Checkup](https://yurukusa.github.io/cc-safe-setup/security-checkup.html)** | 6 questions based on real incidents ($1,800+ in losses) |
-| **[Version Check](https://yurukusa.github.io/cc-safe-setup/version-check.html)** | Is your CC version affected by cache inflation? |
+The command is interactive: it shows what each hook does and lets you choose which to install into your `~/.claude/settings.json` (or a project-local `.claude/settings.json`). Nothing is installed without your confirmation. MIT licensed.
 
-### Go deeper
+> **Why not `npx cc-safe-setup`?** The npm release is stuck at 29.8.0 (2026-04-20) while this repository is at 30.0.4, and the gap is not cosmetic — 29.8.0 lets twenty-five command shapes through that the current code blocks. Details, including the comparison table, are in [The npm release is behind this repository](#the-npm-release-is-behind-this-repository) below.
 
-| Resource | What you get | Price |
-|----------|-------------|-------|
-| **[Token Book](https://yurukusa.github.io/cc-safe-setup/token-book.html)** | Cut token consumption in half. CLAUDE.md templates, hook configs, context management, 32 failure patterns with fixes. 44,000+ words from 800+ hours of real operation data. | ¥2,500 (~$17). Ch.1 free |
-| **[Safety Guide](https://zenn.dev/yurukusa/books/6076c23b1cb18b)** | End-to-end Claude Code safety setup. From first install to overnight autonomous runs. | ¥800 (~$5). Ch.3 free |
+Reading this in order, rather than by section: **[The Claude Code Safety Field Manual](https://leanpub.com/claude-code-safety-field-manual)** is this repository's documentation laid out as a path — the pre-flight checklist, what each guard actually refuses, how to make one fire on purpose so you can watch it work, and what to read in the log afterwards. The minimum price is zero.
 
-**Why pay?** A Max plan costs $200/month. One token waste incident burns 50–80% of your weekly quota in hours ([#46727](https://github.com/anthropics/claude-code/issues/46727)). One `rm -rf` incident costs days of recovery. The Token Book costs less than 2 hours of Max subscription time — and the CLAUDE.md templates alone can reduce consumption by 40%.
+## Something already broken? Start here
 
-### v2.1.85: `if` Field Support
+If you arrived from a search with something already broken, start here: the symptom on the
+left, and the section that answers it on the right. Every section it points to is a
+measurement on a real machine, not a guess. (A third of the visitors here do arrive from a
+search engine — 51 of 152 unique visitors in the 14 days to 2026-09-19. The rest come from
+links such as a gist or GitHub itself, or with no referrer recorded at all.)
 
-Hooks now support an `if` field for conditional execution. The hook process only spawns when the command matches the pattern — `ls` won't trigger a git-only hook.
+| What you are seeing | Start here | Where |
+|---|---|---|
+| The hook refuses, and the tool call runs anyway | The refusal is in a shape or a word the event does not read — or the hook exited 1, crashed, or could not find `jq` | [A refusal the tool never reads](#a-refusal-the-tool-never-reads), then [Proving a hook fires](#proving-a-hook-fires) |
+| The hook never seems to run at all | The session was started in a way that skips your hooks entirely | [Four ways your guards stop running at all](#four-ways-your-guards-stop-running-at-all) |
+| The hook runs, but never on the commands you care about | Your pattern is anchored where your commands are not | [A hook can be installed, current, registered — and still never see you](#a-hook-can-be-installed-current-registered--and-still-never-see-you) |
+| You are not sure the hook does anything | You have not fired it on purpose yet | [Proving a hook fires](#proving-a-hook-fires) |
+| The hooks are installed but feel out of date | Installed copies are snapshots and do not update themselves | [Your installed hooks do not update themselves](#your-installed-hooks-do-not-update-themselves) |
+| `npx cc-safe-setup` behaves unlike this page | npm is serving an older release | [The npm release is behind this repository](#the-npm-release-is-behind-this-repository) |
 
-```json
-{
-  "type": "command",
-  "if": "Bash(git push *)",
-  "command": "~/.claude/hooks/test-before-push.sh"
-}
-```
+## Install as a Claude Code plugin
 
-All example hooks include `if` field documentation in their headers.
-
-## PermissionRequest Hooks (NEW)
-
-Override Claude Code's built-in confirmation prompts. These run **after** the built-in safety checks, so they can auto-approve prompts that `permissions.allow` cannot suppress.
-
-| Hook | What It Solves | Issue |
-|------|---------------|-------|
-| `quoted-flag-approver` | "Quoted characters in flag names" prompt on `git commit -m "msg"` | [#27957](https://github.com/anthropics/claude-code/issues/27957) |
-| `bash-heuristic-approver` | Safety heuristic prompts for `$()`, backticks, ANSI-C quoting | [#30435](https://github.com/anthropics/claude-code/issues/30435) |
-| `edit-always-allow` | Edit prompts in `.claude/skills/` despite `bypassPermissions` | [#36192](https://github.com/anthropics/claude-code/issues/36192) |
-| `allow-git-hooks-dir` | Edit prompts in `.git/hooks/` for pre-commit/pre-push setup | |
-| `allow-protected-dirs` | All protected directory prompts (CI/Docker environments) | [#36168](https://github.com/anthropics/claude-code/issues/36168) |
-| `git-show-flag-sanitizer` | Strips invalid `--no-stat` from `git show` (wastes context on error) | [#13071](https://github.com/anthropics/claude-code/issues/13071) |
-| `compact-blocker` | Blocks auto-compaction via PreCompact (preserves full context) | [#6689](https://github.com/anthropics/claude-code/issues/6689) |
-| `webfetch-domain-allow` | Auto-approves WebFetch by domain (fixes broken `domain:*` wildcard) | [#9329](https://github.com/anthropics/claude-code/issues/9329) |
-
-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) |
-| `read-before-edit` | Warns when Edit targets a file not recently Read (Read:Edit ratio dropped 70% — [#42796](https://github.com/anthropics/claude-code/issues/42796)) | [#42796](https://github.com/anthropics/claude-code/issues/42796) |
-| `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 |
-|---------|-------------|
-| `npx cc-safe-setup` | Install 8 safety hooks |
-| `--create "desc"` | Generate hook from plain English |
-| `--audit [--fix\|--json\|--badge]` | Safety score 0-100 |
-| `--lint` | Static analysis of config |
-| `--diff <file>` | Compare settings |
-| `--compare <a> <b>` | Side-by-side hook comparison |
-| `--migrate` | Detect hooks from other projects |
-| `--generate-ci` | Create GitHub Actions workflow |
-| `--share` | Generate shareable URL |
-| `--benchmark` | Measure hook speed |
-| `--dashboard` | Real-time terminal UI |
-| `--issues` | GitHub Issues each hook addresses |
-| `--doctor` | Diagnose hook problems |
-| `--watch` | Live blocked command feed |
-| `--stats` | Block history analytics |
-| `--learn [--apply]` | Pattern learning |
-| `--scan [--apply]` | Tech stack detection |
-| `--export / --import` | Team config sharing |
-| `--verify` | Test each hook |
-| `--install-example <name>` | Install from 701 examples |
-| `--examples [filter]` | Browse examples by keyword |
-| `--full` | All-in-one setup |
-| `--status` | Check installed hooks |
-| `--dry-run` | Preview changes |
-| `--uninstall` | Remove all hooks |
-| `--shield` | Maximum safety in one command |
-| `--guard "rule"` | Instantly enforce a rule from English |
-| `--suggest` | Predict risks from project analysis |
-| `--from-claudemd` | Convert CLAUDE.md rules to hooks |
-| `--team` | Project-level hooks for git sharing |
-| `--profile [level]` | Switch safety profiles |
-| `--save-profile <name>` | Save current hooks as profile |
-| `--analyze` | Session analysis dashboard |
-| `--health` | Hook health table |
-| `--quickfix` | Auto-fix common problems |
-| `--replay` | Visual blocked commands timeline |
-| `--why <hook>` | Show real incident behind hook |
-| `--migrate-from <tool>` | Migrate from other hook tools |
-| `--diff-hooks [path]` | Compare hook configurations |
-| `--init-project` | Full project setup (hooks + CLAUDE.md + CI) |
-| `--score` | CI-friendly safety score (exit 1 if below threshold) |
-| `--test-hook <name>` | Test a specific hook with sample input |
-| `--simulate "cmd"` | Preview how all hooks react to a command |
-| `--protect <path>` | Block edits to a file or directory |
-| `--rules [file]` | Compile YAML rules into hooks |
-| `--validate` | Validate all hook scripts (syntax + structure) |
-| `--safe-mode` | Maximum protection: all safety hooks + strict config |
-| `--changelog` | Show what changed in each version |
-| `--report` | Generate safety report |
-| `--help` | Show help |
-
-## Quick Start by Scenario
-
-| I want to... | Command |
-|---|---|
-| Make Claude Code safe right now | `npx cc-safe-setup --shield` |
-| Stop permission prompt spam | `npx cc-safe-setup --install-example auto-approve-readonly` |
-| Enforce a rule instantly | `npx cc-safe-setup --guard "never delete production data"` |
-| See what risks my project has | `npx cc-safe-setup --suggest` |
-| Convert CLAUDE.md rules to hooks | `npx cc-safe-setup --from-claudemd` |
-| Share hooks with my team | `npx cc-safe-setup --team && git add .claude/` |
-| Choose a safety level | `npx cc-safe-setup --profile strict` |
-| See what Claude blocked today | `npx cc-safe-setup --replay` |
-| Know why a hook exists | `npx cc-safe-setup --why destructive-guard` |
-| Block silent memory file edits | `npx cc-safe-setup --install-example memory-write-guard` |
-| Stop built-in skills editing opaquely | `npx cc-safe-setup --install-example skill-gate` |
-| Diagnose why hooks aren't working | `npx cc-safe-setup --doctor` |
-| Preview how hooks react to a command | `npx cc-safe-setup --simulate "git push origin main"` |
-| Protect a specific file from edits | `npx cc-safe-setup --protect .env` |
-| Stop .git/ write prompts | `npx cc-safe-setup --install-example allow-git-hooks-dir` |
-| Auto-approve compound git commands | `npx cc-safe-setup --install-example auto-approve-compound-git` |
-| Detect prompt injection patterns | `npx cc-safe-setup --install-example prompt-injection-detector` |
-| Define rules in YAML, compile to hooks | `npx cc-safe-setup --rules rules.yaml` |
-| Validate all hook scripts are correct | `npx cc-safe-setup --validate` |
-| Maximum protection mode | `npx cc-safe-setup --safe-mode` |
-| Migrate from Cursor/Windsurf | [Migration Guide](https://yurukusa.github.io/cc-safe-setup/migration-guide.html) |
-
-## Plugin Marketplace
-
-Install safety hooks as Claude Code plugins — no npm required:
+The core guard sets are also published as Claude Code plugins from this repository. They install from inside Claude Code and track the default branch, so they do not depend on the npm release at all.
 
-```bash
+```sh
 /plugin marketplace add yurukusa/cc-safe-setup
 /plugin install safety-essentials@cc-safe-setup
 ```
 
 | Plugin | What it blocks |
-|---|---|
-| `safety-essentials` | rm -rf, force-push, hard-reset, .env overwrite, npm publish |
-| `git-protection` | Force-push, main/master push, git clean, branch -D |
-| `credential-guard` | .env write/edit, API keys in commands, service account files |
-
-Also listed on [claudemarketplaces.com](https://claudemarketplaces.com).
-
-## Common Pain Points (from GitHub Issues)
+| --- | --- |
+| `safety-essentials` | `rm -rf`, force-push, `git reset --hard`, writes to `.env`, package publish |
+| `git-protection` | force-push, direct pushes to `main`/`master`, hard reset, interactive rebase, `git clean -fd` |
+| `credential-guard` | `Write`/`Edit` to paths matching `.env`, `.env.*`, `credentials`, `secret`, `serviceaccount*.json`, `key.json`. API keys in Bash commands are **warned about, not blocked** — see the limits below |
+| `token-guard` | reads over 100KB, a per-session read budget, subagent fan-out, a token budget that asks for `/compact` |
+
+These are the guards only. The example-hook library, `--doctor`, `--audit`, and the rest of the CLI come from the npm package or from this repository directly.
+
+### Measured limits of `credential-guard` (2026-09-04, against npm 29.8.0)
+
+These are the exit codes, not the intent. Read them before trusting the row above.
+
+- **Bash is never blocked by this plugin.** Both of its `Bash` hooks print a warning to stderr
+  and return 0. `export ANTHROPIC_API_KEY=…`, `curl -H "Authorization: Bearer …"`, and
+  `git commit -m "… <key> …"` all run. 0 of 6 shapes were blocked.
+- **The same write through Bash is invisible.** `Write` to `~/app/.env` is blocked, but
+  `cp k.env ~/app/.env`, `sed -i … ~/app/.env`, `printf … >> ~/app/.env` and `tee` are not.
+  Install `examples/secret-file-write-guard.sh` for that (it covers 9 of 11 such shapes;
+  `git add .env` belongs to `dotenv-commit-guard.sh`, and writes made inside an interpreter,
+  e.g. `python3 -c "open('.env','w')…"`, cannot be seen from the command string at all).
+- **"Service-account files" is narrower than it sounds, and case-sensitive.** The patterns are
+  `serviceaccount.*\.json`, `key\.json`, `credentials\.json`. So `credentials.json` and
+  `application_default_credentials.json` are blocked, but `gcp-service-account.json`,
+  `service_account.json`, `serviceAccountKey.json` and `firebase-adminsdk.json` are **not**
+  (2 of 7 shapes blocked). A hyphen, an underscore or a capital letter is enough to pass.
+- `.env` itself holds up: `.env`, `.env.production`, `.env.local` and `Edit` on `.env` were all
+  blocked (4 of 4).
+
+Hooks stop a tool call before it runs. They are not a permission boundary — pair them with
+`permissions.deny` and keep secrets outside the repository.
+
+## The npm release is behind this repository
+
+`npx cc-safe-setup` currently installs **29.8.0**, published 2026-04-20. This repository is at **30.0.4**. Publishing is blocked on renewing an npm credential, so npm keeps serving 29.8.0 until that is done.
+
+The gap is not cosmetic. I fired twenty-two command shapes at both versions on 2026-09-03, feeding each guard the same JSON on stdin and running it with `bash` — the shell the installer names when it registers the hook. The guards shipped in 29.8.0 allow **nine** of those shapes that 30.0.4 refuses. Nothing went the other way: there is no shape 29.8.0 blocks and 30.0.4 lets through, and two harmless controls (`rm -rf node_modules`, `git push origin feature`) are allowed by both. Only `exit 2` counts as blocked here; `exit 1`, `exit 127` and a crash all let the command run.
+
+The other thirteen behaved identically in both versions, and they are the plain forms: `rm -rf /`, `cd /tmp && sudo rm -rf /var/log`, `find . -name '*.log' | xargs rm -rf /`, `rm -rf ~/Documents/`, `git reset --hard HEAD~5`, `git clean -fd`, `chmod -R 777 /`, `git push --force origin main`, `git push origin +main`, `git push origin main`, `git add .env`, and the two controls. In other words, 29.8.0 stops the shape you would write in a tutorial and misses the shape a shell actually produces.
+
+All nine:
+
+| Command seen by the hook | Guard | 29.8.0 | 30.0.4 |
+| --- | --- | --- | --- |
+| `rm -rf \` with `~/Documents` on the next line — one deletion split over two lines | destructive-guard | allowed | blocked |
+| `rm --recursive --force /` — long-form spelling of `-rf` | destructive-guard | allowed | blocked |
+| a base64 blob decoded and piped into `sh`, carrying `rm -rf ~` | destructive-guard | allowed | blocked |
+| `rm -rf "$HOME"` — home directory reached through a quoted variable | destructive-guard | allowed | blocked |
+| `git push -uf origin feature` — force bundled into a short-flag cluster | branch-guard | allowed | blocked |
+| `cd repo && git push --force origin main` — force push after a separator | branch-guard | allowed | blocked |
+| `git -C /repo push --force` — git's own option placed before the verb | branch-guard | allowed | blocked |
+| `cd app && git add .env` — a secret staged after a separator | secret-guard | allowed | blocked |
+| `git add \` with `.env` on the next line — the same, split over two lines | secret-guard | allowed | blocked |
+
+### Re-measured 2026-09-14: twenty-five, not nine
+
+Two fixes landed here on 2026-09-14 ([#1120](https://github.com/yurukusa/cc-safe-setup/pull/1120),
+[#1121](https://github.com/yurukusa/cc-safe-setup/pull/1121), and the follow-up that
+carried #1121 into `branch-guard` and `secret-guard`), so the sentence above — written in
+the present tense about "the current code" — went stale the same morning it was true.
+
+Fired again that evening, same method, same `bash`, same JSON on stdin. The original
+twenty-two shapes still split nine and thirteen: 29.8.0 cannot move. What moved is the
+list. Widening it to forty-one shapes puts the gap at **twenty-five**, and nothing still
+goes the other way.
+
+The sixteen new ones:
+
+| Shape family | Example | Guard |
+| --- | --- | --- |
+| git reached through a path | `/usr/bin/git push --force origin main`, `./git push --force origin main`, `/usr/bin/git clean -fd` | branch-guard, destructive-guard |
+| git behind a wrapper | `sudo git push --force origin main`, `time …`, `nohup …` | branch-guard |
+| git behind an assignment | `env FOO=1 git push --force origin main`, `FOO=1 git push --force origin main` | branch-guard |
+| a global option whose value is not a `.git` path | `git --git-dir=/tmp/r/repo.d push --force`, `git --work-tree=/tmp/w --git-dir=… push --force`, `git -c user.name=x push --force`, `git --namespace=ns push --force` | branch-guard |
+| the plumbing spelling of a push | `git send-pack --force origin main` | branch-guard |
+| `-C` in front of the other verbs | `git -C /repo add .env`, `git -C /repo reset --hard HEAD~5`, `git -C /repo clean -fd` | secret-guard, destructive-guard |
+
+The script that produces this comparison is checked in as
+`tests/git-invocation-prefixes-all-guards.test.sh` for the current code; the
+version-against-version run is in the book's evidence folder.
+
+If you are reading this to decide whether the gap matters to you: the number is not the
+point. The point is that it grows every time this repository improves and never shrinks,
+because the published package is frozen.
+
+29.8.0 on npm ships **698** example hooks; this repository has **916**. The 218 that are missing from the published package include `agents-md-sync-checker`. (Counted 2026-08-26 from the published tarball and this tree; the tree was recounted on 2026-09-20 and had gained two since.)
+
+To install the current code directly from this repository:
+
+```sh
+npx github:yurukusa/cc-safe-setup
+```
 
-| Problem | Issue | Fix |
-|---|---|---|
-| Claude uses `cat`/`grep`/`sed` instead of built-in Read/Edit/Grep | [#19649](https://github.com/anthropics/claude-code/issues/19649) (48👍) | `npx cc-safe-setup --install-example prefer-builtin-tools` |
-| `cd /path && cmd` bypasses permission allowlist | [#28240](https://github.com/anthropics/claude-code/issues/28240) (88👍) | `npx cc-safe-setup --install-example compound-command-approver` |
-| Multiline commands skip pattern matching | [#11932](https://github.com/anthropics/claude-code/issues/11932) (47👍) | Use hooks instead of allowlist patterns for complex commands |
-| No notification when Claude asks a question | [#13024](https://github.com/anthropics/claude-code/issues/13024) (52👍) | `npx cc-safe-setup --install-example notify-waiting` |
-| `allow` overrides `ask` in permissions | [#6527](https://github.com/anthropics/claude-code/issues/6527) (17👍) | Use hooks to block dangerous commands instead of `ask` rules |
-| Plans stored in `~/.claude/` with random names | [#12619](https://github.com/anthropics/claude-code/issues/12619) (163👍) | `npx cc-safe-setup --install-example plan-repo-sync` |
+That resolves to the default branch. To pin an exact revision, append a commit SHA — `npx github:yurukusa/cc-safe-setup#<sha>`. Pin by SHA rather than by tag: the tag names here come from an older numbering that no longer tracks `package.json`.
 
-## How It Works
+## Why this exists
 
-1. Writes hook scripts to `~/.claude/hooks/`
-2. Updates `~/.claude/settings.json` to register the hooks
-3. Restart Claude Code — hooks are active
+Claude Code can run shell commands, edit files, and call tools on your behalf. Most of the time that is fine. But a single command — `rm -rf`, a force-push, `terraform destroy`, `php artisan migrate:fresh`, a `git checkout --orphan` followed by `git rm -rf .` — can destroy work in a way that is not recoverable, and it can happen without an error or a warning.
 
-Safe to run multiple times. Existing settings are preserved. A backup is created if settings.json can't be parsed.
+Claude Code's built-in safety checks match shell-level danger patterns. Many destructive operations do not look like those patterns: a framework verb, a tool-call, or a config file poisoned from outside the tool boundary all slip past. These hooks add a second layer that inspects the operation at the tool boundary and refuses the dangerous ones, while letting normal work through.
 
-**Maximum safety:** `npx cc-safe-setup --shield` — one command: fix environment, install hooks, detect stack, configure settings, generate CLAUDE.md.
+## What you need installed
 
-**Instant rule:** `npx cc-safe-setup --guard "never touch the database"` — generates, installs, activates a hook instantly from plain English.
+**Nothing from npm** — this package has no dependencies and installs none.
 
-**Team setup:** `npx cc-safe-setup --team` — copy hooks to `.claude/hooks/` with relative paths, commit to repo for team sharing.
+**One JSON reader, though.** A hook is handed its tool call as JSON on stdin, so it needs
+something that can read JSON. The eight core hooks try `jq`, then `python3`, then `node`, and
+if none of the three is present they print a warning that says they are **not** protecting you,
+then allow the command (blocking every call would make Claude Code unusable, which is a
+failure, not safety).
 
-**Preview first:** `npx cc-safe-setup --dry-run`
+The example hooks are stricter about this than the core ones: **757 of the 916 mention `jq`
+and contain no `python3` or `node` anywhere in the file** — 810 mention `jq` at all, and 53 of
+those also mention a possible fallback. (Counted 2026-09-20 with `grep -l` over `examples/*.sh`;
+an earlier edition claimed 798 of 914, which none of three plausible counting rules reproduced,
+so the rule is spelled out here instead of the number being carried forward.) Without `jq` they
+read an empty command and quietly do nothing — no error, no log line, and they still appear in
+your `settings.json`. If you take examples from `examples/`, install `jq` first.
 
-**Check status:** `npx cc-safe-setup --status` — see which hooks are installed (exit code 1 if missing).
+```sh
+jq --version || sudo apt-get install -y jq   # or: brew install jq
+```
 
-**Verify hooks work:** `npx cc-safe-setup --verify` — sends test inputs to each hook and confirms they block/allow correctly.
+This used to be described as "dependency-free", which was wrong in the direction that matters:
+it let someone on a minimal container believe they were protected when the hooks were reading
+nothing. Corrected 2026-08-03 after counting the actual tool calls in the shipped scripts.
 
-**Troubleshoot:** `npx cc-safe-setup --doctor` — diagnoses why hooks aren't working (jq, permissions, paths, shebang).
+## What gets installed
 
-**Live monitor:** `npx cc-safe-setup --watch` — real-time dashboard of blocked commands during autonomous sessions.
+Hooks are small shell scripts. Each is one file, does one thing, and exits with code `2` to block or `0` to allow. They fall into a few groups:
 
-**Uninstall:** `npx cc-safe-setup --uninstall` — removes all hooks and cleans settings.json.
+- **Destructive-operation guards** — refuse `rm -rf` on protected paths, force-push, `git reset --hard`, whole-tree `git rm`, framework database resets (`migrate:fresh`, `db:reset`, `prisma migrate reset`), cloud teardown verbs (`terraform destroy`, `aws … terminate`, `kubectl delete namespace`), and move-then-delete sequences.
+- **Data-loss prevention** — a recycle bin for deleted files, backups before refactors, detection of NUL-corrupted writes, and guards for the `mv`/glob/`rm` and worktree failure modes.
+- **Cost and quota** — token-spike early warnings, per-session budget limits, subagent fan-out limits, and warnings when usage is silently routed to API billing.
+- **Silent-failure surfacing** — detectors for fabricated tool results, unverified "done" claims, forged system-reminder markup from sub-agents, and config poisoned from outside the tool boundary (read-only audits that warn, never edit).
+- **Session and config protection** — backups of `settings.json`, drift detection, and recovery helpers.
+- **Code-quality checks** (opt-in) — syntax checks, test-before-commit, and language-specific linters that run after edits.
 
-**Requires:** [jq](https://jqlang.github.io/jq/) for JSON parsing (`brew install jq` / `apt install jq`).
+Run `npx github:yurukusa/cc-safe-setup --list` to see every available hook with its description.
 
-**Note:** Hooks are skipped when Claude Code runs with `--bare` or `--dangerously-skip-permissions`. These modes bypass all safety hooks by design.
+## How it works
 
-**Known limitations:**
+Claude Code calls a hook before (or after) a tool runs and passes it JSON on stdin describing the tool call. The hook reads the command, decides, and communicates through its exit code:
 
-- In headless mode (`-p` / `--print`), hook exit code 2 may not block tool execution ([#36071](https://github.com/anthropics/claude-code/issues/36071)). For CI pipelines, use interactive mode with hooks rather than `-p` mode.
-- `FileChanged` notifications inject file contents into model context **before** hooks can intervene. If a sensitive file (`.env`, `credentials.json`) is modified externally during a session, its contents may appear in the conversation transcript regardless of hooks ([#44909](https://github.com/anthropics/claude-code/issues/44909)). Mitigation: use `dotenv-watch` to get alerted, and avoid editing sensitive files while Claude Code is running.
+```sh
+#!/bin/sh
+CMD=$(cat | jq -r '.tool_input.command // empty')
+case "$CMD" in
+  *"migrate:fresh"*|*"db:wipe"*)
+    echo "Blocked: destructive database reset. Use an incremental migration." >&2
+    exit 2 ;;   # exit 2 = block the tool call
+esac
+exit 0          # exit 0 = allow
+```
 
-## Before / After
+Because the check happens at the tool boundary, it fires regardless of how the command was constructed, and it works in auto-accept mode where a human is not reviewing each step.
 
-Run `npx cc-health-check` to see the difference:
+## Writing your own hook
 
-| | Before | After |
-|---|--------|-------|
-| Safety Guards | 25% | **75%** |
-| Overall Score | 50/100 | **95/100** |
-| Destructive commands | Unprotected | Blocked |
-| Force push | Allowed | Blocked |
-| `.env` in git | Possible | Blocked |
-| Context warnings | None | 4-stage alerts |
+A hook is any executable that reads the tool-call JSON on stdin and returns `0` (allow) or `2` (block, with a message on stderr). Drop it in your hooks directory and reference it from `settings.json` under the matching trigger (`PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `SubagentStop`, `PermissionRequest`) with a `matcher` for the tool it should watch. See `examples/` for working scripts to copy.
 
-## Configuration
+## Safety audit and CI
 
-| Variable | Hook | Default |
-|----------|------|---------|
-| `CC_ALLOW_DESTRUCTIVE=1` | destructive-guard | `0` (protection on) |
-| `CC_SAFE_DELETE_DIRS` | destructive-guard | `node_modules:dist:build:.cache:__pycache__:coverage` |
-| `CC_PROTECT_BRANCHES` | branch-guard | `main:master` |
-| `CC_ALLOW_FORCE_PUSH=1` | branch-guard | `0` (protection on) |
-| `CC_SECRET_PATTERNS` | secret-guard | `.env:.env.local:credentials:*.pem:*.key` |
-| `CC_CONTEXT_MISSION_FILE` | context-monitor | `$HOME/mission.md` |
+`npx github:yurukusa/cc-safe-setup --audit` reports which classes of danger are and are not guarded.
 
-## After Installing
+Most of what it checks lives inside `settings.json`. One check does not: it reads the safety nets your `CLAUDE.md` **names** against the hooks your settings files actually **register**, and reports the two mismatches that no single-file check can see — a rule naming a script that exists nowhere, and a hook sitting in your hooks directory that appears in no settings file at all. Both files are individually valid in that second case; the guard simply never runs.
 
-Verify your setup:
+You can run the same audit in CI to keep a project's safety posture from regressing:
 
-```bash
-npx cc-health-check
+```yaml
+# .github/workflows/safety.yml
+- run: npx github:yurukusa/cc-safe-setup --audit --ci
 ```
 
-## Full Kit
+`--ci` exits `1` when the audit finds a `CRITICAL` or `HIGH` risk, and `0` otherwise. The line
+is drawn there and not at "any risk" because a machine set up the way this tool recommends
+still carries a `MEDIUM` finding, and a gate that reddens a correct setup gets deleted by the
+first person who sees the build. Set `CC_AUDIT_THRESHOLD` to also fail below a score.
 
-cc-safe-setup gives you 8 essential hooks. Want to know what else your setup needs?
+**If you added this step before 2026-09-03, it never failed.** `--ci` was in this README and
+in nobody's code: the exit compared the score against a default threshold of `0`, and a score
+cannot go below `0`, so the step passed whatever the audit found. That is worse than having no
+step, because the belief that a regression would be caught is what stops you looking. It is
+implemented now, and `tests/audit-ci-gate.test.sh` fails if it ever stops failing.
 
-Run `npx cc-health-check` (free, 20 checks) to see your current score. If it's below 80, the **[Claude Code Ops Kit](https://yurukusa.github.io/cc-ops-kit-landing/?utm_source=github&utm_medium=readme&utm_campaign=safe-setup)** fills the gaps — 6 hooks + 5 templates + 9 scripts + install.sh. Pay What You Want ($0+).
+`--audit` is what a script can decide on its own. For the contradictions that need your
+session logs and CI read alongside your config, there are
+[written audits](#written-audits) below — asynchronous, and nothing is ever
+run in your environment.
 
-**Starter Kit:** Want hooks + settings + templates in one download? The **[Claude Code Safety Kit](https://yurukusa.itch.io/claude-code-safety-kit)** bundles 5 safety hooks, a pre-configured settings.json, CLAUDE.md templates, and 800-hour operation tips. Name your price ($0+).
+### Proving a hook fires
 
-Or browse the free hooks: [claude-code-hooks](https://github.com/yurukusa/claude-code-hooks)
+`--audit` reads configuration. It cannot tell you whether a registered hook actually
+refuses anything, and that is where most of the damage in `examples/` came from: a
+guard that is present, registered, and silent.
 
-## Examples
-
-## Safety Audit
-
-**[Try it in your browser](https://yurukusa.github.io/cc-safe-setup/)** — paste your settings.json, get a score instantly. Nothing leaves your browser.
-
-Or from the CLI:
+`audit/` holds four small scripts for the other half.
 
 ```bash
-npx cc-safe-setup --audit
+# does this guard refuse the operation it was written to refuse?
+audit/fire.sh ~/.claude/hooks/YOUR-HOOK.sh Bash "command=<the dangerous command>"
+#   exit 2 = refused, exit 0 = Claude Code runs it
+#   (a hook that refuses through JSON exits 0 and still blocks — this line will call it
+#    "allowed". See "A refusal the tool never reads" below before rewriting such a hook.)
+
+# same hook, on a machine with no jq, no python3 and no node
+audit/fire.sh --bare ~/.claude/hooks/YOUR-HOOK.sh Bash "command=<the dangerous command>"
 ```
 
-Analyzes 9 safety dimensions and gives you a score (0-100) with one-command fixes for each risk.
+The `--bare` run is the one worth doing today. **757 of the 916 example hooks here mention
+`jq` and contain no `python3` or `node` fallback anywhere in the file** (counted 2026-09-20).
+Without a JSON parser they print a warning to stderr and exit `0` — and Claude Code stops for
+exit code `2`, not for warnings.
 
-### CI Integration (GitHub Action)
+`audit/count-hooks.py` counts registrations across all three settings files;
+`audit/find-dead-hooks.sh` lists registrations whose script is not on disk (those fail to
+launch, which Claude Code treats as non-blocking, so nothing surfaces);
+`audit/selftest.sh` proves that detector really detects, because a detector that has never
+found anything is not yet evidence of anything. `audit/audit-checklist.md` is a 50-point
+sheet covering hooks, git, secrets, cost, autonomous operation and multi-agent work.
 
-```yaml
-# .github/workflows/safety.yml
-- uses: yurukusa/cc-safe-setup@main
-  with:
-    threshold: 70  # CI fails if score drops below this
-```
+## A refusal the tool never reads
 
-### Project Scanner
+A `PreToolUse` hook can run, compute the right decision, print it, and be ignored. Nothing
+errors. The hook exits 0, there is no verdict, and the tool call proceeds — so the logs of a
+guard that is silently open look exactly like the logs of one that is working.
 
-```bash
-npx cc-safe-setup --scan         # detect tech stack, recommend hooks
-npx cc-safe-setup --scan --apply # auto-create CLAUDE.md with project rules
-```
+Measured 2026-09-19 on Claude Code 2.1.278, one hook at a time on `PreToolUse` with matcher
+`Write`, in a throwaway `HOME`. Each hook appended a line to its own log before printing, so
+"never invoked" and "invoked and ignored" stay separable. The verdict is whether the file
+exists on disk afterwards, not what the transcript says:
 
-### Create Hooks from Plain English
+| What the hook printed | Hook ran | File created |
+|---|---|---|
+| nothing, `exit 0` *(control)* | yes | yes |
+| `{"permissionDecision":"deny", …}` — **at the top level** | yes | **yes — ignored** |
+| `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny", …}}` | yes | no |
+| `{"decision":"block","reason":…}`, `exit 0` — the older shape | yes | no |
+| `{"decision":"deny"}` | yes | **yes — ignored** |
+| stderr + `exit 2` | yes | no |
+
+The uppercase `{"decision":"DENY"}` was measured the same day, but on matcher `Bash` and with
+the verdict being whether the command actually ran; it was ignored there too. It is left out
+of the table above because it was not fired under these conditions.
+
+Two things fall out of that table.
+
+**`permissionDecision` belongs inside `hookSpecificOutput`.** At the top level it is not read
+here. The minimal repro in [anthropics/claude-code#91574](https://github.com/anthropics/claude-code/issues/91574)
+(open since 2026-09-02, reported against 2.1.245 on macOS) uses the top-level shape, so this
+is one thing worth ruling out before anything else. It is not a diagnosis of that report: the
+same report also says `PreToolUse` never registers in the debug trace at all, and nothing
+about an unreadable body explains a missing registration line.
+
+**The older `{"decision": …}` field answers to `block`.** It still refuses on 2.1.278 — if you
+have a working hook using it, leave it alone. `deny` and `DENY` are dropped in silence. Other
+values were not fired, so treat this as two data points rather than a vocabulary. One of the guards in this repository's
+example library did exactly that, on three branches that block irreversible deletions, from
+the day it was written until it was measured. Its tests were green the whole time, because
+they asserted that the string `"decision":"DENY"` appeared on stdout and never looked at the
+exit code. It refuses with `exit 2` as of 2026-09-19. **If you copied that example before
+then, take it again** — or run `--outdated`, which compares your installed copies against
+what ships today.
+
+### Checking your own, in two runs
+
+`exit 2` carries no JSON, so it cannot be misparsed. Replace the line that prints your JSON
+with these two — do not keep both, because printing a body *and* exiting 2 was not measured:
 
 ```bash
-npx cc-safe-setup --create "block npm publish without tests"
-npx cc-safe-setup --create "auto approve test commands"
-npx cc-safe-setup --create "block curl pipe to bash"
-npx cc-safe-setup --create "block DROP TABLE and TRUNCATE"
+echo "denied" >&2
+exit 2
 ```
 
-9 built-in templates + generic fallback. Creates the script, registers it, and runs a smoke test.
+If the call is blocked now, your hook was always being consulted and the JSON shape was the
+problem. If it still goes through, the shape is a red herring: either the hook is not
+loaded at all, or it is loaded and your pattern never matches what you actually run. Go to
+[Four ways your guards stop running at all](#four-ways-your-guards-stop-running-at-all) and
+[A hook can be installed, current, registered — and still never see you](#a-hook-can-be-installed-current-registered--and-still-never-see-you).
 
-### Self-Learning Safety
+Run it twice: once with a hook that only does `exit 0`, once with yours. The first run must
+let the operation through. Without that control, "nothing happened" can mean the guard
+worked, or that the command was broken, or that the harness never fired.
 
-```bash
-npx cc-safe-setup --learn        # analyze your block history for patterns
-npx cc-safe-setup --learn --apply # auto-generate custom hooks from patterns
-```
+One practical difference, once you have a choice: both of the JSON shapes that do refuse —
+the nested `permissionDecision` and `{"decision":"block"}` — reach the model as
+`PreToolUse:Write hook error: <your reason>` (measured on `Write`), with nothing identifying
+which hook produced it. `exit 2` arrives with the hook's absolute path in front of the
+message. With more than a couple of hooks on the same tool, that is the difference between
+opening one file and opening all of them.
 
-## Examples
-
-Need custom hooks beyond the 8 built-in ones? Install any example with one command:
+## A hook can be installed, current, registered — and still never see you
 
 ```bash
-npx cc-safe-setup --install-example block-database-wipe
+npx github:yurukusa/cc-safe-setup --blindspots
 ```
 
-Or browse all available examples in [`examples/`](examples/):
-
-- **auto-approve-git-read.sh** — Auto-approve `git status`, `git log`, even with `-C` flags
-- **auto-approve-ssh.sh** — Auto-approve safe SSH commands (`uptime`, `whoami`, etc.)
-- **enforce-tests.sh** — Warn when source files change without corresponding test files
-- **notify-waiting.sh** — Desktop notification when Claude Code waits for input (macOS/Linux/WSL2)
-- **edit-guard.sh** — Block Edit/Write to protected files (defense-in-depth for [#37210](https://github.com/anthropics/claude-code/issues/37210))
-- **auto-approve-build.sh** — Auto-approve npm/yarn/cargo/go/python build, test, and lint commands
-- **auto-approve-docker.sh** — Auto-approve docker build, compose, ps, logs, and other safe commands
-- **block-database-wipe.sh** — Block destructive database commands: Laravel `migrate:fresh`, Django `flush`, Rails `db:drop`, raw `DROP DATABASE` ([#46684](https://github.com/anthropics/claude-code/issues/46684) [#46650](https://github.com/anthropics/claude-code/issues/46650) [#37405](https://github.com/anthropics/claude-code/issues/37405) [#37439](https://github.com/anthropics/claude-code/issues/37439))
-- **auto-approve-python.sh** — Auto-approve pytest, mypy, ruff, black, isort, flake8, pylint commands
-- **auto-snapshot.sh** — Auto-save file snapshots before edits for rollback protection ([#37386](https://github.com/anthropics/claude-code/issues/37386) [#37457](https://github.com/anthropics/claude-code/issues/37457))
-- **allowlist.sh** — Block everything not explicitly approved — inverse permission model ([#37471](https://github.com/anthropics/claude-code/issues/37471))
-- **protect-dotfiles.sh** — Block modifications to `~/.bashrc`, `~/.aws/`, `~/.ssh/` and chezmoi without diff ([#37478](https://github.com/anthropics/claude-code/issues/37478))
-- **scope-guard.sh** — Block file operations outside project directory — absolute paths, home, parent escapes ([#36233](https://github.com/anthropics/claude-code/issues/36233))
-- **auto-checkpoint.sh** — Auto-commit after every edit for rollback protection ([#34674](https://github.com/anthropics/claude-code/issues/34674))
-- **git-config-guard.sh** — Block `git config --global` modifications without consent ([#37201](https://github.com/anthropics/claude-code/issues/37201))
-- **deploy-guard.sh** — Block deploy commands when uncommitted changes exist ([#37314](https://github.com/anthropics/claude-code/issues/37314))
-- **network-guard.sh** — Warn on suspicious network commands sending file contents ([#37420](https://github.com/anthropics/claude-code/issues/37420))
-- **test-before-push.sh** — Block `git push` when tests haven't been run ([#36970](https://github.com/anthropics/claude-code/issues/36970))
-- **large-file-guard.sh** — Warn when Write tool creates files over 500KB
-- **commit-message-check.sh** — Warn on non-conventional commit messages (feat:, fix:, docs:, etc.)
-- **env-var-check.sh** — Block hardcoded API keys (sk-, ghp_, glpat-) in export commands
-- **timeout-guard.sh** — Warn before long-running commands (npm start, rails s, docker-compose up)
-- **branch-name-check.sh** — Warn on non-conventional branch names (feature/, fix/, etc.)
-- **todo-check.sh** — Warn when committing files with TODO/FIXME/HACK markers
-- **path-traversal-guard.sh** — Block Edit/Write with `../../` path traversal and system directories
-- **case-sensitive-guard.sh** — Detect case-insensitive filesystems (exFAT, NTFS, HFS+) and block rm/mkdir that would collide due to case folding ([#37875](https://github.com/anthropics/claude-code/issues/37875))
-- **compound-command-approver.sh** — Auto-approve safe compound commands (`cd && git log`, `cd && npm test`) that the permission system can't match ([#30519](https://github.com/anthropics/claude-code/issues/30519) [#16561](https://github.com/anthropics/claude-code/issues/16561))
-- **tmp-cleanup.sh** — Clean up accumulated `/tmp/claude-*-cwd` files on session end ([#8856](https://github.com/anthropics/claude-code/issues/8856))
-- **session-checkpoint.sh** — Save session state to mission file before context compaction ([#37866](https://github.com/anthropics/claude-code/issues/37866))
-- **verify-before-commit.sh** — Block git commit when lint/test commands haven't been run ([#37818](https://github.com/anthropics/claude-code/issues/37818))
-- **hook-debug-wrapper.sh** — Wrap any hook to log input/output/exit code/timing to `~/.claude/hook-debug.log`
-- **loop-detector.sh** — Detect and break command repetition loops (warn at 3, block at 5 repeats)
-- **commit-quality-gate.sh** — Warn on vague commit messages ("update code"), long subjects, mega-commits
-- **session-handoff.sh** — Auto-save git state and session info to `~/.claude/session-handoff.md` on session end
-- **diff-size-guard.sh** — Warn/block when committing too many files at once (default: warn at 10, block at 50)
-- **dependency-audit.sh** — Warn when installing packages not in manifest (npm/pip/cargo supply chain awareness)
-- **env-source-guard.sh** — Block sourcing .env files into shell environment ([#401](https://github.com/anthropics/claude-code/issues/401))
-- **symlink-guard.sh** — Detect symlink/junction traversal in rm targets ([#36339](https://github.com/anthropics/claude-code/issues/36339) [#764](https://github.com/anthropics/claude-code/issues/764))
-- **no-sudo-guard.sh** — Block all sudo commands
-- **no-install-global.sh** — Block npm -g and system-wide pip
-- **no-curl-upload.sh** — Warn on curl POST/upload (data exfiltration)
-- **no-port-bind.sh** — Warn on network port binding
-- **git-tag-guard.sh** — Block pushing all tags at once
-- **npm-publish-guard.sh** — Version check before npm publish
-- **max-file-count-guard.sh** — Warn when 20+ new files created per session
-- **protect-claudemd.sh** — Block edits to CLAUDE.md and settings files
-- **reinject-claudemd.sh** — Re-inject CLAUDE.md rules after compaction ([#6354](https://github.com/anthropics/claude-code/issues/6354))
-- **binary-file-guard.sh** — Warn when Write targets binary file types (images, archives)
-- **stale-branch-guard.sh** — Warn when working branch is far behind default
-- **cost-tracker.sh** — Estimate session token cost and warn at thresholds ($1, $5)
-- **read-before-edit.sh** — Warn when editing files not recently read (prevents old_string mismatches)
-
-## Safety Checklist
-
-**[SAFETY_CHECKLIST.md](SAFETY_CHECKLIST.md)** — Copy-paste checklist for before/during/after autonomous sessions.
-
-## Windows Support
-
-Works on Windows via WSL or Git Bash. Native PowerShell is not supported (hooks are bash scripts).
-
-**Common issue:** If you see `Permission denied` or `No such file` errors after install, run:
+Every other check here reads one layer. `--status` reads the scripts on disk, `--lint` the
+settings file, `--stats` the block log, `--outdated` the shipped bodies. A guard can pass all
+four and still never fire, because the shape of the commands you actually run never reaches
+it. That gap does not live inside any one layer, so no single-layer check can report it.
+
+`--blindspots` reads your own session transcripts next to your own guards and reports what
+each start-anchored pattern really matches. On the machine it was written on: 38,066 Bash
+calls, **89.1% of them compound** and **32.0% beginning with `cd`** — and `branch-guard.sh`
+examining 47 of 377 `git push` calls, because the other 330 came after a `cd … &&`.
+
+It reads only. Nothing is sent anywhere and nothing is written back. Patterns that are allow
+tests rather than gates are excluded, and a verb is counted only where it starts a command
+segment, so a `git add` inside a quoted string is not mistaken for one that ran.
+
+## Four ways your guards stop running at all
+
+`--blindspots` finds guards that are loaded but never matched. There is a harder case it cannot
+see: the guard is **never loaded**, or the tool it watches **no longer exists**. Four documented
+ways to start Claude Code do that, and none of them reports it.
+
+Measured 2026-09-19 on Claude Code **2.1.278**, Linux under WSL2, with a disposable `HOME` and a
+scratch working directory. Arrival was measured on `UserPromptSubmit` — deliberately not
+`PreToolUse` on `Bash`, because `--restricted` removes Bash, and then "the hook was ignored" and
+"nothing pulled the trigger" look identical.
+
+| How you start it | Your hooks | Bash |
+| --- | --- | --- |
+| *(control)* no flags | user, project and local all fire | present |
+| `--dangerously-skip-permissions` | still fire — the guard refused, exit 2 | present |
+| `claude --restricted` | **none load**; `--settings` is the only way back in I measured | **removed** |
+| `claude --safe-mode` | **none load**, and `--settings` does **not** bring them back | **present** |
+| `CLAUDE_CODE_RESTRICTED=1` | same as `--restricted` | removed |
+| `CLAUDE_CODE_SAFE_MODE=1` | same as `--safe-mode` | **present** |
+
+The control row matters: without it, "the guard stayed quiet" and "the guard is broken" are the
+same observation. It fired and refused, so the guard works — it simply was not asked in the rows
+where it is silent.
+
+`--dangerously-skip-permissions` is in the table because people expect it to be the worst row for
+their hooks. It is not: what that flag removes is the human prompt, not your guards. This table is
+only about whether your hooks load, so do not read the second column as "this flag is safe."
+
+### `claude --safe-mode` is not our `--safe-mode`
+
+These are two different things with the same name, and one of them is ours:
+
+- **`npx github:yurukusa/cc-safe-setup --safe-mode`** — *this tool*, and it is blunter than its
+  name suggests: it moves **every** `.sh` in `~/.claude/hooks` aside and empties the `hooks` block
+  of your `settings.json` — not just ours, yours and anyone else's too. It backs the file up
+  first, it tells you what it did, and **it stays off until you run `--safe-mode off`**, which
+  restores the hooks and copies the backup back over `settings.json` (so edits you make to that
+  file while safe mode is on are lost). Being honest about that: ours is the one you set once and
+  can forget, which is exactly the shape this section warns about.
+- **`claude --safe-mode`** — *Claude Code*. Per invocation, for troubleshooting a broken
+  configuration. Its own help says auth, model selection, **built-in tools and permissions work
+  normally** — so your guards are gone and everything they guard against is still there.
+
+We tell you to reach for our `--safe-mode` when a hook locks you out. Do not let that make
+`claude --safe-mode` sound like the cautious choice. Of the ways to start Claude Code listed
+above, the one whose name sounds safest is the only one that removes your hooks while leaving
+the dangerous tools in place.
+
+### The environment variables are the quiet ones
+
+A flag is retyped every time you start. A line in your shell profile is read once and never seen
+again. Under `--restricted` there is at least a tell — asked to run a shell command, the model
+said in substance that the shell tool was missing and that the absence looked deliberate. Under
+`--safe-mode` there is nothing to notice in the reply: every tool is present, the command runs,
+the answer reads normally, and only the guard is quiet.
+
+That was measured non-interactively (`claude -p`). Interactively you would likely notice, because
+`--safe-mode` also drops `CLAUDE.md`, skills, plugins and MCP servers. The dangerous case is the
+automated one — a script, a cron job, an unattended loop — where nobody reads the session.
+
+**Check this first, it takes one command:**
 
 ```bash
-npx cc-safe-setup --doctor
+grep -rn "CLAUDE_CODE_RESTRICTED\|CLAUDE_CODE_SAFE_MODE" \
+  ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc ~/.zshenv 2>/dev/null
 ```
 
-This detects Windows backslash paths (`C:\Users\...` → `C:/Users/...`) and missing execute permissions.
+That covers the usual shell files. It will not find a variable set anywhere else your shell,
+editor, terminal profile, container image or service manager can set one — check those too if the
+grep comes back empty and something still looks wrong.
 
-See [Issue #1](https://github.com/yurukusa/cc-safe-setup/issues/1) for details.
+### Getting the hooks back is not the same as being guarded
 
-## Troubleshooting
+Under `--restricted` you can pass them in with `--settings`, and they load. They still only cover
+tools that survive. **Of the 24 `PreToolUse` registrations this repository installs by default —
+six in `hooks/hooks.json` plus eighteen across the four plugins — 16 are matched on `Bash`**, and
+`--restricted` is exactly the mode with no Bash. (The 916 files under `examples/` are not
+registered; these 24 are what actually runs after an install.) The file tools remain, confined to
+the working directories; both `Write` and `Edit` were measured modifying a file with no guard
+consulted.
 
-**[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** — "Hook doesn't work" → step-by-step diagnosis. Covers every common failure pattern.
+The five that already watch the file tools are the ones still standing in that mode: the
+`Write|Edit` guard in `hooks/hooks.json`, three in `credential-guard` (`Write`, `Edit`, `Write`),
+and one `Write` guard in `safety-essentials`. If you run `--restricted`, those five are your
+coverage — check they cover what you care about, because the other sixteen cannot fire.
 
-## settings.json Reference
+To be fair to the flag: `--restricted` did not create that gap. In the control run, with Bash
+available, the model went straight to `Write` anyway — a Bash-only guard never covered that path.
+What `--restricted` changes is that `Write` stops being one option among several and becomes the
+only one. If you run `--restricted`, your guards need to be on `Write` and `Edit`.
 
-**[SETTINGS_REFERENCE.md](SETTINGS_REFERENCE.md)** — Complete reference for permissions, hooks, modes, and common configurations. Includes known limitations and workarounds.
+**Not measured:** managed (policy) settings. The help says they survive both flags. There is no
+`/etc/claude-code/` on the machine this was measured on, so that one is documentation, not
+measurement.
 
-## Migration Guide
+## Your installed hooks do not update themselves
 
-**[MIGRATION.md](MIGRATION.md)** — Step-by-step guide for moving from permissions-only to permissions + hooks. Keep your existing config, add safety layers on top.
+Installing a hook copies the file. **Nothing ever copies it back.** A hook installed in March
+keeps running its March logic forever, including bugs fixed here months later.
 
-## Learn More
-
-- **[Opus 4.7 Survival Guide](https://yurukusa.github.io/cc-safe-setup/opus-47-survival-guide.html)** — 61 known issues (76+ GitHub Issues + CVEs) with fixes: data loss, recursive spawn DoS, billing mismatch, subagent OOM, cache_read anomaly, allowedTools bypass, 1.7x token inflation, classifier failure, thinking summary bugs, 30-min stalls, enterprise hooks bypass, and more. [`npx cc-safe-setup --opus47`](#-opus-47-crisis-april-2026)
-- **[Token Book (¥2,500)](https://zenn.dev/yurukusa/books/token-savings-guide)** — Cut token consumption in half. CLAUDE.md optimization, hook-based guards, context management, workflow design. 44,000 words with copy-paste templates. Intro + Ch.1 free. [Details](https://yurukusa.github.io/cc-safe-setup/token-book.html)
-- **[Safety Guide (¥800)](https://zenn.dev/yurukusa/books/6076c23b1cb18b)** — Token consumption diagnosis, file loss prevention, autonomous operation safety. From 800+ hours of real incidents. [Chapter 3 free](https://zenn.dev/yurukusa/books/6076c23b1cb18b/viewer/3-code-quality)
-- **[800 Hours Operation Record (¥800)](https://zenn.dev/yurukusa/books/3c3c3baee85f0a19)** — Non-engineer running Claude Code autonomously for 800 hours. Failures, recovery, revenue reality. [Chapter 2 free](https://zenn.dev/yurukusa/books/3c3c3baee85f0a19/viewer/2-first-failures)
-- **Wiki Guides**: [Token FAQ](https://github.com/yurukusa/cc-safe-setup/wiki/Claude-Code-Token-FAQ) · [CLAUDE.md Best Practices](https://github.com/yurukusa/cc-safe-setup/wiki/CLAUDE-md-Best-Practices) · [Token Optimization](https://github.com/yurukusa/cc-safe-setup/wiki/Token-Optimization-Guide)
-- [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/))
-- [Skills Guide deep-dive (Qiita, 19K+ views)](https://qiita.com/yurukusa/items/f69920b4a02cf7e2988c) — Anthropic's official Skills PDF analyzed with 40% token reduction
-- [Japanese guide (Qiita)](https://qiita.com/yurukusa/items/a9714b33f5d974e8f1e8) — この記事の日本語解説
-- [v2.1.85 `if` field guide (Qiita)](https://qiita.com/yurukusa/items/7079866e9dc239fcdd57) — Reduce hook overhead with conditional execution
-- [Deny rules bypass vulnerability (Qiita)](https://qiita.com/yurukusa/items/f9c48bb44569bbf4492e) — 50+ subcommands disable all deny rules; hook-based defense
-- [Hook Test Runner](https://github.com/yurukusa/cc-hook-test) — `npx cc-hook-test <hook.sh>` to auto-test any hook
-- [Hook Registry](https://github.com/yurukusa/cc-hook-registry) — `npx cc-hook-registry search database` ([browse online](https://yurukusa.github.io/cc-hook-registry/))
-- [Hooks Cheat Sheet](https://yurukusa.github.io/cc-safe-setup/cheatsheet.html) — printable A4 quick reference
-- [Ecosystem Comparison](https://yurukusa.github.io/cc-safe-setup/ecosystem.html) — all Claude Code hook projects compared
-- [The incident that inspired this tool](https://github.com/anthropics/claude-code/issues/36339) — NTFS junction rm -rf
-- [How to prevent rm -rf disasters](https://yurukusa.github.io/cc-safe-setup/prevent-rm-rf.html) — real incidents and the hook that stops them
-- [How to prevent force-push to main](https://yurukusa.github.io/cc-safe-setup/prevent-force-push.html) — branch protection via hooks
-- [How to prevent secret leaks](https://yurukusa.github.io/cc-safe-setup/prevent-secret-leaks.html) — stop git add . from committing .env
-
-### Free Gists
-
-- [settings.json Complete Template](https://gist.github.com/yurukusa/8ec367cf65042bf9fbd83c35931e7ed1) — copy-paste ready safety configuration
-- [First 3 Safety Steps](https://gist.github.com/yurukusa/72513272be9a4ee29b058e2b08453e1a) — 5-minute safety setup from scratch
-- [CLAUDE.md Before/After](https://gist.github.com/yurukusa/f9d7df5930bfb6d36a25673e69720f7e) — 40% token reduction through better writing patterns
-- [Token Savings Cheat Card](https://gist.github.com/yurukusa/cfe44bfbb3756eccaf51660466913a2d) — 5 techniques to cut consumption in half
-- [Token Consumption Checklist](https://gist.github.com/yurukusa/db8700a9f9fa331d36664df2868274cb) — 10-item diagnostic
-- [Outage Survival Kit](https://gist.github.com/yurukusa/a0e31171eecb527d0df1d5498bf5f5d0) — what to do when Claude Code is down
-- [CLAUDE.md Token Optimizer](https://gist.github.com/yurukusa/2b98fd2e90c0c13f6918c9f915e08e27) — 35-line template, 40% token reduction (800h tested)
-- [Worktree Safety Hooks](https://gist.github.com/yurukusa/98bd43c5d0d8a6ebbf2cf21bfc1e2907) — 3 hooks to protect against worktree deletion and cross-tree destruction
-- [Opus 4.7 Emergency Checklist](https://gist.github.com/yurukusa/c95efaee4b670e067369ece08092960c) — token burn diagnosis + immediate fixes
-- [Cache TTL Mitigation Guide](https://gist.github.com/yurukusa/178d3949cd2bd6fbfc275b408f9711d4) — #46829 cache TTL change (1h→5m) impact and 4 mitigations
-- [Security Checkup Hooks](https://gist.github.com/yurukusa/81f79ae6d760b27c17f2cd642ea846d7) — 4 hooks for financial, PII, deny bypass, and background task protection
-- [Cache Breakage Fix](https://gist.github.com/yurukusa/fe6ba0a6aee14207f27ecc84419878b4) — 2 root causes of prompt cache invalidation (#47107 git status, #47098 session restart)
-- [CLAUDE.md Token Optimization Cheat Sheet](https://gist.github.com/yurukusa/556f67c493a2729ce9b1703f5003a227) — 5 CLAUDE.md patterns that reduce token consumption with before/after examples
-- [Token Troubleshooting Guide](https://gist.github.com/yurukusa/47b8c3eadb77cf74946f450f992ddac2) — fix quota drain, cache bugs, 1M context trap. Symptom-based diagnosis with latest issue references
-- [Token Optimization Guide (English)](https://gist.github.com/yurukusa/70ff830c0ad3dff83e53be26cd80bd0a) — 3 biggest token levers with hook code, practical walkthrough
-- [Token Book Sampler: 5 Techniques](https://gist.github.com/yurukusa/4a867ba301b480f996c5b76e4b6a6fbc) — free preview of the Token Book — 5 immediate techniques to reduce consumption
-- [Token Optimization Checklist](https://gist.github.com/yurukusa/4b75025beee916f9904f56b79eeb1217) — 10-step checklist to cut token consumption in half, with hook configs
-- [3 Things That Actually Work](https://gist.github.com/yurukusa/621f6d1cc35816df3da2e07876b44e16) — CLAUDE.md sizing, cache TTL, subagent control — based on 800h data
-- [Cache TTL Diagnostic](https://gist.github.com/yurukusa/3a5bdcfdd295bef17b3ee00978b299f2) — 3 patterns that break prompt cache + fixes
-- [Token Book Ch.1 Free Preview](https://gist.github.com/yurukusa/de862573f18d1a0a68d411b696dbcb73) — Where are your Claude Code tokens going? The 4 layers of token consumption explained
-- [Deny Rules Break After 50 Subcommands](https://gist.github.com/yurukusa/0463d240d7b725218289a556414c72a5) — the hook that fixes Claude Code's deny rule bypass vulnerability
-- [Opus 4.7 Emergency Kit](https://gist.github.com/yurukusa/1970b20fed95a682b72eb6e857e61d30) — 5 commands to protect your data from Opus 4.7 regressions (auto mode broken, 23+ data loss incidents)
-- [cache_read Billing Bug Guide](https://gist.github.com/yurukusa/d5dc731dbc69e3ca92d69832bed641cb) — Opus 4.7 cache_read billed at full rate. Anthropic confirmed. Max plan users losing quota 3-6x faster
-- [Opus 4.7 Survival Guide Summary](https://gist.github.com/yurukusa/5d66f0bcfe3fbfc73e6db106e10c533d) — 50 known issues with quick reference table, free diagnostic tools, and one-command fix
-- [Opus 4.7 Known Issues Quick Reference](https://gist.github.com/yurukusa/2c1effab34a7554130d2704fdac59dff) — 26 issues / 43+ GitHub bugs in one table. Severity ratings and direct issue links
-- [4 New Critical Issues (April 18)](https://gist.github.com/yurukusa/37c19b5b7f50fd8bbbeda5e1336c352e) — DoS via recursive spawn, subagent OOM, billing mismatch, UI/CLI model mismatch
-- [トークン消費を半分にする方法](https://gist.github.com/yurukusa/bf4040a905148d9ca02898a53185fae1) — 800時間の実測データ＋設定テンプレート（日本語）
-- [How to Cut Token Usage in Half](https://gist.github.com/yurukusa/704d5cf9874f553dad5c46fccf53b09f) — 800h real data + config templates (English)
-- [Compaction Triple Threat](https://gist.github.com/yurukusa/aa15f2065199c6fac4dcd3796fbaf90f) — 3 compaction bugs active simultaneously (#50402 + #50467 + #50492)
-- [Sandbox Relative Path Bug (CRITICAL)](https://gist.github.com/yurukusa/a98efb6c561f92c82bcd49125af3b32a) — denyWrite/denyRead silently ignores relative paths (#50454)
-- [27 Token Symptoms Quick Reference](https://gist.github.com/yurukusa/03a379854fa0f8eca091a75f7aab593b) — all 27 known token failure modes with top 5 killers table and April 2026 new symptoms
-- [Token Saving Checklist (15 Items)](https://gist.github.com/yurukusa/6bd0d0a38a4887fc36475dd1f765ecd1) — ordered by impact: critical (30-50%), important (10-20%), good practice (5-10%)
-- [Opus 4.7 Survival Cheatsheet](https://gist.github.com/yurukusa/f2d6e261338eeda70f0ed9507f995c13) — 46 known problems, quick fixes under 60 seconds, full reference table
-
-### Professional Services
-
-Need help configuring Claude Code safely? [**Safety Setup Service**](https://yurukusa.github.io/cc-safe-setup/services.html) — audit, token optimization, and custom hooks by the cc-safe-setup team.
-
-## FAQ
-
-**Q: I installed hooks but Claude says "Unknown skill: claude-code-hooks:setup"**
+```bash
+npx github:yurukusa/cc-safe-setup --outdated
+```
 
-cc-safe-setup installs **hooks**, not skills or plugins. Hooks run automatically in the background — you don't invoke them manually. After install + restart, try running a dangerous command; the hook will block it silently.
+This reports which of your installed hooks no longer match what ships today, and exits `1`
+if any do, so it can run in CI. It only reports — it never overwrites, because a file that
+differs may be your own edit.
 
-**Q: `cc-health-check` says to run `cc-safe-setup` but I already did**
+**If you ran this before 2026-08-12, run it again.** Until then it compared your hooks
+directory against `examples/` only, and the core guards — the ones `--install` writes by
+default — are not files under `examples/`; they live in `scripts.json`. So every core guard
+was reported as *"not shipped by this project — not checked"*, whatever its state.
 
-cc-safe-setup covers Safety Guards (75-100%) and Monitoring (context-monitor). The other health check dimensions (Code Quality, Recovery, Coordination) require additional CLAUDE.md configuration or manual hook installation from [claude-code-hooks](https://github.com/yurukusa/claude-code-hooks).
+That mattered. On the machine where this was found, three core guards were two and a half
+months behind, and feeding the same input to the installed and shipped copies showed **six
+dangerous command shapes that the shipped version blocks and the installed one let
+through** — among them `cd /tmp && git push --force origin main` and `cd /tmp && git add
+.env`. Each of those commands *on its own* was blocked by both copies, which is what makes
+it a real gap rather than a bad measurement.
 
-**Q: Will hooks slow down Claude Code?**
+Core guards are not in `examples/`, so `--install-example` cannot fetch one. To see what
+ships today and compare it yourself:
 
-No. Each hook runs in ~10ms. They only fire on specific events (before tool use, after edits, on stop). No polling, no background processes.
+```bash
+npx github:yurukusa/cc-safe-setup --show-core branch-guard > /tmp/shipped.sh
+diff ~/.claude/hooks/branch-guard.sh /tmp/shipped.sh
+```
 
-**Q: My permission patterns don't match compound commands like `cd /path && git status`**
+`--show-core` prints to stdout and writes nothing.
 
-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.
+## Rolling this out to a team
 
-**Q: `--dangerously-skip-permissions` still prompts for `.claude/` and `.git/` writes**
+If you are the person who has to justify Claude Code to the rest of your organization, these are written for that job. All free, all usable as-is — no sign-up, no inquiry.
 
-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.
+| | What it answers |
+|---|---|
+| [Team adoption safety checklist](https://htmlpreview.github.io/?https://gist.githubusercontent.com/yurukusa/75a565d9582fd31860f7c1a2e4cc938e/raw/team-adoption-checklist-jp.html) | The 7 things to settle before you hand this to developers, plus a shared policy template and a CI gate you can paste (JP) |
+| [Settings reference](https://yurukusa.github.io/cc-safe-setup/settings-reference.html) | What each `settings.json` key actually does, and the ones that silently do nothing when written in the wrong place |
+| [Cost governance for teams](https://yurukusa.github.io/cc-safe-setup/team-cost-governance-jp.html) | The three gaps the official usage limits don't cover, and how to close them with free hooks — cited to the official docs (JP) · [EN](https://yurukusa.github.io/cc-safe-setup/team-cost-governance.html) |
+| [Monthly compliance report sample](https://yurukusa.github.io/cc-safe-setup/org-guard-monthly-report-sample.html) | What a monthly "is it actually working" report looks like, for SOC2 or a customer audit answer (fictional company, marked as such) |
+| [Safety audit](https://yurukusa.github.io/cc-safe-setup/safety-audit.html) | Which classes of danger your current setup does and does not guard |
 
-**Q: `allow: ["Bash(*)"]` overrides my `ask` rules**
+The hooks themselves stay free (MIT), always, and bug reports and questions are always welcome in issues and discussions.
 
-`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.
+## Written audits
 
-**Q: Hooks silently fail on macOS (Homebrew `jq` not found)**
+Three asynchronous written audits exist ($29 and $219): no call, no meeting, and nothing is ever
+run in your environment. Each publishes its full deliverable before you buy, run against my own
+setup. Scope, prices and the samples are in [SERVICES.md](SERVICES.md). Corporate audits,
+training, rollout consulting and monthly retainers are **not** offered.
 
-Claude Code runs hooks with a restricted PATH that excludes `/opt/homebrew/bin` ([#46954](https://github.com/anthropics/claude-code/issues/46954)). If `jq` is installed via Homebrew, hooks silently exit 0. Fix: add `export PATH="/opt/homebrew/bin:$PATH"` at the top of your hook script, or use absolute paths like `/opt/homebrew/bin/jq`. Inline hooks in `settings.json` may also be affected — add a PATH export prefix: `export PATH="/opt/homebrew/bin:$PATH"; INPUT=$(cat); ...`
+## Windows
 
-**Q: How is this different from [claude-token-efficient](https://github.com/drona23/claude-token-efficient)?**
+The hooks run under WSL2 and Git Bash. A few guards are Windows-specific (path handling, CJK-write corruption, the `ext4.vhdx` growth case). See `docs/windows.md`.
 
-Different goals. claude-token-efficient optimizes CLAUDE.md to make Claude's responses shorter and cheaper. cc-safe-setup prevents dangerous operations (file deletion, credential leaks, force-push). They work well together: use claude-token-efficient for cost reduction, cc-safe-setup for safety. For comprehensive token optimization beyond CLAUDE.md (hooks, context management, workflow design), see the [Token Book](https://yurukusa.github.io/cc-safe-setup/token-book.html).
+## Troubleshooting
 
-**Still stuck?** See the full [Permission Troubleshooting Flowchart](https://gist.github.com/yurukusa/b64217ffcb908fa309dbfcfa368cd84d) for step-by-step diagnosis.
+If a hook does not fire, check that it is executable, that its path in `settings.json` is correct, and that the `matcher` names the right tool. `npx github:yurukusa/cc-safe-setup --doctor` checks these and reports what is misconfigured.
 
 ## Contributing
 
-**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.
-
-If cc-safe-setup saved you from a disaster (or just saved you time), a ⭐ helps others find it too.
+Contributions are welcome. Each hook should be a single shell script with a test, and should not pull anything from npm. See [CONTRIBUTING.md](CONTRIBUTING.md) for the layout, the test harness, and how to handle the JSON reader.
 
-## Also by yurukusa
+## Where these hooks came from
 
-- [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
+Every hook here exists because something broke first — a destroyed working tree, a credential
+read that should not have happened, an overnight cost spike. The incident behind each one, what
+the logs actually looked like, and what finally stopped it, are written up at length. Those
+write-ups are books, and they are listed in [docs/books.md](docs/books.md).
 
 ## License
 
-MIT
+MIT. See [LICENSE](LICENSE).