vigiles 26.0.1 → 26.2.0

package/dist/harness-resolve-hooks.mjs

@@ -1,50 +1,27 @@
 /**
- * Module-resolution hook for HARNESS scripts: make a bare `vigiles` import
- * resolve to the CLI's OWN installation.
+ * Module-resolution hook for HARNESS scripts (`vigiles test` / `vigiles eval`):
+ * make a bare `vigiles` import resolve to the CLI's OWN installation.
  *
- * 🔴 WHY. A harness file does `import { runHook } from "vigiles"`, so the
- * package has to sit in a `node_modules` Node can reach from that file. In a
- * repo that already has a `package.json`, the obvious way to put it there is
- * `npm install` in the root — which installs the whole dependency tree. Measured
- * by an adopter (#184): **840 packages in 2 minutes** where vigiles alone is 42
- * and about 90 MB; the other 798 were a model-eval framework and an agent SDK
- * that the gate — `lint` and `test`, both deterministic reads — never touches.
- * One run sat 11 minutes in that step before being cancelled. Their workaround
- * was installing into a directory outside the workspace and symlinking the tree
- * back in, which works and is not something every adopter should reinvent.
+ * The rescue itself — why it exists, what it refuses to touch — lives in
+ * `./self-resolve.mjs`, because the spec host registers the same branch from
+ * `./spec-hooks.mjs` and two copies of it is exactly the divergence that put
+ * `test` and `compile` on different answers to the same question.
  *
- * ⚠️ `NODE_PATH` does NOT solve this, and that was measured rather than assumed:
- * Node ignores it for ESM resolution, and a harness is ESM. So the only ways to
- * resolve a bare specifier from elsewhere are a real `node_modules` entry (the
- * symlink) or a resolver hook. This is the hook.
- *
- * Scope is deliberately narrow: ONLY the `vigiles` specifier and its subpaths,
- * and only when the normal resolution fails. A harness that has vigiles
- * installed locally keeps resolving to the local copy, so nothing changes for a
- * repo that already worked — this only fills the hole where resolution would
- * otherwise throw.
+ * What stays here is the hook PROTOCOL: try normal resolution first, and only
+ * consider the rescue on the way out of the failure.
  */
-import { createRequire } from "node:module";
-import { pathToFileURL } from "node:url";
-/** The CLI's own package root, handed in by the parent process. */
-const SELF = process.env.VIGILES_SELF_ROOT ?? "";
+import { resolveSelfSpecifier } from "./self-resolve.mjs";
 export async function resolve(specifier, context, nextResolve) {
     try {
         return await nextResolve(specifier, context);
     }
     catch (err) {
-        // Only rescue OUR specifier, and only after normal resolution failed, so a
-        // locally installed vigiles always wins and no other package is affected.
-        if (!SELF)
-            throw err;
-        if (specifier !== "vigiles" && !specifier.startsWith("vigiles/"))
+        // Only AFTER normal resolution failed, so a locally installed vigiles always
+        // wins and no other package is affected.
+        const rescued = resolveSelfSpecifier(specifier);
+        if (!rescued)
             throw err;
-        const require = createRequire(pathToFileURL(`${SELF}/package.json`));
-        // Resolve through the package's own `exports` map rather than guessing a
-        // file path, so a subpath like `vigiles/eval` obeys the same contract it
-        // would from a normal install.
-        const target = require.resolve(specifier, { paths: [SELF] });
-        return { url: pathToFileURL(target).href, shortCircuit: true };
+        return rescued;
     }
 }
 //# sourceMappingURL=harness-resolve-hooks.mjs.map

package/dist/hook-state-store.d.ts

