vigiles 5.0.1 → 5.1.0

package/dist/cli.js

@@ -20,6 +20,10 @@ const setup_plan_js_1 = require("./setup-plan.js");
 const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
 const scan_js_1 = require("./scan.js");
+const tool_contract_js_1 = require("./core/tool-contract.js");
+const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
+const dialect_js_1 = require("./adapters/claude-code/dialect.js");
+const scan_behavioral_js_1 = require("./scan-behavioral.js");
 const adapter_registry_js_1 = require("./adapter-registry.js");
 const skill_harness_js_1 = require("./skill-harness.js");
 const leaderboard_js_1 = require("./leaderboard.js");
@@ -31,7 +35,7 @@ const generate_schema_js_1 = require("./core/generate-schema.js");
 const compose_js_1 = require("./core/compose.js");
 const compile_generator_js_1 = require("./core/compile-generator.js");
 const action_gate_js_1 = require("./action-gate.js");
-const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
+const agent_runtime_js_2 = require("./adapters/claude-code/agent-runtime.js");
 const tool_intercept_js_1 = require("./tool-intercept.js");
 const refs_js_1 = require("./core/refs.js");
 const mcp_js_1 = require("./core/mcp.js");
@@ -633,6 +637,17 @@ function lintExitCode(report) {
         report.integrityErrors > 0 ||
         report.coverageErrors > 0 ||
         report.untestedErrors > 0 ||
+        report.toolContractErrors > 0 ||
+        report.hookEventErrors > 0 ||
+        report.frontmatterSchemaErrors > 0 ||
+        report.mcpConfigErrors > 0 ||
+        report.skillFrontmatterErrors > 0 ||
+        report.mcpToolErrors > 0 ||
+        report.hookScriptErrors > 0 ||
+        report.disallowedToolErrors > 0 ||
+        report.descriptionOverlapErrors > 0 ||
+        report.frontmatterValidErrors > 0 ||
+        report.mcpHookErrors > 0 ||
         report.symbolRefErrors > 0 ||
         report.mcpRefErrors > 0)
         return 2;
