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.
- package/dist/core/hook-program.d.ts +77 -11
- package/dist/core/hook-program.js +113 -44
- package/dist/core/hook-providers.d.ts +22 -6
- package/dist/core/hook-providers.js +57 -23
- package/dist/hook-runtime.js +19 -5
- package/dist/hook.d.ts +1 -1
- package/dist/host/changed-files.io.js +11 -1
- package/package.json +1 -1
|
@@ -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
|
-
|
|
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
|
-
|
|
677
|
-
|
|
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
|
-
/**
|
|
855
|
-
|
|
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:
|
|
975
|
+
readonly tools: T;
|
|
914
976
|
};
|
|
915
977
|
/** Declared context providers the trusted runtime gathers into `e.ctx`. */
|
|
916
978
|
readonly needs?: N;
|
|
917
|
-
/**
|
|
918
|
-
|
|
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
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
.
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
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: () =>
|
|
604
|
-
normalized
|
|
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
|
-
|
|
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:
|
|
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
|
|
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
|
-
|
|
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
|
-
*
|
|
148
|
-
*
|
|
149
|
-
*
|
|
150
|
-
*
|
|
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
|
|
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
|
-
*
|
|
142
|
-
*
|
|
143
|
-
*
|
|
144
|
-
*
|
|
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
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
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
|
-
|
|
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
|
package/dist/hook-runtime.js
CHANGED
|
@@ -121,10 +121,23 @@ function applyHookWrites(file, outcome, root) {
|
|
|
121
121
|
}
|
|
122
122
|
}
|
|
123
123
|
/**
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
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.
|
|
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
|
-
|
|
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.
|
|
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",
|