vigiles 5.2.0 → 6.0.0

package/README.md

@@ -5,11 +5,11 @@
 <h1 align="center">vigiles</h1>
 
 <p align="center">
-  <strong>Lint &amp; test the harness your AI agent runs on.</strong>
+  <strong>Lint, test &amp; measure the harness your AI agent runs on.</strong>
 </p>
 
 <p align="center">
-  Your CLAUDE.md, hooks, and skills steer the agent — but nothing checks they're <em>true</em>, and nothing tests they <em>work</em>. vigiles does both.
+  Your CLAUDE.md, hooks, and skills steer the agent — but nothing checks they're <em>true</em>, nothing tests they <em>work</em>, and nothing measures whether they actually <em>help</em>. vigiles does all three.
 </p>
 
 <p align="center">
@@ -20,14 +20,17 @@
 
 ---
 
-`Agent = Model + Harness`. You'd never ship an app without a linter and a test
-suite — yet the harness steering your agent runs on vibes. vigiles[^name] is the
-deterministic layer for it, and does two independent things — adopt either, or both:
+`Agent = Model + Harness`. You'd never ship an app without a linter, a test suite,
+and a benchmark — yet the harness steering your agent runs on vibes. vigiles[^name]
+is the deterministic layer for it — and the only one that can **A/B-test what
+actually moves the needle on your Claude subscription**, not metered API. Three
+things, adopt any:
 
-|             |                                                                                                                                                                                                                                                  |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **🔎 Lint** | Every file path, script, code symbol, and linter rule your CLAUDE.md cites is checked against reality — so a renamed file or a disabled rule can't silently mislead the agent. **[→](docs/verifying-instruction-files.md)**                      |
-| **🧪 Test** | Hooks, skills, and subagents are code. vigiles tests they _do their job_ — and almost all of it is **deterministic, no API key**; the real-model evals run on your **Claude subscription**, not metered tokens. **[→](docs/harness-testing.md)** |
+|                |                                                                                                                                                                                                                                                       |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **🔎 Lint**    | Every file path, script, code symbol, and linter rule your CLAUDE.md cites is checked against reality — so a renamed file or a disabled rule can't silently mislead the agent. **[→](docs/verifying-instruction-files.md)**                           |
+| **🧪 Test**    | Hooks, skills, and subagents are code. vigiles tests they _do their job_ — and almost all of it is **deterministic, no API key**; the real-model evals run on your **Claude subscription**, not metered tokens. **[→](docs/harness-testing.md)**      |
+| **📊 Measure** | Does that skill or plugin actually help — or just add cost? **A/B it on real tasks** and read the bill + correctness, not the vendor's headline. The same engine ranks the hyped ecosystem: **what works vs hype**. **[→](docs/measuring-skills.md)** |
 
 Pick the one that hurts today. **Works with Claude Code and Codex**
 ([`vigiles/codex`](docs/harnesses.md)), and you can
@@ -92,7 +95,16 @@ CLAUDE.md:
 File paths, scripts, and code symbols — plus linter rules across **7 catalogs**
 (the rule exists **and is enabled**). Start with one inline comment, no new files;
 step up to a typed `.spec.ts` (compiled to CLAUDE.md, compiler-grade) when you want
-it. **[Full guide →](docs/verifying-instruction-files.md)**
+it — and that same spec is what makes your skills & subagents deterministically
+**testable** (a `result()` contract → an assert, no LLM judge — see ② below), not
+just lint-able. **[Full guide →](docs/verifying-instruction-files.md)**
+
+> **Markdown is prose; a typed spec is a _program_.** Opt in and an agent that
+> leaks, exceeds its effect floor, or hands off mismatched data is a **type
+> error** — your **multi-agent pipeline won't compile if the handoffs don't line
+> up**. Others lint prose after the fact; vigiles is a **compiler for harnesses**.
+> Graduated like TypeScript's `strict` — markdown still works, type-safety is
+> opt-in. **[The moat →](research/typed-spec-moat.md)**
 
 **Same cross-reference, any plugin.** `npx vigiles scan` checks a plugin's
 _contracts_ — every subagent tool, `mcp__server__tool`, `mcp_tool` hook, hook
