vigiles 5.1.0 → 6.0.0

package/dist/adapters/claude-code/typed-spec.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Typed Claude Code authoring surface — the compile-time half of the purity
+ * contract, bound to the Claude Code tool vocabulary.
+ *
+ * The core `agent()` / `skill()` builders (`vigiles/spec`) are generic over a
+ * tool `ToolVocabulary` that DEFAULTS to fully-open (`string` at every purity
+ * level), so they accept any tools — backwards-compatible, harness-agnostic.
+ * This module re-binds them to the CONCRETE Claude Code vocabulary derived from
+ * `claudeCodeDialect`, so authoring a spec with an invalid `purity`×`tools`
+ * combination is a `tsc` error at EDIT TIME, before any vigiles command runs:
+ *
+ *   import { agent } from "vigiles/claude-code";
+ *
+ *   agent({ purity: "pure", tools: ["Read", "Bash"] });
+ *   //                                       ^^^^^^ tsc error — Bash side-effecting
+ *
+ *   agent({ purity: "bounded", tools: ["Read", "Bash", "Write"] }); // OK
+ *   agent({ purity: "bounded", tools: ["mcp__x__y"] });
+ *   //                                  ^^^^^^^^^^^ tsc error — MCP not decidable
+ *
+ *   agent({ tools: ["anything", "mcp__x__y"] }); // no purity → open, OK
+ *
+ * This is a STRICT ADDITION to the runtime/compile checks: `purityViolations`
+ * (`vigiles compile`) and `decidePurityGate` (the PreToolUse gate) are unchanged
+ * and remain the universal backstop. In particular the command-level decision a
+ * `bounded` unit makes for `Bash` (read-only command allowed, mutating denied)
+ * is the RUNTIME gate's job — the type only admits the `Bash` TOOL at `bounded`.
+ *
+ * The CC literal tool names live ONLY in this adapter (and the dialect it reads
+ * from), never in core — the hexagonal boundary that keeps the domain
+ * harness-agnostic.
+ */
+import { type AgentSpec, type AgentSpecInput, type SkillSpec, type SkillSpecInput, type AuthoredPurity, type ToolVocabulary } from "../../core/spec.js";
+import type { ClaudeCodeReadOnlyTool, ClaudeCodeBoundedTool } from "./dialect.js";
+/**
+ * The Claude Code tool vocabulary, split by the purity floor that admits each
+ * tool (mirrors the runtime ladder in `core/effects.ts`):
+ * - `readOnly`: tools a `pure` unit may declare (Read/Grep/Glob/LS).
+ * - `bounded`:  read-only ∪ Write/Edit/MultiEdit/NotebookEdit ∪ `Bash`.
+ */
+export interface ClaudeCodeToolVocabulary extends ToolVocabulary {
+    readonly readOnly: ClaudeCodeReadOnlyTool;
+    readonly bounded: ClaudeCodeBoundedTool;
+}
+/**
+ * Define a Claude Code subagent with the purity floor enforced AT COMPILE TIME
+ * against the Claude Code tool catalog. Identical to the core `agent()` at
+ * runtime (it IS the core builder); the only difference is the typed `tools`
+ * constraint. `P` is inferred from the literal `purity` field.
+ */
+export declare function agent<const P extends AuthoredPurity | undefined = undefined>(spec: AgentSpecInput<P, ClaudeCodeToolVocabulary>): AgentSpec;
+/**
+ * Define a Claude Code skill with the purity floor enforced AT COMPILE TIME
+ * against the Claude Code tool catalog. Identical to the core `skill()` at
+ * runtime; the typed `tools` constraint is the only difference.
+ */
+export declare function skill<const P extends AuthoredPurity | undefined = undefined>(spec: SkillSpecInput<P, ClaudeCodeToolVocabulary>): SkillSpec;
+//# sourceMappingURL=typed-spec.d.ts.map

