vigiles 16.1.2 → 16.1.3

package/dist/core/vocabulary.d.ts

@@ -0,0 +1,138 @@
+/** What the platform does with a term, per the vendor's own documentation. */
+export type TermStatus = "available" | "withheld" | "conditional";
+/** One word of a harness's vocabulary, with what the platform does with it. */
+export interface VocabularyTerm {
+    readonly name: string;
+    readonly status: TermStatus;
+    /**
+     * The vendor's stated condition, near-verbatim. REQUIRED when `status` is
+     * `"conditional"` — a condition we cannot quote is a condition we cannot
+     * report, and reporting it is the whole point of the status.
+     */
+    readonly condition?: string;
+    /**
+     * The current name this term is a still-working deprecated alias of (e.g.
+     * `Task` → `Agent`, renamed in Claude Code 2.1.63). An alias is NOT a defect:
+     * the platform keeps honouring it.
+     */
+    readonly aliasOf?: string;
+}
+/** A named set of platform terms, tagged with where and when it was captured. */
+export interface HarnessVocabulary {
+    /** Which vocabulary this is — used in messages, so it must read as English. */
+    readonly kind: string;
+    /**
+     * The exact vendor artifact + version this catalog was read from, e.g.
+     * `"code.claude.com/docs/en/hooks § Hook events (claude-code 2.1.233)"`.
+     * Printed with every `unrecognised` advisory, so our staleness is visible to
+     * the person who hit it rather than only to us.
+     */
+    readonly capturedFrom: string;
+    readonly terms: readonly VocabularyTerm[];
+}
+/**
+ * What the catalog says about one name. Total — there is no absent answer, and
+ * deliberately no near-match on the `unrecognised` branch (see the module note:
+ * a distance in scope at the decision point is what produced the bugs).
+ */
+export type TermVerdict = {
+    readonly kind: "available";
+    readonly term: VocabularyTerm;
+} | {
+    readonly kind: "withheld";
+    readonly term: VocabularyTerm;
+} | {
+    readonly kind: "conditional";
+    readonly term: VocabularyTerm;
+} | {
+    readonly kind: "unrecognised";
+    readonly name: string;
+};
+/** How much weight a finding carries — the ONLY input to whether it is scored. */
+export type IssueSeverity = 
+/** A defect in the audited repo. Enters the grade. */
+"scored"
+/** True but not actionable, or a statement about vigiles. Never scored. */
+ | "advisory";
+/** Look the name up. Total: always one of the four verdicts, never null. */
+export declare function classify(vocab: HarnessVocabulary, name: string): TermVerdict;
+/**
+ * Closest catalog name within edit distance 2, else null — a MESSAGE decoration
+ * only. Never call this to decide whether to report something; the verdict has
+ * already decided that. The ≤2 bound stays tight for the reason it always was:
+ * a loose bound mis-suggests (`TaskGet → Task?` is a different real tool, not a
+ * typo). Only `available` terms are offered — suggesting a name the platform
+ * withholds would trade one dead reference for another.
+ */
+export declare function suggest(vocab: HarnessVocabulary, name: string): string | null;
+/** A vocabulary finding: the message to show and whether it counts. */
+export interface TermIssue {
+    /** Which verdict produced this — the input to every downstream policy. */
+    readonly verdict: TermVerdict["kind"];
+    readonly severity: IssueSeverity;
+    readonly message: string;
+    /** Near-match for the message only; null unless the term is unrecognised. */
+    readonly suggestion: string | null;
+    /**
+     * The vendor condition, present only for a `conditional` verdict. Carried so a
+     * report can GROUP the tools that share one condition instead of repeating the
+     * same sentence per tool — a delegating subagent legitimately declares eight of
+     * them, and eight identical paragraphs is noise from a tool that sells itself
+     * on not crying wolf.
+     */
+    readonly condition?: string;
+}
+/**
+ * Turn a verdict into the finding to report, or null when there is nothing to
+ * say. The severity is decided HERE, once, from the verdict — callers never
+ * invent their own policy, which is what let `scan` and `lint` drift apart from
+ * `compileAgent` before.
+ *
+ * `noun` names the thing in the message ("hook event" / "tool"); `subject`
+ * describes what listing it does, e.g. "a hook here never fires".
+ */
+export declare function termIssue(vocab: HarnessVocabulary, verdict: TermVerdict, noun: string, deadConsequence: string): TermIssue | null;
+/**
+ * The issues that count toward a grade. Replaces the per-check
+ * `confidentToolIssues` / `confidentHookEventIssues` helpers, which asked "is
+ * there a near match?" — a question about spelling, answered by a helper each
+ * caller had to remember to apply and which `compileAgent` did not, so `scan`,
+ * `lint` and authoring could disagree about which issues were real. Severity now
+ * travels ON the issue, decided once in {@link termIssue}, so the split is the
+ * same wherever it is taken.
+ */
+export declare function scoredIssues<T extends {
+    readonly severity: IssueSeverity;
+}>(issues: readonly T[]): T[];
+/**
+ * The issues that are surfaced but never scored — `conditional` tools and any
+ * name newer than our capture. Kept out of the grade on purpose: vigiles's own
+ * staleness must not cost someone a letter.
+ */
+export declare function advisoryIssues<T extends {
+    readonly severity: IssueSeverity;
+}>(issues: readonly T[]): T[];
+/**
+ * The issues an AUTHORING path treats as errors — everything except
+ * `conditional`. Authoring is a CLOSED world: you are writing this spec now,
+ * against the vigiles you have, so an unrecognised name is a typo worth stopping
+ * for. Auditing is an OPEN world: someone else wrote the file, possibly against
+ * a newer platform, so there the same verdict is only an advisory.
+ *
+ * `conditional` is an error in NEITHER. The tool is real and declaring it is
+ * correct; erroring on it is exactly what told delegating subagents to drop
+ * `Agent`, and what made `tools: Agent, Read, Bash` — a worked example in the
+ * vendor's own docs — fail to compile.
+ */
+export declare function authoringIssues<T extends {
+    readonly verdict: TermVerdict["kind"];
+}>(issues: readonly T[]): T[];
+/**
+ * Build a vocabulary from a dialect that predates this module — `available` from
+ * its built-in catalog, `withheld` from its never-available list. A dialect on
+ * the legacy shape keeps working and its unknowns become `unrecognised`
+ * ADVISORIES rather than silence, which is the honest reading: a catalog with no
+ * recorded capture cannot claim a name is invalid.
+ */
+export declare function vocabularyFromLists(kind: string, capturedFrom: string, available: readonly string[], withheld?: readonly string[]): HarnessVocabulary;
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/core/vocabulary.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classify = classify;
+exports.suggest = suggest;
+exports.termIssue = termIssue;
+exports.scoredIssues = scoredIssues;
+exports.advisoryIssues = advisoryIssues;
+exports.authoringIssues = authoringIssues;
+exports.vocabularyFromLists = vocabularyFromLists;
+/**
+ * HarnessVocabulary — the platform's own words, with a STATUS per word.
+ *
+ * The three vocabulary checks (`hook-events`, `subagent-tool-contract`, and the
+ * `disallowedTools:` mirror) used to model a harness's vocabulary as two
+ * hand-kept arrays — "these names are fine", "these names are dead" — and then
+ * decide what to SAY about a name in neither by its EDIT DISTANCE to the first
+ * array. That is the defect this module exists to remove, and it failed in both
+ * directions at once (measured against the vendor docs, 2026-08-17):
+ *
+ *  - FALSE ACCUSATION. `Setup` is a documented Claude Code hook event. It was
+ *    reported as "a hook here never fires … Did you mean Stop?" — and the
+ *    suggested repair rewires a one-shot setup hook onto every turn's Stop.
+ *    It was caught for one reason only: `setup` happens to sit at edit distance
+ *    2 from `stop`.
+ *  - SILENCE. Of the 31 events the vendor documents, the old catalog held 9.
+ *    The other 22 were not "accepted" — they were unrecognised and >2 away from
+ *    any known name, so nothing was said. `SubagentStart` and `PostCompact` sat
+ *    at distance 3: one character from becoming the next `Setup`.
+ *
+ * So which of the two a valid name got — an accusation or silence — was decided
+ * by spelling luck. Neither is a verdict, and a tool whose pitch is precision
+ * cannot ship either as its answer to "I don't know this word".
+ *
+ * The fix is not a longer array. It is to stop asking "is this string in my
+ * list?" (a boolean, which has no room for "I don't know") and start asking
+ * "what does my catalog SAY about this string?" — a {@link TermVerdict}, which
+ * has four answers because the vendor's own documentation distinguishes four:
+ *
+ *  - `available`     — the platform provides it.
+ *  - `withheld`      — the platform removes it, unconditionally. A real defect.
+ *  - `conditional`   — the platform removes it only under a STATED condition
+ *                      (`Agent` at the depth limit; `ExitPlanMode` unless
+ *                      `permissionMode: plan`; every non-background built-in when
+ *                      the subagent runs in the background). vigiles cannot see
+ *                      the condition, so it must not assert — it reports the
+ *                      condition and stops.
+ *  - `unrecognised`  — not in the catalog. This is a statement about VIGILES,
+ *                      not about the repo being audited, and the message says so.
+ *
+ * THE THIRD OPTION. `unrecognised` is why this module exists. Silence reads as
+ * approval and hides our own staleness; an error blames the user for our gap.
+ * The honest third answer is an ADVISORY that names vigiles as the possibly-stale
+ * party and prints the capture the catalog came from. It is surfaced and it is
+ * never scored, so a name newer than our capture can never cost anyone a grade.
+ *
+ * WHY THE DISTANCE IS NOT ON THE VERDICT. {@link TermVerdict}'s `unrecognised`
+ * branch carries no near-match. A caller therefore CANNOT write
+ * `if (nearest) report()` — the shape that produced both bugs — because at the
+ * point where the report/skip decision is made, no distance is in scope.
+ * {@link suggest} exists solely to decorate a message that is already being
+ * emitted, and is called from the message builder, not from a branch.
+ *
+ * FAILING LOUDLY. `classify` is total: every name returns one of four cases, so
+ * a `switch` that forgets one is a `tsc` error via the `never` exhaustiveness
+ * check in {@link termIssue}. There is no `null`/`undefined` return to ignore.
+ *
+ * GOING STALE. It will. `capturedFrom` records the exact vendor artifact and
+ * version each catalog was read from, and every name we do not hold prints it.
+ * That is the difference from an ordinary allowlist: this one reports its own
+ * age at the moment it is out of date, rather than silently approving the word
+ * it has never heard of.
+ */
+const edit_distance_js_1 = require("./edit-distance.js");
+/** Look the name up. Total: always one of the four verdicts, never null. */
+function classify(vocab, name) {
+    const term = vocab.terms.find((t) => t.name === name);
+    if (term === undefined)
+        return { kind: "unrecognised", name };
+    switch (term.status) {
+        case "available":
+            return { kind: "available", term };
+        case "withheld":
+            return { kind: "withheld", term };
+        case "conditional":
+            return { kind: "conditional", term };
+    }
+}
+/**
+ * Closest catalog name within edit distance 2, else null — a MESSAGE decoration
+ * only. Never call this to decide whether to report something; the verdict has
+ * already decided that. The ≤2 bound stays tight for the reason it always was:
+ * a loose bound mis-suggests (`TaskGet → Task?` is a different real tool, not a
+ * typo). Only `available` terms are offered — suggesting a name the platform
+ * withholds would trade one dead reference for another.
+ */
+function suggest(vocab, name) {
+    const near = nearest(vocab, name);
+    return near !== null && near.distance <= SUGGEST_MAX ? near.name : null;
+}
+/** How far a hint may reach. Beyond this a "did you mean" mis-suggests. */
+const SUGGEST_MAX = 2;
+/**
+ * How close an unrecognised name must be to a real one before vigiles will call
+ * it a TYPO and put it in the grade, rather than treating it as a name it simply
+ * does not know.
+ *
+ * MEASURED, not assumed — and the measurement is the whole reason the old check
+ * failed. Over every pair of distinct names in the two shipped Claude Code
+ * vocabularies (465 hook-event pairs, 741 subagent-tool pairs):
+ *
+ *   distance 1 : 0 pairs of the 1,206
+ *   distance 2 : exactly 1 pair in each — `Setup`/`Stop` and `Bash`/`Task`
+ *
+ * So the vendor does not ship two real names one edit apart, which makes
+ * distance 1 strong evidence of a mistyped name. Distance 2, on the other hand,
+ * is exactly where two genuinely different real names DO collide — and the one
+ * event-pair that collides there is the bug itself: the old code used ≤2 as its
+ * threshold and therefore accused `Setup`, a real event, of being a typo of
+ * `Stop`. The old bound was not merely too loose, it was set precisely at the
+ * width of the collision.
+ *
+ * Hence: distance 1 is scored, distance 2 still earns a did-you-mean but stays
+ * advisory. RESIDUAL RISK, stated plainly: if the vendor ever ships a name one
+ * edit from an existing one, it will be scored as a typo until the catalog is
+ * updated. Zero of 1,206 current pairs are that close, and `dialect-drift` plus
+ * the conformance invariants are what surface the catalog falling behind.
+ */
+const TYPO_MAX = 1;
+/** Closest catalog name and its distance, or null when the vocabulary is empty. */
+function nearest(vocab, name) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const t of vocab.terms) {
+        if (t.status === "withheld")
+            continue;
+        const d = (0, edit_distance_js_1.editDistance)(name.toLowerCase(), t.name.toLowerCase());
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = t.name;
+        }
+    }
+    return best === null ? null : { name: best, distance: bestDistance };
+}
+/**
+ * Turn a verdict into the finding to report, or null when there is nothing to
+ * say. The severity is decided HERE, once, from the verdict — callers never
+ * invent their own policy, which is what let `scan` and `lint` drift apart from
+ * `compileAgent` before.
+ *
+ * `noun` names the thing in the message ("hook event" / "tool"); `subject`
+ * describes what listing it does, e.g. "a hook here never fires".
+ */
+function termIssue(vocab, verdict, noun, deadConsequence) {
+    switch (verdict.kind) {
+        case "available":
+            return null;
+        case "conditional": {
+            const alias = verdict.term.aliasOf !== undefined
+                ? ` "${verdict.term.name}" is a still-supported deprecated alias of "${verdict.term.aliasOf}".`
+                : "";
+            return {
+                verdict: "conditional",
+                severity: "advisory",
+                suggestion: null,
+                condition: verdict.term.condition,
+                message: `${noun} "${verdict.term.name}" is available to a subagent, but the platform ` +
+                    `removes it ${verdict.term.condition ?? "under a documented condition"}. ` +
+                    `vigiles cannot see that condition from the file, so this is a note, not a defect.${alias}`,
+            };
+        }
+        case "withheld":
+            return {
+                verdict: "withheld",
+                severity: "scored",
+                suggestion: null,
+                message: `${noun} "${verdict.term.name}" is never available to a subagent — remove it from the tools list.`,
+            };
+        case "unrecognised": {
+            const near = nearest(vocab, verdict.name);
+            const suggestion = near !== null && near.distance <= SUGGEST_MAX ? near.name : null;
+            // One edit from a real name, and no two real names are that close (see
+            // TYPO_MAX): this is a mistyped name, and it is dead in the repo now.
+            if (near !== null && near.distance <= TYPO_MAX)
+                return {
+                    verdict: "unrecognised",
+                    severity: "scored",
+                    suggestion,
+                    message: `${noun} "${verdict.name}" matches no known name — ${deadConsequence}. ` +
+                        `Did you mean "${near.name}"?`,
+                };
+            const hint = suggestion !== null ? ` Did you mean "${suggestion}"?` : "";
+            return {
+                verdict: "unrecognised",
+                severity: "advisory",
+                suggestion,
+                message: `${noun} "${verdict.name}" is not in vigiles's ${vocab.kind} catalog ` +
+                    `(captured from ${vocab.capturedFrom}). If it is newer than that capture, or ` +
+                    `custom to your harness, vigiles is out of date — not your config. ` +
+                    `If it is a typo, ${deadConsequence}.${hint}`,
+            };
+        }
+        default: {
+            // Exhaustiveness: a new verdict kind with no branch is a tsc error here,
+            // so a future status cannot be silently dropped on the floor.
+            const never = verdict;
+            return never;
+        }
+    }
+}
+/**
+ * The issues that count toward a grade. Replaces the per-check
+ * `confidentToolIssues` / `confidentHookEventIssues` helpers, which asked "is
+ * there a near match?" — a question about spelling, answered by a helper each
+ * caller had to remember to apply and which `compileAgent` did not, so `scan`,
+ * `lint` and authoring could disagree about which issues were real. Severity now
+ * travels ON the issue, decided once in {@link termIssue}, so the split is the
+ * same wherever it is taken.
+ */
+function scoredIssues(issues) {
+    return issues.filter((i) => i.severity === "scored");
+}
+/**
+ * The issues that are surfaced but never scored — `conditional` tools and any
+ * name newer than our capture. Kept out of the grade on purpose: vigiles's own
+ * staleness must not cost someone a letter.
+ */
+function advisoryIssues(issues) {
+    return issues.filter((i) => i.severity === "advisory");
+}
+/**
+ * The issues an AUTHORING path treats as errors — everything except
+ * `conditional`. Authoring is a CLOSED world: you are writing this spec now,
+ * against the vigiles you have, so an unrecognised name is a typo worth stopping
+ * for. Auditing is an OPEN world: someone else wrote the file, possibly against
+ * a newer platform, so there the same verdict is only an advisory.
+ *
+ * `conditional` is an error in NEITHER. The tool is real and declaring it is
+ * correct; erroring on it is exactly what told delegating subagents to drop
+ * `Agent`, and what made `tools: Agent, Read, Bash` — a worked example in the
+ * vendor's own docs — fail to compile.
+ */
+function authoringIssues(issues) {
+    return issues.filter((i) => i.verdict !== "conditional");
+}
+/**
+ * Build a vocabulary from a dialect that predates this module — `available` from
+ * its built-in catalog, `withheld` from its never-available list. A dialect on
+ * the legacy shape keeps working and its unknowns become `unrecognised`
+ * ADVISORIES rather than silence, which is the honest reading: a catalog with no
+ * recorded capture cannot claim a name is invalid.
+ */
+function vocabularyFromLists(kind, capturedFrom, available, withheld = []) {
+    return {
+        kind,
+        capturedFrom,
+        terms: [
+            ...available.map((name) => ({ name, status: "available" })),
+            ...withheld.map((name) => ({ name, status: "withheld" })),
+        ],
+    };
+}
+//# sourceMappingURL=vocabulary.js.map

