vigiles 8.0.0 → 9.0.0

package/dist/eval.d.ts

@@ -251,7 +251,7 @@ export type AgentRunner = (args: AgentRunArgs) => Promise<RunOut>;
  */
 export declare function resolveSpawnEnv(a: Pick<AgentRunArgs, "env" | "replaceEnv">, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** The real `claude`-spawning runner (composition root). Exported so other
- *  real-model entries (e.g. `scan --trigger`) bind the same runner. */
+ *  real-model entries (e.g. the `audit` trigger tier) bind the same runner. */
 export declare function spawnAgent(a: AgentRunArgs): Promise<RunOut>;
 /**
  * Run the eval: every arm × every trial against the real `claude` CLI, with the

package/dist/eval.js

@@ -96,7 +96,7 @@ function resolveSpawnEnv(a, base = process.env) {
 }
 /* v8 ignore start -- real claude subprocess; exercised by bench/, not the unit gate */
 /** The real `claude`-spawning runner (composition root). Exported so other
- *  real-model entries (e.g. `scan --trigger`) bind the same runner. */
+ *  real-model entries (e.g. the `audit` trigger tier) bind the same runner. */
 function spawnAgent(a) {
     return new Promise((resolvePromise) => {
         const args = [

package/dist/optimize.d.ts

@@ -1,9 +1,9 @@
 /**
- * The per-repo harness optimizer's DETERMINISTIC spine — shipped as the
- * `vigiles scan --fix-plan` lens (NOT its own `optimize` verb: until the measured
- * A/B half lands, an "optimizer" that only re-prints scan's findings doesn't earn
- * a separate command, so it's folded into scan as one more view on the same
- * report; see research/roadmap.md §P2 "reconsider an `optimize` verb").
+ * The per-repo harness optimizer's DETERMINISTIC spine — folded INLINE into the
+ * default `vigiles audit` report (each finding carries its fix; NOT its own
+ * `optimize` verb, and no longer a `--fix-plan` flag: until the measured A/B half
+ * lands, an "optimizer" that only re-prints audit's findings doesn't earn a
+ * separate surface; see research/roadmap.md §P2 "reconsider an `optimize` verb").
  *
  * A2 in the measurement-authority pivot is the ADOPTION product: measure a user's
  * own skills/model/rules on their tasks and recommend add/drop/swap with a MEASURED
@@ -69,6 +69,13 @@ export interface OptimizeReport {
  * before `possible` proxies, via explainScore's own ordering). Pure over the report.
  */
 export declare function optimize(report: ScanReport): OptimizeReport;
+/**
+ * Just the deterministic fix list (no score header) — folded into the default
+ * `vigiles audit` report so every finding carries its fix inline (replaces the
+ * former `--fix-plan`/`--explain` flags). Empty string when there's nothing to
+ * fix (or no loadable surface), so the caller can skip the section entirely.
+ */
+export declare function formatRecommendations(rep: OptimizeReport): string;
 /** Render an optimization plan for the CLI. */
 export declare function formatOptimize(rep: OptimizeReport): string;
 //# sourceMappingURL=optimize.d.ts.map

package/dist/optimize.js

@@ -1,13 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.optimize = optimize;
+exports.formatRecommendations = formatRecommendations;
 exports.formatOptimize = formatOptimize;
 /**
- * The per-repo harness optimizer's DETERMINISTIC spine — shipped as the
- * `vigiles scan --fix-plan` lens (NOT its own `optimize` verb: until the measured
- * A/B half lands, an "optimizer" that only re-prints scan's findings doesn't earn
- * a separate command, so it's folded into scan as one more view on the same
- * report; see research/roadmap.md §P2 "reconsider an `optimize` verb").
+ * The per-repo harness optimizer's DETERMINISTIC spine — folded INLINE into the
+ * default `vigiles audit` report (each finding carries its fix; NOT its own
+ * `optimize` verb, and no longer a `--fix-plan` flag: until the measured A/B half
+ * lands, an "optimizer" that only re-prints audit's findings doesn't earn a
+ * separate surface; see research/roadmap.md §P2 "reconsider an `optimize` verb").
  *
  * A2 in the measurement-authority pivot is the ADOPTION product: measure a user's
  * own skills/model/rules on their tasks and recommend add/drop/swap with a MEASURED
@@ -67,6 +68,27 @@ const ACTION_LABEL = {
     differentiate: "DIFFERENTIATE",
 };
 const measureHint = (dir) => `\`vigiles measure ${dir} --prompts=<file>\` — real-model, runs on your subscription`;
+/**
+ * Just the deterministic fix list (no score header) — folded into the default
+ * `vigiles audit` report so every finding carries its fix inline (replaces the
+ * former `--fix-plan`/`--explain` flags). Empty string when there's nothing to
+ * fix (or no loadable surface), so the caller can skip the section entirely.
+ */
+function formatRecommendations(rep) {
+    if (rep.empty || rep.recommendations.length === 0)
+        return "";
+    const lines = [
+        `${String(rep.recommendations.length)} deterministic fix(es) — free, no model:`,
+        "",
+    ];
+    for (const r of rep.recommendations) {
+        const mark = r.confidence === "likely" ? "✗" : "⚠";
+        lines.push(`${mark} [${ACTION_LABEL[r.action]}] ${r.surface}`);
+        lines.push(`    why: ${r.rationale}  [${r.detector}]`);
+        lines.push(`    →    ${r.fix}`);
+    }
+    return lines.join("\n");
+}
 /** Render an optimization plan for the CLI. */
 function formatOptimize(rep) {
     const head = `Harness health: ${String(rep.score)}/100 (${rep.grade}) — ${rep.dir}`;

package/dist/scan-behavioral.d.ts

@@ -1,8 +1,8 @@
 /**
- * `vigiles scan --trigger` — the BEHAVIORAL column of the scan report.
+ * `vigiles audit` model trigger tier — the BEHAVIORAL column of the audit report.
  *
  * Structural `scan`/`scanPlugin` is deterministic, no-model, CI-free — and stays
- * that way. This is the opt-in, model-gated column that stacks on top: for each
+ * that way. This is the model-gated column that stacks on top: for each
  * model-invocable skill in a plugin, it measures how reliably the description
  * actually FIRES (recall, + precision when irrelevant prompts are supplied),
  * reusing `measureTriggerRate`. It degrades honestly when the `claude` CLI / auth
@@ -12,6 +12,8 @@
  * path in prose is undecidable, and the deterministic-input discipline is what
  * makes the column trustworthy. See `research/plugin-behavioral-findings.md`.
  */
+import type { PluginLayout } from "./core/layout.js";
+import type { HarnessDialect } from "./core/dialect.js";
 import { type EvalDriver } from "./eval.js";
 import { type Trace } from "./harness-test.js";
 /** Which harness drives the behavioral column (default Claude Code). */
@@ -46,6 +48,10 @@ export interface ProbeOptions {
     readonly minDistance?: number;
     /** Which harness to drive (default `"claude-code"`). */
     readonly harness?: ProbeHarness;
+    /** Layout + dialect for candidate discovery — so a Codex repo's skills (under
+     *  the Codex layout) are found, not silently missed by the default CC layout. */
+    readonly layout?: PluginLayout;
+    readonly dialect?: HarnessDialect;
 }
 /**
  * Per-harness probe wiring: the eval driver (runner+parse), how to build the

package/dist/scan-behavioral.js

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * `vigiles scan --trigger` — the BEHAVIORAL column of the scan report.
+ * `vigiles audit` model trigger tier — the BEHAVIORAL column of the audit report.
  *
  * Structural `scan`/`scanPlugin` is deterministic, no-model, CI-free — and stays
- * that way. This is the opt-in, model-gated column that stacks on top: for each
+ * that way. This is the model-gated column that stacks on top: for each
  * model-invocable skill in a plugin, it measures how reliably the description
  * actually FIRES (recall, + precision when irrelevant prompts are supplied),
  * reusing `measureTriggerRate`. It degrades honestly when the `claude` CLI / auth
@@ -131,8 +131,10 @@ async function probeSkill(ctx, name, ps) {
 async function probePluginTriggersWith(dir, promptSet, probe, opts = {}) {
     const ctx = { dir, opts, probe };
     // Only model-invocable, describable skills can auto-trigger; user-invoked and
-    // description-less ones can't, so they're not behavioral candidates.
-    const candidates = (0, scan_js_1.scanPlugin)(dir).skills.filter((s) => !s.userInvoked && s.hasDescription);
+    // description-less ones can't, so they're not behavioral candidates. Discover
+    // them with the resolved layout/dialect (default CC) so a Codex repo's skills
+    // aren't missed by the wrong layout.
+    const candidates = (0, scan_js_1.scanPlugin)(dir, opts.layout, opts.dialect).skills.filter((s) => !s.userInvoked && s.hasDescription);
     const results = [];
     for (const s of candidates) {
         const ps = promptSet[s.name];

package/dist/scan-trigger-suggest.d.ts

@@ -1,10 +1,15 @@
 /**
- * scan → trigger-tier nudge. When a plugin ships model-invocable skills AND a
- * real model is reachable, surface the (real-model) `scan --trigger` tier that
- * measures whether those skills actually FIRE (recall + precision). Pure
- * decision + helpers; the IO (prompt / scaffold write / running the measure)
- * lives in the CLI. Honors `great-agent-flow`: an agent (non-TTY / `--json` /
- * `--no-interactive`) is HINTED, never prompted — a `scan` must never hang.
+ * audit → the ONE read-vs-run decision. `audit` is a Lighthouse-style LOCAL
+ * report: a deterministic READ by default — safe + identical on every OS, nothing
+ * executes — NOT a CI step (CI uses `vigiles lint`, the deterministic gate). The
+ * executing checks (safety battery, live MCP resolution, skill-firing trigger-rate)
+ * run ONLY when there's a human to consent: at a TTY `audit` ASKS once (and
+ * remembers in `.vigilesrc.json` `audit.measure`); headless (an agent / `--json` /
+ * `--no-interactive` / a pipe) it stays a read + a one-line nudge — never hangs,
+ * never silently executes. There is deliberately NO execution flag: automation
+ * tests the harness through the `vigiles/testing` API + skills (the layered tiers),
+ * not through the report verb. The IO (prompt / run / remember) lives in the CLI;
+ * this is the pure decision + helpers.
  */
 /** Only the env vars that signal a reachable model (parse, don't validate). */
 export interface ModelEnv {
@@ -13,42 +18,74 @@ export interface ModelEnv {
     readonly CLAUDE_CODE_ENTRYPOINT?: string;
 }
 /**
- * Is a real model reachable for the eval / trigger tier? Either a metered API
- * key (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session
- * (`CLAUDECODE=1` / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter
- * drives the `claude` CLI on the user's subscription, no key needed. Keeping
- * this a tiny, env-only predicate (not a live probe) means it never spends a
- * token just to decide whether to suggest spending one.
+ * Is a real model reachable for the trigger tier? Either a metered API key
+ * (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session (`CLAUDECODE=1`
+ * / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter drives the `claude`
+ * CLI on the user's subscription, no key needed and $0 metered. A tiny env-only
+ * predicate (not a live probe), so it never spends a token just to decide.
  */
 export declare function hasModelAccess(env: ModelEnv): boolean;
-export type TriggerSuggestion = "prompt" | "hint" | "none";
-export interface SuggestOpts {
-    /** A real model is reachable (`hasModelAccess`). */
-    readonly modelAccess: boolean;
-    /** stdout is an interactive terminal (a human is watching). */
+/**
+ * Is the reachable model METERED (a paid API key) rather than a subscription?
+ * Only affects the consent DISCLOSURE wording (a metered key bills per token; a
+ * subscription is $0 metered) — the run/skip decision itself is consent-driven,
+ * not metered-driven.
+ */
+export declare function isMeteredAccess(env: ModelEnv): boolean;
+/** Why the executing checks were skipped (drives the "not run" nudge). */
+export type ExecuteSkipReason = "nothing" | "headless" | "remembered-no";
+/**
+ * What `audit` should do about the EXECUTING checks (battery + live MCP +
+ * trigger-rate), as ONE bundle:
+ * - `run`  — run them now (a remembered yes).
+ * - `ask`  — interactive human + something to run + no sticky choice: ask once,
+ *            then remember.
+ * - `skip` — stay a deterministic read; the `reason` drives a one-line nudge.
+ */
+export type ExecuteDecision = {
+    readonly kind: "run";
+} | {
+    readonly kind: "ask";
+} | {
+    readonly kind: "skip";
+    readonly reason: ExecuteSkipReason;
+};
+export interface ExecuteEnv {
+    /** Is there ANY executable surface — runnable hooks, an own-repo MCP server, or
+     *  a model-invocable skill? Nothing to run → never ask, never nudge. */
+    readonly hasExecutable: boolean;
+    /** Both stdin AND stdout are a terminal (a human who can answer + wait). */
     readonly isTTY: boolean;
-    /** Count of model-invocable, described skills worth measuring. */
-    readonly triggerableSkills: number;
-    /** `--json` — machine output; never decorate or prompt. */
+    /** `--json` — machine output; stays a read even at a TTY (never prompt). */
     readonly json: boolean;
-    /** `--no-interactive` — explicit agent/CI mode; hint, never prompt. */
+    /** `--no-interactive` / `--yes` — explicit agent/CI mode (never prompt). */
     readonly noInteractive: boolean;
+    /** Sticky remembered choice from `.vigilesrc.json` (`audit.measure`), or undefined. */
+    readonly remembered?: boolean;
 }
 /**
- * Decide how `scan` surfaces the trigger tier after its report:
- * - `"none"`   — no model-invocable skills, no model access, or `--json`.
- * - `"hint"`   — model access + skills but non-interactive (agent / CI / non-TTY
- *                / `--no-interactive`): a one-line, non-blocking hint.
- * - `"prompt"` — model access + skills + a human at a TTY: offer to set it up.
+ * Decide what `audit` does with the executing checks. Total + pure; the first
+ * matching rule wins. There is NO execution flag — `audit` is a local report, so
+ * the executing checks need a human to consent:
+ *  1. nothing executable → skip "nothing" (a clean read; no nudge)
+ *  2. headless (`--json` / `--no-interactive` / non-TTY — an agent, a pipe, CI) →
+ *     skip "headless" (no one to ask; automation uses the `vigiles/testing` API)
+ *  3. sticky no → skip "remembered-no"
+ *  4. sticky yes → run
+ *  5. interactive human, no sticky choice → ask (then remember)
+ */
+export declare function decideExecute(o: ExecuteEnv): ExecuteDecision;
+/**
+ * The one-line "executing checks not run" nudge for a skipped read (the
+ * no-silent-skips corollary). Returns null for `nothing` (nothing to run — not a
+ * gap). There is no flag to point at — `audit` runs them only interactively, and
+ * automation uses the `vigiles/testing` API.
  */
-export declare function decideTriggerSuggestion(o: SuggestOpts): TriggerSuggestion;
-/** The one-line, non-blocking hint (the agent/CI surface). */
-export declare function formatTriggerHint(dir: string, triggerableSkills: number): string;
+export declare function formatExecuteSkip(reason: ExecuteSkipReason): string | null;
 /**
  * A starter `--prompts` file (the real `TriggerPromptSet` shape: bare skill name
  * → `{ prompts, irrelevant }`). One entry per triggerable skill, with TODO
- * placeholders the user replaces with real requests. Deterministic; written
- * only on an explicit human "yes" so a plain `scan` never spends a token.
+ * placeholders the user replaces with real requests.
  */
 export declare function scaffoldTriggerPrompts(skillNames: readonly string[]): string;
 //# sourceMappingURL=scan-trigger-suggest.d.ts.map

package/dist/scan-trigger-suggest.js

@@ -1,24 +1,29 @@
 "use strict";
 /**
- * scan → trigger-tier nudge. When a plugin ships model-invocable skills AND a
- * real model is reachable, surface the (real-model) `scan --trigger` tier that
- * measures whether those skills actually FIRE (recall + precision). Pure
- * decision + helpers; the IO (prompt / scaffold write / running the measure)
- * lives in the CLI. Honors `great-agent-flow`: an agent (non-TTY / `--json` /
- * `--no-interactive`) is HINTED, never prompted — a `scan` must never hang.
+ * audit → the ONE read-vs-run decision. `audit` is a Lighthouse-style LOCAL
+ * report: a deterministic READ by default — safe + identical on every OS, nothing
+ * executes — NOT a CI step (CI uses `vigiles lint`, the deterministic gate). The
+ * executing checks (safety battery, live MCP resolution, skill-firing trigger-rate)
+ * run ONLY when there's a human to consent: at a TTY `audit` ASKS once (and
+ * remembers in `.vigilesrc.json` `audit.measure`); headless (an agent / `--json` /
+ * `--no-interactive` / a pipe) it stays a read + a one-line nudge — never hangs,
+ * never silently executes. There is deliberately NO execution flag: automation
+ * tests the harness through the `vigiles/testing` API + skills (the layered tiers),
+ * not through the report verb. The IO (prompt / run / remember) lives in the CLI;
+ * this is the pure decision + helpers.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasModelAccess = hasModelAccess;
-exports.decideTriggerSuggestion = decideTriggerSuggestion;
-exports.formatTriggerHint = formatTriggerHint;
+exports.isMeteredAccess = isMeteredAccess;
+exports.decideExecute = decideExecute;
+exports.formatExecuteSkip = formatExecuteSkip;
 exports.scaffoldTriggerPrompts = scaffoldTriggerPrompts;
 /**
- * Is a real model reachable for the eval / trigger tier? Either a metered API
- * key (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session
- * (`CLAUDECODE=1` / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter
- * drives the `claude` CLI on the user's subscription, no key needed. Keeping
- * this a tiny, env-only predicate (not a live probe) means it never spends a
- * token just to decide whether to suggest spending one.
+ * Is a real model reachable for the trigger tier? Either a metered API key
+ * (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session (`CLAUDECODE=1`
+ * / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter drives the `claude`
+ * CLI on the user's subscription, no key needed and $0 metered. A tiny env-only
+ * predicate (not a live probe), so it never spends a token just to decide.
  */
 function hasModelAccess(env) {
     return Boolean(env.ANTHROPIC_API_KEY ||
@@ -26,31 +31,59 @@ function hasModelAccess(env) {
         env.CLAUDE_CODE_ENTRYPOINT);
 }
 /**
- * Decide how `scan` surfaces the trigger tier after its report:
- * - `"none"`   — no model-invocable skills, no model access, or `--json`.
- * - `"hint"`   — model access + skills but non-interactive (agent / CI / non-TTY
- *                / `--no-interactive`): a one-line, non-blocking hint.
- * - `"prompt"` — model access + skills + a human at a TTY: offer to set it up.
+ * Is the reachable model METERED (a paid API key) rather than a subscription?
+ * Only affects the consent DISCLOSURE wording (a metered key bills per token; a
+ * subscription is $0 metered) — the run/skip decision itself is consent-driven,
+ * not metered-driven.
  */
-function decideTriggerSuggestion(o) {
-    if (o.json || o.triggerableSkills < 1 || !o.modelAccess)
-        return "none";
-    if (o.noInteractive || !o.isTTY)
-        return "hint";
-    return "prompt";
+function isMeteredAccess(env) {
+    return Boolean(env.ANTHROPIC_API_KEY);
 }
-/** The one-line, non-blocking hint (the agent/CI surface). */
-function formatTriggerHint(dir, triggerableSkills) {
-    const n = triggerableSkills;
-    return (`ℹ ${String(n)} model-invocable skill${n === 1 ? "" : "s"} + model access detected — ` +
-        `measure whether they actually FIRE (recall + precision) with:\n` +
-        `    vigiles scan ${dir} --trigger --prompts=trigger-prompts.json`);
+/**
+ * Decide what `audit` does with the executing checks. Total + pure; the first
+ * matching rule wins. There is NO execution flag — `audit` is a local report, so
+ * the executing checks need a human to consent:
+ *  1. nothing executable → skip "nothing" (a clean read; no nudge)
+ *  2. headless (`--json` / `--no-interactive` / non-TTY — an agent, a pipe, CI) →
+ *     skip "headless" (no one to ask; automation uses the `vigiles/testing` API)
+ *  3. sticky no → skip "remembered-no"
+ *  4. sticky yes → run
+ *  5. interactive human, no sticky choice → ask (then remember)
+ */
+function decideExecute(o) {
+    if (!o.hasExecutable)
+        return { kind: "skip", reason: "nothing" };
+    if (o.json || o.noInteractive || !o.isTTY)
+        return { kind: "skip", reason: "headless" };
+    if (o.remembered === false)
+        return { kind: "skip", reason: "remembered-no" };
+    if (o.remembered === true)
+        return { kind: "run" };
+    return { kind: "ask" };
+}
+/**
+ * The one-line "executing checks not run" nudge for a skipped read (the
+ * no-silent-skips corollary). Returns null for `nothing` (nothing to run — not a
+ * gap). There is no flag to point at — `audit` runs them only interactively, and
+ * automation uses the `vigiles/testing` API.
+ */
+function formatExecuteSkip(reason) {
+    switch (reason) {
+        case "nothing":
+            return null;
+        case "headless":
+            return ("\nℹ Executing checks (safety battery · live MCP · skill firing) skipped — " +
+                "`audit` runs them only interactively (a terminal). For automation, test the " +
+                "harness with the `vigiles/testing` API.");
+        case "remembered-no":
+            return ("\nℹ Executing checks not run (you disabled them — edit .vigilesrc.json " +
+                "`audit.measure` to re-enable).");
+    }
 }
 /**
  * A starter `--prompts` file (the real `TriggerPromptSet` shape: bare skill name
  * → `{ prompts, irrelevant }`). One entry per triggerable skill, with TODO
- * placeholders the user replaces with real requests. Deterministic; written
- * only on an explicit human "yes" so a plain `scan` never spends a token.
+ * placeholders the user replaces with real requests.
  */
 function scaffoldTriggerPrompts(skillNames) {
     const obj = {};

package/dist/scan.d.ts

@@ -1,5 +1,5 @@
 /**
- * `vigiles scan <dir>` — point vigiles at any plugin/repo and see what it ships
+ * `vigiles audit <dir>` — point vigiles at any plugin/repo and see what it ships
  * and what's broken, with **no model and no API key**.
  *
  * This is the deterministic substrate under the plugin/skill leaderboard
@@ -27,14 +27,20 @@ export interface ScanSkill {
     readonly name: string;
     readonly path: string;
     readonly hasDescription: boolean;
+    /**
+     * The skill's effective description (frontmatter `description`, else the first
+     * body paragraph — the same text the selector keys on), trimmed; `undefined`
+     * when neither exists. Feeds the model trigger tier's auto-generated probes.
+     */
+    readonly description?: string;
     readonly userInvoked: boolean;
     /**
      * The description's dominant script when it DIFFERS from the expected one
      * (default `"Latin"`), else null. The model's skill-selection context is
      * English-centric, so a description in another script carries a cross-language
      * trigger risk — it may under-fire on English prompts. A RISK flag, not a
-     * defect (a language-matched audience is fine); measure the real gap with
-     * `scan --trigger`.
+     * defect (a language-matched audience is fine); measure the real gap with the
+     * `audit` trigger tier / `measureTriggerRate`.
      */
     readonly descriptionScript: Script | null;
 }
@@ -86,8 +92,25 @@ export interface FrontmatterValueIssue {
 /** ok = file present; missing = referenced but absent; unresolved = path still has an unexpanded var, can't check. */
 export type HookStatus = "ok" | "missing" | "unresolved";
 export interface ScanHook {
+    /**
+     * The full hook command as it would be run (plugin-root token expanded, shell
+     * quotes stripped). Present on script-based hooks; empty string on hooks whose
+     * command is entirely inline (no script file) — but inline hooks never appear
+     * in `hooks[]`, they are counted by `inlineHooks`, so in practice `command` is
+     * always non-empty when a `ScanHook` is in the list.
+     */
+    readonly command: string;
     readonly script: string;
     readonly status: HookStatus;
+    /**
+     * The hook EVENT this script is registered under (`PreToolUse`, `PostToolUse`,
+     * `SessionStart`, …), when it can be determined from the canonical
+     * object-keyed-by-event settings shape; `undefined` for a non-object/array
+     * config. The safety battery uses it to test only the blocking-capable
+     * `PreToolUse` guards — so a `SessionStart`/`PostToolUse` hook isn't unfairly
+     * scored against "does it block rm -rf".
+     */
+    readonly event?: string;
 }
 /**
  * The repo's top-level instruction file (`CLAUDE.md` / `AGENTS.md`), if present.
@@ -194,14 +217,16 @@ export declare function preferCompiledHooksMessage(count: number): string;
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 export declare function scanPlugin(dir: string, layout?: PluginLayout, dialect?: HarnessDialect): ScanReport;
 /**
- * LIVE MCP tool resolution for a scanned plugin — the opt-in (`scan --verify-mcp`)
- * dynamic check no static linter can do: it STARTS each declared MCP server and
- * checks every `mcp__server__tool` the plugin's agents reference actually exists on
- * it (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
+ * LIVE MCP tool resolution for a scanned plugin — the dynamic check no static
+ * linter can do: it STARTS each declared MCP server and checks every
+ * `mcp__server__tool` the plugin's agents reference actually exists on it
+ * (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
  * already-computed `report` (its agents' tool lists) + the declared server configs;
  * returns `[]` when the plugin declares no MCP servers (nothing to start). Async +
- * side-effecting (spawns servers) — which is exactly why it's opt-in, not a default
- * lint rule. See `verifyMcpContractTools` (core/mcp.ts).
+ * side-effecting (spawns servers) — so `audit` runs it by default only for the
+ * user's OWN repo (own-repo, like running your own tools); a FOREIGN plugin's
+ * servers are never spawned, and `--fast` opts out. See `verifyMcpContractTools`
+ * (core/mcp.ts).
  */
 export declare function verifyLiveMcpTools(report: ScanReport, layout: PluginLayout, dialect: HarnessDialect, timeoutMs?: number): Promise<McpContractToolError[]>;
 /** Render the live MCP tool-check result (human-readable). */
@@ -227,7 +252,7 @@ export interface MarketplaceInfo {
  * Read a `marketplace.json` beside the layout's plugin manifest and classify its
  * members into on-disk vs external. Returns `null` when `dir` is not a
  * marketplace. The source of truth behind {@link expandMarketplace} and the
- * curated-marketplace report in `vigiles scan`.
+ * curated-marketplace report in `vigiles audit`.
  */
 export declare function inspectMarketplace(dir: string, layout?: PluginLayout): MarketplaceInfo | null;
 /**
@@ -235,7 +260,7 @@ export declare function inspectMarketplace(dir: string, layout?: PluginLayout):
  * plugin manifest, e.g. `.claude-plugin/marketplace.json`), expand it into the
  * absolute dirs of its member plugins. Returns `null` when there's no
  * marketplace, `[]` when it's a marketplace whose members are all external (not
- * on disk). Used by `vigiles scan` to rank a whole marketplace — wshobson/agents
+ * on disk). Used by `vigiles audit` to rank a whole marketplace — wshobson/agents
  * alone ships 80+ plugins under one `marketplace.json`. See {@link inspectMarketplace}.
  */
 export declare function expandMarketplace(dir: string, layout?: PluginLayout): string[] | null;