package/dist/adapters/claude-code/typed-spec.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agent = agent;
+exports.skill = skill;
+/**
+ * Typed Claude Code authoring surface — the compile-time half of the purity
+ * contract, bound to the Claude Code tool vocabulary.
+ *
+ * The core `agent()` / `skill()` builders (`vigiles/spec`) are generic over a
+ * tool `ToolVocabulary` that DEFAULTS to fully-open (`string` at every purity
+ * level), so they accept any tools — backwards-compatible, harness-agnostic.
+ * This module re-binds them to the CONCRETE Claude Code vocabulary derived from
+ * `claudeCodeDialect`, so authoring a spec with an invalid `purity`×`tools`
+ * combination is a `tsc` error at EDIT TIME, before any vigiles command runs:
+ *
+ *   import { agent } from "vigiles/claude-code";
+ *
+ *   agent({ purity: "pure", tools: ["Read", "Bash"] });
+ *   //                                       ^^^^^^ tsc error — Bash side-effecting
+ *
+ *   agent({ purity: "bounded", tools: ["Read", "Bash", "Write"] }); // OK
+ *   agent({ purity: "bounded", tools: ["mcp__x__y"] });
+ *   //                                  ^^^^^^^^^^^ tsc error — MCP not decidable
+ *
+ *   agent({ tools: ["anything", "mcp__x__y"] }); // no purity → open, OK
+ *
+ * This is a STRICT ADDITION to the runtime/compile checks: `purityViolations`
+ * (`vigiles compile`) and `decidePurityGate` (the PreToolUse gate) are unchanged
+ * and remain the universal backstop. In particular the command-level decision a
+ * `bounded` unit makes for `Bash` (read-only command allowed, mutating denied)
+ * is the RUNTIME gate's job — the type only admits the `Bash` TOOL at `bounded`.
+ *
+ * The CC literal tool names live ONLY in this adapter (and the dialect it reads
+ * from), never in core — the hexagonal boundary that keeps the domain
+ * harness-agnostic.
+ */
+const spec_js_1 = require("../../core/spec.js");
+/**
+ * Define a Claude Code subagent with the purity floor enforced AT COMPILE TIME
+ * against the Claude Code tool catalog. Identical to the core `agent()` at
+ * runtime (it IS the core builder); the only difference is the typed `tools`
+ * constraint. `P` is inferred from the literal `purity` field.
+ */
+function agent(spec) {
+    return (0, spec_js_1.agent)(spec);
+}
+/**
+ * Define a Claude Code skill with the purity floor enforced AT COMPILE TIME
+ * against the Claude Code tool catalog. Identical to the core `skill()` at
+ * runtime; the typed `tools` constraint is the only difference.
+ */
+function skill(spec) {
+    return (0, spec_js_1.skill)(spec);
+}
+//# sourceMappingURL=typed-spec.js.map

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/layout.js

