vigiles 2.4.0 → 2.5.0

package/README.md

@@ -313,7 +313,8 @@ assert(JSON.parse(r.stdout).num_turns > 1); // the Stop hook forced more work
 ### Level 3 — does it change what Claude does? (real AI, occasional)
 
 `runEval` runs the **real** model N times with your change **on vs off** and
-reports the gap. Costs tokens, so you run it now and then — not on every save:
+reports the gap as **mean ± se** — so you can tell signal from noise instead of
+eyeballing two averages:
 
 ```typescript
 import { runEval, formatEvalReport } from "vigiles/eval";
@@ -325,10 +326,21 @@ const report = await runEval({
     marked: ctx.sh("grep -c vigiles:symbol SKILL.md") !== "0",
   }),
   trials: 6,
+  cache: "readwrite", // replay past runs — editing `measure` re-scores for free
 });
-console.log(formatEvalReport(report)); // off marked=0.00   on marked=0.50
+console.log(formatEvalReport(report));
+// off  marked=0.00   on  marked=0.50±0.20 pass^k=0   ($0.07 · 1.2s/run · 4.1k tok)
 ```
 
+`assertSignificant(report, { baseline: "off", arm: "on", metric: "marked" })`
+turns the gap into a CI gate — a Welch t-test decides whether it cleared the
+noise floor, **computed** from the arms' spread, not hand-fed. Runs go
+**concurrently**, track **cost / latency / tokens** (cap them with `maxCostUsd`),
+and the **record/replay cache** makes re-scoring after a `measure` edit free.
+
+Same tier, different question: **`measureTriggerRate`** measures how reliably a
+skill's _description fires_ across varied prompts — the #1 skill-authoring pain.
+
 ### Test your skills for real — and assert on what Claude _did_
 
 Install a plugin the way Claude actually does (`pluginDir` → `--plugin-dir`) so
@@ -356,6 +368,43 @@ dangerous tool was never used, which "the file looks unchanged" can't. It works
 on **real third-party plugins** too: the suite confirms real `obra/superpowers`
 and `wshobson/agents` skills resolve this way, with no markers injected.
 