@@ -121,20 +133,49 @@ It goes well past _"did it fire?"_:
 
 - **Hooks block** what they must — `runHook`, or the real agent CLI via `runHarnessTest`.
 - **Skills trigger** on the right prompts and stay quiet on the wrong ones — recall _and_ precision (`measureTriggerRate`).
-- **Behaviour is good** — score a skill's output directly, or A/B it on-vs-off for the real lift over no-skill (`measure` / `runEval`, with significance testing).
+- **Behaviour is good** — score a skill's output directly, or A/B it on-vs-off for the real lift (`measure` / `runEval`, with significance testing).
 - **Safety holds** — the agent _didn't_ push to the wrong branch or hit a paid API; `interceptTools` catches the attempt so the side effect never happens.
 
-**The eval you can actually afford.** Almost every tier runs with **no model and
-no API key** — milliseconds, on every commit. The rest drive your own `claude` CLI:
+Almost every tier runs with **no model and no API key** — milliseconds, on every
+commit. Only the real-model evals need a model, and they run on your own `claude`
+CLI. **[How it works →](docs/harness-testing.md)**
+
+## ③ Measure — does it actually help, or just cost more?
+
+A skill claims "65% fewer tokens." A plugin promises "3× faster." Stars and
+vibes — **zero measurement**. vigiles A/Bs the claim on real coding tasks, the
+harness loaded exactly as it ships, and reports the **metric triple**:
+
+```typescript
+import { measureArms } from "vigiles/testing";
+
+const r = await measureArms({
+  fixture: { "in.txt": "Implement a slug helper." },
+  task: "Read in.txt, write slugify() to slug.js, explain. Stop.",
+  arms: { baseline: {}, skill: { files: { "SKILL.md": THE_SKILL } } },
+  measure: (ctx) => ({ cost: ctx.usage.costUsd, correct: check(ctx) }),
+});
+// → is the bill lower? did correctness survive? (not just "fewer output tokens")
+```
+
+- **The bill (`costUsd`)** — the honest number; it weights cache ~0.1× and output 1×, so a "saved tokens" headline can't hide behind cheap cache.
+- **The optimization target** — whatever the skill claims to move (output tokens, latency, tool calls). Verified on its own terms.
+- **The blast radius** — correctness, a deterministic 1/0. A token win that breaks the code is **not a win**.
+
+The kicker: every run is **your own `claude` CLI on your Pro/Max subscription** —
+so you can measure on every change, and the same engine powers the **ecosystem
+benchmark** ("we A/B-tested the most-hyped skills — what works vs hype"). That's
+the moat: continuous, sub-affordable measurement nobody metered-by-the-token can
+match. **[Measure a skill →](docs/measuring-skills.md)** · **[Why it's affordable →](docs/eval-architecture.md)**
+
+**The eval you can actually afford.** Most of vigiles needs no model at all; the
+rest drives your subscription:
 
 |                        | Runs on                 | Cost                                        |
 | ---------------------- | ----------------------- | ------------------------------------------- |
 | promptfoo, DeepEval, … | metered API SDK         | billed **per token, every run**             |
 | **vigiles**            | your Claude Pro/Max sub | **$0 extra** — and most tiers need no model |
 
-That's why you can eval your harness on every change, not just once.
-**[How it works →](docs/harness-testing.md)** · **[Why it's affordable →](docs/eval-architecture.md)** · **[Safety model →](docs/safety.md)**
-
 ## More
 
 - **[Plugin health leaderboard →](docs/cli.md#scan-dir)** — point `scan` at a marketplace (e.g. `wshobson/agents`) and it ranks every plugin by structural health (0–100, A–F), worst issues first — still **no key**. Add `--trigger` for the model-gated column: do the skills actually fire?

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

@@ -72,6 +72,31 @@ export declare function setActiveAgent(cwd: string, agentPath: string): void;
 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;
+/**
+ * EXPERIMENTAL — parked (P3), flat-only, do NOT auto-wire. This deterministic
+ * subagent-window tracking assumes FLAT dispatch (one active subagent at a time);
+ * it is NOT nesting-safe — Claude Code v2.1.172 added depth-5 nested subagents, so
+ * correct tracking needs a depth-aware STACK (push on dispatch, pop on SubagentStop)
+ * + verifying the spawn tool name (`Agent` vs `Task`). See
+ * research/effect-boundary-design.md ("Why dropped").
+ *
+ * Resolve a `Task` tool's `subagent_type` to the compiled agent `.md` to
+ * activate, or null when none is found. The DETERMINISTIC open signal that
+ * replaces the model-invoked `agent-start`: Claude Code fires `PreToolUse` for
+ * the parent's `Task` dispatch (and `SubagentStop` when it returns), so the
+ * harness — not the model — brackets the subagent's active window. The name is
+ * the last ":"-segment (a `--plugin-dir` subagent_type is namespaced
+ * "plugin:name"); searched in `agents/` under the cwd then the plugin root. A
+ * path under the cwd is returned relative (readActiveAgent resolves vs cwd); a
+ * plugin-root hit is absolute. Returns null on an unknown agent (fail-open: an
+ * unresolved subagent is simply not gated, exactly as before agent-start ran).
+ */
+export declare function resolveDispatchedAgent(subagentType: string, cwd: string, pluginRoot?: string): string | null;
+/**
+ * The agent `.md` to activate for a `PreToolUse(Task)` event, or null. Pure
+ * (reads `tool_input.subagent_type`, resolves via {@link resolveDispatchedAgent}).
+ */
+export declare function decideTaskDispatch(toolInput: unknown, cwd: string, pluginRoot?: string): string | null;
 /**
  * PreToolUse-hook decision. If an agent is active, enforce BOTH deterministic
  * rails its compiled `.md` declares, in order:

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

@@ -31,6 +31,8 @@ exports.decidePreToolUse = decidePreToolUse;
 exports.setActiveAgent = setActiveAgent;
 exports.clearActiveAgent = clearActiveAgent;
 exports.readActiveAgent = readActiveAgent;
+exports.resolveDispatchedAgent = resolveDispatchedAgent;
+exports.decideTaskDispatch = decideTaskDispatch;
 exports.evaluatePreToolUse = evaluatePreToolUse;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -129,6 +131,47 @@ function readActiveAgent(cwd) {
 // ---------------------------------------------------------------------------
 // PreToolUse-hook decision
 // ---------------------------------------------------------------------------
+/**
+ * EXPERIMENTAL — parked (P3), flat-only, do NOT auto-wire. This deterministic
+ * subagent-window tracking assumes FLAT dispatch (one active subagent at a time);
+ * it is NOT nesting-safe — Claude Code v2.1.172 added depth-5 nested subagents, so
+ * correct tracking needs a depth-aware STACK (push on dispatch, pop on SubagentStop)
+ * + verifying the spawn tool name (`Agent` vs `Task`). See
+ * research/effect-boundary-design.md ("Why dropped").
+ *
+ * Resolve a `Task` tool's `subagent_type` to the compiled agent `.md` to
+ * activate, or null when none is found. The DETERMINISTIC open signal that
+ * replaces the model-invoked `agent-start`: Claude Code fires `PreToolUse` for
+ * the parent's `Task` dispatch (and `SubagentStop` when it returns), so the
+ * harness — not the model — brackets the subagent's active window. The name is
+ * the last ":"-segment (a `--plugin-dir` subagent_type is namespaced
+ * "plugin:name"); searched in `agents/` under the cwd then the plugin root. A
+ * path under the cwd is returned relative (readActiveAgent resolves vs cwd); a
+ * plugin-root hit is absolute. Returns null on an unknown agent (fail-open: an
+ * unresolved subagent is simply not gated, exactly as before agent-start ran).
+ */
+function resolveDispatchedAgent(subagentType, cwd, pluginRoot) {
+    const name = subagentType.split(":").pop()?.trim();
+    if (!name)
+        return null;
+    const rel = (0, node_path_1.join)("agents", `${name}.md`);
+    if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, rel)))
+        return rel;
+    if (pluginRoot && (0, node_fs_1.existsSync)((0, node_path_1.resolve)(pluginRoot, rel))) {
+        return (0, node_path_1.resolve)(pluginRoot, rel);
+    }
+    return null;
+}
+/**
+ * The agent `.md` to activate for a `PreToolUse(Task)` event, or null. Pure
+ * (reads `tool_input.subagent_type`, resolves via {@link resolveDispatchedAgent}).
+ */
+function decideTaskDispatch(toolInput, cwd, pluginRoot) {
+    const st = toolInput?.subagent_type;
+    if (typeof st !== "string" || !st)
+        return null;
+    return resolveDispatchedAgent(st, cwd, pluginRoot);
+}
 /**
  * PreToolUse-hook decision. If an agent is active, enforce BOTH deterministic
  * rails its compiled `.md` declares, in order:

package/dist/adapters/claude-code/dialect.d.ts

@@ -8,6 +8,40 @@
  * in its adapter (e.g. `src/adapters/codex/dialect.ts` exporting `codexDialect`).
  */
 import type { HarnessDialect } from "../../core/dialect.js";