@@ -0,0 +1,143 @@
+import { type Duration, type StateEntry, type StateFact, type StateWrite } from "./core/hook-state.js";
+/**
+ * The directory a hook's recorded facts live in — the SCOPE of `state()`/`record()`.
+ *
+ * Derived from the hook's own location and never from anything the hook said, so
+ * a key cannot address another owner's store: hooks shipped in the same directory
+ * share their facts (the requirement — one hook records, another reads), a
+ * vendored plugin's hooks get their own. The layout MIRRORS the hook's directory
+ * rather than slugging it, which keeps it injective and lets a human debugging a
+ * hook find the fact by walking the path they already know:
+ *
+ *   .claude/hooks/calendar-sync-record.hook.ts
+ *     → .vigiles/state/.claude/hooks/calendar.synced.json
+ *
+ * A hook outside the project (an absolute path elsewhere) falls back to a hash of
+ * its directory: still stable and still isolated, just not readable — which is the
+ * right trade for a case that should not happen in a project's own harness.
+ */
+export declare function hookStateDir(file: string, cwd?: string): string;
+/** Read one recorded fact for a hook, or `null` if it was never recorded. */
+export declare function readHookState(file: string, key: string, cwd?: string): StateEntry | null;
+/** Options for {@link writeHookState}. */
+export interface WriteHookStateOptions {
+    /** The project root the store hangs off. Default `process.cwd()`. */
+    readonly cwd?: string;
+    /**
+     * The instant to stamp. Default: now.
+     *
+     * The runtime never passes this — a fact it records happened just now, by
+     * definition. It exists for {@link experimental_hookState}'s `seed`, which
+     * must be able to write "four days ago" for a throttle test to have anything
+     * to test. Threading it through the REAL writer rather than letting a test
+     * build its own entry is what keeps the two in step.
+     */
+    readonly at?: Date;
+}
+/**
+ * Record one fact. Atomic: written to a temp file in the same directory and
+ * `rename()`d over, so a concurrent reader sees the whole old entry or the whole
+ * new one — never one write's value with another's timestamp. Distinct keys are
+ * distinct files and never interact at all.
+ */
+export declare function writeHookState(file: string, w: StateWrite, opts?: WriteHookStateOptions): void;
+/**
+ * Options for {@link HookStateHandle.seed}.
+ *
+ * Spelled out as a three-way union rather than `{value} & SeedWhen` so the whole
+ * type is IN this declaration: a public signature that names a type a consumer
+ * cannot import is a surface you can read but not write against. The union is
+ * also what makes `{ ago, at }` — two disagreeing answers to "when" — a tsc
+ * error; `seedInstant` throws on it as well, because harness tests are `.mjs`
+ * and a type does not run there.
+ */
+export type SeedStateOptions = 
+/** Recorded that long ago — the reason this exists (a throttle needs an OLD fact). */
+{
+    readonly value?: string;
+    readonly ago: Duration;
+    readonly at?: never;
+}
+/** Recorded at exactly this instant. */
+ | {
+    readonly value?: string;
+    readonly at: Date;
+    readonly ago?: never;
+}
+/** Recorded just now. */
+ | {
+    readonly value?: string;
+    readonly ago?: never;
+    readonly at?: never;
+};
+/**
+ * A handle on ONE hook's recorded facts — what {@link experimental_hookState}
+ * returns. Every method goes through the runtime's own store functions, so a
+ * seeded fact is indistinguishable from one the hook recorded itself.
+ */
+export interface HookStateHandle {
+    /**
+     * Where this hook's facts live. Exposed for a failure message ("no fact under
+     * …"), NOT as a path to build on — build on it and you are back to the
+     * hard-coded private path this handle exists to retire.
+     */
+    readonly dir: string;
+    /**
+     * Write a fact as if the hook had recorded it, then read it back through the
+     * real reader — so what you get is exactly what the hook will see, and a write
+     * that did not land cannot be mistaken for one that did.
+     *
+     * `ago` is the reason this exists: a throttle is only interesting against an
+     * OLD fact, and "old" is not something a test can produce by waiting.
+     *
+     * ```js
+     * const st = experimental_hookState(".vigiles/hooks/nag.mjs", { cwd });
+     * st.seed("retro.nagged", { ago: "4d" });   // → the hook speaks
+     * st.seed("retro.nagged", { ago: "10m" });  // → the hook stays quiet
+     * ```
+     */
+    seed(key: string, opts?: SeedStateOptions): StateFact;
+    /**
+     * Read a fact exactly as the hook's `e.ctx[key]` would — same `recorded` /
+     * `ageSeconds` / `fresherThan`. Never-recorded reads back as the total
+     * `Infinity` fact rather than throwing, because that is what the hook sees.
+     *
+     * Also the cheap way to drive the IN-PROCESS tier: the value it returns is a
+     * `StateFact`, which is what `runHookProgram(hook, event, ctx)` wants in `ctx`.
+     */
+    read(key: string): StateFact;
+    /**
+     * Forget the facts THIS hook recorded. A no-op when it recorded none.
+     *
+     * Scoped to this hook's own writes, because the store is shared per DIRECTORY
+     * — that sharing is what lets one hook read a fact another recorded — so a
+     * co-located hook's facts (and any entry with no recorded owner) are left
+     * untouched. When a test wants the whole store empty rather than this hook's
+     * share of it, give it a throwaway `cwd`: the store hangs off that root.
+     */
+    clear(): void;
+}
+/**
+ * Seed and read a compiled hook's named state from a test.
+ *
+ * @experimental — the store LAYOUT is not a stable contract (this handle exists
+ * so you never depend on it), and the hook vocabulary it serves is itself
+ * `experimental_`. See `docs/compiled-hooks.md` § Status / pending.
+ *
+ * Pass the hook file exactly as the wiring names it, and the same `cwd` the hook
+ * will run under — the store's location is derived from both, so a handle built
+ * with a different root points at a different (empty) store.
+ *
+ * ```js
+ * import { experimental_hookState, runHook } from "vigiles";
+ *
+ * const st = experimental_hookState(hookFile, { cwd });
+ * st.clear();
+ * st.seed("retro.nagged", { ago: "4d" });
+ * const r = runHook(`npx vigiles hook-runtime run-program ${hookFile}`, event, { cwd });
+ * ```
+ */
+export declare function experimental_hookState(hookFile: string, opts?: {
+    readonly cwd?: string;
+}): HookStateHandle;
+//# sourceMappingURL=hook-state-store.d.ts.map

