vigiles 15.0.2 → 15.0.3

package/dist/core/layout.d.ts

@@ -50,6 +50,19 @@ export interface PluginLayout {
     readonly materializeRoot: string;
     /** Env token expanded to the plugin's absolute root in hook commands. */
     readonly pluginRootToken: string;
+    /**
+     * Tokens that root a path at the PROJECT being scanned, braced form
+     * (`${CLAUDE_PROJECT_DIR}`); the unbraced spelling is derived. Optional — a
+     * harness with no such variable omits it.
+     *
+     * 🔴 SEPARATE FROM {@link pluginRootToken}, and its absence made a whole
+     * surface kind invisible. `hookScripts` stripped only the plugin token, so a
+     * project's own `"$CLAUDE_PROJECT_DIR/.claude/hooks/x.sh"` — Claude Code's
+     * DOCUMENTED spelling for a project hook, because hooks do not run with a
+     * stable cwd — failed `existsSync` and was dropped. MEASURED on a real
+     * consumer repo: `audit` listed sixteen hooks and the SURFACE list held zero.
+     */
+    readonly projectRootTokens?: readonly string[];
     /** Standalone MCP config file, e.g. `.mcp.json`. */
     readonly mcpConfigFile: string;
     /** Manifest key declaring MCP servers, e.g. `mcpServers`. */

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

@@ -34,6 +34,11 @@
  * footgun note, not a hard defect), an inherits-all trifecta is reported as
  * `"advisory"`; an EXPLICIT all-three contract is the `"hard"` flag.
  *
+ * 🔴 SUBAGENTS ONLY. Everything above is the SUBAGENT reading, where `tools:` is a
+ * documented rail that really does bound the unit. It is NOT how a SKILL works —
+ * a skill's `allowed-tools:` is a PRE-APPROVAL, not a fence. See
+ * {@link skillTrifectaIssue} for the skill path and the measurement behind it.
+ *
  * 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`
@@ -62,6 +67,19 @@ export interface TrifectaLegs {
  *                 reported as advisory in line with the inherits-all stance.
  */
 export type TrifectaSeverity = "hard" | "advisory";
+/**
+ * How much of a fence a SKILL's `disallowed-tools:` actually is — set only on
+ * findings produced by {@link skillTrifectaIssue}, absent on subagent findings.
+ *
+ * - `"none"` — no `disallowed-tools:` line (or an unreadable block, which yields
+ *   the same thing): the skill inherits every tool the session grants. This is
+ *   the DEFAULT state of every skill in the ecosystem, which is why the report
+ *   aggregates it into one line instead of repeating it per skill.
+ * - `"ineffective"` — a `disallowed-tools:` line exists but does not deny every
+ *   built-in supplier of any one leg, so no leg is closed. That one is per-skill:
+ *   an author who believed they had fenced and had not.
+ */
+export type SkillFenceState = "none" | "ineffective";
 /**
  * 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`
@@ -74,7 +92,38 @@ export interface TrifectaFinding {
     readonly legs: TrifectaLegs;
     /** A ready-to-show, actionable message. */
     readonly message: string;
+    /**
+     * SKILLS ONLY — the fence state behind the finding ({@link SkillFenceState}).
+     * Absent on subagent findings, whose `tools:` rail is a different mechanism.
+     * The report reads it to decide aggregate-vs-per-unit presentation.
+     */
+    readonly fence?: SkillFenceState;
 }
