vigiles 5.0.1 → 5.2.0

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

@@ -0,0 +1,50 @@
+/**
+ * MCP-tool resolution — the cross-referencing moat ("valid is not true") applied
+ * to an MCP tool reference's SERVER. A contract that lists `mcp__linear__search`
+ * names a server `linear`; if the plugin declares its own MCP servers (a
+ * `.mcp.json` / manifest `mcpServers` block) and `linear` isn't among them, the
+ * tool can't resolve — a dead contract entry. This completes the tool moat:
+ * `subagent-tool-contract` (tool-contract.ts) verifies BUILT-IN tools but passes
+ * ANY `mcp__*` token unchecked; this verifies the MCP half.
+ *
+ * Calibrated HIGH-PRECISION — three guards, each learned from a real plugin in
+ * the mid-2026 sweep (research/plugin-structural-findings.md):
+ *
+ * 1. GATE on a declared set. Only flag when the plugin SHIPS a `mcpServers`
+ *    declaration (a non-empty `declaredServers`). A plugin that declares no
+ *    servers reaches user-global / project-level ones (the normal pattern —
+ *    ananddtyagi's agents reference `mcp__ide__*` with no `.mcp.json`), so
+ *    flagging there would cry wolf. No declared set → return nothing.
+ * 2. ALLOWLIST built-ins. A harness-provided server (`dialect.knownMcpServers`,
+ *    e.g. Claude Code's `ide`) is available without a declaration — never flag it.
+ * 3. SKIP the plugin-namespaced form. Claude Code rewrites a plugin's own MCP
+ *    tool to `mcp__plugin_<plugin>_<server>__<tool>` (observed on han's
+ *    playwright-mcp: `mcp__plugin_playwright-mcp_playwright__…`). The plugin /
+ *    server segments are joined with single underscores and are ambiguous to
+ *    split, and the ref is by construction the plugin's OWN server — so we don't
+ *    interpret it (parsing it would be a false-positive factory).
+ *
+ * Pure + ONE detector reused by `scan` + the `mcp-tool-resolves` lint rule
+ * (one-detector-no-drift). The dialect is injected (core ⊄ adapter).
+ */
+import type { HarnessDialect } from "./dialect.js";
+export interface McpToolIssue {
+    readonly tool: string;
+    readonly server: string;
+    readonly message: string;
+}
+/**
+ * The server segment of a direct `mcp__<server>__<tool>` reference, or null when
+ * the token isn't a direct MCP tool we resolve: a non-MCP tool, or the
+ * plugin-namespaced `mcp__plugin_…__…` form (guard 3 — deliberately skipped).
+ * A `Tool(restriction)` suffix is stripped first.
+ */
+export declare function mcpToolServer(raw: string, dialect: HarnessDialect): string | null;
+/**
+ * Verify the MCP tool references in a contract against the plugin's declared MCP
+ * servers. Returns one {@link McpToolIssue} per direct `mcp__<server>__<tool>`
+ * whose server is neither declared nor a known built-in. Returns `[]` when no
+ * servers are declared (guard 1 — we can't know the resolvable set).
+ */
+export declare function verifyMcpToolServers(tools: readonly string[], declaredServers: readonly string[], dialect: HarnessDialect): McpToolIssue[];
+//# sourceMappingURL=mcp-tool.d.ts.map