package/dist/scan-core.d.ts

@@ -1,3 +1,4 @@
+import type { HookEventIssue } from "./core/hook-events.js";
 import { type DescriptionOverlap } from "./core/description-overlap.js";
 import { type DescriptionBudgetIssue } from "./core/skill-description-budget.js";
 import type { SkillRefSource } from "./skill-refs.js";
@@ -6,7 +7,7 @@ import type { HarnessDialect } from "./core/dialect.js";
 import type { HookRegistration } from "./core/hook-normalize.js";
 import type { HookScriptEntry } from "./core/hook-block-ineffective.js";
 import type { HookMatcherEntry } from "./core/hook-matcher.js";
-import type { ScanSkill, ScanAgent, ScanHook, FrontmatterIssue, FrontmatterValueIssue, FrontmatterParseIssue, ScanTrifectaFinding, ScanSkillResourceFinding, ScanSkillFenceFinding, ScanDelegationFinding } from "./scan.js";
+import type { ScanSkill, ScanAgent, ScanHook, FrontmatterIssue, FrontmatterValueIssue, FrontmatterParseIssue, ScanTrifectaFinding, ScanSkillResourceFinding, ScanSkillFenceFinding, ScanDelegationFinding, VocabularyNote } from "./scan.js";
 /**
  * Per-kind surface classifiers, built from the harness `PluginLayout`'s
  * `skillDir`/`agentDir`/`commandDir` — so adding a harness whose subagents live
@@ -201,4 +202,10 @@ export declare function summarizePurity(agents: readonly ScanAgent[]): {
     bounded: number;
     unrestricted: number;
 };
+/**
+ * Gather the advisory half of the vocabulary findings for the report. Kept in
+ * one place so hook events and subagent tools present identically — the two used
+ * to answer the same question with different policies.
+ */
+export declare function collectVocabularyNotes(hookEventIssues: readonly HookEventIssue[], agents: readonly ScanAgent[]): VocabularyNote[];
 //# sourceMappingURL=scan-core.d.ts.map

