vigiles 16.1.2 → 17.0.0

package/dist/adapters/claude-code/vocabulary.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeSubagentToolVocabulary = exports.claudeCodeHookEventVocabulary = exports.claudeCodeSideEffectingAgentTools = exports.claudeCodeConditionalAgentToolNames = exports.claudeCodeWithheldAgentTools = exports.claudeCodeAvailableAgentTools = exports.claudeCodeHookEventNames = void 0;
+/** The vendor artifact + version both catalogs below were captured from. */
+const CAPTURE = "code.claude.com/docs (claude-code 2.1.233, read 2026-08-17)";
+/**
+ * The Claude Code hook events — the 31 `###` subsections under `## Hook events`
+ * at https://code.claude.com/docs/en/hooks, in document order.
+ *
+ * `Setup` is the third. It is a real event with its own `Setup input` and
+ * `Setup decision control` subsections; the old catalog's absence of it is what
+ * produced the two-letter grade inversion this file exists to fix.
+ */
+exports.claudeCodeHookEventNames = [
+    "SessionStart",
+    "Setup",
+    "InstructionsLoaded",
+    "UserPromptSubmit",
+    "UserPromptExpansion",
+    "MessageDisplay",
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PostToolBatch",
+    "PermissionDenied",
+    "Notification",
+    "SubagentStart",
+    "SubagentStop",
+    "TaskCreated",
+    "TaskCompleted",
+    "Stop",
+    "StopFailure",
+    "TeammateIdle",
+    "ConfigChange",
+    "CwdChanged",
+    "DirectoryAdded",
+    "FileChanged",
+    "WorktreeCreate",
+    "WorktreeRemove",
+    "PreCompact",
+    "PostCompact",
+    "SessionEnd",
+    "Elicitation",
+    "ElicitationResult",
+];
+/**
+ * The 19 built-ins the vendor names as the set a BACKGROUND subagent keeps —
+ * the default case, and the only tool set vigiles can assume without reading
+ * conditions it cannot see.
+ */
+exports.claudeCodeAvailableAgentTools = [
+    "Read",
+    "Grep",
+    "Glob",
+    "Bash",
+    "PowerShell",
+    "Edit",
+    "Write",
+    "NotebookEdit",
+    "WebFetch",
+    "WebSearch",
+    "TodoWrite",
+    "Skill",
+    "ToolSearch",
+    "EnterWorktree",
+    "ExitWorktree",
+    "Monitor",
+    "TaskStop",
+    "SendMessage",
+    "Artifact",
+];
+/**
+ * The 7 unconditional entries of the vendor's first filter — "removes these
+ * tools, even when listed in the `tools` field", with no qualifier attached.
+ * Listing one is a genuine dead reference, and the only tool verdict that
+ * still enters the grade.
+ */
+exports.claudeCodeWithheldAgentTools = [
+    "AskUserQuestion",
+    "EndConversation",
+    "EnterPlanMode",
+    "ScheduleWakeup",
+    "TaskOutput",
+    "WaitForMcpServers",
+    "Workflow",
+];
+/** Vendor conditions quoted once, so the term table below stays readable. */
+const DEPTH_LIMIT = "only when the subagent is at the depth limit; in a fork the tool stays " +
+    "listed but returns an error instead of spawning";
+const BACKGROUND = "from a background subagent (the default) — a foreground subagent or a fork " +
+    "keeps it";
+const BACKGROUND_AND_MODEL = `${BACKGROUND}; also withheld from Opus 4.8 / Sonnet 5 / Fable 5 / Mythos 5 ` +
+    "and later unless CLAUDE_CODE_ENABLE_TODO_TOOLS=1";
+/**
+ * Tools the platform removes only under a stated condition — the qualified
+ * entries of the first filter, plus the built-ins that survive in the
+ * foreground but not in the background. Declaring one is legitimate, so none
+ * of these is scored; the condition is reported and vigiles stops there.
+ */
+exports.claudeCodeConditionalAgentToolNames = [
+    "Agent",
+    // The rename runs the OTHER WAY from what vigiles used to encode: `Task` is
+    // the old name and still works as an alias, `Agent` is the current one.
+    "Task",
+    "ExitPlanMode",
+    "ListAgents",
+    "LSP",
+    "ShareOnboardingGuide",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "TaskCreate",
+    "TaskGet",
+    "TaskList",
+    "TaskUpdate",
+];
+/**
+ * The vendor's qualifier for each conditional tool.
+ *
+ * Typed as a `Record` over the name tuple ON PURPOSE: a conditional tool with no
+ * stated condition cannot be reported as conditional (the condition IS the
+ * report), so adding a name above without a line here is a `tsc` error rather
+ * than a runtime surprise. The equivalent runtime check in
+ * `vocabularyProjectionProblems` stays for adapters that build a vocabulary
+ * dynamically, but for this one the gap is unrepresentable.
+ */
+const CONDITIONS = {
+    Agent: DEPTH_LIMIT,
+    Task: DEPTH_LIMIT,
+    ExitPlanMode: "unless the subagent's permissionMode is plan",
+    ListAgents: "from a background subagent; a foreground subagent inherits it only in " +
+        "sessions where cross-session messaging is enabled",
+    LSP: BACKGROUND,
+    ShareOnboardingGuide: BACKGROUND,
+    CronCreate: BACKGROUND,
+    CronDelete: BACKGROUND,
+    CronList: BACKGROUND,
+    TaskCreate: BACKGROUND_AND_MODEL,
+    TaskGet: BACKGROUND_AND_MODEL,
+    TaskList: BACKGROUND_AND_MODEL,
+    TaskUpdate: BACKGROUND_AND_MODEL,
+};
+/** Still-honoured deprecated spellings, pointing at the current name. */
+const ALIASES = { Task: "Agent" };
+/**
+ * The side-effecting subset of everything a subagent may declare (the
+ * complement is read-only). Two rules decided the additions here, both from the
+ * vendor's own tool descriptions rather than from the tool's name:
+ *
+ *  - `Monitor` "writes a small script, runs it in the background" and can open
+ *    a WebSocket — execution plus network, so it is side-effecting despite
+ *    reading like an observer.
+ *  - `LSP`, `ToolSearch`, `ListAgents`, `TaskGet`, `TaskList` and `CronList`
+ *    only report state, so they stay read-only.
+ *
+ * This matters beyond tidiness: `classifyToolEffect` treats "in the built-in
+ * catalog and NOT here" as read-only, so a name added to the catalog without a
+ * decision here would silently be declared harmless — and a spawning tool
+ * misfiled as read-only would let a subagent pass the lethal-trifecta check it
+ * should fail.
+ */
+exports.claudeCodeSideEffectingAgentTools = [
+    "Bash",
+    "PowerShell",
+    "Edit",
+    "Write",
+    "NotebookEdit",
+    "WebFetch",
+    "WebSearch",
+    "Skill",
+    "TodoWrite",
+    "Monitor",
+    "SendMessage",
+    "Artifact",
+    "EnterWorktree",
+    "ExitWorktree",
+    "TaskStop",
+    "Agent",
+    "Task",
+    "TaskCreate",
+    "TaskUpdate",
+    "CronCreate",
+    "CronDelete",
+    "ShareOnboardingGuide",
+];
+/** The hook-event vocabulary — every documented event, all currently available. */
+exports.claudeCodeHookEventVocabulary = {
+    kind: "claude-code hook event",
+    capturedFrom: `${CAPTURE} § hooks / Hook events`,
+    terms: exports.claudeCodeHookEventNames.map((name) => ({ name, status: "available" })),
+};
+/** The subagent-tool vocabulary — available / withheld / conditional. */
+exports.claudeCodeSubagentToolVocabulary = {
+    kind: "claude-code subagent tool",
+    capturedFrom: `${CAPTURE} § sub-agents / Available tools`,
+    terms: [
+        ...exports.claudeCodeAvailableAgentTools.map((name) => ({ name, status: "available" })),
+        ...exports.claudeCodeWithheldAgentTools.map((name) => ({ name, status: "withheld" })),
+        ...exports.claudeCodeConditionalAgentToolNames.map((name) => ({
+            name,
+            status: "conditional",
+            condition: CONDITIONS[name],
+            ...(ALIASES[name] !== undefined ? { aliasOf: ALIASES[name] } : {}),
+        })),
+    ],
+};
+//# sourceMappingURL=vocabulary.js.map

