vigiles 38.2.0 → 39.0.0

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

@@ -0,0 +1,172 @@
+import { type DispatchKind } from "./hook-program.js";
+/** Where `compile` writes the start-of-session check. Committed, next to the hook sources. */
+export declare const HOOK_CHECK_REF = ".vigiles/hook-check.sh";
+/** The CLI verb every compiled hook line starts the runtime with. */
+export declare const HOOK_RUNTIME_VERB = "hook-runtime";
+/** The runtime kind that runs a compiled hook program; its one operand is the program. */
+export declare const RUN_PROGRAM_KIND = "run-program";
+/**
+ * The lines `init` wires for a harness with no plugin store (Codex): the
+ * shipped nudges, started through npx. Data, so the plan below knows them as
+ * vigiles's own without reading their text.
+ */
+export declare const INIT_NUDGE_COMMANDS: {
+    readonly evalLock: "npx --no-install vigiles hook-runtime eval-lock-nudge";
+    readonly refs: "npx --no-install vigiles hook-runtime refs";
+};
+/**
+ * The command line `compile` writes to run a hook program: the runtime started
+ * by `runnerRef`, the program at `programRef`. {@link plannedHookLines} uses it, so a reader compares a wired line with the same string.
+ */
+export declare function runProgramCommand(runnerRef: string, programRef: string): string;
+/**
+ * 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, runtime?: HookRuntime): string;
+/**
+ * Which file a project starts the hook runtime from, and the command that puts
+ * that file on disk when it is missing.
+ */
+export interface HookRuntime {
+    /** Project-relative path of the runtime's entry point. */
+    readonly path: string;
+    /** What the start-of-session notice tells the user to run when it is missing. */
+    readonly cure: string;
+}
+/** A consumer's runtime: the vigiles it installed as a dependency. */
+export declare const INSTALLED_HOOK_RUNTIME: HookRuntime;
+/**
+ * The runtime a project with this `package.json` can actually start.
+ *
+ * 🔴 THE VIGILES REPOSITORY IS NOT ITS OWN DEPENDENCY. It compiles its own hooks,
+ * and the installed path above does not exist in it: nothing puts a package into
+ * its own `node_modules`. Measured 2026-10-11: both of the repository's compiled
+ * nudges had died with MODULE_NOT_FOUND on every tool call since #260
+ * (2026-09-21), and each one's `|| exit 0` turned the death into silence — a
+ * reminder that cannot load is skipped by design (see `hookRuntimeMissingExit`).
+ * So the package itself starts the bin it declares, which its build writes in
+ * place; the cure the notice names is that build, because `npm ci` alone does
+ * not produce `dist/`.
+ *
+ * Decided from the manifest's CONTENT (name + declared bin), never from where the
+ * running CLI happens to sit: a linked or pnpm-store copy would otherwise emit a
+ * path that is only true on the machine that ran `compile`.
+ */
+export declare function hookRuntimeFor(manifest: unknown): HookRuntime;
+/**
+ * The path token `compile` EMITS into the harness config — anchored at the project root
+ * when the harness declares such a variable.
+ *
+ * 🔴 IT LIVES BESIDE {@link bareToken} ON PURPOSE. That function STRIPS exactly this prefix
+ * and these quotes; this one ADDS them. They are one contract read from two ends, and while
+ * the ends sat apart only one got fixed: 2026-08-21 taught the reader to understand the
+ * anchored spelling, and the emitter went on writing the relative one for three more weeks.
+ *
+ * Why anchored at all, from the two measurements already in this file and in
+ * `PluginLayout.projectRootTokens`: a hook command does not run with a stable cwd, so a
+ * relative path "dies with exit 2 the moment the agent runs from a subdirectory". For a
+ * PreToolUse gate that is not a lost nudge — a gate that cannot load must block, so the
+ * repository seizes. Measured in a consumer repo 2026-09-10: recoverable by file writes
+ * only, because every command was refused, including the one that repairs it.
+ *
+ * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
+ * it is asserted directly rather than left to inspection.
+ */
+export declare function hookGateRef(ref: string, projectRootTokens: readonly string[] | undefined): string;
+/**
+ * A command token reduced to the PATH it names, so two spellings of the same
+ * hook file compare equal.
+ *
+ * 🔴 BOTH STRIPS ARE REGRESSIONS, MEASURED IN A CONSUMER REPO 2026-08-21, and
+ * they compound: a settings.json wired the Claude-Code-recommended way carries
+ * BOTH a quote and the project-dir variable, so `managesHook` saw
+ * `"$CLAUDE_PROJECT_DIR/.claude/hooks/x.hook.ts"`, canonicalized it to
+ * something under the cwd that resembles nothing, and reported "not managed by
+ * this hook". Recompiling then APPENDED its own block beside the existing one.
+ * Twelve hooks, twelve duplicates, and the duplicate is the WORSE of the two:
+ * it spells the path relative to the cwd, so it dies with exit 2 the moment the
+ * agent runs from a subdirectory — while the healthy copy beside it keeps
+ * working, which is why this survived a full day unnoticed.
+ *
+ * - QUOTES. A path with a space MUST be quoted, so the quoted form is not an
+ *   exotic spelling — it is the correct one. Comparing it raw could never match.
+ * - the harness's PROJECT-ROOT variable (Claude Code's `$CLAUDE_PROJECT_DIR`),
+ *   handed in by the caller from its layout. It is defined as the project
+ *   root, which is exactly what a relative path resolves against, so stripping
+ *   it makes the two spellings the same path by definition rather than by
+ *   guess. `${NAME}` and `$NAME` are the same variable. Core names no harness
+ *   variable itself.
+ *
+ * Nothing else is stripped. A token this function does not recognise is left
+ * alone and simply fails to match, which is the pre-existing behaviour: the
+ * cost of a miss here is a duplicate block, and the cost of an over-match is
+ * deleting a hook the user wrote themselves.
+ */
+export declare function bareToken(token: string, rootTokens: readonly string[]): string;
+/** The start-of-session check line `compile` wires beside the compiled hooks. */
+export declare function sessionCheckCommand(projectRootTokens: readonly string[] | undefined): string;
+/**
+ * A hook source and what its last compile recorded about it. `role` comes from
+ * the stamp sidecar; a source never compiled (or compiled by a vigiles that did
+ * not record it) has none, and so has no planned line.
+ */
+export interface HookSourceRecord {
+    /** Repo-relative path of the hook source (`.vigiles/hooks/x.hook.mjs`). */
+    readonly ref: string;
+    readonly role?: DispatchKind;
+}
+/** One line `compile` would write, and the files it needs on disk. */
+export interface PlannedHookLine {
+    readonly command: string;
+    /** Root-anchored (`${TOKEN}/…`) or repo-relative paths. */
+    readonly files: readonly string[];
+}
+/**
+ * The lines `compile` and `init` would write in a repo, and the hook sources
+ * whose wiring `compile` owns (its merge key) — what a reader compares a hook
+ * line against.
+ */
+export interface HookLinePlan {
+    readonly lines: readonly PlannedHookLine[];
+    /** Repo-relative refs of every hook source, compiled or not. */
+    readonly sources: readonly string[];
+}
+/**
+ * The plan for a repo, from what its files say: each hook source's role from
+ * its stamp sidecar, the runtime from `package.json`. `readText` is the
+ * engine's file port (disk or a fetched file map); `undefined` = absent.
+ */
+export declare function hookLinePlan(sourceRefs: readonly string[], readText: (ref: string) => string | undefined, projectRootTokens: readonly string[] | undefined): HookLinePlan;
+/** What the plan needs: the repo's hook sources, its runtime, the harness's root variables. */
+export interface HookPlanInput {
+    readonly sources: readonly HookSourceRecord[];
+    readonly runtime: HookRuntime;
+    readonly projectRootTokens: readonly string[] | undefined;
+}
+/**
+ * Every hook line `compile` (and `init`) would write in this repo — the same
+ * template functions the writers call, so the reader cannot drift from them.
+ */
+export declare function plannedHookLines(input: HookPlanInput): readonly PlannedHookLine[];
+/**
+ * Whether a command names one of `refs` — `compile`'s MERGE KEY, the test it
+ * uses to find the entries it owns when it rewrites a settings file. The
+ * command is split on whitespace and each word reduced by {@link bareToken};
+ * nothing is parsed as shell. `normalize` makes a word comparable to a ref
+ * (the writer and the reader each know their own root).
+ */
+export declare function commandNamesRef(command: string, refs: readonly string[], normalize: (word: string) => string, rootTokens: readonly string[]): boolean;
+//# sourceMappingURL=hook-command.d.ts.map