package/dist/scan-core.js

@@ -20,6 +20,7 @@ exports.collectDelegationTrifecta = collectDelegationTrifecta;
 exports.collectHookBlockEntries = collectHookBlockEntries;
 exports.collectHookMatchers = collectHookMatchers;
 exports.summarizePurity = summarizePurity;
+exports.collectVocabularyNotes = collectVocabularyNotes;
 /**
  * scan-core — the PURE, NODE-FREE detector runtime behind `vigiles audit`.
  *
@@ -438,6 +439,9 @@ ctx) {
         // including every side-effecting one — pass the wildcard sentinel so
         // effectSurface correctly classifies it as `"unrestricted"`.
         const surface = (0, effects_js_1.effectSurface)(tools ?? ["*"], dialect);
+        // Classify ONCE; the scored and advisory halves are two views of one result,
+        // so they cannot disagree about what the vocabulary said.
+        const vocabIssues = tools ? (0, tool_contract_js_1.verifyToolContract)(tools, dialect) : [];
         out.push({
             name: (0, posix_path_js_1.basename)(path, ".md"),
             path: ctx
@@ -445,12 +449,16 @@ ctx) {
                 : path,
             tools,
             // Cross-reference the declared rail against the dialect catalog — the moat.
-            // Auditing third-party plugins → only the HIGH-CONFIDENCE issues (never-
-            // available + close typos); a bare unrecognized tool is likely plugin/MCP-
-            // provided, not a defect (the TaskCreate/TaskGet lesson). See tool-contract.ts.
-            toolIssues: tools
-                ? (0, tool_contract_js_1.confidentToolIssues)((0, tool_contract_js_1.verifyToolContract)(tools, dialect))
-                : [],
+            // The SCORED half only: a tool the platform withholds unconditionally, or a
+            // name one edit from a real one (no two real names are that close, so that
+            // is a typo). Everything else the vocabulary has an opinion about goes to
+            // `toolNotes` — surfaced, never graded. See core/vocabulary.ts.
+            toolIssues: tools ? (0, tool_contract_js_1.scoredIssues)(vocabIssues) : [],
+            // Advisory: a real tool the platform withholds only under a condition
+            // vigiles cannot see (`Agent` at the depth limit), and a name that is
+            // simply not in our capture — which may mean the catalog is stale, not
+            // that the contract is wrong.
+            toolNotes: tools ? (0, tool_contract_js_1.advisoryIssues)(vocabIssues) : [],
             // The MCP half of the moat: an `mcp__server__tool` whose server isn't in the
             // plugin's declared set can't resolve. High-precision (gated on a declared
             // set, built-ins allowlisted, plugin-namespaced form skipped). See mcp-tool.ts.
@@ -879,4 +887,54 @@ function summarizePurity(agents) {
         return acc;
     }, { pure: 0, bounded: 0, unrestricted: 0 });
 }
+// ---------------------------------------------------------------------------
+// Vocabulary notes — the advisory half of the findings
+// ---------------------------------------------------------------------------
+// These live HERE, not in scan.ts, because both engines produce them and only
+// this module is node-free. Importing them from scan.ts pulled the node-only
+// graph (down to `@ast-grep/napi`'s native .node binding) into the browser
+// bundle and broke the site build — the gate that owns this invariant.
+/**
+ * Gather the advisory half of the vocabulary findings for the report. Kept in
+ * one place so hook events and subagent tools present identically — the two used
+ * to answer the same question with different policies.
+ */
+function collectVocabularyNotes(hookEventIssues, agents) {
+    return [
+        ...(0, tool_contract_js_1.advisoryIssues)(hookEventIssues).map((i) => ({
+            where: `hook event "${i.event}"`,
+            message: i.message,
+        })),
+        ...agents.flatMap((a) => groupAgentToolNotes(a)),
+    ];
+}
+/**
+ * One agent's advisory tool notes, with the `conditional` ones GROUPED by the
+ * condition they share. A delegating subagent legitimately declares eight
+ * foreground-only tools; printing the same sentence eight times is noise, and
+ * noise is what this whole change exists to stop producing. Unrecognised names
+ * stay one-per-tool — each carries its own did-you-mean.
+ */
+function groupAgentToolNotes(agent) {
+    const notes = (0, tool_contract_js_1.advisoryIssues)(agent.toolNotes ?? []);
+    const byCondition = new Map();
+    const out = [];
+    for (const i of notes) {
+        if (i.verdict === "conditional" && i.condition !== undefined) {
+            const at = byCondition.get(i.condition) ?? [];
+            at.push(i.tool);
+            byCondition.set(i.condition, at);
+            continue;
+        }
+        out.push({ where: agent.path, message: i.message });
+    }
+    for (const [condition, tools] of byCondition)
+        out.push({
+            where: agent.path,
+            message: `${tools.join(", ")} ${tools.length === 1 ? "is a real tool" : "are real tools"}, ` +
+                `but the platform removes ${tools.length === 1 ? "it" : "them"} ${condition}. ` +
+                `vigiles cannot see that condition from the file, so this is a note, not a defect.`,
+        });
+    return out;
+}
 //# sourceMappingURL=scan-core.js.map