+### Did the injected context actually reach the model?
+
+A SessionStart hook or a slash command can _fire_ and still inject **nothing** —
+wrong output shape, wrong platform. `trace.modelRequests` records what the model
+actually received (system + messages), so you assert it landed, not just that the
+hook ran — **"fired ≠ landed"**:
+
+```typescript
+import { assertRequestContains } from "vigiles/harness-assert";
+
+assertRequestContains(r, "You have superpowers"); // the additionalContext reached the model
+```
+
+(Dogfood: this is exactly how vigiles found that real `obra/superpowers` emits a
+_top-level_ `additionalContext`, which Claude Code — reading the _nested_ form —
+never injects. The hook fired; the context never landed.)
+
+### Running an untrusted plugin? It's confined by default
+
+Testing a third-party plugin means executing **its** hooks. `runHarnessTest` is
+safe by default: code you wrote (inline `settings`/`files`) runs directly, but an
+external `plugin` / `pluginDir` is **confined under bubblewrap** — a network
+namespace with **no egress** (a malicious hook can't phone home), a read-only
+filesystem, and a **cleared environment** (your `ANTHROPIC_API_KEY` and other
+secrets aren't even visible). If no sandbox is available the run **refuses**
+rather than executing unconfined:
+
+```typescript
+runHarnessTest({ pluginDir: "./vendor/some-plugin", model }); // confined, or refuses
+runHarnessTest({ pluginDir: "./audited", model, sandbox: false }); // you vouch for it → direct
+```
+
+Confinement is **Linux-only** (bubblewrap); on macOS / Windows an untrusted run
+refuses unless you pass `sandbox: false`. The suite dogfoods it on real
+`obra/superpowers` — its `SessionStart` hook runs in a no-egress sandbox, and the
+test proves egress is blocked while the scripted mock stays reachable.
+
 ### Run them in CI
 
 `vigiles test` runs `*.harness.mjs` files (free, no key); `vigiles eval` runs
@@ -379,10 +428,12 @@ npx vigiles eval --trials=6 examples/harness/skill-outcome.eval.mjs
 | Hooks — PreCompact / Notification / SessionEnd / SubagentStop | ✅ logic                     | — (mock can't trigger)      | 🟡                |
 | CLAUDE.md / instructions                                      | ✅ refs                      | 🟡 present, not behaviour   | ✅ behaviour      |
 | Skills                                                        | 🟡 refs                      | ✅ resolves via `pluginDir` | ✅ activation     |
-| Subagents (`agents/`)                                         | 🟡 refs                      | 🔴 hard                     | ✅ via Task       |
+| Subagents (`agents/`)                                         | ✅ tool rail · 🟡 refs       | 🟡 rail not live-armed      | ✅ via Task       |
 | Slash commands (`commands/`)                                  | 🟡 refs                      | 🟡 needs prompt capture     | ✅ via `/cmd`     |
 | MCP servers                                                   | ✅ tool refs (`vigiles:mcp`) | 🔴                          | 🔴                |
 | settings.json                                                 | 🟡 assert merged             | ✅ applied                  | ✅                |
+| Hook context injection (does it _land_?)                      | — n/a                        | ✅ `trace.modelRequests`    | ✅                |
+| Untrusted plugin execution                                    | — n/a                        | ✅ confined (bwrap, Linux)  | 🟡 outer sandbox  |
 
 ✅ shipped · 🟡 partial · 🔴 gap · — n/a. Full detail + roadmap: [`research/harness-testing-coverage-matrix.md`](research/harness-testing-coverage-matrix.md).
 

package/dist/agent-result.d.ts

@@ -0,0 +1,40 @@
+/**
+ * vigiles — parse a subagent's railway result.
+ *
+ * A subagent with a `result()` contract is told (in its compiled system prompt)
+ * to end its turn with exactly one fenced block:
+ *
+ *   ```vigiles:ok
+ *   { "files": ["a.ts"], "summary": "done" }
+ *   ```
+ *
+ * or `vigiles:err` for the error track. This module extracts and validates that
+ * block — the single primitive the railway orchestrator and the harness-test
+ * assertions (`assertAgentOk`/`assertAgentErr`) both build on. Pure and
+ * model-free: hand it the worker's text, get back a discriminated outcome.
+ *
+ * "Railway-oriented" is literal here: the parse is `text -> Result<S, E>` with a
+ * third `malformed` track for a worker that didn't honor its contract (no block,
+ * bad JSON, or a shape that doesn't match the declared schema).
+ */
+import type { OutputContract } from "./spec.js";
+/** The outcome of parsing a worker's result block. */
+export type ParsedAgentResult<S = Record<string, unknown>, E = Record<string, unknown>> = {
+    readonly kind: "ok";
+    readonly value: S;
+} | {
+    readonly kind: "err";
+    readonly error: E;
+} | {
+    readonly kind: "malformed";
+    readonly reason: string;
+};
+/**
+ * Parse the last `vigiles:ok` / `vigiles:err` block from a worker's output.
+ *
+ * With a `contract`, the parsed object is validated against the matching track's
+ * shape — a worker that emits the wrong shape is `malformed`, not a silent pass.
+ * Without one, any well-formed JSON block is accepted.
+ */
+export declare function parseAgentResult(text: string, contract?: OutputContract): ParsedAgentResult;
+//# sourceMappingURL=agent-result.d.ts.map

package/dist/agent-result.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * vigiles — parse a subagent's railway result.
+ *
+ * A subagent with a `result()` contract is told (in its compiled system prompt)
+ * to end its turn with exactly one fenced block:
+ *
+ *   ```vigiles:ok
+ *   { "files": ["a.ts"], "summary": "done" }
+ *   ```
+ *
+ * or `vigiles:err` for the error track. This module extracts and validates that
+ * block — the single primitive the railway orchestrator and the harness-test
+ * assertions (`assertAgentOk`/`assertAgentErr`) both build on. Pure and
+ * model-free: hand it the worker's text, get back a discriminated outcome.
+ *
+ * "Railway-oriented" is literal here: the parse is `text -> Result<S, E>` with a
+ * third `malformed` track for a worker that didn't honor its contract (no block,
+ * bad JSON, or a shape that doesn't match the declared schema).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAgentResult = parseAgentResult;
+// Capture every vigiles:ok / vigiles:err fenced block; the LAST one is the
+// worker's final answer (earlier ones may be illustrative in its reasoning).
+const BLOCK_RE = /```vigiles:(ok|err)[ \t]*\r?\n([\s\S]*?)```/g;
+/** Does a runtime value match a declared field type? */
+function fieldMatches(value, type) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number";
+        case "boolean":
+            return typeof value === "boolean";
+        case "string[]":
+            return Array.isArray(value) && value.every((v) => typeof v === "string");
+    }
+}
+/** Validate a parsed object against a contract track; null when it conforms. */
+function shapeError(obj, shape) {
+    for (const [field, type] of Object.entries(shape)) {
+        if (!(field in obj))
+            return `missing field "${field}"`;
+        if (!fieldMatches(obj[field], type)) {
+            return `field "${field}" should be ${type}`;
+        }
+    }
+    return null;
+}
+/**
+ * Parse the last `vigiles:ok` / `vigiles:err` block from a worker's output.
+ *
+ * With a `contract`, the parsed object is validated against the matching track's
+ * shape — a worker that emits the wrong shape is `malformed`, not a silent pass.
+ * Without one, any well-formed JSON block is accepted.
+ */
+function parseAgentResult(text, contract) {
+    BLOCK_RE.lastIndex = 0;
+    let last = null;
+    for (let m = BLOCK_RE.exec(text); m !== null; m = BLOCK_RE.exec(text)) {
+        last = { track: m[1], body: m[2] };
+    }
+    if (!last) {
+        return {
+            kind: "malformed",
+            reason: "no vigiles:ok/vigiles:err block found",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(last.body);
+    }
+    catch {
+        return {
+            kind: "malformed",
+            reason: `invalid JSON in vigiles:${last.track} block`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            kind: "malformed",
+            reason: `vigiles:${last.track} block must be a JSON object`,
+        };
+    }
+    const obj = parsed;
+    if (contract) {
+        const shape = last.track === "ok" ? contract.ok : contract.err;
+        const err = shapeError(obj, shape);
+        if (err) {
+            return { kind: "malformed", reason: `${last.track} block: ${err}` };
+        }
+    }
+    return last.track === "ok"
+        ? { kind: "ok", value: obj }
+        : { kind: "err", error: obj };
+}
+//# sourceMappingURL=agent-result.js.map

package/dist/agent-runtime.d.ts

@@ -0,0 +1,64 @@
+/**
+ * vigiles — Agent runtime: the PreToolUse tool-contract rail.
+ *
+ * A subagent declares an allowed-tools contract in its frontmatter (`tools:`).
+ * But that field is documentation, not a hard runtime boundary (Claude Code
+ * issue #54898): permissions are session-wide, a subagent inherits the parent
+ * session's grants, and `tools:` only filters what's *offered* — it can't deny
+ * what the session allows. The deterministic layer that actually closes the gap
+ * is a **PreToolUse hook** that blocks any tool the active agent's contract
+ * doesn't list.
+ *
+ * This is the same emit-a-hook pattern the skill runtime already ships
+ * (`src/skill-runtime.ts`): there a `Stop` hook reads the active skill's
+ * compiled SKILL.md and runs its result gate; here a `PreToolUse` hook reads
+ * the active agent's compiled `.md`, parses its `tools:` allowlist, and
+ * allows/denies the tool call. The compiled markdown's frontmatter is the
+ * single source of truth — the same list that documents intent IS the list the
+ * hook enforces, so the two agree by construction (see `enforcedTools`).
+ *
+ * Which agent is active is recorded in `.vigiles/active-agent.json` — Claude
+ * Code hooks don't surface the dispatched subagent, so vigiles records it
+ * (mirrors `.vigiles/active-skill.json`). The decision logic below is
+ * harness-agnostic and fully testable.
+ */
+/**
+ * Parse an agent's allowed-tools contract from its compiled markdown.
+ *
+ * Returns the list of allowed tool names, or `null` when the agent declares no
+ * `tools:` line at all — which in Claude Code means it inherits EVERY tool (the
+ * #1 footgun). `null` is the "no restriction" signal the decision logic honors;
+ * an empty list (`tools:` with nothing after it) means "no tools allowed".
+ */
+export declare function parseAgentTools(markdown: string): string[] | null;
+export interface PreToolDecision {
+    /** 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;
+}
+/**
+ * Decide whether `tool` is allowed under an agent's tool contract. Pure, so the
+ * rail is unit-testable without spawning anything.
+ *
+ * - `allowed === null` → the agent declared no `tools:` line, so it inherits
+ *   everything and the rail imposes no restriction (allow).
+ * - otherwise → allow iff the tool is in the allowlist; deny anything else,
+ *   feeding the contract back to the model so it self-corrects.
+ */
+export declare function decidePreToolUse(allowed: readonly string[] | null, tool: string): PreToolDecision;
+/** Record the subagent currently dispatched, so PreToolUse enforces its contract. */
+export declare function setActiveAgent(cwd: string, agentPath: string): void;
+/** Clear the active-agent marker (the subagent finished). */
+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.
+ */
+export declare function evaluatePreToolUse(cwd: string, tool: string): PreToolDecision;
+//# sourceMappingURL=agent-runtime.d.ts.map

package/dist/agent-runtime.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * vigiles — Agent runtime: the PreToolUse tool-contract rail.
+ *
+ * A subagent declares an allowed-tools contract in its frontmatter (`tools:`).
+ * But that field is documentation, not a hard runtime boundary (Claude Code
+ * issue #54898): permissions are session-wide, a subagent inherits the parent
+ * session's grants, and `tools:` only filters what's *offered* — it can't deny
+ * what the session allows. The deterministic layer that actually closes the gap
+ * is a **PreToolUse hook** that blocks any tool the active agent's contract
+ * doesn't list.
+ *
+ * This is the same emit-a-hook pattern the skill runtime already ships
+ * (`src/skill-runtime.ts`): there a `Stop` hook reads the active skill's
+ * compiled SKILL.md and runs its result gate; here a `PreToolUse` hook reads
+ * the active agent's compiled `.md`, parses its `tools:` allowlist, and
+ * allows/denies the tool call. The compiled markdown's frontmatter is the
+ * single source of truth — the same list that documents intent IS the list the
+ * hook enforces, so the two agree by construction (see `enforcedTools`).
+ *
+ * Which agent is active is recorded in `.vigiles/active-agent.json` — Claude
+ * Code hooks don't surface the dispatched subagent, so vigiles records it
+ * (mirrors `.vigiles/active-skill.json`). The decision logic below is
+ * harness-agnostic and fully testable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAgentTools = parseAgentTools;
+exports.decidePreToolUse = decidePreToolUse;
+exports.setActiveAgent = setActiveAgent;
+exports.clearActiveAgent = clearActiveAgent;
+exports.readActiveAgent = readActiveAgent;
+exports.evaluatePreToolUse = evaluatePreToolUse;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// 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.
+ *
+ * Returns the list of allowed tool names, or `null` when the agent declares no
+ * `tools:` line at all — which in Claude Code means it inherits EVERY tool (the
+ * #1 footgun). `null` is the "no restriction" signal the decision logic honors;
+ * 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);
+}
+/**
+ * Decide whether `tool` is allowed under an agent's tool contract. Pure, so the
+ * rail is unit-testable without spawning anything.
+ *
+ * - `allowed === null` → the agent declared no `tools:` line, so it inherits
+ *   everything and the rail imposes no restriction (allow).
+ * - otherwise → allow iff the tool is in the allowlist; deny anything else,
+ *   feeding the contract back to the model so it self-corrects.
+ */
+function decidePreToolUse(allowed, tool) {
+    if (allowed === null)
+        return { allow: true, message: "" };
+    if (allowed.includes(tool))
+        return { allow: true, message: "" };
+    const list = allowed.length > 0 ? allowed.join(", ") : "(none)";
+    return {
+        allow: false,
+        message: `Tool "${tool}" is not in this subagent's allowed-tools contract ` +
+            `(${list}). Use only the listed tools, or widen the agent's \`tools\`.`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Active-agent tracking (mirrors .vigiles/active-skill.json)
+// ---------------------------------------------------------------------------
+const ACTIVE_PATH = ".vigiles/active-agent.json";
+/** Record the subagent currently dispatched, so PreToolUse enforces its contract. */
+function setActiveAgent(cwd, agentPath) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, node_fs_1.writeFileSync)(p, JSON.stringify({ agent: agentPath }) + "\n");
+}
+/** Clear the active-agent marker (the subagent finished). */
+function clearActiveAgent(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if ((0, node_fs_1.existsSync)(p))
+        (0, node_fs_1.rmSync)(p);
+}
+/** The path of the active agent's compiled `.md`, or null when none is active. */
+function readActiveAgent(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if (!(0, node_fs_1.existsSync)(p))
+        return null;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+        return typeof parsed.agent === "string" ? parsed.agent : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// 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.
+ */
+function evaluatePreToolUse(cwd, tool) {
+    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);
+}
+//# sourceMappingURL=agent-runtime.js.map

package/dist/cli.js

@@ -23,6 +23,7 @@ const frontmatter_js_1 = require("./frontmatter.js");
 const generate_schema_js_1 = require("./generate-schema.js");
 const compile_generator_js_1 = require("./compile-generator.js");
 const action_gate_js_1 = require("./action-gate.js");
+const agent_runtime_js_1 = require("./agent-runtime.js");
 const refs_js_1 = require("./refs.js");
 const mcp_js_1 = require("./mcp.js");
 const skill_runtime_js_1 = require("./skill-runtime.js");
@@ -177,8 +178,57 @@ function compileSkillToFile(spec, specPath) {
     printErrors(specPath, errors);
     return false;
 }
+/** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
+function compileAgentToFile(spec, specPath) {
+    const outputPath = specPath.replace(/\.spec\.ts$/, "");
+    const { markdown, errors } = (0, compile_js_1.compileAgent)(spec, {
+        basePath: process.cwd(),
+        specFile: specPath,
+    });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    if (errors.length === 0) {
+        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        return true;
+    }
+    console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+    printErrors(specPath, errors);
+    return false;
+}
+/**
+ * Compile a railway spec → the orchestrator command markdown. `knownAgents` is
+ * the set of compiled agent names in the project, so every `delegate()` target
+ * is resolved at compile time (an unknown target is a stale-ref error).
+ */
+function compileRailwayToFile(spec, specPath, knownAgents) {
+    const outputPath = specPath.replace(/\.spec\.ts$/, "");
+    const { markdown, errors } = (0, compile_js_1.compileRailway)(spec, {
+        specFile: specPath,
+        knownAgents,
+    });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    if (errors.length === 0) {
+        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        return true;
+    }
+    console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+    printErrors(specPath, errors);
+    return false;
+}
+/** Names of every compiled agent spec in the project — resolves delegate() targets. */
+async function collectAgentNames() {
+    const names = [];
+    for (const p of findSpecs()) {
+        const s = await loadSpec(p);
+        if (s && s._specType === "agent")
+            names.push(s.name);
+    }
+    return names;
+}
 async function compile(specPaths, config) {
     let allValid = true;
+    // Resolved lazily on the first railway spec — every delegate() target is
+    // checked against the agents defined anywhere in the project.
+    let knownAgents = null;
     for (const specPath of specPaths) {
         // Generator skills can't be executed to markdown — compile from source.
         const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), specPath), "utf-8");
@@ -202,6 +252,15 @@ async function compile(specPaths, config) {
             if (!compileSkillToFile(spec, specPath))
                 allValid = false;
         }
+        else if (spec._specType === "agent") {
+            if (!compileAgentToFile(spec, specPath))
+                allValid = false;
+        }
+        else if (spec._specType === "railway") {
+            knownAgents ??= await collectAgentNames();
+            if (!compileRailwayToFile(spec, specPath, knownAgents))
+                allValid = false;
+        }
     }
     return allValid;
 }
