vigiles 16.1.2 → 16.1.3

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

package/dist/core/hook-program.js

@@ -679,11 +679,19 @@ function compileHookProgram(source, hook, opts = {}) {
                 `regex (that is why "Edit|Write" works), so it must parse as one.`);
         }
     }
-    // A hook registered under an event the harness never fires is dead — reject it.
+    // A hook registered under an event the harness never fires is dead — reject
+    // it. AUTHORING is a closed world (you are writing this hook now, against the
+    // vigiles you have), so an unrecognised event is still an error — the typo
+    // guarantee this exists for. What changed on 2026-08-17 is the catalog it
+    // asks: this used to throw on `Setup`, `PostCompact`, `ConfigChange` and 19
+    // other REAL events, because vigiles held 9 of the vendor's 31. The fix is the
+    // right vocabulary, not a weaker check. A genuinely newer event still fails
+    // here, and now says so — the message names vigiles's capture as the thing
+    // that may be stale, instead of asserting the event does not exist.
     if (opts.dialect) {
-        const issues = (0, hook_events_js_1.verifyHookEvents)([on], opts.dialect);
-        if (issues.length > 0) {
-            throw new HookCompileError(issues[0].message);
+        const fatal = (0, hook_events_js_1.authoringIssues)((0, hook_events_js_1.verifyHookEvents)([on], opts.dialect));
+        if (fatal.length > 0) {
+            throw new HookCompileError(fatal[0].message);
         }
     }
     // A `needs` entry that isn't a built-in provider never resolves — reject it

package/dist/core/rule-meta.js

@@ -85,7 +85,7 @@ exports.RULE_META = {
         surface: ["subagent"],
         defaultSeverity: "warn",
         summary: "A subagent's tools: are all real (no never-available / typo).",
-        detector: "confidentToolIssues",
+        detector: "verifyToolContract / scoredIssues",
         upstreamPrevention: "typed agent() vocabulary + compileAgent — an unknown tool is a tsc/compile error",
     },
     "disallowed-tools-contract": {
@@ -113,7 +113,7 @@ exports.RULE_META = {
         surface: ["hook"],
         defaultSeverity: "warn",
         summary: "A hook's event name is one the harness defines (it can fire).",
-        detector: "confidentHookEventIssues",
+        detector: "verifyHookEvents / scoredIssues",
         upstreamPrevention: "compiled hook on: is dialect-validated at compile",
     },
     "hook-script-exists": {

package/dist/core/tool-contract.d.ts

@@ -2,8 +2,8 @@
  * Tool-contract verification — the cross-referencing moat ("valid is not true")
  * applied to a subagent's declared `tools:` rail. A subagent may only run
  * built-in tools from the harness dialect's catalog or an MCP tool; anything else
- * is a typo or a nonexistent / never-available tool — a guaranteed-dead reference
- * a compiler catches, not a runtime surprise.
+ * is a typo or a nonexistent tool — a guaranteed-dead reference a compiler
+ * catches, not a runtime surprise.
  *
  * ONE pure detector (`one-detector-no-drift`), reused by THREE callers so they
  * can't disagree: `compileAgent` (spec authoring), `scan` (read-only audit of a
@@ -11,51 +11,89 @@
  * commit gate). The dialect is injected (core ⊄ adapter) — the composition root
  * passes `claudeCodeDialect` / `codexDialect`.
  *
- * Scope note: this validates a SUBAGENT contract against the SUBAGENT catalog
- * (`builtinAgentTools` / `neverAvailableTools`). A skill's `allowed-tools` is a
- * DIFFERENT namespace (skills legitimately use `AskUserQuestion`, `TaskCreate`,
- * … which are never-available to a subagent), so it is deliberately NOT validated
- * here — doing so against the agent catalog would be a false-positive factory.
+ * WHAT CHANGED, 2026-08-17. This used to split names two ways — in
+ * `builtinAgentTools` (fine) or in `neverAvailableTools` (dead) — and decide
+ * what to say about a name in neither by its edit distance to the first list.
+ * Two failures came out of that shape:
+ *
+ *  - `Agent` was in the DENYLIST while its own deprecated alias `Task` was in the
+ *    catalog, so vigiles rejected the platform's current name, accepted the old
+ *    one, and told orchestrator subagents to remove the tool they exist to use.
+ *    Nothing could notice, because the two lists were never compared.
+ *  - Real tools vigiles didn't know (`EndConversation`, `TaskOutput`,
+ *    `Workflow`) and outright invented ones passed in silence, while typos of
+ *    known names were caught — so the more wrong a name was, the likelier it
+ *    went unreported.
+ *
+ * Names are now CLASSIFIED against the dialect's vocabulary
+ * (`core/vocabulary.ts`), which has a third status for what the two-way split
+ * could not express: the vendor removes `Agent` only at the spawn depth limit,
+ * `ExitPlanMode` only outside plan mode, and most built-ins only from a
+ * background subagent. Those are `conditional` — reported as a note with the
+ * condition quoted, never as "remove it". Severity travels on the issue, so
+ * `scan`, `lint` and `compileAgent` cannot drift apart on which issues count.
+ *
+ * Scope note: this validates a SUBAGENT contract against the SUBAGENT catalog. A
+ * skill's `allowed-tools` is a DIFFERENT namespace (skills legitimately use
+ * `AskUserQuestion`, `TaskCreate`, … which a subagent doesn't get), so it is
+ * deliberately NOT validated here — doing so against the agent catalog would be
+ * a false-positive factory.
  */
 import type { HarnessDialect } from "./dialect.js";
-export type ToolIssueKind = "never-available" | "unknown";
+import { type HarnessVocabulary, type IssueSeverity, type TermVerdict } from "./vocabulary.js";
+export type ToolIssueKind = 
+/** The platform removes it unconditionally — a real, scored defect. */
+"never-available"
+/** Not in vigiles's catalog — advisory; may be newer than our capture. */
+ | "unknown"
+/** Real, but removed under a condition vigiles can't see — advisory. */
+ | "conditional";
 export interface ToolIssue {
     readonly tool: string;
     readonly kind: ToolIssueKind;
-    /** Closest known built-in tool (did-you-mean), or null. */
+    /** Which vocabulary verdict produced this — the input to every policy. */
+    readonly verdict: TermVerdict["kind"];
+    /** Closest known built-in tool (did-you-mean), or null. Message only. */
     readonly suggestion: string | null;
+    /**
+     * The vendor condition — present ONLY for a `conditional` verdict. Carried so
+     * a report can group the tools sharing one condition rather than repeat the
+     * same sentence per tool.
+     */
+    readonly condition?: string;
+    /** `"scored"` counts toward the grade; `"advisory"` never does. */
+    readonly severity: IssueSeverity;
     /** A ready-to-show, actionable message. */
     readonly message: string;
 }
 /**
- * Closest known built-in tool by edit distance (≤ 2), for a "did you mean" hint.
- * The ≤ 2 bound is deliberately tight: a suggestion is a CONFIDENCE signal (this
- * `unknown` is really a typo of a real tool), and a loose bound mis-suggests —
- * `TaskGet → Task?` (distance 3) is a real tool set, not a typo of `Task`.
+ * The tool vocabulary this dialect verifies against — its declared one, else a
+ * synthesised one from the flat lists so a legacy adapter keeps working.
  */
-export declare function closestTool(tool: string, dialect: HarnessDialect): string | null;
+export declare function subagentToolVocabulary(dialect: HarnessDialect): HarnessVocabulary;
 /**
- * The HIGH-CONFIDENCE subset of a contract's issues — the ones safe to flag when
- * AUDITING a third-party plugin (scan / lint), where the catalog can't know
- * every tool (plugin-/MCP-provided, newer platform tools). Only two are confident:
- * a `never-available` tool (a curated denylist) and an `unknown` with a close
- * typo suggestion (`Edt → Edit`). A bare `unknown` with no near match is NOT
- * flagged here — it is more likely a tool vigiles doesn't know than a defect
- * (sweeping real plugins surfaced a 280★ plugin using `TaskCreate/TaskGet/…`
- * consistently; flagging those would be crying wolf). `compileAgent` stays strict
- * — when you author your OWN spec, every unrecognized tool is worth an error.
+ * Closest known built-in tool by edit distance (≤ 2), for a "did you mean" hint.
+ * A MESSAGE DECORATION, never a gate: whether to report is already settled by
+ * the verdict before this is called. The ≤ 2 bound stays tight because a loose
+ * bound mis-suggests — `TaskGet → Task?` is a different real tool, not a typo.
  */
-export declare function confidentToolIssues(issues: readonly ToolIssue[]): ToolIssue[];
+export declare function closestTool(tool: string, dialect: HarnessDialect): string | null;
 /**
  * Verify a subagent's `disallowedTools:` BLOCK-list — the mirror of the allow
  * contract. A typo here is dangerous: you meant to block `Bash` but wrote `Bsh`,
  * so nothing is blocked and the dangerous tool stays available, silently. Returns
- * one {@link ToolIssue} per entry that's a CLOSE TYPO of a real built-in (the
- * high-confidence signal). Deliberately NOT flagged: a real built-in (it IS being
- * blocked — correct), a never-available tool (harmless to block), an MCP tool (a
- * legitimate plugin tool to block), or a bare unknown with no near match (likely
- * a plugin/MCP tool, not a typo — the cry-wolf trap). The block-list inverts the
- * allow check: never-available is fine to list, a typo is the actual defect.
+ * one {@link ToolIssue} per entry that's a CLOSE TYPO of a real tool.
+ * Deliberately NOT flagged: any name the vocabulary knows (blocking it is the
+ * point — including a withheld one, which is merely redundant), an MCP tool (a
+ * legitimate plugin tool to block), or a bare unknown with no near match.
+ *
+ * This is the ONE place a near match still gates a finding, and it is not the
+ * confidence proxy the allow-side check was rightly stripped of. On a block-list
+ * the risk inverts: an entry naming nothing is harmless UNLESS you meant a real
+ * tool and mistyped it, and "meant a real tool" is precisely what a one-character
+ * distance evidences. `disallowedTools: [Zzzz]` blocks nothing and nobody
+ * intended otherwise; `disallowedTools: [Bsh]` leaves `Bash` wide open. So the
+ * distance here is the actual semantic signal, not a stand-in for one.
  */
 export declare function disallowedToolIssues(tools: readonly string[], dialect: HarnessDialect): ToolIssue[];
 /**
@@ -65,4 +103,5 @@ export declare function disallowedToolIssues(tools: readonly string[], dialect:
  * is stripped to its base tool before checking.
  */
 export declare function verifyToolContract(tools: readonly string[], dialect: HarnessDialect): ToolIssue[];
+export { scoredIssues, advisoryIssues, authoringIssues } from "./vocabulary.js";
 //# sourceMappingURL=tool-contract.d.ts.map

package/dist/core/tool-contract.js

@@ -1,73 +1,77 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.authoringIssues = exports.advisoryIssues = exports.scoredIssues = void 0;
+exports.subagentToolVocabulary = subagentToolVocabulary;
 exports.closestTool = closestTool;
-exports.confidentToolIssues = confidentToolIssues;
 exports.disallowedToolIssues = disallowedToolIssues;
 exports.verifyToolContract = verifyToolContract;
-const edit_distance_js_1 = require("./edit-distance.js");
+const vocabulary_js_1 = require("./vocabulary.js");
 /**
- * Closest known built-in tool by edit distance (≤ 2), for a "did you mean" hint.
- * The ≤ 2 bound is deliberately tight: a suggestion is a CONFIDENCE signal (this
- * `unknown` is really a typo of a real tool), and a loose bound mis-suggests —
- * `TaskGet → Task?` (distance 3) is a real tool set, not a typo of `Task`.
+ * The wire-shape `kind` each verdict maps to. `never-available` and `unknown`
+ * predate the vocabulary and keep their meaning for existing consumers;
+ * `conditional` is the new one the two-way split could not express.
  */
-function closestTool(tool, dialect) {
-    let best = null;
-    let bestDistance = Infinity;
-    for (const known of dialect.builtinAgentTools) {
-        const d = (0, edit_distance_js_1.editDistance)(tool.toLowerCase(), known.toLowerCase());
-        if (d < bestDistance) {
-            bestDistance = d;
-            best = known;
-        }
-    }
-    return bestDistance <= 2 ? best : null;
+const TOOL_ISSUE_KIND = {
+    withheld: "never-available",
+    conditional: "conditional",
+    unrecognised: "unknown",
+    // `available` never reaches here — termIssue returns null for it.
+    available: "unknown",
+};
+/**
+ * The tool vocabulary this dialect verifies against — its declared one, else a
+ * synthesised one from the flat lists so a legacy adapter keeps working.
+ */
+function subagentToolVocabulary(dialect) {
+    return (dialect.subagentToolVocabulary ??
+        (0, vocabulary_js_1.vocabularyFromLists)(`${dialect.name} subagent tool`, `${dialect.name} adapter (no recorded capture)`, dialect.builtinAgentTools, dialect.neverAvailableTools));
 }
 /**
- * The HIGH-CONFIDENCE subset of a contract's issues — the ones safe to flag when
- * AUDITING a third-party plugin (scan / lint), where the catalog can't know
- * every tool (plugin-/MCP-provided, newer platform tools). Only two are confident:
- * a `never-available` tool (a curated denylist) and an `unknown` with a close
- * typo suggestion (`Edt → Edit`). A bare `unknown` with no near match is NOT
- * flagged here — it is more likely a tool vigiles doesn't know than a defect
- * (sweeping real plugins surfaced a 280★ plugin using `TaskCreate/TaskGet/…`
- * consistently; flagging those would be crying wolf). `compileAgent` stays strict
- * — when you author your OWN spec, every unrecognized tool is worth an error.
+ * Closest known built-in tool by edit distance (≤ 2), for a "did you mean" hint.
+ * A MESSAGE DECORATION, never a gate: whether to report is already settled by
+ * the verdict before this is called. The ≤ 2 bound stays tight because a loose
+ * bound mis-suggests — `TaskGet → Task?` is a different real tool, not a typo.
  */
-function confidentToolIssues(issues) {
-    return issues.filter((i) => i.kind === "never-available" || i.suggestion !== null);
+function closestTool(tool, dialect) {
+    return (0, vocabulary_js_1.suggest)(subagentToolVocabulary(dialect), tool);
 }
 /**
  * Verify a subagent's `disallowedTools:` BLOCK-list — the mirror of the allow
  * contract. A typo here is dangerous: you meant to block `Bash` but wrote `Bsh`,
  * so nothing is blocked and the dangerous tool stays available, silently. Returns
- * one {@link ToolIssue} per entry that's a CLOSE TYPO of a real built-in (the
- * high-confidence signal). Deliberately NOT flagged: a real built-in (it IS being
- * blocked — correct), a never-available tool (harmless to block), an MCP tool (a
- * legitimate plugin tool to block), or a bare unknown with no near match (likely
- * a plugin/MCP tool, not a typo — the cry-wolf trap). The block-list inverts the
- * allow check: never-available is fine to list, a typo is the actual defect.
+ * one {@link ToolIssue} per entry that's a CLOSE TYPO of a real tool.
+ * Deliberately NOT flagged: any name the vocabulary knows (blocking it is the
+ * point — including a withheld one, which is merely redundant), an MCP tool (a
+ * legitimate plugin tool to block), or a bare unknown with no near match.
+ *
+ * This is the ONE place a near match still gates a finding, and it is not the
+ * confidence proxy the allow-side check was rightly stripped of. On a block-list
+ * the risk inverts: an entry naming nothing is harmless UNLESS you meant a real
+ * tool and mistyped it, and "meant a real tool" is precisely what a one-character
+ * distance evidences. `disallowedTools: [Zzzz]` blocks nothing and nobody
+ * intended otherwise; `disallowedTools: [Bsh]` leaves `Bash` wide open. So the
+ * distance here is the actual semantic signal, not a stand-in for one.
  */
 function disallowedToolIssues(tools, dialect) {
-    const never = new Set(dialect.neverAvailableTools);
+    const vocab = subagentToolVocabulary(dialect);
     const issues = [];
     for (const raw of tools) {
         const tool = raw.split("(")[0].trim();
         if (tool === "" || tool === "*")
             continue;
-        if (dialect.builtinAgentTools.includes(tool))
-            continue; // legitimately blocked
-        if (never.has(tool))
-            continue; // harmless to list (already unavailable)
         if (dialect.mcpToolPattern.test(tool))
             continue; // a real plugin/MCP tool to block
-        const near = closestTool(tool, dialect);
+        if ((0, vocabulary_js_1.classify)(vocab, tool).kind !== "unrecognised")
+            continue; // a real name — blocking it is fine
+        const near = (0, vocabulary_js_1.suggest)(vocab, tool);
         if (near === null)
             continue; // bare unknown → likely a plugin tool, not a typo
         issues.push({
             tool,
+            verdict: "unrecognised",
             kind: "unknown",
             suggestion: near,
+            severity: "scored",
             message: `disallowedTools entry "${tool}" matches no real tool — it blocks nothing. Did you mean "${near}"?`,
         });
     }
@@ -80,34 +84,32 @@ function disallowedToolIssues(tools, dialect) {
  * is stripped to its base tool before checking.
  */
 function verifyToolContract(tools, dialect) {
-    const never = new Set(dialect.neverAvailableTools);
+    const vocab = subagentToolVocabulary(dialect);
     const issues = [];
     for (const raw of tools) {
         const tool = raw.split("(")[0].trim(); // strip a Tool(restriction) suffix
         if (tool === "" || tool === "*")
             continue; // "" / "*" = wildcard, inherits all
-        if (never.has(tool)) {
-            issues.push({
-                tool,
-                kind: "never-available",
-                suggestion: null,
-                message: `Tool "${tool}" is never available to a subagent — remove it from the tools list.`,
-            });
-            continue;
-        }
-        if (dialect.builtinAgentTools.includes(tool))
-            continue;
         if (dialect.mcpToolPattern.test(tool))
             continue;
-        const near = closestTool(tool, dialect);
-        const hint = near ? ` Did you mean "${near}"?` : "";
+        const verdict = (0, vocabulary_js_1.classify)(vocab, tool);
+        const issue = (0, vocabulary_js_1.termIssue)(vocab, verdict, "Tool", "the subagent never gets it");
+        if (issue === null)
+            continue;
         issues.push({
             tool,
-            kind: "unknown",
-            suggestion: near,
-            message: `Unknown tool "${tool}" — use a built-in tool (${dialect.builtinAgentTools.join(", ")}) or an MCP tool (mcp__server__tool).${hint}`,
+            verdict: verdict.kind,
+            kind: TOOL_ISSUE_KIND[verdict.kind],
+            suggestion: issue.suggestion,
+            ...(issue.condition !== undefined ? { condition: issue.condition } : {}),
+            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=tool-contract.js.map

package/dist/core/vocabulary-consistency.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The invariant that was missing when `Agent` sat in two catalogs at once.
+ *
+ * A `HarnessDialect` carries several name lists that describe the SAME
+ * vocabulary from different angles — `builtinAgentTools` (declarable),
+ * `neverAvailableTools` (dead), `sideEffectingTools` (a subset of declarable).
+ * Nothing checked that they agreed. So `Agent` could be listed as
+ * never-available while its own alias `Task` sat in the built-in catalog, and
+ * `dialect-drift.ts` could read `Agent` out of the vendor's shipped
+ * `sdk-tools.d.ts` every run, for months, without anything noticing the
+ * contradiction. The lists were consistent with nothing, including each other.
+ *
+ * These checks are cheap, total, and adapter-agnostic, so they run in the
+ * adapter conformance kit — every adapter, present and future, third-party
+ * included. A dialect that contradicts itself now fails LOUDLY at the point an
+ * author would first run the kit, instead of silently producing a confident
+ * wrong finding in someone else's repo.
+ *
+ * Deliberately NOT here: any judgement about whether a name is *correct*. This
+ * cannot tell you the platform renamed `Task` to `Agent` — only that you cannot
+ * claim both at once. Freshness against the real platform is
+ * `dialect-drift.ts`'s job; agreement between our own claims is this one's.
+ */
+import type { HarnessDialect } from "./dialect.js";
+import type { HarnessVocabulary } from "./vocabulary.js";
+/** Human-readable violations of the dialect's internal name invariants. */
+export declare function dialectVocabularyProblems(dialect: HarnessDialect): string[];
+/**
+ * When a dialect declares a vocabulary, its legacy name lists must be exactly
+ * that vocabulary's projections. This is what stops the two from drifting once
+ * both exist: a dialect can carry the richer catalog AND the flat arrays other
+ * code still reads, but it cannot let them disagree.
+ */
+export declare function vocabularyProjectionProblems(vocab: HarnessVocabulary, builtinAgentTools: readonly string[], neverAvailableTools: readonly string[]): string[];
+//# sourceMappingURL=vocabulary-consistency.d.ts.map

package/dist/core/vocabulary-consistency.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dialectVocabularyProblems = dialectVocabularyProblems;
+exports.vocabularyProjectionProblems = vocabularyProjectionProblems;
+/** Human-readable violations of the dialect's internal name invariants. */
+function dialectVocabularyProblems(dialect) {
+    const problems = [];
+    const builtin = new Set(dialect.builtinAgentTools);
+    const never = new Set(dialect.neverAvailableTools);
+    // The exact state that shipped: a name claimed as both declarable and dead.
+    for (const tool of never)
+        if (builtin.has(tool))
+            problems.push(`tool "${tool}" is in BOTH builtinAgentTools and neverAvailableTools — ` +
+                `it cannot be both declarable and never available`);
+    // A side-effecting tool outside the catalog can never be reached by
+    // `classifyToolEffect` (rule 1 only fires for names rule 2 could see), so the
+    // entry is dead weight that reads as protection.
+    for (const tool of dialect.sideEffectingTools ?? [])
+        if (!builtin.has(tool))
+            problems.push(`tool "${tool}" is in sideEffectingTools but not in builtinAgentTools — ` +
+                `the effect classification can never reach it`);
+    // A block-semantics subset that names an event the dialect doesn't fire is a
+    // rule about nothing.
+    const events = new Set(dialect.hookEvents);
+    for (const [field, list] of [
+        ["noEffectHookEvents", dialect.noEffectHookEvents ?? []],
+        [
+            "permissionDecisionHookEvents",
+            dialect.permissionDecisionHookEvents ?? [],
+        ],
+    ])
+        for (const event of list)
+            if (!events.has(event))
+                problems.push(`hook event "${event}" is in ${field} but not in hookEvents — ` +
+                    `it describes an event this dialect says never fires`);
+    return problems;
+}
+/**
+ * When a dialect declares a vocabulary, its legacy name lists must be exactly
+ * that vocabulary's projections. This is what stops the two from drifting once
+ * both exist: a dialect can carry the richer catalog AND the flat arrays other
+ * code still reads, but it cannot let them disagree.
+ */
+function vocabularyProjectionProblems(vocab, builtinAgentTools, neverAvailableTools) {
+    const problems = [];
+    const declarable = new Set(vocab.terms.filter((t) => t.status !== "withheld").map((t) => t.name));
+    const withheld = new Set(vocab.terms.filter((t) => t.status === "withheld").map((t) => t.name));
+    const diff = (label, expected, actual) => {
+        const got = new Set(actual);
+        for (const n of expected)
+            if (!got.has(n))
+                problems.push(`${label} is missing "${n}", which the vocabulary declares`);
+        for (const n of got)
+            if (!expected.has(n))
+                problems.push(`${label} has "${n}", which the vocabulary does not declare`);
+    };
+    diff("builtinAgentTools", declarable, builtinAgentTools);
+    diff("neverAvailableTools", withheld, neverAvailableTools);
+    // A conditional term with no condition cannot be reported as one — the whole
+    // reason the status exists is to quote the platform's qualifier back.
+    for (const t of vocab.terms)
+        if (t.status === "conditional" && (t.condition ?? "").trim() === "")
+            problems.push(`term "${t.name}" is conditional but states no condition — ` +
+                `a condition we cannot quote is one we cannot report`);
+    // An alias pointing at a name the vocabulary doesn't hold sends the reader
+    // somewhere that doesn't exist.
+    for (const t of vocab.terms)
+        if (t.aliasOf !== undefined &&
+            !vocab.terms.some((o) => o.name === t.aliasOf))
+            problems.push(`term "${t.name}" is an alias of "${t.aliasOf}", which this vocabulary ` +
+                `does not contain`);
+    // Two entries for one name make `classify` order-dependent.
+    const seen = new Set();
+    for (const t of vocab.terms) {
+        if (seen.has(t.name))
+            problems.push(`term "${t.name}" appears more than once in the vocabulary`);
+        seen.add(t.name);
+    }
+    return problems;
+}
+//# sourceMappingURL=vocabulary-consistency.js.map