package/dist/scan-files.js

@@ -57,6 +57,7 @@ const scan_core_js_1 = require("./scan-core.js");
 // Zero imports of its own — pure string work, safe in the browser engine.
 const skill_refs_js_1 = require("./skill-refs.js");
 const merge_conflict_js_1 = require("./core/merge-conflict.js");
+const scan_core_js_2 = require("./scan-core.js");
 /**
  * The synthetic absolute root every path in a browser scan resolves against. A
  * pure, deterministic string (never `process.cwd()`), so `join`/`relative` stay
@@ -469,7 +470,8 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
     const hookRegs = (0, hook_normalize_js_1.normalizeHooks)(loaded.settings.hooks);
     const { hooks, inline, manual } = (0, scan_core_js_1.scanHooks)(hookRegs, exports.BROWSER_ROOT, lay.pluginRootToken, exists);
     const eventNames = (0, hook_normalize_js_1.hookEventNames)(loaded.settings.hooks);
-    const hookEventIssues = (0, hook_events_js_1.confidentHookEventIssues)((0, hook_events_js_1.verifyHookEvents)(eventNames, dialect));
+    const allHookEventIssues = (0, hook_events_js_1.verifyHookEvents)(eventNames, dialect);
+    const hookEventIssues = (0, hook_events_js_1.scoredIssues)(allHookEventIssues);
     const instructions = loaded.files[lay.instructionFile] !== undefined
         ? {
             file: lay.instructionFile,
@@ -528,6 +530,7 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
             sources: loaded.sources,
         })).map(skill_refs_js_1.formatSkillRefIssue),
         hookEventIssues,
+        vocabularyNotes: (0, scan_core_js_2.collectVocabularyNotes)(allHookEventIssues, agents),
         frontmatterIssues: remap((0, scan_core_js_1.frontmatterIssuesFor)(loaded.files, cls)),
         frontmatterValueIssues: remap((0, scan_core_js_1.frontmatterValueIssuesFor)(loaded.files, cls)),
         skillMetaIssues: remap((0, scan_core_js_1.skillMetaIssuesFor)(loaded.files, cls)),

package/dist/scan.d.ts

@@ -78,6 +78,12 @@ export interface ScanAgent {
     readonly toolIssues: readonly ToolIssue[];
     /** MCP tool entries naming a server the plugin doesn't declare (can't resolve). */
     readonly mcpToolIssues: readonly McpToolIssue[];
