vigiles 41.2.0 → 41.3.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.
@@ -315,6 +315,18 @@ export declare function trimTrailingSeparators(path: string): string;
315
315
  * repo's `notes`; without one it can only be over-blocked.
316
316
  */
317
317
  export declare function commandView(raw: string, root?: string): CommandView;
318
+ /**
319
+ * The shell tool's name in a hook payload — the one spelling, shared by the Bash
320
+ * gate and the Bash react. A payload-vocabulary fact rather than a per-harness
321
+ * one: Claude Code sends `Bash`, and Codex's hooks docs (read 2026-11-17) say its
322
+ * shell commands, unified exec included, arrive "as `Bash`" too. Not read from
323
+ * the adapter on purpose: resolving it costs the ~280 ms adapter-registry load
324
+ * that `hook-runtime.ts` keeps off every gate path. ⚠️ No real Codex payload has
325
+ * been captured to confirm the docs; the Codex delivery fixture in this repo
326
+ * spells the tool `shell`, Codex's MODEL-facing name. Revisit with a port field
327
+ * if a harness's payload diverges.
328
+ */
329
+ export declare const SHELL_TOOL = "Bash";
318
330
  /**
319
331
  * The typed event a Bash gate decides over. Generic over the declared context
320
332
  * `needs` (`N`) so `e.ctx` exposes ONLY the facts the hook declared — reading an
@@ -444,7 +456,14 @@ export interface CompileHookOptions {
444
456
  * (they never trust this type). Author-facing types keep the precise `N`.
445
457
  */
446
458
  type ErasedNeeds = readonly any[];
447
- export type AnyHook = HookProgram<ErasedNeeds> | FileGateHook<ErasedNeeds> | PromptGateHook<ErasedNeeds> | StopGateHook<ErasedNeeds> | InjectHook<ErasedNeeds> | ReactHook<ErasedNeeds>;
459
+ /**
460
+ * The ERASED declared-tools generic, for the same reason: a react's `react` is
461
+ * contravariant in `T`. With `any`, the union's react event is the widest shape
462
+ * (the Bash one, which every narrower react event accepts), so a Bash-only, an
463
+ * Edit-only and a tool-less react all assign.
464
+ */
465
+ type ErasedTools = readonly any[];
466
+ export type AnyHook = HookProgram<ErasedNeeds> | FileGateHook<ErasedNeeds> | PromptGateHook<ErasedNeeds> | StopGateHook<ErasedNeeds> | InjectHook<ErasedNeeds> | ReactHook<ErasedNeeds, ErasedTools>;
448
467
  /**
449
468
  * The runtime dispatch shapes. A bare {@link HookProgram} (no `role`) is a Bash
450
469
  * command gate; the role-keyed hooks carry their own shape. The runtime uses this
@@ -673,8 +692,13 @@ export interface FileGateHook<N extends readonly NeedSpec[] = readonly ProviderN
673
692
  readonly needs?: N;
674
693
  readonly decide: (e: FileToolEvent<N>) => Decision;
675
694
  }
676
- export declare const tools: (...names: string[]) => {
677
- tools: string[];
695
+ /**
696
+ * Declare the tools a hook matches: `match: tools("Edit", "Write")`. The names
697
+ * keep their LITERAL types, which is how a react declared with `tools("Bash")`
698
+ * alone is known to carry `e.command`.
699
+ */
700
+ export declare const tools: <const T extends readonly string[]>(...names: T) => {
701
+ readonly tools: T;
678
702
  };
679
703
  /**
680
704
  * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
@@ -851,16 +875,54 @@ export interface ResponseView {
851
875
  contains(needle: string): boolean;
852
876
  }
853
877
  export declare function responseView(raw: unknown): ResponseView;
854
- /** The event a react hook reacts over — the tool, the file path, AND its response. */
855
- export interface ReactEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
878
+ /**
879
+ * The event of a react that is NOT declared for the shell tool alone — other
880
+ * tools, a mixed list, a pattern, or a tool-less event. It has NO `command`
881
+ * property at all (not an optional one), so `e.command?.runs(…)`, which would be
882
+ * silently false forever, cannot be written either.
883
+ */
884
+ export interface ToolReactEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
885
+ /** The event the hook is registered on (`PostToolUse`, `Stop`, …). */
856
886
  readonly event: string;
887
+ /** The tool the event is about; `""` on a tool-less event. */
857
888
  readonly tool: string;
889
+ /** The event's `tool_input.file_path`, as a path view (`""` when absent). */
858
890
  readonly path: PathView;
859
891
  /** The tool's response (PostToolUse) — react only on an error, capture output, … */
860
892
  readonly response: ResponseView;
861
893
  /** Host-gathered, DECLARED facts — built-ins, inline providers, and `state()` reads. */
862
894
  readonly ctx: HookCtx<N>;
863
895
  }
