vigiles 16.1.1 → 16.1.3

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

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