vigiles 5.0.1 → 5.2.0

package/README.md

@@ -30,19 +30,18 @@ deterministic layer for it, and does two independent things — adopt either, or
 | **🧪 Test** | Hooks, skills, and subagents are code. vigiles tests they _do their job_ — and almost all of it is **deterministic, no API key**; the real-model evals run on your **Claude subscription**, not metered tokens. **[→](docs/harness-testing.md)** |
 
 Pick the one that hurts today. **Works with Claude Code and Codex**
-([`vigiles/codex`](docs/harnesses.md)) behind a five-port adapter;
-[custom adapters welcome](docs/authoring-an-adapter.md).
+([`vigiles/codex`](docs/harnesses.md)), and you can
+[teach it your own harness](docs/authoring-an-adapter.md).
 
 ## Quick start
 
 **Paste into Claude Code or Codex:**
 
 ```text
-Install vigiles in this repo and run it. Verify my CLAUDE.md / AGENTS.md
-references and show me what's stale, then write and run a harness test for one
-of my hooks or skills. Use good defaults (lint + test, non-interactive), but
-ask me first whether to gate it in CI, whether to add a real-model eval, and
-whether to enforce strictly (--strict).
+Set up vigiles in this repo with good defaults (lint + test, non-interactive).
+Verify my CLAUDE.md / AGENTS.md references and show me what's stale, then write
+and run a harness test for one of my hooks or skills. Ask me first before gating
+it in CI, adding a real-model eval, or enforcing strictly (--strict).
 ```
 
 Or do it yourself:
@@ -95,6 +94,12 @@ File paths, scripts, and code symbols — plus linter rules across **7 catalogs*
 step up to a typed `.spec.ts` (compiled to CLAUDE.md, compiler-grade) when you want
 it. **[Full guide →](docs/verifying-instruction-files.md)**
 