+    /**
+     * ADVISORY tool findings — a real tool withheld only under a condition vigiles
+     * cannot see, or a name not in its capture. Surfaced via `vocabularyNotes`,
+     * never scored. Optional: absence is not a claim of zero.
+     */
+    readonly toolNotes?: readonly ToolIssue[];
     /** `disallowedTools:` block-list entries that are typos of a real tool (block nothing). */
     readonly disallowedToolIssues: readonly ToolIssue[];
     /**
@@ -102,6 +108,12 @@ export interface ScanAgent {
     readonly trifecta: TrifectaFinding | null;
 }
 /** A lethal-trifecta finding tagged with the surface (subagent/skill) that holds it. */
+/** One advisory vocabulary finding, tagged with the surface that carries it. */
+export interface VocabularyNote {
+    /** Where it was found — a hook event key, or an agent's path. */
+    readonly where: string;
+    readonly message: string;
+}
 export interface ScanTrifectaFinding {
     readonly path: string;
     readonly kind: "subagent" | "skill";
@@ -218,6 +230,18 @@ export interface ScanReport {
     readonly skillRefIssues?: readonly string[];
     /** Hooks registered under an event name the harness doesn't define (typo / dead). */
     readonly hookEventIssues: readonly HookEventIssue[];
+    /**
+     * ADVISORY vocabulary findings — names vigiles could not confirm, and real
+     * names the platform withholds only under a condition it cannot see. Surfaced
+     * and NEVER scored, which is the point: the two failure modes this replaced
+     * were silence (which reads as approval and hides vigiles's own staleness) and
+     * an error (which blames the user for our gap). Neither is a verdict, so these
+     * get a third channel instead of a grade.
+     *
+     * OPTIONAL because absence is not a claim: a producer predating this field
+     * reports nothing rather than reporting zero.
+     */
+    readonly vocabularyNotes?: readonly VocabularyNote[];
     /** Skills/agents missing a required frontmatter field (name; agents also description). */
     readonly frontmatterIssues: readonly FrontmatterIssue[];
     /** Agent frontmatter fields with an invalid value (a typo of a real model/color). */

package/dist/scan.js

@@ -153,7 +153,8 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
     // object keys only and returns [] for an array. We don't interpret a format we
     // don't own.
     const eventNames = (0, hook_normalize_js_1.hookEventNames)(loaded.settings.hooks);
-    const hookEventIssues = (0, hook_events_js_1.confidentHookEventIssues)((0, hook_events_js_1.verifyHookEvents)(eventNames, dialect));
+    const allHookEventIssues = (0, hook_events_js_1.verifyHookEvents)(eventNames, dialect);
+    const hookEventIssues = (0, hook_events_js_1.scoredIssues)(allHookEventIssues);
     const instructions = loaded.files[lay.instructionFile] !== undefined
         ? {
             file: lay.instructionFile,
@@ -211,6 +212,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
             sources: loaded.sources,
         })).map(skill_refs_js_1.formatSkillRefIssue),
         hookEventIssues,