+/**
+ * The Claude Code built-in subagent tool catalog as a `const` tuple, so a typed
+ * authoring surface can derive a LITERAL union (`ClaudeCodeBuiltinTool`) from it.
+ * `claudeCodeDialect.builtinAgentTools` references this same array — one source
+ * of truth for the runtime catalog AND the compile-time tool vocabulary.
+ */
+export declare const claudeCodeBuiltinAgentTools: readonly ["Read", "Write", "Edit", "MultiEdit", "Bash", "BashOutput", "KillBash", "Grep", "Glob", "LS", "WebSearch", "WebFetch", "NotebookEdit", "TodoWrite", "Task", "Skill"];
+/**
+ * The Claude Code side-effecting tools as a `const` tuple (the complement of
+ * read-only within `builtinAgentTools`). `claudeCodeDialect.sideEffectingTools`
+ * references this; the typed vocabulary derives the read-only / bounded splits.
+ */
+export declare const claudeCodeSideEffectingTools: readonly ["Bash", "BashOutput", "KillBash", "Edit", "MultiEdit", "Write", "NotebookEdit", "WebFetch", "WebSearch", "Skill", "Task", "TodoWrite"];
 export declare const claudeCodeDialect: HarnessDialect;
+/** Every Claude Code built-in subagent tool (literal union). */
+export type ClaudeCodeBuiltinTool = (typeof claudeCodeBuiltinAgentTools)[number];
+/** The side-effecting subset (literal union). */
+export type ClaudeCodeSideEffectingTool = (typeof claudeCodeSideEffectingTools)[number];
+/**
+ * Read-only built-in tools — the complement of the side-effecting set within
+ * the built-in catalog. The tools a `pure` CC unit may declare.
+ */
+export type ClaudeCodeReadOnlyTool = Exclude<ClaudeCodeBuiltinTool, ClaudeCodeSideEffectingTool>;
+/**
+ * Tools a `bounded` CC unit may declare: read-only ∪ the decidable
+ * side-effecting tools (Write/Edit/MultiEdit/NotebookEdit) ∪ `Bash` (its
+ * command is decided at RUNTIME by the gate). Bars MCP / unknown / wildcard —
+ * those are simply not in the built-in union, so listing one is a `tsc` error.
+ *
+ * NOTE: `BashOutput`/`KillBash` are read-only-ish helpers tied to a running
+ * Bash; `Bash` is the admitting tool, so they're included via the read-only
+ * exclusion path only if read-only — here they stay side-effecting, hence the
+ * explicit add of the bounded-decidable set plus `Bash`.
+ */
+export type ClaudeCodeBoundedTool = ClaudeCodeReadOnlyTool | "Write" | "Edit" | "MultiEdit" | "NotebookEdit" | "Bash";
 export type { HarnessDialect } from "../../core/dialect.js";
 //# sourceMappingURL=dialect.d.ts.map

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

