vigiles 23.0.0 → 25.0.0

package/dist/core/compile.d.ts

@@ -10,7 +10,44 @@ import type { HarnessDialect } from "./dialect.js";
 /** @internal Compute SHA-256 hash of content (excluding any existing hash line). */
 export declare function computeHash(content: string): string;
 /** @internal Prepend a hash comment to compiled content. */
-export declare function addHash(content: string, specFile: string): string;
+/**
+ * A compiled body that carries a valid integrity stamp — mintable ONLY by
+ * {@link addHash}, and by construction only handed out for a CLEAN compile.
+ *
+ * 🔴 WHY A BRAND AND NOT A CHECK AT THE WRITE SITE. #173 was a `CLAUDE.md`
+ * written while its refs were known-dead: `compile` printed the errors, exited
+ * 1, and wrote the file anyway, stamped. `lint` then verified the stamp and
+ * exited 0 over an artifact that names files which do not exist. The fix that
+ * shipped moved the write behind an error check in ONE compiler — and the same
+ * three lines sat unchanged in four siblings (skill, subagent, railway,
+ * generator), where the lint-side backstop does not even reach because
+ * `spec-refs` only inspects `claude` specs. Reproduced end to end after that
+ * fix: a skill spec with a stale ref still produced a stamped `SKILL.md` and a
+ * green `lint`.
+ *
+ * Fixing five write sites leaves the class writable — the sixth compiler would
+ * be written the same way. Branding the STAMP moves the guarantee to where it is
+ * produced: `writeArtifact` accepts nothing else, and an erroring compile has no
+ * stamp to give it.
+ */
+export type StampedMarkdown = string & {
+    readonly __stamped: unique symbol;
+};
+export declare function addHash(content: string, specFile: string): StampedMarkdown;
+/**
+ * How every compiler finishes: the rendered body, plus a STAMPED artifact that
+ * exists only when the compile is clean.
+ *
+ * `markdown` stays a plain string because callers legitimately want the draft
+ * even when it is wrong — `adoptDiff` diffs "what the spec WOULD produce"
+ * against the file on disk, and a stale ref must not stop that. `artifact` is
+ * what a writer needs, and it is `null` the moment there is an error, so the
+ * write cannot happen without narrowing.
+ */
+export declare function seal(body: string, errors: readonly CompileError[], specFile: string): {
+    markdown: string;
+    artifact: StampedMarkdown | null;
+};
 /** @internal Check if a file's hash matches its content. Returns null if no hash found. */
 export declare function verifyHash(content: string): {
     valid: boolean;
@@ -74,6 +111,11 @@ export interface CompileClaudeOptions {
  */
 export declare function compileClaude(spec: ClaudeSpec, options?: CompileClaudeOptions): CompileClaudeResult;
 export interface CompileSkillResult {
+    /**
+     * The stamped artifact — present ONLY when `errors` is empty. `null` is what
+     * makes a failed compile unwritable: `writeArtifact` accepts nothing else.
+     */
+    artifact: StampedMarkdown | null;
     markdown: string;
     errors: CompileError[];
     /** Non-blocking advisories (e.g. an over-long inline code block). */
@@ -90,6 +132,11 @@ export declare function compileSkill(spec: SkillSpec, options?: {
     dialect?: HarnessDialect;
 }): CompileSkillResult;
 export interface CompileAgentResult {
+    /**
+     * The stamped artifact — present ONLY when `errors` is empty. `null` is what
+     * makes a failed compile unwritable: `writeArtifact` accepts nothing else.
+     */
+    artifact: StampedMarkdown | null;
     markdown: string;
     errors: CompileError[];
     /** Non-blocking advisories (e.g. an over-long inline code block). */
@@ -113,6 +160,11 @@ export interface CompileRailwayOptions {
     specFile?: string;
 }
 export interface CompileRailwayResult {
+    /**
+     * The stamped artifact — present ONLY when `errors` is empty. `null` is what
+     * makes a failed compile unwritable: `writeArtifact` accepts nothing else.
+     */
+    artifact: StampedMarkdown | null;
     markdown: string;
     errors: CompileError[];
 }

package/dist/core/compile.js

@@ -11,6 +11,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeHash = computeHash;
 exports.addHash = addHash;
+exports.seal = seal;
 exports.verifyHash = verifyHash;
 exports.estimateTokens = estimateTokens;
 exports.validateFileRef = validateFileRef;
@@ -53,7 +54,6 @@ const DEFAULT_TARGET = "CLAUDE.md";
 function computeHash(content) {
     return (0, hash_js_1.sha256short)((0, integrity_js_1.findIntegrityHeader)(content)?.withoutHeader ?? content);
 }
-/** @internal Prepend a hash comment to compiled content. */
 function addHash(content, specFile) {
     // 🔴 THE LAST GATE BEFORE A COMPILED FILE IS WRITTEN. Every compile path returns through here
     // (four call sites), which makes it the one place a whole class of defect can be stopped.
@@ -72,8 +72,24 @@ function addHash(content, specFile) {
             `where a string was expected, and JavaScript stringified it. Check the arguments to ` +
             `input()/file()/cmd() and friends: they take strings, not option objects.`);
     }
+    // The ONE mint. Every stamped artifact in the codebase originates here, which
+    // is what makes the brand meaningful rather than decorative.
     return (0, integrity_js_1.placeIntegrityHeader)(content, computeHash(content), specFile);
 }
+/**
+ * How every compiler finishes: the rendered body, plus a STAMPED artifact that
+ * exists only when the compile is clean.
+ *
+ * `markdown` stays a plain string because callers legitimately want the draft
+ * even when it is wrong — `adoptDiff` diffs "what the spec WOULD produce"
+ * against the file on disk, and a stale ref must not stop that. `artifact` is
+ * what a writer needs, and it is `null` the moment there is an error, so the
+ * write cannot happen without narrowing.
+ */
+function seal(body, errors, specFile) {
+    const stamped = addHash(body, specFile);
+    return { markdown: stamped, artifact: errors.length === 0 ? stamped : null };
+}
 /** @internal Check if a file's hash matches its content. Returns null if no hash found. */
 function verifyHash(content) {
     const found = (0, integrity_js_1.findIntegrityHeader)(content);
@@ -859,7 +875,7 @@ function compileSkill(spec, options = {}) {
         (marker ? marker + "\n\n" : "") +
         sections.trim() +
         "\n";
-    return { markdown: addHash(content, specFile), errors, warnings };
+    return { ...seal(content, errors, specFile), errors, warnings };
 }
 // ---------------------------------------------------------------------------
 // Compile a subagent spec → agents/<name>.md
@@ -1058,7 +1074,7 @@ function compileAgent(spec, options) {
         (marker ? marker + "\n\n" : "") +
         body.trim() +
         "\n";
-    return { markdown: addHash(content, specFile), errors, warnings };
+    return { ...seal(content, errors, specFile), errors, warnings };
 }
 /** Verify a railway: non-empty, bounded recovery, every delegate target real. */
 function validateRailway(rw, knownAgents) {
@@ -1126,7 +1142,7 @@ function compileRailway(rw, options = {}) {
     const errors = validateRailway(rw, options.knownAgents);
     const specFile = options.specFile ?? `${rw.name}.railway.spec.ts`;
     const content = renderRailwayMarkdown(rw) + "\n";
-    return { markdown: addHash(content, specFile), errors };
+    return { ...seal(content, errors, specFile), errors };
 }
 /** Check if a generated file's hash is intact. */
 function checkFileHash(filePath) {

package/dist/core/repo-path.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `RepoRelativePath` — a path that is provably INSIDE the repository.
+ *
+ * 🔴 WHY A TYPE AND NOT A CHECK. `audit --out=/tmp/x` appended entries like
+ * `../../../../private/tmp/x/vigiles-report.json` to the user's `.gitignore`
+ * (#176.8). Those ignore nothing — `.gitignore` does not reach outside its own
+ * tree — and accumulate one dead block per output path, in a file the tool is
+ * documented as never writing. The fix that shipped was a guard at the write
+ * site, which works and leaves the bug WRITABLE: the next caller to build an
+ * entry list gets a `string[]` and no reason to think twice.
+ *
+ * This makes it unwritable instead. `ensureReportGitignored` accepts only
+ * `RepoRelativePath[]`, and the only way to obtain one is `repoRelative()`,
+ * which returns `null` for anything that escapes the root. There is no cast at
+ * the call site and no second guard to keep in sync — a path that leaves the
+ * repo cannot reach the writer, because it cannot be given the type.
+ *
+ * The brand is the pattern this codebase already uses for `VerifiedPath` and
+ * friends: a nominal marker on `string` that only a smart constructor mints.
+ */
+declare const REPO_RELATIVE: unique symbol;
+/** A POSIX-separated path known to resolve inside the repository root. */
+export type RepoRelativePath = string & {
+    readonly [REPO_RELATIVE]: true;
+};
+/**
+ * Mint a {@link RepoRelativePath}, or `null` when the target escapes `root`.
+ *
+ * Rejects an absolute path and anything whose relative form starts with `..`.
+ * Normalizes to POSIX separators, because `.gitignore` patterns are POSIX and a
+ * Windows `reports\x` would never match `reports/x` — a second silent-miss that
+ * lived next to the first.
+ */
+export declare function repoRelative(root: string, target: string, io: {
+    relative: (from: string, to: string) => string;
+    resolve: (...parts: string[]) => string;
+    isAbsolute: (p: string) => boolean;
+    sep: string;
+}): RepoRelativePath | null;
+export {};
+//# sourceMappingURL=repo-path.d.ts.map

package/dist/core/repo-path.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.repoRelative = repoRelative;
+/**
+ * Mint a {@link RepoRelativePath}, or `null` when the target escapes `root`.
+ *
+ * Rejects an absolute path and anything whose relative form starts with `..`.
+ * Normalizes to POSIX separators, because `.gitignore` patterns are POSIX and a
+ * Windows `reports\x` would never match `reports/x` — a second silent-miss that
+ * lived next to the first.
+ */
+function repoRelative(root, target, io) {
+    const rel = io.relative(root, io.resolve(root, target));
+    if (rel === "" || rel.startsWith("..") || io.isAbsolute(rel))
+        return null;
+    const posix = io.sep === "/" ? rel : rel.split(io.sep).join("/");
+    return posix;
+}
+//# sourceMappingURL=repo-path.js.map

package/dist/core/rule-meta.d.ts

@@ -41,7 +41,7 @@ export type RuleSurface = "instruction" | "skill" | "subagent" | "hook" | "mcp"
 /** Where a rule sits by default — `"off"` is the normalized form of `false`. */
 export type RuleDefaultSeverity = "error" | "warn" | "off";
 /** Every named rule: the `RulesConfig` keys plus the built-in `orphan-docs`. */
-export type RuleName = keyof RulesConfig | "orphan-docs";
+export type RuleName = keyof RulesConfig;
 /**
  * The declared shape of one rule — co-located metadata in the ESLint `meta`
  * sense, gathered into one registry because vigiles shares detectors.

package/dist/core/rule-meta.js

@@ -262,6 +262,22 @@ exports.RULE_META = {
         detector: "delegationTrifectaIssues",
     },
     // --- Docs hygiene ---------------------------------------------------------
+    "duplicate-rules": {
+        id: "duplicate-rules",
+        bucket: "heuristic-behavioral",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "Near-duplicate rules within one spec (NCD similarity) — two rules saying the same thing.",
+        detector: "findDuplicateRules",
+    },
+    "spec-refs": {
+        id: "spec-refs",
+        bucket: "external-decidable",
+        surface: ["instruction"],
+        defaultSeverity: "error",
+        summary: "A compiled instruction file whose spec references a file/script that no longer exists.",
+        detector: "compileClaude",
+    },
     "orphan-docs": {
         id: "orphan-docs",
         bucket: "heuristic-behavioral",

package/dist/core/types.d.ts

@@ -99,6 +99,36 @@ export interface TestCoverageConfig {
     testExtension?: string;
 }
 export interface RulesConfig {
+    /**
+     * Opt-in: a doc in a configured dir (default `docs/`) that no other `.md`
+     * references. The `orphans` block turns the SCAN on; this turns the FINDING
+     * into a warning or an error.
+     *
+     * It lived outside this interface until 2026-09 and therefore could not be
+     * set at all: `"warn"` and `"off"` were both ignored and the check always
+     * exited 1, so a repo's only choice was an always-blocking check or deleting
+     * the `orphans` block (#181). Default: "error", matching the old behaviour.
+     */
+    "orphan-docs"?: RuleSeverity;
+    /**
+     * Re-derive a compiled instruction file's references from its `.spec.ts` and
+     * report the dead ones.
+     *
+     * The integrity hash answers "is this file still what the spec compiled to";
+     * it says nothing about whether the paths and scripts it NAMES still exist. So
+     * an artifact committed while its refs were live stayed green forever after
+     * the target was deleted — `compile` errored, `lint` said "hash valid" and
+     * exited 0 (#173). Default: "error", matching `compile`.
+     */
+    "spec-refs"?: RuleSeverity;
+    /**
+     * Near-duplicate rules WITHIN one spec, by NCD similarity — spec bloat, two
+     * rules saying the same thing in different words.
+     *
+     * Also previously untierable, and worse: it had no rule id at all, so there
+     * was no name a config could even mention (#181). Default: "error".
+     */
+    "duplicate-rules"?: RuleSeverity;
     /**
      * Require a `.spec.ts` behind each instruction file (CLAUDE.md / AGENTS.md) —
      * the file must be compiled from a typed spec, not hand-written. NARROW: only a
@@ -363,6 +393,20 @@ export interface VigilesConfig {
         rulesDir?: string | string[];
     }>;
     /** Orphan-docs check configuration. Include/exclude globs, tsconfig-style. */
+    /**
+     * Which bundles `lint` scores: `"root"` (default) or `"all"`.
+     *
+     * A monorepo holding `skills/` plus `plugins/  * /skills/` had its nested skills
+     * silently uncounted — the counters looked complete while whole surfaces were
+     * never read (#185). `"all"` scores every discovered bundle in one pass, so a
+     * CI gate keeps ONE exit code over the whole repo.
+     *
+     * Root-only remains the default because descending unconditionally would score
+     * vendored third-party plugins (a repo may keep a pinned corpus on disk) as if
+     * they were the project's own. The default no longer hides the skip: `lint`
+     * names the bundles it did not score.
+     */
+    bundles?: "root" | "all";
     orphans?: OrphansConfig;
     /**
      * Glob patterns of instruction/skill files to EXCLUDE from `lint` discovery

package/dist/core/validate.js

@@ -32,6 +32,24 @@ const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 // The default instruction file to validate when no config names one.
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
 exports.DEFAULT_RULES = {
+    // 🔴 BOTH DROP TO "warn", and that is a deliberate behaviour change.
+    //
+    // They used to feed the exit code directly and could not be tiered at all
+    // (#181), so a single unreferenced doc turned a PR red with no way to say
+    // "report it, do not block". Naming them as rules made the contradiction
+    // visible: both are HEURISTIC-BEHAVIORAL (an NCD similarity proxy, an
+    // "unreferenced" guess that an OSS sweep measured at ~100% false positives on
+    // nav-managed doc sites), and this repo's own calibration rule is that a
+    // heuristic never defaults to `error` because it cries wolf. `orphan-docs`
+    // already DECLARED `warn` in its meta while behaving as `error` — the gate
+    // caught that disagreement the moment the rule was registered properly.
+    //
+    // Set either to `"error"` to keep the old blocking behaviour.
+    // Hard error, like `compile` itself: a dead reference is decidable from the
+    // filesystem, not a proxy — the calibration rule's `external-decidable` tier.
+    "spec-refs": "error",
+    "orphan-docs": "warn",
+    "duplicate-rules": "warn",
     "require-instructions-spec": "warn",
     // Default OFF — the consistent `require-<surface>-spec` parallel. Skills are
     // legitimately hand-written, so requiring a .spec.ts per SKILL.md is the wrong

package/dist/harness-resolve-hooks.d.mts

@@ -0,0 +1,13 @@
+type ResolveContext = {
+    parentURL?: string;
+    conditions: string[];
+};
+type Resolved = {
+    url: string;
+    format?: string | null;
+    shortCircuit?: boolean;
+};
+type NextResolve = (specifier: string, context: ResolveContext) => Resolved | Promise<Resolved>;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<Resolved>;
+export {};
+//# sourceMappingURL=harness-resolve-hooks.d.mts.map

package/dist/harness-resolve-hooks.mjs

@@ -0,0 +1,50 @@
+/**
+ * Module-resolution hook for HARNESS scripts: 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.
+ *
+ * ⚠️ `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.
+ */
+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 ?? "";
+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/"))
+            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 };
+    }
+}
+//# sourceMappingURL=harness-resolve-hooks.mjs.map

package/dist/run-hook.d.ts

@@ -187,6 +187,13 @@ export interface HookRunResult extends ScriptRunResult {
      * a halt sets both.
      */
     readonly haltsTurn: boolean;
+    /**
+     * Every block mechanism that fired, from the closed {@link BlockMechanism}
+     * set. Reported so the next mechanism needs no new boolean on this interface —
+     * `haltsTurn` exists because the halt case was added as a one-off, and this is
+     * the shape that stops the pattern repeating.
+     */
+    readonly blockedBy: readonly BlockMechanism[];
     /**
      * The decision the hook expressed, preferring the structured
      * `permissionDecision` ("allow"|"deny"|"ask") then legacy `decision`
@@ -196,14 +203,34 @@ export interface HookRunResult extends ScriptRunResult {
 }
 /** Parse stdout as a hook JSON decision (pure, testable without a process). */
 export declare function parseHookOutput(stdout: string): HookOutput | null;
+/**
+ * The ways a hook can stop an action — a CLOSED set, listed once.
+ *
+ * 🔴 WHY A TABLE AND NOT THREE `||` TERMS. `decideHook` used to be a boolean
+ * expression over three mechanisms while `HookOutput` declared a fourth,
+ * `continue`, that nothing read (#174). The consequence was not a missed
+ * detection but an INVERTED verdict in the flagship feature: a real guard that
+ * stopped every command in the disaster battery was reported by
+ * `assertBlocksDisasters` as blocking none of them.
+ *
+ * A `||` chain has no shape that can be incomplete — every term is optional by
+ * construction, so nothing can say "you declared a mechanism and did not handle
+ * it". `Record<BlockMechanism, …>` can: adding a member to the union without
+ * adding its row is a tsc error, the same device that keeps `RULE_META` honest.
+ */
+export type BlockMechanism = "exit-code" | "deny-decision" | "halt-field";
 /**
  * Decide whether a hook result blocked, and the normalized decision. Pure, so
  * the policy is unit-testable independent of spawning anything.
+ *
+ * Folds the closed {@link BLOCK_MECHANISMS} table rather than testing three
+ * conditions inline, so a mechanism cannot be declared and left unhandled.
  */
 export declare function decideHook(exitCode: number, json: HookOutput | null, protocol?: HookProtocol): {
     blocked: boolean;
     decision: HookRunResult["decision"];
     haltsTurn: boolean;
+    blockedBy: readonly BlockMechanism[];
 };
 /**
  * The hook layer over {@link runScriptWith}: serialize the event to stdin, run

package/dist/run-hook.js

@@ -123,23 +123,42 @@ function parseHookOutput(stdout) {
         return null;
     }
 }
+const BLOCK_MECHANISMS = {
+    "exit-code": ({ exitCode, protocol }) => exitCode === protocol.blockExitCode,
+    "deny-decision": ({ json, protocol }) => {
+        const decision = json?.hookSpecificOutput?.permissionDecision ?? json?.decision;
+        return (decision !== undefined && protocol.denyDecisionValues.includes(decision));
+    },
+    // Read from the PORT, never hard-coded: `"continue"` is a documented Claude
+    // Code fact and unverified for Codex, so the harness that has it declares it
+    // (core ⊄ adapter). `=== false` and not falsy — an absent field is not a halt.
+    "halt-field": ({ json, protocol }) => {
+        const field = protocol.haltsTurnField;
+        return field !== undefined && json?.[field] === false;
+    },
+};
 /**
  * Decide whether a hook result blocked, and the normalized decision. Pure, so
  * the policy is unit-testable independent of spawning anything.
+ *
+ * Folds the closed {@link BLOCK_MECHANISMS} table rather than testing three
+ * conditions inline, so a mechanism cannot be declared and left unhandled.
  */
 function decideHook(exitCode, json, protocol = hook_protocol_js_1.claudeCodeHookProtocol) {
     const permission = json?.hookSpecificOutput?.permissionDecision;
     const decision = permission ?? json?.decision;
-    // The halt field is read from the PORT, never hard-coded: `"continue"` is a
-    // documented Claude Code fact and an unverified one for Codex, so the harness
-    // that has it declares it (core ⊄ adapter). `=== false` and not falsy —
-    // an absent field must not read as a halt.
-    const haltField = protocol.haltsTurnField;
-    const haltsTurn = haltField !== undefined && json?.[haltField] === false;
-    const blocked = exitCode === protocol.blockExitCode ||
-        haltsTurn ||
-        (decision !== undefined && protocol.denyDecisionValues.includes(decision));
-    return { blocked, decision, haltsTurn };
+    const ctx = { exitCode, json, protocol };
+    // EVERY mechanism is evaluated, not the first match: a hook may both exit 2
+    // and halt the turn, and reporting only the first would make `haltsTurn`
+    // depend on the table's order.
+    const blockedBy = Object.keys(BLOCK_MECHANISMS).filter((kind) => BLOCK_MECHANISMS[kind](ctx));
+    return {
+        blocked: blockedBy.length > 0,
+        decision,
+        // Derived, not computed twice — the next mechanism needs no new boolean.
+        haltsTurn: blockedBy.includes("halt-field"),
+        blockedBy,
+    };
 }
 /**
  * The hook layer over {@link runScriptWith}: serialize the event to stdin, run
@@ -150,8 +169,8 @@ function decideHook(exitCode, json, protocol = hook_protocol_js_1.claudeCodeHook
 function runHookWith(command, input, opts, deps) {
     const res = (0, run_script_js_1.runScriptWith)(command, JSON.stringify(input), opts, deps);
     const json = parseHookOutput(res.stdout);
-    const { blocked, decision, haltsTurn } = decideHook(res.exitCode, json);
-    return { ...res, json, blocked, decision, haltsTurn };
+    const { blocked, decision, haltsTurn, blockedBy } = decideHook(res.exitCode, json);
+    return { ...res, json, blocked, decision, haltsTurn, blockedBy };
 }
 /**
  * Run a hook command, piping `input` as JSON to its stdin, and report the exit

package/dist/test.d.ts

@@ -54,7 +54,7 @@ export { recordCheck } from "./check-count.js";
 export { runScript } from "./run-script.js";
 export type { RunScriptOptions, ScriptRunResult } from "./run-script.js";
 export { runHook, parseHookOutput, decideHook, propertyHook, fileToolEvents, egressRoutes, } from "./run-hook.js";
-export type { HookRunResult, RunHookOptions, HookInput, HookOutput, HookPropertyResult, FileToolEventOptions, } from "./run-hook.js";
+export type { HookRunResult, BlockMechanism, RunHookOptions, HookInput, HookOutput, HookPropertyResult, FileToolEventOptions, } from "./run-hook.js";
 export * from "./harness-assert.js";
 export { experimental_emitTool, experimental_parseEmitted, experimental_assertEmittedOk, type EmitFieldSchema, type EmitObjectSchema, type EmitPropertySchema, type EmitTrackSchema, type EmitToolDefinition, type ExperimentalEmitTool, } from "./experimental-emit.js";
 export { loadHook } from "./load-hook.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "23.0.0",
+  "version": "25.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",