@codewizard-dt/bootstrap 2.17.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 (39) hide show
  1. package/lib/hooks/README.md +94 -3
  2. package/lib/hooks/absolute-path-guard.js +5 -0
  3. package/lib/hooks/claude-settings-guard.js +5 -0
  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 +296 -1
  20. package/lib/scripts/bootstrap-prefs.js +734 -0
  21. package/lib/scripts/install-global.sh +147 -18
  22. package/lib/scripts/install-mcps.sh +102 -14
  23. package/lib/scripts/lib.sh +581 -11
  24. package/lib/scripts/merge-gitignore.sh +201 -15
  25. package/lib/scripts/sync-wiki-scaffold.sh +33 -4
  26. package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
  27. package/lib/scripts/templates/bootstrap-prefs-schema.json +175 -0
  28. package/lib/scripts/update-project.sh +42 -9
  29. package/lib/skills/README.md +2 -1
  30. package/lib/skills/bootstrap-config/SKILL.md +154 -0
  31. package/lib/skills/git-commit/SKILL.md +54 -1
  32. package/lib/skills/research/SKILL.md +34 -3
  33. package/lib/skills/simplify/SKILL.md +1 -1
  34. package/lib/skills/uat-auto/SKILL.md +9 -4
  35. package/lib/skills/uat-auto-plus/SKILL.md +6 -6
  36. package/lib/skills/uat-generate/SKILL.md +30 -3
  37. package/lib/skills/uat-walk/UAT-CORE.md +41 -6
  38. package/lib/skills/wiki-query/SKILL.md +48 -8
  39. package/package.json +1 -1
@@ -33,6 +33,28 @@
33
33
  *
34
34
  * No network, no MCP runtime introspection, no dependency on Serena being
35
35
  * installed — detection (if used) reads user-level Claude Code config.
