vigiles 27.1.7 → 27.3.0

package/dist/core/compile.d.ts

@@ -56,7 +56,7 @@ export declare function verifyHash(content: string): {
  */
 /** @internal */ export declare function estimateTokens(text: string): number;
 export interface CompileError {
-    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "effect-in-skill" | "inline-code-too-long";
+    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "effect-in-skill" | "inline-code-too-long" | "entry-too-long" | "section-too-large";
     message: string;
     path?: string;
 }
@@ -69,6 +69,13 @@ export declare function validateGlobRef(pattern: string, basePath: string): Comp
 export interface CompileClaudeResult {
     markdown: string;
     errors: CompileError[];
+    /**
+     * Budget findings — never errors. An over-long `keyFiles` description or a
+     * bloated section does not break the harness, it makes every request more
+     * expensive, so it must not stop a faithful adoption from compiling. Same
+     * channel discipline as `checkInlineCode`.
+     */
+    warnings: CompileError[];
     linterResults: LinterCheckResult[];
     /** Estimated token count of compiled output (~4 chars/token). */
     tokens: number;
@@ -76,6 +83,10 @@ export interface CompileClaudeResult {
     targets: string[];
 }
 export interface CompileClaudeOptions {
+    /** Per-entry `keyFiles`/`commands` character budget (0 disables). */
+    maxEntryChars?: number;
+    /** Per-section character budget, beside the line budget (0 disables). */
+    maxSectionChars?: number;
     basePath?: string;
     specFile?: string;
     /** Injected harness dialect; its instructionTargets[0] is the default target. */
@@ -97,6 +108,34 @@ export interface CompileClaudeOptions {
     /** Per-linter verification mode: true (full), "catalog-only", or false (skip). */
     linterModes?: Record<string, boolean | "catalog-only">;
 }
+/**
+ * The generous per-section line guard. Exported because `adopt` raises it to
+ * exactly the longest adopted section and must name the same number rather than
+ * keep a second copy that drifts.
+ */
+export declare const DEFAULT_MAX_SECTION_LINES = 200;
+/**
+ * Per-ENTRY budget for a `keyFiles` / `commands` description, in characters.
+ *
+ * WHY AN ENTRY AND NOT THE SECTION. The list is append-only in practice: every
+ * session adds a row and none removes one, so the section total says "too big"
+ * long after the point where a reader could act on it, and it names no
+ * offender. A per-entry budget names the row. 200 is deliberately loose — an
+ * entry is a POINTER ("what is this file for"), and anything that needs a
+ * paragraph has a better home in that file's own header, where it is read when
+ * someone opens the file rather than on every request.
+ */
+export declare const DEFAULT_MAX_ENTRY_CHARS = 200;
+/**
+ * Per-section budget in CHARACTERS, beside the line budget.
+ *
+ * The line guard alone is measured to be useless on the shape that actually
+ * bites: this repo's own `Positioning` section was 24 lines and 20 416
+ * characters, passing a 200-LINE gate with two orders of magnitude to spare.
+ * Long lines are the normal shape of compiled prose, so lines do not measure
+ * cost — characters do, because that is what the harness loads.
+ */
+export declare const DEFAULT_MAX_SECTION_CHARS = 15000;
 /**
  * Compile a ClaudeSpec into markdown.
  *

package/dist/core/compile.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_SECTION_CHARS = exports.DEFAULT_MAX_ENTRY_CHARS = exports.DEFAULT_MAX_SECTION_LINES = void 0;
 exports.computeHash = computeHash;
 exports.addHash = addHash;
 exports.seal = seal;
@@ -318,7 +319,79 @@ function compileRule(id, rule) {
 // generous (don't-cry-wolf): real prose sections are short, so this only trips on
 // an egregious dump (a whole essay pasted into one section / prose``).
 // Override per spec with `maxSectionLines`; `maxTokens` is the global backstop.
-const DEFAULT_MAX_SECTION_LINES = 200;
+/**
+ * The generous per-section line guard. Exported because `adopt` raises it to
+ * exactly the longest adopted section and must name the same number rather than
+ * keep a second copy that drifts.
+ */
+exports.DEFAULT_MAX_SECTION_LINES = 200;
+/**
+ * Per-ENTRY budget for a `keyFiles` / `commands` description, in characters.
+ *
+ * WHY AN ENTRY AND NOT THE SECTION. The list is append-only in practice: every
+ * session adds a row and none removes one, so the section total says "too big"
+ * long after the point where a reader could act on it, and it names no
+ * offender. A per-entry budget names the row. 200 is deliberately loose — an
+ * entry is a POINTER ("what is this file for"), and anything that needs a
+ * paragraph has a better home in that file's own header, where it is read when
+ * someone opens the file rather than on every request.
+ */
+exports.DEFAULT_MAX_ENTRY_CHARS = 200;
+/**
+ * Per-section budget in CHARACTERS, beside the line budget.
+ *
+ * The line guard alone is measured to be useless on the shape that actually
+ * bites: this repo's own `Positioning` section was 24 lines and 20 416
+ * characters, passing a 200-LINE gate with two orders of magnitude to spare.
+ * Long lines are the normal shape of compiled prose, so lines do not measure
+ * cost — characters do, because that is what the harness loads.
+ */
+exports.DEFAULT_MAX_SECTION_CHARS = 15000;
+/**
+ * Budget findings for the two append-only maps and for section size. WARNINGS
+ * by construction (`lint-rule-calibration`: severity tracks confidence, and a
+ * gate that fails every real repo on day one is switched off on day two — this
+ * repo's own corpus opens at 26 over-long entries).
+ */
+function checkContentBudgets(spec, specFile, maxEntryChars, maxSectionChars) {
+    const warns = [];
+    const entries = [
+        ["keyFiles", spec.keyFiles],
+        ["commands", spec.commands],
+    ];
+    for (const [field, map] of entries) {
+        if (!map || maxEntryChars <= 0)
+            continue;
+        for (const [key, description] of Object.entries(map)) {
+            if (description.length <= maxEntryChars)
+                continue;
+            warns.push({
+                type: "entry-too-long",
+                path: specFile,
+                message: `${field}[${JSON.stringify(key)}] description is ${String(description.length)} ` +
+                    `characters (budget ${String(maxEntryChars)}). An entry is a pointer — say what the ` +
+                    `file is for in one line and move the explanation into its own header, which is read ` +
+                    `when someone opens it rather than on every request.`,
+            });
+        }
+    }
+    if (spec.sections && maxSectionChars > 0) {
+        for (const [name, body] of Object.entries(spec.sections)) {
+            // Fragment-valued sections are assembled later; only plain prose is
+            // measurable here, and it is the shape that grows.
+            if (typeof body !== "string" || body.length <= maxSectionChars)
+                continue;
+            warns.push({
+                type: "section-too-large",
+                path: specFile,
+                message: `section ${JSON.stringify(name)} is ${String(body.length)} characters ` +
+                    `(budget ${String(maxSectionChars)}). The line guard cannot see this — long lines are ` +
+                    `the normal shape of compiled prose — and every character is loaded on every request.`,
+            });
+        }
+    }
+    return warns;
+}
 // A key-files entry is a POINTER, not an essay: the prose about why a file is
 // shaped the way it is belongs in that file's own header, where it is read when
 // the file is opened. Calibrated against this repo on 2026-09-08 — 285 entries,
@@ -343,7 +416,7 @@ function validateSectionContent(name, text, maxSectionLines) {
             break;
         }
     }
-    const max = maxSectionLines ?? DEFAULT_MAX_SECTION_LINES;
+    const max = maxSectionLines ?? exports.DEFAULT_MAX_SECTION_LINES;
     if (contentLines.length > max) {
         errors.push({
             type: "section-too-long",
@@ -546,6 +619,7 @@ function compileClaude(spec, options = {}) {
     return {
         markdown,
         errors,
+        warnings: checkContentBudgets(spec, specFile, options.maxEntryChars ?? exports.DEFAULT_MAX_ENTRY_CHARS, options.maxSectionChars ?? exports.DEFAULT_MAX_SECTION_CHARS),
         linterResults: rules.linterResults,
         tokens,
         targets: allTargets,

package/dist/core/dialect.d.ts

@@ -23,6 +23,8 @@
  * `HarnessDialect.skillFrontmatter`.
  */
 import type { HarnessVocabulary } from "./vocabulary.js";
+import type { EventCapabilityTable } from "./event-capability.js";
+import type { InstructionBudget } from "./instruction-weight.js";
 export type SkillFrontmatterProfile = "claude-code" | "minimal";
 export interface HarnessDialect {
     /** Stable identifier, e.g. "claude-code". */
@@ -52,13 +54,28 @@ export interface HarnessDialect {
      * cries wolf on a PostToolUse feedback/nudge hook). Optional (additive,
      * non-breaking) — absent ⇒ the harness's block semantics are undeclared and the
      * check does not run for it.
+     *
+     *   @deprecated Superseded by {@link eventCapabilities}, from which this list is
+     * now DERIVED (`blockIneffectiveEvents`) and against which it is asserted. Kept
+     * because removing a public port field breaks third-party adapters; it will go
+     * in the next major.
+     *
+     * 🔴 THE NAME IS WRONG AND THAT MATTERED. "No effect" reads as "a hook here does
+     * nothing", but it MEANS "no effect OF A BLOCK" — Claude Code's `SessionStart`
+     * is in this list and injects context perfectly well; exit 2 is the only thing
+     * it ignores. Deriving the list caught this: the obvious predicate
+     * (`honours === []`) silently dropped SessionStart and would have changed what
+     * `hook-block-ineffective` flags.
      */
     readonly noEffectHookEvents?: readonly string[];
     /**
      * The subset of blocking events whose deny REQUIRES the structured
      * `permissionDecision` field (e.g. Claude Code's `PreToolUse`), where the
      * legacy top-level `decision` field is silently ignored. The basis for the
-     * `hook-block-ineffective` "wrong-field" check. Optional (additive).
+     * `hook-block-ineffective` "wrong-field" check. Optional (additive).   *
+     * @deprecated Superseded by {@link eventCapabilities} (`denyShape:
+     * "permission-decision"`), from which this list is derived and against which it
+     * is asserted. Kept for third-party adapters; goes in the next major.
      */
     readonly permissionDecisionHookEvents?: readonly string[];
     /** Instruction-file targets the harness reads (also the h1 heading). */
@@ -98,6 +115,31 @@ export interface HarnessDialect {
      * and its unknowns become advisories rather than silence.
      */
     readonly hookEventVocabulary?: HarnessVocabulary;
+    /**
+     * What this harness loads WITHOUT being asked, how it MEASURES that, and what
+     * it does when there is too much — {@link InstructionBudget}.
+     *
+     * On the dialect because it is a FORMAT fact (which files, counted in which
+     * unit), and because the browser engine is handed a dialect. Optional: absent
+     * ⇒ the weight report does not run for that adapter, which is the honest
+     * answer for a harness whose limits nobody has read.
+     */
+    readonly instructionBudget?: InstructionBudget;
+    /**
+     * What each hook event CARRIES and HONOURS — {@link EventCapabilityTable}.
+     *
+     * The single table three flat lists had been approximating: `hookEvents`
+     * (membership), `noEffectHookEvents` (blocks ignored) and
+     * `permissionDecisionHookEvents` (deny needs a field) all ask about an event,
+     * none relate it to its PAYLOAD, and the fourth — `injectableEvents` — sits on
+     * a different port entirely. A list per question cannot answer a question
+     * about a PAIR, which is what "is this role legal on this event?" is.
+     *
+     * Optional (additive, non-breaking): absent ⇒ the flat lists still decide, and
+     * the (role, event) compatibility check does not run for that adapter. Present
+     * ⇒ it is the source the derived lists are read from, so the two cannot drift.
+     */
+    readonly eventCapabilities?: EventCapabilityTable;
     /**
      * The subagent-tool catalog as a {@link HarnessVocabulary}. Same contract as
      * `hookEventVocabulary`; absent ⇒ synthesised from `builtinAgentTools`

package/dist/core/event-capability.d.ts

@@ -0,0 +1,128 @@
+/**
+ * What a hook event CARRIES and what it HONOURS — the one table three lists had
+ * been disagreeing across.
+ *
+ * THE DEFECT THIS EXISTS FOR (measured 2026-09-16, six fixtures compiled at HEAD
+ * and run through `hook-runtime run-program`): a compiled hook can name a role
+ * and an event that cannot work together, and nothing says so. A prompt-gate on
+ * `PreToolUse` reads an absent `prompt` as `""` and allows everything. A
+ * stop-gate on `SessionStart` exits 2 into an event that ignores it. A file-gate
+ * on `Stop` matches a tool on an event that carries none. `lint` and `audit`
+ * found ZERO on that fixture; `tsc` caught one of six, and `vigiles compile`
+ * does not run `tsc` at all.
+ *
+ * The facts needed to reject all of them already existed — scattered across
+ * `hookEvents` (dialect), `noEffectHookEvents` (dialect),
+ * `permissionDecisionHookEvents` (dialect) and `injectableEvents` (hookProtocol),
+ * three of them optional, none of them relating an event to what it CARRIES. A
+ * list per question cannot answer a question about the pair.
+ *
+ * WHY THE DIALECT AND NOT THE HOOK PROTOCOL (which is where the fourth list
+ * lives, and where the original proposal put this): the dialect is REQUIRED of
+ * every adapter while `hookProtocol` is optional — OpenCode has hook events and
+ * no shell-hook protocol — and `scanFiles`, the browser-side engine, is handed a
+ * layout and a dialect and never a protocol. Putting the table on the protocol
+ * would have meant widening a public signature to carry one list to the place
+ * three already are.
+ *
+ * WHY IT IS PARTIAL, AND WHY THAT IS THE HONEST SHAPE: Claude Code documents 31
+ * hook events. We know the capabilities of nine. Filling in the other 22 would
+ * be inventing facts about somebody else's product, which is the failure mode
+ * `vocabulary.ts` was written to stop — so this mirrors it: a recorded capture,
+ * a partial table, and a TOTAL classifier whose fourth answer is `unknown`.
+ * Unknown is FAIL-OPEN by design: a check that cannot know stays silent rather
+ * than accusing, because a false rejection at compile time costs more than a
+ * missed one (`lint-rule-calibration`).
+ */
+/**
+ * The channels a hook can reach the harness through. Distinct from the ROLE an
+ * author writes: a role is a promise about the return type, a channel is what
+ * the harness will actually do with it.
+ *
+ * - `veto` — a deny STOPS the thing (the tool call, the prompt, the stopping).
+ * - `ask` — a decision can defer to the human instead of allow/deny.
+ * - `inject` — `additionalContext` reaches the MODEL.
+ * - `feedback` — a non-zero exit reaches the model as text, but stops nothing.
+ * - `halt` — the whole turn can be ended (Claude Code's `continue: false`).
+ */
+export type HookChannel = "veto" | "ask" | "inject" | "feedback" | "halt";
+/** What the event hands the hook — and therefore what a decide() can read. */
+export type EventPayload = "tool" | "prompt" | "stop" | "session" | "none";
+/**
+ * How a deny must be SPELLED on this event. Deliberately NOT folded into
+ * `honours: "ask"`, though on Claude Code both are `PreToolUse` alone and the
+ * merge would look free today: "this event can ask a human" and "this event's
+ * deny needs a structured field rather than an exit code" are different facts
+ * about different mechanisms, and a coincidence on one harness is not a reason
+ * to make them inexpressible apart on the next.
+ */
+export type DenyShape = "exit-code" | "permission-decision";
+/** Everything the compiler needs to judge one (role, event) pair. */
+export interface EventCapability {
+    readonly carries: EventPayload;
+    readonly honours: readonly HookChannel[];
+    /** Whether a tool matcher is meaningful here (it needs `carries: "tool"`). */
+    readonly matcher: boolean;
+    readonly denyShape: DenyShape;
+}
+/**
+ * A capability table for the events an adapter has actually recorded, with the
+ * vendor artifact it was read from — the same shape, and the same reason, as
+ * {@link HarnessVocabulary}.
+ */
+export interface EventCapabilityTable {
+    /** e.g. `"code.claude.com/docs/en/hooks + measured on claude-code 2.1.273"`. */
+    readonly capturedFrom: string;
+    readonly events: Readonly<Record<string, EventCapability>>;
+}
+/** Total: every name gets an answer, and `unknown` is one of them. */
+export type CapabilityVerdict = {
+    readonly kind: "known";
+    readonly event: string;
+    readonly capability: EventCapability;
+} | {
+    readonly kind: "unknown";
+    readonly event: string;
+};
+/** Look one event up in a table that may not hold it. */
+export declare function capabilityOf(table: EventCapabilityTable | undefined, event: string): CapabilityVerdict;
+/**
+ * Does this event honour this channel? THREE answers, never two — collapsing
+ * `unknown` into `false` is how a partial table turns into a confident wrong
+ * rejection, which is the bug this module is written against.
+ */
+export declare function honoursChannel(table: EventCapabilityTable | undefined, event: string, channel: HookChannel): boolean | "unknown";
+/** The events honouring a channel — the derived form of the old flat lists. */
+export declare function eventsHonouring(table: EventCapabilityTable | undefined, channel: HookChannel): readonly string[];
+/**
+ * The events where a BLOCK DECISION reaches nobody — neither vetoing the action
+ * nor feeding the model. The derived replacement for `noEffectHookEvents`.
+ *
+ * 🔴 IT IS NOT `honours === []`, and getting that wrong is what the derivation
+ * caught: `noEffectHookEvents` is named for "no effect" but MEANS "no effect OF
+ * A BLOCK". Claude Code's `SessionStart` is in that list and honours `inject`
+ * perfectly well — exit 2 is what it ignores. An `honours.length === 0` reading
+ * would have dropped SessionStart from the derived list and quietly changed
+ * what `hook-block-ineffective` flags.
+ *
+ * So the predicate is "honours neither veto nor feedback": a deny there stops
+ * nothing and tells nobody, which is the property the check is about. An event
+ * absent from the table is NOT reported (the old flat list could not express
+ * "we have not looked"; this can).
+ */
+export declare function blockIneffectiveEvents(table: EventCapabilityTable | undefined): readonly string[];
+/** The derived replacement for `permissionDecisionHookEvents`. */
+export declare function permissionDecisionEvents(table: EventCapabilityTable | undefined): readonly string[];
+/** Enough of a dialect to answer the event questions, without importing one. */
+export interface EventFactSource {
+    readonly eventCapabilities?: EventCapabilityTable;
+    readonly noEffectHookEvents?: readonly string[];
+    readonly permissionDecisionHookEvents?: readonly string[];
+}
+/** Events honouring `inject`: the table, else the protocol's legacy list. */
+export declare function injectableEventsOf(source: EventFactSource | undefined, legacy: readonly string[] | undefined): readonly string[];
+/** Events where a block reaches nobody: the table, else the legacy list. */
+export declare function blockIneffectiveEventsOf(source: EventFactSource | undefined): readonly string[];
+/** Events whose deny needs the structured field: the table, else the list. */
+export declare function permissionDecisionEventsOf(source: EventFactSource | undefined): readonly string[];
+//# sourceMappingURL=event-capability.d.ts.map

package/dist/core/event-capability.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * What a hook event CARRIES and what it HONOURS — the one table three lists had
+ * been disagreeing across.
+ *
+ * THE DEFECT THIS EXISTS FOR (measured 2026-09-16, six fixtures compiled at HEAD
+ * and run through `hook-runtime run-program`): a compiled hook can name a role
+ * and an event that cannot work together, and nothing says so. A prompt-gate on
+ * `PreToolUse` reads an absent `prompt` as `""` and allows everything. A
+ * stop-gate on `SessionStart` exits 2 into an event that ignores it. A file-gate
+ * on `Stop` matches a tool on an event that carries none. `lint` and `audit`
+ * found ZERO on that fixture; `tsc` caught one of six, and `vigiles compile`
+ * does not run `tsc` at all.
+ *
+ * The facts needed to reject all of them already existed — scattered across
+ * `hookEvents` (dialect), `noEffectHookEvents` (dialect),
+ * `permissionDecisionHookEvents` (dialect) and `injectableEvents` (hookProtocol),
+ * three of them optional, none of them relating an event to what it CARRIES. A
+ * list per question cannot answer a question about the pair.
+ *
+ * WHY THE DIALECT AND NOT THE HOOK PROTOCOL (which is where the fourth list
+ * lives, and where the original proposal put this): the dialect is REQUIRED of
+ * every adapter while `hookProtocol` is optional — OpenCode has hook events and
+ * no shell-hook protocol — and `scanFiles`, the browser-side engine, is handed a
+ * layout and a dialect and never a protocol. Putting the table on the protocol
+ * would have meant widening a public signature to carry one list to the place
+ * three already are.
+ *
+ * WHY IT IS PARTIAL, AND WHY THAT IS THE HONEST SHAPE: Claude Code documents 31
+ * hook events. We know the capabilities of nine. Filling in the other 22 would
+ * be inventing facts about somebody else's product, which is the failure mode
+ * `vocabulary.ts` was written to stop — so this mirrors it: a recorded capture,
+ * a partial table, and a TOTAL classifier whose fourth answer is `unknown`.
+ * Unknown is FAIL-OPEN by design: a check that cannot know stays silent rather
+ * than accusing, because a false rejection at compile time costs more than a
+ * missed one (`lint-rule-calibration`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capabilityOf = capabilityOf;
+exports.honoursChannel = honoursChannel;
+exports.eventsHonouring = eventsHonouring;
+exports.blockIneffectiveEvents = blockIneffectiveEvents;
+exports.permissionDecisionEvents = permissionDecisionEvents;
+exports.injectableEventsOf = injectableEventsOf;
+exports.blockIneffectiveEventsOf = blockIneffectiveEventsOf;
+exports.permissionDecisionEventsOf = permissionDecisionEventsOf;
+/** Look one event up in a table that may not hold it. */
+function capabilityOf(table, event) {
+    const capability = table?.events[event];
+    return capability === undefined
+        ? { kind: "unknown", event }
+        : { kind: "known", event, capability };
+}
+/**
+ * Does this event honour this channel? THREE answers, never two — collapsing
+ * `unknown` into `false` is how a partial table turns into a confident wrong
+ * rejection, which is the bug this module is written against.
+ */
+function honoursChannel(table, event, channel) {
+    const v = capabilityOf(table, event);
+    return v.kind === "unknown" ? "unknown" : v.capability.honours.includes(channel); // prettier-ignore
+}
+/** The events honouring a channel — the derived form of the old flat lists. */
+function eventsHonouring(table, channel) {
+    return Object.entries(table?.events ?? {})
+        .filter(([, c]) => c.honours.includes(channel))
+        .map(([name]) => name);
+}
+/**
+ * The events where a BLOCK DECISION reaches nobody — neither vetoing the action
+ * nor feeding the model. The derived replacement for `noEffectHookEvents`.
+ *
+ * 🔴 IT IS NOT `honours === []`, and getting that wrong is what the derivation
+ * caught: `noEffectHookEvents` is named for "no effect" but MEANS "no effect OF
+ * A BLOCK". Claude Code's `SessionStart` is in that list and honours `inject`
+ * perfectly well — exit 2 is what it ignores. An `honours.length === 0` reading
+ * would have dropped SessionStart from the derived list and quietly changed
+ * what `hook-block-ineffective` flags.
+ *
+ * So the predicate is "honours neither veto nor feedback": a deny there stops
+ * nothing and tells nobody, which is the property the check is about. An event
+ * absent from the table is NOT reported (the old flat list could not express
+ * "we have not looked"; this can).
+ */
+function blockIneffectiveEvents(table) {
+    return Object.entries(table?.events ?? {})
+        .filter(([, c]) => !c.honours.includes("veto") && !c.honours.includes("feedback"))
+        .map(([name]) => name);
+}
+/** The derived replacement for `permissionDecisionHookEvents`. */
+function permissionDecisionEvents(table) {
+    return Object.entries(table?.events ?? {})
+        .filter(([, c]) => c.denyShape === "permission-decision")
+        .map(([name]) => name);
+}
+/** Events honouring `inject`: the table, else the protocol's legacy list. */
+function injectableEventsOf(source, legacy) {
+    return source?.eventCapabilities
+        ? eventsHonouring(source.eventCapabilities, "inject")
+        : (legacy ?? []);
+}
+/** Events where a block reaches nobody: the table, else the legacy list. */
+function blockIneffectiveEventsOf(source) {
+    return source?.eventCapabilities
+        ? blockIneffectiveEvents(source.eventCapabilities)
+        : (source?.noEffectHookEvents ?? []);
+}
+/** Events whose deny needs the structured field: the table, else the list. */
+function permissionDecisionEventsOf(source) {
+    return source?.eventCapabilities
+        ? permissionDecisionEvents(source.eventCapabilities)
+        : (source?.permissionDecisionHookEvents ?? []);
+}
+//# sourceMappingURL=event-capability.js.map

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

@@ -37,6 +37,7 @@ import { type BashEffect } from "./bash-effects.js";
 import { type SHA256Hash } from "./hash.js";
 import type { HarnessDialect } from "./dialect.js";
 import type { HookProtocol } from "./hook-protocol.js";
+import { type EventCapabilityTable } from "./event-capability.js";
 import { type ProviderName, type NeedSpec, type HookCtx } from "./hook-providers.js";
 import { type StateFact, type StateWrite } from "./hook-state.js";
 /**
@@ -367,6 +368,13 @@ export interface CompiledHookProgram {
             readonly command: string;
         }[];
     }[]>;
+    /**
+     * Non-fatal findings about the compiled hook — today, a role that FIRES on its
+     * event but cannot do what the role promises (a gate on `PostToolUse`, whose
+     * deny feeds the model rather than vetoing). Absent when there is nothing to
+     * say; a FATAL mismatch throws instead, so this never carries a dead hook.
+     */
+    readonly warnings?: readonly string[];
     /**
      * The rendered settings block to add to the harness's hooks config — JSON for
      * Claude Code (`.claude/settings.json`), TOML `[[hooks.<event>]]` for Codex
@@ -427,6 +435,36 @@ export declare function hookRouting(hook: AnyHook): {
     on: string;
     matcher?: string;
 };
+/**
+ * Is this ROLE legal on this EVENT? The check six measured fixtures showed
+ * nothing was making (2026-09-16): a prompt-gate on `PreToolUse` reads an absent
+ * prompt as `""` and allows everything; a stop-gate on `SessionStart` exits 2
+ * into an event that ignores it; a file-gate on `Stop` matches a tool on an
+ * event that carries none. All six compiled clean, `lint` and `audit` found
+ * zero, and `tsc` — which `vigiles compile` does not run — caught one.
+ *
+ * THREE VERDICTS, and the third is the point:
+ * - `dead` — the harness's own table says this cannot work. A compile error.
+ * - `degraded` — it fires, but not as the role promises. A WARNING, never an
+ *   error: the worked case is a gate on `PostToolUse`, whose exit 2 feeds the
+ *   model instead of vetoing, and that is a channel this very repo ships a hook
+ *   on. Failing it would be the cry-wolf `lint-rule-calibration` names.
+ * - `unknown` — the event is not in the capability table. SILENT. We record 9
+ *   of Claude Code's 31 events; rejecting an author for using one of the other
+ *   22 would be punishing them for our gap.
+ */
+export type RoleEventFit = {
+    readonly kind: "ok";
+} | {
+    readonly kind: "unknown";
+} | {
+    readonly kind: "dead";
+    readonly message: string;
+} | {
+    readonly kind: "degraded";
+    readonly message: string;
+};
+export declare function checkRoleEventFit(kind: DispatchKind, on: string, hasMatcher: boolean, table: EventCapabilityTable | undefined): RoleEventFit;
 /**
  * Compile a hook program from its source. Runs the capability check FIRST (an
  * out-of-API import does NOT compile), validates the event against the target