@@ -1,28 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.claudeCodeDialect = void 0;
+exports.claudeCodeDialect = exports.claudeCodeSideEffectingTools = exports.claudeCodeBuiltinAgentTools = void 0;
+/**
+ * The Claude Code built-in subagent tool catalog as a `const` tuple, so a typed
+ * authoring surface can derive a LITERAL union (`ClaudeCodeBuiltinTool`) from it.
+ * `claudeCodeDialect.builtinAgentTools` references this same array — one source
+ * of truth for the runtime catalog AND the compile-time tool vocabulary.
+ */
+exports.claudeCodeBuiltinAgentTools = [
+    "Read",
+    "Write",
+    "Edit",
+    "MultiEdit",
+    "Bash",
+    "BashOutput",
+    "KillBash",
+    "Grep",
+    "Glob",
+    "LS",
+    "WebSearch",
+    "WebFetch",
+    "NotebookEdit",
+    "TodoWrite",
+    "Task",
+    "Skill",
+];
+/**
+ * The Claude Code side-effecting tools as a `const` tuple (the complement of
+ * read-only within `builtinAgentTools`). `claudeCodeDialect.sideEffectingTools`
+ * references this; the typed vocabulary derives the read-only / bounded splits.
+ */
+exports.claudeCodeSideEffectingTools = [
+    "Bash",
+    "BashOutput",
+    "KillBash",
+    "Edit",
+    "MultiEdit",
+    "Write",
+    "NotebookEdit",
+    "WebFetch",
+    "WebSearch",
+    "Skill",
+    "Task",
+    "TodoWrite",
+];
 exports.claudeCodeDialect = {
     name: "claude-code",
     // The tool contract a subagent may declare — the rails it runs on. Anything
     // else must be an MCP tool, else it's a typo / nonexistent tool.
-    builtinAgentTools: [
-        "Read",
-        "Write",
-        "Edit",
-        "MultiEdit",
-        "Bash",
-        "BashOutput",
-        "KillBash",
-        "Grep",
-        "Glob",
-        "LS",
-        "WebSearch",
-        "WebFetch",
-        "NotebookEdit",
-        "TodoWrite",
-        "Task",
-        "Skill",
-    ],
+    builtinAgentTools: exports.claudeCodeBuiltinAgentTools,
     // Tools the platform never exposes to a subagent, whatever the list says — so
     // a subagent listing one is a guaranteed-dead reference only a compiler catches.
     neverAvailableTools: [
@@ -68,19 +94,6 @@ exports.claudeCodeDialect = {
     // which are not in the subagent catalog). Bash is side-effecting because
     // `cat` and `rm -rf` are the same tool at the tool-name level — the
     // sandbox is the only closure for subprocess effects.
-    sideEffectingTools: [
-        "Bash",
-        "BashOutput",
-        "KillBash",
-        "Edit",
-        "MultiEdit",
-        "Write",
-        "NotebookEdit",
-        "WebFetch",
-        "WebSearch",
-        "Skill",
-        "Task",
-        "TodoWrite",
-    ],
+    sideEffectingTools: exports.claudeCodeSideEffectingTools,
 };
 //# sourceMappingURL=dialect.js.map

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

@@ -38,7 +38,6 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const effects_js_1 = require("../../core/effects.js");
 const dialect_js_1 = require("./dialect.js");
-const effect_region_js_1 = require("./effect-region.js");
 const STEP_RE = /^###\s+Step\s+(\d+)/;
 const GATE_CMD_RE = /<!--\s*vigiles:gate\s+"([^"]*)"(?:\s+retry:(\d+))?\s*-->/;
 const GATE_FILE_RE = /<!--\s*vigiles:gate\s+file:(\S+)\s*-->/;
@@ -294,13 +293,6 @@ function evaluateSkillPreToolUse(cwd, tool, command) {
         return { allow: true, message: "" };
     const md = (0, node_fs_1.readFileSync)(full, "utf-8");
     const purity = parseSkillPurity(md);
-    const boundary = (0, effect_region_js_1.hasEffectBoundary)(md);
-    if (boundary) {
-        const effective = (0, effect_region_js_1.readEffectActive)(cwd)
-            ? (purity ?? "unrestricted")
-            : "pure";
-        return (0, effects_js_1.decidePurityGate)(effective, tool, command, dialect_js_1.claudeCodeDialect);
-    }
     if (!purity)
         return { allow: true, message: "" };
     return (0, effects_js_1.decidePurityGate)(purity, tool, command, dialect_js_1.claudeCodeDialect);

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/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);