cc-safe-setup 29.8.0 → 30.0.5

package/TROUBLESHOOTING.md

@@ -5,11 +5,32 @@ Your hook isn't working. Here's how to fix it, starting with the most common cau
 ## Quick Diagnosis
 
 ```bash
-npx cc-safe-setup --doctor
+npx github:yurukusa/cc-safe-setup --doctor
 ```
 
 This checks jq, settings.json, file permissions, shebangs, and common misconfigurations. If it says "All checks passed" but hooks still don't fire, read on.
 
+## "No hooks fire at all on Windows" (Git for Windows PATH bug)
+
+If you are on the Windows Desktop app with Git for Windows installed, and **every** `"type": "command"` hook silently does nothing — including these guards — regardless of the command, this is likely an upstream shell-resolution bug, not your config.
+
+Symptoms (visible if you run the CLI with `--output-format stream-json` and watch the `hook_response` events):
+
+```
+Error occurred while executing hook command: Executable not found in $PATH: "C:\Program Files\Git\bin"
+Failed to run: EFTYPE: inappropriate file type or format, uv_spawn
+```
+
+Note the path is missing the trailing `\bash.exe`. The hook runner enumerates `$PATH`, hits the bare `C:\Program Files\Git\bin` entry that the Git for Windows installer adds, and tries to spawn that **directory** as the shell instead of appending `\bash.exe`. It fails during shell auto-detection, before your command ever runs — so the failure is identical no matter what the hook does, and nothing is surfaced in the normal UI.
+
+How to confirm it is this and not a config problem:
+
+- The `--doctor` above says everything is fine, yet no hook has any effect.
+- Registering a trivial hook (`echo fired >> C:\Users\you\hook.log` on `SessionStart`) produces no log line.
+- The stream-json error names the `Git\bin` directory (without `bash.exe`).
+
+This is tracked upstream at [anthropics/claude-code#73971](https://github.com/anthropics/claude-code/issues/73971) (has-repro). Until it is fixed there, a machine hitting this cannot run command hooks, so do not assume these guards are protecting a Windows machine with this symptom — verify with the log test above first. WSL2 sessions resolve the shell differently and are not affected the same way; running Claude Code under WSL2 is the reliable path on Windows while the upstream fix is pending.
+
 ## "Hook doesn't block anything"
 
 ### 1. Did you restart Claude Code?
@@ -25,7 +46,7 @@ cat ~/.claude/settings.json | jq '.hooks'
 You should see your hook's path under the correct trigger. If not:
 
 ```bash
-npx cc-safe-setup  # Re-registers all hooks
+npx github:yurukusa/cc-safe-setup  # Re-registers all hooks
 ```
 
 ### 3. Is the hook file executable?
@@ -180,7 +201,7 @@ This is a known Claude Code limitation, not a hook issue. `Bash(git:*)` doesn't
 Fix:
 
 ```bash
-npx cc-safe-setup --install-example compound-command-approver
+npx github:yurukusa/cc-safe-setup --install-example compound-command-approver
 ```
 
 ## "Hooks slow down Claude Code"
@@ -188,7 +209,7 @@ npx cc-safe-setup --install-example compound-command-approver
 ### 1. Check execution time
 
 ```bash
-npx cc-safe-setup --install-example hook-debug-wrapper
+npx github:yurukusa/cc-safe-setup --install-example hook-debug-wrapper
 # Then wrap your slow hook to see timing
 ```
 
@@ -206,7 +227,7 @@ Hooks with `"matcher": ""` run on every single tool call. Move heavy checks to s
 ### 3. Use --lint to find issues
 
 ```bash
-npx cc-safe-setup --lint
+npx github:yurukusa/cc-safe-setup --lint
 ```
 
 Reports performance warnings and configuration issues.
@@ -216,7 +237,7 @@ Reports performance warnings and configuration issues.
 ### 1. Compare settings
 
 ```bash
-npx cc-safe-setup --diff teammate-settings.json
+npx github:yurukusa/cc-safe-setup --diff teammate-settings.json
 ```
 
 Shows exactly what's different between your setups.
@@ -224,9 +245,9 @@ Shows exactly what's different between your setups.
 ### 2. Export and share
 
 ```bash
-npx cc-safe-setup --export   # Creates cc-safe-setup-export.json
+npx github:yurukusa/cc-safe-setup --export   # Creates cc-safe-setup-export.json
 # Send to teammate
-npx cc-safe-setup --import cc-safe-setup-export.json
+npx github:yurukusa/cc-safe-setup --import cc-safe-setup-export.json
 ```
 
 ### 3. Different jq versions
@@ -243,7 +264,7 @@ LOG="$HOME/.claude/blocked-commands.log"
 echo "[$(date -Iseconds)] BLOCKED: reason | cmd: $COMMAND" >> "$LOG"
 ```
 
-Then view with: `npx cc-safe-setup --watch` or `npx cc-safe-setup --stats`
+Then view with: `npx github:yurukusa/cc-safe-setup --watch` or `npx github:yurukusa/cc-safe-setup --stats`
 
 ## "claude -p returns empty output when Stop hook is configured"
 
@@ -253,7 +274,7 @@ This is a known Claude Code v2.1.83 bug ([#38651](https://github.com/anthropics/
 
 ```bash
 # Quick toggle: comment out Stop hooks before -p commands
-npx cc-safe-setup --status  # See which hooks are active
+npx github:yurukusa/cc-safe-setup --status  # See which hooks are active
 # Manually comment out Stop hooks in ~/.claude/settings.json
 # Run your -p command
 # Uncomment Stop hooks after
@@ -299,8 +320,8 @@ The hook has a strict whitelist. If a command isn't on the list, it passes throu
 
 ```bash
 # Install token tracking hooks
-npx cc-safe-setup --install-example prompt-usage-logger
-npx cc-safe-setup --install-example compact-alert-notification
+npx github:yurukusa/cc-safe-setup --install-example prompt-usage-logger
+npx github:yurukusa/cc-safe-setup --install-example compact-alert-notification
 ```
 
 After a session, check:
@@ -363,8 +384,8 @@ If you see `input length = 0`, that hook is not receiving stdin.
 
 ## Still Stuck?
 
-1. Wrap the hook with debug wrapper: `npx cc-safe-setup --install-example hook-debug-wrapper`
+1. Wrap the hook with debug wrapper: `npx github:yurukusa/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
+3. Run `npx github:yurukusa/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/action.yml

@@ -29,8 +29,11 @@ runs:
       shell: bash
       run: |
         echo "::group::Claude Code Safety Audit"
-        npx cc-safe-setup@latest --audit --json 2>/dev/null > /tmp/audit-json.txt || true
-        npx cc-safe-setup@latest --audit 2>&1 | tee /tmp/audit-output.txt
+        # Run the repository, not the npm entry. The published npm package is frozen at
+        # 29.8.0 (2026-04-20) and misses guards added since, so `npx cc-safe-setup@latest`
+        # would let this action pass a repository that the current checks refuse.
+        npx -y github:yurukusa/cc-safe-setup --audit --json 2>/dev/null > /tmp/audit-json.txt || true
+        npx -y github:yurukusa/cc-safe-setup --audit 2>&1 | tee /tmp/audit-output.txt
         echo "::endgroup::"
 
         # Parse JSON output
@@ -39,11 +42,16 @@ runs:
           GRADE=$(python3 -c "import json; print(json.load(open('/tmp/audit-json.txt'))['grade'])" 2>/dev/null || echo "?")
           RISK_COUNT=$(python3 -c "import json; print(len(json.load(open('/tmp/audit-json.txt'))['risks']))" 2>/dev/null || echo "0")
         else
-          SCORE=$(grep -oP 'Safety Score: \K\d+' /tmp/audit-output.txt || echo "0")
+          # Fallback: strip ANSI colour codes first, otherwise the escape
+          # sequence between "Safety Score: " and the number defeats the match.
+          SCORE=$(sed 's/\x1b\[[0-9;]*m//g' /tmp/audit-output.txt | grep -oP 'Safety Score: \K\d+' | head -1)
           GRADE="?"
           RISK_COUNT="?"
         fi
 
+        # Guard against an empty parse so the threshold comparison stays numeric.
+        [ -z "$SCORE" ] && SCORE="0"
+
         THRESHOLD="${{ inputs.threshold }}"
 
         echo "score=$SCORE" >> $GITHUB_OUTPUT
@@ -53,7 +61,7 @@ runs:
         echo "Safety Score: $SCORE/100 (Grade: $GRADE, Risks: $RISK_COUNT, Threshold: $THRESHOLD)"
 
         if [ "$SCORE" -lt "$THRESHOLD" ]; then
-          echo "::error::Safety score $SCORE is below threshold $THRESHOLD. Run 'npx cc-safe-setup --audit --fix' to improve."
+          echo "::error::Safety score $SCORE is below threshold $THRESHOLD. Run 'npx github:yurukusa/cc-safe-setup --audit --fix' to improve."
           exit 1
         else
           echo "::notice::Safety score $SCORE meets threshold $THRESHOLD ✓"

package/audit/README.md

@@ -0,0 +1,84 @@
+# The Claude Code Safety Audit — course resources
+
+Eight scripts and one sheet. Everything here runs against whatever Claude Code
+setup you already have. Nothing here requires my hooks or my repository.
+
+| File | What it does |
+|---|---|
+| `fire.sh` | Hands one hook the operation it is supposed to refuse, and prints the decision. `--bare` repeats it with no `jq`, no `python3` and no `node` on `PATH`. |
+| `boundary.sh` | Takes one thing your hook should refuse and fires the hook at its neighbours — backups, case changes, a trailing space — and at things it must let through. Counts holes and overreach separately. |
+| `count-hooks.py` | Reads all three settings files and reports how many hook groups are registered in each, plus the merge. |
+| `find-dead-hooks.sh` | Lists registrations whose script is not on disk. Those produce no error and no symptom. |
+| `find-unfirable-rules.sh` | Lists rules whose pattern cannot match anything, in the scripts your settings register and in inline commands. Two mechanisms: a pattern starting with a dash, which `grep` reads as options; and lookaround in an engine that has none. |
+| `audit-checklist.md` | The 50-point sheet, in six sections. |
+| `selftest.sh` | Proves `find-dead-hooks.sh` actually detects a missing registration, using a throwaway directory. Run it once if you want evidence that the detector works before you trust its silence. |
+| `boundary-selftest.sh` | The same evidence for `boundary.sh`: builds a guard with a known hole and a guard without one, and checks that the report separates them. |
+| `unfirable-selftest.sh` | The same evidence for `find-unfirable-rules.sh`: two rules that cannot match, two correct spellings of the same patterns, and the same pair written inline. Checks that it reports the first of each and not the second. |
+
+## The three exit codes
+
+Claude Code hands a hook the tool call as JSON on standard input and reads its
+exit code.
+
+| Code | Meaning |
+|---|---|
+| `0` | allow the operation |
+| `2` | refuse it, and show what the hook wrote to standard error |
+| anything else | the hook itself failed, and the operation proceeds |
+
+A warning printed to standard error does not stop anything. Only `2` does.
+
+## Quick start
+
+```bash
+chmod +x fire.sh boundary.sh find-dead-hooks.sh selftest.sh boundary-selftest.sh
+
+# 1. What is registered?
+python3 count-hooks.py
+
+# 2. Are any registrations pointing at nothing?
+./find-dead-hooks.sh
+
+# 3. Does a guard you rely on actually refuse?
+./fire.sh <your-hook> Bash "command=<the dangerous command>"
+
+# 4. Does it still refuse on a machine without a JSON parser?
+./fire.sh --bare <your-hook> Bash "command=<the dangerous command>"
+
+# 5. Does it also refuse the neighbours of that operation?
+./boundary.sh <your-hook> Read file_path <the file it must protect>
+```
+
+Step 4 is the one that changes most people's score. Step 5 is the one that
+changes it a second time, after you have fixed what steps 3 and 4 found.
+
+## Why step 5 exists
+
+Steps 3 and 4 answer "does the guard refuse this exact operation". That is
+necessary and it is not enough. A path-matching guard draws a border, and the
+holes are never in the middle of the protected area — they are just outside it,
+on names nobody thought to type.
+
+The hook shipped in this repository refused `id_rsa` and allowed `id_rsa.bak`.
+After that was fixed it still allowed `id_rsa~`, `id_rsa.old.2`, and `id_rsa`
+with a trailing space. Each of those is the same file to whoever reads it and a
+different string to the matcher. All three were found by `boundary.sh` on a
+guard that had just been widened by hand and looked finished.
+
+`boundary.sh` also fires at things the guard must **let through** — the `.pub`
+half of the key, a `.md` file that merely names it — and counts those separately
+as overreach. A guard that refuses everything is not safe, it is unusable, and
+there is no way to notice you have built one by testing refusals alone.
+
+Rows marked `policy` are printed and not scored. Whether a key outside the
+`.ssh` directory should be refused is your decision, not this script's.
+
+## A note on steps 3 and 5
+
+Both run the hook with a throwaway `HOME`, so a hook that writes state into its
+config directory will not touch yours while you are testing. Neither sandboxes
+anything else: a hook that itself runs destructive commands would still run
+them. Read a hook before you fire it — they are short.
+
+No file is ever opened. A `PreToolUse` hook only sees the arguments of the tool
+call, so the paths you pass do not need to exist, and no real key is read.

package/audit/audit-checklist.md

@@ -0,0 +1,152 @@
+# Claude Code Safety Audit Checklist
+
+**50-point assessment for Claude Code environments.**
+Complete this checklist to identify gaps in your safety configuration.
+Score: each ✅ = 1 point. Target: 40+ for production use, 45+ for autonomous operation.
+
+---
+
+## Hooks (15 points)
+
+Your first line of defense. Hooks intercept dangerous operations before they execute.
+
+| # | Check | Status | Notes |
+|---|-------|--------|-------|
+| 1 | **Destructive command guard** — `rm -rf`, `git reset --hard`, `git clean -fd` are blocked | ☐ | |
+| 2 | **Force push guard** — `git push --force` (and `--force-with-lease` on shared branches) is blocked | ☐ | |
+| 3 | **Main branch push guard** — direct `git push` to main/master is blocked | ☐ | |
+| 4 | **Sensitive file write guard** — writes to `.env`, credentials, key files are blocked | ☐ | |
+| 5 | **Sensitive file edit guard** — edits to `.env`, credentials, key files are blocked (separate from Write) | ☐ | |
+| 6 | **Package publish guard** — `npm publish`, `docker push`, etc. require human execution | ☐ | |
+| 7 | **External API write guard** — outbound POST/PUT/DELETE requests are blocked or flagged | ☐ | |
+| 8 | **SQL destruction guard** — `DROP TABLE`, `TRUNCATE`, unscoped `DELETE` are blocked | ☐ | |
+| 9 | **Sudo guard** — `sudo` commands are blocked | ☐ | |
+| 10 | **Permission change guard** — `chmod 777`, recursive `chmod`/`chown` are blocked | ☐ | |
+| 11 | **Infrastructure file warning** — edits to Dockerfile, CI config, package.json trigger a warning | ☐ | |
+| 12 | **Long command warning** — commands over 500 characters are flagged for review | ☐ | |
+| 13 | **Hooks are tested** — you have verified each hook actually blocks by triggering it intentionally | ☐ | |
+| 14 | **Hooks survive updates** — hooks are in version control or backed up outside `~/.claude/` | ☐ | |
+| 15 | **Hook failure mode is visible** — if a hook cannot read its input (no `jq`/`python3`/`node`), it says so on stderr instead of exiting 0 in silence. Refusing every call is an outage, not a guard | ☐ | |
+
+## Git Protection (10 points)
+
+Git is both your safety net and your biggest risk vector.
+
+| # | Check | Status | Notes |
+|---|-------|--------|-------|
+| 16 | **Work happens on feature branches** — CLAUDE.md explicitly requires branching | ☐ | |
+| 17 | **Commits have meaningful messages** — convention is documented (conventional commits, etc.) | ☐ | |
+| 18 | **Pre-commit tests** — tests run before or immediately after each commit | ☐ | |
+| 19 | **Backup branch before risky changes** — documented procedure for `git checkout -b backup/...`, **and you have used it at least once** | ☐ | |
+| 20 | **No orphaned branches** — process exists to clean up merged/stale branches | ☐ | |
+| 21 | **`.gitignore` covers sensitive files as a class** — `.env`, `*.pem`, `*.key`, `credentials.*` are all listed (check 28 covers `.env` alone) | ☐ | |
+| 22 | **`.gitignore` covers generated files** — `node_modules/`, `__pycache__/`, `dist/`, build artifacts are listed | ☐ | |
+| 23 | **Git hooks complement Claude hooks** — pre-commit and pre-push hooks exist at the repository level | ☐ | |
+| 24 | **Rebase/merge strategy is documented** — team knows whether to rebase or merge | ☐ | |
+| 25 | **Force push is disabled server-side** — branch protection rules on GitHub/GitLab block force push to main | ☐ | |
+
+## Credentials & Secrets (8 points)
+
+One leaked secret can cost more than your entire project.
+
+| # | Check | Status | Notes |
+|---|-------|--------|-------|
+| 26 | **No hardcoded secrets in source** — grep your codebase for API keys, passwords, tokens | ☐ | |
+| 27 | **Environment variables for all secrets** — documented in `.env.example` (without values) | ☐ | |
+| 28 | **`.env` is gitignored** — confirmed in `.gitignore`, verified with `git status` | ☐ | |
+| 29 | **Secret scanning is active** — GitHub secret scanning, `gitleaks`, or equivalent is enabled | ☐ | |
+| 30 | **API tokens have minimum scope** — each token has only the permissions it needs | ☐ | |
+| 31 | **Token expiration is set** — tokens expire and have a documented renewal process | ☐ | |
+| 32 | **Service account keys are secured** — GCP/AWS/Azure keys are not in the project directory | ☐ | |
+| 33 | **Git history is clean** — no secrets were ever committed (check with `git log -p -S "password"`) | ☐ | |
+
+## Token & Cost Management (7 points)
+
+Uncontrolled token usage can drain your budget overnight.
+
+| # | Check | Status | Notes |
+|---|-------|--------|-------|
+| 34 | **CLAUDE.md is under 500 lines** — bloated instructions waste tokens on every message | ☐ | |
+| 35 | **No redundant context** — instructions are not duplicated across CLAUDE.md, settings, and hooks | ☐ | |
+| 36 | **Large file reads are targeted** — `Read` calls use `offset` and `limit` for files over 200 lines | ☐ | |
+| 37 | **Subagents are used for exploration** — research tasks are offloaded, not done in the main context | ☐ | |
+| 38 | **Session cost is monitored** — you check `/cost` or equivalent regularly | ☐ | |
+| 39 | **Spending limits are configured** — Anthropic Console or API usage limits are set | ☐ | |
+| 40 | **Compact triggers are understood** — you know when context compaction happens and what it loses | ☐ | |
+
+## Autonomous Operation (5 points)
+
+Running Claude Code unattended requires extra safeguards.
+
+| # | Check | Status | Notes |
+|---|-------|--------|-------|
+| 41 | **All external writes are blocked** — `curl POST`, `gh issue create`, API calls are hook-blocked | ☐ | |
+| 42 | **Configuration files are protected** — CLAUDE.md and settings.json cannot be self-modified | ☐ | |
+| 43 | **Remote access is blocked** — `ssh`, `scp`, `rsync` to remote hosts are hook-blocked | ☐ | |
+| 44 | **Service management is blocked** — `systemctl`, `service` commands are hook-blocked | ☐ | |
+| 45 | **Error escalation path exists** — after N failures, the agent logs the issue and moves on (not infinite retry) | ☐ | |
+
+## Team & Multi-Agent (5 points)
+
+When multiple people or agents share a codebase, coordination failures become the primary risk.
+
+| # | Check | Status | Notes |
+|---|-------|--------|-------|
+| 46 | **Shared hooks in version control** — `.claude/settings.json` is committed and reviewed via PR | ☐ | |
+| 47 | **CLAUDE.md changes require review** — project instructions are not unilaterally changed | ☐ | |
+| 48 | **File lock awareness** — multi-agent setups have a mechanism to detect concurrent edits | ☐ | |
+| 49 | **PR review is mandatory** — branch protection rules enforce at least one approving review | ☐ | |
+| 50 | **Personal overrides don't weaken safety** — `.claude/settings.local.json` cannot disable project-level hooks | ☐ | |
+
+---
+
+## Scoring Guide
+
+| Score | Rating | Recommendation |
+|-------|--------|----------------|
+| **45–50** | Excellent | Ready for autonomous and team use |
+| **40–44** | Good | Safe for supervised use. Address gaps before going autonomous |
+| **30–39** | Fair | Significant gaps. Do not run unattended |
+| **20–29** | Poor | High risk of data loss or secret exposure. Fix immediately |
+| **< 20** | Critical | Stop using Claude Code on this project until remediated |
+
+## How to Use This Checklist
+
+1. **Initial audit:** Go through all 50 items. Mark each ✅ or ❌
+2. **Prioritize fixes:** Credentials & Hooks failures are highest priority
+3. **Re-audit monthly:** New dependencies, team members, and workflows introduce new risks
+4. **After incidents:** Re-run the relevant section to find the root cause
+
+## Quick Verification Commands
+
+```bash
+# Check if .env is gitignored
+git check-ignore .env; echo "exit $?"   # 0 = ignored (pass), 1 = NOT ignored (fail)
+
+# Search for hardcoded secrets in source
+# One --include per extension: a braced list is passed to grep literally and
+# matches nothing, so the command returns a reassuring zero. Verified 2026-08-27.
+grep -rn "password\|api_key\|secret\|token" \
+  --include="*.js" --include="*.ts" --include="*.py" --include="*.go" --include="*.rb" . \
+  | grep -v node_modules | grep -v test
+
+# Verify hooks are loaded
+# `claude --print-settings` is not a flag the CLI has (checked 2026-08-27 against
+# 2.1.246; it exits 1 and prints usage). Read the three settings files instead:
+for f in ~/.claude/settings.json .claude/settings.json .claude/settings.local.json; do
+  [ -f "$f" ] && echo "$f: $(jq '[.hooks[]?[]?] | length' "$f")"
+done
+
+# Check for secrets in git history
+# A git pathspec does not brace-expand either. List the globs. Verified 2026-08-27.
+git log -p --all -S "API_KEY" --diff-filter=A -- "*.js" "*.ts" "*.py" "*.go" "*.rb"
+
+# Verify branch protection (GitHub)
+# Run inside the repository; gh fills in {owner}/{repo} from the remote.
+# "Branch not protected" is a failing check 25/49, not an error.
+gh api repos/{owner}/{repo}/branches/main/protection | jq '.required_pull_request_reviews'
+```
+
+---
+
+*Part of [Claude Code Safety Mastery](https://yurukusa.gumroad.com/l/pcctdn). Use this checklist to protect your projects, your secrets, and your budget.*

package/audit/boundary-selftest.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# boundary-selftest.sh - prove that boundary.sh actually distinguishes a guard
+# with a hole from a guard without one.
+#
+# A detector that reports "holes: 0" is worthless until you have watched it
+# report a hole it was supposed to find. This builds two guards in a throwaway
+# directory - one anchored so tightly that backups walk through, one widened -
+# and checks that boundary.sh separates them in both directions.
+set -u
+HERE=$(cd "$(dirname "$0")" && pwd)
+T=$(mktemp -d)
+trap 'rm -rf "$T"' EXIT
+PASS=0; FAIL=0
+check() {  # check <description> <expected> <actual>
+  if [ "$2" = "$3" ]; then echo "  PASS: $1"; PASS=$((PASS + 1))
+  else echo "  FAIL: $1 (expected $2, got $3)"; FAIL=$((FAIL + 1)); fi
+}
+
+# A guard that refuses the exact name and nothing near it.
+cat > "$T/narrow.sh" <<'SH'
+#!/bin/bash
+F=$(cat | grep -o '"file_path":"[^"]*"' | sed 's/.*:"//; s/"$//')
+[ -z "$F" ] && exit 0
+echo "$F" | grep -qE 'id_rsa$' && { echo "BLOCKED" >&2; exit 2; }
+exit 0
+SH
+
+# The same guard, widened to cover backups, and still letting .pub through.
+# The -i is not decoration: the first draft of this fixture omitted it and
+# boundary.sh correctly reported ID_RSA as a hole. Case folding is one of the
+# neighbours, so a fixture that means to be clean has to fold case too.
+cat > "$T/wide.sh" <<'SH'
+#!/bin/bash
+F=$(cat | grep -o '"file_path":"[^"]*"' | sed 's/.*:"//; s/"$//')
+[ -z "$F" ] && exit 0
+echo "$F" | grep -qiE '\.pub[[:space:]]*$' && exit 0
+echo "$F" | grep -qiE 'id_rsa(([._-](bak|old|orig|save|copy|backup|[0-9]+))|~){0,3}[[:space:]]*$' \
+  && { echo "BLOCKED" >&2; exit 2; }
+exit 0
+SH
+
+# A guard that refuses everything. Safe-looking and unusable; the "allow" rows
+# exist to catch exactly this, so the detector must call it overreach.
+cat > "$T/paranoid.sh" <<'SH'
+#!/bin/bash
+cat >/dev/null
+echo "BLOCKED" >&2
+exit 2
+SH
+chmod +x "$T"/*.sh
+
+echo "=== control 1: a narrow guard must be reported as having holes ==="
+out=$(bash "$HERE/boundary.sh" "$T/narrow.sh" Read file_path /home/me/.ssh/id_rsa 2>&1); rc=$?
+printf '%s\n' "$out" | grep -E '^holes|^overreach'
+holes=$(printf '%s\n' "$out" | sed -n 's/^holes *: *\([0-9]*\).*/\1/p')
+over=$(printf '%s\n' "$out" | sed -n 's/^overreach *: *\([0-9]*\).*/\1/p')
+check "narrow guard reports at least one hole" "yes" "$([ "${holes:-0}" -ge 1 ] && echo yes || echo no)"
+check "narrow guard reports no overreach"      "0"   "${over:-x}"
+check "narrow guard exits non-zero"            "yes" "$([ "$rc" -ne 0 ] && echo yes || echo no)"
+
+echo "=== control 2: the widened guard must come back clean ==="
+out=$(bash "$HERE/boundary.sh" "$T/wide.sh" Read file_path /home/me/.ssh/id_rsa 2>&1); rc=$?
+printf '%s\n' "$out" | grep -E '^holes|^overreach'
+holes=$(printf '%s\n' "$out" | sed -n 's/^holes *: *\([0-9]*\).*/\1/p')
+over=$(printf '%s\n' "$out" | sed -n 's/^overreach *: *\([0-9]*\).*/\1/p')
+check "widened guard reports no holes"     "0"   "${holes:-x}"
+check "widened guard reports no overreach" "0"   "${over:-x}"
+check "widened guard exits zero"           "0"   "$rc"
+
+echo "=== control 3: a guard that refuses everything must be reported as overreach ==="
+out=$(bash "$HERE/boundary.sh" "$T/paranoid.sh" Read file_path /home/me/.ssh/id_rsa 2>&1)
+over=$(printf '%s\n' "$out" | sed -n 's/^overreach *: *\([0-9]*\).*/\1/p')
+holes=$(printf '%s\n' "$out" | sed -n 's/^holes *: *\([0-9]*\).*/\1/p')
+check "refuse-everything guard reports overreach" "yes" "$([ "${over:-0}" -ge 1 ] && echo yes || echo no)"
+check "refuse-everything guard reports no holes"  "0"   "${holes:-x}"
+
+echo "=== control 4: the target itself is fired, not just its neighbours ==="
+out=$(bash "$HERE/boundary.sh" "$T/wide.sh" Read file_path /home/me/.ssh/id_rsa 2>&1)
+check "the thing itself appears as a row" "yes" \
+  "$(printf '%s\n' "$out" | grep -qE 'the thing itself .*refused' && echo yes || echo no)"
+
+echo
+echo "=========================="
+echo "Results: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/audit/boundary.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+# boundary.sh — take one thing your hook is meant to refuse, and fire the hook
+# at the neighbours of that thing.
+#
+# Why this exists: fire.sh answers "does the guard refuse this exact operation".
+# That is necessary and it is not enough. Every path-matching guard draws a
+# border, and the holes are never in the middle of the protected area - they
+# are just outside the border, on names nobody thought to type. A guard that
+# refuses ~/.ssh/id_rsa and allows ~/.ssh/id_rsa.bak is not protecting the key,
+# because the backup of a key is the key.
+#
+# The second half matters as much as the first. A guard that refuses everything
+# is not safe, it is unusable, and you only find out you have built one by
+# firing it at things it must let through. So this prints both directions.
+#
+# Usage:
+#   ./boundary.sh <hook-script> <tool-name> <field> <value> [--bare]
+#
+# Examples:
+#   ./boundary.sh ~/.claude/hooks/key-guard.sh Read file_path /home/me/.ssh/id_rsa
+#   ./boundary.sh ~/.claude/hooks/env-guard.sh Read file_path /home/me/app/.env
+#
+# What it prints, per neighbour:
+#   refused / allowed / hook error, and a note where the answer is not a matter
+#   of taste. It deliberately does NOT score you pass/fail on the ambiguous
+#   rows: whether /tmp/id_rsa should be refused is your policy, not ours.
+#
+# Every run uses a throwaway HOME, and no file is ever read - the hook is judged
+# on the tool-call arguments alone, which is all a PreToolUse hook ever sees.
+# That means the paths below do not need to exist, and no real key is touched.
+set -u
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+BARE=""
+ARGS=()
+for a in "$@"; do
+  if [ "$a" = "--bare" ]; then BARE="--bare"; else ARGS+=("$a"); fi
+done
+set -- "${ARGS[@]+"${ARGS[@]}"}"
+
+if [ $# -lt 4 ]; then
+  sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'
+  exit 64
+fi
+
+HOOK="$1"; TOOL="$2"; FIELD="$3"; VALUE="$4"
+[ -f "$HOOK" ] || { echo "boundary.sh: no such hook: $HOOK" >&2; exit 64; }
+
+dir=$(dirname "$VALUE")
+base=$(basename "$VALUE")
+stem="${base%.*}"
+ext=""
+case "$base" in *.*) ext=".${base##*.}" ;; esac
+
+# Neighbours are grouped by what the answer means, not by how they are spelled.
+#   must   - refusing this is the whole point; allowing it is a hole
+#   should - a copy of a secret is a secret; allowing it is almost always a hole
+#   allow  - refusing this makes the guard unusable
+#   policy - reasonable people differ; printed for your eyes, not scored
+CASES=()
+add() { CASES+=("$1|$2|$3"); }
+
+add must   "the thing itself"                 "$VALUE"
+add should "backup, dot suffix"               "${VALUE}.bak"
+add should "backup, word suffix"              "${VALUE}_old"
+add should "backup, editor style"             "${VALUE}~"
+add should "backup, two suffixes"             "${VALUE}.old.2"
+add should "same name, uppercased"            "${dir}/$(printf '%s' "$base" | tr '[:lower:]' '[:upper:]')"
+add should "same file, redundant dot segment" "${dir}/./${base}"
+add should "same file, trailing space"        "${VALUE} "
+add policy "same name, another directory"     "/tmp/${base}"
+add policy "the directory itself"             "${dir}/"
+add policy "relative path"                    "$(printf '%s' "$VALUE" | sed 's#^/[^/]*/[^/]*/##')"
+# .pub is checked whether or not the target has an extension: for key files it
+# is the single most common false positive, and id_rsa has no extension at all.
+if [ -n "$ext" ]; then
+  add allow "public half, .pub"               "${dir}/${stem}.pub"
+else
+  add allow "public half, .pub"               "${VALUE}.pub"
+fi
+add allow  "prose that names it"              "${dir}/${stem}.md"
+add allow  "source file that names it"        "${dir}/${stem}_generator.py"
+add allow  "an ordinary project file"         "${dir}/README.md"
+
+printf 'hook  : %s\n' "$HOOK"
+printf 'tool  : %s   field: %s\n' "$TOOL" "$FIELD"
+printf 'target: %s\n' "$VALUE"
+[ -n "$BARE" ] && printf 'mode  : --bare (no jq, no python3, no node)\n'
+printf '\n%-6s  %-30s  %-8s  %s\n' "GROUP" "NEIGHBOUR" "RESULT" "VALUE"
+printf -- '------  ------------------------------  --------  -----\n'
+
+holes=0; overreach=0; errors=0
+for c in "${CASES[@]}"; do
+  group="${c%%|*}"; rest="${c#*|}"
+  label="${rest%%|*}"; val="${rest#*|}"
+  ${BARE:+:} true   # keep shellcheck quiet about the optional flag
+  out=$(bash "$HERE/fire.sh" ${BARE:+--bare} "$HOOK" "$TOOL" "$FIELD=$val" 2>&1)
+  code=$?
+  case "$code" in
+    2) result="refused" ;;
+    0) result="allowed" ;;
+    *) result="ERROR($code)"; errors=$((errors + 1)) ;;
+  esac
+  case "$group:$result" in
+    must:allowed|should:allowed)   result="$result  <- hole"; holes=$((holes + 1)) ;;
+    allow:refused)                 result="$result  <- over"; overreach=$((overreach + 1)) ;;
+  esac
+  printf '%-6s  %-30s  %-8s  %s\n' "$group" "$label" "$result" "$val"
+done
+
+printf '\n'
+printf 'holes     : %d   (must/should rows the hook let through)\n' "$holes"
+printf 'overreach : %d   (allow rows the hook refused)\n' "$overreach"
+[ "$errors" -gt 0 ] && printf 'errors    : %d   (the hook itself failed; it is not protecting you either)\n' "$errors"
+printf '\n'
+printf 'The "policy" rows are not counted either way. Whether a key outside\n'
+printf '~/.ssh, or the directory itself, should be refused is your decision.\n'
+if [ "$holes" -eq 0 ] && [ "$overreach" -eq 0 ]; then
+  printf '\nNothing to fix on these neighbours. That is worth knowing, and it is\n'
+  printf 'not proof the guard is complete - it is proof it survives these rows.\n'
+fi
+[ "$holes" -gt 0 ] && exit 1
+exit 0

