vigiles 2.3.0 → 2.5.0

package/dist/mock-model.d.ts

@@ -14,12 +14,38 @@ export interface TurnInfo {
     readonly stream: boolean;
     readonly hasToolResult: boolean;
 }
+/**
+ * One `/v1/messages` request the mock received, flattened to text for
+ * assertions. This is the seam that lets a harness test prove what reached the
+ * model — a SessionStart hook's injected `additionalContext`, or a slash
+ * command's expansion — not just that a hook fired.
+ */
+export interface ModelRequest {
+    /** The system prompt, flattened to text (string or text-block array). */
+    readonly system: string;
+    /** The conversation messages, each flattened to `{ role, text }`. */
+    readonly messages: readonly {
+        readonly role: string;
+        readonly text: string;
+    }[];
+}
 export interface MockHandle {
     readonly url: string;
     close(): void;
     /** Number of model turns served so far. */
     readonly count: number;
+    /** Every `/v1/messages` request the mock received, in order. */
+    readonly requests: readonly ModelRequest[];
 }
+/**
+ * Extract a {@link ModelRequest} from a request body — the `system` prompt and
+ * `messages`, each flattened to text. Pure and exported so the capture logic is
+ * testable without the HTTP server.
+ */
+export declare function extractRequest(body: {
+    system?: unknown;
+    messages?: unknown;
+}): ModelRequest;
 /**
  * Start the scripted mock on a free port. Each `/v1/messages` POST consumes the
  * next turn (the last turn repeats if the client asks for more). Resolves to a
@@ -27,5 +53,8 @@ export interface MockHandle {
  */
 export declare function startMock(script: readonly ModelTurn[], opts?: {
     onTurn?: (info: TurnInfo) => void;
+    /** Called with each `/v1/messages` request as it arrives — used by the
+     * in-sandbox mock entry to stream requests to a file for the parent. */
+    onRequest?: (req: ModelRequest) => void;
 }): Promise<MockHandle>;
 //# sourceMappingURL=mock-model.d.ts.map

package/dist/mock-model.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scriptModel = scriptModel;
+exports.extractRequest = extractRequest;
 exports.startMock = startMock;
 /**
  * vigiles — a scripted, deterministic Anthropic Messages API mock.
@@ -127,6 +128,38 @@ function jsonTurn(res, turn, model) {
         usage: { input_tokens: 10, output_tokens: 5 },
     }));
 }
+/** Flatten Anthropic content (string, or an array of text/other blocks) to text. */
+function flattenContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((b) => {
+        if (typeof b === "string")
+            return b;
+        const t = b.text;
+        return typeof t === "string" ? t : "";
+    })
+        .join("");
+}
+/**
+ * Extract a {@link ModelRequest} from a request body — the `system` prompt and
+ * `messages`, each flattened to text. Pure and exported so the capture logic is
+ * testable without the HTTP server.
+ */
+function extractRequest(body) {
+    const messages = Array.isArray(body.messages)
+        ? body.messages.map((m) => {
+            const msg = m;
+            return {
+                role: typeof msg.role === "string" ? msg.role : "",
+                text: flattenContent(msg.content),
+            };
+        })
+        : [];
+    return { system: flattenContent(body.system), messages };
+}
 /**
  * Start the scripted mock on a free port. Each `/v1/messages` POST consumes the
  * next turn (the last turn repeats if the client asks for more). Resolves to a
@@ -134,6 +167,7 @@ function jsonTurn(res, turn, model) {
  */
 function startMock(script, opts = {}) {
     let i = 0;
+    const requests = [];
     const server = node_http_1.default.createServer((req, res) => {
         let body = "";
         req.on("data", (c) => (body += c));
@@ -158,6 +192,9 @@ function startMock(script, opts = {}) {
                 res.end(JSON.stringify({ input_tokens: 10 }));
                 return;
             }
+            const request = extractRequest(reqBody);
+            requests.push(request);
+            opts.onRequest?.(request);
             const last = JSON.stringify(reqBody.messages?.at(-1)?.content ?? "");
             opts.onTurn?.({
                 n: i,
@@ -182,6 +219,9 @@ function startMock(script, opts = {}) {
                 get count() {
                     return i;
                 },
+                get requests() {
+                    return requests;
+                },
             });
         });
     });

