cc-safe-setup 29.8.0 → 30.0.5

package/SAFETY_CHECKLIST.md

@@ -4,8 +4,8 @@ Use this checklist before running Claude Code autonomously. Copy to your project
 
 ## Before First Session
 
-- [ ] Install safety hooks: `npx cc-safe-setup`
-- [ ] Run safety audit: `npx cc-safe-setup --audit` (target: score ≥ 80)
+- [ ] Install safety hooks: `npx github:yurukusa/cc-safe-setup`
+- [ ] Run safety audit: `npx github:yurukusa/cc-safe-setup --audit` (target: score ≥ 80)
 - [ ] Create CLAUDE.md with project-specific rules
 - [ ] Verify .env files are in .gitignore
 - [ ] Ensure git remote is set (so work can be recovered)
@@ -14,7 +14,7 @@ Use this checklist before running Claude Code autonomously. Copy to your project
 
 - [ ] Create backup branch: `git checkout -b backup/before-autonomous-$(date +%Y%m%d)`
 - [ ] Commit all current work
-- [ ] Verify destructive-guard is blocking: `npx cc-safe-setup --verify`
+- [ ] Verify destructive-guard is blocking: `npx github:yurukusa/cc-safe-setup --verify`
 - [ ] Check branch-guard protects main/master
 - [ ] If using database: install `block-database-wipe`
 - [ ] If sensitive configs: install `protect-dotfiles`
@@ -30,7 +30,7 @@ Use this checklist before running Claude Code autonomously. Copy to your project
 - [ ] Review git log for unexpected changes
 - [ ] Run test suite to catch regressions
 - [ ] Check if any .env files were modified
-- [ ] Review blocked-commands.log for patterns: `npx cc-safe-setup --learn`
+- [ ] Review blocked-commands.log for patterns: `npx github:yurukusa/cc-safe-setup --learn`
 
 ## Team Setup
 
@@ -43,11 +43,19 @@ Use this checklist before running Claude Code autonomously. Copy to your project
 
 | Risk | Prevention | Install |
 |------|-----------|---------|
-| `rm -rf /` | destructive-guard | `npx cc-safe-setup` |
-| Push to main | branch-guard | `npx cc-safe-setup` |
-| .env committed | secret-guard | `npx cc-safe-setup` |
+| `rm -rf /` | destructive-guard | `npx github:yurukusa/cc-safe-setup` |
+| Push to main | branch-guard | `npx github:yurukusa/cc-safe-setup` |
+| .env committed | secret-guard | `npx github:yurukusa/cc-safe-setup` |
+| .env written or copied via Bash | secret-file-write-guard | `--install-example secret-file-write-guard` |
 | Database wiped | block-database-wipe | `--install-example block-database-wipe` |
 | Dotfiles modified | protect-dotfiles | `--install-example protect-dotfiles` |
 | Deploy without commit | deploy-guard | `--install-example deploy-guard` |
 | Commit without tests | verify-before-commit | `--install-example verify-before-commit` |
 | Session crash data loss | session-checkpoint | `--install-example session-checkpoint` |
+
+## Why `github:` and not the bare package name
+
+The npm entry is frozen at 29.8.0 (2026-04-20) and lets twenty-five command shapes through that the
+current code blocks — measured 2026-09-03 across twenty-two shapes, with nothing failing in
+the other direction. The table is in the README. Install from GitHub so the guards you get are
+the guards this checklist describes. The tool's own `--help` says the same thing.

package/SERVICES.md