@@ -913,6 +928,39 @@ async function runLint(restArgs, flags, config) {
     // eval. Warning by default (a nudge, exit 0); set rules.untested-{skill,agent,
     // hook} to "error" to gate CI. See src/test-coverage.ts and docs/rules/.
     const untested = checkUntestedSurfaces(config, silent);
+    // 7c. Agent tool-contract check — cross-reference each subagent's `tools:` rail
+    // against the harness catalog (the moat). Off by default unless a severity is
+    // configured; warning surfaces a typo/never-available tool, error gates CI.
+    const toolContract = checkAgentToolContracts(config, silent);
+    // 7d. Hook-event check — a hook registered under an event the harness doesn't
+    // define never fires. High-precision (close typos only). Off unless configured.
+    const hookEvents = checkHookEvents(config, silent);
+    // 7e. Frontmatter-schema check — a skill/agent missing required frontmatter
+    // (name; agents also description) won't load/register. High-confidence.
+    const frontmatter = checkFrontmatterSchema(config, silent);
+    // 7f. MCP-config check — a declared MCP server with no command/url can't start.
+    const mcpConfig = checkMcpConfig(config, silent);
+    // 7g. Skill-frontmatter — RECOMMEND explicit name/description on skills (a
+    // reliable trigger surface). Best-practice nudge; skills load without it.
+    const skillFm = checkSkillFrontmatter(config, silent);
+    // 7h. MCP tool-resolution — an `mcp__server__tool` in a contract whose server
+    // the plugin doesn't declare can't resolve (the MCP half of the tool moat).
+    const mcpToolResolves = checkMcpToolResolves(config, silent);
+    // 7i. Hook-script existence — a hook command referencing a missing script file
+    // never runs (matches Anthropic's own `claude plugin validate`).
+    const hookScripts = checkHookScriptExists(config, silent);
+    // 7j. Disallowed-tools — a `disallowedTools:` block-list typo blocks nothing
+    // (the deny-side mirror of agent-tool-contract; close-typo only).
+    const disallowedTools = checkDisallowedTools(config, silent);
+    // 7k. Description-overlap — two model-invocable skills with near-identical
+    // descriptions collide in the selector (deterministic NCD precision proxy).
+    const descriptionOverlap = checkDescriptionOverlap(config, silent);
+    // 7l. Frontmatter-valid — a `---` block that isn't valid YAML (warn; js-yaml is
+    // stricter than some loaders, so verify before enforcing).
+    const frontmatterValid = checkFrontmatterValid(config, silent);
+    // 7m. MCP hook-target — a `type: mcp_tool` hook action that's incomplete or
+    // targets an undeclared server (the moat applied to the hook surface).
+    const mcpHookTargets = checkMcpHookTargets(config, silent);
     // 8. Validate vigiles builder calls inside markdown code blocks. Default
     // is to validate every ref; illustrative blocks opt out via
     // `<!-- vigiles:ignore -->` (single block) or
@@ -956,6 +1004,28 @@ async function runLint(restArgs, flags, config) {
         orphanCount: orphanReport.orphans.length,
         untestedSurfaces: untested.untested,
         untestedErrors: untested.errors,
+        toolContractIssues: toolContract.issues,
+        toolContractErrors: toolContract.errors,
+        hookEventIssues: hookEvents.issues,
+        hookEventErrors: hookEvents.errors,
+        frontmatterSchemaIssues: frontmatter.issues,
+        frontmatterSchemaErrors: frontmatter.errors,
+        mcpConfigIssues: mcpConfig.issues,
+        mcpConfigErrors: mcpConfig.errors,
+        skillFrontmatterIssues: skillFm.issues,
+        skillFrontmatterErrors: skillFm.errors,
+        mcpToolIssues: mcpToolResolves.issues,
+        mcpToolErrors: mcpToolResolves.errors,
+        hookScriptIssues: hookScripts.issues,
+        hookScriptErrors: hookScripts.errors,
+        disallowedToolIssues: disallowedTools.issues,
+        disallowedToolErrors: disallowedTools.errors,
+        descriptionOverlapIssues: descriptionOverlap.issues,
+        descriptionOverlapErrors: descriptionOverlap.errors,
+        frontmatterValidIssues: frontmatterValid.issues,
+        frontmatterValidErrors: frontmatterValid.errors,
+        mcpHookIssues: mcpHookTargets.issues,
+        mcpHookErrors: mcpHookTargets.errors,
         docRefErrors: docRefReport.errors.length,
         symbolRefErrors,
         mcpRefErrors,
@@ -1931,6 +2001,328 @@ function checkUntestedSurfaces(config, silent) {
         errors: report.untested.filter((s) => sevFor(s.kind) === "error").length,
     };
 }
+/**
+ * Apply the `agent-tool-contract` rule: cross-reference every subagent's `tools:`
+ * rail against the harness tool catalog (the moat — "valid is not true"). Flags
+ * only the HIGH-CONFIDENCE issues (a never-available tool, or a close typo) via
+ * the shared `confidentToolIssues` detector — the same code `scan` and
+ * `compileAgent` use (one-detector-no-drift), so a bare unrecognized tool
+ * (plugin/MCP-provided) is never a false alarm. Warning by default; set
+ * `agent-tool-contract: "error"` to gate CI. Returns the issue + error counts.
+ */
+function checkAgentToolContracts(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["agent-tool-contract"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    const files = (0, glob_1.globSync)(["agents/*.md", ".claude/agents/*.md"], {
+        cwd: process.cwd(),
+        ignore: ["**/*.spec.ts"],
+    });
+    let issues = 0;
+    let printedHeader = false;
+    for (const rel of files.sort()) {
+        let md;
+        try {
+            md = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), rel), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const tools = (0, agent_runtime_js_1.parseAgentTools)(md);
+        if (tools === null)
+            continue; // no contract → inherits all (a different rule)
+        const found = (0, tool_contract_js_1.confidentToolIssues)((0, tool_contract_js_1.verifyToolContract)(tools, dialect_js_1.claudeCodeDialect));
+        if (found.length === 0)
+            continue;
+        issues += found.length;
+        if (!silent) {
+            if (!printedHeader) {
+                console.log("\nAgent tool-contract check:\n");
+                printedHeader = true;
+            }
+            for (const issue of found) {
+                console.log(`  ${sev === "error" ? "✗" : "⚠"} ${rel}: ${issue.message}`);
+                ghAnnotate(sev === "error" ? "error" : "warning", issue.message, rel);
+            }
+        }
+    }
+    return { issues, errors: sev === "error" ? issues : 0 };
+}
+/**
+ * Apply the `hook-events` rule: flag a hook registered under an event name the
+ * harness doesn't define (a typo → the hook never fires). Reuses `scanPlugin`'s
+ * `hookEventIssues` (the shared detector, high-precision: close typos only, never
+ * a framework/custom event). Warning by default; "error" gates CI.
+ */
+function checkHookEvents(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-events"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd()).hookEventIssues;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nHook-event check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `agent-frontmatter` rule. Two kinds of agent-frontmatter defect, one
+ * rule: (1) a subagent MISSING a required field (`name`/`description`) — it won't
+ * register; (2) a subagent with an INVALID `model:`/`color:` value (a close typo
+ * of a real one) — it silently falls back / is ignored. Reuses `scanPlugin`'s
+ * `frontmatterIssues` + `frontmatterValueIssues`. Warning by default; "error" gates CI.
+ */
+function checkFrontmatterSchema(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["agent-frontmatter"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        const r = (0, scan_js_1.scanPlugin)(process.cwd());
+        found = [...r.frontmatterIssues, ...r.frontmatterValueIssues];
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nFrontmatter-schema check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `skill-frontmatter` rule: RECOMMEND (not require) that a SKILL.md
+ * declares an explicit `name` + `description` rather than relying on the
+ * dir-name / first-paragraph fallbacks — a more reliable trigger surface. The
+ * skill still LOADS without them, so this is a best-practice nudge: warn by
+ * default; set "error" to enforce it on your own skills. Reuses `scanPlugin`'s
+ * `skillMetaIssues`.
+ */
+function checkSkillFrontmatter(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-frontmatter"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd()).skillMetaIssues;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nSkill-frontmatter check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `mcp-config` rule: a declared MCP server with neither a `command`
+ * (stdio) nor a `url` (http/sse) can't start. Reuses `scanPlugin`'s `mcpIssues`.
+ * Warning by default; "error" gates CI.
+ */
+function checkMcpConfig(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-config"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd()).mcpIssues;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nMCP-config check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `disallowed-tools-contract` rule: a subagent's `disallowedTools:`
+ * block-list entry that's a close typo of a real tool blocks NOTHING — the tool
+ * it was meant to deny stays available, silently. Reuses `scanPlugin`'s per-agent
+ * `disallowedToolIssues` (close-typo only — high-precision). Warning by default;
+ * "error" gates CI.
+ */
+function checkDisallowedTools(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["disallowed-tools-contract"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd()).agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({ message: i.message, path: a.path })));
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nDisallowed-tools check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.path}: ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `frontmatter-valid` rule: a skill/agent `---` block that EXISTS but
+ * isn't valid YAML — fields may not parse as intended. Reuses `scanPlugin`'s
+ * `malformedFrontmatter`. HONEST caveat (see docs/rules/frontmatter-valid.md):
+ * js-yaml is stricter than some loaders, so a one-line `description:` with a
+ * colon / `<example>` is flagged though it may still load — hence WARN by default
+ * (verify before setting "error").
+ */
+function checkFrontmatterValid(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["frontmatter-valid"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd()).malformedFrontmatter;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nFrontmatter-validity check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `description-overlap` rule: two model-invocable skills with
+ * near-identical descriptions collide in the selector — the wrong one fires. A
+ * deterministic NCD proxy for a `--trigger`-class precision bug. Reuses
+ * `scanPlugin`'s `descriptionOverlaps` (calibrated FP-safe: only basically
+ * identical text). Warning by default; "error" gates CI.
+ */
+function checkDescriptionOverlap(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["description-overlap"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd()).descriptionOverlaps;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nDescription-overlap check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `mcp-hook-target-resolves` rule: a `type: "mcp_tool"` hook action
+ * that's incomplete (no `server`/`tool`) or targets a server the plugin doesn't
+ * declare — the hook silently never dispatches. Reuses `scanPlugin`'s
+ * `mcpHookIssues` (high-precision: declared-set gated, built-ins allowlisted).
+ * Warning by default; "error" gates CI.
+ */
+function checkMcpHookTargets(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-hook-target-resolves"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd()).mcpHookIssues;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nMCP hook-target check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `hook-script-exists` rule: a hook command references a script file
+ * that doesn't exist on disk (with `${CLAUDE_PLUGIN_ROOT}` resolved) → the hook
+ * silently never runs. Reuses `scanPlugin`'s `hooks` (status "missing"); the
+ * shared resolver already excludes the FP-prone cases (unresolved vars,
+ * existence-guarded one-liners, inline commands). Matches Anthropic's own
+ * `claude plugin validate`. Warning by default; "error" gates CI.
+ */
+function checkHookScriptExists(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-script-exists"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let missing;
+    try {
+        missing = (0, scan_js_1.scanPlugin)(process.cwd()).hooks.filter((h) => h.status === "missing");
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (missing.length > 0 && !silent) {
+        console.log("\nHook-script existence check:\n");
+        for (const h of missing) {
+            const msg = `hook script "${h.script}" is referenced but missing — the hook never runs.`;
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${msg}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", msg);
+        }
+    }
+    return {
+        issues: missing.length,
+        errors: sev === "error" ? missing.length : 0,
+    };
+}
+/**
+ * Apply the `mcp-tool-resolves` rule: an `mcp__server__tool` in a subagent's
+ * contract whose server isn't in the plugin's declared `mcpServers` can't resolve
+ * (the MCP half of the tool moat). Reuses `scanPlugin`'s per-agent `mcpToolIssues`
+ * — high-precision (gated on a declared set, built-ins allowlisted, the
+ * plugin-namespaced form skipped). Warning by default; "error" gates CI.
+ */
+function checkMcpToolResolves(config, silent) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-tool-resolves"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd()).agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nMCP tool-resolution check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.path}: ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
 /**
  * Apply the configured coverage thresholds. Returns the number of failing
  * thresholds (so the lint can fail CI when severity is "error").
@@ -2008,6 +2400,43 @@ function findInstructionFiles(restArgs) {
     }
     return files;
 }
+/** Value of a `--flag=value` arg (the `=` form, so it never collides with a positional). */
+function flagValue(args, name) {
+    return args.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1);
+}
+/**
+ * The `scan --trigger` behavioral column: load the author-supplied per-skill
+ * prompt sets, probe the plugin's model-invocable skills, print the column.
+ * Model-gated and opt-in — the structural scan above stays deterministic.
+ */
+async function handleScanTrigger(root, args, json, harness) {
+    const promptsPath = flagValue(args, "--prompts");
+    if (!promptsPath) {
+        console.error("scan --trigger needs --prompts=<file.json> (a map of skill name → { prompts, irrelevant }).");
+        process.exitCode = 2;
+        return;
+    }
+    let promptSet;
+    try {
+        promptSet = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(promptsPath), "utf-8"));
+    }
+    catch (e) {
+        console.error(`scan --trigger: could not read --prompts file "${promptsPath}": ${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 2;
+        return;
+    }
+    const concurrencyRaw = flagValue(args, "--concurrency");
+    const minPromptsRaw = flagValue(args, "--min-prompts");
+    const report = await (0, scan_behavioral_js_1.probePluginTriggers)(root, promptSet, {
+        concurrency: concurrencyRaw ? Number(concurrencyRaw) : undefined,
+        minPrompts: minPromptsRaw ? Number(minPromptsRaw) : undefined,
+        model: flagValue(args, "--model"),
+        harness,
+    });
+    console.log(json
+        ? JSON.stringify(report, null, 2)
+        : `\n${(0, scan_behavioral_js_1.formatBehavioralReport)(report)}`);
+}
 function handleGenerateTypes(args, restArgs) {
     const checkOnly = args.includes("--check");
     const outPath = restArgs[0] ?? ".vigiles/generated.d.ts";
@@ -2295,7 +2724,7 @@ function agentHookCommand() {
     }
     if (!tool)
         return;
-    const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(process.cwd(), tool);
+    const decision = (0, agent_runtime_js_2.evaluatePreToolUse)(process.cwd(), tool);
     if (!decision.allow) {
         console.error(decision.message);
         process.exit(2);
@@ -2331,7 +2760,7 @@ function agentStartCommand(target) {
         console.error("Usage: vigiles agent-start <agents/<name>.md>");
         process.exit(2);
     }
-    (0, agent_runtime_js_1.setActiveAgent)(process.cwd(), target);
+    (0, agent_runtime_js_2.setActiveAgent)(process.cwd(), target);
     console.log(`Active agent: ${target}`);
 }
 /** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
@@ -2353,7 +2782,7 @@ function handleSkillCommand(command, restArgs) {
             agentStartCommand(restArgs[0]);
             return true;
         case "agent-done":
-            (0, agent_runtime_js_1.clearActiveAgent)(process.cwd());
+            (0, agent_runtime_js_2.clearActiveAgent)(process.cwd());
             return true;
         case "agent-hook":
             agentHookCommand();
@@ -2574,13 +3003,36 @@ async function main() {
         case "scan": {
             const dirs = restArgs.length > 0 ? restArgs : ["."];
             const json = args.includes("--json");
-            if (dirs.length > 1) {
+            // A single dir that's a marketplace (e.g. wshobson/agents' 80+ plugins
+            // under one marketplace.json) expands into its members and ranks them.
+            const market = dirs.length === 1 ? (0, scan_js_1.inspectMarketplace)((0, node_path_1.resolve)(dirs[0])) : null;
+            const targets = market && market.onDisk.length > 0 ? [...market.onDisk] : dirs;
+            const wantTrigger = args.includes("--trigger");
+            if (market && market.onDisk.length === 0 && market.total > 0) {
+                // A CURATED marketplace — every member is an external git/url plugin, so
+                // there's nothing on disk to scan. Say so honestly instead of falling
+                // through to a misleading "empty machine / no structural issues" report
+                // (obra/superpowers-marketplace, anthropics/claude-plugins-community).
+                if (json) {
+                    console.log(JSON.stringify(market, null, 2));
+                }
+                else {
+                    console.log(`Marketplace "${market.name}": ${String(market.total)} plugin(s), all external ` +
+                        `(url/git sources, not on disk).\n` +
+                        `Nothing to scan here — clone a member plugin and scan that, or scan a ` +
+                        `marketplace that vendors its plugins in-tree.`);
+                }
+            }
+            else if (targets.length > 1) {
                 // Multiple targets → rank them (the leaderboard engine).
-                const scores = (0, leaderboard_js_1.rankPlugins)(dirs);
+                const scores = (0, leaderboard_js_1.rankPlugins)(targets);
                 console.log(json ? JSON.stringify(scores, null, 2) : (0, leaderboard_js_1.formatLeaderboard)(scores));
+                if (wantTrigger) {
+                    console.log("\n⚠ --trigger (behavioral column) runs per single plugin; not yet wired into the leaderboard. Scan one plugin dir to probe it.");
+                }
             }
             else {
-                const root = (0, node_path_1.resolve)(dirs[0]);
+                const root = (0, node_path_1.resolve)(targets[0]);
                 const harnessFlag = args
                     .find((a) => a.startsWith("--harness="))
                     ?.slice("--harness=".length);
@@ -2588,7 +3040,7 @@ async function main() {
                 const adapter = harnessFlag
                     ? (0, adapter_registry_js_1.resolveAdapter)(root, harnessFlag)
                     : det.adapter;
-                const report = (0, scan_js_1.scanPlugin)(dirs[0], adapter.layout);
+                const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect);
                 if (!json) {
                     console.log(`Detected harness: ${adapter.name}`);
                     if (!harnessFlag && det.ambiguousWith.length > 0) {
@@ -2597,6 +3049,10 @@ async function main() {
                     console.log("");
                 }
                 console.log(json ? JSON.stringify(report, null, 2) : (0, scan_js_1.formatScanReport)(report));
+                if (wantTrigger) {
+                    const harness = adapter.name === "codex" ? "codex" : "claude-code";
+                    await handleScanTrigger(root, args, json, harness);
+                }
             }
             break;
         }

package/dist/codex.d.ts

@@ -17,4 +17,5 @@ export * from "./adapters/codex/model-mock.js";
 export * from "./adapters/codex/mock-model.js";
 export * from "./adapters/codex/driver.js";
 export * from "./adapters/codex/adapter.js";
+export * from "./adapters/codex/eval.js";
 //# sourceMappingURL=codex.d.ts.map

package/dist/codex.js

@@ -33,4 +33,7 @@ __exportStar(require("./adapters/codex/model-mock.js"), exports);
 __exportStar(require("./adapters/codex/mock-model.js"), exports);
 __exportStar(require("./adapters/codex/driver.js"), exports);
 __exportStar(require("./adapters/codex/adapter.js"), exports);
+// Eval-tier transport (increment 2 — scaffold, pending live-binary validation):
+// parseCodexEvalRun (the ModelOutputParser for `codex exec --json`) + codexEvalRunner.
+__exportStar(require("./adapters/codex/eval.js"), exports);
 //# sourceMappingURL=codex.js.map

package/dist/core/compile.js

@@ -26,6 +26,7 @@ const node_path_1 = require("node:path");
 const hash_js_1 = require("./hash.js");
 const symbols_js_1 = require("./symbols.js");
 const linters_js_1 = require("./linters.js");
+const tool_contract_js_1 = require("./tool-contract.js");
 // vigiles's default compile target when a spec names none and no dialect is
 // injected — a product convention (vigiles emits CLAUDE.md by default), not a
 // harness dialect. When a dialect IS injected its instructionTargets win.
@@ -680,43 +681,14 @@ function compileSkill(spec, options = {}) {
 // vigiles does not emit a TOML [agents] block. The Codex dialect still verifies
 // an agent()'s tool contract (its built-in catalog) — only the OUTPUT renderer
 // is CC-only here. See research/codex-prototype-findings.md (gaps).
-/** Closest known tool by edit distance (≤ 3), for a "did you mean" hint. */
-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 <= 3 ? best : null;
-}
-/** Verify a subagent's allowed-tools contract — the rails are real tools. */
+/** Verify a subagent's allowed-tools contract — the rails are real tools. The
+ * detection lives in the shared `verifyToolContract` detector (one-detector-no-
+ * drift: compile + scan + the agent-tool-contract lint rule call the same code). */
 function validateAgentTools(tools, dialect) {
-    const never = new Set(dialect.neverAvailableTools);
-    const errors = [];
-    for (const tool of tools) {
-        if (never.has(tool)) {
-            errors.push({
-                type: "unknown-tool",
-                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}"?` : "";
-        errors.push({
-            type: "unknown-tool",
-            message: `Unknown tool "${tool}" in agent tools — use a built-in tool (${dialect.builtinAgentTools.join(", ")}) or an MCP tool (mcp__server__tool).${hint}`,
-        });
-    }
-    return errors;
+    return (0, tool_contract_js_1.verifyToolContract)(tools, dialect).map((issue) => ({
+        type: "unknown-tool",
+        message: issue.message,
+    }));
 }
 /** Build the subagent YAML frontmatter (name / description / model / tools). */
 function renderAgentFrontmatter(spec) {

package/dist/core/description-overlap.d.ts

@@ -0,0 +1,27 @@
+/** A skill identified by name + its trigger-surface description. */
+export interface DescribedSurface {
+    readonly name: string;
+    readonly description: string;
+}
+export interface DescriptionOverlap {
+    readonly a: string;
+    readonly b: string;
+    /** 0–1, higher = more alike (1 − NCD), rounded to 2 dp. */
+    readonly similarity: number;
+    readonly message: string;
+}
+/**
+ * The NCD cutoff below which two descriptions count as a near-duplicate. 0.2 sits
+ * safely under the sweep's most-similar legitimately-distinct pair (0.25), so
+ * only basically-identical text is flagged. Exported so a caller / test can see
+ * the calibrated value.
+ */
+export declare const OVERLAP_NCD_CUTOFF = 0.2;
+/**
+ * Find near-duplicate description pairs among `surfaces`. Returns one
+ * {@link DescriptionOverlap} per pair whose NCD is below `cutoff`, most-similar
+ * first. Pure; pass only the surfaces that actually compete for auto-selection
+ * (model-invocable, described) so a user-invoked pair isn't a false alarm.
+ */
+export declare function findDescriptionOverlaps(surfaces: readonly DescribedSurface[], cutoff?: number): DescriptionOverlap[];
+//# sourceMappingURL=description-overlap.d.ts.map