+/**
+ * Does a `Bash(...)` grant still supply the shell's legs — reading a secret and
+ * curling it out — or has it been narrowed to a command that cannot?
+ *
+ * Narrowing the grant is a remedy this tool RECOMMENDS, so the reading has to be able
+ * to see a narrowed grant as narrowed: `Bash(node ./scripts/log.mjs:*)` was once read
+ * as plain `Bash` — the whole shell, in both leg A and leg C — and an author who took
+ * the advice saw the score not move. But the fix for that overshot into the opposite
+ * error, and the opposite error is the one that matters (see {@link EFFECT_FREE}), so
+ * the answer is now: a grant is bounded ONLY when it pins a program from that list.
+ *
+ * The honest consequence, stated rather than hidden: narrowing `Bash` to a script of
+ * your own (`node ./ledger.mjs`) no longer drops a leg, because nothing here has read
+ * that script. The remedy that still works is to drop a leg the checker can SEE — fence
+ * the tool off, or narrow to a command whose effects are enumerable.
+ *
+ *   Bash            no restriction at all
+ *   Bash(*)         Bash(:*)        the wildcard forms
+ *   Bash(node:*)    Bash(node x.mjs:*)   an interpreter runs whatever it is handed
+ *   Bash(sh ...)    Bash(curl ...)  the shell, and the pinned exfiltrator
+ *   Bash(echo ready:*)                   bounded — and only this shape is
+ *
+ * When in doubt it returns true (keeps the legs): a false "you are exposed" costs the
+ * author an argument, a false "you are safe" costs them the finding.
+ */
 export declare function bashGrantIsUnbounded(raw: string): boolean;
 /**
  * Classify each tool in a declared contract into the trifecta legs it supplies.
@@ -127,4 +176,48 @@ export interface TrifectaContext {
  *   inherits-all, the `"advisory"` finding. Never the other way round.
  */
 export declare function lethalTrifectaIssues(tools: readonly string[], dialect: HarnessDialect, ctx?: TrifectaContext): TrifectaFinding | null;
+/** The legs a `disallowed-tools:` list leaves standing, naming the suppliers. */
+export declare function skillFenceLegs(disallowed: readonly string[], dialect: HarnessDialect): TrifectaLegs;
+/**
+ * Whether THIS harness understands a skill-level `disallowed-tools:` at all.
+ *
+ * Read off the dialect record that already exists — `skillFrontmatter` is exactly
+ * "which SKILL.md keys this harness understands", and `disallowed-tools` is one of
+ * the Claude-Code-only ones. No new capability flag: a second field saying the
+ * same thing is a second thing to keep true, and the compiler already branches on
+ * this one (`renderSkillFrontmatter` emits the tool keys under `"claude-code"` and
+ * omits them under `"minimal"`).
+ */
+export declare function dialectSupportsSkillFence(dialect: HarnessDialect): boolean;
+/**
+ * The lethal-trifecta finding for a MODEL-INVOCABLE SKILL, computed from its
+ * `disallowed-tools:` — the only skill frontmatter field measured to remove a
+ * tool. `allowed-tools:` is not an input here, on purpose: it is a pre-approval,
+ * and treating it as a bound is the defect this function exists to correct (see
+ * the block comment above for the measurement).
+ *
+ * 🔴 AND IT IS A CLAUDE-CODE MECHANISM, which this applied to every harness. On a
+ * Codex repo (`skillFrontmatter: "minimal"` — name + description only, and our own
+ * compiler drops the tool keys there) every skill was reported as holding all
+ * three legs, scored against Safety, and handed the remedy "add a
+ * `disallowed-tools:` line". That line is INERT in Codex: the author does the
+ * work, the harness ignores the key, the finding returns, and the score never
+ * moves. A remedy the target cannot apply is worse than no finding — it is a floor
+ * dressed up as a defect, and it teaches people that the Safety number is fake.
+ *
+ * So the detector runs only where the fence exists ({@link dialectSupportsSkillFence}).
+ * This is a claim about the MECHANISM, not about the risk: a Codex skill really
+ * does hold every leg, and bounding it is a session/config-level question that
+ * belongs to a Codex-specific detector, not to a Claude Code one applied by
+ * default. Subagent findings are unaffected — `tools:` is a different mechanism,
+ * with its own dialect handling.
+ *
+ * @param disallowed `disallowed-tools:` as declared, or `null` when the line is
+ *   absent — the two are NOT the same: an explicit empty list still denies nothing,
+ *   but the message should not tell an author who wrote the line that they didn't.
+ * @returns `null` once the fence closes at least one leg (Rule of Two satisfied,
+ *   among the built-ins — see {@link FENCE_SUPPLIERS} for the stated limit), and
+ *   `null` for any harness with no skill fence to close it with.
+ */
+export declare function skillTrifectaIssue(disallowed: readonly string[] | null, dialect: HarnessDialect, ctx?: TrifectaContext): TrifectaFinding | null;
 //# sourceMappingURL=lethal-trifecta.d.ts.map