@codewizard-dt/bootstrap 2.15.0 → 2.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/lib/hooks/README.md +192 -184
  2. package/lib/hooks/absolute-path-guard.js +5 -0
  3. package/lib/hooks/claude-settings-guard.js +43 -73
  4. package/lib/hooks/env-content-read-guard.js +13 -3
  5. package/lib/hooks/env-file-guard.js +42 -0
  6. package/lib/hooks/interpreter-indirection-guard.js +7 -0
  7. package/lib/hooks/lib/command-parse.js +8 -0
  8. package/lib/hooks/lib/serena-languages.js +94 -1
  9. package/lib/hooks/lib/serena.js +228 -0
  10. package/lib/hooks/mv-absolute-path-block.js +84 -3
  11. package/lib/hooks/package-install-consent.js +11 -0
  12. package/lib/hooks/protected-write-guard.js +7 -0
  13. package/lib/hooks/serena-bash-grep-block.js +507 -44
  14. package/lib/hooks/serena-first-glob-guard.js +65 -20
  15. package/lib/hooks/serena-first-guard.js +98 -2
  16. package/lib/hooks/serena-first-read-guard.js +92 -2
  17. package/lib/hooks/serena-pre-delegation.js +123 -0
  18. package/lib/hooks/serena-write-guard.js +56 -3
  19. package/lib/scripts/README.md +319 -16
  20. package/lib/scripts/bootstrap-prefs.js +734 -0
  21. package/lib/scripts/install-global.sh +182 -25
  22. package/lib/scripts/install-mcps.sh +102 -14
  23. package/lib/scripts/lib.sh +595 -20
  24. package/lib/scripts/merge-gitignore.sh +254 -16
  25. package/lib/scripts/merge-settings-hooks.js +374 -0
  26. package/lib/scripts/sync-wiki-scaffold.sh +33 -4
  27. package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
  28. package/lib/scripts/templates/bootstrap-prefs-schema.json +175 -0
  29. package/lib/scripts/templates/settings-hooks.json +151 -0
  30. package/lib/scripts/update-project.sh +42 -9
  31. package/lib/skills/README.md +2 -1
  32. package/lib/skills/bootstrap-config/SKILL.md +154 -0
  33. package/lib/skills/git-commit/SKILL.md +54 -1
  34. package/lib/skills/research/SKILL.md +34 -3
  35. package/lib/skills/simplify/SKILL.md +1 -1
  36. package/lib/skills/uat-auto/SKILL.md +9 -4
  37. package/lib/skills/uat-auto-plus/SKILL.md +6 -6
  38. package/lib/skills/uat-generate/SKILL.md +30 -3
  39. package/lib/skills/uat-walk/UAT-CORE.md +41 -6
  40. package/lib/skills/wiki-query/SKILL.md +48 -8
  41. package/package.json +1 -1
@@ -4,10 +4,14 @@ PreToolUse / PostToolUse / SessionStart hook scripts managed by this template.
4
4
  `./lib/scripts/install-global.sh` (also `npx @codewizard-dt/bootstrap install`)
5
5
  rsyncs this directory — including `lib/` — to `~/.claude/hooks/`.
6
6
 