@@ -1612,6 +1671,44 @@ function skillStartCommand(target) {
     (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
     console.log(`Active skill: ${target}`);
 }
+/**
+ * PreToolUse-hook entrypoint: enforce the active subagent's allowed-tools
+ * contract. Reads the tool event on stdin, parses the active agent's compiled
+ * `.md` tool rail, and blocks (exit 2 + reason on stderr) any tool outside it —
+ * the deterministic boundary `tools:` alone can't provide (Claude Code #54898).
+ */
+function agentHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let tool = "";
+    try {
+        tool = JSON.parse(raw).tool_name ?? "";
+    }
+    catch {
+        /* malformed input → no tool, allow */
+    }
+    if (!tool)
+        return;
+    const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(process.cwd(), tool);
+    if (!decision.allow) {
+        console.error(decision.message);
+        process.exit(2);
+    }
+}
+/** Mark a subagent active so the PreToolUse hook enforces its tool contract. */
+function agentStartCommand(target) {
+    if (!target) {
+        console.error("Usage: vigiles agent-start <agents/<name>.md>");
+        process.exit(2);
+    }
+    (0, agent_runtime_js_1.setActiveAgent)(process.cwd(), target);
+    console.log(`Active agent: ${target}`);
+}
 /** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
 function handleSkillCommand(command, restArgs) {
     switch (command) {
@@ -1627,6 +1724,15 @@ function handleSkillCommand(command, restArgs) {
         case "skill-hook":
             skillHookCommand();
             return true;
+        case "agent-start":
+            agentStartCommand(restArgs[0]);
+            return true;
+        case "agent-done":
+            (0, agent_runtime_js_1.clearActiveAgent)(process.cwd());
+            return true;
+        case "agent-hook":
+            agentHookCommand();
+            return true;
         case "action-hook":
             actionHookCommand();
             return true;

package/dist/compile.d.ts

@@ -4,7 +4,7 @@
  * Reads .spec.ts files, validates references, and produces
  * markdown instruction files with integrity hashes.
  */
