vigiles 26.2.0 → 27.0.0

package/dist/hook-runtime.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The compiled-hook RUNTIME — `vigiles hook-runtime run-program <file>`, the
+ * process the harness spawns on every matching tool call.
+ *
+ * WHY IT IS ITS OWN MODULE, and why that is the whole point (#216): this code
+ * used to live in `src/cli.ts` beside `compile` / `lint` / `audit` / `eval`, and
+ * CommonJS resolves a module's top-level imports before a single argument is
+ * parsed — so deciding `allow` on `ls -la` loaded the report template loader, the
+ * linter catalogs, the adapter registry and ~30 more barrels. MEASURED
+ * 2026-09-08 (Node 22.22.2, `tools/measure-hook-startup.mjs`, median of 20
+ * spawns): `require("dist/cli.js")` cost 623 ms against a 42 ms bare Node start,
+ * and a real `run-program` spawn cost 610-661 ms. A shell hook doing the same job
+ * costs ~12 ms.
+ *
+ * So `src/cli.ts` is now a dispatcher shim that `require`s THIS file for
+ * `hook-runtime run-program` and the verb barrel for everything else. The
+ * emitted command is unchanged and MUST stay unchanged — it is baked into every
+ * already-emitted settings block and into the SHA stamp beside each hook.
+ *
+ * KEEP THIS MODULE'S TOP-LEVEL IMPORTS MINIMAL. Everything imported here is paid
+ * on every gated tool call. Two deliberately-lazy edges, each with the measurement
+ * at its call site: `@iarna/toml` (compile-time only, in `core/hook-program.ts`
+ * and `hook-install.ts`) and `mvdan-sh` (bash predicates only, in
+ * `core/bash-effects.ts`). `src/hook-runtime-graph.test.ts` asserts the graph
+ * deterministically, because a timing threshold on a shared CI runner would be
+ * flaky and would be the first thing quarantined.
+ *
+ * Harness-neutral: the gate protocol (deny → exit 2) is byte-identical on Claude
+ * Code and Codex, and the ONE harness-specific fact the runtime needs — which
+ * events accept injected context — is read from the resolved adapter's
+ * `HookProtocol.injectableEvents`, never a literal. That resolution is itself a
+ * lazy `require` because only the react role needs it (the adapter registry
+ * measured 279 ms on its own).
+ *
+ * This is COMPOSITION-ROOT code (`src/` root), not `src/core/`: it does real I/O
+ * (stdin, the stamp sidecar, state writes, `spawnSync`) and reaches the adapter
+ * registry, so `core ⊄ adapter` keeps it out of the domain layer.
+ */
+import { type RegisteredProvider } from "./core/hook-providers.js";
+import { loadHook } from "./load-hook.js";
+/**
+ * Load a compiled-hook program's default export — the SHARED loader, also the
+ * public `vigiles` `loadHook` a `.harness.mjs` test uses, so a hook that
+ * loads in a test loads identically here (one loader, no drift).
+ */
+export declare const loadHookProgram: typeof loadHook;
+/** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
+export declare function loadProvider(file: string): Promise<RegisteredProvider>;
+/** Path of the tamper-evident stamp sidecar for a hook file. */
+export declare function hookStampPath(file: string): string;
+/**
+ * `vigiles hook-runtime run-program <file>` — the runtime the compiled hooks block
+ * points at. Reads the live event on stdin, loads the typed program, verifies
+ * its stamp, and dispatches by role: a gate exits 2 + reason on `deny`; an
+ * inject prints `additionalContext`; a react runs its effect-classified
+ * command. A hook that won't load — or whose stamp is stale — fails CLOSED
+ * (exit 2), never silent-allow, with two loudly-announced exceptions: the repair
+ * action itself ({@link isStampRepairEvent}), and — on a LOAD failure only — the
+ * load-path repair WRITE ({@link isLoadPathRepairEvent}), or the repo wedges
+ * with no way to fix whatever broke the load path.
+ */
+export declare function runHookProgramCommand(file: string | undefined): Promise<void>;
+//# sourceMappingURL=hook-runtime.d.ts.map

package/dist/hook-runtime.js

@@ -0,0 +1,540 @@
+"use strict";
+/**
+ * The compiled-hook RUNTIME — `vigiles hook-runtime run-program <file>`, the
+ * process the harness spawns on every matching tool call.
+ *
+ * WHY IT IS ITS OWN MODULE, and why that is the whole point (#216): this code
+ * used to live in `src/cli.ts` beside `compile` / `lint` / `audit` / `eval`, and
+ * CommonJS resolves a module's top-level imports before a single argument is
+ * parsed — so deciding `allow` on `ls -la` loaded the report template loader, the
+ * linter catalogs, the adapter registry and ~30 more barrels. MEASURED
+ * 2026-09-08 (Node 22.22.2, `tools/measure-hook-startup.mjs`, median of 20
+ * spawns): `require("dist/cli.js")` cost 623 ms against a 42 ms bare Node start,
+ * and a real `run-program` spawn cost 610-661 ms. A shell hook doing the same job
+ * costs ~12 ms.
+ *
+ * So `src/cli.ts` is now a dispatcher shim that `require`s THIS file for
+ * `hook-runtime run-program` and the verb barrel for everything else. The
+ * emitted command is unchanged and MUST stay unchanged — it is baked into every
+ * already-emitted settings block and into the SHA stamp beside each hook.
+ *
+ * KEEP THIS MODULE'S TOP-LEVEL IMPORTS MINIMAL. Everything imported here is paid
+ * on every gated tool call. Two deliberately-lazy edges, each with the measurement
+ * at its call site: `@iarna/toml` (compile-time only, in `core/hook-program.ts`
+ * and `hook-install.ts`) and `mvdan-sh` (bash predicates only, in
+ * `core/bash-effects.ts`). `src/hook-runtime-graph.test.ts` asserts the graph
+ * deterministically, because a timing threshold on a shared CI runner would be
+ * flaky and would be the first thing quarantined.
+ *
+ * Harness-neutral: the gate protocol (deny → exit 2) is byte-identical on Claude
+ * Code and Codex, and the ONE harness-specific fact the runtime needs — which
+ * events accept injected context — is read from the resolved adapter's
+ * `HookProtocol.injectableEvents`, never a literal. That resolution is itself a
+ * lazy `require` because only the react role needs it (the adapter registry
+ * measured 279 ms on its own).
+ *
+ * This is COMPOSITION-ROOT code (`src/` root), not `src/core/`: it does real I/O
+ * (stdin, the stamp sidecar, state writes, `spawnSync`) and reaches the adapter
+ * registry, so `core ⊄ adapter` keeps it out of the domain layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadHookProgram = void 0;
+exports.loadProvider = loadProvider;
+exports.hookStampPath = hookStampPath;
+exports.runHookProgramCommand = runHookProgramCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const hook_program_js_1 = require("./core/hook-program.js");
+const merge_conflict_js_1 = require("./core/merge-conflict.js");
+const hook_install_js_1 = require("./hook-install.js");
+const hook_providers_js_1 = require("./core/hook-providers.js");
+const hook_state_store_js_1 = require("./hook-state-store.js");
+const observe_js_1 = require("./observe.js");
+const load_hook_js_1 = require("./load-hook.js");
+/**
+ * Which events accept injected context, from the ACTIVE adapter — the one
+ * harness-specific fact a react needs, read through the `HookProtocol` port so
+ * this stays harness-neutral (never a Claude Code literal).
+ *
+ * LAZY on purpose: `./adapter-registry.js` pulls every registered adapter and
+ * its ports, and measured 279 ms to require on its own (2026-09-08, Node
+ * 22.22.2) — more than the whole rest of this module's graph. Only the REACT
+ * role needs it; a gate or an inject must not pay for it.
+ */
+function injectableEventsFor(root) {
+    const { resolveAdapter } = require("./adapter-registry.js");
+    return resolveAdapter(root).hookProtocol?.injectableEvents ?? [];
+}
+/**
+ * Load a compiled-hook program's default export — the SHARED loader, also the
+ * public `vigiles` `loadHook` a `.harness.mjs` test uses, so a hook that
+ * loads in a test loads identically here (one loader, no drift).
+ */
+exports.loadHookProgram = load_hook_js_1.loadHook;
+/** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
+async function loadProvider(file) {
+    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+    const { pathToFileURL } = require("node:url");
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(abs).href));
+    }
+    catch (e) {
+        throw new hook_program_js_1.HookCompileError(`Cannot load provider "${file}": ${e.message}`);
+    }
+    const def = mod.default?.default ?? mod.default;
+    if (!def ||
+        typeof def !== "object" ||
+        def.kind !== "provider-def") {
+        throw new hook_program_js_1.HookCompileError(`${file} has no default-exported provider ` +
+            `(use \`export default defineProvider({…})\`).`);
+    }
+    return def;
+}
+/** Path of the tamper-evident stamp sidecar for a hook file. */
+function hookStampPath(file) {
+    return (0, node_path_1.resolve)(process.cwd(), ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
+}
+/**
+ * Perform the state writes a hook declared, after its output has been emitted.
+ * A refused write (a hand-built record object with a key `record()` would have
+ * thrown on) is announced — silence here would be a hook that believes it
+ * remembered something.
+ */
+function applyHookWrites(file, outcome) {
+    const { ok, refused } = (0, hook_program_js_1.outcomeWrites)(outcome);
+    for (const name of refused) {
+        console.error(`vigiles: refused to record ${name} from ${file} — not a valid state key.`);
+    }
+    for (const w of ok) {
+        try {
+            (0, hook_state_store_js_1.writeHookState)(file, w);
+        }
+        catch (e) {
+            console.error(`vigiles: could not record ${w.name} from ${file}: ${String(e)}`);
+        }
+    }
+}
+/**
+ * Gather a gate's DECLARED context providers (the trusted-host I/O step). Runs
+ * each declared read-only command via execSync in the hook's cwd; a provider
+ * that can't resolve yields its default (never throws). The pure registry +
+ * decision logic live in core/hook-providers.ts — this only injects the real IO.
+ */
+async function gatherHookContext(program, file) {
+    const needs = (0, hook_program_js_1.hookNeeds)(program);
+    if (needs.length === 0)
+        return {};
+    // Only load the registered-provider registry if a provider() ref is declared.
+    const hasRef = needs.some((n) => typeof n !== "string" && n.kind === "provider-ref");
+    const registry = hasRef ? await loadProviderRegistry() : {};
+    const { execSync } = require("node:child_process");
+    const { isCI } = require("ci-info");
+    return (0, hook_providers_js_1.gatherContext)(needs, {
+        exec: (command) => execSync(command, {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }),
+        cwd: process.cwd(),
+        platform: process.platform,
+        isCI,
+        // The namespace is bound HERE, from the hook's own path — core never sees
+        // it, so no key a hook can spell reaches another owner's store.
+        readState: (key) => (0, hook_state_store_js_1.readHookState)(file, key),
+        now: Date.now(),
+    }, registry);
+}
+/**
+ * Load the registered providers (`.vigiles/providers/`) into a name→def registry
+ * for `provider()` ref resolution. A bad/unloadable provider file is skipped (the
+ * ref then yields its default ""), never crashes a live session.
+ */
+async function loadProviderRegistry() {
+    const registry = {};
+    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+        try {
+            const def = await loadProvider(file);
+            registry[def.name] = def;
+        }
+        catch {
+            /* skip an unloadable provider file */
+        }
+    }
+    return registry;
+}
+/** Append an observe-mode record to `.vigiles/hook-observations.jsonl` (best-effort). */
+function recordObservation(file, on, would, reason) {
+    try {
+        const dir = (0, node_path_1.resolve)(process.cwd(), ".vigiles");
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            hook: file,
+            event: on,
+            would,
+            reason,
+        }) + "\n";
+        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, "hook-observations.jsonl"), line);
+    }
+    catch {
+        /* recording is best-effort — never let it break a live session */
+    }
+}
+/**
+ * Emit a gate Decision in the harness protocol — the author never writes it.
+ * `observe` mode turns a would-be block/ask into a recorded no-op (exit 0): the
+ * shadow/rollout path. Harness-neutral — exit 2 / exit 0 are identical on Claude
+ * Code and Codex; the record is vigiles-local.
+ */
+function emitGate(decision, on, mode, file) {
+    const action = (0, hook_program_js_1.gateAction)(decision, mode);
+    switch (action.kind) {
+        case "block":
+            (0, observe_js_1.appendObservation)({
+                kind: "hook",
+                event: on,
+                decision: "deny",
+                mode: "enforce",
+                rule: file,
+                reason: action.reason,
+            });
+            console.error(action.reason);
+            process.exit(2);
+            return;
+        case "ask":
+            (0, observe_js_1.appendObservation)({
+                kind: "hook",
+                event: on,
+                decision: "ask",
+                mode: "enforce",
+                rule: file,
+                reason: action.reason,
+            });
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: on,
+                    permissionDecision: "ask",
+                    permissionDecisionReason: action.reason,
+                },
+            }) + "\n");
+            return;
+        case "observe":
+            (0, observe_js_1.appendObservation)({
+                kind: "hook",
+                event: on,
+                decision: action.would,
+                mode: "observe",
+                rule: file,
+                reason: action.reason,
+            });
+            recordObservation(file, on, action.would, action.reason);
+            console.error(`⚠ [vigiles observe] ${on}: would ${action.would} — ${action.reason}`);
+            return; // exit 0 — observe never blocks
+        case "allow":
+            return; // emit nothing, exit 0
+    }
+}
+/**
+ * Every `package.json` between the hook file and the filesystem root, plus the
+ * project's `.vigilesrc.json` — the files Node and the runtime must PARSE for a
+ * compiled hook to load at all. Repo-relative-ish paths, for a message.
+ *
+ * Walking UP is not decoration: `vigiles/hook` is a bare specifier, so Node reads
+ * the nearest `package.json` (and every one above it) while resolving it. The
+ * observed wedge came from a `package.json` the author was not thinking about at
+ * the time — it had merge-conflict markers in it, nothing to do with hooks.
+ */
+function hookLoadPathFiles(hookFile) {
+    const files = [];
+    let dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(process.cwd(), hookFile));
+    for (;;) {
+        const pkg = (0, node_path_1.resolve)(dir, "package.json");
+        files.push(pkg);
+        // 🔴 THE WALK STOPS AT THE FIRST ONE THAT EXISTS, and this list is now also
+        // the set of writes the repair door accepts, so its length is a blast
+        // radius. Unbounded, it reached `/home/package.json` and `/package.json` —
+        // files Node never opens once a nearer one is found. MEASURED against this
+        // runtime, hook at `gp/p/repo/.claude/hooks/`, conflict markers planted at
+        // one ancestor:
+        //
+        //   repo pkg PRESENT , parent conflicted        → loads fine
+        //   repo pkg absent  , parent conflicted        → WEDGES (cause: ../package.json)
+        //   repo pkg absent  , parent absent, gp broken → WEDGES (cause: ../../package.json)
+        //   repo pkg PRESENT , parent absent, gp broken → loads fine
+        //   repo pkg absent  , parent HEALTHY, gp broken→ loads fine
+        //
+        // A missing one is still pushed before the check: `package.json` may be the
+        // file the author has to CREATE, and it is the commonest repair of all.
+        if ((0, node_fs_1.existsSync)(pkg))
+            break;
+        const up = (0, node_path_1.dirname)(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    files.push((0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json"));
+    return files;
+}
+/**
+ * The conflicted files on this hook's load path, if any — the difference between
+ * "your hook is broken" and "your repo is mid-merge and the hook is collateral".
+ */
+function conflictedLoadPathFiles(hookFile) {
+    return hookLoadPathFiles(hookFile)
+        .filter((p) => {
+        try {
+            return ((0, node_fs_1.existsSync)(p) && (0, merge_conflict_js_1.hasMergeConflictMarkers)((0, node_fs_1.readFileSync)(p, "utf-8")));
+        }
+        catch {
+            return false; // unreadable is a different problem; don't guess about it
+        }
+    })
+        .map((p) => (0, node_path_1.relative)(process.cwd(), p) || p);
+}
+/**
+ * Print the loud stderr banner that accompanies a REPAIR-only pass-through, and
+ * return true — the caller allows exactly this one tool call. Shared by the two
+ * refusal paths (stale stamp, unloadable program) so the wording can't drift.
+ */
+function announceRepairEscape(file, why) {
+    console.error(`vigiles: hook ${file} ${why}.\n` +
+        `vigiles: ALLOWING this one call because it is a repair or recovery action ` +
+        `(a write to ${file}, to ${hookStampPath(file)}, or to one of ` +
+        `${merge_conflict_js_1.HARNESS_CONFIG_FILES.join(", ")}) ` +
+        `— without this the gate blocks the only actions that can fix it.\n` +
+        `vigiles: every OTHER tool call stays BLOCKED until the hook loads again.`);
+    return true;
+}
+/**
+ * Fail closed if a stamp sidecar exists and the on-disk source no longer
+ * matches it — a hand-edit that smuggles in a capability breaks the stamp.
+ * No sidecar → run uncompiled (e.g. a test fixture or a not-yet-compiled hook).
+ *
+ * ONE exception, and it is loud: the author's own REPAIR action
+ * ({@link isStampRepairEvent}) is let through, or a repo WEDGES. A stale stamp on
+ * a PreToolUse Bash gate blocks every Bash command — including `vigiles compile`,
+ * the only command that regenerates the stamp — so a normal edit-compile cycle
+ * could paint you into a corner whose only escape was hand-editing
+ * `.claude/settings.json` to unwire the gate. Observed 2026-08-03.
+ */
+function verifyStampOrRefuse(file, event) {
+    const stampPath = hookStampPath(file);
+    if (!(0, node_fs_1.existsSync)(stampPath))
+        return;
+    try {
+        const { stamp } = JSON.parse((0, node_fs_1.readFileSync)(stampPath, "utf-8"));
+        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
+        if (stamp && !(0, hook_program_js_1.verifyHookStamp)(source, stamp)) {
+            if ((0, hook_program_js_1.isStampRepairEvent)(event, file, process.cwd())) {
+                announceRepairEscape(file, "does not match its compiled stamp");
+                return;
+            }
+            console.error(`vigiles: hook ${file} does not match its compiled stamp (tampered).\n` +
+                `vigiles: if YOU edited it, the way out is a FILE WRITE, not a command — ` +
+                `this refusal blocks the recompile too. Either edit ${file} back to what ` +
+                `was compiled, or clear its stamp by writing \`{}\` into ` +
+                `${stampPath}. The hook then runs UNSTAMPED but still ENFORCES, so ` +
+                `\`vigiles compile ${file}\` goes through the normal gate.`);
+            process.exit(2);
+        }
+    }
+    catch {
+        /* unreadable sidecar → don't block a live session on it */
+    }
+}
+/**
+ * Say so, ON STDERR, when this event's path cannot be matched against a
+ * repo-relative prefix — an absolute `file_path` and no project root anywhere.
+ * The failure it announces is otherwise invisible: the hook runs, exits 0, and
+ * decides on nothing. Deliberately silent for a relative `file_path` (decidable
+ * without a root) so it cannot be mistaken for a react hook's `notice`.
+ */
+function warnIfPathUndecidable(event, root) {
+    const warning = (0, hook_program_js_1.undecidablePathWarning)(event.tool_input?.file_path, root);
+    if (warning !== undefined)
+        console.error(warning);
+}
+/**
+ * `vigiles hook-runtime run-program <file>` — the runtime the compiled hooks block
+ * points at. Reads the live event on stdin, loads the typed program, verifies
+ * its stamp, and dispatches by role: a gate exits 2 + reason on `deny`; an
+ * inject prints `additionalContext`; a react runs its effect-classified
+ * command. A hook that won't load — or whose stamp is stale — fails CLOSED
+ * (exit 2), never silent-allow, with two loudly-announced exceptions: the repair
+ * action itself ({@link isStampRepairEvent}), and — on a LOAD failure only — the
+ * load-path repair WRITE ({@link isLoadPathRepairEvent}), or the repo wedges
+ * with no way to fix whatever broke the load path.
+ */
+async function runHookProgramCommand(file) {
+    if (!file) {
+        console.error("Usage: vigiles hook-runtime run-program <hook-file>");
+        process.exit(2);
+        return;
+    }
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let event = {};
+    try {
+        event = JSON.parse(raw);
+    }
+    catch {
+        /* malformed → empty event */
+    }
+    // The root repo-relative path prefixes resolve against. `$CLAUDE_PROJECT_DIR`
+    // first (the same root the harness resolved THIS hook's own path against),
+    // then the payload's `cwd`; never `process.cwd()`, which under a git worktree
+    // can be a different checkout. See `projectRootOf`.
+    const projectRoot = (0, hook_program_js_1.projectRootOf)(event, process.env);
+    let program;
+    try {
+        program = await (0, exports.loadHookProgram)(file);
+    }
+    catch {
+        // A LOAD failure is a fact about the harness, not a verdict about the
+        // command that happened to arrive — so it must still fail CLOSED (a gate
+        // that cannot run must not wave traffic through), but the two things it owes
+        // the author are different from a `deny`'s: name the real cause, and leave a
+        // way back.
+        //
+        // Escapes, both announced loudly on stderr:
+        //   - the stale-stamp one (an edit to the hook itself / `vigiles compile`),
+        //     for the hook broken mid-edit;
+        //   - the RECOVERY set, for the case where the hook is fine and something
+        //     else on its load path is not (observed 2026-08-10: `package.json` left
+        //     holding merge-conflict markers → Node can't resolve `vigiles/hook` →
+        //     no compiled hook loads → the Bash gate refuses `git merge --abort`,
+        //     the one command that undoes the cause. Irreversible from inside the
+        //     session; it was fixed by hand-editing the JSON, because file tools do
+        //     not go through PreToolUse(Bash)).
+        // Everything else stays BLOCKED, and the escapes are whitelists of commands
+        // that are WRITES — see `isLoadPathRepairEvent` for why no command is one.
+        const conflicted = conflictedLoadPathFiles(file);
+        const cause = conflicted.length > 0
+            ? `cannot be loaded — ${conflicted.join(", ")} contains merge-conflict ` +
+                `markers, so Node cannot resolve \`vigiles/hook\` from it (the hook itself ` +
+                `may be fine)`
+            : "cannot be loaded";
+        if ((0, hook_program_js_1.isLoadPathRepairEvent)(event, file, {
+            // The root the REST of this runtime already uses: `hookStampPath` and
+            // `verifyStampOrRefuse` read the hook and its sidecar via `process.cwd()`,
+            // so a repair accepted against any other root would name a file the
+            // runtime never reads. The hook's own path cannot supply it (a hook sits
+            // at any depth, and a `.git` probe would be a disk read core does not do).
+            root: process.cwd(),
+            loadPathFiles: hookLoadPathFiles(file),
+        })) {
+            announceRepairEscape(file, cause);
+            return;
+        }
+        console.error(`vigiles: hook ${file} ${cause}.\n` +
+            `vigiles: this is the state of the HARNESS, not a decision about your ` +
+            `command — the gate never ran. Blocking anyway (a gate that cannot run ` +
+            `must not pass traffic).\n` +
+            `vigiles: the way out is a FILE WRITE, not a command — under a tool that ` +
+            `WRITES (Write/Edit/MultiEdit); a Read of the same path repairs nothing ` +
+            `and is refused. Fix whichever of ` +
+            `${file}, ${merge_conflict_js_1.HARNESS_CONFIG_FILES.join(", ")} is broken — those writes are ` +
+            `allowed even while this refuses, and a Bash gate never gated file tools ` +
+            `at all. The hook then loads and the gate decides normally again.\n` +
+            `vigiles: those paths resolve under ${process.cwd()} — plus any ancestor ` +
+            `\`package.json\` Node actually reads, so whatever is named above as the ` +
+            `cause is writable. A path in a DIFFERENT checkout is refused: it cannot ` +
+            `repair this failure.\n` +
+            `vigiles: no command is allowed, deliberately. \`git merge --abort\` and ` +
+            `\`git checkout\` RUN \`.git/hooks/*\` (measured: reference-transaction, ` +
+            `post-checkout), and \`vigiles compile\` loads the hook through the same ` +
+            `resolver that just failed.`);
+        process.exit(2);
+        return;
+    }
+    verifyStampOrRefuse(file, event);
+    switch ((0, hook_program_js_1.dispatchKind)(program)) {
+        case "inject": {
+            const ctx = await gatherHookContext(program, file);
+            const injection = (0, hook_program_js_1.injectionOf)(program, event, ctx);
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: program.on,
+                    additionalContext: injection.context,
+                },
+            }) + "\n");
+            // Writes land AFTER the output is emitted: a hook that recorded "I spoke"
+            // must not have recorded it if emitting threw.
+            applyHookWrites(file, {
+                kind: "injection",
+                context: injection.context,
+                records: injection.records,
+            });
+            return;
+        }
+        case "react": {
+            const ctx = await gatherHookContext(program, file);
+            warnIfPathUndecidable(event, projectRoot);
+            const reaction = (0, hook_program_js_1.runReact)(program, event, ctx, projectRoot);
+            // A notice has to REACH someone. stderr at exit 0 goes to the debug log
+            // and nothing else (the host's docs are explicit: "Claude never sees it"),
+            // and a react always exits 0 because its type has no `deny` — so stderr
+            // alone delivered nowhere. Emit the same `additionalContext` shape the
+            // shipped refs/eval-lock nudges use, gated on the ACTIVE adapter's
+            // `injectableEvents` so this is per-harness fact, not a CC literal.
+            const injectable = injectableEventsFor(projectRoot ?? process.cwd());
+            const delivery = (0, hook_program_js_1.noticeDelivery)(reaction, program.on, injectable);
+            if (delivery.kind === "inject") {
+                process.stdout.write(JSON.stringify({
+                    hookSpecificOutput: {
+                        hookEventName: program.on,
+                        additionalContext: delivery.context,
+                    },
+                }) + "\n");
+            }
+            // The stderr copy STAYS, deliberately. It is what the debug log and every
+            // `runHook`-based probe already read, it costs nothing, and on an event
+            // this harness does not inject it is the only trace that exists at all.
+            // Removing it would break existing consumers to gain nothing.
+            if (reaction.kind === "notice")
+                console.error(reaction.message);
+            applyHookWrites(file, { kind: "reaction", reaction });
+            if (reaction.kind === "run") {
+                const { spawnSync } = require("node:child_process");
+                const res = spawnSync(reaction.command, {
+                    shell: true,
+                    stdio: "inherit",
+                });
+                process.exit(res.status ?? 0);
+            }
+            return;
+        }
+        case "file-gate": {
+            const ctx = await gatherHookContext(program, file);
+            warnIfPathUndecidable(event, projectRoot);
+            emitGate((0, hook_program_js_1.decideFileGate)(program, event, ctx, projectRoot), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+        case "bash-gate": {
+            const ctx = await gatherHookContext(program, file);
+            // The same `projectRoot` the file gates get: without it every
+            // repo-relative prefix in a DENYLIST matcher (`touches`/`writesTo`) is
+            // matched by over-blocking alone, and with it an absolute token is placed
+            // exactly. Measured bypass this closes: `sed -i s/a/b/ <abs>/paper.tex`
+            // exited 0 against a guard that blocked the relative spelling.
+            emitGate((0, hook_program_js_1.decideProgram)(program, event, ctx, projectRoot), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+        case "prompt-gate": {
+            const ctx = await gatherHookContext(program, file);
+            emitGate((0, hook_program_js_1.decidePromptGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+        case "stop-gate": {
+            const ctx = await gatherHookContext(program, file);
+            emitGate((0, hook_program_js_1.decideStopGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+    }
+}
+//# sourceMappingURL=hook-runtime.js.map

package/dist/hook.d.ts

@@ -49,7 +49,7 @@
  * entirely (#45427 / #32376 — a Bash heredoc instead of `Write`), so a gate is a
  * strong default and is NEVER an unbypassable wall. See `docs/compiled-hooks.md`.
  */
-export { experimental_defineHook, experimental_defineFileGate, experimental_definePromptGate, experimental_defineStopGate, tool, 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";
+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";
 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";
 export { provide, dangerously, defineProvider, provider, } from "./core/hook-providers.js";
 export { state, record, stateFact, isValidStateKey, isStateNeed, isStateWrite, admissibleWrites, durationSeconds, HookStateError, } from "./core/hook-state.js";

package/dist/hook.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isStateWrite = exports.isStateNeed = exports.isValidStateKey = exports.stateFact = exports.record = exports.state = exports.provider = exports.defineProvider = exports.dangerously = exports.provide = exports.HookCompileError = exports.verifyHookStamp = exports.stampHook = exports.checkHookImports = exports.compileHookProgram = exports.invalidToolPatterns = exports.matchesTool = exports.outcomeWrites = exports.injectionOf = exports.hookNeeds = exports.hookRouting = exports.dispatchKind = exports.decisionExitCode = exports.runHookProgram = exports.runReact = exports.runInject = exports.decideStopGate = exports.decidePromptGate = exports.decideFileGate = exports.decideProgram = exports.responseView = exports.nothing = exports.notice = exports.run = exports.experimental_defineReact = exports.inject = exports.experimental_defineInject = exports.hookMode = exports.gateAction = exports.pathView = exports.commandView = exports.ask = exports.deny = exports.allow = exports.tools = exports.tool = exports.experimental_defineStopGate = exports.experimental_definePromptGate = exports.experimental_defineFileGate = exports.experimental_defineHook = void 0;
-exports.leafCommandsNormalized = exports.HookStateError = exports.durationSeconds = exports.admissibleWrites = void 0;
+exports.admissibleWrites = exports.isStateWrite = exports.isStateNeed = exports.isValidStateKey = exports.stateFact = exports.record = exports.state = exports.provider = exports.defineProvider = exports.dangerously = exports.provide = exports.HookCompileError = exports.verifyHookStamp = exports.stampHook = exports.checkHookImports = exports.compileHookProgram = exports.invalidToolPatterns = exports.matchesTool = exports.outcomeWrites = exports.injectionOf = exports.hookNeeds = exports.hookRouting = exports.dispatchKind = exports.decisionExitCode = exports.runHookProgram = exports.runReact = exports.runInject = exports.decideStopGate = exports.decidePromptGate = exports.decideFileGate = exports.decideProgram = exports.responseView = exports.nothing = exports.notice = exports.run = exports.experimental_defineReact = exports.inject = exports.experimental_defineInject = exports.hookMode = exports.gateAction = exports.pathView = exports.commandView = exports.ask = exports.deny = exports.allow = exports.tools = exports.experimental_defineStopGate = exports.experimental_definePromptGate = exports.experimental_defineFileGate = exports.experimental_defineHook = void 0;
+exports.leafCommandsNormalized = exports.HookStateError = exports.durationSeconds = void 0;
 /**
  * `vigiles/hook` — the **closed vocabulary** for authoring a compiled hook.
  *
@@ -78,7 +78,6 @@ Object.defineProperty(exports, "experimental_defineHook", { enumerable: true, ge
 Object.defineProperty(exports, "experimental_defineFileGate", { enumerable: true, get: function () { return hook_program_js_1.experimental_defineFileGate; } });
 Object.defineProperty(exports, "experimental_definePromptGate", { enumerable: true, get: function () { return hook_program_js_1.experimental_definePromptGate; } });
 Object.defineProperty(exports, "experimental_defineStopGate", { enumerable: true, get: function () { return hook_program_js_1.experimental_defineStopGate; } });
-Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return hook_program_js_1.tool; } });
 Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return hook_program_js_1.tools; } });
 Object.defineProperty(exports, "allow", { enumerable: true, get: function () { return hook_program_js_1.allow; } });
 Object.defineProperty(exports, "deny", { enumerable: true, get: function () { return hook_program_js_1.deny; } });

package/dist/test-coverage.d.ts

@@ -173,7 +173,7 @@ export interface UntestedReport {
      */
     readonly staleRuns?: readonly StaleRun[];
     /**
-     * DETERMINISTIC coverage only — `*.harness.*`, plus any custom `testGlobs`.
+     * DETERMINISTIC coverage only — `*.harness.*`, plus any custom `include`.
      * Free, millisecond, every-push. Answers "does this gate still catch what it
      * claims?" (`*.test.*` has NOT counted since 15.x — see DEFAULT_TEST_GLOBS.)
      */
@@ -194,7 +194,7 @@ export interface TestCoverageOptions {
     /** Scan hook scripts referenced from plugin.json / settings.json. Default true. */
     readonly hooks?: boolean;
     /** Globs of test files that count as coverage. */
-    readonly testGlobs?: readonly string[];
+    readonly include?: readonly string[];
     /**
      * Which extension a GENERATED test gets. Detection (a tsconfig.json, a
      * typescript dependency) decides by default; this field exists only to
@@ -206,7 +206,7 @@ export interface TestCoverageOptions {
      * (or the `-subagent` / `-hook` twin — the three share their options). The
      * previous wording here said only "from `.vigilesrc.json`", which read as a
      * promise the CLI did not keep: `TestCoverageConfig` had no such key and
-     * `checkUntestedSurfaces` forwarded only `testGlobs`/`exclude`, so a configured
+     * `checkUntestedSurfaces` forwarded only `include`/`exclude`, so a configured
      * `mjs` was silently ignored on any TypeScript-shaped repo.
      */
     readonly testExtension?: string;