package/audit/count-hooks.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""count-hooks.py — how many hook groups are actually registered, per scope.
+
+Why this exists: the usual advice is to run `claude --print-settings`. That flag
+does not exist (checked on 2026-08-27 against 2.1.246); it exits 1 with a
+one-line "error: unknown option". The settings that matter live in up to three
+files, and Claude Code merges them. Counting only one under-reports. The settings that matter live in up to three files, and
+Claude Code merges them. Counting only one of them under-reports.
+
+Run it from your project directory.
+"""
+import collections
+import json
+import os
+
+SCOPES = [
+    ("user   ", os.path.expanduser("~/.claude/settings.json")),
+    ("project", os.path.join(os.getcwd(), ".claude", "settings.json")),
+    ("local  ", os.path.join(os.getcwd(), ".claude", "settings.local.json")),
+]
+
+total = collections.Counter()
+for label, path in SCOPES:
+    if not os.path.exists(path):
+        print(f"  {label}  (no file)          {path}")
+        continue
+    try:
+        data = json.load(open(path, encoding="utf-8"))
+    except Exception as exc:                      # a malformed file is a finding, not a crash
+        print(f"  {label}  UNREADABLE: {exc}   {path}")
+        continue
+    hooks = data.get("hooks") or {}
+    counts = {event: len(groups) for event, groups in hooks.items()}
+    total.update(counts)
+    print(f"  {label}  {counts if counts else 'no hooks'}")
+
+print()
+print("  merged :", dict(total))
+print("  total  :", sum(total.values()), "hook groups")
+print()
+print("  A count above zero means they are registered.")
+print("  It does not mean any of them fires. Use fire.sh for that.")