-import type { ClaudeSpec, SkillSpec } from "./spec.js";
+import type { ClaudeSpec, SkillSpec, AgentSpec, Railway } from "./spec.js";
 import type { LinterCheckResult } from "./linters.js";
 /** @internal Compute SHA-256 hash of content (excluding any existing hash line). */
 export declare function computeHash(content: string): string;
@@ -24,7 +24,7 @@ export declare function verifyHash(content: string): {
  */
 /** @internal */ export declare function estimateTokens(text: string): number;
 export interface CompileError {
-    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch";
+    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway";
     message: string;
     path?: string;
 }
@@ -79,6 +79,35 @@ export declare function compileSkill(spec: SkillSpec, options?: {
     basePath?: string;
     specFile?: string;
 }): CompileSkillResult;
+export interface CompileAgentResult {
+    markdown: string;
+    errors: CompileError[];
+}
+/**
+ * Compile an AgentSpec into a subagent markdown file with YAML frontmatter.
+ * Verifies the tool contract and the body's references; the marks the body
+ * carries (`vigiles:symbol`, file/cmd refs) are the same ones `audit` re-checks.
+ */
+export declare function compileAgent(spec: AgentSpec, options?: {
+    basePath?: string;
+    specFile?: string;
+}): CompileAgentResult;
+export interface CompileRailwayOptions {
+    /** Names of compiled agents, to resolve `delegate` targets. Skipped if omitted. */
+    knownAgents?: readonly string[];
+    specFile?: string;
+}
+export interface CompileRailwayResult {
+    markdown: string;
+    errors: CompileError[];
+}
+/** Verify a railway: non-empty, bounded recovery, every delegate target real. */
+export declare function validateRailway(rw: Railway, knownAgents?: readonly string[]): CompileError[];
+/**
+ * Compile a railway into an orchestrator command markdown (with integrity hash),
+ * resolving every delegate target against `knownAgents` when provided.
+ */
+export declare function compileRailway(rw: Railway, options?: CompileRailwayOptions): CompileRailwayResult;
 export interface HashCheckResult {
     hasHash: boolean;
     valid: boolean;
@@ -101,5 +130,5 @@ export interface AdoptResult {
  * Compare a generated file against what the spec would produce.
  * Returns the diff so users can see what was manually changed.
  */
-export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec, basePath: string): AdoptResult;
+export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec | AgentSpec, basePath: string): AdoptResult;
 //# sourceMappingURL=compile.d.ts.map