package/dist/hook-state-store.js

@@ -0,0 +1,241 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hookStateDir = hookStateDir;
+exports.readHookState = readHookState;
+exports.writeHookState = writeHookState;
+exports.experimental_hookState = experimental_hookState;
+/**
+ * The named-state STORE — the one place on disk a compiled hook's facts live,
+ * and the one seam a test seeds them through.
+ *
+ * `src/core/hook-state.ts` is the pure MODEL of a fact (`record`, `state`,
+ * `stateFact`, the key charset). It reads no disk on purpose. This module is the
+ * other half: where a fact is written, under what name, and how a reader finds
+ * it again. It sits at the composition root rather than in `src/core/` because
+ * it touches the filesystem, and rather than in an adapter because nothing here
+ * is harness-specific — `.vigiles/state/` is vigiles's own directory on Claude
+ * Code, on Codex, and on whatever comes next.
+ *
+ * ## Why it is a module and not three private functions in `cli.ts`
+ *
+ * It WAS three private functions in `cli.ts` (`hookStateDir`, `readHookState`,
+ * `writeHookState`), exported nowhere and named in no `api-surface/*.api.md`.
+ * The consequence is quoted in `docs/compiled-hooks.md` as a reason the hook
+ * vocabulary still carries the `experimental_` prefix:
+ *
+ * > Testing a hook that uses named state is archaeology today. The runtime
+ * > derives the store's path from the hook's own location and validates the key
+ * > charset, so a test that wants to seed "this fact was recorded four days ago"
+ * > must reconstruct a private path. The dogfood repo does exactly that,
+ * > hard-coded, and it broke when the facts were renamed.
+ *
+ * A throttled hook's ONLY interesting behaviour is what it does with an old fact
+ * versus a fresh one, so a store nobody can seed is a hook nobody can test. The
+ * fix is not a second store for tests — that is the drift this repo's
+ * one-detector rule exists to forbid, and a seeder that agrees with a private
+ * path derivation only until someone edits the derivation is worth less than
+ * nothing, because it fails silently and green. {@link experimental_hookState}
+ * is a THIN handle over the SAME {@link writeHookState} / {@link readHookState}
+ * / {@link hookStateDir} the live runtime calls; there is no second
+ * implementation to keep in step. Same shape as `src/load-hook.ts`, which was
+ * lifted out of `cli.ts` for the same reason: the CLI and a test must agree, so
+ * they call one function.
+ *
+ * ## Why the handle is on `vigiles` and NOT on `vigiles/hook`
+ *
+ * `vigiles/hook` is the closed authoring vocabulary, and `checkHookImports`
+ * makes it the ONLY import a compiled hook may have. Its guarantee — stated at
+ * the top of `core/hook-state.ts` — is that a hook "cannot touch the filesystem:
+ * `record()` returns a VALUE… this API hands out no writer". Exporting a store
+ * writer there would hand out exactly that writer, to exactly the code the
+ * guarantee is about. So the seeding handle lives on the `vigiles` TEST root,
+ * beside `runHook`, `loadHook` and the `assertHook*` helpers, where a test can
+ * reach it and a hook cannot.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const hash_js_1 = require("./core/hash.js");
+const hook_state_js_1 = require("./core/hook-state.js");
+const hook_install_js_1 = require("./hook-install.js");
+/**
+ * The directory a hook's recorded facts live in — the SCOPE of `state()`/`record()`.
+ *
+ * Derived from the hook's own location and never from anything the hook said, so
+ * a key cannot address another owner's store: hooks shipped in the same directory
+ * share their facts (the requirement — one hook records, another reads), a
+ * vendored plugin's hooks get their own. The layout MIRRORS the hook's directory
+ * rather than slugging it, which keeps it injective and lets a human debugging a
+ * hook find the fact by walking the path they already know:
+ *
+ *   .claude/hooks/calendar-sync-record.hook.ts
+ *     → .vigiles/state/.claude/hooks/calendar.synced.json
+ *
+ * A hook outside the project (an absolute path elsewhere) falls back to a hash of
+ * its directory: still stable and still isolated, just not readable — which is the
+ * right trade for a case that should not happen in a project's own harness.
+ */
+function hookStateDir(file, cwd = process.cwd()) {
+    const dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, file));
+    const rel = (0, node_path_1.relative)(cwd, dir);
+    const inside = rel !== "" && !rel.startsWith("..") && !(0, node_path_1.isAbsolute)(rel);
+    return (0, node_path_1.resolve)(cwd, ".vigiles/state", inside ? rel : `external-${(0, hash_js_1.sha256short)(dir)}`);
+}
+/** Read one recorded fact for a hook, or `null` if it was never recorded. */
+function readHookState(file, key, cwd = process.cwd()) {
+    try {
+        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(hookStateDir(file, cwd), key + ".json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.value === "string" && typeof parsed.at === "string"
+            ? parsed
+            : null;
+    }
+    catch {
+        // Never recorded, unreadable, or corrupt — all "no fact", which `stateFact`
+        // turns into an infinite age, so the reading hook SPEAKS. Failing toward
+        // noise is the whole point; a store problem must never look like freshness.
+        return null;
+    }
+}
+/**
+ * Record one fact. Atomic: written to a temp file in the same directory and
+ * `rename()`d over, so a concurrent reader sees the whole old entry or the whole
+ * new one — never one write's value with another's timestamp. Distinct keys are
+ * distinct files and never interact at all.
+ */
+function writeHookState(file, w, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const dir = hookStateDir(file, cwd);
+    const target = (0, node_path_1.resolve)(dir, w.name + ".json");
+    const entry = {
+        value: w.value,
+        at: (opts.at ?? new Date()).toISOString(),
+        by: (0, hook_install_js_1.normalizeHookRef)(file, cwd),
+    };
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const tmp = `${target}.${String(process.pid)}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(entry, null, 2) + "\n");
+    (0, node_fs_1.renameSync)(tmp, target);
+}
+/**
+ * Forget the facts THIS hook recorded, leaving a co-located hook's alone.
+ *
+ * The store is keyed by DIRECTORY, not by file, and deliberately so: that
+ * sharing is what lets one hook declare `state("calendar.synced")` and read a
+ * fact another hook in the same folder recorded. So "delete the directory" and
+ * "forget this hook's facts" are different operations, and the recursive
+ * delete this replaced was the wrong one — a test following the documented
+ * `st.clear()` opener reset every co-located hook, and two tests seeding
+ * different hooks in one directory erased each other.
+ *
+ * Ownership is {@link StateEntry.by}, which {@link writeHookState} stamps from
+ * the hook's own path. It is the SAME derivation {@link hookStateDir} uses
+ * (`resolve` then `relative`), so a handle built with a relative spelling and a
+ * runtime invoked with an absolute one agree — verified against the live
+ * runtime in both directions in the colocated test, because a scope that only
+ * matched the writer a test happens to use would fail silently and green.
+ *
+ * An entry we cannot READ, or one carrying no `by` at all, is left in place:
+ * every write this module performs stamps an owner, so an unattributed entry
+ * was written by something else, and deleting it is exactly the collateral
+ * damage being removed here. It reads back as another owner's fact — seed over
+ * it, or point `cwd` at a throwaway root when a completely empty store is what
+ * the test wants.
+ *
+ * The directory itself is left behind, possibly empty. Removing it would race
+ * a concurrent test writing into the same shared directory, which is the class
+ * of interference this function exists to stop.
+ */
+function clearOwnState(file, cwd) {
+    const dir = hookStateDir(file, cwd);
+    const mine = (0, hook_install_js_1.normalizeHookRef)(file, cwd);
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        // Nothing was ever recorded here — the documented no-op.
+        return;
+    }
+    for (const name of entries) {
+        // A torn `<key>.json.<pid>.tmp` from an interrupted write is not an entry.
+        if (!name.endsWith(".json"))
+            continue;
+        const path = (0, node_path_1.resolve)(dir, name);
+        let owner;
+        try {
+            owner = JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8")).by;
+        }
+        catch {
+            continue;
+        }
+        if (owner === mine)
+            (0, node_fs_1.rmSync)(path, { force: true });
+    }
+}
+/**
+ * Seed and read a compiled hook's named state from a test.
+ *
+ * @experimental — the store LAYOUT is not a stable contract (this handle exists
+ * so you never depend on it), and the hook vocabulary it serves is itself
+ * `experimental_`. See `docs/compiled-hooks.md` § Status / pending.
+ *
+ * Pass the hook file exactly as the wiring names it, and the same `cwd` the hook
+ * will run under — the store's location is derived from both, so a handle built
+ * with a different root points at a different (empty) store.
+ *
+ * ```js
+ * import { experimental_hookState, runHook } from "vigiles";
+ *
+ * const st = experimental_hookState(hookFile, { cwd });
+ * st.clear();
+ * st.seed("retro.nagged", { ago: "4d" });
+ * const r = runHook(`npx vigiles hook-runtime run-program ${hookFile}`, event, { cwd });
+ * ```
+ */
+function experimental_hookState(hookFile, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const dir = hookStateDir(hookFile, cwd);
+    const read = (key) => {
+        // Validate the key the way a hook's `needs` does — one validator, one
+        // message. A test that reads `"../settings"` should hear about it, not get
+        // a silent never-recorded fact back.
+        (0, hook_state_js_1.state)(key);
+        return (0, hook_state_js_1.stateFact)(readHookState(hookFile, key, cwd), Date.now());
+    };
+    return {
+        dir,
+        read,
+        seed(key, seedOpts = {}) {
+            // `record()` is the hook's OWN constructor, so the key charset is checked
+            // here by the same code and with the same error a hook would hit.
+            const w = (0, hook_state_js_1.record)(key, seedOpts.value ?? "");
+            writeHookState(hookFile, w, { cwd, at: seedInstant(seedOpts) });
+            // Read back through the real reader rather than returning what we meant to
+            // write: a seed that did not land must not look like one that did.
+            return read(key);
+        },
+        clear() {
+            clearOwnState(hookFile, cwd);
+        },
+    };
+}
+/**
+ * The instant a seed lands on. The `ago`/`at` exclusion is a type error AND a
+ * throw: harness tests are `.mjs` by convention (`dual-language-tests`), so a
+ * type-only guard would not run where most of these calls live.
+ */
+function seedInstant(opts) {
+    if (opts.ago !== undefined && opts.at !== undefined) {
+        throw new hook_state_js_1.HookStateError(`pass either ago or at, not both — "${opts.ago}" and ${opts.at.toISOString()} disagree about when the fact was recorded.`);
+    }
+    if (opts.at !== undefined)
+        return opts.at;
+    if (opts.ago === undefined)
+        return new Date();
+    const seconds = (0, hook_state_js_1.durationSeconds)(opts.ago);
+    if (seconds === null) {
+        throw new hook_state_js_1.HookStateError(`invalid duration "${opts.ago}" — use <number><s|m|h|d>, e.g. "90s", "30m", "1h", "7d".`);
+    }
+    return new Date(Date.now() - seconds * 1000);
+}
+//# sourceMappingURL=hook-state-store.js.map

package/dist/hook.d.ts

@@ -43,7 +43,9 @@
  * harness's DELIVERY. The delivery floor MOVED — #34692 (a subagent's tool calls
  * never reaching PreToolUse) is FIXED as of Claude Code 2.1.241, measured against
  * a stock registry install and pinned by src/subagent-delivery.test.ts, which goes
- * red if it regresses. What has NOT changed: a model can still route around a tool
+ * red if it regresses. SCOPE of that measurement: headless `claude -p` only —
+ * interactive is unmeasured, and depth-2 subagent nesting does not occur there at
+ * all. What has NOT changed: a model can still route around a tool
  * 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`.
  */

package/dist/hook.js

@@ -47,7 +47,9 @@ exports.leafCommandsNormalized = exports.HookStateError = exports.durationSecond
  * harness's DELIVERY. The delivery floor MOVED — #34692 (a subagent's tool calls
  * never reaching PreToolUse) is FIXED as of Claude Code 2.1.241, measured against
  * a stock registry install and pinned by src/subagent-delivery.test.ts, which goes
- * red if it regresses. What has NOT changed: a model can still route around a tool
+ * red if it regresses. SCOPE of that measurement: headless `claude -p` only —
+ * interactive is unmeasured, and depth-2 subagent nesting does not occur there at
+ * all. What has NOT changed: a model can still route around a tool
  * 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`.
  */

package/dist/run-hook.d.ts

@@ -45,7 +45,25 @@ export type { RunScriptOptions, ScriptRunResult, ScriptSpawnResult, ScriptSpawne
  * Options for {@link runHook} — every {@link RunScriptOptions} knob except
  * `stdin`, which the hook layer owns (it serializes the event there).
  */
-export type RunHookOptions = Omit<RunScriptOptions, "stdin">;
+export type RunHookOptions = Omit<RunScriptOptions, "stdin"> & {
+    /**
+     * The hook's CONDITION as the harness config writes it — Claude Code's `if`,
+     * e.g. `"Bash(git push *--force*)"`. When the condition does not match the
+     * event, the harness never spawns the hook, so neither do we: the result comes
+     * back `ran: false`, `blocked: false`.
+     *
+     * 🔴 PASS IT WHENEVER THE HOOK YOU ARE TESTING DECLARES ONE. A conditional hook
+     * tested without its condition is tested as an unconditional one, and since the
+     * bodies of real conditional guards are unconditional denies, that reports the
+     * guard as blocking everything you feed it. See `core/hook-condition.ts`.
+     */
+    readonly condition?: string;
+    /**
+     * The harness whose wire protocol + condition grammar to use. Defaults to
+     * Claude Code, so every existing caller is unaffected.
+     */
+    readonly protocol?: HookProtocol;
+};
 /** Result of {@link propertyHook}: the first shrunk counterexample, if any. */
 export interface HookPropertyResult<E> {
     readonly passed: boolean;
@@ -200,6 +218,20 @@ export interface HookRunResult extends ScriptRunResult {
      * ("approve"|"block"), else undefined.
      */
     readonly decision: HookOutput["decision"] | "allow" | "deny" | "ask" | undefined;
+    /**
+     * Whether the hook process was actually SPAWNED. False only when a declared
+     * condition (`RunHookOptions.condition`) did not match, meaning the harness
+     * would not have run it either.
+     *
+     * 🔴 READ THIS BEFORE READING `blocked`. `ran: false` and a hook that ran and
+     * allowed both arrive as `blocked: false`, and they are completely different
+     * facts — "the harness would never invoke this guard here" versus "the guard
+     * looked and let it through". Collapsing them is what let a conditional guard
+     * be reported as blocking a battery it cannot see.
+     */
+    readonly ran: boolean;
+    /** Why the hook ran or did not — the condition verdict, always present. */
+    readonly conditionReason: string;
 }
 /** Parse stdout as a hook JSON decision (pure, testable without a process). */
 export declare function parseHookOutput(stdout: string): HookOutput | null;

package/dist/run-hook.js

@@ -7,6 +7,7 @@ exports.parseHookOutput = parseHookOutput;
 exports.decideHook = decideHook;
 exports.runHookWith = runHookWith;
 exports.runHook = runHook;
+const hook_condition_js_1 = require("./core/hook-condition.js");
 const hook_protocol_js_1 = require("./adapters/claude-code/hook-protocol.js");
 const proofs_js_1 = require("./core/proofs.js");
 const hook_program_js_1 = require("./core/hook-program.js");
@@ -167,10 +168,53 @@ function decideHook(exitCode, json, protocol = hook_protocol_js_1.claudeCodeHook
  * bwrap. `runHook` is this with the real seams.
  */
 function runHookWith(command, input, opts, deps) {
+    const protocol = opts.protocol ?? hook_protocol_js_1.claudeCodeHookProtocol;
+    // The condition is decided BEFORE the spawn, because that is what the harness
+    // does — a non-matching `if` means the process never starts. Deciding it after
+    // would still report the right verdict but would run the user's hook for an
+    // event the harness would never have handed it.
+    const verdict = (0, hook_condition_js_1.decideHookCondition)(opts.condition, {
+        event: input.hook_event_name ?? "",
+        tool: input.tool_name ?? "",
+        input: (input.tool_input ?? {}),
+    }, protocol.condition);
+    if (!verdict.runs)
+        return {
+            ...skippedScriptResult(),
+            json: null,
+            blocked: false,
+            decision: undefined,
+            haltsTurn: false,
+            blockedBy: [],
+            ran: false,
+            conditionReason: verdict.why,
+        };
     const res = (0, run_script_js_1.runScriptWith)(command, JSON.stringify(input), opts, deps);
     const json = parseHookOutput(res.stdout);
-    const { blocked, decision, haltsTurn, blockedBy } = decideHook(res.exitCode, json);
-    return { ...res, json, blocked, decision, haltsTurn, blockedBy };
+    const { blocked, decision, haltsTurn, blockedBy } = decideHook(res.exitCode, json, protocol);
+    return {
+        ...res,
+        json,
+        blocked,
+        decision,
+        haltsTurn,
+        blockedBy,
+        ran: true,
+        conditionReason: verdict.why,
+    };
+}
+/**
+ * The `ScriptRunResult` shape for a hook that was never spawned. Exit code 0 and
+ * empty streams describe reality: no process existed, so the tool call proceeded.
+ * The fact that distinguishes this from a hook that ran and allowed is `ran`.
+ *
+ * `egressDropped` and `filesWritten` stay UNDEFINED on purpose — they mean
+ * "recorded nothing", and nothing was recorded because nothing ran. Filling them
+ * with zeroes would claim an observation that never happened, which is the same
+ * class of lie this whole change removes.
+ */
+function skippedScriptResult() {
+    return { exitCode: 0, stdout: "", stderr: "", egress: [] };
 }
 /**
  * Run a hook command, piping `input` as JSON to its stdin, and report the exit