@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.
- package/lib/hooks/README.md +192 -184
- package/lib/hooks/absolute-path-guard.js +5 -0
- package/lib/hooks/claude-settings-guard.js +43 -73
- package/lib/hooks/env-content-read-guard.js +13 -3
- package/lib/hooks/env-file-guard.js +42 -0
- package/lib/hooks/interpreter-indirection-guard.js +7 -0
- package/lib/hooks/lib/command-parse.js +8 -0
- package/lib/hooks/lib/serena-languages.js +94 -1
- package/lib/hooks/lib/serena.js +228 -0
- package/lib/hooks/mv-absolute-path-block.js +84 -3
- package/lib/hooks/package-install-consent.js +11 -0
- package/lib/hooks/protected-write-guard.js +7 -0
- package/lib/hooks/serena-bash-grep-block.js +507 -44
- package/lib/hooks/serena-first-glob-guard.js +65 -20
- package/lib/hooks/serena-first-guard.js +98 -2
- package/lib/hooks/serena-first-read-guard.js +92 -2
- package/lib/hooks/serena-pre-delegation.js +123 -0
- package/lib/hooks/serena-write-guard.js +56 -3
- package/lib/scripts/README.md +319 -16
- package/lib/scripts/bootstrap-prefs.js +734 -0
- package/lib/scripts/install-global.sh +182 -25
- package/lib/scripts/install-mcps.sh +102 -14
- package/lib/scripts/lib.sh +595 -20
- package/lib/scripts/merge-gitignore.sh +254 -16
- package/lib/scripts/merge-settings-hooks.js +374 -0
- package/lib/scripts/sync-wiki-scaffold.sh +33 -4
- package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
- package/lib/scripts/templates/bootstrap-prefs-schema.json +175 -0
- package/lib/scripts/templates/settings-hooks.json +151 -0
- package/lib/scripts/update-project.sh +42 -9
- package/lib/skills/README.md +2 -1
- package/lib/skills/bootstrap-config/SKILL.md +154 -0
- package/lib/skills/git-commit/SKILL.md +54 -1
- package/lib/skills/research/SKILL.md +34 -3
- package/lib/skills/simplify/SKILL.md +1 -1
- package/lib/skills/uat-auto/SKILL.md +9 -4
- package/lib/skills/uat-auto-plus/SKILL.md +6 -6
- package/lib/skills/uat-generate/SKILL.md +30 -3
- package/lib/skills/uat-walk/UAT-CORE.md +41 -6
- package/lib/skills/wiki-query/SKILL.md +48 -8
- package/package.json +1 -1
package/lib/hooks/README.md
CHANGED
|
@@ -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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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`
|
|
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
|
|
356
|
-
|
|
357
|
-
|
|
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,
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
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
|
-
(`:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
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
|
|
867
|
-
run
|
|
868
|
-
|
|
869
|
-
|
|
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
|
|
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
|
|
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
|
|
20
|
-
//
|
|
21
|
-
//
|
|
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
|
-
//
|
|
24
|
-
//
|
|
25
|
-
//
|
|
26
|
-
//
|
|
27
|
-
//
|
|
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
|
-
//
|
|
50
|
-
//
|
|
51
|
-
//
|
|
52
|
-
//
|
|
53
|
-
//
|
|
54
|
-
//
|
|
55
|
-
//
|
|
56
|
-
//
|
|
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}
|
|
173
|
-
`
|
|
174
|
-
`
|
|
175
|
-
`
|
|
176
|
-
|
|
177
|
-
`
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
`
|
|
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
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
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
|
});
|