7
- **Important:** the install script copies the *scripts* but does **not** wire them
8
- into `~/.claude/settings.json`. Hook *registration* is a global-settings concern
9
- and must be added once, by hand, using the snippets below. Without the wiring the
10
- scripts sit on disk and never run.
7
+ The same run also *registers* them: after the deny-list merge,
8
+ `lib/scripts/merge-settings-hooks.js` merges the canonical wiring template
9
+ ([`lib/scripts/templates/settings-hooks.json`](../scripts/templates/settings-hooks.json))
10
+ into the `hooks` key of `~/.claude/settings.json`. Manual pasting is no longer
11
+ required — copying the scripts and wiring them are one step, repeated
12
+ idempotently on every `install` / `setup` / `update` run. See
13
+ [the wiring section below](#required-claudesettingsjson-wiring) for the merge
14
+ semantics.
11
15
 
12
16
  ## Why hooks (vs. allow/deny permission rules)
13
17
 
@@ -28,6 +32,97 @@ cannot enumerate — and it can return a **message** explaining the block, which
28
32
  exiting 2 stops a call the rules would never see. Keep a matching `deny` entry
29
33
  too — defence in depth, and the rules keep working if a hook ever fails to fire.
30
34
 
35
+ ## Commenting standard
36
+
37
+ **The repo-wide "no comments" default is suspended in `lib/hooks/`, and only
38
+ here.** Everywhere else the default holds: self-documenting code, no commentary.
39
+ These files are the exception because they encode *security decisions* whose
40
+ rationale is not recoverable from the code. A regex tells you what it matches; it
41
+ cannot tell you which real command motivated it, which false positive was accepted
42
+ in exchange, or what breaks if you move the check above it. The comments are that
43
+ record — **do not "clean them up" as slop.** The exception does not extend to
44
+ `lib/scripts/`, `lib/skills/`, or `bin/`.
45
+
46
+ **Why, never what.** A comment restating a regex in English is worse than no
47
+ comment: it adds a second thing to keep in sync and answers a question nobody
48
+ had. Comment these five classes, and largely nothing else.
49
+
50
+ 1. **Why a pattern is in a list** — and what real command motivated it.
51
+ 2. **Why a threshold has its value** — `MAX_WALK = 64`, `prompt.length < 200`,
52
+ the 2-hour `.task/` mtime window, `FREE_READS` / `WARN_AT`. A bare number is
53
+ unauditable; a number with its reason can be argued with.
54
+ 3. **Known false positives, each with its escape hatch** — the deny message
55
+ usually names the escape hatch, so the comment's job is why the trade was
56
+ accepted.
57
+ 4. **Ordering dependencies** — where moving a check breaks the guard. State the
58
+ failure ("reversing these deadlocks Gate 1"), not that order matters.
59
+ 5. **Why a tempting simplification was rejected** — the refactor the next reader
60
+ will otherwise attempt, and what it costs.
61
+
62
+ **Point at this README; do not restate it.** The three groups above are
63
+ documented here in very different depth, and the inline comments take up exactly
64
+ the slack:
65
+
66
+ - **Command-class guards** already have a full per-hook section above (Blocks /
67
+ Why a hook / Why not X / Accepted consequence / Known friction / Residual risk
68
+ / Cost / Not covered). Their comments carry **none** of that argument — a
69
+ header block that ends in `See README.md § <section>`, plus inline notes only
70
+ where the prose does not reach (a specific lookahead, a fail-closed branch).
71
+ Two copies of one argument drift, and the copy in the code drifts silently.
72
+ - **Serena-first hooks** get only a one-line-purpose table row plus the shared
73
+ narrative sections. Nothing else records their heuristics, so here the inline
74
+ comments *are* the primary documentation and carry the full weight.
75
+ - **Safety / policy hooks** get a three-column table row. Same as above: comment
76
+ fully.
77
+
78
+ **Every file opens with this header block.** It is a signpost, not a second copy
79
+ of the README section:
80
+
81
+ ```js
82
+ /**
83
+ * <file>.js — <event>[ + <event>] / <matcher>
84
+ *
85
+ * Blocks: <the surface it gates, one line>
86
+ * Why a hook: <why a settings.json rule cannot express this>
87
+ * Fails: open|closed — <what happens when the check itself cannot run>
88
+ * False positives: <the known one> — escape hatch: <the rephrase that clears it>
89
+ * See README.md § <exact heading> for the full rationale.
90
+ */
91
+ ```
92
+
93
+ - The **matcher** belongs on the identity line because the wrong matcher makes a
94
+ hook silently inert (see [the wiring notes](#required-claudesettingsjson-wiring)).
95
+ A hook wired on two events lists both.
96
+ - A hook that gates nothing (`serena-usage-tracker.js`,
97
+ `serena-session-reset.js`) replaces `Blocks:` with `Does:` and may drop
98
+ `False positives:`.
99
+ - **`Fails:` is required for anything that can block a call**, because it is
100
+ never inferable from a skim and the answer is rarely the one you would guess.
101
+ The *infrastructure* fails **open** across nearly every guard: the shared
102
+ `readHookInput` in `lib/command-parse.js` wraps both the `JSON.parse` and the
103
+ handler call in `try { … } catch { process.exit(0) }`, and states fail-open as
104
+ the deliberate module-wide contract — so the five guards built on it allow the
105
+ call whenever the check itself cannot run. `env-file-guard.js` and
106
+ `mv-absolute-path-block.js` hand-roll their own stdin handlers and also fail
107
+ open. What fails **closed** is an ambiguous *match*: a construct the guard did
108
+ parse but cannot vouch for is blocked. `interpreter-indirection-guard.js` is
109
+ the sole genuinely fail-closed guard — a missing sibling file, a spawn error, a
110
+ 2s timeout, non-JSON output, a non-zero exit, or an unreadable deny list all
111
+ deny. Serena-first guards fail **open** by explicit design (see
112
+ [Health tracking & fail-open enforcement](#health-tracking--fail-open-enforcement)).
113
+ - Below the block, add free-form paragraphs only for structure the fields cannot
114
+ carry — a two-mode split, a payload-shape compatibility note. Keep the whole
115
+ header under ~30 lines; a header approaching the length of its README section
116
+ has become the duplicate this standard exists to prevent.
117
+
118
+ **The calibration target is `serena-usage-tracker.js:4-32`** (29 lines), which
119
+ predates this standard and already meets it: it names its two modes and what each
120
+ one *decides*, states the one non-obvious fact a reader cannot derive (both
121
+ PostToolUse and PostToolUseFailure payload shapes are handled, and that dual
122
+ handling is also the version-compatibility fallback), and **delegates rather than
123
+ restates** — `./lib/serena.js#isLspProviderTool` instead of a paragraph on tool-name
124
+ forms. Not one line of it describes what a line of code does. Match that.
125
+
31
126
  ---
32
127
 
33
128
  ## Scripts
@@ -54,7 +149,7 @@ environment assignment, or on the far side of an MCP tool boundary.
54
149
  | `package-install-consent.js` | `Bash` | Every package-manager install, with one allowlisted source (Serena) |
55
150
  | `absolute-path-guard.js` | `Bash` | Evasive *spellings* of destructive commands (`/bin/rm`, `\rm`, `env rm`) |
56
151
  | `protected-write-guard.js` | `Bash` | `>`/`>>` into shell/git/Claude config, `DYLD_*`/`LD_*` injection, `git -c` RCE config keys |
57
- | `claude-settings-guard.js` | `Edit\|Write\|NotebookEdit\|MultiEdit` | File-tool writes to `~/.claude/settings*.json` (with a bootstrap-claude exception) and `~/.claude/hooks/**` (no exception) |
152
+ | `claude-settings-guard.js` | `Edit\|Write\|NotebookEdit\|MultiEdit` | File-tool writes to `~/.claude/settings*.json` and `~/.claude/hooks/**` — unconditional, no exceptions |
58
153
  | `env-content-read-guard.js` | `Bash\|mcp__serena__.*\|mcp__plugin_[^_]+_serena__.*` | `.env` *contents* reaching the transcript, on both the Bash and Serena surfaces |
59
154
 
60
155
  They share `lib/command-parse.js` (stdin read, segment split, tokenize, deny
@@ -352,10 +447,28 @@ protected paths (`echo … >> ~/.claude/settings.json`) is
352
447
  `protected-write-guard.js` rule 1.
353
448
 
354
449
  **Blocks** `Edit`/`Write`/`NotebookEdit`/`MultiEdit` targeting
355
- `~/.claude/settings.json` and `~/.claude/settings.local.json` — **except** when
356
- the session's working directory sits inside a genuine bootstrap-claude checkout —
357
- and anything under `~/.claude/hooks/` with **no exception at all**.
358
-
450
+ `~/.claude/settings.json`, `~/.claude/settings.local.json`, and anything under
451
+ `~/.claude/hooks/`. **Unconditional — the verdict does not depend on cwd.**
452
+
453
+ > **A bootstrap-claude carve-out existed here and was removed on 2026-07-30.**
454
+ > It allowed the settings write when the session's cwd sat inside a genuine
455
+ > checkout, identified by marker file (`lib/scripts/templates/settings-deny.json`
456
+ > plus a `package.json` named `@codewizard-dt/bootstrap`) rather than by directory
457
+ > name. The rationale was that this repo manages those files.
458
+ >
459
+ > **That rationale was wrong.** The repo writes them through
460
+ > `node merge-settings-deny.js` (and now `merge-settings-hooks.js`) *inside*
461
+ > `install-global.sh` — Bash subprocesses that no `PreToolUse` hook and no
462
+ > permission rule ever observes. Nothing here
463
+ > ever needed the Edit *tool* on those paths. The exception was not load-bearing,
464
+ > and it did let any agent running in this repo rewrite its own permission
465
+ > boundary — which was demonstrated live before it was closed.
466
+ >
467
+ > The former marker shapes are still exercised in
468
+ > `test/command-class-hooks.test.js`, now asserting **deny**, because they are the
469
+ > most sensitive canaries for the carve-out creeping back.
470
+
471
+ <!-- superseded, retained for provenance:
359
472
  **A checkout is identified by marker file, not by path substring.**
360
473
  `cwd.includes('bootstrap-claude')` is spoofed by `mkdir bootstrap-claude`, so
361
474
  both of these must hold at a candidate root: `lib/scripts/templates/settings-deny.json`
@@ -375,6 +488,18 @@ deny made the repo unable to work on itself. A hook is the only layer that can
375
488
  carry a conditional. The shipped deny list carries zero `.claude/settings`
376
489
  entries today and `test/settings-deny.test.js` locks that in, so the carve-out is
377
490
  live rather than dead on arrival.
491
+ -->
492
+
493
+ **The deny entries stay out, and that is now a free choice rather than a forced one.**
494
+ `Edit(~/.claude/settings.json)` and `Edit(~/.claude/settings.local.json)` were
495
+ removed from `settings-deny.json` to make the carve-out expressible — deny beats
496
+ allow at every scope, and a hook cannot loosen a deny rule, so the exception was
497
+ unsayable while they existed. With the carve-out gone they could be restored as
498
+ defence in depth. They have not been, deliberately: the deny merge is
499
+ additive-only with **no removal path**, so re-adding them is permanent for every
500
+ installed user, and the hook already blocks the same surface *plus* the `Write`
501
+ and `NotebookEdit` tools that `Edit(...)` rules never reach. Restore them only if
502
+ the hook proves unreliable.
378
503
 
379
504
  **Why the `~/.claude/hooks/` tree is also checked here, and is not duplication.** The
380
505
  `Edit(~/.claude/hooks/**)` and `Edit(**/.claude/hooks/**)` deny entries remain in
@@ -395,13 +520,18 @@ same function so both sides of the comparison are real paths, and a literal `~`
395
520
  `NotebookEdit` names its target `notebook_path`; `MultiEdit` is checked per
396
521
  `edits[].file_path`, so a protected target cannot ride along in a batch.
397
522
 
398
- **Residual risk, accepted deliberately.** An agent working inside a genuine
399
- bootstrap-claude checkout can still self-grant permissions by writing
400
- `~/.claude/settings.json`. This hook does not prevent that and is not trying to:
401
- managing those settings is this repo's entire purpose, so the exception *is* the
402
- feature. The containment for a compromised agent inside this repo is OS-level
403
- sandboxing, not this hook. **Do not "harden" this by removing the exception** —
404
- it breaks the repo and still would not contain a Bash-capable agent.
523
+ **Residual risk, stated plainly.** This hook guards the file *tools*. An agent
524
+ with Bash can still reach these files another way — `node write-settings.js`
525
+ gets there, and nothing here parses inside a script file.
526
+ `protected-write-guard.js` catches shell redirects
527
+ (`echo … >> ~/.claude/settings.json`) and `interpreter-indirection-guard.js`
528
+ catches `node -e`, but a script written to disk and then executed is uncovered by
529
+ design.
530
+
531
+ So this is a guardrail, not a boundary: it closes the casual and accidental paths
532
+ — which is most of them — and raises the cost of the deliberate one. The only
533
+ real containment for a compromised agent is OS-level sandboxing (`/sandbox`).
534
+ Do not read "unconditional" as "guaranteed".
405
535
 
406
536
  **Not covered, deliberately:** project-level `.claude/settings.json` files (this
407
537
  hook is scoped to the user-global `~/.claude/` tree); and writing a script
@@ -424,7 +554,7 @@ extension, which `.env` is neither.
424
554
 
425
555
  **Relationship to `serena-bash-grep-block.js`.** That hook's grep phase goes
426
556
  further and *explicitly allows* `.env` targets as a "non-code extension"
427
- (`:126`, `:160`, `:189`). That is correct for its purpose — Serena-first
557
+ (`:312`, `:393`, `:454`). That is correct for its purpose — Serena-first
428
558
  navigation does not care about non-code files — and wrong for this one, and it is
429
559
  why `grep KEY .env` leaked. The two are complementary: the navigation hook decides
430
560
  where you should look for *code*, this one decides what may be *displayed*.
@@ -464,7 +594,7 @@ Closing only Bash would have moved the leak rather than sealed it:
464
594
  returns exactly the same lines.
465
595
 
466
596
  **`source .env` and `. .env` remain permitted. This is deliberate — do not "close
467
- the gap" later.** `CLAUDE.md` grants it and `env-file-guard.js:39` says so in its
597
+ the gap" later.** `CLAUDE.md` grants it and `env-file-guard.js:81` says so in its
468
598
  own deny message. Sourcing loads values into the environment and prints *nothing*;
469
599
  the leak is sourcing **plus emission** (`source .env && echo $KEY`), and the
470
600
  emission half can be written without `source` at all. Blocking `source` would
@@ -480,7 +610,7 @@ naming a *directory* that contains a `.env`; `find . -name .env -exec cat {} +`
480
610
  and `xargs cat` (the reader is not at the front of a segment); `git show
481
611
  HEAD:.env`; `docker exec … cat .env`.
482
612
 
483
- **Follow-up.** `isBlockedEnvFile` is byte-identical to `env-file-guard.js:6-13`
613
+ **Follow-up.** `isBlockedEnvFile` is byte-identical to `env-file-guard.js:48-55`
484
614
  and is annotated "change it in both places or in neither". It should be extracted
485
615
  into `lib/` so the two cannot drift; that was left undone here because it means
486
616
  editing a live shipped control for a refactor.
@@ -683,164 +813,38 @@ acquirer rather than blocking on it.
683
813
 
684
814
  ## Required `~/.claude/settings.json` wiring
685
815
 
686
- Add these under `hooks`. If a block already exists for a given matcher, add the
687
- hook objects to its existing `hooks` array rather than creating a second block.
688
-
689
- ```json
690
- {
691
- "hooks": {
692
- "SessionStart": [
693
- {
694
- "hooks": [
695
- {
696
- "type": "command",
697
- "command": "node ~/.claude/hooks/serena-session-reset.js"
698
- }
699
- ]
700
- }
701
- ],
702
- "PreToolUse": [
703
- {
704
- "matcher": "Read|Write|Edit|MultiEdit",
705
- "hooks": [
706
- {
707
- "type": "command",
708
- "command": "node ~/.claude/hooks/env-file-guard.js"
709
- }
710
- ]
711
- },
712
- {
713
- "matcher": "Edit|Write|NotebookEdit|MultiEdit",
714
- "hooks": [
715
- {
716
- "type": "command",
717
- "command": "node ~/.claude/hooks/claude-settings-guard.js"
718
- }
719
- ]
720
- },
721
- {
722
- "matcher": "Bash|mcp__serena__.*|mcp__plugin_[^_]+_serena__.*",
723
- "hooks": [
724
- {
725
- "type": "command",
726
- "command": "node ~/.claude/hooks/env-content-read-guard.js"
727
- }
728
- ]
729
- },
730
- {
731
- "matcher": "Read",
732
- "hooks": [
733
- {
734
- "type": "command",
735
- "command": "node ~/.claude/hooks/serena-first-read-guard.js"
736
- }
737
- ]
738
- },
739
- {
740
- "matcher": "Edit|MultiEdit",
741
- "hooks": [
742
- {
743
- "type": "command",
744
- "command": "node ~/.claude/hooks/serena-edit-guard.js"
745
- }
746
- ]
747
- },
748
- {
749
- "matcher": "Write",
750
- "hooks": [
751
- {
752
- "type": "command",
753
- "command": "node ~/.claude/hooks/serena-write-guard.js"
754
- }
755
- ]
756
- },
757
- {
758
- "matcher": "Grep",
759
- "hooks": [
760
- {
761
- "type": "command",
762
- "command": "node ~/.claude/hooks/serena-first-guard.js"
763
- }
764
- ]
765
- },
766
- {
767
- "matcher": "Glob",
768
- "hooks": [
769
- {
770
- "type": "command",
771
- "command": "node ~/.claude/hooks/serena-first-glob-guard.js"
772
- }
773
- ]
774
- },
775
- {
776
- "matcher": "Agent",
777
- "hooks": [
778
- {
779
- "type": "command",
780
- "command": "node ~/.claude/hooks/serena-pre-delegation.js"
781
- }
782
- ]
783
- },
784
- {
785
- "matcher": "Bash",
786
- "hooks": [
787
- {
788
- "type": "command",
789
- "command": "node ~/.claude/hooks/serena-bash-grep-block.js"
790
- },
791
- {
792
- "type": "command",
793
- "command": "node ~/.claude/hooks/mv-absolute-path-block.js",
794
- "if": "Bash(mv *)"
795
- },
796
- {
797
- "type": "command",
798
- "command": "node ~/.claude/hooks/git-protected-ops-block.js"
799
- },
800
- {
801
- "type": "command",
802
- "command": "node ~/.claude/hooks/interpreter-indirection-guard.js"
803
- },
804
- {
805
- "type": "command",
806
- "command": "node ~/.claude/hooks/package-install-consent.js"
807
- },
808
- {
809
- "type": "command",
810
- "command": "node ~/.claude/hooks/absolute-path-guard.js"
811
- },
812
- {
813
- "type": "command",
814
- "command": "node ~/.claude/hooks/protected-write-guard.js"
815
- }
816
- ]
817
- }
818
- ],
819
- "PostToolUse": [
820
- {
821
- "matcher": "mcp__serena__.*|mcp__plugin_[^_]+_serena__.*",
822
- "hooks": [
823
- {
824
- "type": "command",
825
- "command": "node ~/.claude/hooks/serena-usage-tracker.js"
826
- }
827
- ]
828
- }
829
- ],
830
- "PostToolUseFailure": [
831
- {
832
- "matcher": "mcp__serena__.*|mcp__plugin_[^_]+_serena__.*",
833
- "hooks": [
834
- {
835
- "type": "command",
836
- "command": "node ~/.claude/hooks/serena-usage-tracker.js"
837
- }
838
- ]
839
- }
840
- ]
841
- }
842
- }
843
- ```
816
+ The canonical wiring — which script runs on which event, under which matcher —
817
+ lives in exactly one place:
818
+ [`lib/scripts/templates/settings-hooks.json`](../scripts/templates/settings-hooks.json).
819
+ It is a bare hooks-value object (four events: `SessionStart`, `PreToolUse`,
820
+ `PostToolUse`, `PostToolUseFailure`) whose entries map 1:1 onto the scripts in
821
+ this directory. This README deliberately does not inline a copy: the template
822
+ file is what `merge-settings-hooks.js` reads and merges into the `hooks` key of
823
+ `~/.claude/settings.json` on every `install` / `setup` / `update` run, so a
824
+ second copy here could only drift from what actually ships.
825
+
826
+ Merge semantics — "the template owns its blocks":
827
+
828
+ - **Foreign (user-added) blocks and hook entries are never modified, reordered,
829
+ or removed.** The same goes for entire hooks events the template does not ship
830
+ (e.g. `UserPromptSubmit`): the merge never visits them. A repo hook found
831
+ relocated into a user-modified block is left where it is (with a warning), not
832
+ duplicated back into the template's block, and the merge never writes an empty
833
+ placeholder block. It always exits 0 — a wiring merge must never abort an
834
+ install.
835
+ - **Direct edits to an *owned* entry are overwritten on the next run.** An entry
836
+ is owned when its `command` points at `~/.claude/hooks/<name>.js` (or an
837
+ absolute-path expansion of it) and `<name>` matches a hook the template ships.
838
+ Because the template owns its blocks, any local tweak to such an entry — and
839
+ any matcher drift on a block made up entirely of owned entries — is reverted
840
+ to the template's version the next time `install` / `setup` / `update` runs.
841
+ To opt an entry out of the overwrite, point its `command` at a different path
842
+ (e.g. a copy of the script outside `~/.claude/hooks/`) so it no longer
843
+ classifies as owned; the merge will then treat it as foreign and leave it
844
+ alone. Note the limit of that opt-out: because the re-pointed entry no longer
845
+ carries the template basename, the next merge run re-appends the stock
846
+ template entry alongside it — your variant is preserved, but the shipped hook
847
+ is not disabled.
844
848
 
845
849
  Three notes on the command-class guard matchers, each of which makes a hook
846
850
  silently inert if it is wrong:
@@ -863,13 +867,16 @@ silently inert if it is wrong:
863
867
  permission-matcher path that lets compound and piped commands slip past a `deny`
864
868
  rule.
865
869
 
866
- Reminder: `install-global.sh` rsyncs these scripts to `~/.claude/hooks/` on every
867
- run, but it never touches the `hooks` section of `~/.claude/settings.json`.
868
- Registration is the one-time manual step above; until it is done every script
869
- here sits on disk and does nothing.
870
+ Reminder: `install-global.sh` rsyncs these scripts to `~/.claude/hooks/` on
871
+ every run **and** registers them, by running `merge-settings-hooks.js` right
872
+ after the deny-list merge. There is no one-time manual step: the wiring is
873
+ re-merged automatically on every `install` / `setup` / `update` run, and when
874
+ that merge creates the wiring fresh or applies changes, the install prints a
875
+ note to restart your Claude Code sessions (hooks load at session start, so a
876
+ running session does not pick up new wiring).
870
877
 
871
- The `PostToolUse` matcher is broadened from the six navigation tools to **all**
872
- Serena tools so every call feeds health tracking; the tracker gates the read-guard
878
+ The template's `PostToolUse` matcher is broadened from the six navigation tools
879
+ to **all** Serena tools so every call feeds health tracking; the tracker gates the read-guard
873
880
  nav counters internally (only the six nav/exploration tools advance the gate, as
874
881
  before). The `PostToolUseFailure` block points at the same script — see
875
882
  [Health tracking & fail-open enforcement](#health-tracking--fail-open-enforcement)
@@ -894,4 +901,5 @@ Two documented caveats on those deny rules:
894
901
  matching call even when a narrower `allow` rule also matches. So
895
902
  `Bash(git stash:*)` also blocks read-only `git stash list`.
896
903
 
897
- Hooks load at session start, so restart any running session after wiring.
904
+ Hooks load at session start, so restart any running session after an install
905
+ run that created or changed the wiring.
@@ -46,6 +46,11 @@
46
46
  // reason to reach for the absolute path here, and the path prefix is itself
47
47
  // the signal — inspecting the arguments to decide would put us back to
48
48
  // matching literal spellings, which is the failure this tier exists to escape.
49
+ //
50
+ // Fails: open — this hook reads nothing but the command string, so no check can
51
+ // be left unrun; a throw exits 0 via lib/command-parse.js. Its firing rule is
52
+ // the conservative half: an evasive spelling blocks even when the underlying
53
+ // command would have been allowed.
49
54
  // ---------------------------------------------------------------------------
50
55
 
51
56
  const { readHookInput, splitSegments, tokenize, deny } = require('./lib/command-parse');
@@ -16,15 +16,21 @@
16
16
  //
17
17
  // TASK-026 originally shipped `Edit(~/.claude/settings.json)` and
18
18
  // `Edit(~/.claude/settings.local.json)` as deny entries. They were removed on
19
- // 2026-07-29 by user decision, because THIS repo legitimately manages those
20
- // files — that is exactly what install-global.sh and merge-settings-deny.js
21
- // do — and a blanket deny made the repo unable to work on itself.
19
+ // 2026-07-29 to make room for a bootstrap-claude carve-out, on the belief that
20
+ // THIS repo needs to edit those files because install-global.sh and
21
+ // merge-settings-deny.js manage them.
22
22
  //
23
- // The removal was forced, not preferred. Deny beats allow at every scope, and
24
- // a hook returning `allow` cannot loosen a deny rule either, so there is no
25
- // way to express "blocked everywhere except here" while the deny entry
26
- // exists. The entry had to come out for the exception to be sayable at all.
27
- // A hook is the only layer that can carry a conditional.
23
+ // THAT BELIEF WAS WRONG, and the carve-out was removed on 2026-07-30. The
24
+ // repo's settings writes go through `node merge-settings-deny.js` *inside*
25
+ // install-global.sh — Bash subprocesses, which no PreToolUse hook and no
26
+ // permission rule ever sees. Nothing in this repo's workflow needs the Edit
27
+ // TOOL on those files. The exception cost real safety and bought nothing:
28
+ // it let any agent running here rewrite its own permission boundary, which
29
+ // was demonstrated live before it was closed.
30
+ //
31
+ // The block is now unconditional. To change the permission rules, edit
32
+ // lib/scripts/templates/settings-deny.json and re-run install-global.sh —
33
+ // the same flow this hook's message tells everyone else to use.
28
34
  //
29
35
  // Why ~/.claude/hooks/** is ALSO checked here, and is not redundant:
30
36
  //
@@ -46,14 +52,17 @@
46
52
  //
47
53
  // RESIDUAL RISK, stated plainly:
48
54
  //
49
- // An agent working inside a genuine bootstrap-claude checkout can still
50
- // self-grant permissions by writing ~/.claude/settings.json. This hook does
51
- // not prevent that and is not trying to. It is an accepted, deliberate
52
- // trade-off: managing those settings is this repo's entire purpose, so the
53
- // exception is the feature. The containment for a compromised agent inside
54
- // this repo is Tier 3 (/sandbox — OS-level confinement), not this hook.
55
- // Do not "harden" this by removing the exception; that breaks the repo and
56
- // still would not contain a Bash-capable agent.
55
+ // This hook guards the file TOOLS. An agent with Bash can still write these
56
+ // files another way — `node write-settings.js` reaches them, and no hook here
57
+ // parses inside a script file. protected-write-guard.js catches shell
58
+ // redirects (`echo … >> ~/.claude/settings.json`) and
59
+ // interpreter-indirection-guard.js catches `node -e`, but a script written to
60
+ // disk and then executed is not covered by design.
61
+ //
62
+ // So this is a guardrail, not a boundary: it closes the casual and accidental
63
+ // paths, which is most of them, and raises the cost of the deliberate one. The
64
+ // only real containment for a compromised agent is Tier 3 (/sandbox —
65
+ // OS-level confinement). Do not read the unconditional block as a guarantee.
57
66
  //
58
67
  // Known gaps, deliberate:
59
68
  // - Project-level `.claude/settings.json` files are not guarded here; this
@@ -62,18 +71,17 @@
62
71
  // replaces some unguarded path with a symlink and then writes through it is
63
72
  // caught (the target resolves into ~/.claude/), but an agent that writes a
64
73
  // script elsewhere and executes it is a Bash concern, not this hook's.
74
+ //
75
+ // Fails: open — realpathBestEffort() has no error return: when nothing along the
76
+ // ancestor chain resolves it hands back the lexical path, so a target whose real
77
+ // location could not be determined is classified on its spelling alone and can
78
+ // miss. A throw anywhere in the handler exits 0 via lib/command-parse.js.
65
79
 
66
80
  const fs = require('fs');
67
81
  const os = require('os');
68
82
  const path = require('path');
69
83
  const { readHookInput, deny } = require('./lib/command-parse');
70
84
 
71
- // Both marker conditions must hold for a directory to count as a real
72
- // bootstrap-claude checkout. A path-substring test like
73
- // `cwd.includes('bootstrap-claude')` is spoofed by `mkdir bootstrap-claude`.
74
- const MARKER_FILE = path.join('lib', 'scripts', 'templates', 'settings-deny.json');
75
- const MARKER_PACKAGE_NAME = '@codewizard-dt/bootstrap';
76
-
77
85
  // Upper bound on any parent walk. path.dirname() is purely lexical and reaches
78
86
  // a fixed point at the filesystem root, so this is belt-and-braces against a
79
87
  // pathological input rather than a real loop risk — but a hook must never hang.
@@ -135,49 +143,17 @@ function classify(resolved) {
135
143
  return null;
136
144
  }
137
145
 
138
- /**
139
- * A directory is a bootstrap-claude root only if it carries the template the
140
- * deny list is authored in AND its package.json claims the package name.
141
- * A missing, unreadable, or unparseable package.json means "not a checkout" —
142
- * never a crash.
143
- */
144
- function isBootstrapRoot(dir) {
145
- try {
146
- if (!fs.statSync(path.join(dir, MARKER_FILE)).isFile()) return false;
147
- const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
148
- return pkg && pkg.name === MARKER_PACKAGE_NAME;
149
- } catch {
150
- return false;
151
- }
152
- }
153
-
154
- /**
155
- * Walk up from the session's directory looking for a marker root. The walk is
156
- * lexical (path.dirname), so it cannot follow a symlink into a cycle, and it
157
- * terminates at the filesystem root. No marker root found means no exception.
158
- */
159
- function findBootstrapRoot(startDir) {
160
- let dir = realpathBestEffort(startDir);
161
- for (let i = 0; i < MAX_WALK; i++) {
162
- if (isBootstrapRoot(dir)) return dir;
163
- const parent = path.dirname(dir);
164
- if (parent === dir) return null;
165
- dir = parent;
166
- }
167
- return null;
168
- }
169
-
170
146
  function reasonForSettings(resolved) {
171
147
  return (
172
- `Blocked: editing \`${resolved}\` outside a bootstrap-claude checkout. ` +
173
- `This file decides what every agent session is permitted to do, so a write to it ` +
174
- `is a change to your own permission boundary rather than a change to a project. ` +
175
- `The one exception is the repo that exists to manage it: inside a genuine ` +
176
- `bootstrap-claude checkout (identified by \`${MARKER_FILE}\` plus a package.json ` +
177
- `named \`${MARKER_PACKAGE_NAME}\`, not by directory name) this edit is allowed. ` +
178
- `To change the permission rules, edit \`lib/scripts/templates/settings-deny.json\` ` +
179
- `in the bootstrap-claude repo and re-run \`install-global.sh\`, which merges it in — ` +
180
- `that way the change is reviewable in git instead of being a local mutation nobody sees.`
148
+ `Blocked: editing \`${resolved}\`. This file decides what every agent session is ` +
149
+ `permitted to do, so a write to it is a change to your own permission boundary ` +
150
+ `rather than a change to a project. There is no exception — not even inside the ` +
151
+ `bootstrap-claude repo, which manages these settings through ` +
152
+ `\`install-global.sh\` (a shell subprocess this hook never sees) rather than through ` +
153
+ `the Edit tool. To change the permission rules, edit ` +
154
+ `\`lib/scripts/templates/settings-deny.json\` in the bootstrap-claude repo and re-run ` +
155
+ `\`install-global.sh\`, which merges it in — that way the change is reviewable in git ` +
156
+ `instead of being a local mutation nobody sees.`
181
157
  );
182
158
  }
183
159
 
@@ -216,20 +192,14 @@ readHookInput(data => {
216
192
  // Relative paths resolve against the session's directory, not this process's.
217
193
  const baseDir = typeof data.cwd === 'string' && data.cwd ? data.cwd : process.cwd();
218
194
 
219
- // Resolved once and reused: the walk touches the filesystem, and it is the
220
- // same answer for every target in a MultiEdit batch.
221
- let bootstrapRoot;
222
-
223
195
  for (const target of targets) {
224
196
  const resolved = realpathBestEffort(path.resolve(baseDir, expandHome(target, HOME)));
225
197
  const kind = classify(resolved);
226
198
  if (!kind) continue;
227
199
 
228
- if (kind === 'hooks') deny(reasonForHooks(resolved));
229
-
230
- if (bootstrapRoot === undefined) bootstrapRoot = findBootstrapRoot(baseDir);
231
- if (bootstrapRoot) continue; // the deliberate carve-out — see RESIDUAL RISK above
232
-
233
- deny(reasonForSettings(resolved));
200
+ // Both kinds block unconditionally. There is no cwd-dependent branch here
201
+ // any more — see the header for why the bootstrap-claude carve-out was
202
+ // removed rather than narrowed.
203
+ deny(kind === 'hooks' ? reasonForHooks(resolved) : reasonForSettings(resolved));
234
204
  }
235
205
  });