@@ -9,6 +9,9 @@ exports.codexLayout = {
     settingsFormat: "toml",
     instructionFile: "AGENTS.md",
     surfaceDirs: ["skills", "prompts"],
+    skillDir: "skills",
+    agentDir: "", // Codex `[agents]` is a TOML concurrency table, not a subagent dir
+    commandDir: "prompts",
     materializeRoot: ".codex",
     pluginRootToken: "${PLUGIN_ROOT}",
     mcpConfigFile: ".mcp.json",

package/dist/adapters/opencode/adapter.js

@@ -29,6 +29,7 @@ exports.opencodeAdapter = {
         referenceVerification: true,
         harnessTesting: true,
         shellHooks: false,
+        subagents: true,
     },
     dialect: dialect_js_1.opencodeDialect,
     layout: layout_js_1.opencodeLayout,

package/dist/adapters/opencode/layout.js

@@ -16,6 +16,9 @@ exports.opencodeLayout = {
     // `.opencode/` segment. (Contrast Claude Code: root-level `skills/` surfaces
     // relocated under `.claude`.)
     surfaceDirs: [".opencode/agent", ".opencode/command"],
+    skillDir: ".opencode/skill",
+    agentDir: ".opencode/agent",
+    commandDir: ".opencode/command",
     materializeRoot: "",
     pluginRootToken: "${OPENCODE_PLUGIN_ROOT}",
     mcpConfigFile: "opencode.json",

package/dist/check.d.ts

@@ -104,6 +104,14 @@ export declare function turns(opts: {
 }): Check<Trace>;
 /** The agent wrote (or left) a file at this path in the work dir. */
 export declare function wrote(path: string): Check<Trace>;
+/**
+ * The agent did NOT leave a file at this path — the **side-effect boundary**
+ * negative: a skill that declares it writes only `out.txt` should leave nothing
+ * at `secrets.env`. The symmetric sibling of `wrote()`; pairs with
+ * `notTool(...)` to assert a unit stayed inside its declared write surface
+ * deterministically (no model judge).
+ */
+export declare function didNotWrite(path: string): Check<Trace>;
 /** The named subagent (`Task` `subagent_type`) ran and passed every nested check. */
 export declare function subagent(name: string, checks: readonly Check<Trace>[]): Check<Trace>;
 /** The hook blocked the event (exit 2 / deny / block). */

package/dist/check.js

@@ -11,6 +11,7 @@ exports.hookFired = hookFired;
 exports.received = received;
 exports.turns = turns;
 exports.wrote = wrote;
+exports.didNotWrite = didNotWrite;
 exports.subagent = subagent;
 exports.blocked = blocked;
 exports.allowed = allowed;
@@ -236,16 +237,34 @@ function wrote(path) {
         toJSON: () => ({ kind: "wrote", path }),
     };
 }
+/**
+ * The agent did NOT leave a file at this path — the **side-effect boundary**
+ * negative: a skill that declares it writes only `out.txt` should leave nothing
+ * at `secrets.env`. The symmetric sibling of `wrote()`; pairs with
+ * `notTool(...)` to assert a unit stayed inside its declared write surface
+ * deterministically (no model judge).
+ */
+function didNotWrite(path) {
+    return {
+        kind: "didNotWrite",
+        eval: (t) => t.file(path) === null
+            ? ok(`file "${path}" was not created`)
+            : no(`expected the agent NOT to create "${path}", but it exists`),
+        toJSON: () => ({ kind: "didNotWrite", path }),
+    };
+}
 // ---------------------------------------------------------------------------
 // Subagent — a `Task` run as a nested trace. Run checks over what the SUBAGENT
 // did, not just that `Task` fired. Composes the whole vocabulary recursively.
 // ---------------------------------------------------------------------------
-/** Wrap a subagent's tool calls as a minimal `Trace` so checks run over it. */
+/** Wrap a subagent's tool calls + returned text as a minimal `Trace` so checks
+ * (incl. `output()` over the sub's RETURN — where a result() vigiles:ok/err block
+ * lands) run over it. */
 function subTrace(sub) {
     return {
         toolCalls: sub.toolCalls,
         hooks: [],
-        output: "",
+        output: sub.output,
         modelRequests: [],
         turns: 0,
         subagents: [],
@@ -258,7 +277,12 @@ function subagent(name, checks) {
         kind: "subagent",
         eval: (t) => {
             const subs = t.subagents ?? [];
-            const sub = subs.find((s) => s.name === name);
+            // A `--plugin-dir` agent's `subagent_type` is namespaced `plugin:agent`
+            // (e.g. "reviewer-spec:code-reviewer"), but callers pass the bare agent name
+            // — so match the full id OR its last `:`-segment. Non-namespaced (harness
+            // mock) names match exactly as before.
+            const bare = (n) => n.includes(":") ? n.slice(n.lastIndexOf(":") + 1) : n;
+            const sub = subs.find((s) => s.name === name || bare(s.name) === name);
             if (!sub) {
                 return no(`expected subagent "${name}" to run; subagents that ran: ${subs.length > 0 ? `[${subs.map((s) => s.name).join(", ")}]` : "none"}`);
             }

package/dist/claude-code.d.ts

@@ -9,6 +9,7 @@ export * from "./adapters/claude-code/plugin-loader.js";
 export * from "./mock-model.js";
 export { claudeCodeDriver, buildClaudeArgs, parseClaudeRun, claudeAvailable, } from "./harness-test.js";
 export * from "./adapters/claude-code/dialect.js";
+export { agent, skill, type ClaudeCodeToolVocabulary, } from "./adapters/claude-code/typed-spec.js";
 export * from "./adapters/claude-code/layout.js";
 export * from "./adapters/claude-code/runtime.js";
 export * from "./adapters/claude-code/hook-protocol.js";

package/dist/claude-code.js

@@ -14,7 +14,7 @@ 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 });
-exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
+exports.skill = exports.agent = exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
 /**
  * `vigiles/claude-code` — the Claude Code-specific harness pieces a *different*
  * harness would swap out: the plugin/repo loader (reads real Claude Code plugin
@@ -35,6 +35,13 @@ Object.defineProperty(exports, "buildClaudeArgs", { enumerable: true, get: funct
 Object.defineProperty(exports, "parseClaudeRun", { enumerable: true, get: function () { return harness_test_js_1.parseClaudeRun; } });
 Object.defineProperty(exports, "claudeAvailable", { enumerable: true, get: function () { return harness_test_js_1.claudeAvailable; } });
 __exportStar(require("./adapters/claude-code/dialect.js"), exports);
+// The typed Claude Code authoring surface: `agent` / `skill` with the `purity`
+// floor enforced AT COMPILE TIME against the CC tool catalog (a `tsc` error for
+// e.g. `purity: "pure"` + `"Bash"`). A strict addition to the runtime/compile
+// purity checks; the bare core `agent()`/`skill()` (`vigiles/spec`) stay open.
+var typed_spec_js_1 = require("./adapters/claude-code/typed-spec.js");
+Object.defineProperty(exports, "agent", { enumerable: true, get: function () { return typed_spec_js_1.agent; } });
+Object.defineProperty(exports, "skill", { enumerable: true, get: function () { return typed_spec_js_1.skill; } });
 __exportStar(require("./adapters/claude-code/layout.js"), exports);
 __exportStar(require("./adapters/claude-code/runtime.js"), exports);
 __exportStar(require("./adapters/claude-code/hook-protocol.js"), exports);