vigiles 27.3.0 → 28.0.0

package/dist/adapters/claude-code/adapter.js

@@ -14,7 +14,6 @@ const layout_js_1 = require("./layout.js");
 const runtime_js_1 = require("./runtime.js");
 const hook_protocol_js_1 = require("./hook-protocol.js");
 const model_mock_js_1 = require("./model-mock.js");
-const harness_test_js_1 = require("../../harness-test.js");
 exports.claudeCodeAdapter = {
     name: "claude-code",
     // The reference harness: every tier. Mockable transport (Anthropic SSE) and
@@ -30,7 +29,9 @@ exports.claudeCodeAdapter = {
     runtime: runtime_js_1.claudeCodeRuntime,
     hookProtocol: hook_protocol_js_1.claudeCodeHookProtocol,
     modelMock: model_mock_js_1.claudeCodeModelMock,
-    harnessTestDriver: harness_test_js_1.claudeCodeDriver,
+    // Imported inside the thunk, not at the top: a top-level import runs at module
+    // init and would pull the whole test/compiler graph back in.
+    harnessTestDriver: async () => (await import("../../harness-test.js")).claudeCodeDriver,
     detect(root) {
         // Most specific signal wins: a plugin manifest (3) > repo settings (2) >
         // a bare CLAUDE.md (1, weak — many tools also read it / AGENTS.md).

package/dist/adapters/codex/adapter.js

@@ -20,7 +20,6 @@ const layout_js_1 = require("./layout.js");
 const runtime_js_1 = require("./runtime.js");
 const hook_protocol_js_1 = require("./hook-protocol.js");
 const model_mock_js_1 = require("./model-mock.js");
-const driver_js_1 = require("./driver.js");
 exports.codexAdapter = {
     name: "codex",
     // Full convergence with Claude Code: mockable (Responses SSE) + shell hooks
@@ -38,7 +37,7 @@ exports.codexAdapter = {
     runtime: runtime_js_1.codexRuntime,
     hookProtocol: hook_protocol_js_1.codexHookProtocol,
     modelMock: model_mock_js_1.codexModelMock,
-    harnessTestDriver: driver_js_1.codexDriver,
+    harnessTestDriver: async () => (await import("./driver.js")).codexDriver,
     detect(root) {
         // A `.codex/config.toml` is a strong signal; a bare AGENTS.md is weak (many
         // harnesses read it). (Unused while unregistered — kept for symmetry.)

package/dist/cli-main.js

@@ -5252,6 +5252,45 @@ function annotateLintForGitHub(report, flags) {
         ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
     }
 }
+/**
+ * The project root a `hook-runtime` rail acts on — NEVER `process.cwd()` first.
+ *
+ * These rails are a SECOND execution path, wired by hand into a hooks config
+ * (`npx vigiles hook-runtime <kind>`), and every one of them used to ask
+ * `process.cwd()` where the project was. The hook process has no stable cwd: a
+ * git worktree, or a session that has `cd`-ed into a subdirectory, stands
+ * somewhere the project's files are not, and then the state store writes its
+ * marker beside the wrong repo and `.vigiles/*.json` is simply not found. The
+ * failure is SILENT in the permissive direction — no gates loaded reads exactly
+ * like a project that declared none.
+ *
+ * Same order the compiled runtime uses (`projectRootOf`, core/hook-program.ts):
+ * `$CLAUDE_PROJECT_DIR` first — the harness resolved the hook's own path against
+ * it — then the event's own `cwd`, which Claude Code puts in every hook payload.
+ * `process.cwd()` stays as the documented LAST resort, for the rails a human or
+ * the model invokes as a plain command with no event and no env to go on.
+ *
+ * Pass the parsed event wherever stdin was already read; the handlers that take
+ * only an argument pass nothing and get the env answer.
+ */
+function runtimeRoot(event = {}) {
+    return (0, hook_program_js_1.projectRootOf)(event, process.env) ?? process.cwd();
+}
+/**
+ * The hook payload as a root SOURCE — `{}` when stdin was absent or malformed,
+ * which {@link runtimeRoot} reads as "this event offers no root" and falls
+ * through. Deliberately separate from each handler's own parse: a rail that
+ * cannot understand its event still knows where the project is, and a rail that
+ * only wants `tool_name` should not have to widen its own type to say so.
+ */
+function eventRoot(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Run a compiled skill's deterministic gate ladder: execute each step gate in
  * order (short-circuiting on the first failure), then the result gate. This is
@@ -5264,7 +5303,8 @@ function runSkillCommand(target) {
         console.error("Usage: vigiles hook-runtime run-skill <SKILL.md>");
         process.exit(2);
     }
-    const path = (0, node_path_1.resolve)(process.cwd(), target);
+    const root = runtimeRoot();
+    const path = (0, node_path_1.resolve)(root, target);
     if (!(0, node_fs_1.existsSync)(path)) {
         console.error(`Not found: ${target}`);
         process.exit(2);
@@ -5275,7 +5315,7 @@ function runSkillCommand(target) {
         return;
     }
     console.log(`Running gate ladder for ${target}:\n`);
-    const report = (0, skill_runtime_js_1.runSkillGates)(gates, process.cwd());
+    const report = (0, skill_runtime_js_1.runSkillGates)(gates, root);
     for (const r of report.results) {
         const label = r.at === "result" ? "result" : `step ${String(r.at)}`;
         console.log(`  ${r.ok ? "✓" : "✗"} ${label} — ${(0, skill_runtime_js_1.gateLabel)(r.gate)}`);
@@ -5303,11 +5343,12 @@ function runSkillCommand(target) {
  * feeds the message back to the model; exit 0 allows it and clears the marker.
  */
 function skillHookCommand() {
-    const decision = (0, skill_runtime_js_1.evaluateStopHook)(process.cwd());
+    const root = runtimeRoot();
+    const decision = (0, skill_runtime_js_1.evaluateStopHook)(root);
     if (decision.allow) {
         if (decision.message)
             console.log(decision.message);
-        (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+        (0, skill_runtime_js_1.clearActiveSkill)(root);
         return;
     }
     console.error(decision.message);
@@ -5319,12 +5360,20 @@ function skillStartCommand(target) {
         console.error("Usage: vigiles hook-runtime skill-start <SKILL.md>");
         process.exit(2);
     }
-    (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
+    const root = runtimeRoot();
+    (0, skill_runtime_js_1.setActiveSkill)(root, target);
     // Record the fire in the flight recorder: the skill NAME is the parent dir of
     // its SKILL.md (skills/<name>/SKILL.md), falling back to the raw target.
     const parts = target.replace(/\\/g, "/").split("/").filter(Boolean);
     const name = parts.length >= 2 ? parts[parts.length - 2] : (parts[0] ?? target);
-    (0, observe_js_1.appendObservation)({ kind: "skill", name, fired: true });
+    // The SAME root the decision above used. `appendObservation` defaults to
+    // `process.cwd()`, which is correct as a library default and wrong here: a
+    // hook does not run with a stable cwd, so the decision would land in the
+    // project while its record landed beside whatever directory the process
+    // happened to stand in. A ledger split across two directories is not untidy,
+    // it is wrong in a way that reads as normal — the file in the project looks
+    // complete, and nobody notices a flight recorder that is short.
+    (0, observe_js_1.appendObservation)({ kind: "skill", name, fired: true }, root);
     console.log(`Active skill: ${target}`);
 }
 /**
@@ -5357,7 +5406,7 @@ function skillToolHookCommand() {
     }
     if (!tool)
         return;
-    const decision = (0, skill_runtime_js_1.evaluateSkillPreToolUse)(process.cwd(), tool, command);
+    const decision = (0, skill_runtime_js_1.evaluateSkillPreToolUse)(runtimeRoot(eventRoot(raw)), tool, command);
     if (!decision.allow) {
         console.error(decision.message);
         process.exit(2);
@@ -5393,7 +5442,7 @@ function agentHookCommand() {
     catch {
         /* malformed input → no tool, allow */
     }
-    const cwd = process.cwd();
+    const cwd = runtimeRoot(eventRoot(raw));
     // EXPERIMENTAL (parked P3 — do NOT auto-wire). The spawn/SubagentStop bracketing
     // is now nesting-safe: a depth-aware STACK (push on dispatch, POP on SubagentStop)
     // closes the contract-escape the flat single-slot model allowed under CC v2.1.172
@@ -5425,13 +5474,15 @@ function agentHookCommand() {
         return;
     const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(cwd, tool, command);
     if (!decision.allow) {
+        // Same root as the decision — see `skillStartCommand` for why the default
+        // is wrong on a hook rail.
         (0, observe_js_1.appendObservation)({
             kind: "agent",
             name: (0, agent_runtime_js_1.readActiveAgent)(cwd) ?? "unknown",
             tool,
             allowed: false,
             reason: decision.message,
-        });
+        }, cwd);
         console.error(decision.message);
         process.exit(2);
     }
@@ -5476,7 +5527,7 @@ function guardHookCommand() {
     catch {
         /* no stdin */
     }
-    const { decision } = (0, guards_js_1.runGuardHook)(process.cwd(), raw);
+    const { decision } = (0, guards_js_1.runGuardHook)(runtimeRoot(eventRoot(raw)), raw);
     if (!decision.allow) {
         console.error(decision.reason ?? "Blocked by a vigiles guard.");
         process.exit(2);
@@ -5488,7 +5539,7 @@ function agentStartCommand(target) {
         console.error("Usage: vigiles hook-runtime agent-start <agents/<name>.md>");
         process.exit(2);
     }
-    (0, agent_runtime_js_1.pushActiveAgent)(process.cwd(), target);
+    (0, agent_runtime_js_1.pushActiveAgent)(runtimeRoot(), target);
     console.log(`Active agent: ${target}`);
 }
 /** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
@@ -5512,7 +5563,7 @@ async function handleHookRuntime(kind, restArgs) {
             agentStartCommand(restArgs[0]);
             return;
         case "agent-done":
-            (0, agent_runtime_js_1.popActiveAgent)(process.cwd());
+            (0, agent_runtime_js_1.popActiveAgent)(runtimeRoot());
             return;
         case "skill":
             skillHookCommand();
@@ -5524,7 +5575,7 @@ async function handleHookRuntime(kind, restArgs) {
             skillStartCommand(restArgs[0]);
             return;
         case "skill-done":
-            (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+            (0, skill_runtime_js_1.clearActiveSkill)(runtimeRoot());
             return;
         case "run-skill":
             runSkillCommand(restArgs[0]);
@@ -5545,11 +5596,11 @@ async function handleHookRuntime(kind, restArgs) {
             evalLockNudgeHookCommand();
             return;
         case "effect-enter":
-            (0, effect_region_js_1.setEffectActive)(process.cwd());
+            (0, effect_region_js_1.setEffectActive)(runtimeRoot());
             console.log("Effect boundary entered.");
             return;
         case "effect-exit":
-            (0, effect_region_js_1.clearEffectActive)(process.cwd());
+            (0, effect_region_js_1.clearEffectActive)(runtimeRoot());
             return;
         default:
             console.error(`vigiles hook-runtime: unknown runtime entrypoint "${kind ?? ""}". ` +
@@ -5580,7 +5631,8 @@ function actionHookCommand() {
     catch {
         /* malformed input → no event, allow */
     }
-    const decision = (0, action_gate_js_1.evaluateAction)(event, (0, action_gate_js_1.loadActionGates)(process.cwd()), process.cwd());
+    const root = runtimeRoot(eventRoot(raw));
+    const decision = (0, action_gate_js_1.evaluateAction)(event, (0, action_gate_js_1.loadActionGates)(root), root);
     if (!decision.allow) {
         console.error(decision.message);
         process.exit(2);
@@ -5624,7 +5676,7 @@ function evalLockNudgeHookCommand() {
     }
     if (!file)
         return;
-    const cwd = process.cwd();
+    const cwd = runtimeRoot(eventRoot(raw));
     const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
     // 🔴 THE SAME CONFIG `vigiles lint` READS. This used to pass `basePath` alone,
     // so a repo that had switched `untested-skill` off, or pointed `include` at
@@ -5638,7 +5690,7 @@ function evalLockNudgeHookCommand() {
     // second gate saying the same thing is a branch no test can distinguish from
     // its absence (measured — the mutation passed), i.e. the dead-fragment class
     // this same change removed from the runner table.
-    const config = (0, validate_js_1.loadConfig)();
+    const config = (0, validate_js_1.loadConfig)(cwd);
     const { options } = untestedRules(config);
     // 🔴 THE SAME LAYOUT `vigiles lint` RESOLVES, for the same reason as the config
     // above. This used to pass `basePath` alone, so the detector fell back to the
@@ -5701,10 +5753,12 @@ function refsHookCommand() {
     }
     if (!file || !isInstructionFile(file))
         return;
-    const severity = (0, types_js_1.ruleSeverity)((0, validate_js_1.loadConfig)().rules["unmarked-refs"]);
+    // Root first: the config read below is anchored on it, and reading the config
+    // from the process's directory is how a disabled rule comes back to life.
+    const cwd = runtimeRoot(eventRoot(raw));
+    const severity = (0, types_js_1.ruleSeverity)((0, validate_js_1.loadConfig)(cwd).rules["unmarked-refs"]);
     if (severity === false)
         return;
-    const cwd = process.cwd();
     const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
     let markdown;
     try {
@@ -5787,7 +5841,14 @@ async function installHookFile(file, adapter, registeredProviders = []) {
         // emitter never produced it. Measured 2026-09-10 in a consumer repo: after a compile,
         // one `cd` into a subdirectory made a PreToolUse gate fail to load, and a gate that
         // cannot load must block — the repo seized, every command refused including the repair.
-        gateCommand: `npx vigiles hook-runtime run-program ${(0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)}`,
+        //
+        // 🔴 AND LAUNCHED LOCALLY, NOT THROUGH `npx` — 193 ms against 2545 ms on a warm
+        // cache, thirteen times, on every tool call. The trailing `|| exit N` is what the
+        // shell does when that binary cannot start at all, and N is decided by the hook's
+        // ROLE: see `hookRuntimeRef` and `hookRuntimeMissingExit` for both measurements
+        // and for why a gate and a nudge must answer differently.
+        gateCommand: `${(0, hook_install_js_1.hookRuntimeRef)(adapter.layout.projectRootTokens)} hook-runtime run-program ` +
+            `${(0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)} || exit ${(0, hook_install_js_1.hookRuntimeMissingExit)((0, hook_program_js_1.dispatchKind)(program))}`,
         dialect: adapter.dialect,
         hookProtocol: adapter.hookProtocol,
         settingsFormat: adapter.layout.settingsFormat,

package/dist/core/adapter.d.ts

@@ -84,7 +84,28 @@ export interface HarnessAdapter {
      * one seam the runner dispatches through). Carried on the bundle so the runner
      * never imports a sibling adapter to find it.
      */
-    readonly harnessTestDriver?: HarnessTestDriver;
+    /**
+     * 🔴 A THUNK, NOT THE DRIVER, and the indirection is the whole point. A driver
+     * lives in `harness-test.ts`, which imports the conformance suite, which
+     * imports the compiler, which imports the cross-language symbol index, which
+     * loads a NATIVE binary. Holding the driver eagerly meant every consumer of an
+     * adapter paid for all of it — including the hook runtime, which reads only
+     * `dialect` and `hookProtocol` and never runs a harness test at all.
+     *
+     * Measured 2026-09-19, `require("./adapter-registry.js")`:
+     *
+     *     eager:  107 modules, 7 ast-grep, 1 native .node
+     *
+     * ...on a path whose actual work takes about a millisecond. Calling the thunk
+     * is what loads the driver, so the test tier pays and the runtime does not.
+     *
+     * ASYNC because a dynamic `import()` is the only form that defers in BOTH
+     * environments this code runs in: the CJS `dist/` build (where TypeScript
+     * lowers it to a deferred `require`) and vitest loading the TS sources
+     * directly, where a synchronous `require` of a sibling `.ts` does not resolve
+     * at all — measured, not assumed.
+     */
+    readonly harnessTestDriver?: () => Promise<HarnessTestDriver>;
     /**
      * How strongly a repo at `root` looks like it targets this harness — the CLI
      * uses it to auto-detect which adapter to use (the library selects by import).

package/dist/core/hook-program.d.ts

@@ -895,6 +895,49 @@ export interface RawHookEvent {
      */
     readonly cwd?: string;
 }
+/**
+ * A hook event whose project root has already been RESOLVED — the shape every
+ * consumer past the entry point takes.
+ *
+ * {@link RawHookEvent} is what arrives on stdin; this is what the runtime works
+ * with. The difference is one field, and that field is the whole point: with the
+ * root ON the event, an event and a root cannot be handed to different places
+ * and disagree. That divergence is not hypothetical. Measured 2026-09-19: the
+ * decision layer resolved against the payload while the tamper stamp resolved
+ * against `process.cwd()`, and under a git worktree the stamp check did not
+ * point at the wrong file — it returned silently and did not run at all.
+ *
+ * Threading the root as a second parameter beside the event fixes an instance
+ * and keeps the shape. A field removes the shape.
+ */
+export interface HookEvent extends RawHookEvent {
+    /**
+     * The project root, always usable — so no consumer repeats a `?? cwd` fallback
+     * and none can forget it.
+     */
+    readonly root: string;
+    /**
+     * Whether {@link root} came from the payload (`$CLAUDE_PROJECT_DIR` or the
+     * event's own `cwd`) or is the fallback standing in for a payload that
+     * declared none.
+     *
+     * 🔴 THIS IS THE FIELD A POLICY DECISION READS. What to do with an undeclared
+     * root differs by ROLE, not by call site: a gate that cannot locate the
+     * project is a gate that cannot decide, and a gate that cannot decide must
+     * refuse; a nudge in the same position must stay quiet, because a reminder is
+     * never worth a wedged repository. Collapsing both into one behaviour inside
+     * the resolver would make that choice unexpressible.
+     */
+    readonly rootDeclared: boolean;
+}
+/**
+ * Resolve a raw payload's project root ONCE, at the entry point.
+ *
+ * `fallback` is injected rather than read here, because this module does no IO
+ * and holds no ambient state — the caller supplies `process.cwd()`. That is what
+ * keeps `process.cwd()` to a single occurrence in the whole hook runtime.
+ */
+export declare function resolveHookEvent(raw: RawHookEvent, env: Readonly<Record<string, string | undefined>>, fallback: string): HookEvent;
 /** The normalized outcome of running a hook program — discriminated by role. */
 export type HookProgramOutcome = {
     readonly kind: "decision";

package/dist/core/hook-program.js

@@ -34,6 +34,7 @@ exports.injectionOf = injectionOf;
 exports.responseView = responseView;
 exports.experimental_defineReact = experimental_defineReact;
 exports.runReact = runReact;
+exports.resolveHookEvent = resolveHookEvent;
 exports.outcomeWrites = outcomeWrites;
 exports.rememberHookSource = rememberHookSource;
 exports.hookSource = hookSource;
@@ -717,6 +718,22 @@ function hookRouting(hook) {
         // A react MAY also be tool-less (Stop/SessionEnd) — same shape, same reason.
         if (hook.match === undefined)
             return { on: hook.on };
+        // 🔴 SAY WHAT IS WRONG, IN THE AUTHOR'S VOCABULARY. From a typed `.ts` hook
+        // this is unreachable — tsc rejects a `match` without `tools`. From a `.mjs`
+        // hook, which is a supported authoring format, nothing checks it, and
+        // reading `.tools.join` off the wrong shape used to surface as
+        // `Cannot read properties of undefined (reading 'join')`: a message that
+        // names an internal property of an internal function and points nowhere
+        // near the author's file. This repo has already paid twice for a diagnosis
+        // that sends the reader to the wrong place (the loader that advised
+        // `npm run build` when the answer was `npm install`; the bare "cannot be
+        // loaded"). A `HookCompileError` is also what the installer catches to
+        // print the FILE alongside the reason — a TypeError falls past it.
+        if (!Array.isArray(hook.match.tools)) {
+            throw new HookCompileError(`a ${hook.role} hook's \`match\` must be \`{ tools: [...] }\` — got ` +
+                `${JSON.stringify(hook.match)}. Use \`tools("Edit", "Write")\` to build it; ` +
+                `a path condition belongs in the gate's own predicate, not in \`match\`.`);
+        }
         return { on: hook.on, matcher: hook.match.tools.join("|") };
     }
     // Bash by construction — see decideProgram; the author no longer declares it.
@@ -1331,6 +1348,21 @@ function runReact(hook, raw, ctx = {}, root = typeof raw.cwd === "string" ? raw.
         ctx: ctx,
     });
 }
+/**
+ * Resolve a raw payload's project root ONCE, at the entry point.
+ *
+ * `fallback` is injected rather than read here, because this module does no IO
+ * and holds no ambient state — the caller supplies `process.cwd()`. That is what
+ * keeps `process.cwd()` to a single occurrence in the whole hook runtime.
+ */
+function resolveHookEvent(raw, env, fallback) {
+    const declared = projectRootOf(raw, env);
+    return {
+        ...raw,
+        root: declared ?? fallback,
+        rootDeclared: declared !== undefined,
+    };
+}
 /**
  * The state writes an outcome declares, filtered to the ones the runtime may
  * actually perform. A gate's `Decision` carries none — deliberately: a gate is

package/dist/core/validate.d.ts

@@ -19,7 +19,21 @@ export declare function normalizeSeverity(v: unknown): unknown;
  * A non-string/array value falls back with a warning (the `ruleMarkers` pattern).
  */
 export declare function asStringArray(v: unknown, fallback: readonly string[], key: string): readonly string[];
-export declare function loadConfig(): VigilesConfig;
+/**
+ * Read `.vigilesrc.json`.
+ *
+ * 🔴 `searchFrom` IS NOT A CONVENIENCE. cosmiconfig defaults to the process's
+ * working directory and walks up — right for a CLI verb, where the user is
+ * standing in the project they mean, and wrong for a hook, whose process has no
+ * stable cwd. A hook rail that omits it reads a DIFFERENT project's config, or
+ * none, and the failure runs the wrong way: a missing file means defaults, so a
+ * rule the author switched OFF comes back on, silently, because the file saying
+ * "off" was never found. Nothing in the output distinguishes that from a project
+ * that never configured the rule.
+ *
+ * Every CLI verb still calls this with no argument and is unaffected.
+ */
+export declare function loadConfig(searchFrom?: string): VigilesConfig;
 export declare function parseRules(content: string, { ruleMarkers }?: ParseOptions): ParsedRule[];
 export declare function validate(content: string, { ruleMarkers, rules: rulesConfig, filePath, dialect }?: ValidateOptions): ValidationResult;
 export declare function readInstructionFile(filePath: string, options?: ReadOptions): ReadResult;

package/dist/core/validate.js

@@ -172,13 +172,27 @@ function asStringArray(v, fallback, key) {
     console.warn(`Invalid ${key} in config: expected a string or string[], got ${JSON.stringify(v)}. Ignoring.`);
     return fallback;
 }
-function loadConfig() {
+/**
+ * Read `.vigilesrc.json`.
+ *
+ * 🔴 `searchFrom` IS NOT A CONVENIENCE. cosmiconfig defaults to the process's
+ * working directory and walks up — right for a CLI verb, where the user is
+ * standing in the project they mean, and wrong for a hook, whose process has no
+ * stable cwd. A hook rail that omits it reads a DIFFERENT project's config, or
+ * none, and the failure runs the wrong way: a missing file means defaults, so a
+ * rule the author switched OFF comes back on, silently, because the file saying
+ * "off" was never found. Nothing in the output distinguishes that from a project
+ * that never configured the rule.
+ *
+ * Every CLI verb still calls this with no argument and is unaffected.
+ */
+function loadConfig(searchFrom) {
     try {
         const explorer = (0, cosmiconfig_1.cosmiconfigSync)("vigiles", {
             searchPlaces: [".vigilesrc.json"],
             mergeSearchPlaces: false,
         });
-        const result = explorer.search();
+        const result = explorer.search(searchFrom);
         if (!result?.config)
             return { ...DEFAULT_CONFIG };
         const userConfig = result.config;

package/dist/harness-test.js

@@ -430,7 +430,7 @@ async function runHarnessTest(spec, opts = {}) {
     // Default (no adapter): the unchanged Claude Code driver — keeps the
     // sandbox/confined path and behaviour byte-for-byte identical.
     const driver = adapter
-        ? requireDriver(adapter)
+        ? await requireDriver(adapter)
         : exports.claudeCodeDriver;
     const isClaudeCode = driver.runtime.name === runtime_js_1.claudeCodeRuntime.name;
     const decision = (0, sandbox_js_1.decideSandbox)({
@@ -528,12 +528,12 @@ async function runHarness(spec, opts = {}) {
     return runHarnessTest(spec, opts);
 }
 /** Pull the pillar-2 driver off an adapter, asserting it supports testing. */
-function requireDriver(adapter) {
+async function requireDriver(adapter) {
     (0, adapter_conformance_js_1.assertHarnessTestable)(adapter);
     if (!adapter.harnessTestDriver) {
         throw new Error(`Adapter "${adapter.name}" declares harnessTesting but carries no harnessTestDriver — it cannot drive runHarnessTest.`);
     }
-    return adapter.harnessTestDriver;
+    return await adapter.harnessTestDriver();
 }
 /* v8 ignore stop */
 //# sourceMappingURL=harness-test.js.map

package/dist/hook-install.d.ts

@@ -1,3 +1,4 @@
+import type { DispatchKind } from "./core/hook-program.js";
 /** The agnostic, committed home for hook SOURCE — one dir, cross-adapter. */
 export declare const HOOKS_DIR = ".vigiles/hooks";
 /** The committed home for registered context-provider SOURCE (v2). */
@@ -55,6 +56,58 @@ export declare function normalizeHookRef(hookPath: string, cwd?: string): string
  * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
  * it is asserted directly rather than left to inspection.
  */
+/**
+ * Where the hook runtime lives, spelled so the shell can find it WITHOUT `npx`.
+ *
+ * 🔴 MEASURED 2026-09-19, warm cache, five runs each:
+ *
+ *     node <local>/dist/cli.js hook-runtime run-program …   193 ms
+ *     npx vigiles              hook-runtime run-program …  2545 ms
+ *
+ * Thirteen times, on every tool call, because `npx` re-resolves the package on
+ * each invocation — local, then global, then the registry. That search is the
+ * single largest cost in a hook's life; everything the runtime does inside adds
+ * up to less than a fifth of it.
+ *
+ * A harness with no project-root token gets the relative spelling, which is all
+ * it can be given — see {@link hookGateRef} for the same fallback.
+ */
+export declare function hookRuntimeRef(projectRootTokens: readonly string[] | undefined): string;
+/**
+ * What the shell must do when the runtime above CANNOT START — a missing
+ * `node_modules/vigiles`, an unreadable file, an interpreter that dies before a
+ * single line of ours runs. No code of ours executes in that case, so the policy
+ * has to be expressed in the emitted command or not at all.
+ *
+ * 🔴 THIS IS NOT A NEW POLICY. `runHookProgramCommand`'s load-failure branch has
+ * decided it since 2026-08: *"an inject's purpose is to ADD context, not to
+ * ENFORCE a decision … Gates (file, bash, prompt, stop) remain conservative and
+ * fail closed."* That branch only reaches failures that happen AFTER the runtime
+ * starts. This carries the same rule one layer out, to the failures that happen
+ * before it.
+ *
+ * WHY THE SPLIT, RATHER THAN ONE ANSWER FOR EVERYTHING — the two failures are
+ * not comparable:
+ *
+ *   A GATE THAT SILENTLY PASSES IS WORSE THAN NO GATE. Its whole value is the
+ *   refusal, and a harness that reports protection it is not providing is the
+ *   one state worse than admitting it has none. So a gate whose runtime is
+ *   missing exits 2: loud, blocking, and the cause is on stderr.
+ *
+ *   A NUDGE THAT BLOCKS COSTS THE WHOLE REPOSITORY. Measured here 2026-08-10:
+ *   merge-conflict markers in `package.json` stopped every hook loading, the
+ *   Bash gate then refused `git merge --abort` — the one command that undoes the
+ *   cause — and the session could not be repaired from inside. A reminder is
+ *   never worth that, so a nudge exits 0 and says nothing it cannot say.
+ *
+ * The role is not a flag someone can flip: `Reaction` has no `deny` and an
+ * inject returns context, so "nudge" is a fact about the TYPE the author chose.
+ *
+ * (Industry does not agree on one answer either — husky and lefthook skip,
+ * pre-commit fails. Which is itself the argument for deciding by role instead
+ * of picking one and imposing it on both.)
+ */
+export declare function hookRuntimeMissingExit(kind: DispatchKind): 0 | 2;
 export declare function hookGateRef(ref: string, projectRootTokens: readonly string[] | undefined): string;
 /**
  * Idempotently merge a compiled hook's block into an existing `settings.json`

package/dist/hook-install.js

@@ -4,6 +4,8 @@ exports.PROVIDERS_DIR = exports.HOOKS_DIR = void 0;
 exports.discoverHookFiles = discoverHookFiles;
 exports.discoverProviderFiles = discoverProviderFiles;
 exports.normalizeHookRef = normalizeHookRef;
+exports.hookRuntimeRef = hookRuntimeRef;
+exports.hookRuntimeMissingExit = hookRuntimeMissingExit;
 exports.hookGateRef = hookGateRef;
 exports.mergeHooksJson = mergeHooksJson;
 exports.mergeHooksToml = mergeHooksToml;
@@ -99,6 +101,64 @@ function normalizeHookRef(hookPath, cwd = process.cwd()) {
  * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
  * it is asserted directly rather than left to inspection.
  */
+/**
+ * Where the hook runtime lives, spelled so the shell can find it WITHOUT `npx`.
+ *
+ * 🔴 MEASURED 2026-09-19, warm cache, five runs each:
+ *
+ *     node <local>/dist/cli.js hook-runtime run-program …   193 ms
+ *     npx vigiles              hook-runtime run-program …  2545 ms
+ *
+ * Thirteen times, on every tool call, because `npx` re-resolves the package on
+ * each invocation — local, then global, then the registry. That search is the
+ * single largest cost in a hook's life; everything the runtime does inside adds
+ * up to less than a fifth of it.
+ *
+ * A harness with no project-root token gets the relative spelling, which is all
+ * it can be given — see {@link hookGateRef} for the same fallback.
+ */
+function hookRuntimeRef(projectRootTokens) {
+    const rel = "node_modules/vigiles/dist/cli.js";
+    const token = projectRootTokens?.[0];
+    return token === undefined ? `node ${rel}` : `node "${token}/${rel}"`;
+}
+/**
+ * What the shell must do when the runtime above CANNOT START — a missing
+ * `node_modules/vigiles`, an unreadable file, an interpreter that dies before a
+ * single line of ours runs. No code of ours executes in that case, so the policy
+ * has to be expressed in the emitted command or not at all.
+ *
+ * 🔴 THIS IS NOT A NEW POLICY. `runHookProgramCommand`'s load-failure branch has
+ * decided it since 2026-08: *"an inject's purpose is to ADD context, not to
+ * ENFORCE a decision … Gates (file, bash, prompt, stop) remain conservative and
+ * fail closed."* That branch only reaches failures that happen AFTER the runtime
+ * starts. This carries the same rule one layer out, to the failures that happen
+ * before it.
+ *
+ * WHY THE SPLIT, RATHER THAN ONE ANSWER FOR EVERYTHING — the two failures are
+ * not comparable:
+ *
+ *   A GATE THAT SILENTLY PASSES IS WORSE THAN NO GATE. Its whole value is the
+ *   refusal, and a harness that reports protection it is not providing is the
+ *   one state worse than admitting it has none. So a gate whose runtime is
+ *   missing exits 2: loud, blocking, and the cause is on stderr.
+ *
+ *   A NUDGE THAT BLOCKS COSTS THE WHOLE REPOSITORY. Measured here 2026-08-10:
+ *   merge-conflict markers in `package.json` stopped every hook loading, the
+ *   Bash gate then refused `git merge --abort` — the one command that undoes the
+ *   cause — and the session could not be repaired from inside. A reminder is
+ *   never worth that, so a nudge exits 0 and says nothing it cannot say.
+ *
+ * The role is not a flag someone can flip: `Reaction` has no `deny` and an
+ * inject returns context, so "nudge" is a fact about the TYPE the author chose.
+ *
+ * (Industry does not agree on one answer either — husky and lefthook skip,
+ * pre-commit fails. Which is itself the argument for deciding by role instead
+ * of picking one and imposing it on both.)
+ */
+function hookRuntimeMissingExit(kind) {
+    return kind === "inject" || kind === "react" ? 0 : 2;
+}
 function hookGateRef(ref, projectRootTokens) {
     const token = projectRootTokens?.[0];
     return token === undefined ? ref : `"${token}/${ref}"`;

package/dist/hook-runtime.d.ts

@@ -45,9 +45,9 @@ import { loadHook } from "./load-hook.js";
  */
 export declare const loadHookProgram: typeof loadHook;
 /** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
-export declare function loadProvider(file: string): Promise<RegisteredProvider>;
+export declare function loadProvider(file: string, root?: string): Promise<RegisteredProvider>;
 /** Path of the tamper-evident stamp sidecar for a hook file. */
-export declare function hookStampPath(file: string): string;
+export declare function hookStampPath(file: string, root?: 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

package/dist/hook-runtime.js

@@ -75,8 +75,8 @@ function injectableEventsFor(root) {
  */
 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);
+async function loadProvider(file, root = process.cwd()) {
+    const abs = (0, node_path_1.resolve)(root, file);
     const { pathToFileURL } = require("node:url");
     let mod;
     try {
@@ -95,8 +95,8 @@ async function loadProvider(file) {
     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");
+function hookStampPath(file, root = process.cwd()) {
+    return (0, node_path_1.resolve)(root, ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
 }
 /**
  * Perform the state writes a hook declared, after its output has been emitted.
@@ -104,14 +104,14 @@ function hookStampPath(file) {
  * thrown on) is announced — silence here would be a hook that believes it
  * remembered something.
  */
-function applyHookWrites(file, outcome) {
+function applyHookWrites(file, outcome, root) {
     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);
+            (0, hook_state_store_js_1.writeHookState)(file, w, { cwd: root });
         }
         catch (e) {
             console.error(`vigiles: could not record ${w.name} from ${file}: ${String(e)}`);
@@ -124,13 +124,13 @@ function applyHookWrites(file, outcome) {
  * 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) {
+async function gatherHookContext(program, file, root) {
     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 registry = hasRef ? await loadProviderRegistry(root) : {};
     const { execSync } = require("node:child_process");
     const { isCI } = require("ci-info");
     return (0, hook_providers_js_1.gatherContext)(needs, {
@@ -138,12 +138,12 @@ async function gatherHookContext(program, file) {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "ignore"],
         }),
-        cwd: process.cwd(),
+        cwd: root,
         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),
+        readState: (key) => (0, hook_state_store_js_1.readHookState)(file, key, root),
         now: Date.now(),
     }, registry);
 }
@@ -152,11 +152,11 @@ async function gatherHookContext(program, file) {
  * 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() {
+async function loadProviderRegistry(root) {
     const registry = {};
-    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+    for (const file of (0, hook_install_js_1.discoverProviderFiles)(root)) {
         try {
-            const def = await loadProvider(file);
+            const def = await loadProvider(file, root);
             registry[def.name] = def;
         }
         catch {
@@ -166,9 +166,9 @@ async function loadProviderRegistry() {
     return registry;
 }
 /** Append an observe-mode record to `.vigiles/hook-observations.jsonl` (best-effort). */
-function recordObservation(file, on, would, reason) {
+function recordObservation(file, on, would, reason, root) {
     try {
-        const dir = (0, node_path_1.resolve)(process.cwd(), ".vigiles");
+        const dir = (0, node_path_1.resolve)(root, ".vigiles");
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
         const line = JSON.stringify({
             ts: new Date().toISOString(),
@@ -189,7 +189,7 @@ function recordObservation(file, on, would, reason) {
  * 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) {
+function emitGate(decision, on, mode, file, root) {
     const action = (0, hook_program_js_1.gateAction)(decision, mode);
     switch (action.kind) {
         case "block":
@@ -200,7 +200,7 @@ function emitGate(decision, on, mode, file) {
                 mode: "enforce",
                 rule: file,
                 reason: action.reason,
-            });
+            }, root);
             console.error(action.reason);
             process.exit(2);
             return;
@@ -212,7 +212,7 @@ function emitGate(decision, on, mode, file) {
                 mode: "enforce",
                 rule: file,
                 reason: action.reason,
-            });
+            }, root);
             process.stdout.write(JSON.stringify({
                 hookSpecificOutput: {
                     hookEventName: on,
@@ -229,8 +229,8 @@ function emitGate(decision, on, mode, file) {
                 mode: "observe",
                 rule: file,
                 reason: action.reason,
-            });
-            recordObservation(file, on, action.would, action.reason);
+            }, root);
+            recordObservation(file, on, action.would, action.reason, root);
             console.error(`⚠ [vigiles observe] ${on}: would ${action.would} — ${action.reason}`);
             return; // exit 0 — observe never blocks
         case "allow":
@@ -247,9 +247,9 @@ function emitGate(decision, on, mode, file) {
  * 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) {
+function hookLoadPathFiles(hookFile, root) {
     const files = [];
-    let dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(process.cwd(), hookFile));
+    let dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(root, hookFile));
     for (;;) {
         const pkg = (0, node_path_1.resolve)(dir, "package.json");
         files.push(pkg);
@@ -275,15 +275,15 @@ function hookLoadPathFiles(hookFile) {
             break;
         dir = up;
     }
-    files.push((0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json"));
+    files.push((0, node_path_1.resolve)(root, ".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)
+function conflictedLoadPathFiles(hookFile, root) {
+    return hookLoadPathFiles(hookFile, root)
         .filter((p) => {
         try {
             return ((0, node_fs_1.existsSync)(p) && (0, merge_conflict_js_1.hasMergeConflictMarkers)((0, node_fs_1.readFileSync)(p, "utf-8")));
@@ -292,7 +292,7 @@ function conflictedLoadPathFiles(hookFile) {
             return false; // unreadable is a different problem; don't guess about it
         }
     })
-        .map((p) => (0, node_path_1.relative)(process.cwd(), p) || p);
+        .map((p) => (0, node_path_1.relative)(root, p) || p);
 }
 /**
  * Print the loud stderr banner that accompanies a REPAIR-only pass-through, and
@@ -321,14 +321,15 @@ function announceRepairEscape(file, why) {
  * `.claude/settings.json` to unwire the gate. Observed 2026-08-03.
  */
 function verifyStampOrRefuse(file, event) {
-    const stampPath = hookStampPath(file);
+    const { root } = event;
+    const stampPath = hookStampPath(file, root);
     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");
+        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(root, file), "utf-8");
         if (stamp && !(0, hook_program_js_1.verifyHookStamp)(source, stamp)) {
-            if ((0, hook_program_js_1.isStampRepairEvent)(event, file, process.cwd())) {
+            if ((0, hook_program_js_1.isStampRepairEvent)(event, file, root)) {
                 announceRepairEscape(file, "does not match its compiled stamp");
                 return;
             }
@@ -388,21 +389,39 @@ async function runHookProgramCommand(file) {
     catch {
         /* no stdin */
     }
-    let event = {};
+    let payload = {};
     try {
-        event = JSON.parse(raw);
+        payload = 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);
+    // 🔴 THE ROOT IS RESOLVED ONCE, HERE, AND RIDES ON THE EVENT. Everything below
+    // reads `event.root`; nothing recomputes it and nothing is handed a root
+    // beside an event it might disagree with. That disagreement is the defect
+    // this shape exists to prevent — the stamp sidecar, the hook's own source,
+    // the state store, the ledger and the provider registry each used to resolve
+    // against `process.cwd()` while the decision layer resolved against the
+    // payload, so under a worktree the tamper check did not misfire, it did not
+    // run at all.
+    //
+    // This is the only `process.cwd()` on the runtime's own execution path, and
+    // it is the documented last resort for a payload that declares no root. The
+    // two others in this file are back-compat defaults on exported helpers
+    // (`loadProvider`, `hookStampPath`) for callers outside the runtime; the
+    // runtime itself always passes a root and never takes them.
+    const event = (0, hook_program_js_1.resolveHookEvent)(payload, process.env, process.cwd());
+    const root = event.root;
+    // ⚠️ THE DECISION LAYER MUST NOT SEE THE FALLBACK, and this is not a detail.
+    // `pathView` treats an undefined root as "I cannot place this path" and errs
+    // toward SILENCE. Handing it `process.cwd()` instead would turn that silence
+    // into confident decisions measured against a directory nobody declared —
+    // quietly widening what gates fire on. IO paths need a usable root; verdicts
+    // need an honest one, and they are not the same question.
+    const declaredRoot = event.rootDeclared ? event.root : undefined;
     let program;
     try {
-        program = await (0, exports.loadHookProgram)(file);
+        program = await (0, exports.loadHookProgram)(file, root);
     }
     catch (err) {
         // A LOAD failure is a fact about the harness, not a verdict about the
@@ -430,7 +449,7 @@ async function runHookProgramCommand(file) {
         //     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 conflicted = conflictedLoadPathFiles(file, root);
         // 🔴 THE THROWN MESSAGE IS THE ONLY THING THAT NAMES THE REAL CAUSE when the
         // merge-conflict heuristic above does not fire. Without it this said just
         // "cannot be loaded" — a diagnosis that sends the reader looking in the wrong
@@ -444,13 +463,13 @@ async function runHookProgramCommand(file) {
                 `may be fine)`
             : `cannot be loaded — ${thrown}`;
         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),
+            // The root the REST of this runtime already uses — now the PROJECT's,
+            // not the process's. 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), so it is passed in.
+            root,
+            loadPathFiles: hookLoadPathFiles(file, root),
         })) {
             announceRepairEscape(file, cause);
             return;
@@ -466,7 +485,7 @@ async function runHookProgramCommand(file) {
             `${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 ` +
+            `vigiles: those paths resolve under ${root} — 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` +
@@ -494,7 +513,7 @@ async function runHookProgramCommand(file) {
     verifyStampOrRefuse(file, event);
     switch ((0, hook_program_js_1.dispatchKind)(program)) {
         case "inject": {
-            const ctx = await gatherHookContext(program, file);
+            const ctx = await gatherHookContext(program, file, root);
             const injection = (0, hook_program_js_1.injectionOf)(program, event, ctx);
             process.stdout.write(JSON.stringify({
                 hookSpecificOutput: {
@@ -508,20 +527,20 @@ async function runHookProgramCommand(file) {
                 kind: "injection",
                 context: injection.context,
                 records: injection.records,
-            });
+            }, root);
             return;
         }
         case "react": {
-            const ctx = await gatherHookContext(program, file);
-            warnIfPathUndecidable(event, projectRoot);
-            const reaction = (0, hook_program_js_1.runReact)(program, event, ctx, projectRoot);
+            const ctx = await gatherHookContext(program, file, root);
+            warnIfPathUndecidable(event, declaredRoot);
+            const reaction = (0, hook_program_js_1.runReact)(program, event, ctx, declaredRoot);
             // 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 injectable = injectableEventsFor(root);
             const delivery = (0, hook_program_js_1.noticeDelivery)(reaction, program.on, injectable);
             if (delivery.kind === "inject") {
                 process.stdout.write(JSON.stringify({
@@ -537,7 +556,7 @@ async function runHookProgramCommand(file) {
             // Removing it would break existing consumers to gain nothing.
             if (reaction.kind === "notice")
                 console.error(reaction.message);
-            applyHookWrites(file, { kind: "reaction", reaction });
+            applyHookWrites(file, { kind: "reaction", reaction }, root);
             if (reaction.kind === "run") {
                 const { spawnSync } = require("node:child_process");
                 const res = spawnSync(reaction.command, {
@@ -549,29 +568,29 @@ async function runHookProgramCommand(file) {
             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);
+            const ctx = await gatherHookContext(program, file, root);
+            warnIfPathUndecidable(event, declaredRoot);
+            emitGate((0, hook_program_js_1.decideFileGate)(program, event, ctx, declaredRoot), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
         case "bash-gate": {
-            const ctx = await gatherHookContext(program, file);
-            // The same `projectRoot` the file gates get: without it every
+            const ctx = await gatherHookContext(program, file, root);
+            // The same `declaredRoot` 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);
+            emitGate((0, hook_program_js_1.decideProgram)(program, event, ctx, declaredRoot), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             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);
+            const ctx = await gatherHookContext(program, file, root);
+            emitGate((0, hook_program_js_1.decidePromptGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             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);
+            const ctx = await gatherHookContext(program, file, root);
+            emitGate((0, hook_program_js_1.decideStopGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
     }

package/dist/load-hook.d.ts

@@ -20,5 +20,5 @@ import { type AnyHook } from "./core/hook-program.js";
  * @throws {HookCompileError} when the file can't be imported, or has no
  * default-exported hook program.
  */
-export declare function loadHook(file: string): Promise<AnyHook>;
+export declare function loadHook(file: string, root?: string): Promise<AnyHook>;
 //# sourceMappingURL=load-hook.d.ts.map

package/dist/load-hook.js

@@ -39,8 +39,8 @@ const hook_program_js_1 = require("./core/hook-program.js");
  * @throws {HookCompileError} when the file can't be imported, or has no
  * default-exported hook program.
  */
-async function loadHook(file) {
-    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+async function loadHook(file, root = process.cwd()) {
+    const abs = (0, node_path_1.resolve)(root, file);
     let mod;
     try {
         mod = (await import((0, node_url_1.pathToFileURL)(abs).href));

package/dist/run-hook.js

@@ -189,7 +189,23 @@ function runHookWith(command, input, opts, deps) {
             ran: false,
             conditionReason: verdict.why,
         };
-    const res = (0, run_script_js_1.runScriptWith)(command, JSON.stringify(input), opts, deps);
+    // 🔴 A SPAWN DIRECTORY WITH NO DECLARED ROOT MEANS "THIS DIRECTORY IS THE
+    // PROJECT". Without this, a test that says `{ cwd: dir }` and nothing else
+    // inherits whatever `$CLAUDE_PROJECT_DIR` the AMBIENT shell exports, and since
+    // the runtime prefers the env over the payload (see `projectRootOf`), the hook
+    // resolves a root the test never named. Measured 2026-09-19: five rail suites
+    // pass with the variable unset — which is CI, and this container — and fail
+    // when it is set, which is any run inside a live Claude Code session. That is
+    // a one-sided failure, invisible exactly where it would be caught.
+    //
+    // An EXPLICIT value always wins, including the empty string: a test that pins
+    // `CLAUDE_PROJECT_DIR: ""` is saying "no env root, resolve from the payload",
+    // and that case has its own coverage.
+    const rooted = opts.cwd !== undefined &&
+        !Object.prototype.hasOwnProperty.call(opts.env ?? {}, "CLAUDE_PROJECT_DIR")
+        ? { ...opts, env: { ...opts.env, CLAUDE_PROJECT_DIR: opts.cwd } }
+        : opts;
+    const res = (0, run_script_js_1.runScriptWith)(command, JSON.stringify(input), rooted, deps);
     const json = parseHookOutput(res.stdout);
     const { blocked, decision, haltsTurn, blockedBy } = decideHook(res.exitCode, json, protocol);
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "27.3.0",
+  "version": "28.0.0",
   "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.",
   "keywords": [
     "claude-code",