vigiles 5.2.0 → 7.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>Make the harness your AI agent runs on reliable.</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 stops them entering a <em>bad state</em>, nothing tests they <em>work</em>, and nothing measures whether they actually <em>help</em>. vigiles does all four — deterministically, mostly with no API key.
 </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`. The model gets the headlines; the **harness** — the
+instruction files, hooks, and skills you actually control — is the half that
+fails silently. vigiles[^name] turns that harness into a compilable, analyzable,
+testable object instead of vibes. Four instruments, 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 — a lint that asks _is this **true**_, not just _well-formed_ — so a renamed file or a disabled rule can't silently mislead the agent. **[→](docs/verifying-instruction-files.md)** |
+| **🛡 Guard** | Author a hook as a pure typed function and vigiles compiles it — making **whole classes of hook bugs unrepresentable** (the guard that silently doesn't block). **[→](docs/compiled-hooks.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)**                                          |
+| **📊 Eval**  | 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 eval you can afford. 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
@@ -50,24 +53,16 @@ Or do it yourself:
 npx vigiles init   # sets up lint + test: spec + harness test + CI + plugin
 ```
 
-It's interactive in a terminal and non-interactive for agents/CI (or with
-`--yes`), so "set up vigiles" from a Claude Code / Codex prompt Just Works — and
-it installs a model-invocable **`test-harness` skill**, so afterward you can just
-tell your agent _"test my skills"_ and it picks the tier and writes the test.
+Interactive in a terminal, non-interactive for agents/CI (or `--yes`). It installs
+a model-invocable **`test-harness` skill** too, so you can then tell your agent
+_"test my skills"_ and it writes the test.
 
 <details>
 <summary>What <code>init</code> sets up</summary>
 
-- **Both lint and test** by default; scope with `--lint` / `--test` (one or both).
-- Adds `vigiles` to your `devDependencies`.
-- Installs the Claude Code plugin (skills + hooks) via the marketplace —
-  globally, never vendored into your repo.
-- Wires CI as a `zernie/vigiles@v1` workflow (a composite over the same CLI):
-
-  ```yaml
-  - uses: actions/checkout@v4
-  - uses: zernie/vigiles@v1 # lints by default; posts a sticky PR comment + a `valid` output
-  ```
+- **Both lint and test** by default; scope with `--lint` / `--test`.
+- Adds `vigiles` to `devDependencies`; installs the Claude Code plugin (skills + hooks) via the marketplace — globally, never vendored.
+- Wires CI as a `zernie/vigiles@v1` workflow (a composite over the same CLI) that posts a sticky PR comment + a `valid` output.
 
 Prefer to write tests yourself? They can be JS **or** TS
 (`*.harness.{mjs,ts}`) — run them with `npx vigiles test`.
@@ -76,11 +71,10 @@ Prefer to write tests yourself? They can be JS **or** TS
 
 ## ① Lint — your CLAUDE.md lies to your agent
 
-Your CLAUDE.md points the agent at `src/auth/login.ts` and tells it to run
-`npm run check`. But the file moved to `src/auth/session.ts` six commits ago, and
-the script was renamed. The agent trusts the stale claim and acts on fiction.
-
-`npx vigiles lint` resolves every reference against reality:
+Your CLAUDE.md points the agent at `src/auth/login.ts` and says to run `npm run
+check`. But the file moved six commits ago and the script was renamed — the agent
+trusts the stale claim and acts on fiction. `npx vigiles lint` resolves every
+reference against reality:
 
 ```text
 CLAUDE.md:
@@ -91,19 +85,54 @@ 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)**
+step up to a typed `.spec.ts` (compiled to CLAUDE.md) when you want it.
+**[Full guide →](docs/verifying-instruction-files.md)**
+
+> **Markdown is prose; a typed spec is a _program_.** Opt in and an agent that
+> leaks 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; vigiles
+> is a **compiler for harnesses**, graduated like `strict`. **[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
 event, and script path actually **exists and resolves**, not just parses (valid
-YAML ≠ a tool that's real). A **superset of Anthropic's `claude plugin validate`**,
-no key. **[Audit any plugin →](docs/cli.md#scan-dir)**
+YAML ≠ a real tool). A **superset of `claude plugin validate`**, no key. **[Audit any plugin →](docs/cli.md#scan-dir)**
+
+## ② Guard — author a hook that can't be wrong
+
+A safety hook is the one place that can _stop_ the agent before something
+irreversible — yet hand-written hooks fail silently (`exit 1` not `2`, the wrong
+JSON field, a `grep` that misses `cd x && git push -f`): they look like a guard
+and block nothing. Write the hook as a pure typed function instead — vigiles
+compiles the protocol for you:
+
+```typescript
+import { defineHook, tool, deny, allow } from "vigiles/hook";
+
+export default defineHook({
+  on: "PreToolUse",
+  match: tool("Bash"),
+  decide: (e) =>
+    e.command.runs("git push", { force: true })
+      ? deny("no force-push to a protected branch")
+      : allow(),
+});
+```
 
-## ② Test — does your harness do its job?
+This **eliminates an entire class of bugs**: you never write the exit code / JSON
+field (false confidence), the matcher is **AST-backed** (catches the compound
+bypass a glob misses), the only import allowed is `vigiles/hook` (capability = API
+surface), and the artifact is **stamped** (a later hand-edit is refused). A real,
+widely-copied OSS safety hook blocks **2/7** of the disaster battery; the compiled
+rewrite blocks **7/7**. Honest about the cons: this fixes a hook's _logic_, not
+the harness's _delivery_ — a subagent's tool calls still bypass any PreToolUse
+hook ([#34692](https://github.com/anthropics/claude-code/issues/34692)), so it's a
+strong default, not an unbypassable wall. **[Compiled hooks — bug classes + trade-offs →](docs/compiled-hooks.md)**
 
-A hook can be wired wrong. A skill's description can fail to trigger — or hijack
-unrelated prompts. Injected context can never reach the model. All of it passes a
+## ③ Test — does your harness do its job?
+
+A hook can be wired wrong; a skill's description can fail to trigger — or hijack
+unrelated prompts; injected context can never reach the model. All of it passes a
 naive "did it run?" check. vigiles tests the assembled harness for real:
 
 ```typescript
