vigiles 27.1.7 → 27.2.0

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

package/dist/core/hook-program.js

@@ -15,6 +15,7 @@ exports.dispatchKind = dispatchKind;
 exports.hookMode = hookMode;
 exports.hookNeeds = hookNeeds;
 exports.hookRouting = hookRouting;
+exports.checkRoleEventFit = checkRoleEventFit;
 exports.compileHookProgram = compileHookProgram;
 exports.stampHook = stampHook;
 exports.verifyHookStamp = verifyHookStamp;
@@ -88,6 +89,7 @@ const hash_js_1 = require("./hash.js");
  * fails if `@iarna/toml` reappears in a decision's module graph.
  */
 const stringifyToml = (value) => require("@iarna/toml").stringify(value);
+const event_capability_js_1 = require("./event-capability.js");
 const hook_events_js_1 = require("./hook-events.js");
 const tool_contract_js_1 = require("./tool-contract.js");
 const merge_conflict_js_1 = require("./merge-conflict.js");
@@ -743,6 +745,79 @@ function renderSettingsBlock(on, matcher, gateCommand, format) {
         : { matcher, hooks: [{ type: "command", command: gateCommand }] };
     return JSON.stringify({ hooks: { [on]: [entry] } }, null, 2);
 }
+/** What payload a dispatch kind must be handed to be able to decide at all. */
+function requiredPayload(kind) {
+    switch (kind) {
+        case "bash-gate":
+        case "file-gate":
+            return "tool";
+        case "prompt-gate":
+            return "prompt";
+        case "stop-gate":
+            return "stop";
+        // An inject or a react reads whatever the event carries; neither claims a
+        // field that might be absent, so neither constrains the payload.
+        case "inject":
+        case "react":
+            return undefined;
+    }
+}
+/** Whether this dispatch kind's whole purpose is a block decision. */
+function isGate(kind) {
+    return (kind === "bash-gate" ||
+        kind === "file-gate" ||
+        kind === "prompt-gate" ||
+        kind === "stop-gate");
+}
+function checkRoleEventFit(kind, on, hasMatcher, table) {
+    const verdict = (0, event_capability_js_1.capabilityOf)(table, on);
+    if (verdict.kind === "unknown")
+        return { kind: "unknown" };
+    const cap = verdict.capability;
+    const needs = requiredPayload(kind);
+    if (needs !== undefined && cap.carries !== needs) {
+        return {
+            kind: "dead",
+            message: `a ${kind} on \`${on}\` can never decide: the role reads the event's ` +
+                `${needs}, and ${on} carries ${cap.carries === "none" ? "nothing" : cap.carries}. ` +
+                `The field it reads is absent, so the hook runs and waves everything through.`,
+        };
+    }
+    if (hasMatcher && !cap.matcher) {
+        return {
+            kind: "dead",
+            message: `a tool matcher is meaningless on \`${on}\` — it carries ` +
+                `${cap.carries === "none" ? "nothing" : cap.carries}, not a tool, so the ` +
+                `matcher can match nothing and the hook never fires.`,
+        };
+    }
+    if (isGate(kind) && !cap.honours.includes("veto")) {
+        // The degraded case: it still reaches the model, it just does not block.
+        if (cap.honours.includes("feedback")) {
+            return {
+                kind: "degraded",
+                message: `\`${on}\` does not honour a veto — a deny there reaches the model as ` +
+                    `FEEDBACK after the action already happened. Fine as a nudge, but this ` +
+                    `is a ${kind}, so it stops nothing. Use a react, or gate on an event ` +
+                    `that vetoes.`,
+            };
+        }
+        return {
+            kind: "dead",
+            message: `a ${kind} on \`${on}\` blocks nothing: the event honours ` +
+                `${cap.honours.length === 0 ? "no channel at all" : cap.honours.join(", ")}, ` +
+                `so a deny is discarded silently — no veto, and no feedback to the model.`,
+        };
+    }
+    if (kind === "inject" && !cap.honours.includes("inject")) {
+        return {
+            kind: "dead",
+            message: `an inject on \`${on}\` reaches nobody — the event does not honour ` +
+                `additionalContext, so the text goes to the debug log.`,
+        };
+    }
+    return { kind: "ok" };
+}
 /**
  * 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
@@ -761,6 +836,26 @@ function compileHookProgram(source, hook, opts = {}) {
     if (violations.length > 0) {
         throw new HookCompileError(`hook program uses capabilities outside \`${ALLOWED_IMPORT}\`: ${violations.join(", ")} — only the sanctioned API is allowed (capability = API surface).`);
     }
+    // A BARE gate is a Bash gate by construction — `hookRouting` emits the matcher
+    // `Bash` for it unconditionally, and `HookProgram` has no `match` field. So a
+    // `match` here is a field the author wrote and the compiler ignores, and the
+    // result is the WORST of the six measured fixtures (d): not a dead hook but a
+    // LIVE one guarding the wrong thing — `defineHook({match: tools("mcp__…")})`
+    // compiled to a matcher of `Bash`, asking on every shell command while the MCP
+    // call it was written for went straight through.
+    //
+    // `tsc` rejects the excess property, which is why this looked covered. It is
+    // not: a compiled hook is often `.mjs` (this repo's own two are), and
+    // `vigiles compile` does not run `tsc` at all — so for a JS author the type
+    // was never in the path. Same defect, different population; the rule the
+    // repo already states as prevent-at-stage-1 AND detect-at-stage-3.
+    if (!("role" in hook) && "match" in hook) {
+        throw new HookCompileError(`a bare hook gate is a BASH gate — it matches \`Bash\` by construction, so ` +
+            `the \`match\` you passed is ignored and the hook would guard shell ` +
+            `commands instead of what you named. For a file tool use ` +
+            `experimental_defineFileGate; for any other tool matcher use ` +
+            `experimental_defineReact, whose event carries the tool.`);
+    }
     const { on, matcher: rawMatcher } = hookRouting(hook);
     // A tool pattern that is not a valid regex cannot match under the semantics the
     // emitted matcher is read with, so it would compile to a hook that never fires.
@@ -804,6 +899,13 @@ function compileHookProgram(source, hook, opts = {}) {
             throw new HookCompileError(fatal[0].message);
         }
     }
+    // …and an event the harness DOES fire can still be one this role cannot work
+    // on. Checked against the dialect's capability table; silent where the table
+    // has no row, so our gaps never become the author's error.
+    const fit = checkRoleEventFit(dispatchKind(hook), on, rawMatcher !== undefined, opts.dialect?.eventCapabilities);
+    if (fit.kind === "dead")
+        throw new HookCompileError(fit.message);
+    const fitWarnings = fit.kind === "degraded" ? [fit.message] : [];
     // A `needs` entry that isn't a built-in provider never resolves — reject it
     // (the typo-won't-compile guarantee, for JS authors the type can't reach).
     const needs = hookNeeds(hook);
@@ -830,6 +932,7 @@ function compileHookProgram(source, hook, opts = {}) {
         hooks: { [on]: [entry] },
         settingsBlock: renderSettingsBlock(on, matcher, gateCommand, opts.settingsFormat ?? "json"),
         stamp: stampHook(source),
+        ...(fitWarnings.length > 0 ? { warnings: fitWarnings } : {}),
     };
 }
 /** Stamp a hook's source (the integrity.ts pattern, applied to a hook artifact). */

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

