@codewizard-dt/bootstrap 2.15.0 → 2.17.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.
@@ -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
 
@@ -54,7 +58,7 @@ environment assignment, or on the far side of an MCP tool boundary.
54
58
  | `package-install-consent.js` | `Bash` | Every package-manager install, with one allowlisted source (Serena) |
55
59
  | `absolute-path-guard.js` | `Bash` | Evasive *spellings* of destructive commands (`/bin/rm`, `\rm`, `env rm`) |
56
60
  | `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) |
61
+ | `claude-settings-guard.js` | `Edit\|Write\|NotebookEdit\|MultiEdit` | File-tool writes to `~/.claude/settings*.json` and `~/.claude/hooks/**` — unconditional, no exceptions |
58
62
  | `env-content-read-guard.js` | `Bash\|mcp__serena__.*\|mcp__plugin_[^_]+_serena__.*` | `.env` *contents* reaching the transcript, on both the Bash and Serena surfaces |
59
63
 
60
64
  They share `lib/command-parse.js` (stdin read, segment split, tokenize, deny
@@ -352,10 +356,28 @@ protected paths (`echo … >> ~/.claude/settings.json`) is
352
356
  `protected-write-guard.js` rule 1.
353
357
 
354
358
  **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
-
359
+ `~/.claude/settings.json`, `~/.claude/settings.local.json`, and anything under
360
+ `~/.claude/hooks/`. **Unconditional — the verdict does not depend on cwd.**
361
+
362
+ > **A bootstrap-claude carve-out existed here and was removed on 2026-07-30.**
363
+ > It allowed the settings write when the session's cwd sat inside a genuine
364
+ > checkout, identified by marker file (`lib/scripts/templates/settings-deny.json`
365
+ > plus a `package.json` named `@codewizard-dt/bootstrap`) rather than by directory
366
+ > name. The rationale was that this repo manages those files.
367
+ >
368
+ > **That rationale was wrong.** The repo writes them through
369
+ > `node merge-settings-deny.js` (and now `merge-settings-hooks.js`) *inside*
370
+ > `install-global.sh` — Bash subprocesses that no `PreToolUse` hook and no
371
+ > permission rule ever observes. Nothing here
372
+ > ever needed the Edit *tool* on those paths. The exception was not load-bearing,
373
+ > and it did let any agent running in this repo rewrite its own permission
374
+ > boundary — which was demonstrated live before it was closed.
375
+ >
376
+ > The former marker shapes are still exercised in
377
+ > `test/command-class-hooks.test.js`, now asserting **deny**, because they are the
378
+ > most sensitive canaries for the carve-out creeping back.
379
+
380
+ <!-- superseded, retained for provenance:
359
381
  **A checkout is identified by marker file, not by path substring.**
360
382
  `cwd.includes('bootstrap-claude')` is spoofed by `mkdir bootstrap-claude`, so
361
383
  both of these must hold at a candidate root: `lib/scripts/templates/settings-deny.json`
@@ -375,6 +397,18 @@ deny made the repo unable to work on itself. A hook is the only layer that can
375
397
  carry a conditional. The shipped deny list carries zero `.claude/settings`
376
398
  entries today and `test/settings-deny.test.js` locks that in, so the carve-out is
377
399
  live rather than dead on arrival.
400
+ -->
401
+
402
+ **The deny entries stay out, and that is now a free choice rather than a forced one.**
403
+ `Edit(~/.claude/settings.json)` and `Edit(~/.claude/settings.local.json)` were
404
+ removed from `settings-deny.json` to make the carve-out expressible — deny beats
405
+ allow at every scope, and a hook cannot loosen a deny rule, so the exception was
406
+ unsayable while they existed. With the carve-out gone they could be restored as
407
+ defence in depth. They have not been, deliberately: the deny merge is
408
+ additive-only with **no removal path**, so re-adding them is permanent for every
409
+ installed user, and the hook already blocks the same surface *plus* the `Write`
410
+ and `NotebookEdit` tools that `Edit(...)` rules never reach. Restore them only if
411
+ the hook proves unreliable.
378
412
 
379
413
  **Why the `~/.claude/hooks/` tree is also checked here, and is not duplication.** The
380
414
  `Edit(~/.claude/hooks/**)` and `Edit(**/.claude/hooks/**)` deny entries remain in
@@ -395,13 +429,18 @@ same function so both sides of the comparison are real paths, and a literal `~`
395
429
  `NotebookEdit` names its target `notebook_path`; `MultiEdit` is checked per
396
430
  `edits[].file_path`, so a protected target cannot ride along in a batch.
397
431
 
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.
432
+ **Residual risk, stated plainly.** This hook guards the file *tools*. An agent
433
+ with Bash can still reach these files another way — `node write-settings.js`
434
+ gets there, and nothing here parses inside a script file.
435
+ `protected-write-guard.js` catches shell redirects
436
+ (`echo … >> ~/.claude/settings.json`) and `interpreter-indirection-guard.js`
437
+ catches `node -e`, but a script written to disk and then executed is uncovered by
438
+ design.
439
+
440
+ So this is a guardrail, not a boundary: it closes the casual and accidental paths
441
+ — which is most of them — and raises the cost of the deliberate one. The only
442
+ real containment for a compromised agent is OS-level sandboxing (`/sandbox`).
443
+ Do not read "unconditional" as "guaranteed".
405
444
 
406
445
  **Not covered, deliberately:** project-level `.claude/settings.json` files (this
407
446
  hook is scoped to the user-global `~/.claude/` tree); and writing a script
@@ -683,164 +722,38 @@ acquirer rather than blocking on it.
683
722
 
684
723
  ## Required `~/.claude/settings.json` wiring
685
724
 
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
- ```
725
+ The canonical wiring — which script runs on which event, under which matcher —
726
+ lives in exactly one place:
727
+ [`lib/scripts/templates/settings-hooks.json`](../scripts/templates/settings-hooks.json).
728
+ It is a bare hooks-value object (four events: `SessionStart`, `PreToolUse`,
729
+ `PostToolUse`, `PostToolUseFailure`) whose entries map 1:1 onto the scripts in
730
+ this directory. This README deliberately does not inline a copy: the template
731
+ file is what `merge-settings-hooks.js` reads and merges into the `hooks` key of
732
+ `~/.claude/settings.json` on every `install` / `setup` / `update` run, so a
733
+ second copy here could only drift from what actually ships.
734
+
735
+ Merge semantics — "the template owns its blocks":
736
+
737
+ - **Foreign (user-added) blocks and hook entries are never modified, reordered,
738
+ or removed.** The same goes for entire hooks events the template does not ship
739
+ (e.g. `UserPromptSubmit`): the merge never visits them. A repo hook found
740
+ relocated into a user-modified block is left where it is (with a warning), not
741
+ duplicated back into the template's block, and the merge never writes an empty
742
+ placeholder block. It always exits 0 — a wiring merge must never abort an
743
+ install.
744
+ - **Direct edits to an *owned* entry are overwritten on the next run.** An entry
745
+ is owned when its `command` points at `~/.claude/hooks/<name>.js` (or an
746
+ absolute-path expansion of it) and `<name>` matches a hook the template ships.
747
+ Because the template owns its blocks, any local tweak to such an entry — and
748
+ any matcher drift on a block made up entirely of owned entries — is reverted
749
+ to the template's version the next time `install` / `setup` / `update` runs.
750
+ To opt an entry out of the overwrite, point its `command` at a different path
751
+ (e.g. a copy of the script outside `~/.claude/hooks/`) so it no longer
752
+ classifies as owned; the merge will then treat it as foreign and leave it
753
+ alone. Note the limit of that opt-out: because the re-pointed entry no longer
754
+ carries the template basename, the next merge run re-appends the stock
755
+ template entry alongside it — your variant is preserved, but the shipped hook
756
+ is not disabled.
844
757
 
845
758
  Three notes on the command-class guard matchers, each of which makes a hook
846
759
  silently inert if it is wrong:
@@ -863,13 +776,16 @@ silently inert if it is wrong:
863
776
  permission-matcher path that lets compound and piped commands slip past a `deny`
864
777
  rule.
865
778
 
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.
779
+ Reminder: `install-global.sh` rsyncs these scripts to `~/.claude/hooks/` on
780
+ every run **and** registers them, by running `merge-settings-hooks.js` right
781
+ after the deny-list merge. There is no one-time manual step: the wiring is
782
+ re-merged automatically on every `install` / `setup` / `update` run, and when
783
+ that merge creates the wiring fresh or applies changes, the install prints a
784
+ note to restart your Claude Code sessions (hooks load at session start, so a
785
+ running session does not pick up new wiring).
870
786
 
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
787
+ The template's `PostToolUse` matcher is broadened from the six navigation tools
788
+ to **all** Serena tools so every call feeds health tracking; the tracker gates the read-guard
873
789
  nav counters internally (only the six nav/exploration tools advance the gate, as
874
790
  before). The `PostToolUseFailure` block points at the same script — see
875
791
  [Health tracking & fail-open enforcement](#health-tracking--fail-open-enforcement)
@@ -894,4 +810,5 @@ Two documented caveats on those deny rules:
894
810
  matching call even when a narrower `allow` rule also matches. So
895
811
  `Bash(git stash:*)` also blocks read-only `git stash list`.
896
812
 
897
- Hooks load at session start, so restart any running session after wiring.
813
+ Hooks load at session start, so restart any running session after an install
814
+ run that created or changed the wiring.
@@ -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
@@ -68,12 +77,6 @@ const os = require('os');
68
77
  const path = require('path');
69
78
  const { readHookInput, deny } = require('./lib/command-parse');
70
79
 
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
80
  // Upper bound on any parent walk. path.dirname() is purely lexical and reaches
78
81
  // a fixed point at the filesystem root, so this is belt-and-braces against a
79
82
  // pathological input rather than a real loop risk — but a hook must never hang.
@@ -135,49 +138,17 @@ function classify(resolved) {
135
138
  return null;
136
139
  }
137
140
 
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
141
  function reasonForSettings(resolved) {
171
142
  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.`
143
+ `Blocked: editing \`${resolved}\`. This file decides what every agent session is ` +
144
+ `permitted to do, so a write to it is a change to your own permission boundary ` +
145
+ `rather than a change to a project. There is no exception — not even inside the ` +
146
+ `bootstrap-claude repo, which manages these settings through ` +
147
+ `\`install-global.sh\` (a shell subprocess this hook never sees) rather than through ` +
148
+ `the Edit tool. To change the permission rules, edit ` +
149
+ `\`lib/scripts/templates/settings-deny.json\` in the bootstrap-claude repo and re-run ` +
150
+ `\`install-global.sh\`, which merges it in — that way the change is reviewable in git ` +
151
+ `instead of being a local mutation nobody sees.`
181
152
  );
182
153
  }
183
154
 
@@ -216,20 +187,14 @@ readHookInput(data => {
216
187
  // Relative paths resolve against the session's directory, not this process's.
217
188
  const baseDir = typeof data.cwd === 'string' && data.cwd ? data.cwd : process.cwd();
218
189
 
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
190
  for (const target of targets) {
224
191
  const resolved = realpathBestEffort(path.resolve(baseDir, expandHome(target, HOME)));
225
192
  const kind = classify(resolved);
226
193
  if (!kind) continue;
227
194
 
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));
195
+ // Both kinds block unconditionally. There is no cwd-dependent branch here
196
+ // any more — see the header for why the bootstrap-claude carve-out was
197
+ // removed rather than narrowed.
198
+ deny(kind === 'hooks' ? reasonForHooks(resolved) : reasonForSettings(resolved));
234
199
  }
235
200
  });
@@ -8,9 +8,9 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
8
8
 
9
9
  | Script | `bootstrap` command | What it does |
10
10
  |--------|---------------------|---------------|
11
- | `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: MCP install (interactive), global skills/hooks install, wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap. Does **not** scaffold deployment — that's explicit via `deploy`. |
12
- | `update-project.sh` | `update` | Re-installs global skills/hooks and re-syncs the wiki scaffold + tiered `wiki/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
13
- | `install-global.sh` | `install` | Installs/updates MCPs, hooks, and skills globally with **no project path** — the shared step both `setup` and `update` delegate to. Also prunes stale skill folders left over from the wiki rename (`adr-*` → `decision-*`, `prd-*` → `req-*`), and merges the canonical permission deny list into `~/.claude/settings.json` via `merge-settings-deny.js`. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (same script, `--set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. Accepts `--skip-mcps` when the caller already handled MCP install interactively. |
11
+ | `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: global hooks/skills/settings install first (offline-safe, via `install-global.sh --skip-mcps` — includes the deny-list and hooks-wiring merges), then the interactive MCP install (guarded — a failure warns and continues), wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap. Does **not** scaffold deployment — that's explicit via `deploy`. |
12
+ | `update-project.sh` | `update` | Re-runs the same shared sequence as `setup` (global hooks/skills/settings via `install-global.sh --skip-mcps`, then the guarded interactive MCP install) and re-syncs the wiki scaffold + tiered `wiki/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
13
+ | `install-global.sh` | `install` | Installs/updates hooks, skills, settings, and MCPs globally with **no project path** — the shared step both `setup` and `update` delegate to. Local/offline-safe steps run first: hooks rsync to `~/.claude/hooks/` (stderr warning if `lib/hooks` is missing), skills install (pruning stale skill folders from the wiki rename — `adr-*` → `decision-*`, `prd-*` → `req-*`), the canonical permission deny-list merge into `~/.claude/settings.json` via `merge-settings-deny.js`, then the hooks-wiring merge via `merge-settings-hooks.js` — registering the copied hook scripts in the settings `hooks` key, with a restart-your-session reminder when the wiring was created or changed. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (`merge-settings-deny.js --set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. MCPs install **last** — the only network-dependent step, guarded so a failure warns instead of aborting the local installs — and `--skip-mcps` skips them when the caller already handled MCP install interactively. |
14
14
  | `setup-deployment.sh` | `deploy` / `deployment` | Reads `raw/guides/deployment-strategy.md` as a prompt template, copies it into the target's `wiki/guides/` (deploy-only guide tier — the wiki sync never ships it), and runs `claude` to scaffold `.github/workflows/`, `Makefile` Docker targets, and `.gitleaks.toml` into the target project. Deliberately **not** called by `setup`/`update` — CI files get hand-customized per project (Dockerfile paths, runner labels, deploy steps) and must never be created or clobbered implicitly. `security.yml` is always overwritten (generic); `build.yml`/`.gitleaks.toml` are copy-once; `Makefile` targets are merged. |
15
15
  | `migrate-project.sh` | `migrate` | Claude-driven migration of a legacy `.docs/`-layout project to the LLM Wiki structure (`wiki/knowledge/` + `wiki/work/`). Preflight requires a clean git tree; runs on a fresh `wiki-migration` branch so the whole migration is one reviewable diff. Scaffolds first via `sync-wiki-scaffold.sh --interactive`, assembles `wiki/guides/mcp-tools.md` via `build-mcp-guide.sh`, then drives the semantic conversion (frontmatter synthesis, ID renames, link rewrites, family indexes) with the prompt at `lib/prompts/migrate-wiki.md`. `git mv` before edit, so history is preserved. `--dry-run` prints the file inventory only and does not touch anything. |
16
16
  | `setup-strict-typechecks.sh` | `typechecks` | Loads `lib/prompts/setup-strict-typechecks.md`, appends an optional language list (space- or comma-separated), and runs `claude` to detect languages, research current strict-mode conventions, install toolchains, and wire `make typecheck`. |
@@ -20,13 +20,14 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
20
20
 
21
21
  | Script | Used by | Purpose |
22
22
  |--------|---------|---------|
23
- | `lib.sh` | Every script above | Shared bash library: `resolve_project_dir` (path resolution + validation), `mcp_installed`/`serena_installed`/`detect_installed_mcps` (MCP state checks), `run_project_sync` (the common setup/update sequence: MCPs → skills/hooks → wiki scaffold → gitignore → Serena), and `prompt_yn`/`prompt_scope` (interactive prompt helpers). |
23
+ | `lib.sh` | Every script above | Shared bash library: `resolve_project_dir` (path resolution + validation), `mcp_installed`/`serena_installed`/`detect_installed_mcps` (MCP state checks), `run_project_sync` (the common setup/update sequence: `install-global.sh --skip-mcps` first — hooks/skills/deny-list/hooks-wiring/fileSuggestion, offline-safe — then the guarded interactive MCP install, wiki scaffold, gitignore, MCP-tools guide, Serena bootstrap), and `prompt_yn`/`prompt_scope` (interactive prompt helpers). |
24
24
  | `install-mcps.sh` | `install-global.sh`, `setup-project.sh`, `update-project.sh` | Installs Brave Search, Context7, Playwright, and (when a project dir is given) Serena. Two modes: non-interactive (`install-global.sh`'s default — installs everything missing at user scope) and `--interactive --project-dir <dir>` (prompts per-MCP and asks for scope, used by `setup`/`update`). Playwright has a dedicated conflict flow: registered as `playwright` (user scope) by default; when a project ships its own `playwright`, a git-tracked `.mcp.json` is never modified (interactive options: register ours as `playwright-shared` + disable the project entry machine-locally via `disabledMcpjsonServers` in `.claude/settings.local.json` / register alongside / skip), while a machine-local registration can be replaced or kept (ours then uses the alternate name). Non-interactive conflicts are left untouched with a hint. |
25
25
  | `sync-wiki-scaffold.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Scaffolds an **empty** wiki into the target project from `templates/wiki/`: creates `raw/` + all `wiki/` family directories, lifecycle docs, per-family `index.md`, and stub `index.md`/`log.md`. Copy-once for project-owned files; always-refreshes `conventions.md` and `lifecycle.md`. Delivers guides from `raw/guides/` tier-wise into `wiki/guides/`: `command-anti-patterns.md` required (always refreshed); `evals-framework.md` + `type-checking-templates/` optional (`--interactive` prompts on first delivery, sticky refresh once present — legacy `.docs/guides/` presence counts, opt out by deleting); migrates legacy `.docs/guides/` (template-owned files removed or relocated, deprecated `task-spec.md` deleted, empty dirs pruned). Also delivers the `## LLM Wiki` section and `.env` safety policy (copy-once, sentinel-guarded, from `templates/CLAUDE-wiki.md` / `templates/CLAUDE-env-safety.md`) into the target's `CLAUDE.md` — when a `CLAUDE.md` already exists without the schema, prompts whether to modify it or write `CLAUDE.local.md` instead (non-interactive default: `CLAUDE.local.md`). |
26
26
  | `build-mcp-guide.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Assembles `wiki/guides/mcp-tools.md` in the target project from the per-server stub files in `templates/guides/stubs/`, including only the sections for MCPs actually installed. |
27
27
  | `bootstrap-serena.sh` | `setup-project.sh`, `update-project.sh` | Headlessly triggers `.serena/project.yml` creation via `claude --print` and enables the optional Serena tools needed by this template's workflow. Preflights `claude` and `python3`. |
28
28
  | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Fully interactive `.gitignore` merge — **nothing is ever added without asking**. The packaged template's titled sections are offered one by one (`Add/update .gitignore section '<title>' (N new line(s))? [y/N]`); sections with nothing new are skipped silently. Non-interactive runs (or no tty) change nothing at all. Never touches existing project content. Also offers (git repos only) to keep `.serena/`/`raw/`/`wiki/` out of git via **`.git/info/exclude`** — never `.gitignore`, which would blind Serena on the wiki (see `wiki/knowledge/concepts/git-ignore-tool-visibility.md`); per-machine and idempotent. `info/exclude` *is* honored by ripgrep-class walkers and the `@` file picker, so the excluded paths are written under a `# bootstrap wiki & agent state (machine-local)` sentinel that the `fileSuggestion` picker installed by `install-global.sh` reads back to restore `@`-autocomplete. |
29
29
  | `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical permission deny list (`templates/settings-deny.json` — `Bash(...)` command patterns plus `Edit(...)`/`Read(...)` file-tool patterns) into `~/.claude/settings.json` `permissions.deny`. Entries are opaque strings, so any rule form the permission system accepts merges unchanged. Additive union only: missing entries are appended, user entries are never removed or reordered, all other settings keys pass through untouched. Atomic write, preserves existing indentation, and always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. A second mode, `--set-key <name> --set-value <json>`, merges a single top-level settings key instead of the deny list (used to register `fileSuggestion`): absent → set; already deep-equal → no-op; present but different → one-line warning and skip, never a clobber. Supplying `--set-key` skips the deny merge entirely; a malformed `--set-value` exits 1, since that is a call-site bug rather than a user's file. |
30
+ | `merge-settings-hooks.js` | `install-global.sh` | Zero-dependency Node sibling of `merge-settings-deny.js` (deliberately not a new mode of it — different, block-and-entry-aware semantics) that merges the canonical hook wiring (`templates/settings-hooks.json`) into the `hooks` key of `~/.claude/settings.json` with a "template owns its blocks" model: repo-owned entries (a `command` under `~/.claude/hooks/` whose basename appears in the template) are created or updated in place; matcher drift on a pure-owned block is adopted (a matcher rename ships without duplicating the block); user/foreign blocks and entries are never modified, reordered, or removed; a repo hook found relocated into a mixed block is warned about but not duplicated; no empty placeholder blocks are ever written. Always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. |
30
31
 
31
32
  ## Standalone infra scripts (not wired to the CLI)
32
33
 
@@ -50,6 +51,7 @@ Static and semi-static assets copied or read by the scripts above — never exec
50
51
  | `templates/gitignore` | `merge-gitignore.sh` | Packed copy of this repo's own `.gitignore` (dotfiles aren't included in npm packages, so it's shipped under a non-dot name and renamed on copy). |
51
52
  | `templates/file-suggestion.sh` | `install-global.sh` | The `fileSuggestion` `@`-autocomplete picker, copied to `~/.claude/file-suggestion.sh`. Reads the picker's stdin JSON `query` with `sed` (no `jq`), lists the project from `rg --files` (falling back to `git ls-files`, then `find`), and re-includes the paths under the `# bootstrap wiki & agent state (machine-local)` sentinel in `.git/info/exclude` — so bootstrap's hidden dirs are suggestible again while a user's other `info/exclude` entries stay hidden. Always exits 0. |
52
53
  | `templates/settings-deny.json` | `merge-settings-deny.js` | The canonical `permissions.deny` list (bare JSON array of rule strings). Covers **both** `Bash(...)` command patterns (destructive disk/system commands, `sudo`, permission footguns, git working-tree/history protections, macOS persistence, credential exfiltration, fetch-and-execute) **and** file-tool path patterns — `Edit(...)` / `Read(...)` — protecting Claude Code's own settings and hooks, shell profiles, git config, and credential stores. Audited against the Claude Code permission-rule docs; merged additively into `~/.claude/settings.json` on every `install`/`setup`/`update`. See [Deny-list notes](#deny-list-notes) for the enforcement model and known costs. |
54
+ | `templates/settings-hooks.json` | `merge-settings-hooks.js` | The canonical hook wiring — a bare hooks-value object (the value of the settings `hooks` key, not a full settings file) covering 4 events (`SessionStart`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`) whose entries map 1:1 onto the 18 hook scripts in `lib/hooks/*.js`. The single source of truth for the wiring merged into `~/.claude/settings.json` on every `install`/`setup`/`update`; each block's matcher is load-bearing (see `lib/hooks/README.md`), which is why the wiring ships as a template instead of being hand-pasted. |
53
55
 
54
56
  ## Deny-list notes
55
57
 
@@ -84,19 +86,25 @@ tool call, and Claude Code hot-reloads both files so such a write takes effect
84
86
  immediately. It matters *most* under `bypassPermissions`, where Claude Code's
85
87
  built-in protection for `.claude` paths is **not** applied.
86
88
 
87
- That protection deliberately lives in a `PreToolUse` hook
88
- (`claude-settings-guard.js`), **not** in this deny list, because it needs an
89
- exception a deny rule cannot express: **this repo manages `~/.claude/settings.json`
90
- itself** — that is exactly what `install-global.sh` and `merge-settings-deny.js`
91
- do. A blanket `Edit(~/.claude/settings.json)` deny left bootstrap-claude unable to
92
- work on itself, and no allow rule or hook could carve a way back in: deny beats
93
- allow at every scope, and a hook returning `allow` cannot loosen a deny rule
94
- either. So the deny entries were removed and the hook took over.
95
-
96
- The guard blocks edits to `~/.claude/settings.json` and `settings.local.json`
97
- outside a bootstrap-claude checkout, and permits them inside one — identifying the
98
- checkout by marker file (`lib/scripts/templates/settings-deny.json` plus a
99
- `package.json` named `@codewizard-dt/bootstrap`), not by path name.
89
+ That protection lives in a `PreToolUse` hook (`claude-settings-guard.js`) rather
90
+ than in this deny list. `claude-settings-guard.js` blocks `Edit`/`Write`/
91
+ `NotebookEdit`/`MultiEdit` on `~/.claude/settings.json` and `settings.local.json`
92
+ **unconditionally** — the verdict does not depend on cwd.
93
+
94
+ *History worth knowing, because the code changed under it:* the deny entries were
95
+ originally removed to make room for a bootstrap-claude carve-out, on the belief
96
+ that this repo needs to edit those files. **It does not.** The repo writes them
97
+ through `node merge-settings-deny.js` *inside* `install-global.sh` — a Bash
98
+ subprocess that no hook and no permission rule ever observes. The exception was
99
+ never load-bearing and was removed on 2026-07-30, after it was demonstrated that
100
+ any agent running in this repo could rewrite its own permission boundary with a
101
+ plain `Edit` call.
102
+
103
+ The deny entries stay out, but now by choice rather than necessity: the merge is
104
+ additive-only with **no removal path**, so restoring them is permanent for every
105
+ installed user, and the hook already covers the same paths *plus* the `Write` and
106
+ `NotebookEdit` surfaces that `Edit(...)` rules never reach. Restore them only if
107
+ the hook proves unreliable.
100
108
 
101
109
  **`~/.claude/hooks/**` stays in the deny list with no exception**, including
102
110
  inside this repo. The canonical flow there is to edit `lib/hooks/` and re-run