package/dist/core/mcp-tool.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpToolServer = mcpToolServer;
+exports.verifyMcpToolServers = verifyMcpToolServers;
+/**
+ * The server segment of a direct `mcp__<server>__<tool>` reference, or null when
+ * the token isn't a direct MCP tool we resolve: a non-MCP tool, or the
+ * plugin-namespaced `mcp__plugin_…__…` form (guard 3 — deliberately skipped).
+ * A `Tool(restriction)` suffix is stripped first.
+ */
+function mcpToolServer(raw, dialect) {
+    const tool = raw.split("(")[0].trim();
+    if (!dialect.mcpToolPattern.test(tool))
+        return null;
+    // Non-greedy first segment after `mcp__`, up to the next `__`.
+    const m = /^mcp__(.+?)__/.exec(tool);
+    if (!m)
+        return null;
+    const server = m[1];
+    // Guard 3: the plugin-namespaced form references the plugin's OWN server under
+    // an ambiguous single-underscore join — don't try to split it, don't flag it.
+    if (server.startsWith("plugin_"))
+        return null;
+    return server;
+}
+/**
+ * Verify the MCP tool references in a contract against the plugin's declared MCP
+ * servers. Returns one {@link McpToolIssue} per direct `mcp__<server>__<tool>`
+ * whose server is neither declared nor a known built-in. Returns `[]` when no
+ * servers are declared (guard 1 — we can't know the resolvable set).
+ */
+function verifyMcpToolServers(tools, declaredServers, dialect) {
+    // Guard 1: no declared set → the plugin relies on global/project servers; we
+    // can't tell a dead reference from a legitimate global one. Flag nothing.
+    if (declaredServers.length === 0)
+        return [];
+    const known = new Set([
+        ...declaredServers,
+        ...(dialect.knownMcpServers ?? []),
+    ]);
+    const issues = [];
+    const seen = new Set();
+    for (const raw of tools) {
+        const server = mcpToolServer(raw, dialect);
+        if (server === null)
+            continue; // not a direct MCP tool / plugin-namespaced
+        if (known.has(server))
+            continue;
+        const tool = raw.split("(")[0].trim();
+        if (seen.has(tool))
+            continue; // de-dupe a repeated entry
+        seen.add(tool);
+        issues.push({
+            tool,
+            server,
+            message: `MCP tool "${tool}" references server "${server}", which the plugin doesn't declare (declared: ${declaredServers.join(", ")}) — the tool can't resolve.`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=mcp-tool.js.map

package/dist/core/orphans.js

@@ -35,6 +35,25 @@ const DEFAULT_IGNORE = [
  * that nothing else links to but is not rot.
  */
 const DISABLE_RE = /<!--\s*vigiles-disable\s+orphan-docs\s*-->/;
+/**
+ * Files the HARNESS loads directly — an instruction file (`CLAUDE.md` /
+ * `AGENTS.md`), a skill (`SKILL.md`), a subagent (`agents/*.md`), or a slash
+ * command (`commands/*.md`) — are load-bearing by their NAME/LOCATION, not
+ * because another `.md` links to them. They are categorically NOT docs, so they
+ * are never orphans, even if a project broadens `orphans.include` to scan the
+ * whole repo. (They are still scanned as REFERENCERS, so a real doc that only
+ * a CLAUDE.md links to is still credited — this exemption only removes them from
+ * the orphan-CANDIDATE set.)
+ */
+function isHarnessLoadedFile(path) {
+    const norm = normalizePath(path);
+    const base = norm.slice(norm.lastIndexOf("/") + 1);
+    if (base === "CLAUDE.md" || base === "AGENTS.md" || base === "SKILL.md") {
+        return true;
+    }
+    // Subagent / slash-command surfaces the harness enumerates by directory.
+    return /(^|\/)(agents|commands)\//.test(norm);
+}
 // Match markdown links ](path.md) or ](path.md#anchor)
 const LINK_RE = /\]\(([^)\s]+\.md)(?:#[^)]*)?\)/g;
 // Match backtick code spans wrapping a path ending in .md
@@ -56,6 +75,8 @@ function collectDocs(basePath, include, ignore) {
     const docs = new Set();
     for (const pattern of include) {
         for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore: [...ignore] })) {
+            if (isHarnessLoadedFile(p))
+                continue; // instruction files are never orphans
             if (isOrphanExempt((0, node_path_1.resolve)(basePath, p)))
                 continue;
             docs.add(normalizePath(p));

package/dist/core/spec.d.ts

@@ -120,6 +120,12 @@ export type VerifiedCmd = string & {
 export type VerifiedRef = string & {
     readonly [__brand]: "VerifiedRef";
 };
+export type VerifiedDir = string & {
+    readonly [__brand]: "VerifiedDir";
+};
+export type VerifiedGlob = string & {
+    readonly [__brand]: "VerifiedGlob";
+};
 /** A typed file reference — verified at compile time. */
 export interface FileRef {
     readonly _ref: "file";
@@ -141,7 +147,17 @@ export interface SymbolRef {
     readonly file: VerifiedPath;
     readonly symbol: string;
 }
-export type Ref = FileRef | CmdRef | SkillRef | SymbolRef;
+/** A typed directory reference — verified to exist AND be a directory. */
+export interface DirRef {
+    readonly _ref: "dir";
+    readonly path: VerifiedDir;
+}
+/** A typed glob reference — verified to match at least one path. */
+export interface GlobRef {
+    readonly _ref: "glob";
+    readonly pattern: VerifiedGlob;
+}
+export type Ref = FileRef | CmdRef | SkillRef | SymbolRef | DirRef | GlobRef;
 /**
  * Reference a file path — verified to exist at compile time.
  * When generated types are present, narrowed to known project files.
@@ -164,7 +180,33 @@ export declare function symbol(file: NoInfer<StrictFile>, name: string): SymbolR
  * Compiles to a markdown link: [skill name](path)
  */
 export declare function ref(path: string): SkillRef;
-export type InstructionFragment = string | Ref;
+/**
+ * Reference a directory — verified at compile time to exist AND be a directory
+ * (not a file). The "architecture floats free" fix: a spec that names `src/core/`
+ * proves the directory is really there, where a plain string in prose rots
+ * silently. Compiles to the inline form `` `path` ``.
+ */
+export declare function dir(path: string): DirRef;
+/**
+ * Reference a glob pattern — verified at compile time to match at least one path,
+ * so `glob("src/*.test.ts")` proves tests actually exist where the instructions
+ * claim (the pattern supports the usual `*` / `**` syntax). Compiles to the
+ * inline form `` `pattern` ``.
+ */
+export declare function glob(pattern: string): GlobRef;
+/**
+ * A marked side-effect BOUNDARY inside a skill/agent body — "side effects are
+ * allowed ONLY inside this block." Compiles to `<!-- vigiles:effect -->` …
+ * `<!-- /vigiles:effect -->` markers the runtime PreToolUse gate keys on: outside
+ * the region the unit is treated as read-only (the `"pure"` effective floor),
+ * inside it the declared purity floor applies. The position-aware companion to
+ * the per-call `purity` floor. See `research/effect-boundary-design.md`.
+ */
+export interface EffectRegion {
+    readonly _ref: "effect";
+    readonly body: InstructionFragment[];
+}
+export type InstructionFragment = string | Ref | EffectRegion;
 /**
  * Tagged template literal for skill instructions with typed references.
  *
@@ -175,6 +217,39 @@ export type InstructionFragment = string | Ref;
  *   `
  */
 export declare function instructions(strings: TemplateStringsArray, ...values: InstructionFragment[]): InstructionFragment[];
+/**
+ * Tagged template literal marking a side-effect boundary — usable as an
+ * interpolated fragment inside a body / `instructions\`\``:
+ *
+ *   instructions`
+ *     ## Apply
+ *     ${effect`
+ *       Side effects are allowed ONLY here:
+ *       - write ${file("CHANGELOG.md")}
+ *       - ${cmd("npm publish")}
+ *     `}
+ *   `
+ *
+ * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
+ * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
+ * surface — it does not block on it.
+ */
+export declare function effect(strings: TemplateStringsArray, ...values: InstructionFragment[]): EffectRegion;
+/**
+ * The purity an author DECLARES for a skill/agent — the floor `compile`
+ * enforces against the tool contract (see `purityViolations` in
+ * `core/effects.ts`). Mirrors the analysis `PurityLevel` for the two meaningful
+ * rungs, so what you DECLARE and what `scan` REPORTS share one vocabulary:
+ * - `"pure"`:    only read-only tools — no side effects at all.
+ * - `"bounded"`: decidable side-effecting tools (Write, Edit, …) are allowed,
+ *   but not `Bash` / unknown-effect / inherits-all (the unbounded cells).
+ * - `"dangerously-unrestricted"`: the explicit escape hatch — no enforcement.
+ *   Deliberately loud (cf. React's `dangerouslySetInnerHTML`) so opting OUT of
+ *   the guardrail stands out in review. Omitting `purity` is the same
+ *   (unenforced) default WITHOUT typing the loud word — you write it only when
+ *   you mean to override a stricter level.
+ */
+export type AuthoredPurity = "pure" | "bounded" | "dangerously-unrestricted";
 /** Known markdown instruction file targets. */
 export type InstructionTarget = "CLAUDE.md" | "AGENTS.md" | (string & {});
 export interface ClaudeSpec {
@@ -190,7 +265,12 @@ export interface ClaudeSpec {
     readonly keyFiles?: Record<string, string>;
     /** Named prose sections — plain strings or tagged templates with file()/cmd()/ref(). */
     readonly sections?: Record<string, string | InstructionFragment[]>;
-    /** Maximum lines per prose section (per-spec override). */
+    /**
+     * Maximum lines for a single named prose section. Overrides the generous
+     * compile-time default (200 lines) that guards every section + agent section
+     * against an egregious content dump — set a tighter number to enforce your own
+     * house limit, or a larger one for an intentionally long section.
+     */
     readonly maxSectionLines?: number;
     /**
      * Maximum estimated tokens for the compiled output (~4 chars per token).
@@ -293,6 +373,31 @@ export interface SkillSpec {
     readonly inputs?: readonly SkillInput[];
     /** Whether to disable model invocation (frontmatter flag). */
     readonly disableModelInvocation?: boolean;
+    /**
+     * Execution context. `"fork"` runs the skill's body as the task inside a
+     * forked SUBAGENT (its own context window) instead of inline in the main
+     * conversation (Anthropic's `context: fork` frontmatter). This is the ONLY
+     * setting under which a skill gains a real call→return boundary — so it's the
+     * prerequisite for declaring an `output` Result contract (see `output`). Omit
+     * for the default inline execution.
+     */
+    readonly context?: "fork";
+    /**
+     * The allowed-tools contract for this skill. Each entry must be a known
+     * built-in tool or an MCP tool (`mcp__server__tool`). Omit to inherit all
+     * tools. When `purity` is `"pure"`/`"bounded"`, the declared tools are checked
+     * against that floor — compile rejects a tool looser than the declared level.
+     */
+    readonly tools?: readonly string[];
+    /**
+     * Declare this skill's purity floor — compile rejects a tool contract looser
+     * than it. `"pure"` allows only read-only tools; `"bounded"` also allows
+     * decidable side-effecting tools (Write, Edit, …) but bars `Bash` /
+     * unknown-effect / inherits-all; `"dangerously-unrestricted"` (or omitting it)
+     * enforces nothing. NOTE: `"pure"`/`"bounded"` require an explicit read-only
+     * `tools` list — an absent list inherits ALL tools and is a violation.
+     */
+    readonly purity?: AuthoredPurity;
     /**
      * Gated pipeline steps. When set, the skill compiles to a `## Steps`
      * checklist with a deterministic gate per step. Use this OR `body`.
@@ -303,6 +408,18 @@ export interface SkillSpec {
      * Compiles to a `## Result` section + a `vigiles:result` marker.
      */
     readonly result?: Gate;
+    /**
+     * The skill's typed railway outcome — the SAME `Result<ok, err>` contract a
+     * subagent declares with `result(okShape, errShape)`. Valid ONLY with
+     * `context: "fork"`: a forked skill runs as a subagent, so it has the
+     * call→return boundary a typed outcome needs (compile errors if `output` is set
+     * without `context: "fork"`). When valid, compiles to a `## Output contract`
+     * with a `vigiles:ok` / `vigiles:err` block — parseable (`parseAgentResult`) and
+     * testable (`assertAgentOk`) via the existing subagent rail. An INLINE skill has
+     * no return, so a typed outcome there is a category error — hence the gate. See
+     * `research/spec-syntax-and-railway-scope.md`.
+     */
+    readonly output?: OutputContract;
     /** Freeform instruction body (linear/unstructured skills). Use this OR `steps`. */
     readonly body?: string | InstructionFragment[];
     /**
@@ -338,6 +455,8 @@ export interface AgentSpec {
     readonly description: string;
     /** Model alias (e.g. "sonnet", "opus", "haiku", "inherit"). Optional. */
     readonly model?: string;
+    /** Subagent UI colour (Claude Code frontmatter, e.g. "pink", "blue"). Optional. */
+    readonly color?: string;
     /**
      * The allowed-tools contract — the rails the worker runs on. Each entry must be
      * a known built-in tool (Read/Write/Edit/Bash/Grep/Glob/WebSearch/WebFetch/
@@ -345,6 +464,17 @@ export interface AgentSpec {
      * Omit to inherit all tools. Verified at compile time.
      */
     readonly tools?: readonly string[];
+    /**
+     * The DENY-side contract — tools the worker may NOT use. Use this INSTEAD OF
+     * `tools`, not with it: `tools` is an allowlist (only these), so a tool not
+     * listed is already unavailable and a `disallowedTools` entry would be
+     * redundant. `disallowedTools` earns its place only when there's NO allowlist
+     * (the agent inherits ALL tools) and you want to subtract a few — e.g.
+     * `disallowedTools: ["Bash"]` on an otherwise-unrestricted worker. Rendered to
+     * the `disallowedTools:` frontmatter; close-typos are flagged (a typo'd entry
+     * blocks nothing). For a read-only floor prefer a tight `tools` list + `purity`.
+     */
+    readonly disallowedTools?: readonly string[];
     /**
      * The lead/intro prose of the system prompt (the "You are…" opener), before any
      * sections. Carries verified `file()`/`cmd()`/`symbol()`/`ref()` marks. No
@@ -367,6 +497,15 @@ export interface AgentSpec {
      * and testable (see `result()`, `parseAgentResult`, `assertAgentOk`).
      */
     readonly output?: OutputContract;
+    /**
+     * Declare this agent's purity floor — compile rejects a tool contract looser
+     * than it. `"pure"` allows only read-only tools; `"bounded"` also allows
+     * decidable side-effecting tools (Write, Edit, …) but bars `Bash` /
+     * unknown-effect / inherits-all; `"dangerously-unrestricted"` (or omitting it)
+     * enforces nothing. `"pure"`/`"bounded"` require an explicit `tools` list — a
+     * wildcard or absent-tools (inherits-all) is always a violation.
+     */
+    readonly purity?: AuthoredPurity;
 }
 /**
  * Define a subagent specification (compiles to `agents/<name>.md`).

package/dist/core/spec.js

@@ -17,7 +17,10 @@ exports.file = file;
 exports.cmd = cmd;
 exports.symbol = symbol;
 exports.ref = ref;
+exports.dir = dir;
+exports.glob = glob;
 exports.instructions = instructions;
+exports.effect = effect;
 exports.claude = claude;
 exports.project = project;
 exports.input = input;
@@ -105,6 +108,24 @@ function symbol(file, name) {
 function ref(path) {
     return { _ref: "skill", path: path };
 }
+/**
+ * Reference a directory — verified at compile time to exist AND be a directory
+ * (not a file). The "architecture floats free" fix: a spec that names `src/core/`
+ * proves the directory is really there, where a plain string in prose rots
+ * silently. Compiles to the inline form `` `path` ``.
+ */
+function dir(path) {
+    return { _ref: "dir", path: path };
+}
+/**
+ * Reference a glob pattern — verified at compile time to match at least one path,
+ * so `glob("src/*.test.ts")` proves tests actually exist where the instructions
+ * claim (the pattern supports the usual `*` / `**` syntax). Compiles to the
+ * inline form `` `pattern` ``.
+ */
+function glob(pattern) {
+    return { _ref: "glob", pattern: pattern };
+}
 /**
  * Tagged template literal for skill instructions with typed references.
  *
@@ -124,6 +145,33 @@ function instructions(strings, ...values) {
     }
     return result;
 }
+/**
+ * Tagged template literal marking a side-effect boundary — usable as an
+ * interpolated fragment inside a body / `instructions\`\``:
+ *
+ *   instructions`
+ *     ## Apply
+ *     ${effect`
+ *       Side effects are allowed ONLY here:
+ *       - write ${file("CHANGELOG.md")}
+ *       - ${cmd("npm publish")}
+ *     `}
+ *   `
+ *
+ * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
+ * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
+ * surface — it does not block on it.
+ */
+function effect(strings, ...values) {
+    const body = [];
+    for (let i = 0; i < strings.length; i++) {
+        if (strings[i])
+            body.push(strings[i]);
+        if (i < values.length)
+            body.push(values[i]);
+    }
+    return { _ref: "effect", body };
+}
 /**
  * Define a CLAUDE.md specification.
  *

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

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ *
+ * 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
+ * shipped plugin), and the `subagent-tool-contract` lint rule (the severity-gated
+ * 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.
+ */
+import type { HarnessDialect } from "./dialect.js";
+export type ToolIssueKind = "never-available" | "unknown";
+export interface ToolIssue {
+    readonly tool: string;
+    readonly kind: ToolIssueKind;
+    /** Closest known built-in tool (did-you-mean), or null. */
+    readonly suggestion: string | null;
+    /** 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`.
+ */
+export declare function closestTool(tool: string, dialect: HarnessDialect): string | null;
+/**
+ * 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.
+ */
+export declare function confidentToolIssues(issues: readonly ToolIssue[]): ToolIssue[];
+/**
+ * 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.
+ */
+export declare function disallowedToolIssues(tools: readonly string[], dialect: HarnessDialect): ToolIssue[];
+/**
+ * Verify a subagent's `tools:` contract against the dialect catalog. Returns one
+ * {@link ToolIssue} per offending entry (empty when every tool is a real built-in
+ * or a well-formed MCP tool). A `Tool(restriction)` suffix (e.g. `Bash(git:*)`)
+ * is stripped to its base tool before checking.
+ */
+export declare function verifyToolContract(tools: readonly string[], dialect: HarnessDialect): ToolIssue[];
+//# sourceMappingURL=tool-contract.d.ts.map

package/dist/core/tool-contract.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.closestTool = closestTool;
+exports.confidentToolIssues = confidentToolIssues;
+exports.disallowedToolIssues = disallowedToolIssues;
+exports.verifyToolContract = verifyToolContract;
+const linters_js_1 = require("./linters.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`.
+ */
+function closestTool(tool, dialect) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const known of dialect.builtinAgentTools) {
+        const d = (0, linters_js_1.editDistance)(tool.toLowerCase(), known.toLowerCase());
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = known;
+        }
+    }
+    return bestDistance <= 2 ? best : null;
+}
+/**
+ * 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.
+ */
+function confidentToolIssues(issues) {
+    return issues.filter((i) => i.kind === "never-available" || i.suggestion !== 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.
+ */
+function disallowedToolIssues(tools, dialect) {
+    const never = new Set(dialect.neverAvailableTools);
+    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 (near === null)
+            continue; // bare unknown → likely a plugin tool, not a typo
+        issues.push({
+            tool,
+            kind: "unknown",
+            suggestion: near,
+            message: `disallowedTools entry "${tool}" matches no real tool — it blocks nothing. Did you mean "${near}"?`,
+        });
+    }
+    return issues;
+}
+/**
+ * Verify a subagent's `tools:` contract against the dialect catalog. Returns one
+ * {@link ToolIssue} per offending entry (empty when every tool is a real built-in
+ * or a well-formed MCP tool). A `Tool(restriction)` suffix (e.g. `Bash(git:*)`)
+ * is stripped to its base tool before checking.
+ */
+function verifyToolContract(tools, dialect) {
+    const never = new Set(dialect.neverAvailableTools);
+    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}"?` : "";
+        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}`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=tool-contract.js.map