+        vocabularyNotes: (0, scan_core_js_1.collectVocabularyNotes)(allHookEventIssues, agents),
         frontmatterIssues: remap((0, scan_core_js_1.frontmatterIssuesFor)(loaded.files, cls)),
         frontmatterValueIssues: remap((0, scan_core_js_1.frontmatterValueIssuesFor)(loaded.files, cls)),
         skillMetaIssues: remap((0, scan_core_js_1.skillMetaIssuesFor)(loaded.files, cls)),
@@ -468,6 +470,11 @@ function formatScanReport(r) {
     out.push(...section("Hooks", hookLines, r.hooks.length + r.inlineHooks));
     out.push(...section("Broken references", r.danglingRefs.map((ref) => `  ✗ ${ref} (referenced but MISSING)`)));
     out.push(...section("Hook events", r.hookEventIssues.map((i) => `  ✗ ${i.message}`)));
+    // Advisory, never scored — a name vigiles cannot confirm, or a real one the
+    // platform withholds only under a condition it cannot see. Printed with `·`
+    // rather than `✗` so it reads as a note about vigiles's knowledge, not a
+    // defect in the repo being audited.
+    out.push(...section("Vocabulary notes (advisory, not graded)", (r.vocabularyNotes ?? []).map((n) => `  · ${n.where}: ${n.message}`)));
     out.push(...section("Frontmatter", [
         ...r.frontmatterIssues.map((i) => `  ✗ ${i.message}`),
         ...r.frontmatterValueIssues.map((i) => `  ✗ ${i.message}`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "16.1.2",
+  "version": "16.1.3",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",