package/dist/adapters/codex/eval.js

@@ -36,6 +36,7 @@ exports.codexEvalAgentRunner = codexEvalAgentRunner;
 exports.codexEvalRunner = codexEvalRunner;
 const node_child_process_1 = require("node:child_process");
 const foreign_runner_js_1 = require("../../core/foreign-runner.js");
+const eval_load_phase_js_1 = require("../../core/eval-load-phase.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const str = (v) => (typeof v === "string" ? v : "");
@@ -229,6 +230,7 @@ function codexEvalRunner(args) {
     // The DOCUMENTED alternative to the default Claude runner, and the one the
     // untested-skill nudge now recommends — so it is exactly as able to be
     // collected by a stray `npx vitest run`, and exactly as expensive.
+    (0, eval_load_phase_js_1.refuseDuringEvalLoad)("driving `codex exec`");
     (0, foreign_runner_js_1.refuseUnderForeignRunner)("driving `codex exec`");
     const r = (0, node_child_process_1.spawnSync)("codex", [
         "exec",

package/dist/audit-score.js

@@ -49,7 +49,7 @@ const score_core_js_1 = require("./score-core.js");
 const W_UNTESTED = 3;
 /** The command that answers the firing question — named, not alluded to. */
 const MEASURE_FIRING_COMMAND = "run `npx vigiles audit` interactively to measure, or add a `*.eval.mjs` " +
-    "(`paid_measureTriggerRate`, vigiles/eval)";
+    "(`export default defineEval({ measureTriggerRate: … })`, vigiles)";
 /** Resolve the terse "thing(s)" plural placeholder against a count:
  * n===1 drops the "(s)" ("1 tool"); otherwise it becomes "s" ("3 tools"). */
 function pluralizeLabel(n, label) {

package/dist/cli.js

@@ -1706,7 +1706,7 @@ function formatTriggerNudge(triggerableSkills) {
         return "";
     const n = triggerableSkills;
     return (`ℹ Do your ${String(n)} skill${n === 1 ? "" : "s"} actually fire? The deterministic read can't tell — ` +
-        `run \`audit\` interactively to measure, or test with \`paid_measureTriggerRate\` (vigiles/eval).`);
+        `run \`audit\` interactively to measure, or add a \`*.eval.mjs\` declaring \`measureTriggerRate\` (vigiles).`);
 }
 /** A terminal summary of the rule map: the CONFIDENT lane counts + the POSSIBLE
  * (review) and SKIPPED tiers, with the honest caveat that detection is a
@@ -4336,7 +4336,12 @@ async function handleRunScripts(kind, args, restArgs) {
     if (trialsFlag)
         env.VIGILES_TRIALS = trialsFlag.split("=")[1];
     console.log(`Running ${String(files.length)} ${kind} file(s):\n`);
-    const results = (0, run_scripts_js_1.runScripts)(files, cwd, env);
+    // An eval file DESCRIBES its eval; `dist/eval-entry.js` is what imports the
+    // description and runs what it declares. A harness script is still its own
+    // program (it is free, so "import spends money" never applied to it).
+    const results = (0, run_scripts_js_1.runScripts)(files, cwd, env, {
+        ...(kind === "eval" ? { entry: (0, node_path_1.resolve)(__dirname, "eval-entry.js") } : {}),
+    });
     // Write down WHAT the run exercised, so `lint`/`audit` can answer "tested?"
     // from execution instead of from a matching file name. Not a new verb and not
     // a flag: the run already happened, and this is the runner recording what it

package/dist/core/compile.js

@@ -827,7 +827,12 @@ function compileSkill(spec, options = {}) {
  * detection lives in the shared `verifyToolContract` detector (one-detector-no-
  * drift: compile + scan + the subagent-tool-contract lint rule call the same code). */
 function validateAgentTools(tools, dialect) {
-    return (0, tool_contract_js_1.verifyToolContract)(tools, dialect).map((issue) => ({
+    // `authoringIssues` drops the `conditional` verdicts: `Agent`, `ExitPlanMode`
+    // and the foreground-only built-ins are REAL tools, legitimate to declare, and
+    // erroring on them is what made `tools: Agent, Read, Bash` — a worked example
+    // in the vendor's own docs — fail to compile. Everything else stays an error,
+    // because authoring your own spec is a closed world.
+    return (0, tool_contract_js_1.authoringIssues)((0, tool_contract_js_1.verifyToolContract)(tools, dialect)).map((issue) => ({
         type: "unknown-tool",
         message: issue.message,
     }));

package/dist/core/dialect.d.ts

@@ -22,6 +22,7 @@
  * Which SKILL.md frontmatter keys a harness understands — see
  * `HarnessDialect.skillFrontmatter`.
  */
+import type { HarnessVocabulary } from "./vocabulary.js";
 export type SkillFrontmatterProfile = "claude-code" | "minimal";
 export interface HarnessDialect {
     /** Stable identifier, e.g. "claude-code". */
@@ -83,5 +84,31 @@ export interface HarnessDialect {
      * Optional (additive, non-breaking) — absent ⇒ no tool is known-side-effecting.
      */
     readonly sideEffectingTools?: readonly string[];
+    /**
+     * The hook-event catalog as a {@link HarnessVocabulary} — a status and a
+     * recorded vendor capture per term, rather than bare membership in
+     * `hookEvents`. When present it is what `verifyHookEvents` classifies against,
+     * so a name the catalog doesn't hold produces an `unrecognised` ADVISORY
+     * (naming vigiles's capture as the possibly-stale party) instead of the old
+     * behaviour, where an unknown name drew an accusation or silence depending on
+     * its edit distance to the list.
+     *
+     * Optional (additive, non-breaking). Absent ⇒ one is synthesised from
+     * `hookEvents` via `vocabularyFromLists`, so a legacy adapter keeps working
+     * and its unknowns become advisories rather than silence.
+     */
+    readonly hookEventVocabulary?: HarnessVocabulary;
+    /**
+     * The subagent-tool catalog as a {@link HarnessVocabulary}. Same contract as
+     * `hookEventVocabulary`; absent ⇒ synthesised from `builtinAgentTools`
+     * (available) + `neverAvailableTools` (withheld).
+     *
+     * The third status is why this exists: the vendor removes `Agent` only at the
+     * spawn depth limit and `ExitPlanMode` only outside plan mode, and removes
+     * most built-ins from a background subagent but not a foreground one — so
+     * "available to a subagent" is not a property of the name, and a two-way
+     * split had to encode one of those conditions as an unconditional fact.
+     */
+    readonly subagentToolVocabulary?: HarnessVocabulary;
 }
 //# sourceMappingURL=dialect.d.ts.map

package/dist/core/eval-load-phase.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The paid tier is closed while an eval file is being LOADED.
+ *
+ * ## The failure this removes
+ *
+ * An eval file used to do its work at the top level:
+ *
+ *   const report = await measureTriggerRate({ … });   // ← module body
+ *
+ * In ESM, `import` IS execution, so *reading* such a file spends real money.
+ * Measured 2026-08-12 (and reproduced 2026-08-18 with an inert stand-in that
+ * writes a marker file instead of spawning): `node -e 'import("./x.eval.mjs")'`
+ * ran the whole body and the one guard that exists — `refuseUnderForeignRunner`
+ * — stayed SILENT, because under `node -e` there is no `process.argv[1]` at all:
+ *
+ *   node -e 'import(x)'   argv[1] = undefined  → foreignRunner(…) = null
+ *
+ * That guard is not broken; it answers a different question ("does somebody
+ * else's test runner own this process?"). No process fact distinguishes
+ * `node -e 'import(x)'` from a legitimate runner doing `import(x)`, so no
+ * argv-shaped guard can close this door without also refusing the correct
+ * invocation — the exact failure mode that got `process.env.VITEST` rejected in
+ * `foreign-runner.ts`.
+ *
+ * ## What closes it instead
+ *
+ * The SHAPE changed: an eval file now DESCRIBES its eval (`defineEval`) and
+ * `vigiles eval` runs it. A description cannot spend, so for a conforming file
+ * the door is shut by construction and this module is not needed.
+ *
+ * This module covers the file that is only HALF migrated — a `defineEval` export
+ * plus a leftover top-level `measure(…)`. During the import that the eval runner
+ * performs, the paid tier refuses. So the usual way anyone runs an eval turns a
+ * silent bill into a loud error that names the fix, instead of paying it.
+ *
+ * ⚠️ HONEST BOUNDARY, stated rather than implied. This is scoped to the runner's
+ * own import. `node -e 'import("./half-migrated.eval.mjs")'` still spends,
+ * because that file still contains the original defect — the redesign made the
+ * defect *avoidable and detectable*, it cannot retroactively fix a file that did
+ * not adopt it. The free syntax check is `node --check <file>`, which never
+ * executes anything.
+ *
+ * ## Why the default is OPEN
+ *
+ * `paid_runEval` and friends are public API; somebody's own script calling them
+ * at top level is their business. A gate that defaulted to closed would refuse
+ * every correct direct call — again, "a guard that fires on correct input is a
+ * guard people delete". So the window is opened by nobody and closed by exactly
+ * one caller: `eval-entry.ts`, around its `import()`.
+ *
+ * Imports NOTHING, so every spawn door (including the adapters) can call it
+ * without a cycle — the same reason `foreign-runner.ts` is a leaf.
+ */
+/**
+ * Open the no-spend window. Called by `eval-entry.ts` immediately before it
+ * imports an eval file, and paired with {@link endEvalLoad} in a `finally`.
+ */
+export declare function beginEvalLoad(): void;
+/** Close the no-spend window: the description is loaded, the runner may spend. */
+export declare function endEvalLoad(): void;
+/** Whether the no-spend window is open (exported for tests + the entry). */
+export declare function inEvalLoad(): boolean;
+/**
+ * The refusal message. Separate from the check so a test can assert the WORDS:
+ * this fires on a file whose author has not seen the new shape yet, so it has to
+ * teach it, not just stop.
+ */
+export declare function evalLoadRefusal(what: string): string;
+/**
+ * Refuse to spend model budget while an eval file is being imported.
+ *
+ * 🔴 CALL THIS AT EVERY REAL-MODEL SPAWN, beside `refuseUnderForeignRunner`, and
+ * OUTSIDE any `try` that swallows — `judge` and `deriveAttackReal` both wrap
+ * their spawn in `try { … } catch { return fallback }`, so a refusal thrown
+ * inside would be downgraded to a score of 0 instead of stopping the run.
+ */
+export declare function refuseDuringEvalLoad(what: string): void;
+//# sourceMappingURL=eval-load-phase.d.ts.map

package/dist/core/eval-load-phase.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * The paid tier is closed while an eval file is being LOADED.
+ *
+ * ## The failure this removes
+ *
+ * An eval file used to do its work at the top level:
+ *
+ *   const report = await measureTriggerRate({ … });   // ← module body
+ *
+ * In ESM, `import` IS execution, so *reading* such a file spends real money.
+ * Measured 2026-08-12 (and reproduced 2026-08-18 with an inert stand-in that
+ * writes a marker file instead of spawning): `node -e 'import("./x.eval.mjs")'`
+ * ran the whole body and the one guard that exists — `refuseUnderForeignRunner`
+ * — stayed SILENT, because under `node -e` there is no `process.argv[1]` at all:
+ *
+ *   node -e 'import(x)'   argv[1] = undefined  → foreignRunner(…) = null
+ *
+ * That guard is not broken; it answers a different question ("does somebody
+ * else's test runner own this process?"). No process fact distinguishes
+ * `node -e 'import(x)'` from a legitimate runner doing `import(x)`, so no
+ * argv-shaped guard can close this door without also refusing the correct
+ * invocation — the exact failure mode that got `process.env.VITEST` rejected in
+ * `foreign-runner.ts`.
+ *
+ * ## What closes it instead
+ *
+ * The SHAPE changed: an eval file now DESCRIBES its eval (`defineEval`) and
+ * `vigiles eval` runs it. A description cannot spend, so for a conforming file
+ * the door is shut by construction and this module is not needed.
+ *
+ * This module covers the file that is only HALF migrated — a `defineEval` export
+ * plus a leftover top-level `measure(…)`. During the import that the eval runner
+ * performs, the paid tier refuses. So the usual way anyone runs an eval turns a
+ * silent bill into a loud error that names the fix, instead of paying it.
+ *
+ * ⚠️ HONEST BOUNDARY, stated rather than implied. This is scoped to the runner's
+ * own import. `node -e 'import("./half-migrated.eval.mjs")'` still spends,
+ * because that file still contains the original defect — the redesign made the
+ * defect *avoidable and detectable*, it cannot retroactively fix a file that did
+ * not adopt it. The free syntax check is `node --check <file>`, which never
+ * executes anything.
+ *
+ * ## Why the default is OPEN
+ *
+ * `paid_runEval` and friends are public API; somebody's own script calling them
+ * at top level is their business. A gate that defaulted to closed would refuse
+ * every correct direct call — again, "a guard that fires on correct input is a
+ * guard people delete". So the window is opened by nobody and closed by exactly
+ * one caller: `eval-entry.ts`, around its `import()`.
+ *
+ * Imports NOTHING, so every spawn door (including the adapters) can call it
+ * without a cycle — the same reason `foreign-runner.ts` is a leaf.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.beginEvalLoad = beginEvalLoad;
+exports.endEvalLoad = endEvalLoad;
+exports.inEvalLoad = inEvalLoad;
+exports.evalLoadRefusal = evalLoadRefusal;
+exports.refuseDuringEvalLoad = refuseDuringEvalLoad;
+/** Whether an eval module is being imported by the eval runner right now. */
+let loading = false;
+/**
+ * Open the no-spend window. Called by `eval-entry.ts` immediately before it
+ * imports an eval file, and paired with {@link endEvalLoad} in a `finally`.
+ */
+function beginEvalLoad() {
+    loading = true;
+}
+/** Close the no-spend window: the description is loaded, the runner may spend. */
+function endEvalLoad() {
+    loading = false;
+}
+/** Whether the no-spend window is open (exported for tests + the entry). */
+function inEvalLoad() {
+    return loading;
+}
+/**
+ * The refusal message. Separate from the check so a test can assert the WORDS:
+ * this fires on a file whose author has not seen the new shape yet, so it has to
+ * teach it, not just stop.
+ */
+function evalLoadRefusal(what) {
+    return (`vigiles refused to spawn a model: ${what} while an eval file was being IMPORTED.\n` +
+        `  An eval file DESCRIBES its eval; it must not run one at the top level — importing such a\n` +
+        `  file spends real money (that is the defect this shape removes).\n` +
+        `  Move the runner call into the description, keyed by the runner's own name:\n` +
+        `      import { defineEval } from "vigiles";\n` +
+        `      export default defineEval({ measureTriggerRate: { …the spec you passed… } });\n` +
+        `  and read the report in \`assert(report)\`. See docs/harness-testing.md § Eval files.`);
+}
+/**
+ * Refuse to spend model budget while an eval file is being imported.
+ *
+ * 🔴 CALL THIS AT EVERY REAL-MODEL SPAWN, beside `refuseUnderForeignRunner`, and
+ * OUTSIDE any `try` that swallows — `judge` and `deriveAttackReal` both wrap
+ * their spawn in `try { … } catch { return fallback }`, so a refusal thrown
+ * inside would be downgraded to a score of 0 instead of stopping the run.
+ */
+function refuseDuringEvalLoad(what) {
+    if (loading)
+        throw new Error(evalLoadRefusal(what));
+}
+//# sourceMappingURL=eval-load-phase.js.map

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

@@ -4,31 +4,48 @@
  * (`PreToolUse`, `SessionStart`, …); a TYPO (`PreToolUSe`) means the hook
  * silently never fires — a dead registration no generic JSON linter catches.
  *
- * Like the tool catalog, the event set is NOT closed in practice: frameworks
- * extend it (TheBushidoCollective/han ships a custom runtime with `TeammateIdle`,
- * `WorktreeRemove`, … in its own `hooks.json`). So the audit path (scan/lint) is
- * HIGH-PRECISION — `confidentHookEventIssues` keeps only a close typo
- * (a did-you-mean within edit distance 2), never a bare unrecognized event that
- * may be a custom/future one. ONE detector (one-detector-no-drift): scan + the
- * `hook-events` lint rule call the same code. Dialect injected (core ⊄ adapter).
+ * The event set is NOT closed in practice: the vendor keeps adding events, and
+ * frameworks ship custom runtimes with their own (TheBushidoCollective/han fires
+ * `TeammateIdle`, `WorktreeRemove`, … from its own `hooks.json` — both of which
+ * have since become real Claude Code events). This check used to handle that by
+ * reporting an unknown event ONLY when it sat within edit distance 2 of a known
+ * one. That is not a confidence signal, and it failed both ways at once:
+ * `Setup`, a documented event, was accused of never firing and told to become
+ * `Stop`; twenty-one other documented events drew nothing, because they happened
+ * to be further than two characters from anything in a nine-name list.
+ *
+ * Now every name is CLASSIFIED against the dialect's vocabulary
+ * (`core/vocabulary.ts`) and every verdict is reported — with the severity
+ * coming from the verdict rather than from the caller. An event vigiles doesn't
+ * hold is an `advisory` that names vigiles's own capture as the thing that may
+ * be stale; it is surfaced and never scored, so a newer or custom event cannot
+ * cost anyone a grade. ONE detector (one-detector-no-drift): scan + the
+ * `hook-events` lint rule + compiled-hook `on:` validation call the same code.
+ * Dialect injected (core ⊄ adapter).
  */
 import type { HarnessDialect } from "./dialect.js";
+import { type HarnessVocabulary, type IssueSeverity, type TermVerdict } from "./vocabulary.js";
 export interface HookEventIssue {
     readonly event: string;
-    /** Closest known event (did-you-mean), or null. */
+    /** Which vocabulary verdict produced this — the input to every policy. */
+    readonly verdict: TermVerdict["kind"];
+    /** Closest known event (did-you-mean), or null. Message decoration only. */
     readonly suggestion: string | null;
+    /** `"scored"` counts toward the grade; `"advisory"` never does. */
+    readonly severity: IssueSeverity;
     readonly message: string;
 }
 /**
- * The HIGH-CONFIDENCE subset (what scan / lint act on): only an unrecognized
- * event that's a close typo of a real one. A bare unknown (no near match) is
- * likely a framework/custom event, not a defect — never flagged when auditing.
+ * The event vocabulary this dialect verifies against — its declared one, else a
+ * synthesised one built from the flat `hookEvents` list so an adapter that
+ * predates vocabularies keeps working.
  */
-export declare function confidentHookEventIssues(issues: readonly HookEventIssue[]): HookEventIssue[];
+export declare function hookEventVocabulary(dialect: HarnessDialect): HarnessVocabulary;
 /**
- * Verify hook-event names against the dialect catalog. Returns one issue per
- * unrecognized event. Like the tool-contract check, a suggestion (edit distance
- * ≤ 2) is the confidence signal that an unknown is really a typo of a real event.
+ * Verify hook-event names against the dialect vocabulary. Returns one issue per
+ * name that isn't plainly available, each already carrying its severity — see
+ * {@link scoredIssues} / {@link advisoryIssues} to split them.
  */
 export declare function verifyHookEvents(events: readonly string[], dialect: HarnessDialect): HookEventIssue[];
+export { scoredIssues, advisoryIssues, authoringIssues } from "./vocabulary.js";
 //# sourceMappingURL=hook-events.d.ts.map

package/dist/core/hook-events.js

@@ -1,48 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.confidentHookEventIssues = confidentHookEventIssues;
+exports.authoringIssues = exports.advisoryIssues = exports.scoredIssues = void 0;
+exports.hookEventVocabulary = hookEventVocabulary;
 exports.verifyHookEvents = verifyHookEvents;
-const edit_distance_js_1 = require("./edit-distance.js");
-/** Closest known hook event by edit distance (≤ 2) — a confidence signal. */
-function closestEvent(event, dialect) {
-    let best = null;
-    let bestDistance = Infinity;
-    for (const known of dialect.hookEvents) {
-        const d = (0, edit_distance_js_1.editDistance)(event.toLowerCase(), known.toLowerCase());
-        if (d < bestDistance) {
-            bestDistance = d;
-            best = known;
-        }
-    }
-    return bestDistance <= 2 ? best : null;
-}
+const vocabulary_js_1 = require("./vocabulary.js");
 /**
- * The HIGH-CONFIDENCE subset (what scan / lint act on): only an unrecognized
- * event that's a close typo of a real one. A bare unknown (no near match) is
- * likely a framework/custom event, not a defect — never flagged when auditing.
+ * The event vocabulary this dialect verifies against — its declared one, else a
+ * synthesised one built from the flat `hookEvents` list so an adapter that
+ * predates vocabularies keeps working.
  */
-function confidentHookEventIssues(issues) {
-    return issues.filter((i) => i.suggestion !== null);
+function hookEventVocabulary(dialect) {
+    return (dialect.hookEventVocabulary ??
+        (0, vocabulary_js_1.vocabularyFromLists)(`${dialect.name} hook event`, `${dialect.name} adapter (no recorded capture)`, dialect.hookEvents));
 }
 /**
- * Verify hook-event names against the dialect catalog. Returns one issue per
- * unrecognized event. Like the tool-contract check, a suggestion (edit distance
- * ≤ 2) is the confidence signal that an unknown is really a typo of a real event.
+ * Verify hook-event names against the dialect vocabulary. Returns one issue per
+ * name that isn't plainly available, each already carrying its severity — see
+ * {@link scoredIssues} / {@link advisoryIssues} to split them.
  */
 function verifyHookEvents(events, dialect) {
-    const known = new Set(dialect.hookEvents);
+    const vocab = hookEventVocabulary(dialect);
     const issues = [];
     for (const event of events) {
-        if (known.has(event))
+        const issue = (0, vocabulary_js_1.termIssue)(vocab, (0, vocabulary_js_1.classify)(vocab, event), "Hook event", "a hook here never fires");
+        if (issue === null)
             continue;
-        const near = closestEvent(event, dialect);
-        const hint = near ? ` Did you mean "${near}"?` : "";
         issues.push({
             event,
-            suggestion: near,
-            message: `Unknown hook event "${event}" — a hook here never fires. Valid events: ${dialect.hookEvents.join(", ")}.${hint}`,
+            verdict: issue.verdict,
+            suggestion: issue.suggestion,
+            severity: issue.severity,
+            message: issue.message,
         });
     }
     return issues;
 }
+var vocabulary_js_2 = require("./vocabulary.js");
+Object.defineProperty(exports, "scoredIssues", { enumerable: true, get: function () { return vocabulary_js_2.scoredIssues; } });
+Object.defineProperty(exports, "advisoryIssues", { enumerable: true, get: function () { return vocabulary_js_2.advisoryIssues; } });
+Object.defineProperty(exports, "authoringIssues", { enumerable: true, get: function () { return vocabulary_js_2.authoringIssues; } });
 //# sourceMappingURL=hook-events.js.map