vigiles 24.0.0 → 25.0.0

package/dist/cli.js

@@ -17,6 +17,7 @@ exports.discoverNestedBundles = discoverNestedBundles;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const minimatch_1 = require("minimatch");
+const repo_path_js_1 = require("./core/repo-path.js");
 const node_child_process_1 = require("node:child_process");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./core/generate-types.js");
@@ -288,11 +289,14 @@ function printWarnings(specFile, warnings) {
 /** Compile a generator-skill spec from source → SKILL.md. Returns validity. */
 function compileGeneratorSkillToFile(specPath, source) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors } = (0, compile_generator_js_1.compileGeneratorSkill)(source, {
+    const { artifact, errors } = (0, compile_generator_js_1.compileGeneratorSkill)(source, {
         basePath: process.cwd(),
         specFile: specPath,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    // Written only when the compile is clean: `artifact` is null otherwise, and
+    // `writeArtifact` takes nothing else.
+    if (artifact)
+        writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath} (generator skill)`);
         return true;
@@ -393,14 +397,17 @@ function writeInstructionMirrors(primaryOutput, harnesses) {
 /** Compile a declarative SkillSpec → SKILL.md. */
 function compileSkillToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors, warnings } = (0, compile_js_1.compileSkill)(spec, {
+    const { artifact, errors, warnings } = (0, compile_js_1.compileSkill)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         // The SKILL.md frontmatter profile comes from the resolved harness — a Codex
         // repo gets a minimal (name + description) SKILL.md; CC gets the full set.
         dialect,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    // Written only when the compile is clean: `artifact` is null otherwise, and
+    // `writeArtifact` takes nothing else.
+    if (artifact)
+        writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
         printWarnings(specPath, warnings);
@@ -414,12 +421,15 @@ function compileSkillToFile(spec, specPath, dialect) {
 /** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
 function compileAgentToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors, warnings } = (0, compile_js_1.compileAgent)(spec, {
+    const { artifact, errors, warnings } = (0, compile_js_1.compileAgent)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         dialect,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    // Written only when the compile is clean: `artifact` is null otherwise, and
+    // `writeArtifact` takes nothing else.
+    if (artifact)
+        writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
         printWarnings(specPath, warnings);
@@ -437,11 +447,14 @@ function compileAgentToFile(spec, specPath, dialect) {
  */
 function compileRailwayToFile(spec, specPath, knownAgents) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors } = (0, compile_js_1.compileRailway)(spec, {
+    const { artifact, errors } = (0, compile_js_1.compileRailway)(spec, {
         specFile: specPath,
         knownAgents,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    // Written only when the compile is clean: `artifact` is null otherwise, and
+    // `writeArtifact` takes nothing else.
+    if (artifact)
+        writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
         return true;
@@ -1294,6 +1307,18 @@ async function checkSpecRefs(config, silent, dialect) {
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
 }
+/**
+ * Write a compiled artifact. Accepts ONLY a {@link StampedMarkdown}, so a body
+ * that failed to compile cannot reach the disk — there is no stamp to pass.
+ *
+ * This replaces four copies of `writeFileSync(path, markdown)` that ran BEFORE
+ * their error check (#173, reproduced in the skill/subagent/railway/generator
+ * compilers after the CLAUDE.md one was fixed). Guarding four call sites would
+ * have left the fifth writable; the type leaves nothing to remember.
+ */
+function writeArtifact(outputPath, artifact) {
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), artifact);
+}
 async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
@@ -6222,14 +6247,12 @@ async function runHookProgramCommand(file) {
 function ensureReportGitignored(cwd, entries) {
     if (entries.length === 0)
         return;
-    // An `--out` outside the repo produced entries like
-    // `../../../../private/tmp/x/vigiles-report.json`, which ignore NOTHING —
-    // .gitignore does not reach outside its own tree — and accumulate one dead
-    // block per output path. Worse in principle than in practice: `audit` is
-    // documented as a read-only report, and this made it edit a tracked file for
-    // no benefit at all. Inside the repo the write is expected and documented.
-    if (entries.some((e) => e.startsWith("..") || (0, node_path_1.isAbsolute)(e)))
-        return;
+    // 🔴 THE GUARD THAT USED TO BE HERE IS GONE, and its absence is the point.
+    // It checked at the write site that no entry escaped the repo (#176.8) — which
+    // worked, and left the bug writable: the next caller to build an entry list
+    // still got a bare `string[]`. `RepoRelativePath` moves the check into the
+    // TYPE, so an escaping path cannot be handed to this function at all. One
+    // place mints them (`repoRelative`), and it returns null instead.
     const gi = (0, node_path_1.resolve)(cwd, ".gitignore");
     try {
         if (!(0, node_fs_1.existsSync)(gi)) {
@@ -7135,10 +7158,17 @@ async function main() {
                 // backslashes (`relative()` yields `reports\x` on Windows, which would
                 // never match `reports/x`).
                 if (wroteReports.length > 0) {
-                    const rel = wroteReports.map((f) => {
-                        const r = (0, node_path_1.relative)(process.cwd(), (0, node_path_1.resolve)(outDir, f)) || f;
-                        return node_path_1.sep === "/" ? r : r.split(node_path_1.sep).join("/");
-                    });
+                    // Only paths that PROVABLY sit inside the repo can be minted, so an
+                    // `--out` pointing elsewhere yields nothing to write rather than a
+                    // dead `../../..` entry.
+                    const rel = wroteReports
+                        .map((f) => (0, repo_path_js_1.repoRelative)(process.cwd(), (0, node_path_1.resolve)(outDir, f), {
+                        relative: node_path_1.relative,
+                        resolve: node_path_1.resolve,
+                        isAbsolute: node_path_1.isAbsolute,
+                        sep: node_path_1.sep,
+                    }))
+                        .filter((p) => p !== null);
                     ensureReportGitignored(process.cwd(), rel);
                 }
                 // A shareable deep-link for a public GitHub repo: the in-browser demo

package/dist/core/compile-generator.d.ts

@@ -25,6 +25,7 @@
  * Gate references (`cmd`/`file`/`project`) are collected and verified, so the
  * cross-referencing moat works on generators too (literal args only).
  */
+import { type StampedMarkdown } from "./compile.js";
 export interface GeneratorError {
     type: "stale-file" | "stale-command";
     message: string;
@@ -34,6 +35,11 @@ export interface CompileGeneratorResult {
     errors: GeneratorError[];
 }
 export interface CompileGeneratorSkillResult {
+    /**
+     * 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: GeneratorError[];
 }

package/dist/core/compile-generator.js

@@ -278,6 +278,9 @@ function compileGeneratorSkill(source, options = {}) {
         !genArg.body) {
         return {
             markdown: "",
+            // No stamp for a spec that did not compile — the error branch has nothing
+            // to write, which is the whole point of the field.
+            artifact: null,
             errors: [
                 {
                     type: "stale-command",
@@ -300,7 +303,7 @@ function compileGeneratorSkill(source, options = {}) {
     }
     fm.push("", "---");
     const content = `${fm.join("\n")}\n\n${body.trim()}\n`;
-    return { markdown: (0, compile_js_1.addHash)(content, specFile), errors };
+    return { ...(0, compile_js_1.seal)(content, errors, specFile), errors };
 }
 /**
  * Compile a generator's SOURCE text to SKILL.md markdown + verified-ref

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/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": "24.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",