896
+ /**
897
+ * The event of a react declared for the shell tool ALONE (`match: tools("Bash")`):
898
+ * everything a {@link ToolReactEvent} carries, plus the command it reacts to.
899
+ */
900
+ export interface BashReactEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> extends ToolReactEvent<N> {
901
+ /** Always `"Bash"`: comparing it with another tool name is a type error. */
902
+ readonly tool: "Bash";
903
+ /**
904
+ * The command that ran, as the same AST-backed {@link CommandView} a Bash gate
905
+ * decides over, built by the same constructor. It parses on the first
906
+ * predicate call, so a react that never asks costs no parse.
907
+ */
908
+ readonly command: CommandView;
909
+ }
910
+ /**
911
+ * Shell-only iff the declared list is non-empty and every entry is exactly the
912
+ * shell tool's name. A pattern (`"Ba.*"`), a mixed list, an empty or a widened
913
+ * `string[]` are not: the command is a fact about ONE tool, so a hook that wants
914
+ * it for Bash and something else is two hooks.
915
+ */
916
+ type DeclaresOnlyShell<T extends readonly string[]> = [T[number]] extends [
917
+ never
918
+ ] ? false : [T[number]] extends [typeof SHELL_TOOL] ? true : false;
919
+ /**
920
+ * The event a react hook reacts over — the tool, the file path, its response,
921
+ * and, for a react declared for Bash alone, the command. `T` is the declared
922
+ * `match.tools`; the default (`readonly string[]`) is the shape every react had
923
+ * before the command existed, so `ReactEvent<N>` keeps meaning what it meant.
924
+ */
925
+ export type ReactEvent<N extends readonly NeedSpec[] = readonly ProviderName[], T extends readonly string[] = readonly string[]> = DeclaresOnlyShell<T> extends true ? BashReactEvent<N> : ToolReactEvent<N>;
864
926
  export interface RunReaction {
865
927
  readonly kind: "run";
866
928
  readonly command: string;
@@ -893,7 +955,7 @@ export declare const notice: (message: string, ...records: readonly StateWrite[]
893
955
  * (an MCP call, a deploy) so a different hook can read it later.
894
956
  */
895
957
  export declare const nothing: (...records: readonly StateWrite[]) => Reaction;
896
- export interface ReactHook<N extends readonly NeedSpec[] = readonly ProviderName[]> {
958
+ export interface ReactHook<N extends readonly NeedSpec[] = readonly ProviderName[], T extends readonly string[] = readonly string[]> {
897
959
  readonly role: "react";
898
960
  readonly on: string;
899
961
  /**
@@ -910,12 +972,15 @@ export interface ReactHook<N extends readonly NeedSpec[] = readonly ProviderName
910
972
  * this feature was built for are `Stop` nudges.
911
973
  */
912
974
  readonly match?: {
913
- readonly tools: readonly string[];
975
+ readonly tools: T;
914
976
  };
915
977
  /** Declared context providers the trusted runtime gathers into `e.ctx`. */
916
978
  readonly needs?: N;
917
- /** Reacts to a tool that already ran. Returns a Reaction — NO `deny` exists here. */
918
- readonly react: (e: ReactEvent<N>) => Reaction;
979
+ /**
980
+ * Reacts to a tool call. Returns a Reaction — NO `deny` exists here. Declared
981
+ * for Bash alone, `e.command` is the command that ran.
982
+ */
983
+ readonly react: (e: ReactEvent<N, T>) => Reaction;
919
984
  }
920
985
  /**
921
986
  * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
@@ -924,7 +989,7 @@ export interface ReactHook<N extends readonly NeedSpec[] = readonly ProviderName
924
989
  * at 0 of 5 call sites in the only user-facing example, because a reader 200
925
990
  * lines down sees `defineReact` without it and cannot tell it is provisional.
926
991
  */
927
- export declare function experimental_defineReact<const N extends readonly NeedSpec[] = readonly []>(p: Omit<ReactHook<N>, "role">): ReactHook<N>;
992
+ export declare function experimental_defineReact<const N extends readonly NeedSpec[] = readonly [], const T extends readonly string[] = readonly []>(p: Omit<ReactHook<N, T>, "role">): ReactHook<N, T>;
928
993
  /**
929
994
  * Run a react hook against a raw PostToolUse event → the (classified) Reaction.
930
995
  *
@@ -933,10 +998,11 @@ export declare function experimental_defineReact<const N extends readonly NeedSp
933
998
  * trails `ctx` so the argument order matches {@link decideProgram} and
934
999
  * {@link decideFileGate} — every decode function reads `(hook, raw, ctx, root)`.
935
1000
  */
936
- export declare function runReact<N extends readonly NeedSpec[]>(hook: ReactHook<N>, raw: {
1001
+ export declare function runReact<N extends readonly NeedSpec[], T extends readonly string[]>(hook: ReactHook<N, T>, raw: {
937
1002
  tool_name?: string;
938
1003
  tool_input?: {
939
1004
  file_path?: unknown;
1005
+ command?: unknown;
940
1006
  };
941
1007
  tool_response?: unknown;
942
1008
  cwd?: unknown;
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.nothing = exports.notice = exports.run = exports.inject = exports.tools = exports.HookCompileError = exports.ask = exports.deny = exports.allow = void 0;
3
+ exports.nothing = exports.notice = exports.run = exports.inject = exports.tools = exports.HookCompileError = exports.SHELL_TOOL = exports.ask = exports.deny = exports.allow = void 0;
4
4
  exports.matchesTool = matchesTool;
5
5
  exports.invalidToolPatterns = invalidToolPatterns;
6
6
  exports.gateAction = gateAction;
@@ -140,6 +140,8 @@ function matchesTool(tools, name) {
140
140
  }
141
141
  /** Regex metacharacters — an entry containing one is a PATTERN, not a name. */
142
142
  const REGEX_META = /[.*+?^${}()|[\]\\]/;
143
+ /** The declared entries that are tool NAMES (no regex metacharacter), not patterns. */
144
+ const literalToolNames = (tools) => tools.filter((t) => !REGEX_META.test(t));
143
145
  /** Tool patterns that are not valid regexes — rejected at compile, see {@link matchesTool}. */
144
146
  function invalidToolPatterns(tools) {
145
147
  return tools.filter((t) => {
@@ -477,19 +479,7 @@ function writeTargetsOf(leaf) {
477
479
  const underChdir = (target, chdir) => chdir === null || target === "" || target.startsWith("~")
478
480
  ? target
479
481
  : resolveRef(chdir, target);
480
- /**
481
- * An AST-backed view of a Bash command.
482
- *
483
- * @param raw - the command line as the tool event carried it.
484
- * @param root - the project root repo-relative prefixes resolve against, from
485
- * the runtime ({@link projectRootOf}: `$CLAUDE_PROJECT_DIR`, else the event's
486
- * own `cwd`, never `process.cwd()`). Omitting it does NOT disarm the denylist
487
- * matchers — without a root an absolute token is `"undecidable"` rather than
488
- * placeable, and {@link CommandView.touches} treats that as a match. It does
489
- * cost precision: with a root, `/somewhere-else/notes/x` is provably not this
490
- * repo's `notes`; without one it can only be over-blocked.
491
- */
492
- function commandView(raw, root) {
482
+ function parseCommand(raw) {
493
483
  const leaves = (0, bash_effects_js_1.leafCommands)(raw);
494
484
  // The operation-normalized leaves carry the redirections (and quote-unwrapped,
495
485
  // wrapper-resolved argv) that `writesTo` needs; `leafCommands` cannot see them.
@@ -505,12 +495,40 @@ function commandView(raw, root) {
505
495
  // `NormalizedLeaf.chdir` for why the value was being read and discarded.
506
496
  ...writeTargetsOf(leaf).map((t) => underChdir(t, leaf.chdir)),
507
497
  ]);
498
+ return { leaves, normalized, allWriteTargets };
499
+ }
500
+ /**
501
+ * An AST-backed view of a Bash command.
502
+ *
503
+ * @param raw - the command line as the tool event carried it.
504
+ * @param root - the project root repo-relative prefixes resolve against, from
505
+ * the runtime ({@link projectRootOf}: `$CLAUDE_PROJECT_DIR`, else the event's
506
+ * own `cwd`, never `process.cwd()`). Omitting it does NOT disarm the denylist
507
+ * matchers — without a root an absolute token is `"undecidable"` rather than
508
+ * placeable, and {@link CommandView.touches} treats that as a match. It does
509
+ * cost precision: with a root, `/somewhere-else/notes/x` is provably not this
510
+ * repo's `notes`; without one it can only be over-blocked.
511
+ */
512
+ function commandView(raw, root) {
513
+ // 🔴 PARSED ON THE FIRST PREDICATE CALL, NOT HERE. Building the view used to
514
+ // parse at once, which was harmless while only a Bash GATE built one — a gate
515
+ // exists to ask about the command. Since #396 (a) a react declared for Bash
516
+ // carries this view too, and most such reacts read only `e.response` ("the
517
+ // command failed"). An eager parse would make every one of them load the shell
518
+ // parser (`mvdan-sh`, ~70–140 ms) on every Bash call for a value it never
519
+ // reads. `src/hook-runtime-graph.test.ts` pins both directions: a Bash react
520
+ // that never asks does not load the parser; one that asks does. Memoized, so a
521
+ // view parses at most once however many predicates a decision calls.
522
+ // eslint-disable-next-line functional/no-let -- the memo cell of a lazy parse; it is written once, on the first predicate call, and never reassigned after
523
+ let parsed;
524
+ const parse = () => (parsed ??= parseCommand(raw));
508
525
  const matchedWriteTargets = (prefixes) => [
509
- ...new Set(allWriteTargets.filter((t) => prefixes.some((p) => matchesPrefix(prefixVerdict(t, p, root), "match")))),
526
+ ...new Set(parse().allWriteTargets.filter((t) => prefixes.some((p) => matchesPrefix(prefixVerdict(t, p, root), "match")))),
510
527
  ];
511
528
  return {
512
529
  raw,
513
530
  runs(program, opts) {
531
+ const { leaves, normalized } = parse();
514
532
  const tokens = program.split(/\s+/).filter(Boolean);
515
533
  // 🔴 READS RAW **AND** NORMALIZED ARGV — the same union `touches` already
516
534
  // uses, and for the same reason. This matcher read only `leaves` (raw), so
@@ -570,25 +588,31 @@ function commandView(raw, root) {
570
588
  // `writesTo` was already correct precisely because it reads `normalized`;
571
589
  // this is the same class as the other siblings this PR keeps finding, so
572
590
  // both denylists now read the SAME argv.
573
- touches: (prefixes) =>
574
- // 🔴 THE UNION IS THE FIX, AND EACH HALF COVERS THE OTHER'S BLIND SPOT.
575
- // Raw argv keeps a word exactly as written, so a QUOTED path arrives as
576
- // `"papers/x.tex"` and matches nothing — measured end-to-end on a shipped
577
- // guard: unquoted exited 2, quoted exited 0. Normalized argv unwraps the
578
- // quotes, but `stripWrappers` also CONSUMES wrapper options, so
579
- // `env -C secrets cat key` loses `secrets` entirely and a denylist on it
580
- // fails open. Reading only one of the two trades one bypass for the other;
581
- // that is exactly what the previous commit did, and it earned a P1.
582
- // A denylist over-matching costs an argument. Missing costs the write.
583
- [...leaves.map((argv) => argv.slice(1)), ...normalized.map((l) => l.args)]
584
- .flat()
585
- // `--chdir=secrets` is ONE token, so the path is invisible to a whole-token
586
- // comparison. Only the tail of an `--opt=value` word can be a path, so the
587
- // extra candidate is added rather than replacing the token.
588
- .flatMap((tok) => /^-{1,2}[^=]+=/.test(tok)
589
- ? [tok, tok.slice(tok.indexOf("=") + 1)]
590
- : [tok])
591
- .some((tok) => prefixes.some((p) => matchesPrefix(prefixVerdict(tok, p, root), "match"))),
591
+ touches: (prefixes) => {
592
+ const { leaves, normalized } = parse();
593
+ return (
594
+ // 🔴 THE UNION IS THE FIX, AND EACH HALF COVERS THE OTHER'S BLIND SPOT.
595
+ // Raw argv keeps a word exactly as written, so a QUOTED path arrives as
596
+ // `"papers/x.tex"` and matches nothing — measured end-to-end on a shipped
597
+ // guard: unquoted exited 2, quoted exited 0. Normalized argv unwraps the
598
+ // quotes, but `stripWrappers` also CONSUMES wrapper options, so
599
+ // `env -C secrets cat key` loses `secrets` entirely and a denylist on it
600
+ // fails open. Reading only one of the two trades one bypass for the other;
601
+ // that is exactly what the previous commit did, and it earned a P1.
602
+ // A denylist over-matching costs an argument. Missing costs the write.
603
+ [
604
+ ...leaves.map((argv) => argv.slice(1)),
605
+ ...normalized.map((l) => l.args),
606
+ ]
607
+ .flat()
608
+ // `--chdir=secrets` is ONE token, so the path is invisible to a whole-token
609
+ // comparison. Only the tail of an `--opt=value` word can be a path, so the
610
+ // extra candidate is added rather than replacing the token.
611
+ .flatMap((tok) => /^-{1,2}[^=]+=/.test(tok)
612
+ ? [tok, tok.slice(tok.indexOf("=") + 1)]
613
+ : [tok])
614
+ .some((tok) => prefixes.some((p) => matchesPrefix(prefixVerdict(tok, p, root), "match"))));
615
+ },
592
616
  // DERIVED, not a second implementation of the same rule. The boolean stays
593
617
  // because `writesTo(secrets) ? deny() : allow()` is the common gate shape,
594
618
  // but it is a PROJECTION of the list — one code path, so the two can never
@@ -600,10 +624,38 @@ function commandView(raw, root) {
600
624
  // pipe-to-shell, and a raw-only check misses both (`isBareShellLeaf` tests
601
625
  // the head literally, and the normalizer is what reduces `/bin/sh`→`sh` and
602
626
  // strips the wrapper).
603
- pipesToShell: () => leaves.some(isBareShellLeaf) ||
604
- normalized.some((leaf) => isBareShellLeaf(leaf.argv)),
627
+ pipesToShell: () => {
628
+ const { leaves, normalized } = parse();
629
+ return (leaves.some(isBareShellLeaf) ||
630
+ normalized.some((leaf) => isBareShellLeaf(leaf.argv)));
631
+ },
605
632
  };
606
633
  }
634
+ /**
635
+ * The shell tool's name in a hook payload — the one spelling, shared by the Bash
636
+ * gate and the Bash react. A payload-vocabulary fact rather than a per-harness
637
+ * one: Claude Code sends `Bash`, and Codex's hooks docs (read 2026-11-17) say its
638
+ * shell commands, unified exec included, arrive "as `Bash`" too. Not read from
639
+ * the adapter on purpose: resolving it costs the ~280 ms adapter-registry load
640
+ * that `hook-runtime.ts` keeps off every gate path. ⚠️ No real Codex payload has
641
+ * been captured to confirm the docs; the Codex delivery fixture in this repo
642
+ * spells the tool `shell`, Codex's MODEL-facing name. Revisit with a port field
643
+ * if a harness's payload diverges.
644
+ */
645
+ exports.SHELL_TOOL = "Bash";
646
+ /**
647
+ * The command of a SHELL event, or `undefined` when the event is not one. Keyed
648
+ * on the tool name alone; a shell event with no string command reads as `""`, so
649
+ * every predicate of its view is false (the gate's behaviour since it existed).
650
+ * Used by both the Bash gate and the Bash react — one decode for "this event's
651
+ * command".
652
+ */
653
+ function shellCommandOf(raw) {
654
+ if (raw.tool_name !== exports.SHELL_TOOL)
655
+ return undefined;
656
+ const c = raw.tool_input?.command;
657
+ return typeof c === "string" ? c : "";
658
+ }
607
659
  /**
608
660
  * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
609
661
  * Imported and CALLED as `experimental_defineHook` — do not alias the prefix away at
@@ -642,14 +694,12 @@ function decideProgram(program, rawEvent, ctx = {}, root = typeof rawEvent.cwd =
642
694
  // role routes through `matchesTool`; that runtime/emit disagreement is the
643
695
  // one MEASURED and fixed for reacts on 2026-08-12 (see the header), and it
644
696
  // survived here on the flagship role. Removed 2026-09-08.
645
- if (rawEvent.tool_name !== "Bash")
697
+ const command = shellCommandOf(rawEvent);
698
+ if (command === undefined)
646
699
  return (0, exports.allow)();
647
- const command = typeof rawEvent.tool_input?.command === "string"
648
- ? rawEvent.tool_input.command
649
- : "";
650
700
  return program.decide({
651
701
  event: program.on,
652
- tool: "Bash",
702
+ tool: exports.SHELL_TOOL,
653
703
  command: commandView(command, root),
654
704
  ctx: ctx,
655
705
  });
@@ -947,7 +997,7 @@ function compileHookProgram(source, hook, opts = {}) {
947
997
  // itself (dialect.mcpToolPattern), so a fully-spelled server tool passes on
948
998
  // both counts.
949
999
  if (opts.dialect) {
950
- const literal = hook.match.tools.filter((t) => !REGEX_META.test(t));
1000
+ const literal = literalToolNames(hook.match.tools);
951
1001
  const badNames = (0, hook_events_js_1.authoringIssues)((0, tool_contract_js_1.verifyToolContract)(literal, opts.dialect));
952
1002
  if (badNames.length > 0) {
953
1003
  throw new HookCompileError(badNames[0].message);
@@ -1194,6 +1244,11 @@ function undecidablePathWarning(filePath, root) {
1194
1244
  `Repo-relative prefixes in this hook cannot match it, so the hook is ` +
1195
1245
  `deciding on less than it looks like it is. Set CLAUDE_PROJECT_DIR.`);
1196
1246
  }
1247
+ /**
1248
+ * Declare the tools a hook matches: `match: tools("Edit", "Write")`. The names
1249
+ * keep their LITERAL types, which is how a react declared with `tools("Bash")`
1250
+ * alone is known to carry `e.command`.
1251
+ */
1197
1252
  const tools = (...names) => ({
1198
1253
  tools: names,
1199
1254
  });
@@ -1395,13 +1450,27 @@ function runReact(hook, raw, ctx = {}, root = typeof raw.cwd === "string" ? raw.
1395
1450
  const fp = typeof raw.tool_input?.file_path === "string"
1396
1451
  ? raw.tool_input.file_path
1397
1452
  : "";
1398
- return hook.react({
1453
+ const base = {
1399
1454
  event: hook.on,
1400
1455
  tool: t,
1401
1456
  path: pathView(fp, root),
1402
1457
  response: responseView(raw.tool_response),
1403
1458
  ctx: ctx,
1404
- });
1459
+ };
1460
+ // The command is attached on SHELL events only, keyed on the tool NAME — never
1461
+ // on the presence of `tool_input.command`, which Codex's `apply_patch` also
1462
+ // carries (a patch, not a command line). The type promises it only to a react
1463
+ // declared for Bash alone; at run time it is present on every Bash event, so a
1464
+ // react whose declared tools merely MATCH Bash does not see a different object.
1465
+ const command = shellCommandOf(raw);
1466
+ const event = command === undefined
1467
+ ? base
1468
+ : { ...base, command: commandView(command, root) };
1469
+ // `ReactEvent<N, T>` is a conditional type over a still-generic `T`, which tsc
1470
+ // cannot narrow from a value; the runtime half of the promise is the tool-name
1471
+ // check above, held by the adapter twins' payload tests.
1472
+ // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- see the line above
1473
+ return hook.react(event);
1405
1474
  }
1406
1475
  /**
1407
1476
  * Resolve a raw payload's project root ONCE, at the entry point.
@@ -143,13 +143,29 @@ export declare function unsafeInlineProviders(needs: readonly NeedSpec[]): Inlin
143
143
  * `dangerous`)? Reused when compiling a `.vigiles/providers/` file.
144
144
  */
145
145
  export declare function unsafeProvider(def: RegisteredProvider): boolean;
146
+ /** One resolved fact: a string, a boolean (built-ins), or a state fact. */
147
+ type Fact = string | boolean | StateFact;
146
148
  /**
147
- * Gather the DECLARED facts into a context object (the trusted-host step). Only
148
- * the names in `needs` are gathered, each at most once; a built-in, inline, or
149
- * registered provider that can't resolve yields its default ("" / false), never
150
- * throws. Pure over the injected `io` (CLI passes a real execSync; tests a fake)
151
- * and the `registry` (the loaded `.vigiles/providers/`, for `provider()` refs).
149
+ * Resolve ONE declared need — the single resolver behind both {@link lazyContext}
150
+ * and {@link gatherContext}. TOTAL: an unresolvable need yields its default (""
151
+ * for a command or a missing registered ref, the built-in's own default, a
152
+ * never-recorded `state()` fact), never throws.
152
153
  */
153
- export declare function gatherContext(needs: readonly NeedSpec[], io: ProviderIO, registry?: ProviderRegistry): Record<string, string | boolean | StateFact>;
154
+ export declare function resolveNeed(need: NeedSpec, io: ProviderIO, registry?: ProviderRegistry): Fact;
155
+ /**
156
+ * The runtime's `e.ctx`: one enumerable, MEMOIZED getter per DECLARED need.
157
+ * Nothing runs until a key is read, each key resolves at most once per context
158
+ * (two reads in one decision see one value), and a key never read never runs —
159
+ * so an unread `dangerously()` provider costs nothing and fires nothing. Getters
160
+ * never throw ({@link resolveNeed} is total). `io.now` is fixed when the context
161
+ * is built, so a `state()` age does not depend on when `decide` reads it.
162
+ */
163
+ export declare function lazyContext(needs: readonly NeedSpec[], io: ProviderIO, registry?: ProviderRegistry): Readonly<Record<string, Fact>>;
164
+ /**
165
+ * Gather the DECLARED facts eagerly: {@link lazyContext} with every key read
166
+ * once (the eager twin, same resolver). Kept for callers that want a plain
167
+ * snapshot object. Pure over the injected `io` and the `registry`.
168
+ */
169
+ export declare function gatherContext(needs: readonly NeedSpec[], io: ProviderIO, registry?: ProviderRegistry): Readonly<Record<string, Fact>>;
154
170
  export {};
155
171
  //# sourceMappingURL=hook-providers.d.ts.map
@@ -4,6 +4,8 @@ exports.BUILTIN_PROVIDERS = exports.provider = exports.defineProvider = exports.
4
4
  exports.unknownProviders = unknownProviders;
5
5
  exports.unsafeInlineProviders = unsafeInlineProviders;
6
6
  exports.unsafeProvider = unsafeProvider;
7
+ exports.resolveNeed = resolveNeed;
8
+ exports.lazyContext = lazyContext;
7
9
  exports.gatherContext = gatherContext;
8
10
  /**
9
11
  * Hook CONTEXT PROVIDERS — let a compiled gate decide on EXTERNAL STATE (git
@@ -138,30 +140,62 @@ function unsafeProvider(def) {
138
140
  return !def.dangerous && !(0, bash_effects_js_1.isReadOnlyBash)(def.run);
139
141
  }
140
142
  /**
141
- * Gather the DECLARED facts into a context object (the trusted-host step). Only
142
- * the names in `needs` are gathered, each at most once; a built-in, inline, or
143
- * registered provider that can't resolve yields its default ("" / false), never
144
- * throws. Pure over the injected `io` (CLI passes a real execSync; tests a fake)
145
- * and the `registry` (the loaded `.vigiles/providers/`, for `provider()` refs).
143
+ * Resolve ONE declared need — the single resolver behind both {@link lazyContext}
144
+ * and {@link gatherContext}. TOTAL: an unresolvable need yields its default (""
145
+ * for a command or a missing registered ref, the built-in's own default, a
146
+ * never-recorded `state()` fact), never throws.
146
147
  */
147
- function gatherContext(needs, io, registry = {}) {
148
- const ctx = {};
149
- for (const need of needs) {
150
- if ((0, hook_state_js_1.isStateNeed)(need)) {
151
- // The one need that reaches no subprocess: the trusted runtime hands the
152
- // stored entry (or null) straight in, and the fact view does the clamping
153
- // every shell stamp-reader used to re-implement by hand.
154
- ctx[need.name] = (0, hook_state_js_1.stateFact)(io.readState(need.name), io.now);
155
- }
156
- else if (isInline(need))
157
- ctx[need.name] = tryExec(io, need.run);
158
- else if (isRef(need)) {
159
- const def = registry[need.name];
160
- ctx[need.name] = def ? tryExec(io, def.run) : "";
161
- }
162
- else
163
- ctx[need] = exports.BUILTIN_PROVIDERS[need].gather(io);
148
+ function resolveNeed(need, io, registry = {}) {
149
+ if ((0, hook_state_js_1.isStateNeed)(need)) {
150
+ // The one need that reaches no subprocess: the trusted runtime hands the
151
+ // stored entry (or null) straight in, and the fact view does the clamping
152
+ // every shell stamp-reader used to re-implement by hand.
153
+ return (0, hook_state_js_1.stateFact)(io.readState(need.name), io.now);
164
154
  }
165
- return ctx;
155
+ if (isInline(need))
156
+ return tryExec(io, need.run);
157
+ if (isRef(need)) {
158
+ const def = registry[need.name];
159
+ return def ? tryExec(io, def.run) : "";
160
+ }
161
+ return exports.BUILTIN_PROVIDERS[need].gather(io);
162
+ }
163
+ /** The key a need is exposed under in `e.ctx`. */
164
+ const needKey = (need) => typeof need === "string" ? need : need.name;
165
+ /**
166
+ * The runtime's `e.ctx`: one enumerable, MEMOIZED getter per DECLARED need.
167
+ * Nothing runs until a key is read, each key resolves at most once per context
168
+ * (two reads in one decision see one value), and a key never read never runs —
169
+ * so an unread `dangerously()` provider costs nothing and fires nothing. Getters
170
+ * never throw ({@link resolveNeed} is total). `io.now` is fixed when the context
171
+ * is built, so a `state()` age does not depend on when `decide` reads it.
172
+ */
173
+ function lazyContext(needs, io, registry = {}) {
174
+ return Object.defineProperties({}, Object.fromEntries(needs.map((need) => [
175
+ needKey(need),
176
+ {
177
+ enumerable: true,
178
+ configurable: true,
179
+ // Memoization by self-replacement: the first read resolves the need and
180
+ // redefines the key as a plain data property holding the result, so a
181
+ // second read can never run it again and no cache variable exists.
182
+ get() {
183
+ const value = resolveNeed(need, io, registry);
184
+ Object.defineProperty(this, needKey(need), {
185
+ value,
186
+ enumerable: true,
187
+ });
188
+ return value;
189
+ },
190
+ },
191
+ ])));
192
+ }
193
+ /**
194
+ * Gather the DECLARED facts eagerly: {@link lazyContext} with every key read
195
+ * once (the eager twin, same resolver). Kept for callers that want a plain
196
+ * snapshot object. Pure over the injected `io` and the `registry`.
197
+ */
198
+ function gatherContext(needs, io, registry = {}) {
199
+ return Object.fromEntries(Object.entries(lazyContext(needs, io, registry)));
166
200
  }
167
201
  //# sourceMappingURL=hook-providers.js.map
@@ -121,10 +121,23 @@ function applyHookWrites(file, outcome, root) {
121
121
  }
122
122
  }
123
123
  /**
124
- * Gather a gate's DECLARED context providers (the trusted-host I/O step). Runs
125
- * each declared read-only command via execSync in the hook's cwd; a provider
126
- * that can't resolve yields its default (never throws). The pure registry +
127
- * decision logic live in core/hook-providers.ts — this only injects the real IO.
124
+ * Longest a single provider command may run before it is killed and yields the
125
+ * same default as a failed one. 10 s: the repo's own precedent for a one-shot
126
+ * probe subprocess is 10_000 ms (`src/cli-main.ts`, the `--version` check), the
127
+ * slowest legitimate provider is a `git status` on a large tree (a second or
128
+ * two), and it must stay well under the harness's own hook timeout so a hung
129
+ * provider is reported as a default rather than as a dead hook. Not
130
+ * configurable by design (no new key); a provider needing more is not a fact.
131
+ */
132
+ const PROVIDER_TIMEOUT_MS = 10_000;
133
+ /**
134
+ * Build a gate's DECLARED context (`e.ctx`) — LAZILY. Each declared read-only
135
+ * command runs via execSync in the hook's cwd only when the hook READS its key,
136
+ * at most once per call, bounded by {@link PROVIDER_TIMEOUT_MS}; a provider that
137
+ * can't resolve or times out yields its default (never throws). The pure
138
+ * registry + resolver live in core/hook-providers.ts — this only injects the
139
+ * real IO. Loading `.vigiles/providers/` files stays eager (async import), but
140
+ * only when a `provider()` ref is declared.
128
141
  */
129
142
  async function gatherHookContext(program, file, root) {
130
143
  const needs = (0, hook_program_js_1.hookNeeds)(program);
@@ -135,10 +148,11 @@ async function gatherHookContext(program, file, root) {
135
148
  const registry = hasRef ? await loadProviderRegistry(root) : {};
136
149
  const { execSync } = require("node:child_process");
137
150
  const { isCI } = require("ci-info");
138
- return (0, hook_providers_js_1.gatherContext)(needs, {
151
+ return (0, hook_providers_js_1.lazyContext)(needs, {
139
152
  exec: (command) => execSync(command, {
140
153
  encoding: "utf-8",
141
154
  stdio: ["ignore", "pipe", "ignore"],
155
+ timeout: PROVIDER_TIMEOUT_MS,
142
156
  }),
143
157
  cwd: root,
144
158
  platform: process.platform,
package/dist/hook.d.ts CHANGED
@@ -50,7 +50,7 @@
50
50
  * strong default and is NEVER an unbypassable wall. See `docs/compiled-hooks.md`.
51
51
  */
52
52
  export { experimental_defineHook, experimental_defineFileGate, experimental_definePromptGate, experimental_defineStopGate, tools, allow, deny, ask, commandView, pathView, gateAction, hookMode, experimental_defineInject, inject, experimental_defineReact, run, notice, nothing, responseView, decideProgram, decideFileGate, decidePromptGate, decideStopGate, runInject, runReact, runHookProgram, decisionExitCode, dispatchKind, hookRouting, hookNeeds, injectionOf, outcomeWrites, matchesTool, invalidToolPatterns, compileHookProgram, checkHookImports, stampHook, verifyHookStamp, HookCompileError, } from "./core/hook-program.js";
53
- export type { Decision, HookMode, GateAction, CommandView, PathView, ResponseView, BashToolEvent, FileToolEvent, PromptEvent, StopEvent, ReactEvent, SessionEvent, HookProgram, FileGateHook, PromptGateHook, StopGateHook, InjectHook, ReactHook, AnyHook, DispatchKind, Injection, Reaction, RunReaction, CompiledHookProgram, CompileHookOptions, RawHookEvent, HookProgramOutcome, } from "./core/hook-program.js";
53
+ export type { Decision, HookMode, GateAction, CommandView, PathView, ResponseView, BashToolEvent, FileToolEvent, PromptEvent, StopEvent, ReactEvent, BashReactEvent, ToolReactEvent, SessionEvent, HookProgram, FileGateHook, PromptGateHook, StopGateHook, InjectHook, ReactHook, AnyHook, DispatchKind, Injection, Reaction, RunReaction, CompiledHookProgram, CompileHookOptions, RawHookEvent, HookProgramOutcome, } from "./core/hook-program.js";
54
54
  export { provide, dangerously, defineProvider, provider, } from "./core/hook-providers.js";
55
55
  export { state, record, stateFact, isValidStateKey, isStateNeed, isStateWrite, admissibleWrites, durationSeconds, HookStateError, } from "./core/hook-state.js";
56
56
  export type { StateFact, StateEntry, StateNeed, StateWrite, Duration, } from "./core/hook-state.js";
@@ -28,7 +28,17 @@ exports.nodeSourceHost = {
28
28
  return null;
29
29
  }
30
30
  },
31
- isFile: (path) => (0, node_fs_1.statSync)(path, { throwIfNoEntry: false })?.isFile() === true,
31
+ // Total: tsc's resolver probes `<main>/index.ts`, a path THROUGH a file when
32
+ // `main` is a file. Node 20 throws ENOTDIR there despite `throwIfNoEntry`
33
+ // (newer Node swallows it), and a throw here killed `test --changed`.
34
+ isFile: (path) => {
35
+ try {
36
+ return (0, node_fs_1.statSync)(path, { throwIfNoEntry: false })?.isFile() === true;
37
+ }
38
+ catch {
39
+ return false;
40
+ }
41
+ },
32
42
  realpath: (path) => {
33
43
  try {
34
44
  return (0, node_fs_1.realpathSync)(path);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vigiles",
3
- "version": "41.2.0",
3
+ "version": "41.3.0",
4
4
  "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
5
5
  "keywords": [
6
6
  "claude-code",