36
+ *
37
+ * ── This is a library, not a hook ─────────────────────────────────────────
38
+ * It is never wired in lib/scripts/templates/settings-hooks.json, has no
39
+ * stdin/stdout contract, and must never call process.exit — every consumer is
40
+ * fail-open, and an uncaught throw here would take down a tool call the hook
41
+ * was never meant to gate. Hence the swallowed catches throughout: silent
42
+ * degradation is the correct failure mode for this file specifically.
43
+ *
44
+ * Nine hooks require it (all siblings in ../, installed to ~/.claude/hooks/):
45
+ * serena-first-guard.js Grep symbol detection
46
+ * serena-first-glob-guard.js Glob symbol detection ('glob' dialect)
47
+ * serena-bash-grep-block.js Bash symbol detection ('bash') + paths
48
+ * serena-first-read-guard.js Read state file, gates, isAllowedPath
49
+ * serena-edit-guard.js Edit|MultiEdit isAllowedPath + block copy
50
+ * serena-write-guard.js Write isAllowedPath + block copy
51
+ * serena-usage-tracker.js PostToolUse(+Failure) state file, health
52
+ * serena-session-reset.js SessionStart state file path
53
+ * serena-pre-delegation.js Agent fail-open gate only
54
+ * A behaviour change here lands in all nine at once and there is no way to roll
55
+ * one back independently — which is why the call-site differences are expressed
56
+ * as explicit `opts` (see isCodeSymbol's dialect table) rather than as branches
57
+ * on who is calling.
36
58
  */
37
59
 
38
60
  const fs = require('fs');
@@ -445,6 +467,26 @@ function defaultHealth() {
445
467
  // each other's updates. This fails open by design — a hook that can't get
446
468
  // the lock within budget proceeds unlocked rather than hanging; hooks must
447
469
  // never block indefinitely.
470
+ // Why these three numbers. The critical section is a read, a JSON.parse, an
471
+ // in-memory mutate and an atomic rename — sub-millisecond in practice. A lock
472
+ // still held after LOCK_STALE_MS (750ms) is therefore not contended, it is
473
+ // orphaned by a hook process that died mid-cycle; nothing auto-releases a plain
474
+ // marker file, so without a staleness rule one crash wedges every later state
475
+ // write for the rest of the session. 750ms sits far enough above the real cost
476
+ // that clearing a genuinely live holder takes a pathological stall.
477
+ //
478
+ // LOCK_RETRY_BUDGET_MS (250ms) is the other side of the trade: it caps what a
479
+ // *waiting* hook adds to a tool call it was never meant to slow down. On
480
+ // exhaustion the caller proceeds unlocked and best-effort — a lost counter
481
+ // update is cheap, a PreToolUse hook that hangs is not. Being well under
482
+ // LOCK_STALE_MS means a waiter normally gives up rather than clearing a lock
483
+ // whose holder is merely slow. (Staleness is judged from the lock file's own
484
+ // mtime, not from how long this waiter has waited, so a waiter that arrives late
485
+ // in a stale lock's life still clears it immediately — that is the self-heal
486
+ // working, not a violation of the budget.)
487
+ //
488
+ // The backoff ladder tops out at 80ms, so the budget covers about five wakeups:
489
+ // enough to yield to a real holder, few enough that waiting is never the cost.
448
490
  const LOCK_STALE_MS = 750;
449
491
  const LOCK_RETRY_BUDGET_MS = 250;
450
492
  const LOCK_BACKOFF_MS = [10, 20, 40, 80];
@@ -580,10 +622,30 @@ function classifySerenaFailure(errorPayload) {
580
622
  // Tool-level: the server answered, the query just didn't resolve, or it
581
623
  // declined for a benign/config reason (e.g. the file's language isn't
582
624
  // enabled in .serena/project.yml — a normal, expected response).
625
+ // The alternation is grouped by what Serena's error strings actually say, not
626
+ // by an error taxonomy: query misses ("not found", "no results", "no matching",
627
+ // "no symbol", "could not find"), path misses ("does not exist", "no such
628
+ // file/symbol/path/directory"), the "error at <location>" form emitted for a
629
+ // bad location, and — the group that matters most — the language-config
630
+ // declines ("cannot extract symbols", "active languages", "unsupported
631
+ // language", "no language server"). A file whose language is not enabled in
632
+ // .serena/project.yml fails on EVERY call, so misfiling that group as
633
+ // transport would shell out to pgrep on each one and, the first time the probe
634
+ // came back empty, disable Serena-first enforcement for the whole project on
635
+ // the strength of a perfectly healthy server declining a file type.
583
636
  if (/not found|no results|no matching|no symbol|could not find|error searching|error finding|does not exist|no such (?:file|symbol|path|directory)|error at |cannot extract symbols|active languages|unsupported language|no language server/i.test(s)) {
584
637
  return 'tool';
585
638
  }
586
639
  // Transport-level: the server is unreachable / the pipe broke.
640
+ // Transport-level: nothing in this alternation describes a query, only a pipe.
641
+ // `closed`, `reset` and `connection` are bare because they arrive with no
642
+ // stable prefix ("connection closed", "transport closed", "socket reset").
643
+ //
644
+ // Ordering is load-bearing: a single error string can match both lists
645
+ // ("connection to the language server closed: symbol not found"), and first
646
+ // match wins, so the narrower tool-level test must run first. Swapping the two
647
+ // blocks would route ordinary query misses that merely mention a connection
648
+ // into the health-assessment path.
587
649
  if (/timeout|timed out|connection|refused|econnrefused|socket|epipe|closed|disconnect|not connected|unreachable|reset|broken pipe|hang/i.test(s)) {
588
650
  return 'transport';
589
651
  }
@@ -630,8 +692,43 @@ function isSerenaProcessAlive(projectDir) {
630
692
  // slightly different allowlists — those genuine differences are expressed via
631
693
  // `opts`, so identical inputs yield identical block/allow decisions.
632
694
 
695
+ // Zero-width and bidi formatting characters. They render as nothing, so
696
+ // `create<ZWSP>Order` is visually identical to `createOrder` while every ASCII
697
+ // shape regex below fails to match it — a single pasted character is enough to
698
+ // walk a symbol search past the guards. Stripping is opt-in (`stripZeroWidth`)
699
+ // because the three call sites handle it differently: the Glob guard sets the
700
+ // flag, the Bash guard strips them in its own `clean` callback before tokens
701
+ // ever reach here, and the Grep guard (serena-first-guard.js) does NEITHER.
702
+ //
703
+ // SUSPECTED DEFECT — annotated, deliberately not fixed in this comments-only
704
+ // pass. That third case leaves the exact bypass this constant exists to close
705
+ // still open on the Grep surface: a zero-width character inside a Grep pattern
706
+ // token is neither stripped nor rejected (it is not a regex metacharacter, so
707
+ // rejectRegexSpecials does not catch it). The fix is one option at that call
708
+ // site, but it needs its own regression test rather than riding along here.
633
709
  const SYMBOL_ZERO_WIDTH = /[­​-‏⁠-⁤]/g;
634
710
 
711
+ // Why this list is ~150 entries long, and what earns a place on it. The Glob
712
+ // guard hands over a pattern already shredded into fragments — `src/**/*Modal.tsx`
713
+ // becomes `src`, `Modal`, `tsx` — and by the time a fragment reaches
714
+ // isCodeSymbol there is no context left to distinguish "this was the extension"
715
+ // from "this was a symbol". So every fragment a legitimate file-discovery glob
716
+ // routinely produces has to be named here, or the guard blocks ordinary work:
717
+ // extensions, directory names, file stems, framework/tool config stems, and the
718
+ // directive words people search for. The length is the cost of exact matching;
719
+ // each entry is one word that would otherwise be judged on its shape alone.
720
+ //
721
+ // The bar for adding an entry: the token shows up in globs people write to find
722
+ // files by location or kind, and nobody writes it meaning a symbol. `Modal`
723
+ // fails that test (it is a real component name) and is deliberately absent;
724
+ // `middleware`, `providers`, and `transformers` pass it and are present even
725
+ // though each is also a plausible identifier — because here a false block costs
726
+ // a real search while a false allow costs only a slower route to the same files.
727
+ //
728
+ // Matched lowercased and EXACTLY. Substring matching would exempt `UserService`
729
+ // for containing `service`, which is the entire class of token this guard exists
730
+ // to catch. (`next` and `turbo` appear under two group headings; Set membership
731
+ // makes the duplicate inert.)
635
732
  // Glob guard's exact-match skip set: extensions, common dirs/stems, framework
636
733
  // config names, directives. Checked case-insensitively.
637
734
  const GLOB_SKIP_EXACT = new Set([
@@ -665,6 +762,37 @@ const GLOB_SKIP_EXACT = new Set([
665
762
  'require', 'http', 'https',
666
763
  ]);
667
764
 
765
+ // ── The kebab carve-out (Grep dialect only) ────────────────────────────────
766
+ // A kebab token is normally a filename, not a symbol, and the Glob dialect
767
+ // rejects the shape outright for exactly that reason. The Grep dialect cannot
768
+ // afford to: in a React/Next codebase the component and its file share a name,
769
+ // so a developer greps `user-modal` meaning the component. These three regexes
770
+ // triage that, and they are tested in the order they are declared.
771
+ //
772
+ // KEBAB_TAILWIND_PREFIX — the dominant false positive by volume, and the reason
773
+ // the carve-out needs a reject list at all. A Tailwind project's markup is
774
+ // wall-to-wall `text-sm`, `bg-white`, `hover:bg-gray-100`, `max-w-md`,
775
+ // `data-state` — every one a kebab token of symbol-ish length. Grepping a
776
+ // utility class is a styling search over markup, never a symbol lookup, and
777
+ // Serena has nothing better to offer for it, so these must fall through to Grep
778
+ // or the guard makes CSS work impossible. The list is the Tailwind utility
779
+ // prefix set (spacing, sizing, colour, layout, typography, transition, and the
780
+ // `hover:`/`focus:`/`active:`/`group-` state variants); it is not exhaustive,
781
+ // it stops where class attributes stop.
782
+ //
783
+ // KEBAB_COMPONENT_SUFFIX — the inverse judgement. A kebab token ending in a
784
+ // UI-part noun (`user-modal`, `date-picker`, `nav-bar`, `error-boundary`) names
785
+ // something that exists as a symbol, so Serena can answer for it. The trailing
786
+ // `s?` covers the plural filename convention (`user-cards`). The agent-role tail
787
+ // (`-runner`, `-reviewer`, `-checker`, `-resolver`, `-guard`, `-enforcer`) is
788
+ // not decoration: this repo and the kit it was ported from name their own
789
+ // subagents and hook scripts that way, so it is the local vocabulary and the
790
+ // tokens actually get searched for.
791
+ //
792
+ // KEBAB_DOMAIN_PREFIX — the same call from the other end. A token whose FIRST
793
+ // segment is a code-layer word (`actions-`, `helpers-`, `utils-`, `hooks-`,
794
+ // `types-`, `constants-`, `validations-`, `services-`) is naming code whatever
795
+ // follows it, so the suffix never has to be enumerated.
668
796
  // Guard's tailwind-utility prefixes — kebab tokens starting with these are
669
797
  // styling classes, never symbols.
670
798
  const KEBAB_TAILWIND_PREFIX = /^(text-|bg-|border-|font-|hover:|focus:|active:|group-|ring-|shadow-|rounded-|flex-|grid-|gap-|space-|divide-|overflow-|whitespace-|break-|leading-|tracking-|align-|justify-|items-|self-|order-|col-|row-|transition-|duration-|ease-|animate-|scale-|rotate-|translate-|origin-|cursor-|select-|resize-|appearance-|outline-|decoration-|underline-|line-|placeholder-|caret-|accent-|sr-|z-|opacity-|w-|h-|p-|m-|px-|py-|pt-|pb-|pl-|pr-|mx-|my-|mt-|mb-|ml-|mr-|max-|min-|inset-|top-|right-|bottom-|left-|float-|data-)/;
@@ -685,12 +813,63 @@ const KEBAB_DOMAIN_PREFIX = /^(actions?|helpers?|utils?|hooks?|types?|constants?
685
813
  function isCodeSymbol(raw, opts = {}) {
686
814
  if (raw == null) return false;
687
815
  let s = String(raw);
816
+ // Ordering: strip zero-width first, then measure. Measuring first would let a
817
+ // padded 3-character name clear the floor and then fail every shape test below
818
+ // — allowed, but for the wrong reason, and silently.
819
+ //
820
+ // The 4-character floor and the whitespace reject are the two rules every
821
+ // dialect shares. Below 4 characters the shape tests stop discriminating (`ab`,
822
+ // `x1`, `Foo` are as likely to be prose as code) and find_symbol is not the
823
+ // better tool for such a name anyway. Whitespace means the token is a phrase,
824
+ // and a phrase is a text search — which is precisely what Grep is for.
688
825
  if (opts.stripZeroWidth) s = s.replace(SYMBOL_ZERO_WIDTH, '');
689
826
  if (s.length < 4) return false;
690
827
  if (/\s/.test(s)) return false;
691
828
 
829
+ // Grep dialect only. Its tokens arrive raw, so one still carrying `(`, `[`,
830
+ // `\`, `^`, `$`, `*`, `+`, `?` or `&` is a regex fragment, not a name — and
831
+ // Serena's find_symbol takes a name, not a pattern. Blocking there would trade
832
+ // a working regex search for a tool that cannot express it. The other two
833
+ // dialects never need this: the Bash call site strips the same metacharacters
834
+ // in `clean`, and the Glob splitRe consumes them as delimiters.
692
835
  if (opts.rejectRegexSpecials && /[&?+[\]{}()\\^$*]/.test(s)) return false;
693
836
 
837
+ // ── The three allowlist dialects ─────────────────────────────────────────
838
+ // This is the entire false-positive surface of three hooks, so the differences
839
+ // below are deliberate rather than drift. Every dialect answers one question —
840
+ // "would blocking this token cost the caller a search Serena cannot do?" — for
841
+ // a different input shape:
842
+ //
843
+ // 'guard' serena-first-guard.js (Grep). Tokens are raw pattern fragments,
844
+ // split on `|` and nothing else, so they can still be comment
845
+ // markers, quoted strings, JS keywords, or call syntax. Hence the
846
+ // widest reject list (`^//`, `^#`, `^.`, `^['"` + backtick`]`,
847
+ // `require(`, `console.`, `use client|server`): every one of those
848
+ // is a thing people grep for, and none of them is a symbol name.
849
+ // 'bash' serena-bash-grep-block.js (a grep/rg command line). The call site
850
+ // has already stripped regex metacharacters in its `clean`
851
+ // callback, so the list is shorter — but it adds
852
+ // `^[a-z]+-[a-z]+`, rejecting kebab outright. A shell grep for
853
+ // `user-modal` is usually hunting a filename or a CSS class, and
854
+ // this dialect never sets kebabComponents, so the two agree.
855
+ // 'glob' serena-first-glob-guard.js (a file glob). Tokens are path
856
+ // fragments, so prefix rules do not apply; it uses GLOB_SKIP_EXACT
857
+ // — an exact-match vocabulary of everything a legitimate glob
858
+ // produces — plus a full kebab-filename reject, because inside a
859
+ // glob a kebab token IS a filename.
860
+ //
861
+ // Passing no allowlist (the default) applies none of this: only the shared
862
+ // floors above and the shape tests below. Nothing in this repo calls it that
863
+ // way. It is the honest default for a new call site that has not yet decided
864
+ // what its tokens look like, and it is also the STRICTEST — with no rejects it
865
+ // calls more things symbols and therefore blocks more.
866
+ //
867
+ // Two rules recur in all three lists and carry most of the weight:
868
+ // `^[A-Z_]{3,}$` (SCREAMING_SNAKE is a constant or an env var — grep is the
869
+ // right tool, find_symbol is not) and `^[a-z]{1,8}$` (a short all-lowercase
870
+ // word is too generic to be worth a symbol lookup). `^\d` and `^http` appear
871
+ // in the two prefix-based dialects; the glob dialect covers the same ground by
872
+ // exact match (`http`, `https` are in GLOB_SKIP_EXACT).
694
873
  if (opts.allowlist === 'guard') {
695
874
  const allow = [
696
875
  /^(TODO|FIXME|HACK|XXX|NOTE)/i,
@@ -710,6 +889,12 @@ function isCodeSymbol(raw, opts = {}) {
710
889
  ];
711
890
  if (skip.some(rx => rx.test(s))) return false;
712
891
  } else if (opts.allowlist === 'glob') {
892
+ // Ordering trap: the kebab-filename reject below sits ABOVE the
893
+ // kebabComponents carve-out further down, so a caller passing both
894
+ // `allowlist: 'glob'` and `kebabComponents: true` would never reach the
895
+ // carve-out and every kebab component name would be allowed. No call site
896
+ // does that today — the two options are mutually exclusive by intent, and
897
+ // nothing here enforces it.
713
898
  if (GLOB_SKIP_EXACT.has(s.toLowerCase())) return false;
714
899
  if (/^[a-z]{1,8}$/.test(s)) return false;
715
900
  if (/^[A-Z_]{3,}$/.test(s)) return false;
@@ -717,6 +902,18 @@ function isCodeSymbol(raw, opts = {}) {
717
902
  }
718
903
 
719
904
  // Guard's kebab carve-out: some kebab tokens ARE symbols.
905
+ // Reached only from the Grep dialect — it is the sole call site that sets
906
+ // kebabComponents. The `^[a-z]+-[a-z]/` test scopes the block to lowercase
907
+ // kebab; anything else falls straight through to the shape tests below.
908
+ //
909
+ // Overlaps resolve top-down, and there are real ones: `grid-item` and
910
+ // `text-field` carry a Tailwind prefix *and* a component suffix, and the
911
+ // prefix wins, so they are treated as styling and the Grep is allowed. That
912
+ // error direction is the cheap one — a permitted Grep costs a slower route to
913
+ // the same lines, while a wrong block costs a search Serena cannot perform.
914
+ //
915
+ // The trailing `return false` is the actual policy of this block: an
916
+ // unrecognised kebab token is a filename until proven otherwise.
720
917
  if (opts.kebabComponents && /^[a-z]+-[a-z]/.test(s)) {
721
918
  if (KEBAB_TAILWIND_PREFIX.test(s)) return false;
722
919
  if (KEBAB_COMPONENT_SUFFIX.test(s)) return true;
@@ -724,6 +921,22 @@ function isCodeSymbol(raw, opts = {}) {
724
921
  return false;
725
922
  }
726
923
 
924
+ // The shapes that mean "this is an identifier". What each one is really doing:
925
+ // camelCase requires an interior capital; the `{3,}` bound only restates
926
+ // the shared 4-character floor above.
927
+ // PascalCase requires the *second* character to be a letter, so `S3Client`
928
+ // and `X11Server` are not recognised. That miss is real; no
929
+ // rationale for excluding a digit there is recoverable from the
930
+ // code or the README — verify before relying on it either way.
931
+ // snake_case demands three or more segments AND 9+ characters, because
932
+ // two-segment snake (`user_id`, `my_var`, `is_open`) is far more
933
+ // often a column, a flag, or a variable than a function anyone
934
+ // would navigate to — and blocking those would break routine
935
+ // grepping of SQL and config text.
936
+ // dotted Grep-only (`mcp.Tool`, `router.push`): a module-qualified name.
937
+ // The Bash dialect splits on `.` and the Glob dialect treats it
938
+ // as a path separator, so the raw-token dialect is the only one
939
+ // that can ever see one intact.
727
940
  const isCamelCase = /^[a-z][a-zA-Z0-9]{3,}$/.test(s) && /[A-Z]/.test(s);
728
941
  const isPascalCase = /^[A-Z][a-zA-Z][a-zA-Z0-9]{2,}$/.test(s);
729
942
  const isSnakeCaseFn = /^[a-z]+(_[a-z]+){2,}$/.test(s) && s.length >= 9;
@@ -738,6 +951,21 @@ function isCodeSymbol(raw, opts = {}) {
738
951
  * optionally cleans each token before trimming. Remaining opts are forwarded
739
952
  * to isCodeSymbol.
740
953
  */
954
+ // The tokenizer belongs to the call site, not to this function, because the
955
+ // three pattern syntaxes disagree about what a delimiter is:
956
+ // Grep splitRe '|' regex alternation and nothing else; a dot
957
+ // stays inside the token (see dottedSymbol).
958
+ // Bash splitRe /\\?\||\./ alternation plus dots — a shell grep pattern
959
+ // keeps `mcp.Tool` as one token, and the
960
+ // call site's `clean` strips the dot, which
961
+ // would manufacture `mcpTool`, a camelCase
962
+ // false positive out of thin air.
963
+ // Glob splitRe /[*/.\\{}...]+/ all punctuation — a glob is a path, and its
964
+ // punctuation is structure, not content.
965
+ // Choosing wrong does not fail loudly: it silently changes which tokens exist,
966
+ // and therefore which searches get blocked. `opts` is forwarded whole to
967
+ // isCodeSymbol, so a call site's splitRe and its dialect must be picked together
968
+ // — see the dialect table in isCodeSymbol.
741
969
  function extractSymbolsFromPattern(pattern, opts = {}) {
742
970
  const p = String(pattern ?? '');
743
971
  const splitRe = opts.splitRe || '|';
@@ -1,9 +1,35 @@
1
1
  #!/usr/bin/env node
2
2
  'use strict';
3
3
 
4
- // mv-absolute-path-block.js — PreToolUse hook (matcher: Bash, if: Bash(mv *))
5
- // Blocks `mv` commands where any argument is an absolute path rooted outside
6
- // the project directory. Directs the user to check the project root.
4
+ /**
5
+ * mv-absolute-path-block.js — PreToolUse / Bash (wiring adds `if: Bash(mv *)`)
6
+ *
7
+ * Blocks: an `mv` with an absolute-path argument rooted outside the hook's idea
8
+ * of the project root (see BUG-0005 below — that idea is not the session's) —
9
+ * the "I thought I was somewhere else" move that lands a file in /etc, /usr,
10
+ * or a neighbouring repo.
11
+ * Why a hook: whether an absolute path is acceptable depends on where the
12
+ * project root is, and a settings.json pattern cannot see the project root.
13
+ * Denying every absolute-path mv would deny the legitimate in-project ones
14
+ * too, and enumerating the roots worth protecting is precisely the unbounded
15
+ * list a hook exists to replace. The verdict also has to arrive as a
16
+ * CORRECTION ("check that you are in the project root") rather than a
17
+ * prohibition, and a deny rule cannot carry a message at all.
18
+ * Fails: open — unparseable stdin exits 0 silently at the JSON.parse catch
19
+ * below. A payload that parses to a non-object (`null`) throws on
20
+ * `data.tool_name` and exits non-zero, which Claude Code reads as a
21
+ * NON-blocking hook error: stderr is surfaced and the tool call proceeds
22
+ * anyway. Both paths allow. This file does not use lib/command-parse.js's
23
+ * readHookInput, so there is no handler-level catch; of the hooks in this
24
+ * directory only interpreter-indirection-guard.js genuinely fails closed.
25
+ * False positives: a pipeline is not a segment boundary here, so a later
26
+ * stage's absolute path is attributed to the `mv` —
27
+ * `mv notes.md archive.md | tee /var/log/mvlog.txt` denies a move that is
28
+ * entirely in-project (BUG-0006, annotated at the segment split below) —
29
+ * escape hatch: join with `&&` instead of `|`, which IS a segment boundary,
30
+ * so the `mv` is then judged on its own two operands.
31
+ * See README.md § Safety / policy hooks for the full rationale.
32
+ */
7
33
 
8
34
  const path = require('path');
9
35
 
@@ -18,10 +44,56 @@ process.stdin.on('end', () => {
18
44
  const fullCmd = String(data.tool_input?.command ?? '').trim();
19
45
  if (!fullCmd) process.exit(0);
20
46
 
47
+ // BUG-0005 — UNEXPLAINED DIVERGENCE, annotated here and deliberately not fixed.
48
+ // Every sibling guard that needs a project root reads `data.cwd` off the hook
49
+ // payload and falls back to `process.cwd()` only if it is missing
50
+ // (protected-write-guard.js:189, claude-settings-guard.js:192,
51
+ // interpreter-indirection-guard.js:579, serena-pre-delegation.js:95). This one
52
+ // alone asks node and never looks at the payload. `data.cwd` is the
53
+ // authoritative session cwd Claude Code reports for the tool call;
54
+ // `process.cwd()` is merely wherever the node process running this hook was
55
+ // started. When the two differ the check inverts in BOTH directions: absolute
56
+ // paths that really are in-project stop matching `cwdWithSep` and get denied,
57
+ // while paths under node's cwd but outside the session's project get allowed.
58
+ // No comment, commit message, or test explains the choice, which is why it is
59
+ // filed rather than assumed intentional. Do not swap it in passing — it is a
60
+ // behaviour change to a live shipped control and belongs to BUG-0005.
21
61
  const cwd = process.cwd();
22
62
  const cwdWithSep = cwd + path.sep;
23
63
 
24
64
  // Split on command separators and inspect each segment independently.
65
+ //
66
+ // BUG-0006 — DIVERGENCE, annotated and deliberately not fixed: this list is
67
+ // `;`, `&&`, `||` but NOT `|`, whereas lib/command-parse.js's splitSegments
68
+ // (:48) includes the pipe. Read the next three paragraphs before touching it,
69
+ // because the obvious reading of this gap is wrong.
70
+ //
71
+ // It is NOT a bypass. `args` is `tokens.slice(mvIdx + 1)` and runs to the end
72
+ // of the segment, straight through any `|`, so an absolute path still lands in
73
+ // `args` regardless of which pipeline stage wrote it:
74
+ // echo x | mv /etc/foo /tmp/bar still denies
75
+ // cat mv | mv /etc/x /tmp/y still denies
76
+ //
77
+ // The actual defect is the inverse — FALSE denials. Operands belonging to a
78
+ // later stage are attributed to the `mv`, so a wholly in-project move that
79
+ // merely logs somewhere absolute is refused:
80
+ // mv notes.md archive.md | tee /var/log/mvlog.txt denies, wrongly
81
+ //
82
+ // WARNING TO THE NEXT READER: the tempting fix — anchor the verb at the head
83
+ // of each segment, the way absolute-path-guard.js does — would OPEN the bypass
84
+ // this only looks like it has. With `|` still absent from the split,
85
+ // `echo x | mv /etc/foo /tmp/bar` is one segment headed by `echo`, and an
86
+ // anchored check would stop seeing the `mv` entirely. Adding `|` to the split
87
+ // and anchoring the verb are a single change, not two; either one alone makes
88
+ // this hook strictly worse. That coupling is why it is filed as BUG-0006
89
+ // instead of patched in place.
90
+ //
91
+ // One nuance if you go to reproduce any of the above: the shipped wiring gates
92
+ // this hook behind `if: Bash(mv *)` (settings-hooks.json:104), so only commands
93
+ // whose first token is `mv` reach the file at all. `echo x | mv /etc/foo …` is
94
+ // filtered out upstream and never arrives, while the false-denial case does,
95
+ // because it starts with `mv`. The gate lives in settings-hooks.json, not
96
+ // here, so the logic above still has to stand on its own if it is relaxed.
25
97
  const segments = fullCmd.split(/;|&&|\|\|/).map(s => s.trim()).filter(Boolean);
26
98
 
27
99
  for (const segment of segments) {
@@ -30,6 +102,15 @@ process.stdin.on('end', () => {
30
102
  if (mvIdx === -1) continue;
31
103
 
32
104
  // Arguments after 'mv', skipping flags (-n, -f, -v, etc.)
105
+ //
106
+ // `!t.startsWith('-')` is a heuristic, not getopt, and it is safe in this
107
+ // one direction: every mv flag that takes a value takes a PATH as that value
108
+ // (`-t /etc/cron.d`, `--target-directory=/etc/cron.d`). Dropping the flag
109
+ // therefore leaves its value behind in `args`, still inspected — the naive
110
+ // failure mode where a flag swallows the very path you wanted to check
111
+ // cannot occur here. The cost is the mirror case: a file whose name starts
112
+ // with `-` is skipped. That is free, because such a name cannot also start
113
+ // with `/`, and an absolute path is the only thing this hook blocks.
33
114
  const args = tokens.slice(mvIdx + 1).filter(t => !t.startsWith('-'));
34
115
 
35
116
  const offendingArg = args.find(arg => {
@@ -36,6 +36,11 @@
36
36
  // `npm install -g @playwright/mcp@latest` at the prompt IS gated. Both are
37
37
  // correct: consent was given once for the setup script as a whole; an ad-hoc
38
38
  // install carries no such consent.
39
+ //
40
+ // Fails: open — matching is pure token inspection with no external input, and a
41
+ // throw exits 0 via lib/command-parse.js. The asymmetry that matters here is
42
+ // coverage rather than failure: a manager or invocation form absent from the
43
+ // tables below is allowed, which is also why the scope note above holds.
39
44
 
40
45
  const { readHookInput, splitSegments, tokenize, deny } = require('./lib/command-parse');
41
46
 
@@ -92,6 +97,12 @@ function stripInvocationPrefix(tokens) {
92
97
  // `uvx --from X` fetches and runs X, so it is an install in everything but
93
98
  // name. The flag is located anywhere in the segment rather than at a fixed
94
99
  // position, because `uvx --python 3.12 --from X` is equally valid.
100
+ //
101
+ // NOTE: bare `uvx <pkg>` (no `--from`) returns null here and is therefore
102
+ // ALLOWED, even though it fetches and runs a package by the same reasoning
103
+ // above. Whether that is a deliberate scope choice or an oversight is not
104
+ // recoverable from this file or from lib/hooks/README.md — verify before
105
+ // changing, and do not treat the current behaviour as intentional coverage.
95
106
  function uvxSource(tokens) {
96
107
  for (let i = 1; i < tokens.length; i++) {
97
108
  if (tokens[i] === '--from') return tokens[i + 1] ?? '';
@@ -64,6 +64,13 @@
64
64
  // unremarkable but which points into ~/.claude/ is not caught.
65
65
  // - `git --config-env=alias.x=VAR` reads the value from an environment
66
66
  // variable, so the dangerous string never appears in the command. Not covered.
67
+ //
68
+ // Fails: open — all three rules are pure string/path matching over the command
69
+ // itself, with no file read, no subprocess, and no external list, so there is no
70
+ // "could not check" state to fail into. If this hook throws anyway,
71
+ // lib/command-parse.js catches it and exits 0 and the command is allowed.
72
+ // Ambiguous MATCHES go the other way and block — see the inherited false
73
+ // positive above.
67
74
 
68
75
  const path = require('path');
69
76
  const os = require('os');