package/dist/plugin-loader.js

@@ -26,16 +26,19 @@ exports.resolveHarness = resolveHarness;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const MAX_SKILL_FILE_BYTES = 256 * 1024;
-/** Read and return the `.hooks` field of a JSON file, or undefined on any error. */
-function readHooksFile(path) {
+/** Parse a JSON file, or null on any error (missing / malformed). */
+function safeReadJson(path) {
     try {
-        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"))
-            .hooks;
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"));
     }
     catch {
-        return undefined;
+        return null;
     }
 }
+/** Read and return the `.hooks` field of a JSON file, or undefined on any error. */
+function readHooksFile(path) {
+    return safeReadJson(path)?.hooks;
+}
 /**
  * Read the hooks block, handling the real-world plugin layouts:
  *   1. inline `hooks` object in .claude-plugin/plugin.json,
@@ -44,9 +47,10 @@ function readHooksFile(path) {
  *   4. a plain repo's `.claude/settings.json`.
  */
 function readHooks(root) {
-    const manifestPath = (0, node_path_1.join)(root, ".claude-plugin", "plugin.json");
-    if ((0, node_fs_1.existsSync)(manifestPath)) {
-        const m = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf-8"));
+    // A malformed plugin.json must not crash the loader — fall through to the
+    // other layouts (safeReadJson returns null on a parse error).
+    const m = safeReadJson((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"));
+    if (m) {
         if (typeof m.hooks === "string")
             return readHooksFile((0, node_path_1.join)(root, m.hooks));
         if (m.hooks !== undefined)
@@ -134,6 +138,12 @@ function pluginWarnings(root, counts, hooks, files) {
     if (hasMcp(root)) {
         warnings.push(`plugin declares MCP server(s) (mcpServers / .mcp.json) — the loader does not wire MCP; bring the server up yourself if your test needs it.`);
     }
+    const dangling = danglingRefs(root);
+    if (dangling.length) {
+        const shown = dangling.slice(0, 5).join(", ");
+        const more = dangling.length > 5 ? `, … (+${String(dangling.length - 5)})` : "";
+        warnings.push(`plugin references ${String(dangling.length)} intra-plugin file(s) that don't exist (broken path / partial vendor): ${shown}${more}`);
+    }
     if (!hooks && Object.keys(files).length === 0) {
         warnings.push(`nothing was loaded (no hooks, CLAUDE.md, skills, agents, or commands) — the deterministic harness would run an effectively empty machine.`);
     }
@@ -143,16 +153,40 @@ function pluginWarnings(root, counts, hooks, files) {
 function hasMcp(root) {
     if ((0, node_fs_1.existsSync)((0, node_path_1.join)(root, ".mcp.json")))
         return true;
-    const manifestPath = (0, node_path_1.join)(root, ".claude-plugin", "plugin.json");
-    if (!(0, node_fs_1.existsSync)(manifestPath))
-        return false;
-    try {
-        const m = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf-8"));
-        return m.mcpServers !== undefined;
-    }
-    catch {
-        return false;
+    return (safeReadJson((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"))?.mcpServers !==
+        undefined);
+}
+// A plugin-relative path reference to a file under a standard surface dir, with a
+// known extension — e.g. a hook script that `cat`s `skills/using-superpowers/SKILL.md`.
+const INTRA_REF_RE = /(?:skills|hooks|commands|agents)\/[A-Za-z0-9._/-]+\.(?:md|sh|cmd|mjs|cjs|js|ts|py|rb|txt|json)/g;
+/**
+ * Intra-plugin file references that don't resolve — the partial-vendor / broken-
+ * path class (e.g. obra/superpowers' `SessionStart` reads
+ * `skills/using-superpowers/SKILL.md`, which a sliced vendor snapshot omits). We
+ * scan the plugin's own text files under the surface dirs (hooks scripts
+ * included — those aren't materialized into `files`) for root-relative path refs
+ * and report the ones missing on disk. A static check that would have caught a
+ * bug the dogfood hit twice. Best-effort: a warning, not an error.
+ */
+function danglingRefs(root) {
+    const missing = new Set();
+    const seen = new Set();
+    for (const surface of ["hooks", "skills", "agents", "commands"]) {
+        const dir = (0, node_path_1.join)(root, surface);
+        if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory())
+            continue;
+        for (const content of Object.values(readTree(dir, root))) {
+            for (const m of content.matchAll(INTRA_REF_RE)) {
+                const ref = m[0];
+                if (seen.has(ref))
+                    continue;
+                seen.add(ref);
+                if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(root, ref)))
+                    missing.add(ref);
+            }
+        }
     }
+    return [...missing];
 }
 /**
  * Merge a loaded plugin's settings with inline settings. Inline wins; when both

package/dist/sandbox.d.ts

@@ -0,0 +1,76 @@
+import { type ModelTurn, type ModelRequest } from "./mock-model.js";
+/**
+ * How to treat code execution. `"auto"` (default) is safe-by-default: trusted
+ * code runs directly, untrusted code is sandboxed if possible and otherwise
+ * refuses. `false` is the dangerous opt-out — run unconfined (you audited it, or
+ * you trust the outer container). `"strict"` forces confinement even for trusted
+ * code and throws if no sandbox is available.
+ */
+export type SandboxMode = "auto" | "strict" | false;
+/**
+ * Whether bubblewrap is available to confine untrusted code. **Linux only** —
+ * bubblewrap is a Linux tool, so this is always `false` on macOS / Windows,
+ * where confined execution isn't supported and untrusted code must instead be
+ * run via `sandbox: false` (trusting the outer container) or skipped.
+ */
+export declare function sandboxAvailable(): boolean;
+/**
+ * Is this spec's executed code trusted? Inline `settings`/`files` you authored
+ * are trusted; any external `plugin` / `pluginDir` brings in third-party hooks
+ * and is NOT — committing it to your repo is the same trust decision as a
+ * dependency, so the trust boundary follows provenance: foreign = confined.
+ */
+export declare function specTrusted(spec: {
+    plugin?: string;
+    pluginDir?: string;
+}): boolean;
+/** The chosen action for a run: execute directly, confine it, or refuse. */
+export type SandboxDecision = {
+    readonly action: "direct";
+} | {
+    readonly action: "sandbox";
+} | {
+    readonly action: "throw";
+    readonly reason: string;
+};
+/**
+ * The pure safe-by-default policy. Untrusted code NEVER runs unconfined unless
+ * the caller explicitly opted out (`mode: false`). This is the whole security
+ * contract, isolated as a pure function so it is exhaustively unit-tested.
+ */
+export declare function decideSandbox(opts: {
+    trusted: boolean;
+    mode: SandboxMode;
+    available: boolean;
+}): SandboxDecision;
+/**
+ * The bubblewrap confinement argv (everything before the command): a fresh
+ * network namespace (`--unshare-all`, loopback-only, no egress), a read-only
+ * system, writable mounts limited to the work dir, the IO dir, and a fresh empty
+ * HOME (inside the IO dir so it needs no mountpoint on the read-only root, and so
+ * no host credentials/config leak in), and a **cleared environment** —
+ * `--clearenv` drops every host variable (API keys, cloud creds) and only PATH /
+ * HOME / TMPDIR are set back, so untrusted code can't even read your secrets.
+ * Pure, so the confinement shape is asserted in a unit test.
+ */
+export declare function bwrapArgs(opts: {
+    cwd: string;
+    ioDir: string;
+    home: string;
+    path: string;
+}): string[];
+/** Parse the in-sandbox mock's ndjson request log into {@link ModelRequest}s. */
+export declare function parseRequestLog(ndjson: string): ModelRequest[];
+/** The raw output of a sandboxed run: exit code, captured stdout, and requests. */
+export interface SandboxRunOut {
+    readonly code: number;
+    readonly stdout: string;
+    readonly requests: readonly ModelRequest[];
+}
+export declare function runSandboxed(opts: {
+    cwd: string;
+    claudeArgs: readonly string[];
+    script: readonly ModelTurn[];
+    timeoutMs: number;
+}): Promise<SandboxRunOut>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.js

@@ -0,0 +1,241 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sandboxAvailable = sandboxAvailable;
+exports.specTrusted = specTrusted;
+exports.decideSandbox = decideSandbox;
+exports.bwrapArgs = bwrapArgs;
+exports.parseRequestLog = parseRequestLog;
+exports.runSandboxed = runSandboxed;
+/**
+ * vigiles — safe-by-default confinement for executing untrusted harness code.
+ *
+ * `runHarnessTest` runs the real `claude` CLI, which runs the real hooks of
+ * whatever plugin you load. For code YOU authored (inline `settings`/`files`)
+ * that's fine — trust is implicit. But pointing it at someone else's `plugin` /
+ * `pluginDir` executes THEIR hooks with your privileges. This module makes that
+ * safe by default: untrusted code is confined under bubblewrap, or — if no
+ * sandbox is available — the run refuses rather than executing unconfined.
+ *
+ * Confinement (proven on bwrap 0.9): `--unshare-all` gives a fresh network
+ * namespace whose loopback is auto-up but has NO external route — so the
+ * scripted mock, co-launched INSIDE the namespace, is reachable over 127.0.0.1
+ * while a malicious hook cannot phone home. The filesystem is `--ro-bind`
+ * read-only except the throwaway work dir, a fresh empty `$HOME`, and an IO dir
+ * used to hand the script in and stream captured requests back out.
+ *
+ * The policy (`decideSandbox`), trust test (`specTrusted`), and bwrap argv
+ * (`bwrapArgs`) are pure and unit-tested; the executor (`runSandboxed`) needs a
+ * real bwrap and is covered by the integration test, which skips where bwrap is
+ * absent — the same pattern as the real-`claude` paths.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * Whether bubblewrap is available to confine untrusted code. **Linux only** —
+ * bubblewrap is a Linux tool, so this is always `false` on macOS / Windows,
+ * where confined execution isn't supported and untrusted code must instead be
+ * run via `sandbox: false` (trusting the outer container) or skipped.
+ */
+function sandboxAvailable() {
+    /* v8 ignore next -- non-Linux has no bwrap; CI/coverage runs on Linux */
+    if (process.platform !== "linux")
+        return false;
+    try {
+        return (0, node_child_process_1.spawnSync)("bwrap", ["--version"], { stdio: "ignore" }).status === 0;
+    }
+    catch {
+        /* v8 ignore next -- defensive: spawnSync only throws on a fork failure */
+        return false;
+    }
+}
+/**
+ * Is this spec's executed code trusted? Inline `settings`/`files` you authored
+ * are trusted; any external `plugin` / `pluginDir` brings in third-party hooks
+ * and is NOT — committing it to your repo is the same trust decision as a
+ * dependency, so the trust boundary follows provenance: foreign = confined.
+ */
+function specTrusted(spec) {
+    return spec.plugin === undefined && spec.pluginDir === undefined;
+}
+/**
+ * The pure safe-by-default policy. Untrusted code NEVER runs unconfined unless
+ * the caller explicitly opted out (`mode: false`). This is the whole security
+ * contract, isolated as a pure function so it is exhaustively unit-tested.
+ */
+function decideSandbox(opts) {
+    // Explicit dangerous opt-out: run unconfined, trusted or not.
+    if (opts.mode === false)
+        return { action: "direct" };
+    // Force confinement regardless of trust; refuse if we can't.
+    if (opts.mode === "strict") {
+        return opts.available
+            ? { action: "sandbox" }
+            : {
+                action: "throw",
+                reason: "sandbox: 'strict' requires Linux + bubblewrap (bwrap), which was not available",
+            };
+    }
+    // auto: trusted code runs directly; untrusted must be confined or refused.
+    if (opts.trusted)
+        return { action: "direct" };
+    return opts.available
+        ? { action: "sandbox" }
+        : {
+            action: "throw",
+            reason: "refusing to execute an untrusted plugin's hooks without a sandbox: " +
+                "the sandbox needs Linux + bubblewrap (bwrap) — install it to run " +
+                "confined, or pass sandbox: false to run unconfined if you trust this " +
+                "code / the outer container",
+        };
+}
+/**
+ * The bubblewrap confinement argv (everything before the command): a fresh
+ * network namespace (`--unshare-all`, loopback-only, no egress), a read-only
+ * system, writable mounts limited to the work dir, the IO dir, and a fresh empty
+ * HOME (inside the IO dir so it needs no mountpoint on the read-only root, and so
+ * no host credentials/config leak in), and a **cleared environment** —
+ * `--clearenv` drops every host variable (API keys, cloud creds) and only PATH /
+ * HOME / TMPDIR are set back, so untrusted code can't even read your secrets.
+ * Pure, so the confinement shape is asserted in a unit test.
+ */
+function bwrapArgs(opts) {
+    return [
+        // New user/net/pid/ipc/uts/cgroup namespaces. The net namespace has only a
+        // loopback route, so the in-sandbox mock is reachable but egress is blocked.
+        "--unshare-all",
+        // Drop ALL inherited env (host secrets); only the essentials are set back.
+        "--clearenv",
+        "--ro-bind",
+        "/",
+        "/",
+        "--dev",
+        "/dev",
+        "--proc",
+        "/proc",
+        // Writable: the work dir and the IO dir (later binds override the ro-bind).
+        "--bind",
+        opts.cwd,
+        opts.cwd,
+        "--bind",
+        opts.ioDir,
+        opts.ioDir,
+        // A fresh empty HOME so no host credentials/config are visible.
+        "--setenv",
+        "HOME",
+        opts.home,
+        "--setenv",
+        "TMPDIR",
+        opts.ioDir,
+        // PATH must be set back explicitly (cleared above) so node/claude resolve.
+        "--setenv",
+        "PATH",
+        opts.path,
+        "--chdir",
+        opts.cwd,
+        "--die-with-parent",
+        "--new-session",
+    ];
+}
+/** Parse the in-sandbox mock's ndjson request log into {@link ModelRequest}s. */
+function parseRequestLog(ndjson) {
+    const out = [];
+    for (const line of ndjson.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            /* a partially-written final line — skip */
+        }
+    }
+    return out;
+}
+/**
+ * Co-launch the scripted mock and `claude` inside ONE bubblewrap network
+ * namespace: the mock serves on the sandbox's loopback (reachable), egress is
+ * blocked, and captured requests stream out through the bound IO dir. Paths come
+ * in via env so the wrapper needs no escaping; `claude`'s args are the wrapper's
+ * positional params (`"$@"`).
+ */
+const WRAPPER = [
+    // start the in-sandbox mock; it writes its port to $VIG_PORT when ready
+    'node "$VIG_MOCKENTRY" "$VIG_SCRIPT" "$VIG_REQS" "$VIG_PORT" &',
+    "MOCKPID=$!",
+    "i=0",
+    'while [ ! -s "$VIG_PORT" ] && [ "$i" -lt 200 ]; do sleep 0.05; i=$((i+1)); done',
+    'export ANTHROPIC_BASE_URL="http://127.0.0.1:$(cat "$VIG_PORT")"',
+    "export ANTHROPIC_API_KEY=sk-vigiles-mock",
+    'claude "$@"',
+    "code=$?",
+    'kill "$MOCKPID" 2>/dev/null',
+    'exit "$code"',
+].join("\n");
+/* v8 ignore start -- spawns bwrap + the real claude CLI; exercised by the
+   bwrap-backed integration test (skipped without bwrap), not the unit gate —
+   the pure policy/args/parse helpers above carry the testable logic. */
+function runSandboxed(opts) {
+    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-sbx-"));
+    const home = (0, node_path_1.join)(ioDir, "home");
+    (0, node_fs_1.mkdirSync)(home);
+    const scriptF = (0, node_path_1.join)(ioDir, "script.json");
+    const reqsF = (0, node_path_1.join)(ioDir, "requests.ndjson");
+    const portF = (0, node_path_1.join)(ioDir, "port");
+    (0, node_fs_1.writeFileSync)(scriptF, JSON.stringify(opts.script));
+    (0, node_fs_1.writeFileSync)(reqsF, "");
+    // The mock entry is only runnable as built JS. In production __dirname is
+    // dist/ (sibling); under vitest the source runs from src/, so fall back to
+    // the built dist/ copy.
+    const mockEntry = [
+        (0, node_path_1.join)(__dirname, "mock-entry.js"),
+        (0, node_path_1.join)(__dirname, "..", "dist", "mock-entry.js"),
+    ].find((p) => (0, node_fs_1.existsSync)(p)) ?? (0, node_path_1.join)(__dirname, "mock-entry.js");
+    const args = [
+        ...bwrapArgs({
+            cwd: opts.cwd,
+            ioDir,
+            home,
+            path: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+        }),
+        "--setenv",
+        "VIG_MOCKENTRY",
+        mockEntry,
+        "--setenv",
+        "VIG_SCRIPT",
+        scriptF,
+        "--setenv",
+        "VIG_REQS",
+        reqsF,
+        "--setenv",
+        "VIG_PORT",
+        portF,
+        "sh",
+        "-c",
+        WRAPPER,
+        "sh",
+        ...opts.claudeArgs,
+    ];
+    return new Promise((resolvePromise) => {
+        const child = (0, node_child_process_1.spawn)("bwrap", args, {
+            cwd: opts.cwd,
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", () => {
+            /* hook diagnostics — not needed for the captured result */
+        });
+        const timer = setTimeout(() => child.kill("SIGKILL"), opts.timeoutMs);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            const requests = parseRequestLog((0, node_fs_1.existsSync)(reqsF) ? (0, node_fs_1.readFileSync)(reqsF, "utf-8") : "");
+            (0, node_fs_1.rmSync)(ioDir, { recursive: true, force: true });
+            resolvePromise({ code: code ?? 0, stdout, requests });
+        });
+    });
+}
+/* v8 ignore stop */
+//# sourceMappingURL=sandbox.js.map

package/dist/spec.d.ts

@@ -320,6 +320,136 @@ export interface SkillSpec {
  *   export default skill({ name: "my-skill", description: "...", body: "..." });
  */
 export declare function skill(spec: Omit<SkillSpec, "_specType">): SkillSpec;
+/**
+ * A subagent definition (compiles to `agents/<name>.md`). Unlike a skill —
+ * reference material the model reads on activation — a subagent is a *delegated
+ * worker with a contract*: a dispatch `description`, an allowed-`tools` rail, an
+ * optional `model`, a system-prompt `body`, and the `rules` it must follow. That
+ * tool contract + those rules are the "railway" a subagent runs on, and they're
+ * exactly the compile-time-verifiable surface vigiles owns: the body's
+ * `file()`/`cmd()`/`symbol()` marks are checked like any instruction file, and
+ * the tools list is verified against the real tool set.
+ */
+export interface AgentSpec {
+    readonly _specType: "agent";
+    /** Subagent name (frontmatter + dispatch handle). */
+    readonly name: string;
+    /** When to dispatch this subagent — the trigger (frontmatter). */
+    readonly description: string;
+    /** Model alias (e.g. "sonnet", "opus", "haiku", "inherit"). Optional. */
+    readonly model?: string;
+    /**
+     * The allowed-tools contract — the rails the worker runs on. Each entry must be
+     * a known built-in tool (Read/Write/Edit/Bash/Grep/Glob/WebSearch/WebFetch/
+     * NotebookEdit/TodoWrite/Task/Skill) or an MCP tool (`mcp__server__tool`).
+     * Omit to inherit all tools. Verified at compile time.
+     */
+    readonly tools?: readonly string[];
+    /**
+     * The lead/intro prose of the system prompt (the "You are…" opener), before any
+     * sections. Carries verified `file()`/`cmd()`/`symbol()`/`ref()` marks. No
+     * markdown headers — use `sections` for those.
+     */
+    readonly body?: string | InstructionFragment[];
+    /**
+     * Named `##` sections of the system prompt (e.g. Purpose, Core Principles,
+     * Capabilities) — the shape real subagents actually take. Same verified-ref +
+     * no-nested-`##` rules as a CLAUDE.md spec's sections. Use `body` for the intro
+     * and `sections` for the structured rest.
+     */
+    readonly sections?: Record<string, string | InstructionFragment[]>;
+    /** Rules the worker must follow — rendered as a `## Rules` section. */
+    readonly rules?: Record<string, Rule>;
+    /**
+     * The typed result contract — what this worker returns on success/error. When
+     * set, compiles to an `## Output contract` section instructing the worker to
+     * end with a `vigiles:ok` / `vigiles:err` block, so its outcome is parseable
+     * and testable (see `result()`, `parseAgentResult`, `assertAgentOk`).
+     */
+    readonly output?: OutputContract;
+}
+/**
+ * Define a subagent specification (compiles to `agents/<name>.md`).
+ *
+ *   // agents/reviewer.md.spec.ts
+ *   export default agent({
+ *     name: "reviewer",
+ *     description: "Review a diff for correctness. Dispatch PROACTIVELY after edits.",
+ *     model: "sonnet",
+ *     tools: ["Read", "Grep", "Bash"],
+ *     body: instructions`Review the diff. Run ${cmd("npm test")} first.`,
+ *     rules: {
+ *       "no-floating": enforce("@typescript-eslint/no-floating-promises", "Await promises."),
+ *     },
+ *   });
+ */
+export declare function agent(spec: Omit<AgentSpec, "_specType">): AgentSpec;
+/** The field types a result contract can declare (kept tiny + dependency-free). */
+export type OutputFieldType = "string" | "number" | "boolean" | "string[]";
+/**
+ * A subagent's typed result contract: the shape it must return on success
+ * (`ok`) and on failure (`err`). Rich on both tracks — an error is structured
+ * detail, not a bare pass/fail bit. Compiles into the worker's system prompt
+ * (the `vigiles:ok` / `vigiles:err` block it must emit) and is the schema the
+ * `parseAgentResult` parser + the `assertAgentOk/Err` test helpers validate.
+ */
+export interface OutputContract {
+    readonly _ref: "output";
+    readonly ok: Readonly<Record<string, OutputFieldType>>;
+    readonly err: Readonly<Record<string, OutputFieldType>>;
+}
+/**
+ * Declare a subagent's success/error result contract.
+ *
+ *   result(
+ *     { files: "string[]", summary: "string" },          // rich success
+ *     { reason: "string", retryable: "boolean" },         // rich error
+ *   )
+ *
+ * (Distinct from a skill's `result:` postcondition gate — this types a
+ * subagent's *return value*, the success/error tracks of the railway.)
+ */
+export declare function result(ok: Record<string, OutputFieldType>, err: Record<string, OutputFieldType>): OutputContract;
+/** One step on a railway: dispatch a flat subagent (the "activity"). */
+export interface RailwayStep {
+    readonly _step: "delegate";
+    /** The subagent to dispatch — resolved against compiled agent names. */
+    readonly agent: string;
+    /** Optional task hint passed to the worker. */
+    readonly task?: string;
+}
+/** Build a railway step that dispatches `agent` (optionally with a task hint). */
+export declare function delegate(agent: string, task?: string): RailwayStep;
+/**
+ * A railway over flat subagents. `steps` run in order on the success track; the
+ * first step that returns an error short-circuits to `onError`. `recover`
+ * optionally retries the failing step a *bounded* number of times before the
+ * error track. There is intentionally no loop combinator — the value is a finite
+ * tree, so it always terminates and is fully verifiable at compile time.
+ */
+export interface Railway {
+    readonly _specType: "railway";
+    readonly name: string;
+    readonly steps: readonly RailwayStep[];
+    /** Error track — runs with the failing step's error payload. */
+    readonly onError?: RailwayStep;
+    /** Bounded recovery: retry the failing step up to `max` times (finite). */
+    readonly recover?: {
+        readonly step: RailwayStep;
+        readonly max: number;
+    };
+}
+/**
+ * Compose flat subagents into a railway (compiles to an orchestrator command).
+ *
+ *   railway({
+ *     name: "ship",
+ *     steps: [delegate("planner"), delegate("coder"), delegate("reviewer")],
+ *     onError: delegate("reporter"),
+ *     recover: { step: delegate("fixer"), max: 2 },
+ *   })
+ */
+export declare function railway(spec: Omit<Railway, "_specType">): Railway;
 /** Derive the spec filename from an output filename. */
 export type SpecPath<Output extends `${string}.md`> = `${Output}.spec.ts`;
 /** Extract the output filename from a spec filename. */