vigiles 2.4.0 → 2.6.0

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/claude-code.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `vigiles/claude-code` — the Claude Code-specific harness pieces a *different*
+ * harness would swap out: the plugin/repo loader (reads real Claude Code plugin
+ * layouts) and the scriptable Anthropic Messages mock. Split from
+ * `vigiles/testing` on purpose — the test API above is the stable surface; this
+ * is the adapter, so a future `vigiles/<other-harness>` can sit beside it.
+ */
+export * from "./plugin-loader.js";
+export * from "./mock-model.js";
+//# sourceMappingURL=claude-code.d.ts.map

package/dist/claude-code.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `vigiles/claude-code` — the Claude Code-specific harness pieces a *different*
+ * harness would swap out: the plugin/repo loader (reads real Claude Code plugin
+ * layouts) and the scriptable Anthropic Messages mock. Split from
+ * `vigiles/testing` on purpose — the test API above is the stable surface; this
+ * is the adapter, so a future `vigiles/<other-harness>` can sit beside it.
+ */
+__exportStar(require("./plugin-loader.js"), exports);
+__exportStar(require("./mock-model.js"), exports);
+//# sourceMappingURL=claude-code.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