+**Same cross-reference, any plugin.** `npx vigiles scan` checks a plugin's
+_contracts_ — every subagent tool, `mcp__server__tool`, `mcp_tool` hook, hook
+event, and script path actually **exists and resolves**, not just parses (valid
+YAML ≠ a tool that's real). A **superset of Anthropic's `claude plugin validate`**,
+no key. **[Audit any plugin →](docs/cli.md#scan-dir)**
+
 ## ② Test — does your harness do its job?
 
 A hook can be wired wrong. A skill's description can fail to trigger — or hijack
@@ -132,8 +137,9 @@ That's why you can eval your harness on every change, not just once.
 
 ## More
 
-- **[CLI & GitHub Action →](docs/cli.md)** — every command, the Action (inputs / output / versioning), the Claude Code plugin, and the five `lint` rules.
-- **[Skills →](docs/skills.md)** — consumer skills installed as a Claude Code plugin: `/plugin marketplace add zernie/vigiles` then `/plugin install vigiles@vigiles` (or let `vigiles init` do it). The model-invocable ones (`test-harness`, `strengthen`, `edit-spec`) fire on their own — ask _"test my skills"_, _"strengthen my rules"_, or _"add a rule to CLAUDE.md"_ and the agent reaches for them; `migrate-to-spec` and `linter-docs` are user-invoked.
+- **[Plugin health leaderboard →](docs/cli.md#scan-dir)** — point `scan` at a marketplace (e.g. `wshobson/agents`) and it ranks every plugin by structural health (0–100, A–F), worst issues first — still **no key**. Add `--trigger` for the model-gated column: do the skills actually fire?
+- **[CLI & GitHub Action →](docs/cli.md)** — every command, the Action (inputs / output / versioning), and the Claude Code plugin. The full **[lint rules matrix →](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix)** lives with the linting guide.
+- **[Skills →](docs/skills.md)** — consumer skills installed as a Claude Code plugin: `/plugin marketplace add zernie/vigiles` then `/plugin install vigiles@vigiles` (or let `vigiles init` do it). The model-invocable ones (`test-harness`, `strengthen`, `edit-spec`) fire on their own — ask _"test my skills"_, _"strengthen my rules"_, or _"add a rule to CLAUDE.md"_ and the agent reaches for them; `adopt-spec` and `linter-docs` are user-invoked.
 - **[Docs index →](docs/README.md)** · **[Research →](research/README.md)** · **[Related tools →](docs/related-tools.md)** (ast-grep, Dependency Cruiser, Ruler, rulesync).
 - Companion to [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need).
 

package/dist/adapters/claude-code/adapter.js

@@ -23,6 +23,7 @@ exports.claudeCodeAdapter = {
         referenceVerification: true,
         harnessTesting: true,
         shellHooks: true,
+        subagents: true,
     },
     dialect: dialect_js_1.claudeCodeDialect,
     layout: layout_js_1.claudeCodeLayout,

package/dist/adapters/claude-code/agent-runtime.d.ts

@@ -22,6 +22,7 @@
  * (mirrors `.vigiles/active-skill.json`). The decision logic below is
  * harness-agnostic and fully testable.
  */
+import type { PurityLevel } from "../../core/effects.js";
 /**
  * Parse an agent's allowed-tools contract from its compiled markdown.
  *
@@ -31,6 +32,24 @@
  * an empty list (`tools:` with nothing after it) means "no tools allowed".
  */
 export declare function parseAgentTools(markdown: string): string[] | null;
+/**
+ * Parse a comma/array tool list under an arbitrary frontmatter `key` (e.g.
+ * `tools:` or `disallowedTools:`) via the shared lenient reader
+ * (core/frontmatter-read.ts): a real YAML parse (so `key: [Read, "Bash"]` is a
+ * native array and `key: Read, Bash` a comma scalar) with a regex salvage when
+ * the block is malformed — the rail still reads the contract. `null` when the key
+ * is absent (inherits all), `[]` when present-but-empty (no tools). Shared by the
+ * rail (`tools:`) and the `disallowed-tools-contract` scan/lint.
+ */
+export declare function parseAgentToolList(markdown: string, key: string): string[] | null;
+/**
+ * Parse the declared purity floor from a compiled agent's `.md` — the
+ * `<!-- vigiles:purity:LEVEL -->` marker `compile` emits (see `purityMarker`).
+ * Returns null when no marker is present (the unit declared no floor, so the
+ * purity gate imposes no constraint). The single source of truth the runtime
+ * gate reads, exactly like `tools:` for the tool-contract rail.
+ */
+export declare function parseAgentPurity(markdown: string): PurityLevel | null;
 export interface PreToolDecision {
     /** Whether the tool call is allowed (true) or blocked (false). */
     readonly allow: boolean;
@@ -54,11 +73,16 @@ export declare function clearActiveAgent(cwd: string): void;
 /** The path of the active agent's compiled `.md`, or null when none is active. */
 export declare function readActiveAgent(cwd: string): string | null;
 /**
- * PreToolUse-hook decision. If an agent is active, parse its compiled `.md`
- * tool contract and allow the call only when the tool is in the allowlist;
- * otherwise block and tell the model which tools it may use. With no active
- * agent (or an agent that inherits all tools), always allow — the rail only
- * constrains agents that declared a contract.
+ * PreToolUse-hook decision. If an agent is active, enforce BOTH deterministic
+ * rails its compiled `.md` declares, in order:
+ *
+ *  1. the tool-contract rail (`tools:`) — allow only listed tools;
+ *  2. the purity gate (`vigiles:purity:`) — allow only calls within the declared
+ *     effect floor, refining `Bash` by the live `command` (`decidePurityGate`).
+ *
+ * The first to deny wins, feeding its reason back to the model. With no active
+ * agent (or one that declared neither contract), always allow — the rails only
+ * constrain agents that opted in.
  */
-export declare function evaluatePreToolUse(cwd: string, tool: string): PreToolDecision;
+export declare function evaluatePreToolUse(cwd: string, tool: string, command?: string): PreToolDecision;
 //# sourceMappingURL=agent-runtime.d.ts.map

package/dist/adapters/claude-code/agent-runtime.js

@@ -25,6 +25,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseAgentTools = parseAgentTools;
+exports.parseAgentToolList = parseAgentToolList;
+exports.parseAgentPurity = parseAgentPurity;
 exports.decidePreToolUse = decidePreToolUse;
 exports.setActiveAgent = setActiveAgent;
 exports.clearActiveAgent = clearActiveAgent;
@@ -32,28 +34,13 @@ exports.readActiveAgent = readActiveAgent;
 exports.evaluatePreToolUse = evaluatePreToolUse;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const frontmatter_read_js_1 = require("../../core/frontmatter-read.js");
+const effects_js_1 = require("../../core/effects.js");
+const dialect_js_1 = require("./dialect.js");
+const effect_region_js_1 = require("./effect-region.js");
 // ---------------------------------------------------------------------------
 // Parse the tool contract from a compiled agent .md
 // ---------------------------------------------------------------------------
-/** Extract the YAML frontmatter block (between the first pair of `---` fences). */
-function extractFrontmatter(markdown) {
-    const lines = markdown.split("\n");
-    let start = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (lines[i].trim() === "---") {
-            start = i;
-            break;
-        }
-    }
-    if (start === -1)
-        return null;
-    for (let i = start + 1; i < lines.length; i++) {
-        if (lines[i].trim() === "---") {
-            return lines.slice(start + 1, i).join("\n");
-        }
-    }
-    return null;
-}
 /**
  * Parse an agent's allowed-tools contract from its compiled markdown.
  *
@@ -63,16 +50,31 @@ function extractFrontmatter(markdown) {
  * an empty list (`tools:` with nothing after it) means "no tools allowed".
  */
 function parseAgentTools(markdown) {
-    const fm = extractFrontmatter(markdown);
-    if (fm === null)
-        return null;
-    const match = /^tools:[ \t]*(.*)$/m.exec(fm);
-    if (!match)
-        return null;
-    return match[1]
-        .split(",")
-        .map((t) => t.trim())
-        .filter((t) => t.length > 0);
+    return parseAgentToolList(markdown, "tools");
+}
+/**
+ * Parse a comma/array tool list under an arbitrary frontmatter `key` (e.g.
+ * `tools:` or `disallowedTools:`) via the shared lenient reader
+ * (core/frontmatter-read.ts): a real YAML parse (so `key: [Read, "Bash"]` is a
+ * native array and `key: Read, Bash` a comma scalar) with a regex salvage when
+ * the block is malformed — the rail still reads the contract. `null` when the key
+ * is absent (inherits all), `[]` when present-but-empty (no tools). Shared by the
+ * rail (`tools:`) and the `disallowed-tools-contract` scan/lint.
+ */
+function parseAgentToolList(markdown, key) {
+    return (0, frontmatter_read_js_1.frontmatterList)((0, frontmatter_read_js_1.readFrontmatter)(markdown), key);
+}
+const PURITY_RE = /<!--\s*vigiles:purity:(pure|bounded|unrestricted)\s*-->/;
+/**
+ * Parse the declared purity floor from a compiled agent's `.md` — the
+ * `<!-- vigiles:purity:LEVEL -->` marker `compile` emits (see `purityMarker`).
+ * Returns null when no marker is present (the unit declared no floor, so the
+ * purity gate imposes no constraint). The single source of truth the runtime
+ * gate reads, exactly like `tools:` for the tool-contract rail.
+ */
+function parseAgentPurity(markdown) {
+    const m = PURITY_RE.exec(markdown);
+    return m ? m[1] : null;
 }
 /**
  * Decide whether `tool` is allowed under an agent's tool contract. Pure, so the
@@ -128,20 +130,47 @@ function readActiveAgent(cwd) {
 // PreToolUse-hook decision
 // ---------------------------------------------------------------------------
 /**
- * PreToolUse-hook decision. If an agent is active, parse its compiled `.md`
- * tool contract and allow the call only when the tool is in the allowlist;
- * otherwise block and tell the model which tools it may use. With no active
- * agent (or an agent that inherits all tools), always allow — the rail only
- * constrains agents that declared a contract.
+ * PreToolUse-hook decision. If an agent is active, enforce BOTH deterministic
+ * rails its compiled `.md` declares, in order:
+ *
+ *  1. the tool-contract rail (`tools:`) — allow only listed tools;
+ *  2. the purity gate (`vigiles:purity:`) — allow only calls within the declared
+ *     effect floor, refining `Bash` by the live `command` (`decidePurityGate`).
+ *
+ * The first to deny wins, feeding its reason back to the model. With no active
+ * agent (or one that declared neither contract), always allow — the rails only
+ * constrain agents that opted in.
  */
-function evaluatePreToolUse(cwd, tool) {
+function evaluatePreToolUse(cwd, tool, command) {
     const agentPath = readActiveAgent(cwd);
     if (!agentPath)
         return { allow: true, message: "" };
     const full = (0, node_path_1.resolve)(cwd, agentPath);
     if (!(0, node_fs_1.existsSync)(full))
         return { allow: true, message: "" };
-    const allowed = parseAgentTools((0, node_fs_1.readFileSync)(full, "utf-8"));
-    return decidePreToolUse(allowed, tool);
+    const md = (0, node_fs_1.readFileSync)(full, "utf-8");
+    // 1) Tool-contract rail — the declared allowlist.
+    const rail = decidePreToolUse(parseAgentTools(md), tool);
+    if (!rail.allow)
+        return rail;
+    // 2) Purity gate — the declared effect floor, refined by the live command.
+    //    If an effect boundary is declared, tighten to "pure" outside it and apply
+    //    the declared purity (or "unrestricted") inside.
+    const purity = parseAgentPurity(md);
+    const boundary = (0, effect_region_js_1.hasEffectBoundary)(md);
+    if (boundary) {
+        const effective = (0, effect_region_js_1.readEffectActive)(cwd)
+            ? (purity ?? "unrestricted")
+            : "pure";
+        const gate = (0, effects_js_1.decidePurityGate)(effective, tool, command, dialect_js_1.claudeCodeDialect);
+        if (!gate.allow)
+            return gate;
+    }
+    else if (purity) {
+        const gate = (0, effects_js_1.decidePurityGate)(purity, tool, command, dialect_js_1.claudeCodeDialect);
+        if (!gate.allow)
+            return gate;
+    }
+    return { allow: true, message: "" };
 }
 //# sourceMappingURL=agent-runtime.js.map

package/dist/adapters/claude-code/dialect.js

@@ -9,9 +9,13 @@ exports.claudeCodeDialect = {
         "Read",
         "Write",
         "Edit",
+        "MultiEdit",
         "Bash",
+        "BashOutput",
+        "KillBash",
         "Grep",
         "Glob",
+        "LS",
         "WebSearch",
         "WebFetch",
         "NotebookEdit",
@@ -30,12 +34,24 @@ exports.claudeCodeDialect = {
         "WaitForMcpServers",
     ],
     mcpToolPattern: /^mcp__[a-z0-9_-]+__[a-z0-9_-]+$/i,
+    // Claude Code's own built-in MCP server: the IDE integration provides
+    // `mcp__ide__getDiagnostics` / `mcp__ide__executeCode` at runtime without any
+    // plugin declaring it, so a contract that lists those must NOT be flagged as
+    // referencing an undeclared server (the mcp-tool-resolves allowlist).
+    knownMcpServers: ["ide"],
+    // The real Claude Code hook events. (Was wrong: PreSession/PostSession don't
+    // exist; SessionStart/SessionEnd/Stop/SubagentStop/UserPromptSubmit/PreCompact
+    // were missing — verified against the events real plugins register.)
     hookEvents: [
         "PreToolUse",
         "PostToolUse",
-        "PreSession",
-        "PostSession",
+        "UserPromptSubmit",
         "Notification",
+        "Stop",
+        "SubagentStop",
+        "PreCompact",
+        "SessionStart",
+        "SessionEnd",
     ],
     // Claude Code natively reads CLAUDE.md only — it does NOT auto-load AGENTS.md
     // (anthropics/claude-code#34235 is open; AGENTS.md works solely via an
@@ -47,5 +63,24 @@ exports.claudeCodeDialect = {
     // Claude Code reads the full SKILL.md frontmatter set (description,
     // disable-model-invocation, argument-hint, …).
     skillFrontmatter: "claude-code",
+    // Tools that produce side effects in Claude Code. The complement — the
+    // read-only tools — are: Read, Grep, Glob, LS, ToolSearch (and LSP/Agent
+    // which are not in the subagent catalog). Bash is side-effecting because
+    // `cat` and `rm -rf` are the same tool at the tool-name level — the
+    // sandbox is the only closure for subprocess effects.
+    sideEffectingTools: [
+        "Bash",
+        "BashOutput",
+        "KillBash",
+        "Edit",
+        "MultiEdit",
+        "Write",
+        "NotebookEdit",
+        "WebFetch",
+        "WebSearch",
+        "Skill",
+        "Task",
+        "TodoWrite",
+    ],
 };
 //# sourceMappingURL=dialect.js.map

package/dist/adapters/claude-code/effect-region.d.ts

@@ -0,0 +1,9 @@
+/** Record that the agent has entered an effect boundary. */
+export declare function setEffectActive(cwd: string): void;
+/** Clear the effect-active marker (the agent exited the effect boundary). */
+export declare function clearEffectActive(cwd: string): void;
+/** True iff the agent is currently inside an effect boundary. Tolerates malformed file. */
+export declare function readEffectActive(cwd: string): boolean;
+/** True iff the compiled markdown declares an effect boundary (`<!-- vigiles:effect -->`). */
+export declare function hasEffectBoundary(markdown: string): boolean;
+//# sourceMappingURL=effect-region.d.ts.map

package/dist/adapters/claude-code/effect-region.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setEffectActive = setEffectActive;
+exports.clearEffectActive = clearEffectActive;
+exports.readEffectActive = readEffectActive;
+exports.hasEffectBoundary = hasEffectBoundary;
+/**
+ * Effect-boundary position-aware state tracking.
+ * Mirrors active-unit tracking (.vigiles/active-agent.json / .vigiles/active-skill.json).
+ * The PreToolUse hook reads this file to decide whether the agent is inside an
+ * effect boundary (set by `vigiles effect-enter`) or outside it.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const EFFECT_ACTIVE_PATH = ".vigiles/effect-active.json";
+/** Record that the agent has entered an effect boundary. */
+function setEffectActive(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, EFFECT_ACTIVE_PATH);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, node_fs_1.writeFileSync)(p, JSON.stringify({ active: true }) + "\n");
+}
+/** Clear the effect-active marker (the agent exited the effect boundary). */
+function clearEffectActive(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, EFFECT_ACTIVE_PATH);
+    if ((0, node_fs_1.existsSync)(p))
+        (0, node_fs_1.rmSync)(p);
+}
+/** True iff the agent is currently inside an effect boundary. Tolerates malformed file. */
+function readEffectActive(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, EFFECT_ACTIVE_PATH);
+    if (!(0, node_fs_1.existsSync)(p))
+        return false;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+        return parsed.active === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True iff the compiled markdown declares an effect boundary (`<!-- vigiles:effect -->`). */
+function hasEffectBoundary(markdown) {
+    return markdown.includes("<!-- vigiles:effect -->");
+}
+//# sourceMappingURL=effect-region.js.map

package/dist/adapters/claude-code/layout.js

@@ -9,6 +9,9 @@ exports.claudeCodeLayout = {
     settingsFormat: "json",
     instructionFile: "CLAUDE.md",
     surfaceDirs: ["skills", "agents", "commands"],
+    skillDir: "skills",
+    agentDir: "agents",
+    commandDir: "commands",
     materializeRoot: ".claude",
     pluginRootToken: "${CLAUDE_PLUGIN_ROOT}",
     mcpConfigFile: ".mcp.json",

package/dist/adapters/claude-code/skill-runtime.d.ts

@@ -20,6 +20,7 @@
  * (`vigiles run-skill`). It is not a silent hook and runs nothing the spec
  * didn't declare as a gate.
  */
+import type { PurityLevel } from "../../core/effects.js";
 export type RuntimeGate = {
     readonly kind: "cmd";
     readonly command: string;
@@ -86,6 +87,30 @@ export declare function setActiveSkill(cwd: string, skillPath: string): void;
 export declare function clearActiveSkill(cwd: string): void;
 /** The path of the active skill, or null when none is in progress. */
 export declare function readActiveSkill(cwd: string): string | null;
+/**
+ * Parse the declared purity floor from a compiled SKILL.md — the
+ * `<!-- vigiles:purity:LEVEL -->` marker `compileSkill` emits (see
+ * `purityMarker` in compile.ts). Returns null when no marker is present (the
+ * skill declared no floor, so the purity gate imposes no constraint). Mirrors
+ * `parseAgentPurity` in agent-runtime.ts.
+ */
+export declare function parseSkillPurity(markdown: string): PurityLevel | null;
+/** A runtime allow/deny decision (mirrors PreToolDecision in agent-runtime.ts). */
+export interface SkillPreToolDecision {
+    /** Whether the tool call is allowed (true) or blocked (false). */
+    readonly allow: boolean;
+    /** Message fed back to the model on a block; empty on allow. */
+    readonly message: string;
+}
+/**
+ * PreToolUse purity gate for skills. Mirrors `evaluatePreToolUse` in
+ * agent-runtime.ts, but enforces ONLY the purity floor — skills have no
+ * tools-allowlist rail (that's a separate, future concern). If a skill is
+ * active and declares a `vigiles:purity:` marker, `decidePurityGate` checks
+ * the live call (refining `Bash` by the concrete command via `isReadOnlyBash`).
+ * With no active skill, a missing `.md`, or no purity marker, always allows.
+ */
+export declare function evaluateSkillPreToolUse(cwd: string, tool: string, command?: string): SkillPreToolDecision;
 export interface StopDecision {
     /** Whether the agent may stop (true) or must keep working (false). */
     readonly allow: boolean;

package/dist/adapters/claude-code/skill-runtime.js

@@ -30,10 +30,15 @@ exports.runSkillGates = runSkillGates;
 exports.setActiveSkill = setActiveSkill;
 exports.clearActiveSkill = clearActiveSkill;
 exports.readActiveSkill = readActiveSkill;
+exports.parseSkillPurity = parseSkillPurity;
+exports.evaluateSkillPreToolUse = evaluateSkillPreToolUse;
 exports.evaluateStopHook = evaluateStopHook;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const effects_js_1 = require("../../core/effects.js");
+const dialect_js_1 = require("./dialect.js");
+const effect_region_js_1 = require("./effect-region.js");
 const STEP_RE = /^###\s+Step\s+(\d+)/;
 const GATE_CMD_RE = /<!--\s*vigiles:gate\s+"([^"]*)"(?:\s+retry:(\d+))?\s*-->/;
 const GATE_FILE_RE = /<!--\s*vigiles:gate\s+file:(\S+)\s*-->/;
@@ -257,6 +262,49 @@ function readActiveSkill(cwd) {
         return null;
     }
 }
+// ---------------------------------------------------------------------------
+// Skill purity gate (mirrors agent-runtime.ts parseAgentPurity / evaluatePreToolUse)
+// ---------------------------------------------------------------------------
+const PURITY_RE = /<!--\s*vigiles:purity:(pure|bounded|unrestricted)\s*-->/;
+/**
+ * Parse the declared purity floor from a compiled SKILL.md — the
+ * `<!-- vigiles:purity:LEVEL -->` marker `compileSkill` emits (see
+ * `purityMarker` in compile.ts). Returns null when no marker is present (the
+ * skill declared no floor, so the purity gate imposes no constraint). Mirrors
+ * `parseAgentPurity` in agent-runtime.ts.
+ */
+function parseSkillPurity(markdown) {
+    const m = PURITY_RE.exec(markdown);
+    return m ? m[1] : null;
+}
+/**
+ * PreToolUse purity gate for skills. Mirrors `evaluatePreToolUse` in
+ * agent-runtime.ts, but enforces ONLY the purity floor — skills have no
+ * tools-allowlist rail (that's a separate, future concern). If a skill is
+ * active and declares a `vigiles:purity:` marker, `decidePurityGate` checks
+ * the live call (refining `Bash` by the concrete command via `isReadOnlyBash`).
+ * With no active skill, a missing `.md`, or no purity marker, always allows.
+ */
+function evaluateSkillPreToolUse(cwd, tool, command) {
+    const skillPath = readActiveSkill(cwd);
+    if (!skillPath)
+        return { allow: true, message: "" };
+    const full = (0, node_path_1.resolve)(cwd, skillPath);
+    if (!(0, node_fs_1.existsSync)(full))
+        return { allow: true, message: "" };
+    const md = (0, node_fs_1.readFileSync)(full, "utf-8");
+    const purity = parseSkillPurity(md);
+    const boundary = (0, effect_region_js_1.hasEffectBoundary)(md);
+    if (boundary) {
+        const effective = (0, effect_region_js_1.readEffectActive)(cwd)
+            ? (purity ?? "unrestricted")
+            : "pure";
+        return (0, effects_js_1.decidePurityGate)(effective, tool, command, dialect_js_1.claudeCodeDialect);
+    }
+    if (!purity)
+        return { allow: true, message: "" };
+    return (0, effects_js_1.decidePurityGate)(purity, tool, command, dialect_js_1.claudeCodeDialect);
+}
 /**
  * Stop-hook decision. If a skill is active and declares a result gate, run it:
  * allow the stop only when the gate passes; otherwise block and tell the model

package/dist/adapters/codex/adapter.js

@@ -29,6 +29,9 @@ exports.codexAdapter = {
         referenceVerification: true,
         harnessTesting: true,
         shellHooks: true,
+        // Codex `[agents]` is a concurrency table, not a subagent tool-contract file
+        // — the subagent-surface rules report n/a here (a deliberate non-goal).
+        subagents: false,
     },
     dialect: dialect_js_1.codexDialect,
     layout: layout_js_1.codexLayout,

package/dist/adapters/codex/eval.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Codex EVAL-tier transport — the runner + trace parser that
+ * `measureTriggerRate`/`runEval` dispatch to via the `ModelOutputParser` seam.
+ *
+ * SCHEMA: CONFIRMED against real `codex exec --json` (codex-cli 0.139.0, ChatGPT
+ * auth). The stream is the thread/item model:
+ *
+ *   {"type":"thread.started","thread_id":"…"}
+ *   {"type":"turn.started"}
+ *   {"type":"item.started","item":{"id":"item_0","type":"command_execution",…}}   // mid-flight
+ *   {"type":"item.completed","item":{"id":"item_0","type":"command_execution","command":"…","aggregated_output":"…","exit_code":0}}
+ *   {"type":"item.completed","item":{"id":"item_1","type":"agent_message","text":"…"}}
+ *   {"type":"turn.completed","usage":{"input_tokens":…,"cached_input_tokens":…,"output_tokens":…}}
+ *
+ * So: assistant text = `item.completed` with `item.type:"agent_message"` →
+ * `item.text`; a tool call = `item.type:"command_execution"` → `item.command`;
+ * usage rides `turn.completed`. We count `item.completed` ONLY (an `item.started`
+ * carries the same `id` mid-flight — counting both double-counts).
+ *
+ * THE SKILL FINDING: Codex has NO discrete "skill selected" event (its CLI has no
+ * Skill-tool concept). When a skill triggers, the model READS the skill's
+ * `SKILL.md` via a `command_execution` (`sed/cat … skills/<name>/SKILL.md`) and
+ * usually says so in an `agent_message`. So "did skill X fire" on Codex is not a
+ * clean trace event like Claude's `Skill` tool_use — it's detected by the
+ * SKILL.md read (`codexSkillFired`). Best-effort by nature (a cached skill might
+ * not be re-read); pair with a behavioral/judged check for certainty.
+ */
+import type { ParsedModelRun, AgentRunArgs, RunOut, EvalDriver } from "../../eval.js";
+import type { ToolCall } from "../../core/harness-driver.js";
+/** Parse `codex exec --json` stdout into the common trace fields (confirmed schema). */
+export declare function parseCodexEvalRun(out: {
+    stdout: string;
+}): ParsedModelRun;
+/**
+ * The error message if the run errored or was rate-limited (an `error` /
+ * `turn.failed` event), else null. CRITICAL for the eval tier: an errored turn
+ * must NOT be scored as a clean "skill didn't fire" miss — dogfooding hit a Codex
+ * usage limit ("You've hit your usage limit…") whose `error` event left an empty
+ * trace that `codexSkillFired` read as recall 0. A caller should skip/retry an
+ * errored run, not count it. (The Claude path has `isRateLimited` + backoff; this
+ * is the Codex equivalent detector.)
+ */
+export declare function codexRunError(out: {
+    stdout: string;
+}): string | null;
+/**
+ * Did Codex activate skill `name` on this run? Detected by the SKILL.md read —
+ * Codex has no discrete skill-selection event, so when a skill triggers the model
+ * reads its `…/<name>/SKILL.md` via a `command_execution`. Best-effort (a cached
+ * skill might not be re-read); for the trigger-rate `fired` predicate over Codex.
+ */
+export declare function codexSkillFired(run: {
+    toolCalls: readonly ToolCall[];
+}, name: string): boolean;
+/**
+ * Materialize a (Claude-shaped) plugin dir's skills into `<cwd>/.codex/skills/` —
+ * where Codex actually discovers them (validated live: codex reads
+ * `<cwd>/.codex/skills/<name>/SKILL.md`). This is the Codex analog of Claude's
+ * `--plugin-dir`: `measureTriggerRate` hands the runner a `pluginDir` (the
+ * stubbed/packaged skills), and the Codex runner installs them here before the
+ * turn. Pure fs — unit-testable without a binary.
+ */
+export declare function installCodexSkills(pluginDir: string, cwd: string): number;
+/**
+ * The Codex eval-tier `AgentRunner`: install the run's skills into `.codex/skills`
+ * (Codex's discovery path, vs Claude's `--plugin-dir`), then drive a real
+ * `codex exec --json` turn. The seam `measureTriggerRate(spec, { evalDriver:
+ * codexEvalDriver })` dispatches through.
+ */
+export declare function codexEvalAgentRunner(args: AgentRunArgs): Promise<RunOut>;
+/**
+ * The Codex eval driver — pass to `measureTriggerRate(spec, { evalDriver:
+ * codexEvalDriver })` to run a trigger-rate eval natively on `codex exec`. Pair
+ * the spec's `fired` with `codexSkillFired` (Codex has no Skill-tool event).
+ */
+export declare const codexEvalDriver: EvalDriver;
+/**
+ * Spawn real `codex exec --json` for the eval tier (real model, the user's codex
+ * auth — NOT the mock). CONFIRMED flags (codex 0.139.0): `--json` for the event
+ * stream, `--skip-git-repo-check` for a bare cwd, the approvals/sandbox bypass so
+ * the turn runs unattended, `-C <cwd>` for the working dir, prompt as the trailing
+ * positional, and stdin = /dev/null (`stdio: ["ignore",…]`) — codex otherwise
+ * blocks on "Reading additional input from stdin…". Needs ChatGPT/API auth +
+ * network egress to the model backend.
+ */
+export declare function codexEvalRunner(args: {
+    task: string;
+    cwd: string;
+    timeoutMs: number;
+}): {
+    code: number;
+    stdout: string;
+};
+//# sourceMappingURL=eval.d.ts.map