@@ -121,26 +150,48 @@ 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, 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, on your own `claude` CLI.
+**[How it works →](docs/harness-testing.md)**
+
+## ④ Eval — 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) }),
+});
+```
+
+- **The bill (`costUsd`)** — weights cache ~0.1× / output 1×, so a "saved tokens" headline can't hide behind cheap cache.
+- **The 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**.
 
-|                        | 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 |
+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** ("what works vs hype"). **[Eval a skill →](docs/measuring-skills.md)** · **[Why it's affordable →](docs/eval-architecture.md)**
 
-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)**
+**The eval you can actually afford.** promptfoo / DeepEval / … hit a metered API
+SDK and bill **per token, every run**; vigiles answers most questions with **no
+model at all** and runs the rest on **your Claude Pro/Max subscription — $0 extra**.
 
 ## 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?
-- **[CLI & GitHub Action →](docs/cli.md)** — every command, the Action (inputs / output / versioning), and the Claude Code plugin. The full **[lint rules matrix →](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix)** lives with the linting guide.
-- **[Skills →](docs/skills.md)** — consumer skills installed as a Claude Code plugin: `/plugin marketplace add zernie/vigiles` then `/plugin install vigiles@vigiles` (or let `vigiles init` do it). The model-invocable ones (`test-harness`, `strengthen`, `edit-spec`) fire on their own — ask _"test my skills"_, _"strengthen my rules"_, or _"add a rule to CLAUDE.md"_ and the agent reaches for them; `adopt-spec` and `linter-docs` are user-invoked.
-- **[Docs index →](docs/README.md)** · **[Research →](research/README.md)** · **[Related tools →](docs/related-tools.md)** (ast-grep, Dependency Cruiser, Ruler, rulesync).
+- **[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 — **no key**. Add `--trigger` for the model-gated column: do the skills actually fire?
+- **[CLI & GitHub Action →](docs/cli.md)** — every command (incl. compiled hooks via `compile`), the Action, and the plugin. The full **[lint rules matrix →](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix)** lives with the linting guide.
+- **[Skills →](docs/skills.md)** — consumer skills installed as a Claude Code plugin. The model-invocable ones (`test-harness`, `strengthen`, `edit-spec`) fire on their own — ask _"test my skills"_ and the agent reaches for them.
+- **[Docs index →](docs/README.md)** · **[Research →](research/README.md)** · **[API reference →](https://zernie.github.io/vigiles/)** (generated) · **[Related tools →](docs/related-tools.md)** (ast-grep, Dependency Cruiser, Ruler, rulesync).
 - Companion to [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need).
 
 ## License

package/dist/action-gate.js

@@ -13,7 +13,7 @@ exports.loadActionGates = loadActionGates;
  *
  * It is the same deterministic gate primitive (reuses `runGate` + the
  * author-time reference resolution), re-anchored from step → action. Delivered
- * as a PostToolUse hook (`vigiles action-hook`): exit 2 blocks the action and
+ * as a PostToolUse hook (`vigiles hook-runtime action`): exit 2 blocks the action and
  * feeds the reason back, exit 0 allows it.
  *
  * Config: `.vigiles/action-gates.json` → `{ "gates": [ { on, gate, when? } ] }`.

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

@@ -10,7 +10,7 @@
  * 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
+ * (`src/adapters/claude-code/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
@@ -66,12 +66,72 @@ export interface PreToolDecision {
  *   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. */
+/**
+ * Read the active-agent stack (oldest → newest; the dispatched subagent chain).
+ * Back-compat: a legacy single-slot `{ agent: string }` marker reads as a one-frame
+ * stack; a malformed file or non-string entries → an empty stack (fail-open).
+ */
+export declare function readActiveStack(cwd: string): string[];
+/**
+ * Push a dispatched subagent onto the active stack (a `PreToolUse` spawn). The
+ * PreToolUse gate then enforces this subagent's contract until it returns. Under
+ * nesting each dispatch pushes a frame, so the chain is tracked, not overwritten.
+ */
+export declare function pushActiveAgent(cwd: string, agentPath: string): void;
+/**
+ * Pop the top frame — the subagent returned (`SubagentStop`), so control returns
+ * to its PARENT (the next frame down), whose contract the gate enforces again.
+ * This is the nesting-safe close, distinct from {@link clearActiveAgent} (which
+ * drops the whole stack). Popping an empty stack is a no-op.
+ */
+export declare function popActiveAgent(cwd: string): void;
+/**
+ * Push a subagent frame (the manual `agent-start` fallback + the deterministic
+ * spawn open-signal both use this). A single call is equivalent to a one-frame
+ * stack, so the top — what the gate reads — is this agent. Alias of
+ * {@link pushActiveAgent} kept under the historical name.
+ */
 export declare function setActiveAgent(cwd: string, agentPath: string): void;
-/** Clear the active-agent marker (the subagent finished). */
+/**
+ * Clear the WHOLE stack (a hard reset / session end). Distinct from
+ * {@link popActiveAgent}, which returns to the parent frame. Idempotent.
+ */
 export declare function clearActiveAgent(cwd: string): void;
-/** The path of the active agent's compiled `.md`, or null when none is active. */
+/**
+ * The active agent's compiled `.md` — the STACK TOP — or null when none is active.
+ * The gate reads the top, so a returned nested subagent reveals its parent's
+ * contract again (the contract-escape fix).
+ */
 export declare function readActiveAgent(cwd: string): string | null;
+/**
+ * EXPERIMENTAL — parked (P3), do NOT auto-wire. The subagent-window tracking is
+ * now nesting-safe: a depth-aware STACK (push on dispatch, pop on SubagentStop —
+ * see {@link pushActiveAgent}/{@link popActiveAgent}) closes the contract-escape
+ * the flat single-slot model allowed under Claude Code v2.1.172 depth-5 nesting
+ * (certified in research/prototypes/.../AgentWindowStack.tla). The open signal
+ * recognizes BOTH spawn tool names (`Task` and the nested-spawn `Agent`), gated on
+ * a resolvable `subagent_type` so a non-spawn call never opens a frame. Still
+ * parked because the `effect()` sub-region goal it served was dropped (see
+ * research/effect-boundary-design.md, "Why dropped") — the stack is shipped for
+ * when active-agent contract enforcement under nesting is wanted on its own.
+ *
+ * Resolve a spawn 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

@@ -11,7 +11,7 @@
  * 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
+ * (`src/adapters/claude-code/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
@@ -28,9 +28,14 @@ exports.parseAgentTools = parseAgentTools;
 exports.parseAgentToolList = parseAgentToolList;
 exports.parseAgentPurity = parseAgentPurity;
 exports.decidePreToolUse = decidePreToolUse;
+exports.readActiveStack = readActiveStack;
+exports.pushActiveAgent = pushActiveAgent;
+exports.popActiveAgent = popActiveAgent;
 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");
@@ -98,37 +103,146 @@ function decidePreToolUse(allowed, tool) {
     };
 }
 // ---------------------------------------------------------------------------
-// Active-agent tracking (mirrors .vigiles/active-skill.json)
+// Active-agent tracking — a depth-aware STACK (mirrors .vigiles/active-skill.json)
 // ---------------------------------------------------------------------------
+//
+// Claude Code v2.1.172 added nested subagents (a subagent with the spawn tool can
+// dispatch its own, up to depth 5). A single active-agent slot is NOT nesting-safe:
+// when an inner subagent returns, clearing the whole slot drops the OUTER agent's
+// contract while it is still running, so the PreToolUse gate then allows a tool the
+// outer subagent forbids — a CONTRACT ESCAPE. The fix (certified in TLC, see
+// research/prototypes/typed-spec-formal-verification/AgentWindowStack.tla) is a
+// STACK: push on dispatch, pop on SubagentStop (back to the parent), gate on the
+// stack TOP. Counterexample the flat model fails and the stack model passes:
+// Open(writer); Open(writer); Stop; Call(Bash).
 const ACTIVE_PATH = ".vigiles/active-agent.json";
-/** Record the subagent currently dispatched, so PreToolUse enforces its contract. */
-function setActiveAgent(cwd, agentPath) {
+/**
+ * Read the active-agent stack (oldest → newest; the dispatched subagent chain).
+ * Back-compat: a legacy single-slot `{ agent: string }` marker reads as a one-frame
+ * stack; a malformed file or non-string entries → an empty stack (fail-open).
+ */
+function readActiveStack(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if (!(0, node_fs_1.existsSync)(p))
+        return [];
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+        if (Array.isArray(parsed.stack)) {
+            return parsed.stack.filter((x) => typeof x === "string");
+        }
+        // legacy single-slot format
+        if (typeof parsed.agent === "string")
+            return [parsed.agent];
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeActiveStack(cwd, stack) {
     const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if (stack.length === 0) {
+        if ((0, node_fs_1.existsSync)(p))
+            (0, node_fs_1.rmSync)(p);
+        return;
+    }
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
-    (0, node_fs_1.writeFileSync)(p, JSON.stringify({ agent: agentPath }) + "\n");
+    (0, node_fs_1.writeFileSync)(p, JSON.stringify({ stack }) + "\n");
 }
-/** Clear the active-agent marker (the subagent finished). */
+/**
+ * Push a dispatched subagent onto the active stack (a `PreToolUse` spawn). The
+ * PreToolUse gate then enforces this subagent's contract until it returns. Under
+ * nesting each dispatch pushes a frame, so the chain is tracked, not overwritten.
+ */
+function pushActiveAgent(cwd, agentPath) {
+    writeActiveStack(cwd, [...readActiveStack(cwd), agentPath]);
+}
+/**
+ * Pop the top frame — the subagent returned (`SubagentStop`), so control returns
+ * to its PARENT (the next frame down), whose contract the gate enforces again.
+ * This is the nesting-safe close, distinct from {@link clearActiveAgent} (which
+ * drops the whole stack). Popping an empty stack is a no-op.
+ */
+function popActiveAgent(cwd) {
+    const stack = readActiveStack(cwd);
+    stack.pop();
+    writeActiveStack(cwd, stack);
+}
+/**
+ * Push a subagent frame (the manual `agent-start` fallback + the deterministic
+ * spawn open-signal both use this). A single call is equivalent to a one-frame
+ * stack, so the top — what the gate reads — is this agent. Alias of
+ * {@link pushActiveAgent} kept under the historical name.
+ */
+function setActiveAgent(cwd, agentPath) {
+    pushActiveAgent(cwd, agentPath);
+}
+/**
+ * Clear the WHOLE stack (a hard reset / session end). Distinct from
+ * {@link popActiveAgent}, which returns to the parent frame. Idempotent.
+ */
 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. */
+/**
+ * The active agent's compiled `.md` — the STACK TOP — or null when none is active.
+ * The gate reads the top, so a returned nested subagent reveals its parent's
+ * contract again (the contract-escape fix).
+ */
 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;
-    }
+    const stack = readActiveStack(cwd);
+    return stack.length > 0 ? stack[stack.length - 1] : null;
 }
 // ---------------------------------------------------------------------------
 // PreToolUse-hook decision
 // ---------------------------------------------------------------------------
+/**
+ * EXPERIMENTAL — parked (P3), do NOT auto-wire. The subagent-window tracking is
+ * now nesting-safe: a depth-aware STACK (push on dispatch, pop on SubagentStop —
+ * see {@link pushActiveAgent}/{@link popActiveAgent}) closes the contract-escape
+ * the flat single-slot model allowed under Claude Code v2.1.172 depth-5 nesting
+ * (certified in research/prototypes/.../AgentWindowStack.tla). The open signal
+ * recognizes BOTH spawn tool names (`Task` and the nested-spawn `Agent`), gated on
+ * a resolvable `subagent_type` so a non-spawn call never opens a frame. Still
+ * parked because the `effect()` sub-region goal it served was dropped (see
+ * research/effect-boundary-design.md, "Why dropped") — the stack is shipped for
+ * when active-agent contract enforcement under nesting is wanted on its own.
+ *
+ * Resolve a spawn 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/effect-region.js

@@ -8,7 +8,7 @@ exports.hasEffectBoundary = hasEffectBoundary;
  * Effect-boundary position-aware state tracking.
  * Mirrors active-unit tracking (.vigiles/active-agent.json / .vigiles/active-skill.json).
  * The PreToolUse hook reads this file to decide whether the agent is inside an
- * effect boundary (set by `vigiles effect-enter`) or outside it.
+ * effect boundary (set by `vigiles hook-runtime effect-enter`) or outside it.
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");