vigiles 29.1.0 → 30.0.0

package/dist/core/dialect.d.ts

@@ -18,14 +18,53 @@
  * vocabulary: the concrete dialects live in the adapters, only this interface
  * lives in the core. That is the format axis of the hexagonal boundary.
  */
-/**
- * Which SKILL.md frontmatter keys a harness understands — see
- * `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";
+/**
+ * Every SKILL.md frontmatter key the COMPILER knows how to render, in the order
+ * it renders them. A property of `renderSkillFrontmatter`, not of any harness:
+ * a dialect's {@link HarnessDialect.skillFrontmatterKeys} is a subset of this,
+ * and a key outside it can be declared but will never be emitted.
+ *
+ * 🔴 THIS REPLACES A TYPE ALIAS THAT SPELLED A HARNESS. It used to be
+ * `type SkillFrontmatterProfile = "claude-code" | "minimal"`, and it was the
+ * root of five of the eleven per-site lint disables on this branch: `compile.ts`
+ * defaulted to it, branched on it and defaulted it again, and
+ * `lethal-trifecta.ts` compared against it. Each of those is now a set
+ * membership test over key names, which are facts about a FILE FORMAT and carry
+ * no harness in them.
+ */
+export declare const RENDERABLE_SKILL_FRONTMATTER_KEYS: readonly ["name", "description", "disable-model-invocation", "context", "argument-hint", "allowed-tools", "disallowed-tools"];
+/**
+ * The instruction filenames vigiles recognizes when NO dialect is injected, in
+ * precedence order — `[0]` is what a spec compiles into when it names no target.
+ *
+ * 🔴 IT IS THE CORE'S OWN DEFAULT, AND DERIVING IT FROM THE REGISTRY IS NOT
+ * ALLOWED HERE — worth saying, because that is the obvious fix and it is the
+ * wrong one. `src/core/CLAUDE.md` states the invariant ("the core must not
+ * import an adapter, `core ⊄ adapter`") and the registry IS the adapters.
+ * Measured on a probe that added `import { ADAPTERS } from
+ * "../adapter-registry.js"` to `validate.ts`: the module graph of
+ * `dist/core/validate.js` went from 108 to 136 modules and pulled BOTH
+ * `adapters/claude-code/adapter.js` and `adapters/codex/adapter.js` into the
+ * domain's own graph.
+ *
+ * ⚠️ AND THE LINT DOES NOT STOP IT — same probe: `npx eslint
+ * src/core/validate.ts` reported 0 errors, because `boundaries/dependencies`
+ * treats `src/adapter-registry.ts` as the unclassified composition root and
+ * judges DIRECT edges only. That silence is an artifact of where the rule
+ * looks, not permission. So the agreement between this list and the registry is
+ * held by a TEST that lives outside the core (`adapter-contract.test.ts`),
+ * where importing the registry is legal — a ratchet instead of an inversion.
+ *
+ * ONE PLACE, because it was two: `validate.ts` held `["CLAUDE.md", "AGENTS.md"]`
+ * and `compile.ts` held `DEFAULT_TARGET = "CLAUDE.md"`, which is this list's
+ * head under another name — {@link HarnessDialect.instructionTargets} already
+ * contracts that `[0]` is the default target, so the second was the first,
+ * restated.
+ */
+export declare const DEFAULT_INSTRUCTION_TARGETS: readonly string[];
 export interface HarnessDialect {
     /** Stable identifier, e.g. "claude-code". */
     readonly name: string;
@@ -83,14 +122,17 @@ export interface HarnessDialect {
     /** The env token expanded to the plugin root in hook commands. */
     readonly pluginRootToken: string;
     /**
-     * Which SKILL.md frontmatter keys this harness understands — the profile the
-     * compiler renders under:
-     * - `"claude-code"` — the full Claude Code set (name, description, plus the
-     *   CC-only keys: disable-model-invocation, argument-hint, …).
-     * - `"minimal"` — name + description ONLY (the cross-tool SKILL.md shape Codex
-     *   and OpenCode read; CC-only keys are omitted because they'd be inert noise).
+     * The SKILL.md frontmatter keys this harness READS. The compiler emits a key
+     * iff it is listed here, so a harness that reads only the cross-tool shape
+     * declares `["name", "description"]` and the CC-only keys are omitted from its
+     * output rather than written as inert noise.
+     *
+     * Conformance requires `name` and `description` (a SKILL.md without them has
+     * no identity) and refuses a key outside
+     * {@link RENDERABLE_SKILL_FRONTMATTER_KEYS} — a key the compiler cannot render
+     * is a declaration nothing acts on.
      */
-    readonly skillFrontmatter: SkillFrontmatterProfile;
+    readonly skillFrontmatterKeys: readonly string[];
     /**
      * Tools that PRODUCE side effects (write, exec, network, spawn) — the
      * complement of read-only within `builtinAgentTools`. The basis for

package/dist/core/dialect.js

@@ -1,3 +1,59 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INSTRUCTION_TARGETS = exports.RENDERABLE_SKILL_FRONTMATTER_KEYS = void 0;
+/**
+ * Every SKILL.md frontmatter key the COMPILER knows how to render, in the order
+ * it renders them. A property of `renderSkillFrontmatter`, not of any harness:
+ * a dialect's {@link HarnessDialect.skillFrontmatterKeys} is a subset of this,
+ * and a key outside it can be declared but will never be emitted.
+ *
+ * 🔴 THIS REPLACES A TYPE ALIAS THAT SPELLED A HARNESS. It used to be
+ * `type SkillFrontmatterProfile = "claude-code" | "minimal"`, and it was the
+ * root of five of the eleven per-site lint disables on this branch: `compile.ts`
+ * defaulted to it, branched on it and defaulted it again, and
+ * `lethal-trifecta.ts` compared against it. Each of those is now a set
+ * membership test over key names, which are facts about a FILE FORMAT and carry
+ * no harness in them.
+ */
+exports.RENDERABLE_SKILL_FRONTMATTER_KEYS = [
+    "name",
+    "description",
+    "disable-model-invocation",
+    "context",
+    "argument-hint",
+    "allowed-tools",
+    "disallowed-tools",
+];
+/**
+ * The instruction filenames vigiles recognizes when NO dialect is injected, in
+ * precedence order — `[0]` is what a spec compiles into when it names no target.
+ *
+ * 🔴 IT IS THE CORE'S OWN DEFAULT, AND DERIVING IT FROM THE REGISTRY IS NOT
+ * ALLOWED HERE — worth saying, because that is the obvious fix and it is the
+ * wrong one. `src/core/CLAUDE.md` states the invariant ("the core must not
+ * import an adapter, `core ⊄ adapter`") and the registry IS the adapters.
+ * Measured on a probe that added `import { ADAPTERS } from
+ * "../adapter-registry.js"` to `validate.ts`: the module graph of
+ * `dist/core/validate.js` went from 108 to 136 modules and pulled BOTH
+ * `adapters/claude-code/adapter.js` and `adapters/codex/adapter.js` into the
+ * domain's own graph.
+ *
+ * ⚠️ AND THE LINT DOES NOT STOP IT — same probe: `npx eslint
+ * src/core/validate.ts` reported 0 errors, because `boundaries/dependencies`
+ * treats `src/adapter-registry.ts` as the unclassified composition root and
+ * judges DIRECT edges only. That silence is an artifact of where the rule
+ * looks, not permission. So the agreement between this list and the registry is
+ * held by a TEST that lives outside the core (`adapter-contract.test.ts`),
+ * where importing the registry is legal — a ratchet instead of an inversion.
+ *
+ * ONE PLACE, because it was two: `validate.ts` held `["CLAUDE.md", "AGENTS.md"]`
+ * and `compile.ts` held `DEFAULT_TARGET = "CLAUDE.md"`, which is this list's
+ * head under another name — {@link HarnessDialect.instructionTargets} already
+ * contracts that `[0]` is the default target, so the second was the first,
+ * restated.
+ */
+exports.DEFAULT_INSTRUCTION_TARGETS = [
+    "CLAUDE.md",
+    "AGENTS.md",
+];
 //# sourceMappingURL=dialect.js.map

package/dist/core/eval-driver.d.ts

@@ -0,0 +1,194 @@
+/**
+ * The EXECUTING tiers' shared shapes — the eval-tier transport (`EvalDriver`
+ * and the runner/parser types it is built from) and the unified run record
+ * (`Trace`) both tiers produce.
+ *
+ * WHY THEY LIVE IN CORE, exactly as `harness-driver.ts` says of the mock tier's
+ * trace shapes: a core PORT has to be able to reference them, and the core may
+ * not import `src/eval.ts` or `src/harness-test.ts` (those are composition-root
+ * runners that wire the Claude Code defaults, and `boundaries/dependencies`
+ * classifies everything they reach). `HarnessLiveDriver` (`./live-driver.js`)
+ * is the port that needed them; before it existed the types could sit beside
+ * their runners, and nothing forced the split.
+ *
+ * NOTHING MOVED BUT THE TYPES. `claudeEvalDriver`, `spawnAgent`,
+ * `parseClaudeRun`, `parseToolCalls`, `parseHooks` and `parseSubagents` stay in
+ * their runners — they are the wired Claude Code DEFAULT, and wiring the default
+ * is a composition root's job (`eval.ts:2336-2348` argues this at length). Both
+ * runners re-export these names, so every existing import keeps resolving.
+ */
+import type { ToolCall, HookFire, ModelRequest } from "./harness-driver.js";
+/** Per-run resource use, parsed from the terminal `result` event (0 when absent). */
+export interface EvalUsage {
+    /** `total_cost_usd` reported by the harness binary. */
+    readonly costUsd: number;
+    /** Wall-clock `duration_ms` of the run. */
+    readonly durationMs: number;
+    /** Fresh (uncached) input tokens, billed at full input price. */
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** Tokens written to the prompt cache this run (~1.25× input price). */
+    readonly cacheCreationTokens: number;
+    /** Tokens served from the prompt cache this run (~0.1× input price). */
+    readonly cacheReadTokens: number;
+}
+/** A sub-agent (`Task`) run as a nested trace: its name + the tools it used. */
+export interface SubagentTrace {
+    /** The `subagent_type` from the `Task` tool input. */
+    readonly name: string;
+    /** The tools the subagent invoked (events tagged with the Task's id). */
+    readonly toolCalls: readonly ToolCall[];
+    /**
+     * The subagent's RETURNED text — the dispatch tool_result the orchestrator
+     * receives back. This is where a `result()` contract's `vigiles:ok`/`vigiles:err`
+     * block lands, so `subagent(name, [output(/vigiles:ok/)])` can assert the typed
+     * outcome. "" if not captured.
+     */
+    readonly output: string;
+}
+/**
+ * The observable record of ONE run — the unified shape produced by BOTH testing
+ * tiers: `runHarnessTest`'s result and `runEval`'s `measure` ctx (`eval.ts`)
+ * both satisfy it. That's what lets the bare predicates in `harness-assert.ts`
+ * (`usedTool` / `skillResolved` / `toolCount` / `toolUsedWith` / `hookFired` /
+ * `outputContains`) run over either, with the testing helpers asserting and eval
+ * measuring over the same vocabulary.
+ */
+export interface Trace {
+    /**
+     * The tools the agent invoked, each paired with its result — parsed from the
+     * transcript. Empty unless the run captured the stream (`transcript: true` on
+     * the harness tier; always on the eval tier). Lets a test assert on the
+     * agent's *actions* (skills, MCP tools, subagents) instead of grepping stdout.
+     */
+    readonly toolCalls: readonly ToolCall[];
+    /**
+     * The hooks that fired during the run, each with its decision — parsed from
+     * the CLI's `hook_response` stream events. Same capture requirement as
+     * `toolCalls` (empty without the stream). Lets a test assert hook firing
+     * honestly instead of via a marker file.
+     */
+    readonly hooks: readonly HookFire[];
+    /** The agent's final answer text (the terminal `result` event), or "". */
+    readonly output: string;
+    /**
+     * The requests the model received, captured by the scripted mock — each with
+     * its `system` prompt and `messages`, flattened to text. Lets a test assert
+     * what actually reached the model (a SessionStart hook's injected context, a
+     * slash command's expansion), not just that a hook fired. **Harness tier
+     * only**: the mock sees the requests, so this is populated by `runHarnessTest`
+     * (with or without `transcript`); the eval tier drives the real API, so its
+     * `modelRequests` is always empty.
+     */
+    readonly modelRequests: readonly ModelRequest[];
+    /** Number of model turns. */
+    readonly turns: number;
+    /**
+     * Sub-agent (`Task`) runs as nested traces, keyed by `subagent_type`. A
+     * subagent runs its own session; CC tags its events with `parent_tool_use_id`
+     * (= the `Task` tool call) so its tool calls are recovered into a sub-trace
+     * here, lettng a test assert what the subagent DID (not just that `Task` fired).
+     * Empty unless the stream was captured / the harness emits subagent events.
+     */
+    readonly subagents?: readonly SubagentTrace[];
+    /** Final contents of a file under the working dir, or null if absent. */
+    file(path: string): string | null;
+}
+/** The raw output of one trial: the agent's exit code + captured streams. */
+export interface RunOut {
+    code: number;
+    stdout: string;
+    /** Captured stderr, when the runner provides it (used for rate-limit detection). */
+    stderr?: string;
+}
+/** The per-trial arguments handed to an {@link AgentRunner}. */
+export interface AgentRunArgs {
+    readonly task: string;
+    readonly cwd: string;
+    readonly model: string;
+    /**
+     * Reasoning-budget level for the run (`claude --effort`). Part of the
+     * MEASUREMENT, not a run knob: it changes the model's output distribution, not
+     * the sample size — so it lives on the spec next to `model` (never an env),
+     * and it is hashed into both the cache key and the eval lock. Deliberately
+     * `string | number` rather than a literal union: the binary accepts an alias
+     * map, is case-insensitive, and takes an integer budget, and its own valid set
+     * MOVED between builds (2.1.42 had no `xhigh`, 2.1.257 does) — a hard-coded
+     * union would reject a valid level after any upstream addition. A wrong value
+     * is caught at RUNTIME instead, by `effortRejection`, which is what the
+     * binary actually tells us. Omit for the harness default.
+     */
+    readonly effort?: string | number;
+    readonly tools: readonly string[];
+    readonly hasSettings: boolean;
+    readonly pluginDir: string | undefined;
+    readonly timeoutMs: number;
+    /** Extra env layered over `process.env` for this run (e.g. `VIGILES_INTERCEPT_TOOLS`). */
+    readonly env?: Record<string, string>;
+    /**
+     * When true, `env` is the COMPLETE spawn environment (an ephemeral run env from
+     * `ephemeralRunEnv`) — the runner does NOT prepend `process.env`, so the
+     * real `$HOME` / secrets are scrubbed. Default false: `env` is an overlay over
+     * `process.env` (the byte-identical-to-today path). Set only by `ephemeralEnv`.
+     */
+    readonly replaceEnv?: boolean;
+}
+/**
+ * Runs one trial and returns its raw output. The default (`spawnAgent`)
+ * drives the real `claude` CLI; `runEvalWith` takes one explicitly, so the eval
+ * orchestration is testable without a model (pass a fake returning canned
+ * stream-json) and a custom runtime can be plugged in.
+ */
+export type AgentRunner = (args: AgentRunArgs) => Promise<RunOut>;
+/**
+ * The harness-specific half of a run trace: how a real model's raw stdout maps
+ * to the common fields. Claude Code's `parseClaudeRun` reads its stream-json; a
+ * second harness (Codex) supplies its own parser of `codex exec --json` JSONL, so
+ * the eval tier (`measureTriggerRate`/`runEval`) isn't bound to Claude's format.
+ * The non-harness fields (cwd/exitCode/stdout/file/sh) stay in `makeContext`.
+ */
+export interface ParsedModelRun {
+    readonly turns: number;
+    readonly output: string;
+    readonly toolCalls: ToolCall[];
+    readonly hooks: HookFire[];
+    readonly subagents: SubagentTrace[];
+    readonly usage: EvalUsage;
+}
+export type ModelOutputParser = (out: RunOut) => ParsedModelRun;
+/**
+ * An eval-tier transport: how to RUN a real harness turn and PARSE its output.
+ * The default is Claude Code (`claudeEvalDriver`); a second harness supplies its
+ * own (e.g. `codexEvalDriver` from `vigiles/codex`) and passes it as
+ * `measureTriggerRate(spec, { evalDriver })` — the eval-tier analog of
+ * `runHarnessTest`'s `{ adapter }`. `runError` lets the loop drop an
+ * errored/rate-limited turn instead of scoring it as a miss.
+ */
+export interface EvalDriver {
+    readonly runner: AgentRunner;
+    readonly parse: ModelOutputParser;
+    readonly runError?: (out: RunOut) => string | null;
+    /**
+     * The harness this driver runs (e.g. the adapter's `name`). Folded into a
+     * trigger-rate eval's LOCK hash so a report recorded on one harness is marked
+     * STALE if the eval is later switched to another (a different harness can fire a
+     * skill differently). Optional for back-compat — absent defaults to the
+     * default harness, so an existing single-harness lock is unaffected.
+     */
+    readonly harness?: string;
+    /**
+     * When set, this driver's trigger-rate number is EXPERIMENTAL and not
+     * validated — the string is the human caveat explaining why (e.g. Codex has no
+     * skill-selection event, so firing is inferred from a SKILL.md read, which can
+     * be wrong in both directions). Absent = supported/trustworthy (the default).
+     * `measureTriggerRate` copies it onto the report and warns; the formatter
+     * prints it. Precision-first: never let a possibly-wrong number read as a
+     * measurement.
+     *
+     * The same fact as `HarnessLiveDriver.firing` (`./live-driver.js`), which is
+     * the typed form the measurement tiers branch on; `adapter-contract.test.ts`
+     * asserts the two agree on every adapter.
+     */
+    readonly experimental?: string;
+}
+//# sourceMappingURL=eval-driver.d.ts.map

package/dist/core/eval-driver.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=eval-driver.js.map

package/dist/core/frontmatter-read.d.ts

@@ -6,6 +6,16 @@ export interface FrontmatterRead {
     /** True when a leading `---` block EXISTS but is NOT valid YAML. */
     readonly malformed: boolean;
 }
+/**
+ * The markdown BODY — everything after the leading frontmatter block, or the
+ * whole text when there is none.
+ *
+ * Lives here, beside {@link readFrontmatter}, because `BLOCK_RE` above is the
+ * ONE statement of where frontmatter ends; a caller slicing the body for itself
+ * would be a second one, free to disagree (and the header records what the
+ * first one already has to know about BOMs and legacy stamp comments).
+ */
+export declare function frontmatterBody(markdown: string): string;
 /** Extract + parse the leading frontmatter block, never throwing. */
 export declare function readFrontmatter(markdown: string): FrontmatterRead;
 /**

package/dist/core/frontmatter-read.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.frontmatterBody = frontmatterBody;
 exports.readFrontmatter = readFrontmatter;
 exports.frontmatterScalar = frontmatterScalar;
 exports.frontmatterList = frontmatterList;
@@ -20,7 +21,20 @@ exports.frontmatterList = frontmatterList;
  * the regex parse in agent-runtime.ts); `core/frontmatter.ts` is a DIFFERENT
  * concern (the Level-1 `vigiles:` rule block) and is untouched.
  */
-const js_yaml_1 = require("js-yaml");
+/**
+ * 🔴 `js-yaml` IS REQUIRED LAZILY, AND THAT IS A MEASUREMENT, NOT A STYLE. The
+ * same wrapper is in `core/settings-codec.ts` and `core/markdown.ts` with the
+ * reason recorded: a top-level import puts the parser into the module graph of
+ * every HOOK DECISION, because the hook runtime reaches the adapter registry
+ * and from there a layout. This module became reachable that way on 2026-09-21
+ * through `PluginLayout.instructionChain` (a rule's `paths:` frontmatter is
+ * what decides whether it loads at launch) — measured by
+ * `src/hook-runtime-graph.test.ts`: 37 modules became 71 with an eager import.
+ * `tsc` lowers this to CommonJS, so the `require` does not run until a
+ * frontmatter block is actually parsed, and {@link frontmatterBody}, which needs
+ * no YAML at all, never triggers it.
+ */
+const yaml = () => require("js-yaml");
 // Frontmatter is the very first thing in the file. Anchoring at the start — not
 // `(?:^|\n)` — means a `---` horizontal rule in the BODY is never mistaken for
 // frontmatter (which matters for the malformed-YAML verdict). A leading BOM is
@@ -33,6 +47,19 @@ const js_yaml_1 = require("js-yaml");
 const BLOCK_RE = /^\uFEFF?(?:<!--[\s\S]*?-->\s*)?---\r?\n([\s\S]*?)\r?\n---/;
 /** A YAML block-scalar indicator: `>`/`|` with optional chomp (`+`/`-`) + indent digit. */
 const BLOCK_SCALAR_RE = /^[|>][+-]?\d*$/;
+/**
+ * The markdown BODY — everything after the leading frontmatter block, or the
+ * whole text when there is none.
+ *
+ * Lives here, beside {@link readFrontmatter}, because `BLOCK_RE` above is the
+ * ONE statement of where frontmatter ends; a caller slicing the body for itself
+ * would be a second one, free to disagree (and the header records what the
+ * first one already has to know about BOMs and legacy stamp comments).
+ */
+function frontmatterBody(markdown) {
+    const m = BLOCK_RE.exec(markdown);
+    return m === null ? markdown : markdown.slice(m[0].length);
+}
 /** Extract + parse the leading frontmatter block, never throwing. */
 function readFrontmatter(markdown) {
     const m = BLOCK_RE.exec(markdown);
@@ -40,7 +67,7 @@ function readFrontmatter(markdown) {
         return { data: null, block: null, malformed: false };
     const block = m[1];
     try {
-        const parsed = (0, js_yaml_1.load)(block);
+        const parsed = yaml().load(block);
         if (parsed !== null &&
             typeof parsed === "object" &&
             !Array.isArray(parsed)) {
@@ -55,7 +82,7 @@ function readFrontmatter(markdown) {
         return { data: null, block, malformed: false };
     }
     catch (e) {
-        if (e instanceof js_yaml_1.YAMLException)
+        if (e instanceof yaml().YAMLException)
             return { data: null, block, malformed: true };
         throw e;
     }

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

@@ -35,8 +35,25 @@
  */
 import { type BashEffect } from "./bash-effects.js";
 import { type SHA256Hash } from "./hash.js";
+/**
+ * `@iarna/toml` is required LAZILY, at the one call site that serializes a Codex
+ * TOML settings block — never at module load. MEASURED 2026-09-08 (Node 22.22.2,
+ * `tools/measure-hook-startup.mjs`): the top-level import cost 56 ms of a
+ * ~170 ms `require("dist/core/hook-program.js")`, and this module is on the hot
+ * path of `vigiles hook-runtime run-program`, which runs on EVERY matching tool
+ * call. A hook DECIDES; it never serializes a settings block, so it paid 56 ms
+ * per tool call for a compile-time dependency.
+ *
+ * 🔴 THE LAZY REQUIRE MOVED, IT DID NOT GO AWAY. Serializing a settings block
+ * is now `SettingsCodec.render`, and `core/settings-codec.ts` keeps exactly
+ * this wrapper for exactly this reason — a codec is reached from strictly MORE
+ * places than this module was, so a top-level import there would have widened
+ * the regression rather than repeated it. `src/hook-runtime-graph.test.ts`
+ * still fails if `@iarna/toml` reappears in a decision's module graph.
+ */
 import type { HarnessDialect } from "./dialect.js";
 import type { HookProtocol } from "./hook-protocol.js";
+import { type SettingsCodec } from "./settings-codec.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";
@@ -397,8 +414,16 @@ export interface CompileHookOptions {
     readonly dialect?: HarnessDialect;
     /** Matcher style (exact vs anchored regex). Defaults to Claude Code's `"exact"`. */
     readonly hookProtocol?: HookProtocol;
-    /** Settings encoding — `"json"` (Claude Code) or `"toml"` (Codex). From `PluginLayout.settingsFormat`. */
-    readonly settingsFormat?: "json" | "toml";
+    /**
+     * Settings ENCODING, from `PluginLayout.settings`. Absent ⇒ JSON, the
+     * backwards-compatible default for a caller that injects no layout.
+     *
+     * It used to be `settingsFormat?: "json" | "toml"` and `renderSettingsBlock`
+     * branched on it for BOTH the encoding and the entry shape. The shape comes
+     * from `hookProtocol.registration` now, so the two can no longer be chosen
+     * independently of each other by accident.
+     */
+    readonly settings?: SettingsCodec;
     /** Names of registered providers (`.vigiles/providers/`) a `provider()` ref may resolve to. */
     readonly registeredProviders?: readonly string[];
 }

package/dist/core/hook-program.js

@@ -78,18 +78,7 @@ exports.isLoadPathRepairEvent = isLoadPathRepairEvent;
  */
 const bash_effects_js_1 = require("./bash-effects.js");
 const hash_js_1 = require("./hash.js");
-/**
- * `@iarna/toml` is required LAZILY, at the one call site that serializes a Codex
- * TOML settings block — never at module load. MEASURED 2026-09-08 (Node 22.22.2,
- * `tools/measure-hook-startup.mjs`): the top-level import cost 56 ms of a
- * ~170 ms `require("dist/core/hook-program.js")`, and this module is on the hot
- * path of `vigiles hook-runtime run-program`, which runs on EVERY matching tool
- * call. A hook DECIDES; it never serializes a settings block, so it paid 56 ms
- * per tool call for a compile-time dependency. Keep it a call-site require —
- * hoisting it back to the top is the regression, and `src/hook-runtime-graph.test.ts`
- * fails if `@iarna/toml` reappears in a decision's module graph.
- */
-const stringifyToml = (value) => require("@iarna/toml").stringify(value);
+const settings_codec_js_1 = require("./settings-codec.js");
 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");
@@ -750,17 +739,33 @@ function styleMatcher(matcher, protocol) {
  * Claude Code (the nested `{event:[{matcher,hooks:[{type,command}]}]}` shape);
  * TOML `[[hooks.<event>]]` with a flat `command` for Codex.
  */
-function renderSettingsBlock(on, matcher, gateCommand, format) {
-    if (format === "toml") {
-        const entry = matcher === undefined
-            ? { command: gateCommand }
-            : { matcher, command: gateCommand };
-        return stringifyToml({ hooks: { [on]: [entry] } }).trim();
-    }
-    const entry = matcher === undefined
-        ? { hooks: [{ type: "command", command: gateCommand }] }
-        : { matcher, hooks: [{ type: "command", command: gateCommand }] };
-    return JSON.stringify({ hooks: { [on]: [entry] } }, null, 2);
+/**
+ * The settings block a user pastes: the harness's entry SHAPE
+ * (`hookProtocol.registration`) rendered in the harness's ENCODING
+ * (`settings.render`).
+ *
+ * 🔴 IT USED TO BUILD BOTH FROM ONE `"json" | "toml"` ARGUMENT — the TOML
+ * branch also hard-coded Codex's flat entry and the JSON branch Claude Code's
+ * nested one, so "TOML" silently meant "flat" and "JSON" meant "nested". Two
+ * facts on one switch: a JSON harness with flat entries, or a TOML one with
+ * nested entries, was unrepresentable, and the day one appeared the branch
+ * would have quietly produced the other harness's shape.
+ */
+function renderSettingsBlock(on, matcher, gateCommand, protocol, settings) {
+    const block = protocol
+        ? protocol.registration(on, matcher, gateCommand)
+        : {
+            hooks: {
+                [on]: [
+                    matcher === undefined
+                        ? { hooks: [{ type: "command", command: gateCommand }] }
+                        : { matcher, hooks: [{ type: "command", command: gateCommand }] },
+                ],
+            },
+        };
+    return (settings ?? settings_codec_js_1.jsonSettingsCodec)
+        .render(block)
+        .trimEnd();
 }
 /** What payload a dispatch kind must be handed to be able to decide at all. */
 function requiredPayload(kind) {
@@ -947,7 +952,7 @@ function compileHookProgram(source, hook, opts = {}) {
         };
     return {
         hooks: { [on]: [entry] },
-        settingsBlock: renderSettingsBlock(on, matcher, gateCommand, opts.settingsFormat ?? "json"),
+        settingsBlock: renderSettingsBlock(on, matcher, gateCommand, opts.hookProtocol, opts.settings),
         stamp: stampHook(source),
         ...(fitWarnings.length > 0 ? { warnings: fitWarnings } : {}),
     };

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

@@ -32,6 +32,60 @@ export interface HookProtocol {
      * Used by `compileHookProgram` when rendering the settings block.
      */
     readonly matcherStyle?: "exact" | "regex";
+    /**
+     * The config fragment that registers ONE command on ONE event, in this
+     * harness's native settings SHAPE. Claude Code nests
+     * `{matcher, hooks: [{type: "command", command}]}`; Codex is flat
+     * `{matcher, command}`.
+     *
+     * 🔴 THE SHAPE HALF OF WHAT `settingsFormat` WAS STANDING IN FOR, and it does
+     * not belong with the encoding. `PluginLayout.settingsFormat` was a
+     * `"json" | "toml"` enum that three call sites read as "which entry shape",
+     * which is neither what its name says nor what its values mean — a TOML
+     * harness with CC-shaped entries, or a JSON harness with flat ones, were both
+     * expressible and both would have been read wrong. A constructor cannot be
+     * wrong about its own shape.
+     *
+     * Reading already tolerates both shapes (`core/hook-normalize.ts`); this
+     * makes WRITING symmetric.
+     */
+    registration(on: string, matcher: string | undefined, command: string): {
+        readonly hooks: Readonly<Record<string, readonly unknown[]>>;
+    };
+    /**
+     * Merge a compiled hook's registrations into an already-parsed settings
+     * object, idempotently: entries this hook file manages are REPLACED, every
+     * other command — including the user's own hand-written hooks sharing a
+     * matcher block — is preserved.
+     *
+     * 🔴 `compiled` IS THE COMPILER'S CANONICAL BLOCK, NOT `registration`'s
+     * OUTPUT, and the asymmetry is load-bearing enough to state rather than
+     * leave to be discovered. `compileHookProgram` always produces the nested
+     * `{matcher?, hooks:[{type, command}]}` form (`CompiledHooks` —
+     * "the CC-shaped structured block a compiled hook program carries"), and each
+     * implementation converts to its own shape on the way in; Codex's flattens
+     * with `toTomlEntries`. `registration` goes the other way: it produces the
+     * NATIVE shape, for the settings block a human pastes. Feeding this method a
+     * `registration` result is a type-level no-op and a run-time TypeError on
+     * the flat side — found by the property test below, which asserted it.
+     *
+     * `managedBy` is the canonical hook-source reference whose commands this
+     * merge owns; a compiled block whose commands do not mention it is APPENDED,
+     * not replaced, which is what keeps a user's own hooks intact.
+     *
+     * On `HookProtocol` because it is the same SHAPE question `registration`
+     * answers, from the other direction: the CC shape nests several commands
+     * under one matcher (so the granularity has to be the command), the Codex
+     * shape carries one command per entry (so entry- and command-granularity
+     * coincide). Typed structurally here, because the concrete entry types are
+     * the application layer's.
+     *
+     * ⚠️ There is no `registrations(config)` INVERSE yet — reading a third shape
+     * would need one, and that is deferred until a third shape exists. What
+     * exists now is: write one (`registration`), and merge into a parsed object
+     * (this).
+     */
+    mergeRegistrations(existing: Record<string, unknown>, compiled: Readonly<Record<string, readonly unknown[]>>, managedBy: string): Record<string, unknown>;
     /**
      * The events whose hook can inject **developer context** into the agent by
      * printing `{ hookSpecificOutput: { hookEventName, additionalContext } }` on

package/dist/core/install-reader.d.ts

@@ -0,0 +1,18 @@
+import type { HarnessAdapter, InstallReader } from "./adapter.js";
+/**
+ * Is `vigiles` a declared dependency of this `package.json` text? Pure. Any of
+ * the four dependency fields counts — the question is "did this repo take
+ * vigiles on", not how. The vigiles repo itself is not a consumer: it IS the
+ * package, so it answers false.
+ */
+export declare function declaresVigilesDependency(pkgJson: string): boolean;
+/**
+ * Build the reader for one adapter over one repo root.
+ *
+ * `home` is injectable so the machine read is testable without a real `$HOME`;
+ * it defaults to the user's own. Everything it feeds is advisory-only.
+ */
+export declare function buildInstallReader(adapter: HarnessAdapter, root: string, opts?: {
+    readonly home?: string;
+}): InstallReader;
+//# sourceMappingURL=install-reader.d.ts.map