@@ -40,11 +40,27 @@ export interface HookProtocol {
      * **which events honor it** — and encoding it here is what makes "this harness
      * can deliver an inject hook" a TESTED contract instead of an assumption. Both
      * Claude Code and Codex support the main lifecycle events (SessionStart,
-     * UserPromptSubmit, PostToolUse); a few (Stop, SubagentStop, PreCompact) carry
-     * no context on either. An empty list means the harness cannot inject context
-     * from a hook at all. Verified for Codex against the official hooks docs
+     * UserPromptSubmit, PreToolUse, PostToolUse); beyond that they DIVERGE, which
+     * is why this is a port and not a core constant: Claude Code also honors
+     * `Stop` (measured 2026-09-15 on 2.1.273, headless), Codex instead honors
+     * `SubagentStart`. An empty list means the harness cannot inject context from
+     * a hook at all. Verified for Codex against the official hooks docs
      * (developers.openai.com/codex/hooks). The conformance kit asserts a
      * shell-hook harness declares a non-empty set.
+     *
+     * ⚠️ This comment previously asserted that "a few (Stop, SubagentStop,
+     * PreCompact) carry no context on EITHER" harness. For Claude Code's `Stop`
+     * that was wrong, and the cost was structural rather than cosmetic: an
+     * unmeasured claim in a doc-comment became the runtime's emit gate, so three
+     * react hooks were reported undeliverable-by-vocabulary when the harness
+     * would have delivered them. A per-harness fact belongs in the adapter WITH
+     * its measurement; the residue (`SubagentStop`, `PreCompact`) stays unclaimed
+     * here rather than re-asserted.   *
+     * @deprecated Superseded by `HarnessDialect.eventCapabilities`
+     * (`honours: "inject"`), which is asserted to reproduce this list exactly. It
+     * lives on the DIALECT rather than here because three sibling event facts
+     * already did, and because the browser-side engine is handed a dialect and
+     * never a protocol. Kept for third-party adapters; goes in the next major.
      */
     readonly injectableEvents: readonly string[];
     /**

package/dist/core/instruction-weight.d.ts

@@ -0,0 +1,86 @@
+/**
+ * How heavy are the instructions this harness loads WITHOUT BEING ASKED — and
+ * what does the harness do when that is too much.
+ *
+ * WHY THIS IS NOT "the size of CLAUDE.md". Measured 2026-09-16 in a consumer
+ * repo: a 4 101-line root instruction file was "cut" to 2 665 lines by moving
+ * 225 837 characters of it into a sibling directory, and the cost of a request
+ * did not move at all — because the harness loads that directory
+ * unconditionally too. Splitting a file that is loaded either way relocates
+ * bytes; it does not remove them. So the number that matters is the SUM over
+ * everything loaded without a decision, and a per-file check silently INVITES
+ * the evasion (it rewards the split that changes nothing).
+ *
+ * WHY THE UNIT IS PER-HARNESS AND NOT TOKENS. The harnesses measure different
+ * things and neither gates on tokens:
+ *
+ *   - Claude Code counts CHARACTERS and WARNS ("Large file will impact
+ *     performance"); the instructions still reach the model.
+ *   - Codex counts BYTES (`project_doc_max_bytes`, default 32 KiB) and
+ *     TRUNCATES — silently. Its own source says so: "Maximum number of bytes of
+ *     the documentation that will be embedded. Larger files are *silently
+ *     truncated*" (openai/codex#7138, CLOSED AS NOT PLANNED, so this is the
+ *     standing behaviour rather than a bug in flight).
+ *
+ * That asymmetry is the whole point of reporting `onExceed`: over budget on
+ * Claude Code costs money and attention, over budget on Codex means some of
+ * your rules DO NOT EXIST for the model and nothing tells you which. The same
+ * number carries a different severity per harness, so the harness must supply
+ * it — hence a port field, not a constant.
+ *
+ * NOT A GATE, AND THAT IS MEASURED. Both corpora this was built against sit at
+ * roughly four times the Claude Code threshold. A rule that fails every real
+ * repo on day one is switched off on day one (`lint-rule-calibration`: severity
+ * tracks confidence, and a check nobody leaves on catches nothing). So the
+ * first consumer is `audit`, as a REPORT. It earns a severity when a corpus
+ * exists that it would not immediately fail.
+ */
+/** What the harness counts, and what it does when the count is exceeded. */
+export interface InstructionBudget {
+    /** Claude Code counts characters; Codex counts bytes. Never tokens. */
+    readonly unit: "chars" | "bytes";
+    /** The harness's own threshold, in `unit`. */
+    readonly limit: number;
+    /**
+     * `warns` — the instructions still reach the model (Claude Code).
+     * `truncates` — everything past the limit DOES NOT EXIST for the model, with
+     * no signal in the session (Codex). The difference is losing money versus
+     * losing rules.
+     */
+    readonly onExceed: "warns" | "truncates";
+    /** The vendor artifact this was read from, version included. */
+    readonly capturedFrom: string;
+    /**
+     * Globs the harness loads WITHOUT the user asking — the set the SUM is taken
+     * over. A file reachable only by an explicit read does not belong here; that
+     * is exactly the distinction the relocation trick exploits.
+     */
+    readonly alwaysLoaded: readonly string[];
+}
+/** One file's contribution, so a report can say WHERE the weight is. */
+export interface WeighedFile {
+    readonly path: string;
+    readonly size: number;
+}
+export interface InstructionWeight {
+    readonly unit: "chars" | "bytes";
+    readonly limit: number;
+    readonly onExceed: "warns" | "truncates";
+    /** Heaviest first — a report's first line should name the biggest payer. */
+    readonly files: readonly WeighedFile[];
+    /** The number that matters: everything loaded without a decision. */
+    readonly total: number;
+    /** `null` when within budget; otherwise how far over, in `unit`. */
+    readonly overBy: number | null;
+}
+/** Size in the harness's own unit. Bytes and chars differ on any non-ASCII text. */
+export declare function sizeIn(text: string, unit: "chars" | "bytes"): number;
+/**
+ * Weigh every unconditionally-loaded file in a file map.
+ *
+ * Takes a MAP rather than a directory so the same function serves the CLI and
+ * the browser engine (the `scan-files.ts` split), and so a test states its
+ * input instead of building a tree.
+ */
+export declare function weighInstructions(files: Readonly<Record<string, string>>, budget: InstructionBudget): InstructionWeight;
+//# sourceMappingURL=instruction-weight.d.ts.map