package/dist/core/hook-command.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTALLED_HOOK_RUNTIME = exports.INIT_NUDGE_COMMANDS = exports.RUN_PROGRAM_KIND = exports.HOOK_RUNTIME_VERB = exports.HOOK_CHECK_REF = void 0;
+exports.runProgramCommand = runProgramCommand;
+exports.hookRuntimeRef = hookRuntimeRef;
+exports.hookRuntimeFor = hookRuntimeFor;
+exports.hookGateRef = hookGateRef;
+exports.bareToken = bareToken;
+exports.sessionCheckCommand = sessionCheckCommand;
+exports.hookLinePlan = hookLinePlan;
+exports.plannedHookLines = plannedHookLines;
+exports.commandNamesRef = commandNamesRef;
+/**
+ * The hook command lines vigiles WRITES, and the one way they are recognised:
+ * by IDENTITY with what `compile` would write (#361, #362).
+ *
+ * 🔴 VIGILES NEVER PARSES A HAND-WRITTEN HOOK COMMAND LINE. Two branches of
+ * this repository tried: #359 taught `resolveScript` one more shell shape
+ * (`$CLAUDE_PROJECT_DIR`), and #361's first version parsed the line as shell
+ * and kept an interpreter list to find "the script". Each shape it learned
+ * exposed the next one it did not (`env X=1 cmd`, `sh -c '…'`, `cd d && ./x`,
+ * `bash -x x.sh`), and even a perfect parse answers only "does one path exist",
+ * never "does the hook work". Both were removed (#362). The lines vigiles owns
+ * need no parse: `compile` is their only writer, so a line is `compiled`
+ * exactly when it equals the line the plan below says compile would write for
+ * one of this repo's hook sources. Everything else is hand-written, and the
+ * answer to a hand-written hook is to compile it. Whether any hook works is
+ * answered by running it (`runHook`, `vigiles test`).
+ *
+ * Enforced by `no-restricted-imports` in eslint.config.mjs: this module and the
+ * scan's hook readers may not import the shell parser.
+ *
+ * Pure and harness-agnostic: the root variables, the runtime and the hook
+ * sources come from the caller.
+ */
+const hook_paths_js_1 = require("./hook-paths.js");
+const hook_program_js_1 = require("./hook-program.js");
+/** Where `compile` writes the start-of-session check. Committed, next to the hook sources. */
+exports.HOOK_CHECK_REF = ".vigiles/hook-check.sh";
+/** The CLI verb every compiled hook line starts the runtime with. */
+exports.HOOK_RUNTIME_VERB = "hook-runtime";
+/** The runtime kind that runs a compiled hook program; its one operand is the program. */
+exports.RUN_PROGRAM_KIND = "run-program";
+/**
+ * The lines `init` wires for a harness with no plugin store (Codex): the
+ * shipped nudges, started through npx. Data, so the plan below knows them as
+ * vigiles's own without reading their text.
+ */
+exports.INIT_NUDGE_COMMANDS = {
+    evalLock: "npx --no-install vigiles hook-runtime eval-lock-nudge",
+    refs: "npx --no-install vigiles hook-runtime refs",
+};
+/**
+ * The command line `compile` writes to run a hook program: the runtime started
+ * by `runnerRef`, the program at `programRef`. {@link plannedHookLines} uses it, so a reader compares a wired line with the same string.
+ */
+function runProgramCommand(runnerRef, programRef) {
+    return `${runnerRef} ${exports.HOOK_RUNTIME_VERB} ${exports.RUN_PROGRAM_KIND} ${programRef}`;
+}
+/**
+ * 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, runtime = exports.INSTALLED_HOOK_RUNTIME) {
+    const token = projectRootTokens?.[0];
+    return token === undefined
+        ? `node ${runtime.path}`
+        : `node "${token}/${runtime.path}"`;
+}
+/** A consumer's runtime: the vigiles it installed as a dependency. */
+exports.INSTALLED_HOOK_RUNTIME = {
+    path: "node_modules/vigiles/dist/cli.js",
+    cure: "npm ci (or npm install)",
+};
+/**
+ * The runtime a project with this `package.json` can actually start.
+ *
+ * 🔴 THE VIGILES REPOSITORY IS NOT ITS OWN DEPENDENCY. It compiles its own hooks,
+ * and the installed path above does not exist in it: nothing puts a package into
+ * its own `node_modules`. Measured 2026-10-11: both of the repository's compiled
+ * nudges had died with MODULE_NOT_FOUND on every tool call since #260
+ * (2026-09-21), and each one's `|| exit 0` turned the death into silence — a
+ * reminder that cannot load is skipped by design (see `hookRuntimeMissingExit`).
+ * So the package itself starts the bin it declares, which its build writes in
+ * place; the cure the notice names is that build, because `npm ci` alone does
+ * not produce `dist/`.
+ *
+ * Decided from the manifest's CONTENT (name + declared bin), never from where the
+ * running CLI happens to sit: a linked or pnpm-store copy would otherwise emit a
+ * path that is only true on the machine that ran `compile`.
+ */
+function hookRuntimeFor(manifest) {
+    if (fieldOf(manifest, "name") !== "vigiles")
+        return exports.INSTALLED_HOOK_RUNTIME;
+    const bin = fieldOf(manifest, "bin");
+    // npm's two spellings: `"bin": "x.js"` or `"bin": { "vigiles": "x.js" }`.
+    const declared = typeof bin === "string" ? bin : fieldOf(bin, "vigiles");
+    if (typeof declared !== "string" || declared === "")
+        return exports.INSTALLED_HOOK_RUNTIME;
+    return {
+        path: declared.replace(/^\.\//, ""),
+        cure: "npm ci && npm run build",
+    };
+}
+/** `value[key]` when `value` is an object, else `undefined` — no cast. */
+function fieldOf(value, key) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const found = Object.entries(value).find(([k]) => k === key)?.[1];
+    return found;
+}
+/**
+ * The path token `compile` EMITS into the harness config — anchored at the project root
+ * when the harness declares such a variable.
+ *
+ * 🔴 IT LIVES BESIDE {@link bareToken} ON PURPOSE. That function STRIPS exactly this prefix
+ * and these quotes; this one ADDS them. They are one contract read from two ends, and while
+ * the ends sat apart only one got fixed: 2026-08-21 taught the reader to understand the
+ * anchored spelling, and the emitter went on writing the relative one for three more weeks.
+ *
+ * Why anchored at all, from the two measurements already in this file and in
+ * `PluginLayout.projectRootTokens`: a hook command does not run with a stable cwd, so a
+ * relative path "dies with exit 2 the moment the agent runs from a subdirectory". For a
+ * PreToolUse gate that is not a lost nudge — a gate that cannot load must block, so the
+ * repository seizes. Measured in a consumer repo 2026-09-10: recoverable by file writes
+ * only, because every command was refused, including the one that repairs it.
+ *
+ * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
+ * it is asserted directly rather than left to inspection.
+ */
+function hookGateRef(ref, projectRootTokens) {
+    const token = projectRootTokens?.[0];
+    return token === undefined ? ref : `"${token}/${ref}"`;
+}
+/**
+ * A command token reduced to the PATH it names, so two spellings of the same
+ * hook file compare equal.
+ *
+ * 🔴 BOTH STRIPS ARE REGRESSIONS, MEASURED IN A CONSUMER REPO 2026-08-21, and
+ * they compound: a settings.json wired the Claude-Code-recommended way carries
+ * BOTH a quote and the project-dir variable, so `managesHook` saw
+ * `"$CLAUDE_PROJECT_DIR/.claude/hooks/x.hook.ts"`, canonicalized it to
+ * something under the cwd that resembles nothing, and reported "not managed by
+ * this hook". Recompiling then APPENDED its own block beside the existing one.
+ * Twelve hooks, twelve duplicates, and the duplicate is the WORSE of the two:
+ * it spells the path relative to the cwd, so it dies with exit 2 the moment the
+ * agent runs from a subdirectory — while the healthy copy beside it keeps
+ * working, which is why this survived a full day unnoticed.
+ *
+ * - QUOTES. A path with a space MUST be quoted, so the quoted form is not an
+ *   exotic spelling — it is the correct one. Comparing it raw could never match.
+ * - the harness's PROJECT-ROOT variable (Claude Code's `$CLAUDE_PROJECT_DIR`),
+ *   handed in by the caller from its layout. It is defined as the project
+ *   root, which is exactly what a relative path resolves against, so stripping
+ *   it makes the two spellings the same path by definition rather than by
+ *   guess. `${NAME}` and `$NAME` are the same variable. Core names no harness
+ *   variable itself.
+ *
+ * Nothing else is stripped. A token this function does not recognise is left
+ * alone and simply fails to match, which is the pre-existing behaviour: the
+ * cost of a miss here is a duplicate block, and the cost of an over-match is
+ * deleting a hook the user wrote themselves.
+ */
+function bareToken(token, rootTokens) {
+    const unquoted = token.replace(/^["']/, "").replace(/["']$/, "");
+    const prefix = rootTokens
+        .map((t) => t.replace(/^\$\{(.+)\}$/, "$1"))
+        .flatMap((name) => [`\${${name}}`, `$${name}`])
+        .flatMap((spelled) => [`${spelled}/`, `${spelled}\\`])
+        .find((p) => unquoted.startsWith(p));
+    return prefix === undefined ? unquoted : unquoted.slice(prefix.length);
+}
+/** The start-of-session check line `compile` wires beside the compiled hooks. */
+function sessionCheckCommand(projectRootTokens) {
+    return `sh ${hookGateRef(exports.HOOK_CHECK_REF, projectRootTokens)} || exit 0`;
+}
+/**
+ * The plan for a repo, from what its files say: each hook source's role from
+ * its stamp sidecar, the runtime from `package.json`. `readText` is the
+ * engine's file port (disk or a fetched file map); `undefined` = absent.
+ */
+function hookLinePlan(sourceRefs, readText, projectRootTokens) {
+    const sources = sourceRefs.map((ref) => {
+        const role = fieldOf(parseJson(readText((0, hook_paths_js_1.hookStampRef)(ref))), "role");
+        return isDispatchKind(role) ? { ref, role } : { ref };
+    });
+    return {
+        lines: plannedHookLines({
+            sources,
+            runtime: hookRuntimeFor(parseJson(readText("package.json"))),
+            projectRootTokens,
+        }),
+        sources: sourceRefs,
+    };
+}
+/** JSON text → value; absent or malformed → undefined (the plan then has less). */
+function parseJson(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        const value = JSON.parse(text);
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every role a compiled hook can have — a record, so a new kind is a tsc error here. */
+const DISPATCH_KINDS = {
+    "bash-gate": true,
+    "file-gate": true,
+    "prompt-gate": true,
+    "stop-gate": true,
+    inject: true,
+    react: true,
+};
+function isDispatchKind(value) {
+    return (typeof value === "string" &&
+        Object.keys(DISPATCH_KINDS).some((k) => k === value));
+}
+/**
+ * Every hook line `compile` (and `init`) would write in this repo — the same
+ * template functions the writers call, so the reader cannot drift from them.
+ */
+function plannedHookLines(input) {
+    const { sources, projectRootTokens: tokens } = input;
+    return [
+        ...sources.flatMap((s) => compiledLine(s, input)),
+        {
+            command: sessionCheckCommand(tokens),
+            files: [anchored(exports.HOOK_CHECK_REF, tokens)],
+        },
+        ...Object.values(exports.INIT_NUDGE_COMMANDS).map((command) => ({
+            command,
+            files: [],
+        })),
+    ];
+}
+/** The line `compile` writes for one recorded hook source; none without a role. */
+function compiledLine({ ref, role }, { runtime, projectRootTokens: tokens }) {
+    if (role === undefined)
+        return [];
+    const command = (0, hook_program_js_1.withRoleExit)(runProgramCommand(hookRuntimeRef(tokens, runtime), hookGateRef(ref, tokens)), role);
+    const files = [runtime.path, ref, (0, hook_paths_js_1.hookStampRef)(ref)].map((f) => anchored(f, tokens));
+    return [{ command, files }];
+}
+/** `rel` anchored at the harness's project root, as the emitted line spells it. */
+function anchored(rel, projectRootTokens) {
+    const token = projectRootTokens?.[0];
+    return token === undefined ? rel : `${token}/${rel}`;
+}
+/**
+ * Whether a command names one of `refs` — `compile`'s MERGE KEY, the test it
+ * uses to find the entries it owns when it rewrites a settings file. The
+ * command is split on whitespace and each word reduced by {@link bareToken};
+ * nothing is parsed as shell. `normalize` makes a word comparable to a ref
+ * (the writer and the reader each know their own root).
+ */
+function commandNamesRef(command, refs, normalize, rootTokens) {
+    return command.split(/\s+/).some((word) => {
+        const bare = bareToken(word, rootTokens);
+        return bare !== "" && refs.includes(normalize(bare));
+    });
+}
+//# sourceMappingURL=hook-command.js.map

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

@@ -0,0 +1,133 @@
+/**
+ * Did a hook's TEXT reach the model? — the observed-output twin of
+ * `noticeDelivery` (which answers the same question for a compiled react
+ * BEFORE anything runs).
+ *
+ * 🔴 THE DEFECT THIS EXISTS FOR, MEASURED 2026-10-11 IN A DOWNSTREAM REPO. Its
+ * main knowledge-base linter ran as a `PostToolUse` hook, wrote every finding to
+ * stderr and exited 0 — for weeks. Probe: exit 0, 0 bytes of stdout, 237 bytes
+ * of stderr. Every `runHook`-based test of it was green, because every one of
+ * them asserted on `r.stderr`, which is exactly the stream nobody reads. The
+ * host's hooks documentation is explicit:
+ *
+ *   "Claude never sees stderr from a hook that exits 0. [...] To surface a
+ *    warning to Claude from a `PostToolUse` or `PostToolUseFailure` hook, exit 2
+ *    instead so Claude sees the stderr even though the tool already ran."
+ *    — code.claude.com/docs/en/hooks § Exit code 0, read 2026-10-11
+ *
+ * "The hook printed it" and "the model received it" are the repo's own
+ * `fired ≠ landed` split, at the unit tier. A test of a nudge must assert the
+ * second, and the second is a function of FOUR facts — the event, the exit
+ * code, which stream carried the text, and what the harness's capability table
+ * says that event honours. This module is that function. Pure: no process, no
+ * harness literal (the table and the block code are injected), so a test and
+ * the runtime agree about delivery without running a harness.
+ *
+ * WHAT IT DELIBERATELY DOES NOT CLAIM:
+ * - an event with no row in the table is `unknown`, never `undelivered` — the
+ *   same fail-open stance as `capabilityOf`. A harness with no table at all
+ *   (Codex today) can still be judged on the ONE fact its port carries, the
+ *   legacy `injectableEvents`: `additionalContext` there is `delivered`, and
+ *   anything else is `unknown`;
+ * - a BLOCK (a veto, or a halt of the turn) is reported as `blocked`, not as
+ *   delivery. Where the block reason
+ *   goes differs per event (a vetoed prompt shows it to the user only), the
+ *   capability table does not record that, and a block is not a nudge — its
+ *   assertion is `assertHookBlocked`;
+ * - `systemMessage` is not judged: it is addressed to the user by design.
+ */
+import type { EventCapabilityTable } from "./event-capability.js";
+/** A route by which hook text reached the model. */
+export type DeliveryChannel = 
+/** `hookSpecificOutput.additionalContext` on an event honouring `inject`. */
+"additional-context"
+/** Plain (non-JSON) stdout at exit 0, on an event honouring `stdout-context`. */
+ | "plain-stdout"
+/** stderr at the block exit code, on an event honouring `feedback`. */
+ | "exit-code-feedback"
+/** JSON `decision: "block"` + `reason`, on an event honouring `feedback`. */
+ | "decision-reason";
+/** Text the hook printed that reached NO channel the model reads. */
+export interface StrandedOutput {
+    readonly stream: "stdout" | "stderr";
+    readonly bytes: number;
+    /** Why it went nowhere — phrased as an instruction, not a verdict. */
+    readonly why: string;
+}
+/**
+ * The verdict. FIVE answers, because "the model saw nothing" has four distinct
+ * causes and a test failure must name the right one (`make-the-distinction-a-type`):
+ * the hook said nothing, it said something on a dead stream, it blocked
+ * instead, or we do not know this event.
+ */
+export type HookDelivery = {
+    readonly kind: "delivered";
+    readonly via: readonly DeliveryChannel[];
+    /** Output that ALSO went nowhere — informational, not a failure. */
+    readonly stranded: readonly StrandedOutput[];
+}
+/** The hook vetoed the action. Not a nudge; see the module header. */
+ | {
+    readonly kind: "blocked";
+    readonly stranded: readonly StrandedOutput[];
+}
+/** The hook printed text and none of it reached the model. Never empty. */
+ | {
+    readonly kind: "undelivered";
+    readonly stranded: readonly StrandedOutput[];
+}
+/**
+ * Nothing addressed to the model: empty streams, or control-only JSON
+ * (`permissionDecision: "allow"`, a user-facing `systemMessage`).
+ */
+ | {
+    readonly kind: "silent";
+}
+/** The table has no row for this event, so delivery cannot be judged. */
+ | {
+    readonly kind: "unknown";
+    readonly event: string;
+    readonly why: string;
+};
+/** What a finished hook process left behind — the observable half. */
+export interface HookEmission {
+    readonly event: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** stdout parsed as one JSON object, or null when it is plain text / empty. */
+    readonly json: Readonly<Record<string, unknown>> | null;
+}
+/** The harness facts the verdict needs — injected, never a literal. */
+export interface DeliveryFacts {
+    /** The dialect's capability table, when the adapter has one. */
+    readonly table: EventCapabilityTable | undefined;
+    /** The protocol's block exit code (exit 2 on both shipped harnesses). */
+    readonly blockExitCode: number;
+    /** The protocol's deny decision values (`"block"`, `"deny"`). */
+    readonly denyDecisionValues: readonly string[];
+    /** The protocol's halt-the-turn field, if it has one. */
+    readonly haltsTurnField?: string;
+    /**
+     * The legacy flat list of events honouring `additionalContext` — the fallback
+     * for an adapter with no table. Ignored when `table` is present.
+     */
+    readonly injectableEvents?: readonly string[];
+}
+/**
+ * Judge one finished hook run. Pure.
+ *
+ * Order matters and is the specification:
+ * 1. nothing printed → `silent` (true on every event, known or not);
+ * 2. no table row → `delivered` only on the one fact the legacy list proves,
+ *    else `unknown`;
+ * 3. a veto on an event that honours one, or a halt on an event that
+ *    honours `halt` → `blocked`;
+ * 4. otherwise collect every channel that carried text, and every stream that
+ *    carried text to no channel; at least one channel → `delivered`. A JSON
+ *    object on stdout is applied on any exit code (the host's exit-code table:
+ *    valid JSON is "Success" at exit 0 and at any other code, and its fields
+ *    are still read at exit 2); plain text is context only at exit 0.
+ */
+export declare function hookOutputDelivery(e: HookEmission, f: DeliveryFacts): HookDelivery;
+//# sourceMappingURL=hook-delivery.d.ts.map