vigiles 41.1.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/action.yml CHANGED
@@ -9,13 +9,15 @@ inputs:
9
9
  command:
10
10
  description: >
11
11
  Which vigiles command to run: 'lint' (verify references + integrity +
12
- coverage), 'compile' (specs → markdown), or 'eval-check' (verify committed
12
+ coverage), 'compile' (specs → markdown), 'test' (run the *.harness.*
13
+ files against a scripted model — free, no API key; installs the repo's
14
+ dependencies first, see `install`), or 'eval-check' (verify committed
13
15
  eval locks against current inputs — the staleness gate; runs NO model, so
14
16
  it is the CI-safe half of evals you produce locally with `vigiles eval --update`).
15
17
  required: false
16
18
  default: "lint"
17
19
  paths:
18
- description: "Comma- or space-separated paths to operate on (.md files for lint, .spec.ts files for compile). Auto-discovers when empty."
20
+ description: "Comma- or space-separated paths or globs to operate on (.md files for lint, .spec.ts files for compile, harness files for test). Auto-discovers when empty."
19
21
  required: false
20
22
  default: ""
21
23
  version:
@@ -46,6 +48,34 @@ inputs:
46
48
  none.
47
49
  required: false
48
50
  default: ""
51
+ changed-only:
52
+ description: >
53
+ test only. Run only the harness files the change can reach (maps to a
54
+ bare `--changed`): on pull_request events the CLI diffs against the PR
55
+ base (fetching it); on any other event every file runs. 'true' or
56
+ 'false'.
57
+ required: false
58
+ default: "false"
59
+ min:
60
+ description: >
61
+ test and eval-check. Fail unless discovery matched at least this many
62
+ files (maps to the CLI's --min=). Under changed-only it counts the files
63
+ discovery matched, before the PR narrows them, so a broken glob still
64
+ fails. Empty (the default) sets no floor.
65
+ required: false
66
+ default: ""
67
+ no-skip:
68
+ description: "test and eval-check. Fail when a file reports itself SKIPPED (maps to the CLI's --no-skip). 'true' or 'false'."
69
+ required: false
70
+ default: "false"
71
+ install:
72
+ description: >
73
+ test only. Run `npm ci` before the harness files, because they import the
74
+ repo's own dependencies — only when package-lock.json exists and
75
+ node_modules does not (an earlier install step wins). Cache it with
76
+ `actions/setup-node`'s `cache: npm`. 'true' or 'false'.
77
+ required: false
78
+ default: "true"
49
79
  working-directory:
50
80
  description: "Directory to run vigiles in."
51
81
  required: false
@@ -83,6 +113,10 @@ runs:
83
113
  shell: bash
84
114
  working-directory: ${{ inputs.working-directory }}
85
115
  env:
116
+ # The commands the Action accepts — the ONE list, as data:
117
+ # src/action-dogfood.test.ts reads it and fails unless this repo's CI
118
+ # runs each through `uses: ./`.
119
+ VIGILES_COMMANDS: "lint compile test eval-check"
86
120
  # Inputs are passed through the environment (never interpolated into
87
121
  # the script body) so a value can't break out of the command line.
88
122
  VIGILES_COMMAND: ${{ inputs.command }}
@@ -95,11 +129,25 @@ runs:
95
129
  VIGILES_COMMENT: ${{ inputs.comment }}
96
130
  VIGILES_CAPABILITY_DIFF: ${{ inputs.capability-diff }}
97
131
  VIGILES_FAIL_ON_WIDEN: ${{ inputs.fail-on-widen }}
132
+ VIGILES_CHANGED_ONLY: ${{ inputs.changed-only }}
133
+ VIGILES_MIN: ${{ inputs.min }}
134
+ VIGILES_NO_SKIP: ${{ inputs.no-skip }}
135
+ VIGILES_INSTALL: ${{ inputs.install }}
98
136
  GH_TOKEN: ${{ inputs.github-token }}
99
137
  run: |
138
+ # This step maps inputs to CLI flags and reports the result. Any
139
+ # DECISION — reading the event payload, asking git, choosing what runs —
140
+ # belongs in the CLI, where it is unit-tested and works locally too (the
141
+ # prod-grade-gha-cli rule, docs/contributing/rules.md).
100
142
  set -euo pipefail
101
143
 
102
144
  cmd="${VIGILES_COMMAND:-lint}"
145
+ # Anything outside VIGILES_COMMANDS used to pass through and fail as a
146
+ # CLI error that looked like a vigiles bug.
147
+ if [[ " ${VIGILES_COMMANDS} " != *" ${cmd} "* ]]; then
148
+ echo "::error::vigiles: unknown command '${cmd}' (one of: ${VIGILES_COMMANDS})"
149
+ exit 2
150
+ fi
103
151
  # 'eval-check' is the CI staleness gate — it maps to the real verb
104
152
  # `eval --check` (verify committed locks vs current inputs, NO model).
105
153
  # Real evals run locally on a subscription (`eval --update`), never in CI.
@@ -132,6 +180,34 @@ runs:
132
180
  args+=("--preset=${preset// /}")
133
181
  fi
134
182
 
183
+ # The count floor and the no-skip gate: the CLI validates both per
184
+ # verb (an unknown flag exits 2), so they are passed through as written.
185
+ min="${VIGILES_MIN:-}"
186
+ if [[ -n "${min// /}" ]]; then
187
+ args+=("--min=${min// /}")
188
+ fi
189
+ if [[ "${VIGILES_NO_SKIP:-false}" == "true" ]]; then
190
+ args+=("--no-skip")
191
+ fi
192
+
193
+ # changed-only → a bare `--changed`: the CLI picks the base (the PR's on
194
+ # pull_request, everything on any other event) and fetches it.
195
+ if [[ "$cmd" == "test" && "${VIGILES_CHANGED_ONLY:-false}" == "true" ]]; then
196
+ args+=("--changed")
197
+ fi
198
+
199
+ # test runs the repo's harness files, which import its dependencies.
200
+ # Installed BEFORE the runner is resolved, so the default `version`
201
+ # then finds the vigiles this repo declares, installed.
202
+ if [[ "$cmd" == "test" && "${VIGILES_INSTALL:-true}" == "true" && ! -d node_modules ]]; then
203
+ if [[ -f package-lock.json || -f npm-shrinkwrap.json ]]; then
204
+ echo "vigiles: npm ci (the harness files import this repo's dependencies)"
205
+ npm ci --no-audit --no-fund
206
+ elif [[ -f package.json ]]; then
207
+ echo "::warning::vigiles test: no package-lock.json and no node_modules — install dependencies in a step before this one"
208
+ fi
209
+ fi
210
+
135
211
  # Resolve the runner. 'local' runs the action's own build (CI
136
212
  # dogfood via `uses: ./`); an explicit version runs the published npm
137
213
  # package at that version. EMPTY (the default) runs the vigiles this
@@ -92,7 +92,17 @@ exports.COMMAND_FLAGS = {
92
92
  "--update-baseline",
93
93
  ],
94
94
  // handleRunScripts (free tier — no lock flags).
95
- test: ["--min=", "--all", "--yes", "--no-interactive", "--no-skip"],
95
+ test: [
96
+ "--min=",
97
+ "--all",
98
+ "--yes",
99
+ "--no-interactive",
100
+ "--no-skip",
101
+ // test-selection.ts: run only what a change since <ref> can reach; bare,
102
+ // the base is decided (core/changed-base.ts).
103
+ "--changed",
104
+ "--changed=",
105
+ ],
96
106
  // handleRunScripts + resolveEvalLockEnv + the trials knob.
97
107
  eval: [
98
108
  "--min=",
package/dist/cli-main.js CHANGED
@@ -106,6 +106,10 @@ const skill_runtime_js_1 = require("./adapters/claude-code/skill-runtime.js");
106
106
  const linters_js_1 = require("./core/linters.js");
107
107
  const harness_test_js_1 = require("./harness-test.js");
108
108
  const run_scripts_js_1 = require("./adapters/claude-code/run-scripts.js");
109
+ const test_selection_js_1 = require("./core/test-selection.js");
110
+ const test_reach_js_1 = require("./core/test-reach.js");
111
+ const changed_files_io_js_1 = require("./host/changed-files.io.js");
112
+ const changed_base_js_1 = require("./core/changed-base.js");
109
113
  /**
110
114
  * THE RULE SET, WIRED IN — the composition root's one job for rules. Core
111
115
  * declares the port and takes the set as a parameter; this file (and the
@@ -5927,11 +5931,16 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
5927
5931
  const env = { ...lockEnv };
5928
5932
  if (trialsFlag)
5929
5933
  env.VIGILES_TRIALS = trialsFlag.split("=")[1];
5930
- console.log(`Running ${String(files.length)} ${kind} file(s):\n`);
5934
+ // `--changed=<ref>` narrows the set AFTER `--min` has counted discovery, so a
5935
+ // broken glob still fails on a PR that touches nothing (test-selection.ts).
5936
+ const toRun = kind === "test" ? narrowToChanged(cwd, files, args) : files;
5937
+ if (toRun.length === 0)
5938
+ return;
5939
+ console.log(`Running ${String(toRun.length)} ${kind} file(s):\n`);
5931
5940
  // An eval file DESCRIBES its eval; `dist/eval-entry.js` is what imports the
5932
5941
  // description and runs what it declares. A harness script is still its own
5933
5942
  // program (it is free, so "import spends money" never applied to it).
5934
- const results = await (0, run_scripts_js_1.runScripts)(files, cwd, env, {
5943
+ const results = await (0, run_scripts_js_1.runScripts)(toRun, cwd, env, {
5935
5944
  ...(kind === "eval" ? { entry: (0, node_path_1.resolve)(__dirname, "eval-entry.js") } : {}),
5936
5945
  });
5937
5946
  // Write down WHAT the run exercised, so `lint`/`audit` can answer "tested?"
@@ -5941,10 +5950,13 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
5941
5950
  recordRunCoverage(cwd, results, kind, harnessFlagFrom(args));
5942
5951
  console.log("\n" + (0, run_scripts_js_1.formatScriptSummary)(results));
5943
5952
  const loadedCount = results.filter((r) => !(0, run_scripts_js_1.loadFailed)(r)).length;
5944
- const belowFloor = loadedCount < minRequired;
5953
+ // Under `--changed` the floor was met by discovery; what is left to hold is
5954
+ // that every SELECTED file loaded.
5955
+ const floor = Math.min(minRequired, toRun.length);
5956
+ const belowFloor = loadedCount < floor;
5945
5957
  if (belowFloor) {
5946
5958
  console.error(`\n✗ vigiles ${kind}: --min=${String(minRequired)} but only ${String(loadedCount)} of ` +
5947
- `${String(files.length)} matched ${kind} file(s) loaded.`);
5959
+ `${String(toRun.length)} matched ${kind} file(s) loaded.`);
5948
5960
  }
5949
5961
  // An eval whose stubs left a call unanswered measured an answer nobody wrote.
5950
5962
  // That is not a failed assertion but a non-measurement, and it must fail the
@@ -6003,6 +6015,67 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
6003
6015
  process.exit(1);
6004
6016
  }
6005
6017
  }
6018
+ /**
6019
+ * The ref `--changed` compares against. `--changed=<ref>` names it, and an
6020
+ * unusable one exits 2. A bare `--changed` decides it (`core/changed-base.ts`):
6021
+ * the pull request's base on GitHub Actions (fetched when the clone lacks it),
6022
+ * the default branch locally — and `undefined`, said out loud, when the answer
6023
+ * is "every file runs".
6024
+ */
6025
+ function changedRef(cwd, flag) {
6026
+ if (flag === "--changed") {
6027
+ const d = (0, changed_files_io_js_1.ensureBase)(cwd, (0, changed_base_js_1.decideBase)((0, changed_files_io_js_1.readBaseFacts)(cwd, process.env)));
6028
+ console.log(`--changed: ${d.why}.`);
6029
+ return d.kind === "diff" ? d.ref : undefined;
6030
+ }
6031
+ const parsed = (0, test_selection_js_1.parseChangedRef)(flag.slice("--changed=".length));
6032
+ if (parsed.kind === "error") {
6033
+ console.error(`✗ vigiles test: ${parsed.message}`);
6034
+ process.exit(2);
6035
+ }
6036
+ return parsed.ref;
6037
+ }
6038
+ /**
6039
+ * Apply `--changed[=<ref>]` to the discovered harness files: print which run and
6040
+ * why, and return them. Without the flag, every file. An empty return means the
6041
+ * selection was empty and has been said; an unusable explicit ref exits 2,
6042
+ * because running everything or nothing would both misreport what was asked.
6043
+ */
6044
+ function narrowToChanged(cwd, files, args) {
6045
+ const flag = args.find((a) => a === "--changed" || a.startsWith("--changed="));
6046
+ if (flag === undefined)
6047
+ return files;
6048
+ const ref = changedRef(cwd, flag);
6049
+ if (ref === undefined)
6050
+ return files;
6051
+ const changed = (0, changed_files_io_js_1.changedSince)(cwd, ref);
6052
+ if (changed.kind === "error") {
6053
+ console.error(`✗ vigiles test: ${changed.message}`);
6054
+ process.exit(2);
6055
+ }
6056
+ // Real path on every side: git and TypeScript's resolver both report one, and
6057
+ // a symlinked cwd (macOS /tmp) would otherwise match nothing.
6058
+ const real = (0, node_fs_1.realpathSync)(cwd);
6059
+ const key = (f) => (0, test_reach_js_1.posixRelative)(real, (0, node_path_1.resolve)(real, f));
6060
+ const byKey = new Map(files.map((f) => [key(f), f]));
6061
+ const reach = (0, test_reach_js_1.reachFor)({
6062
+ cwd: real,
6063
+ host: changed_files_io_js_1.nodeSourceHost,
6064
+ project: (0, test_reach_js_1.readProject)(real, changed_files_io_js_1.nodeSourceHost),
6065
+ });
6066
+ const sel = (0, test_selection_js_1.selectTests)({
6067
+ files: [...byKey.keys()],
6068
+ changed: changed.files,
6069
+ runAllOn: [
6070
+ ...test_selection_js_1.DEFAULT_RUN_ALL_ON,
6071
+ changed.workflowsGlob,
6072
+ ...(loadConfig().test?.runAllOn ?? []),
6073
+ ],
6074
+ reach,
6075
+ });
6076
+ console.log((0, test_selection_js_1.formatSelection)(sel, ref, changed) + "\n");
6077
+ return sel.selected.map((s) => byKey.get(s.file) ?? s.file);
6078
+ }
6006
6079
  /** Parse the `--harness=<name>` override out of an argv list (the one definition). */
6007
6080
  function harnessFlagFrom(argv) {
6008
6081
  return argv
@@ -6063,6 +6136,11 @@ const COMMAND_HELP = {
6063
6136
  // "Free, no API key" is the CONSEQUENCE; "deterministic" was the mechanism, and a reader
6064
6137
  // deciding whether to put this in CI needs the cost, not the implementation.
6065
6138
  usage: " vigiles test [files...] Against a scripted stand-in model. Free, no API key — every commit.",
6139
+ detail: [
6140
+ " --changed[=<ref>] run only the files a change since <ref> can reach: the file itself,",
6141
+ " a changed file in its folder, imports or effect calls, or a run-all trigger (package.json…).",
6142
+ " Bare, the base is decided: the PR's base in CI, the default branch locally.",
6143
+ ],
6066
6144
  },
6067
6145
  eval: {
6068
6146
  usage: " vigiles eval [files...] Against a real model. Spends your subscription — on demand.",
@@ -0,0 +1,34 @@
1
+ /** Where the run is, as the host saw it. */
2
+ export type CiFacts = {
3
+ readonly provider: "github";
4
+ /** `GITHUB_EVENT_NAME`. */
5
+ readonly event: string | undefined;
6
+ /** `pull_request.base.sha` from the event payload. */
7
+ readonly prBase: string | undefined;
8
+ /** `GITHUB_BASE_REF`: the base BRANCH of a pull request. */
9
+ readonly baseRef: string | undefined;
10
+ } | {
11
+ readonly provider: "other";
12
+ } | {
13
+ readonly provider: "none";
14
+ };
15
+ export interface BaseFacts {
16
+ readonly ci: CiFacts;
17
+ /** The first of origin/HEAD, origin/main, origin/master that exists locally. */
18
+ readonly defaultBranch: string | undefined;
19
+ }
20
+ export type BaseDecision = {
21
+ readonly kind: "diff";
22
+ readonly ref: string;
23
+ /** What to `git fetch` from origin when `ref` is not in the clone. */
24
+ readonly fetch: string | undefined;
25
+ readonly why: string;
26
+ } | {
27
+ readonly kind: "all";
28
+ readonly why: string;
29
+ };
30
+ /** The base to diff against, or why every file runs. */
31
+ export declare function decideBase(f: BaseFacts): BaseDecision;
32
+ /** `pull_request.base.sha` of a parsed event payload, or undefined for any other shape. */
33
+ export declare function prBaseFromEvent(payload: unknown): string | undefined;
34
+ //# sourceMappingURL=changed-base.d.ts.map
@@ -0,0 +1,82 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.decideBase = decideBase;
4
+ exports.prBaseFromEvent = prBaseFromEvent;
5
+ /**
6
+ * Bare `vigiles test --changed`: the base to compare against, decided from
7
+ * facts the host gathered. Pure; the env, the event file and git are read in
8
+ * `src/host/changed-files.io.ts`.
9
+ *
10
+ * The shape follows Turborepo's `--affected`: on GitHub Actions a pull request
11
+ * diffs against its base, any other event runs everything, and a local run
12
+ * diffs against the default branch. 🔴 WHEN NOTHING RESOLVES, EVERYTHING RUNS,
13
+ * and the run says why. A guessed base can only narrow, and a narrow nobody
14
+ * asked for is the silent skip this whole feature exists to avoid.
15
+ */
16
+ const zod_1 = require("zod");
17
+ const PR_EVENTS = new Set([
18
+ "pull_request",
19
+ "pull_request_target",
20
+ ]);
21
+ /** The base to diff against, or why every file runs. */
22
+ function decideBase(f) {
23
+ switch (f.ci.provider) {
24
+ case "github":
25
+ return githubBase(f.ci);
26
+ case "other":
27
+ return {
28
+ kind: "all",
29
+ why: "a CI run with no known pull-request base, so every file runs",
30
+ };
31
+ case "none":
32
+ return f.defaultBranch === undefined
33
+ ? {
34
+ kind: "all",
35
+ why: "no default branch found (origin/HEAD, origin/main, origin/master), so every file runs",
36
+ }
37
+ : {
38
+ kind: "diff",
39
+ ref: f.defaultBranch,
40
+ fetch: undefined,
41
+ why: `merge-base with ${f.defaultBranch}, the default branch`,
42
+ };
43
+ }
44
+ }
45
+ function githubBase(ci) {
46
+ const event = ci.event ?? "unknown";
47
+ if (!PR_EVENTS.has(event)) {
48
+ return {
49
+ kind: "all",
50
+ why: `${event} event: not a pull request, so every file runs`,
51
+ };
52
+ }
53
+ return prBase(event, ci.prBase, ci.baseRef);
54
+ }
55
+ /** A pull request's base: the payload's sha, else the base branch, else none. */
56
+ function prBase(event, sha, branch) {
57
+ if (sha !== undefined) {
58
+ const why = `${event} base ${sha} from the event payload`;
59
+ return { kind: "diff", ref: sha, fetch: sha, why };
60
+ }
61
+ if (branch === undefined || branch === "") {
62
+ return {
63
+ kind: "all",
64
+ why: `${event} event with no base in the payload or GITHUB_BASE_REF, so every file runs`,
65
+ };
66
+ }
67
+ return {
68
+ kind: "diff",
69
+ ref: `origin/${branch}`,
70
+ fetch: `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
71
+ why: `${event} base branch ${branch} (GITHUB_BASE_REF)`,
72
+ };
73
+ }
74
+ const prEvent = zod_1.z.object({
75
+ pull_request: zod_1.z.object({ base: zod_1.z.object({ sha: zod_1.z.string() }) }),
76
+ });
77
+ /** `pull_request.base.sha` of a parsed event payload, or undefined for any other shape. */
78
+ function prBaseFromEvent(payload) {
79
+ const parsed = prEvent.safeParse(payload);
80
+ return parsed.success ? parsed.data.pull_request.base.sha : undefined;
81
+ }
82
+ //# sourceMappingURL=changed-base.js.map
@@ -115,6 +115,15 @@ declare const configTailKeys: {
115
115
  eval: z.ZodOptional<z.ZodObject<{
116
116
  apiVersion: z.ZodOptional<z.ZodNumber>;
117
117
  }, z.core.$strict>>;
118
+ /**
119
+ * `vigiles test --changed=<ref>`: globs (relative to where vigiles runs) whose change
120
+ * runs EVERY harness, on top of the built-in triggers (package.json, the
121
+ * lockfiles, this file, the CI workflows). For an input a harness spawns or
122
+ * reads from outside its own folder.
123
+ */
124
+ test: z.ZodOptional<z.ZodObject<{
125
+ runAllOn: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
126
+ }, z.core.$strict>>;
118
127
  nudge: z.ZodOptional<z.ZodLiteral<"dismissed">>;
119
128
  };
120
129
  /**
@@ -190,6 +190,13 @@ const configTailKeys = {
190
190
  harnesses: zod_1.z.record(zod_1.z.string(), harnessDeclarationSchema).optional(),
191
191
  audit: zod_1.z.object({ measure: zod_1.z.boolean().optional() }).strict().optional(),
192
192
  eval: zod_1.z.object({ apiVersion: zod_1.z.number().optional() }).strict().optional(),
193
+ /**
194
+ * `vigiles test --changed=<ref>`: globs (relative to where vigiles runs) whose change
195
+ * runs EVERY harness, on top of the built-in triggers (package.json, the
196
+ * lockfiles, this file, the CI workflows). For an input a harness spawns or
197
+ * reads from outside its own folder.
198
+ */
199
+ test: zod_1.z.object({ runAllOn: exports.stringList.optional() }).strict().optional(),
193
200
  nudge: zod_1.z.literal("dismissed").optional(),
194
201
  };
195
202
  /**
@@ -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;