@@ -0,0 +1,194 @@
+# Services
+
+If you want more than what the free tools give you, there are four paid options. All are fulfilled using the same methodology I use to run Claude Code autonomously, applied to your specific setup.
+
+This page is in English, but Japanese orders are welcome for all four: order and write your request in Japanese and the report comes back in Japanese. 日本語でも受け付けます（注文と依頼を日本語で書いていただければ、報告書は日本語でお返しします）。
+
+## Which one is for you
+
+Pick by what your setup actually looks like, not by what sounds most thorough. The most expensive one is the wrong choice for most people, and its own section says so.
+
+| What your setup looks like right now | Start here |
+|---|---|
+| You have not run the free audit yet | Run `--audit` from this repo first. It is free, it takes seconds, and it may answer your question. Come back only if it did not. |
+| One `CLAUDE.md`, no hooks of your own, no CI | **§1 CLAUDE.md Audit — $29.** One file, read closely. |
+| Your bill or your rate limit is the problem | **§2 Token Burn Audit — $29.** Reads your session logs, not your rules. |
+| `CLAUDE.md` in more than one layer, **and** hooks you wrote yourself, **and** CI | **§3 Full-Surface Audit — $219.** The only one that reads layers *against each other*. |
+| Only one layer — no hooks, no CI | **Not §3.** A contradiction between layers cannot exist when there is only one layer. §1 is the right size. |
+| You want to keep up with new failure patterns rather than audit anything | **§4 CC Safety Lab — ¥500/month.** |
+
+**日本語の説明ページ:** [CLAUDE.md 監査（¥3,980）](https://yurukusa.github.io/cc-safe-setup/claude-md-audit-jp.html)／[Token Burn 監査（¥3,980）](https://yurukusa.github.io/cc-safe-setup/token-burn-audit-jp.html)／[Full-Surface 監査（¥29,800）](https://yurukusa.github.io/cc-safe-setup/full-surface-audit-jp.html)。価格・納期・返金の条件・含まないもの・送っていただくものを日本語で書いてあります。
+
+---
+
+## 1. CLAUDE.md Audit — $29 (¥3,980)
+
+**What you get:**
+
+A written audit of your `CLAUDE.md` (and optionally `settings.json` + your 5 most-invoked hooks), delivered as a Markdown report within 48 hours.
+
+**See exactly what you get: [a full sample report](./docs/claude-md-audit-sample.md).** It is this audit run against my own 608-line, three-layer setup — real findings, including two rules that could not be followed at all. Also available in Japanese: **[見本の報告書（日本語）](./docs/claude-md-audit-sample-jp.md)** — same content, same figures. 日本語の説明ページは **[CLAUDE.md の監査（¥3,980・48時間）](https://yurukusa.github.io/cc-safe-setup/claude-md-audit-jp.html)** にあります。
+
+The report covers:
+
+1. **Reference resolution** — every path your rules depend on, checked against the scope the rule actually runs in. The failure this catches is not a missing file: it is a file that *exists somewhere else*, so it passes existence checks while the rule stays silently unfollowable.
+2. **Testable-assertion ratio** — how much of your CLAUDE.md is aspirational (and therefore silently drops out under pressure) vs. checkable, as a measured ratio per layer.
+3. **Cross-layer redundancy** — rules duplicated between your global, home and project files. This is an ownership problem, not a cost problem: editing one copy leaves the other in force and neither file says so.
+4. **Vague-rule detection** — the specific lines the model is most likely to ignore, with concrete rewrites that attach a checkable condition without changing your intent.
+5. **Top-3 fixes**, ranked by expected impact, with before/after diffs ready to paste.
+
+**On token weight:** earlier versions of this page led with "how much your instructions cost per turn." Having measured it, I think that was the wrong headline. `CLAUDE.md` sits in the cached prefix, so on my own setup, deleting *every* duplicated rule works out to roughly $0.24–$1.19/month. The report still includes the token arithmetic for your files — as a bound, and usually as a reason **not** to spend your time there. If your bill is the problem, the Token Burn Audit below reads session logs, which is where the money actually goes.
+
+**Not included:** a live 1:1 call, hook implementation, or code review beyond the files you submit. This is an audit, not consulting. The diffs are proposals; you apply them.
+
+**How to book:**
+
+1. Order at https://ko-fi.com/yurukusa/commissions — listing: *CLAUDE.md Audit — written report within 48h*, ¥3,980 (≈$29). _If that listing is ever missing, a ¥3,980 tip at https://ko-fi.com/yurukusa with the note "CLAUDE.md audit" is honored at the same price._
+2. Open an Audit Request issue on this repo using [the template](./.github/ISSUE_TEMPLATE/3-audit_request.md). Paste your CLAUDE.md there, or — if you would rather not publish it — say so in the issue and I reply with a private route. Mention your Ko-fi order so the two can be matched.
+3. You receive the report as an issue reply, and the issue is closed when you confirm it.
+
+If you cannot post anything publicly at all, say so in the Ko-fi order message instead and I'll arrange another route without an issue.
+
+**Attaching a file to an issue does not make it private.** This repository is public, and attachment URLs on a public repository can be opened by anyone who has the link. If your `CLAUDE.md` should not be public, do not attach it — ask for the private route instead. (This page said the opposite until 2026-08-12; it was wrong.)
+
+**A `CLAUDE.md` is not always harmless.** Mine names internal paths; other people's name customers, hostnames and occasionally a key. Strip anything you would not put on a public page before you post it — the issue is public. And as above: the report is written with Claude Code, so your file's contents go to Anthropic's API; on my side it is never published and is deleted within 30 days of delivery.
+
+**Refund:** if I cannot produce a useful audit (for example because the file is effectively empty, or is entirely in a language I cannot parse), full refund via Ko-fi.
+
+---
+
+## 2. Token Burn Audit — $29 (¥3,980)
+
+**What it is:** a diagnosis of where your Claude Code tokens are actually going, based on *your* `/cost` output and session transcripts. Not a generic "7 tips" article — a specific read of your real usage.
+
+**Why this still matters — counted 2026-08-13, not in April:**
+
+> *"I used up Max 5 in 1 hour of working, before I could work 8 hours"* — user report via [DevOps.com, April 2026](https://devops.com/claude-code-quota-limits-usage-problems/)
+
+The reports did not stop when that quote was written. Both of these are still open:
+
+| Issue | Reactions | Comments | State |
+|---|---|---|---|
+| [#16157](https://github.com/anthropics/claude-code/issues/16157) — hitting usage limits immediately on Max | 724 | 1,486 | open |
+| [#38335](https://github.com/anthropics/claude-code/issues/38335) — Max session limits draining in as little as 19 minutes | 543 | 831 | open |
+
+I counted the same way across the issues about hooks and settings silently not applying — which is the subject of the more expensive audit in §3. That cluster comes to **371** reactions and comments in total. This one comes to **9,643**.
+
+That is not a claim that this audit fixes the platform's limits. It is why the cheaper audit sits on this subject: it is where people are actually stuck.
+
+Context from April 2026, kept because the causes have not changed:
+
+- March 23, 2026 is where this cluster starts ([#38335](https://github.com/anthropics/claude-code/issues/38335), [#41788](https://github.com/anthropics/claude-code/issues/41788))
+- Anthropic confirmed investigation: "top priority for the team"
+- Root cause partially identified: `cache_read` tokens may count at full rate against rate limits (negating caching benefits)
+- April 21 pricing whiplash: Claude Code removed from $20 Pro plan, reverted hours later
+
+This audit tells you which of the 56 cataloged token-waste symptoms (Token Book Ch.8) are actually firing in *your* logs — not "in general."
+
+**See exactly what you get: [a full sample report](./docs/token-burn-audit-sample.md).** It is this audit run against my own 156 session logs (21,770 API round-trips), including the part where the largest waste pattern turned out to match *none* of the 56 symptoms, and the part where my own hooks were failing to catch it.
+
+**What you get (delivered in 48 hours as a Markdown report in your issue thread):**
+
+1. **Top 3 waste patterns** found in your logs, ranked by estimated cost. Each mapped to a Ch.8 symptom where one applies — and flagged explicitly when none does. In the sample, the single largest pattern matched *none* of the 56.
+2. **Per-pattern fix**: the exact hook, CLAUDE.md change, or workflow adjustment that addresses it. Example hooks from `cc-safe-setup/examples/` that you can install in one command.
+3. **Estimated savings range** (stated as a range, not a single number — the actual savings depend on your next month's usage pattern).
+4. **`cc-token-diet` walkthrough**: if you haven't run [cc-token-diet](https://github.com/yurukusa/cc-token-diet) yet, I include the command line and help interpret the output.
+
+**Not included:** real-time monitoring, implementation (you apply the fixes yourself), or a guarantee that your $ spend will drop by a specific amount. If the report does not identify at least one addressable waste pattern, full refund via Ko-fi.
+
+**How to book:**
+
+1. Order at https://ko-fi.com/yurukusa/commissions — listing: *Token Burn Audit — written report within 48h*, ¥3,980 (≈$29). _If that listing is ever missing, a ¥3,980 tip at https://ko-fi.com/yurukusa with the note "Token Burn audit" is honored at the same price._
+2. Open a Token Burn Audit Request issue on this repo using [the template](./.github/ISSUE_TEMPLATE/4-token_burn_audit_request.md) — and post **only** the `/cost` summary and a couple of lines about your setup there. **Do not paste raw session transcripts into the issue.** Issues on this repository are public and stay public. Say in the issue that the logs are coming separately; I reply with a private route (the Ko-fi order message thread, or an address you name) and you send them there.
+3. You receive the report as an issue reply, and the issue is closed when you confirm it.
+
+**Strip your logs before you send them.** Session transcripts routinely carry API keys, customer names, internal paths and source code. Remove those first. I cannot un-see what arrives, and a public issue cannot be un-published — if a secret does reach me, tell me and rotate it, because deleting the message does not undo the exposure.
+
+**What happens to the files you send.** The report is written with Claude Code, which means **the contents of your files are sent to Anthropic's API**. Doing the work this way makes that unavoidable, and what happens on their side is governed by [their terms](https://www.anthropic.com/legal/commercial-terms), not by me — I cannot promise anything about it. What I can promise is three things: I publish nothing, I delete your files within 30 days of delivery (sooner if you ask), and the only thing I keep is the report I wrote. Redact anything you would rather not send; I note the redacted range in the report. If your environment cannot send anything to an external API, this audit is the wrong tool and you should not buy it.
+
+**What the free tools already give you — run them first:** `/cost` (or `/usage`) inside Claude Code shows the current session. [`ccusage`](https://github.com/ccusage/ccusage) gives you daily and monthly totals from the same local logs, and it folds duplicate `usage` rows correctly (keyed on `message.id` + `requestId`) — a detail my own `cc-token-diet` got wrong until 2026-08-09. If your question is *"how much?"*, those answer it for free and you do not need me.
+
+What none of them answer is *"which of my habits is producing that number, and what do I change on Monday."* Counting is solved; attribution is not. That gap is what this audit is for.
+
+**Good fit:** Max plan users watching their quota vanish faster than it used to. Teams where one session burned an unexpected $50–$500. Anyone who read a "7 tips" article and tried them but nothing changed.
+
+**Not a good fit:** if you have not yet run Claude Code for at least one week on your actual project. There has to be real usage to audit.
+
+**Japanese is welcome / 日本語でも受け付けます:** there is a full Japanese description of this audit — price, turnaround, refund terms, what is not included, and what you send me — at **[トークンが何に消えたかを、あなたのログから読む監査（¥3,980・48時間）](https://yurukusa.github.io/cc-safe-setup/token-burn-audit-jp.html)**. The sample report is also available in Japanese: **[見本の報告書（日本語）](./docs/token-burn-audit-sample-jp.md)** — same content, same figures, same measurement date as the English one. You can place the Ko-fi order and file the request issue in Japanese, and the report comes back in Japanese. この監査の日本語の説明（価格・納期・返金の条件・含まないもの・送っていただくもの）は上のページにあります。見本の報告書も日本語版を用意しました（中身・数字・測定日は英語版と同じ）。注文と issue を日本語で書いていただければ、報告書は日本語でお返しします。
+
+---
+
+## 3. Full-Surface Audit — $219 (¥29,800)
+
+**What it is:** the two audits above each read one kind of file. This one crosses five layers of your setup — `CLAUDE.md`, `settings.json`, your hooks, your session logs, and your CI config — and reports only the contradictions that fall *between* them.
+
+**Why a separate offering rather than a bigger version of the ones above:** because the failures it finds are not larger versions of single-file failures. They are a different kind. A rule that names a safety net which exists but is never registered passes every check you can run on the rule, and every check you can run on the config. It only shows up when the two are read against each other.
+
+**See exactly what you get: [a full sample report](./docs/full-surface-audit-sample-jp.md).** It is this audit run against my own setup — three layers of `CLAUDE.md`, 27 registered hooks, 649 session log files holding 34,026 shell calls, and three CI workflows. On the day I wrote it, it found five things I did not know, and the largest was about this project:
+
+> The guards protecting my machine were a different program from the ones I ship under the same names. Six dangerous command shapes that the shipped version blocks were passing on my own machine. And `--outdated`, the command in this repo whose only job is to notice exactly that drift, was structurally unable to see those files — the core guards live in `scripts.json`, and it compared against `examples/`. I fixed that the same day; the fix is in this repo.
+
+The report also measured how much it mattered, against my own logs rather than in principle. Of 515 recorded calls containing `git push`, **502 (97.5%)** sat outside the position the installed guard was reading — and reading those 502 line by line turned up **two real force-pushes that ran and were never stopped**, on a guard whose own header says it blocks force-push on *all* branches.
+
+It also records the two times my own scan was wrong about that number, in both directions, and how I found out.
+
+**What you get, as a Markdown report within 72 hours:**
+
+1. **Cross-layer contradictions.** Each one names the layers it spans and why a single-file audit cannot surface it.
+2. **A control for every finding** — the same probe on a case that should *not* trigger. Without that, "everything passed" and "my probe was wrong" look identical. The sample includes the three cases where my own scan was wrong and I threw the finding out.
+3. **Coverage measured against your own logs.** Not "this rule looks weak" but "this rule sits outside N% of the commands you actually ran."
+4. **Diffs you can paste**, and the 30-second command that shows each one working.
+5. **What the audit did not find**, and what it could not measure.
+
+**Not included:** a call, implementation, or running anything in your environment. I read what you send and write the report. The diffs are proposals; you apply them. If you want a senior human engineer manually reviewing your repo, this is not that.
+
+**How to book:**
+
+1. Order at https://ko-fi.com/yurukusa/commissions — listing: *Full-Surface Audit — all 5 layers, written report within 72h*, ¥29,800 (≈$219).
+2. Reply to the order with a message saying which of the five layers you can send. **You do not need all five; three is enough to start.** I reply within 24 hours with a private route for the files.
+3. **Do not post logs or settings publicly.** Session transcripts routinely carry API keys, customer names, internal paths and source code. Strip what you can before you send them. I cannot un-see what arrives.
+
+**What happens to the files you send.** The report is written with Claude Code, which means **the contents of your files are sent to Anthropic's API**. Doing the work this way makes that unavoidable, and what happens on their side is governed by [their terms](https://www.anthropic.com/legal/commercial-terms), not by me — I cannot promise anything about it. What I can promise is three things: I publish nothing, I delete your files within 30 days of delivery (sooner if you ask), and the only thing I keep is the report I wrote. Redact anything you would rather not send; I note the redacted range in the report. If your environment cannot send anything to an external API, this audit is the wrong tool and you should not buy it.
+
+**Refund:** if the audit surfaces no cross-layer contradiction at all, full refund via Ko-fi.
+
+**Japanese is welcome / 日本語でも受け付けます:** there is a full Japanese description of this audit — price, turnaround, refund terms, what is not included, and what you send me — at **[層と層のあいだにしか現れない矛盾を読む監査（¥29,800・72時間）](https://yurukusa.github.io/cc-safe-setup/full-surface-audit-jp.html)**. The sample report linked above is already the Japanese one. 注文と依頼を日本語で書いていただければ、報告書は日本語でお返しします。この監査の日本語の説明（価格・納期・返金の条件・含まないもの・送っていただくもの）は上のページにあります。
+
+---
+
+## 4. CC Safety Lab — Founder Membership, ¥500/month
+
+Monthly recurring. Each issue covers:
+
+- 3–5 new incident reports from the prior month, each with a concrete workaround.
+- 1 new safety hook, released to Founder members one month before it ships to `cc-safe-setup` main.
+- 1 measured token-saving technique, with the data behind it.
+- 1 week of early access to Token Book updates.
+
+**The delivery record, since I would rather you saw it than found it.** This page used to say
+"delivered on the 1st of each month." It has never worked out that way, so the claim is gone.
+Issues went out on 2026-04-23, 04-24, 05-08, 05-15, 05-22 — and then **nothing until 08-08**.
+June and July have no issue at all; I found the August one sitting unpublished as a draft and
+shipped it late. No issue has ever gone out on the 1st.
+
+What I will commit to instead: **one issue per calendar month, no fixed date.** If a month is
+missed, the next issue says so at the top rather than quietly skipping it. If that is not good
+enough for ¥500/month — and it may well not be — do not join yet.
+
+Founder rate is grandfathered — you keep the ¥500 price even if the tier is later raised.
+
+**Join:** https://ko-fi.com/yurukusa → *Membership* tab.
+
+---
+
+## Why these prices
+
+Comparable AI-audit consulting, in the listings I have seen, runs $150–$300/hour and $999+ per productized report. These are deliberately priced below that because they are AI-assisted: I apply the same 7-check framework documented in the [free self-audit Gist](https://gist.github.com/yurukusa/df29f506af33368b03b1c5aeae85f04c), plus judgment from having read hundreds of public Claude Code incident reports. If you want a senior human engineer manually reviewing your repo, this is not that. Read the sample and decide.
+
+**On the gap between $29 and $219:** it is not a bigger version of the same work. The $29 audits read one kind of file each, and a single-file audit cannot produce a contradiction that lives *between* files — the gap is in what the work can find, not in how much of it there is. The sample report for each tier shows the difference; read both before deciding which one you want. If the $29 audits answer your question, buy those.
+
+---
+
+## Questions before booking
+
+Open a [General Discussion](https://github.com/yurukusa/cc-safe-setup/discussions/categories/general) or message on Ko-fi.

package/SETTINGS_REFERENCE.md

@@ -10,6 +10,39 @@ Everything you can put in `~/.claude/settings.json`, documented from real usage
 | `.claude/settings.json` | Current project | Overrides user |
 | `.claude/settings.local.json` | Current project (gitignored) | Highest |
 
+> **Project-scoped files resolve against the launch directory, not the git root — and the two do not behave the same.**
+> Launching Claude Code from a subdirectory of a repo (e.g. `packages/api/` in a monorepo) silently drops
+> `.claude/settings.json` from the repo root, while `.claude/settings.local.json` from that same root still applies.
+> Measured on 2.1.220 (Linux/WSL2) with hooks registered only at the repo root, launching from a nested subdirectory,
+> with a root launch as the control on every run:
+>
+> | At repo root | Launched from subdirectory | Launched from root (control) |
+> |---|---|---|
+> | `settings.json` only | hook does **not** fire | fires |
+> | `settings.local.json` only | hook fires | fires |
+> | both present | **only** the `.local` hook fires | both fire |
+>
+> The direction matters for safety: `settings.local.json` is the personal, gitignored file, so the copy that survives
+> is the one only you have, and the copy that disappears is the committed one your whole team relies on. A `PreToolUse`
+> guard shipped in `settings.json`, verified from the repo root, can be inert for every developer who runs Claude from
+> a package subdirectory — with nothing in the output saying so.
+>
+> **Until this is fixed upstream** ([#74023](https://github.com/anthropics/claude-code/issues/74023)), launch from the
+> repo root so the shared config loads:
+>
+> ```sh
+> # ccroot: launch from the repo root so project config loads
+> root="$(git rev-parse --show-toplevel 2>/dev/null)" && cd "$root"; exec claude "$@"
+> ```
+>
+> Copying `settings.json` to `settings.local.json` also makes the hooks fire from a subdirectory, but that file is not
+> the one you commit, so it is a diagnostic rather than a team fix: if your hooks start working after that copy, you
+> have confirmed you are hitting this bug and not a malformed config.
+>
+> This installer writes to `$CLAUDE_PROJECT_DIR/.claude/settings.json` when `CLAUDE_PROJECT_DIR` is set, and to
+> `~/.claude/settings.json` otherwise. The default (user-level) path is unaffected by this bug; the
+> `CLAUDE_PROJECT_DIR` path is affected.
+
 ## Permissions
 
 ### allow
@@ -47,7 +80,7 @@ Commands that auto-execute without prompting.
 - Compound commands don't match: `Bash(git:*)` won't match `cd /path && git log` ([#30519](https://github.com/anthropics/claude-code/issues/30519), [#16561](https://github.com/anthropics/claude-code/issues/16561))
 - "Always Allow" saves exact strings, not patterns ([#6850](https://github.com/anthropics/claude-code/issues/6850))
 - User-level settings may not apply at project level ([#5140](https://github.com/anthropics/claude-code/issues/5140))
-- **Workaround:** Use `compound-command-approver` hook: `npx cc-safe-setup --install-example compound-command-approver`
+- **Workaround:** Use `compound-command-approver` hook: `npx github:yurukusa/cc-safe-setup --install-example compound-command-approver`
 
 ### deny
 
@@ -91,16 +124,86 @@ Commands that are always blocked.
 
 ### Hook Events
 
-| Event | When | Use Case |
-|-------|------|----------|
-| `PreToolUse` | Before tool executes | Block/modify commands |
-| `PostToolUse` | After tool executes | Validate output, check syntax |
-| `Stop` | Session ends | Log data, notify |
-| `UserPromptSubmit` | User presses Enter | Validate prompts |
-| `Notification` | Claude shows notification | Custom alerts |
-| `PreCompact` | Before context compaction | Save state |
-| `SessionStart` | Session begins | Initialize |
-| `SessionEnd` | Session ends | Cleanup |
+There are **31** hook events. This table used to list 8 of them, and described `Stop` as
+"Session ends" — which is wrong, and wrong in a direction that costs you: `Stop` fires
+**after every turn**, not once at the end. A cleanup or notification hook registered there
+runs dozens of times per session.
+
+**A wrong event name is not an error.** Claude Code drops the hook and says
+`Unknown hook event "..." was ignored` — but only where you have to go looking for it.
+Check yours:
+
+```bash
+claude doctor    # any "Unknown hook event" line means that hook never runs
+```
+
+The same output prints the authoritative list of valid names, which is where the table below
+comes from. Descriptions are quoted from the official hooks reference.
+
+**Session lifecycle**
+
+| Event | When it fires | Use case |
+|-------|---------------|----------|
+| `SessionStart` | "Claude Code starts a new session or resumes an existing session" | Initialize, restore state |
+| `Setup` | Start with `--init-only`, or `--init`/`--maintenance` in `-p` mode | One-time prep in CI |
+| `SessionEnd` | "When a session terminates" | Cleanup, final report |
+
+**Prompt and turn**
+
+| Event | When it fires | Use case |
+|-------|---------------|----------|
+| `UserPromptSubmit` | "When you submit a prompt, before Claude processes it" | Validate or annotate prompts |
+| `UserPromptExpansion` | "When a user-typed command expands into a prompt" | Gate your own slash commands |
+| `Stop` | **"When Claude finishes responding"** — every turn, not once | Per-turn checks, commitments |
+| `StopFailure` | "When the turn ends due to an API error" | Catch `rate_limit`, `billing_error`, `overloaded` |
+| `MessageDisplay` | "While assistant message text is displayed" | Redact or annotate on screen only |
+
+**Tools and permissions**
+
+| Event | When it fires | Use case |
+|-------|---------------|----------|
+| `PreToolUse` | "Before a tool call executes. Can block it" | **Where guards belong.** Fires in every permission mode |
+| `PermissionRequest` | "When a tool call needs a permission decision" | Custom approval logic — **does not fire under auto mode or bypassed permissions** |
+| `PermissionDenied` | "When a tool call is denied by the auto mode classifier" | Audit what is actually being blocked |
+| `PostToolUse` | "After a tool call succeeds" | Validate output, syntax-check writes |
+| `PostToolUseFailure` | "After a tool call fails" | Feed the failure reason back to Claude |
+| `PostToolBatch` | "After a full batch of parallel tool calls resolves" | Check a whole batch before the next model call |
+
+**Subagents and tasks**
+
+| Event | When it fires | Use case |
+|-------|---------------|----------|
+| `SubagentStart` | "When a subagent is spawned" | Count and constrain fan-out |
+| `SubagentStop` | "When a subagent finishes" | Collect subagent results |
+| `TaskCreated` | "When a task is being created via `TaskCreate`" | Enforce task hygiene (exit 2 blocks) |
+| `TaskCompleted` | "When a task is being marked as completed" | Require evidence before "done" (exit 2 blocks) |
+| `TeammateIdle` | "When an agent team teammate is about to go idle" | Keep a teammate working (exit 2 blocks) |
+
+**Environment and config**
+
+| Event | When it fires | Use case |
+|-------|---------------|----------|
+| `ConfigChange` | "When a configuration file changes during a session" | **exit 2 blocks the change** (except `policy_settings`) |
+| `InstructionsLoaded` | "When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context" | Verify your instructions actually loaded |
+| `CwdChanged` | "When the working directory changes, for example when Claude executes a `cd` command" | Reactive environment management (direnv) |
+| `DirectoryAdded` | "When a working directory is added mid-session via `/add-dir`" | Audit scope expansion |
+| `FileChanged` | "When a watched file changes on disk" | React to edits; `matcher` selects filenames |
+| `WorktreeCreate` | "When a worktree is being created" | **Hook returns the path; non-zero aborts creation** |
+| `WorktreeRemove` | "When a worktree is being removed" | Salvage work before removal |
+
+**Context and MCP**
+
+| Event | When it fires | Use case |
+|-------|---------------|----------|
+| `PreCompact` | "Before context compaction" | Save state, or block compaction |
+| `PostCompact` | "After context compaction completes" | Re-inject what compaction dropped |
+| `Notification` | "When Claude Code sends a notification" | Custom alerts |
+| `Elicitation` | "When an MCP server requests user input during a tool call" | Auto-answer or refuse MCP prompts |
+| `ElicitationResult` | "After a user responds to an MCP elicitation" | Vet the response before it leaves |
+
+Not every event supports a `matcher`, and the decision control differs per event (some can
+block with exit code 2, some ignore the exit code entirely). Check the official reference
+before relying on one to *stop* something.
 
 ### Matcher Values
 
@@ -256,27 +359,143 @@ Commands that are always blocked.
 ### Generate This Automatically
 
 ```bash
-npx cc-safe-setup        # Install hooks
-npx cc-safe-setup --audit  # Check your score
-npx cc-safe-setup --doctor # Diagnose issues
+npx github:yurukusa/cc-safe-setup        # Install hooks
+npx github:yurukusa/cc-safe-setup --audit  # Check your score
+npx github:yurukusa/cc-safe-setup --doctor # Diagnose issues
+```
+
+## Undocumented settings (verified from the bundled binary)
+
+These `settings.json` keys are not in the official docs but are real and read at runtime. Defaults below were verified by inspecting the bundled `@anthropic-ai/claude-code` binary. Internal short names change between versions — rely on the **key name and default**, not on any internal symbol. Behaviour may change in future releases; re-verify before depending on them.
+
+| Key | Default | What it does | Why you might set it |
+|-----|---------|--------------|----------------------|
+| `switchModelsOnFlag` | `true` | When a safety classifier flags a message, the session auto-switches to a different (often larger/costlier) model to keep going. `false` makes the session **pause** instead. | Set `false` to keep your model and cost assumptions stable, and to notice flags instead of being silently moved to another model. |
+| `skillListingMaxDescChars` | `1536` | Per-skill `description` character cap in the skill listing sent to the model. Longer descriptions are **silently truncated** (from the end). | A skill that "won't auto-trigger" can be a truncated description. Put trigger words first, keep descriptions short, or raise this (costs more per-turn context). |
+| `skillListingBudgetFraction` | `0.01` (1%) | Fraction of the context window reserved for the whole skill listing. When the listing exceeds it, descriptions are shortened to fit. | Many skills ⇒ less room per skill ⇒ more truncation. Prune unused skills, or raise this (costs more per-turn context). |
+
+```json
+{
+  "switchModelsOnFlag": false,
+  "skillListingMaxDescChars": 4096,
+  "skillListingBudgetFraction": 0.03
+}
 ```
 
+Raising the two skill-listing caps opts you into higher per-turn context cost (the listing is sent every turn). Prefer trimming descriptions and pruning skills first.
+
+## Recently added settings (2.1.220 – 2.1.226)
+
+> **Source: the official changelog, not my own machine.** Every other entry in this file was written
+> from usage I ran here. These eleven were introduced in the last seven releases and are listed so the
+> file keeps its promise of covering everything you can put in `settings.json`. Descriptions follow the
+> changelog wording; I have not reproduced each one locally yet, and I say so rather than implying I have.
+>
+> Measured 2026-08-11 against Claude Code 2.1.226: all eleven were missing from this file.
+>
+> **Update, same day: I reproduced the first one — and it did not behave the way I had paraphrased it.**
+> See [What `crossSessionInbound` actually did on my machine](#what-crosssessioninbound-actually-did-on-my-machine)
+> below. That is the reason the remaining ten still carry the caveat above instead of being quietly
+> promoted to "verified".
+
+| Setting | Since | What the changelog says |
+|---|---|---|
+| `crossSessionInbound` | 2.1.224 | Changelog wording: messages sent to a session **running with bypassed permissions are held for your approval**; messages to other sessions auto-deliver. ⚠️ **I could not reproduce the "held" half — [see below](#what-crosssessioninbound-actually-did-on-my-machine).** Accepted values are `"accept"`, `"hold"`, `"refuse"`. |
+| `dialogExpiry` | 2.1.224 | Paired with `crossSessionInbound`; controls how long the held approval dialog stays valid. |
+| `network.tlsTerminate` | 2.1.224 | Required for the sandbox credential-masking options below to take effect. |
+| `onExtractNoMatch` | 2.1.224 | Sandbox credential masking: what to do when `extract` finds no match in a structured env value. |
+| `maskClaims` | 2.1.224 | Sandbox credential masking with `decode: "jwt"` — masks named JWT claims. |
+| `awsPairs` | 2.1.224 | Sandbox credential masking for AWS SigV4 re-signing (with `sigv4`). |
+| `strictKnownMarketplaces` | 2.1.223 | Managed setting: allow-list for plugin marketplaces. Supports `hostPattern`, `pathPattern`, and owner wildcards (`"owner/*"`). Enforced on install, update, refresh and autoupdate. |
+| `blockedMarketplaces` | 2.1.223 | Managed setting: block-list for plugin marketplaces, same matching options. |
+| `modelOverrides` | 2.1.223 | Maps model-picker entries to custom provider model IDs (e.g. Bedrock inference profile ARNs). Keys that are not Anthropic model IDs are ignored. |
+| `sandbox.filesystem.denyWrite` | 2.1.223 | Sandbox write deny-list. A 2.1.223 fix covers the case where it includes the working directory. |
+| `remoteControlAtStartup` | 2.1.224 | Whether Remote Control starts with the session. |
+
+**Why three of these belong in a safety file, not just a completeness list**
+
+- `crossSessionInbound` is a permission gate — **but only if you set it.** I originally wrote here that
+  it is "the one place a message from another session still stops for a human" when you run with
+  `--dangerously-skip-permissions`. **I tested that claim and it was wrong on my machine.** Corrected
+  version and the measurements are in the next section. Set it explicitly; do not rely on the default.
+- `strictKnownMarketplaces` / `blockedMarketplaces` are supply-chain controls. They decide which plugin
+  sources can install code on your machine, and as of 2.1.223 they are enforced on **autoupdate** too —
+  so a source you allowed once keeps its access without a further prompt.
+- The sandbox credential-masking options only take effect with `network.tlsTerminate`. A masking rule
+  written without it is inert, and nothing in the output says so.
+
+**None of these are covered by the example hooks in this repo yet.** If you rely on the hooks for a
+control that one of these settings now provides natively, check both — they are separate layers.
+
+### What `crossSessionInbound` actually did on my machine
+
+I run a session under `--dangerously-skip-permissions` around the clock, so this setting is one I am
+exposed to rather than one I only read about. On **2026-08-11, Claude Code 2.1.226, Linux (WSL2)**, with
+`crossSessionInbound` absent from every settings file (`~/.claude/settings.json`, `settings.local.json`,
+and both project-level files — grepped, zero hits), I sent peer messages with `SendMessage` and watched
+what arrived.
+
+| # | receiver's `crossSessionInbound` | sender's permission class | result |
+|---|---|---|---|
+| 1 | unset (receiver in bypass) | `bypass` | **delivered** — no dialog, no hold |
+| 2 | unset (receiver in bypass) | `prompting` | **delivered** — no dialog, no hold |
+| 3 | `"refuse"` (via `--settings`) | `bypass` | **not delivered** — receiver stayed at 0 in / 0 out |
+| 4 | unset — same steps as #3, setting removed | `bypass` | **delivered, and the receiver acted on it** (41.1K in / 221 out: it composed and sent a reply, with no human in the loop) |
+
+Rows 3 and 4 are the same procedure with one file changed, so "an idle peer just doesn't render it" is
+ruled out. **The gate works. What does not work is leaving it unset.**
+
+Two things follow, and they are the reason this correction matters more than a wording fix:
+
+1. **The default did not stop anything for a human here.** If you are running unattended and you assumed
+   the gate was on by default — as I did, and as I wrote in this file — you were not protected.
+2. **What arrives in place of a gate is a warning aimed at the model, not a block.** The delivered
+   message carried instructions telling the receiving Claude not to treat a peer as an escalation path
+   ("permission laundering"). That is a real mitigation, but it is enforced by the model choosing to obey,
+   not by the permission system refusing. Those are different security properties and this file should
+   not have blurred them.
+
+**What to set.** An explicit value is evaluated before any mode-based default, so it always wins
+(a repository-level setting can only tighten it further, never loosen it):
+
+```json
+{
+  "crossSessionInbound": "refuse"
+}
+```
+
+- `"refuse"` — opt this session out entirely. **This is the one I verified** (row 3). Use it for
+  unattended sessions, where "held for review" means "held until nobody reviews it".
+- `"hold"` — park messages for your approval. Sensible when a human is actually watching the session.
+  Note from reading the 2.1.226 implementation (not measured): the hold buffer is bounded, the oldest
+  entry is dropped as *expired* when it overflows, and anything still held is settled as *expired* at
+  shutdown. Held is not a durable queue.
+- `"accept"` — deliver everything. This is what my unset session behaved like.
+
+**What I did not establish.** I could not reconcile the delivery in rows 1, 2 and 4 with the gating code
+I read in the 2.1.226 binary: with no explicit setting and a bypass-class receiver, every branch I found
+returns *hold*. Something outside those files decides — most likely a server-delivered settings layer,
+which is not greppable from disk. I am reporting the behaviour I measured and flagging the mechanism as
+unknown, rather than inventing an explanation that fits.
+
 ## Troubleshooting
 
 | Problem | Cause | Fix |
 |---------|-------|-----|
-| Hooks don't fire | Not registered in settings.json | `npx cc-safe-setup` |
+| Skill won't auto-trigger | `description` truncated past `skillListingMaxDescChars` (default 1536), or too many skills under the 1% listing budget | Put trigger words first, shorten descriptions, prune unused skills (see Undocumented settings above) |
+| Model changed mid-session | `switchModelsOnFlag` is `true` by default; a safety flag auto-switched the model | Set `"switchModelsOnFlag": false` to pause instead |
+| Hooks don't fire | Not registered in settings.json | `npx github:yurukusa/cc-safe-setup` |
 | Hooks don't block | Wrong exit code (not 2) | Check `echo $?` after test |
 | "jq: command not found" | jq not installed | `brew install jq` / `apt install jq` |
 | Hook permission denied | Not executable | `chmod +x ~/.claude/hooks/*.sh` |
 | Compound commands prompt | Permission system limitation | Install `compound-command-approver` |
 | "Always Allow" doesn't stick | Saves exact string, not pattern | Use hooks instead |
 
-Run `npx cc-safe-setup --doctor` for automated diagnosis.
+Run `npx github:yurukusa/cc-safe-setup --doctor` for automated diagnosis.
 
 ## Resources
 
-- [Official Hooks Documentation](https://docs.anthropic.com/en/docs/claude-code/hooks)
+- [Official Hooks Documentation](https://code.claude.com/docs/en/hooks)
 - [COOKBOOK.md](https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md) — 20 hook recipes
 - [Migration Guide](MIGRATION.md) — from permissions to hooks
 - [Ecosystem Comparison](https://yurukusa.github.io/cc-safe-setup/ecosystem.html) — all hook projects

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cc-safe-setup
-description: Safety hooks for Claude Code — 700 pre-built hooks that prevent file deletion, credential leaks, git disasters, and token waste during autonomous AI coding sessions. 9,200+ tests. Install with npx cc-safe-setup.
+description: Safety hooks for Claude Code — 916 pre-built hooks that prevent file deletion, credential leaks, git disasters, and token waste during autonomous AI coding sessions. 296 test files. Install with npx github:yurukusa/cc-safe-setup.
 ---
 
 # cc-safe-setup
@@ -21,7 +21,7 @@ Installs pre-built safety hooks into your Claude Code environment. These hooks r
 ## Quick start
 
 ```bash
-npx cc-safe-setup
+npx github:yurukusa/cc-safe-setup
 ```
 
 This runs an interactive wizard that configures hooks based on your risk profile.
@@ -29,9 +29,9 @@ This runs an interactive wizard that configures hooks based on your risk profile
 ## Install individual hooks
 
 ```bash
-npx cc-safe-setup --install-example large-read-guard
-npx cc-safe-setup --install-example prevent-rm-rf
-npx cc-safe-setup --install-example git-force-push-block
+npx github:yurukusa/cc-safe-setup --install-example large-read-guard
+npx github:yurukusa/cc-safe-setup --install-example prevent-rm-rf
+npx github:yurukusa/cc-safe-setup --install-example git-force-push-block
 ```
 
 ## Why hooks instead of CLAUDE.md rules