vigiles 16.1.2 → 16.1.3

package/dist/adapter-conformance.js

@@ -18,6 +18,7 @@ const node_path_1 = require("node:path");
 const compile_js_1 = require("./core/compile.js");
 const spec_js_1 = require("./core/spec.js");
 const plugin_loader_js_1 = require("./plugin-loader.js");
+const vocabulary_consistency_js_1 = require("./core/vocabulary-consistency.js");
 /** Check an adapter against the port contracts; returns the (possibly empty) failure list. */
 function checkAdapterConformance(adapter) {
     const failures = [];
@@ -33,6 +34,22 @@ function checkAdapterConformance(adapter) {
     need(refVerification, "capabilities.referenceVerification must be true (every adapter does pillar 1)");
     // --- Pillar 1 (always required): dialect + layout ---
     need(adapter.dialect.builtinAgentTools.length > 0, "dialect has no builtinAgentTools");
+    // The dialect's several name lists describe ONE vocabulary from different
+    // angles, and nothing used to check they agreed — which is how `Agent` came to
+    // sit in `neverAvailableTools` while its own alias `Task` sat in the built-in
+    // catalog, undetected, for every consumer of the adapter. Cheap, total, and it
+    // runs for every adapter including third-party ones.
+    for (const problem of (0, vocabulary_consistency_js_1.dialectVocabularyProblems)(adapter.dialect))
+        need(false, `dialect self-contradiction: ${problem}`);
+    // When a dialect ships the richer vocabulary AND the flat lists, the flat ones
+    // must be exactly its projections — else the two drift apart again, one level
+    // down.
+    if (adapter.dialect.subagentToolVocabulary !== undefined)
+        for (const problem of (0, vocabulary_consistency_js_1.vocabularyProjectionProblems)(adapter.dialect.subagentToolVocabulary, adapter.dialect.builtinAgentTools, adapter.dialect.neverAvailableTools))
+            need(false, `subagentToolVocabulary: ${problem}`);
+    if (adapter.dialect.hookEventVocabulary !== undefined)
+        for (const problem of (0, vocabulary_consistency_js_1.vocabularyProjectionProblems)(adapter.dialect.hookEventVocabulary, adapter.dialect.hookEvents, []))
+            need(false, `hookEventVocabulary: ${problem}`);
     need(adapter.dialect.instructionTargets.length > 0, "dialect has no instructionTargets");
     need(adapter.layout.instructionFile.length > 0, "layout.instructionFile is empty");
     need(adapter.layout.manifestPath.length > 0, "layout.manifestPath is empty");

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

@@ -11,16 +11,23 @@ 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.
+ *
+ * DERIVED, not authored: it is exactly the vocabulary's declarable terms — the
+ * ones the platform provides outright plus the ones it withholds only under a
+ * condition. Both halves are legitimate to write in a `tools:` line, which is
+ * why `Agent` belongs here and used to sit in `neverAvailableTools` instead.
+ * Because this is a projection rather than a second hand-kept list, the two can
+ * no longer disagree; `vocabularyProjectionProblems` asserts it in the
+ * conformance kit rather than leaving it to care.
  */
-export declare const claudeCodeBuiltinAgentTools: readonly ["Read", "Write", "Edit", "MultiEdit", "Bash", "BashOutput", "KillBash", "Grep", "Glob", "LS", "WebSearch", "WebFetch", "NotebookEdit", "TodoWrite", "Task", "Skill"];
+export declare const claudeCodeBuiltinAgentTools: readonly ["Read", "Grep", "Glob", "Bash", "PowerShell", "Edit", "Write", "NotebookEdit", "WebFetch", "WebSearch", "TodoWrite", "Skill", "ToolSearch", "EnterWorktree", "ExitWorktree", "Monitor", "TaskStop", "SendMessage", "Artifact", "Agent", "Task", "ExitPlanMode", "ListAgents", "LSP", "ShareOnboardingGuide", "CronCreate", "CronDelete", "CronList", "TaskCreate", "TaskGet", "TaskList", "TaskUpdate"];
 /**
- * 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.
+ * The Claude Code side-effecting tools (the complement of read-only within
+ * `builtinAgentTools`). Authored in `vocabulary.ts` beside the catalog it
+ * partitions, because a name added to the catalog without a decision here would
+ * silently be classified read-only.
  */
-export declare const claudeCodeSideEffectingTools: readonly ["Bash", "BashOutput", "KillBash", "Edit", "MultiEdit", "Write", "NotebookEdit", "WebFetch", "WebSearch", "Skill", "Task", "TodoWrite"];
+export declare const claudeCodeSideEffectingTools: readonly ["Bash", "PowerShell", "Edit", "Write", "NotebookEdit", "WebFetch", "WebSearch", "Skill", "TodoWrite", "Monitor", "SendMessage", "Artifact", "EnterWorktree", "ExitWorktree", "TaskStop", "Agent", "Task", "TaskCreate", "TaskUpdate", "CronCreate", "CronDelete", "ShareOnboardingGuide"];
 export declare const claudeCodeDialect: HarnessDialect;
 /** Every Claude Code built-in subagent tool (literal union). */
 export type ClaudeCodeBuiltinTool = (typeof claudeCodeBuiltinAgentTools)[number];
@@ -33,15 +40,14 @@ export type ClaudeCodeSideEffectingTool = (typeof claudeCodeSideEffectingTools)[
 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
+ * side-effecting tools (Write/Edit/NotebookEdit) ∪ `Bash`/`PowerShell` (whose
  * 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`.
+ * `MultiEdit` was listed here until 2026-08-17. It is not a Claude Code tool —
+ * it appears zero times across the vendor's documentation — so it is gone along
+ * with `BashOutput`, `KillBash` and `LS`.
  */
-export type ClaudeCodeBoundedTool = ClaudeCodeReadOnlyTool | "Write" | "Edit" | "MultiEdit" | "NotebookEdit" | "Bash";
+export type ClaudeCodeBoundedTool = ClaudeCodeReadOnlyTool | "Write" | "Edit" | "NotebookEdit" | "Bash" | "PowerShell";
 export type { HarnessDialect } from "../../core/dialect.js";
 //# sourceMappingURL=dialect.d.ts.map

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

@@ -1,84 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeCodeDialect = exports.claudeCodeSideEffectingTools = exports.claudeCodeBuiltinAgentTools = void 0;
+const vocabulary_js_1 = require("./vocabulary.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.
+ *
+ * DERIVED, not authored: it is exactly the vocabulary's declarable terms — the
+ * ones the platform provides outright plus the ones it withholds only under a
+ * condition. Both halves are legitimate to write in a `tools:` line, which is
+ * why `Agent` belongs here and used to sit in `neverAvailableTools` instead.
+ * Because this is a projection rather than a second hand-kept list, the two can
+ * no longer disagree; `vocabularyProjectionProblems` asserts it in the
+ * conformance kit rather than leaving it to care.
  */
 exports.claudeCodeBuiltinAgentTools = [
-    "Read",
-    "Write",
-    "Edit",
-    "MultiEdit",
-    "Bash",
-    "BashOutput",
-    "KillBash",
-    "Grep",
-    "Glob",
-    "LS",
-    "WebSearch",
-    "WebFetch",
-    "NotebookEdit",
-    "TodoWrite",
-    "Task",
-    "Skill",
+    ...vocabulary_js_1.claudeCodeAvailableAgentTools,
+    ...vocabulary_js_1.claudeCodeConditionalAgentToolNames,
 ];
 /**
- * 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.
+ * The Claude Code side-effecting tools (the complement of read-only within
+ * `builtinAgentTools`). Authored in `vocabulary.ts` beside the catalog it
+ * partitions, because a name added to the catalog without a decision here would
+ * silently be classified read-only.
  */
-exports.claudeCodeSideEffectingTools = [
-    "Bash",
-    "BashOutput",
-    "KillBash",
-    "Edit",
-    "MultiEdit",
-    "Write",
-    "NotebookEdit",
-    "WebFetch",
-    "WebSearch",
-    "Skill",
-    "Task",
-    "TodoWrite",
-];
+exports.claudeCodeSideEffectingTools = vocabulary_js_1.claudeCodeSideEffectingAgentTools;
 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: 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: [
-        "Agent",
-        "AskUserQuestion",
-        "EnterPlanMode",
-        "ExitPlanMode",
-        "ScheduleWakeup",
-        "WaitForMcpServers",
-    ],
+    // Tools the platform removes UNCONDITIONALLY, whatever the list says — so a
+    // subagent listing one is a guaranteed-dead reference only a compiler catches.
+    // Derived from the vocabulary's `withheld` terms. `Agent` and `ExitPlanMode`
+    // are deliberately absent: the vendor removes both only under a stated
+    // condition (depth limit / `permissionMode: plan`), so they are `conditional`
+    // and reported as a note. Listing them here is what told delegating subagents
+    // to delete the tool they exist to use.
+    neverAvailableTools: vocabulary_js_1.claudeCodeWithheldAgentTools,
     mcpToolPattern: /^mcp__[a-z0-9_-]+__[a-z0-9_-]+$/i,
     // Claude Code's own built-in MCP server: the IDE integration provides
     // `mcp__ide__getDiagnostics` / `mcp__ide__executeCode` at runtime without any
     // plugin declaring it, so a contract that lists those must NOT be flagged as
     // referencing an undeclared server (the mcp-tool-resolves allowlist).
     knownMcpServers: ["ide"],
-    // The real Claude Code hook events. (Was wrong: PreSession/PostSession don't
-    // exist; SessionStart/SessionEnd/Stop/SubagentStop/UserPromptSubmit/PreCompact
-    // were missing — verified against the events real plugins register.)
-    hookEvents: [
-        "PreToolUse",
-        "PostToolUse",
-        "UserPromptSubmit",
-        "Notification",
-        "Stop",
-        "SubagentStop",
-        "PreCompact",
-        "SessionStart",
-        "SessionEnd",
-    ],
+    // The real Claude Code hook events — all 31 the vendor documents, derived from
+    // `claudeCodeHookEventNames`. This list held 9 until 2026-08-17; `Setup` was
+    // reported as "never fires" and the other 21 absentees drew nothing at all,
+    // because whether an unknown name was accused or ignored came down to its edit
+    // distance from the 9 we had. See `vocabulary.ts` for the capture.
+    hookEvents: vocabulary_js_1.claudeCodeHookEventNames,
     // Events where a block decision is silently ignored ENTIRELY — no veto AND no
     // model feedback (exit 2 there writes stderr only to the user). These are the
     // ONLY events hook-block-ineffective flags as wrong-event. PostToolUse is NOT
@@ -105,10 +76,17 @@ exports.claudeCodeDialect = {
     // disable-model-invocation, argument-hint, …).
     skillFrontmatter: "claude-code",
     // Tools that produce side effects in Claude Code. The complement — the
-    // read-only tools — are: Read, Grep, Glob, LS, ToolSearch (and LSP/Agent
-    // 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
+    // read-only tools — are: Read, Grep, Glob, ToolSearch, LSP, ListAgents,
+    // TaskGet, TaskList, CronList. Bash (and PowerShell) are 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: exports.claudeCodeSideEffectingTools,
+    // The richer catalogs the flat lists above project from — status per term,
+    // with the vendor capture they were read from. An unknown name resolves
+    // against these to an `unrecognised` ADVISORY that names vigiles as the
+    // possibly-stale party, instead of the silence-or-accusation coin flip that
+    // edit distance used to decide.
+    hookEventVocabulary: vocabulary_js_1.claudeCodeHookEventVocabulary,
+    subagentToolVocabulary: vocabulary_js_1.claudeCodeSubagentToolVocabulary,
 };
 //# sourceMappingURL=dialect.js.map

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

@@ -0,0 +1,133 @@
+/**
+ * The Claude Code vocabularies — hook events and subagent tools — re-derived
+ * from the vendor's own documentation on 2026-08-17 against Claude Code 2.1.233
+ * (`claude --version` on the capture box).
+ *
+ * Every entry below came from a STRUCTURAL read of the docs, not a prose grep:
+ * the hook events are the 31 `<h3>` subsections of the `## Hook events` section
+ * of https://code.claude.com/docs/en/hooks (2,589,700 bytes as fetched), in
+ * document order; the tool statuses are the two filter lists in the
+ * "Available tools" section of https://code.claude.com/docs/en/sub-agents
+ * (1,126,213 bytes as fetched). The `condition` strings are the vendor's own
+ * wording, trimmed.
+ *
+ * This file is the ONE authored place for both catalogs. `dialect.ts` builds
+ * `builtinAgentTools` / `neverAvailableTools` / `sideEffectingTools` and the
+ * literal tool unions from the tuples below, so the state that produced the
+ * `Agent`/`Task` inversion — two hand-kept lists disagreeing with each other —
+ * has nowhere left to live.
+ *
+ * WHAT THIS CORRECTS, and how badly it was wrong (measured; the mechanism is
+ * documented in `core/vocabulary.ts`):
+ *
+ *  - HOOK EVENTS: the old catalog held 9 of 31. It was NOT "current except for
+ *    `Setup`" — 22 documented events were missing, and 21 of those went unsaid
+ *    only because they sit more than 2 edit distance from a name we held.
+ *    `Setup` was the one that happened to land within 2 of `Stop`, so it alone
+ *    drew an accusation, and the fix it suggested — rewire a one-shot setup hook
+ *    onto every turn's Stop — would have broken the repo it was aimed at.
+ *  - `Agent` WAS BACKWARDS. The old dialect listed `Agent` as never-available
+ *    and `Task` as a built-in. The vendor renamed it the other way round:
+ *
+ *      > In version 2.1.63, the Task tool was renamed to Agent. Existing
+ *      > `Task(...)` references in settings and agent definitions still work
+ *      > as aliases.
+ *
+ *    and ships `tools: Agent(worker, researcher), Read, Bash` as a worked
+ *    example. vigiles rejected the current name, accepted the deprecated one,
+ *    and told orchestrator subagents to delete the one tool they exist to use.
+ *  - FOUR NAMES WE HELD DO NOT EXIST. `MultiEdit`, `BashOutput`, `KillBash` and
+ *    `LS` appear ZERO times across all six vendor doc pages fetched (hooks,
+ *    sub-agents, tools-reference, settings, iam, tool-use). They are historical.
+ *    They are gone from this catalog, so listing one now draws an
+ *    `unrecognised` advisory instead of silent approval.
+ *  - THE EVIDENCE WAS ALREADY IN THE REPO. `dialect-drift.ts`'s
+ *    `ACKNOWLEDGED_TOOL_INPUT_TYPES` has carried `Agent`, `TaskOutput` and
+ *    `Workflow` — read from the vendor's own `sdk-tools.d.ts` — since 2.1.187,
+ *    under a note asserting they are "NOT subagent-grantable". Nothing ever
+ *    compared that list against this one, so the drift alarm watched the
+ *    platform move while our two catalogs contradicted both it and each other.
+ *
+ * WHY `conditional` IS NOT A DEFECT. The vendor is explicit that a subagent's
+ * tool set is not a property of the name:
+ *
+ *   > Claude Code removes every other built-in tool from a background subagent,
+ *   > whether inherited or listed in the `tools` field, so the same definition
+ *   > can resolve to different tools in the foreground and the background.
+ *
+ * and, of the catalog as a whole:
+ *
+ *   > Your exact tool set depends on your provider, platform, and settings.
+ *
+ * Availability is therefore a function of foreground/background, spawn depth,
+ * `permissionMode`, model, provider and settings — none of which vigiles can
+ * read off a `tools:` line. `conditional` records the condition and reports it
+ * as a note. Evaluating those conditions (two of them are decidable from
+ * frontmatter we already parse — `ExitPlanMode` against the agent's own
+ * `permissionMode`, and background-vs-foreground) is real follow-on work and is
+ * deliberately NOT done here.
+ *
+ * KNOWN GAP, recorded rather than smoothed: `TodoWrite` is named by the vendor
+ * among the built-ins a background subagent keeps, so it is `available` — but
+ * `tools-reference` also says that from 2.1.233 `TodoWrite`, `TaskCreate`,
+ * `TaskGet`, `TaskUpdate` and `TaskList` are withheld on Opus 4.8 / Sonnet 5 /
+ * Fable 5 / Mythos 5 and later unless opted in. That is a MODEL axis on top of
+ * the two filter axes. The four `Task*` tools are `conditional` for the
+ * background reason anyway and their condition says so; `TodoWrite` stays
+ * `available` because the vendor names it in the kept-list verbatim. One
+ * condition string cannot express three independent axes, and adding a field to
+ * hold a case we still could not evaluate would be worse than saying so here.
+ */
+import type { HarnessVocabulary } from "../../core/vocabulary.js";
+/**
+ * The Claude Code hook events — the 31 `###` subsections under `## Hook events`
+ * at https://code.claude.com/docs/en/hooks, in document order.
+ *
+ * `Setup` is the third. It is a real event with its own `Setup input` and
+ * `Setup decision control` subsections; the old catalog's absence of it is what
+ * produced the two-letter grade inversion this file exists to fix.
+ */
+export declare const claudeCodeHookEventNames: readonly ["SessionStart", "Setup", "InstructionsLoaded", "UserPromptSubmit", "UserPromptExpansion", "MessageDisplay", "PreToolUse", "PermissionRequest", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PermissionDenied", "Notification", "SubagentStart", "SubagentStop", "TaskCreated", "TaskCompleted", "Stop", "StopFailure", "TeammateIdle", "ConfigChange", "CwdChanged", "DirectoryAdded", "FileChanged", "WorktreeCreate", "WorktreeRemove", "PreCompact", "PostCompact", "SessionEnd", "Elicitation", "ElicitationResult"];
+/**
+ * The 19 built-ins the vendor names as the set a BACKGROUND subagent keeps —
+ * the default case, and the only tool set vigiles can assume without reading
+ * conditions it cannot see.
+ */
+export declare const claudeCodeAvailableAgentTools: readonly ["Read", "Grep", "Glob", "Bash", "PowerShell", "Edit", "Write", "NotebookEdit", "WebFetch", "WebSearch", "TodoWrite", "Skill", "ToolSearch", "EnterWorktree", "ExitWorktree", "Monitor", "TaskStop", "SendMessage", "Artifact"];
+/**
+ * The 7 unconditional entries of the vendor's first filter — "removes these
+ * tools, even when listed in the `tools` field", with no qualifier attached.
+ * Listing one is a genuine dead reference, and the only tool verdict that
+ * still enters the grade.
+ */
+export declare const claudeCodeWithheldAgentTools: readonly ["AskUserQuestion", "EndConversation", "EnterPlanMode", "ScheduleWakeup", "TaskOutput", "WaitForMcpServers", "Workflow"];
+/**
+ * Tools the platform removes only under a stated condition — the qualified
+ * entries of the first filter, plus the built-ins that survive in the
+ * foreground but not in the background. Declaring one is legitimate, so none
+ * of these is scored; the condition is reported and vigiles stops there.
+ */
+export declare const claudeCodeConditionalAgentToolNames: readonly ["Agent", "Task", "ExitPlanMode", "ListAgents", "LSP", "ShareOnboardingGuide", "CronCreate", "CronDelete", "CronList", "TaskCreate", "TaskGet", "TaskList", "TaskUpdate"];
+/**
+ * The side-effecting subset of everything a subagent may declare (the
+ * complement is read-only). Two rules decided the additions here, both from the
+ * vendor's own tool descriptions rather than from the tool's name:
+ *
+ *  - `Monitor` "writes a small script, runs it in the background" and can open
+ *    a WebSocket — execution plus network, so it is side-effecting despite
+ *    reading like an observer.
+ *  - `LSP`, `ToolSearch`, `ListAgents`, `TaskGet`, `TaskList` and `CronList`
+ *    only report state, so they stay read-only.
+ *
+ * This matters beyond tidiness: `classifyToolEffect` treats "in the built-in
+ * catalog and NOT here" as read-only, so a name added to the catalog without a
+ * decision here would silently be declared harmless — and a spawning tool
+ * misfiled as read-only would let a subagent pass the lethal-trifecta check it
+ * should fail.
+ */
+export declare const claudeCodeSideEffectingAgentTools: readonly ["Bash", "PowerShell", "Edit", "Write", "NotebookEdit", "WebFetch", "WebSearch", "Skill", "TodoWrite", "Monitor", "SendMessage", "Artifact", "EnterWorktree", "ExitWorktree", "TaskStop", "Agent", "Task", "TaskCreate", "TaskUpdate", "CronCreate", "CronDelete", "ShareOnboardingGuide"];
+/** The hook-event vocabulary — every documented event, all currently available. */
+export declare const claudeCodeHookEventVocabulary: HarnessVocabulary;
+/** The subagent-tool vocabulary — available / withheld / conditional. */
+export declare const claudeCodeSubagentToolVocabulary: HarnessVocabulary;
+//# sourceMappingURL=vocabulary.d.ts.map

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

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeSubagentToolVocabulary = exports.claudeCodeHookEventVocabulary = exports.claudeCodeSideEffectingAgentTools = exports.claudeCodeConditionalAgentToolNames = exports.claudeCodeWithheldAgentTools = exports.claudeCodeAvailableAgentTools = exports.claudeCodeHookEventNames = void 0;
+/** The vendor artifact + version both catalogs below were captured from. */
+const CAPTURE = "code.claude.com/docs (claude-code 2.1.233, read 2026-08-17)";
+/**
+ * The Claude Code hook events — the 31 `###` subsections under `## Hook events`
+ * at https://code.claude.com/docs/en/hooks, in document order.
+ *
+ * `Setup` is the third. It is a real event with its own `Setup input` and
+ * `Setup decision control` subsections; the old catalog's absence of it is what
+ * produced the two-letter grade inversion this file exists to fix.
+ */
+exports.claudeCodeHookEventNames = [
+    "SessionStart",
+    "Setup",
+    "InstructionsLoaded",
+    "UserPromptSubmit",
+    "UserPromptExpansion",
+    "MessageDisplay",
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PostToolBatch",
+    "PermissionDenied",
+    "Notification",
+    "SubagentStart",
+    "SubagentStop",
+    "TaskCreated",
+    "TaskCompleted",
+    "Stop",
+    "StopFailure",
+    "TeammateIdle",
+    "ConfigChange",
+    "CwdChanged",
+    "DirectoryAdded",
+    "FileChanged",
+    "WorktreeCreate",
+    "WorktreeRemove",
+    "PreCompact",
+    "PostCompact",
+    "SessionEnd",
+    "Elicitation",
+    "ElicitationResult",
+];
+/**
+ * The 19 built-ins the vendor names as the set a BACKGROUND subagent keeps —
+ * the default case, and the only tool set vigiles can assume without reading
+ * conditions it cannot see.
+ */
+exports.claudeCodeAvailableAgentTools = [
+    "Read",
+    "Grep",
+    "Glob",
+    "Bash",
+    "PowerShell",
+    "Edit",
+    "Write",
+    "NotebookEdit",
+    "WebFetch",
+    "WebSearch",
+    "TodoWrite",
+    "Skill",
+    "ToolSearch",
+    "EnterWorktree",
+    "ExitWorktree",
+    "Monitor",
+    "TaskStop",
+    "SendMessage",
+    "Artifact",
+];
+/**
+ * The 7 unconditional entries of the vendor's first filter — "removes these
+ * tools, even when listed in the `tools` field", with no qualifier attached.
+ * Listing one is a genuine dead reference, and the only tool verdict that
+ * still enters the grade.
+ */
+exports.claudeCodeWithheldAgentTools = [
+    "AskUserQuestion",
+    "EndConversation",
+    "EnterPlanMode",
+    "ScheduleWakeup",
+    "TaskOutput",
+    "WaitForMcpServers",
+    "Workflow",
+];
+/** Vendor conditions quoted once, so the term table below stays readable. */
+const DEPTH_LIMIT = "only when the subagent is at the depth limit; in a fork the tool stays " +
+    "listed but returns an error instead of spawning";
+const BACKGROUND = "from a background subagent (the default) — a foreground subagent or a fork " +
+    "keeps it";
+const BACKGROUND_AND_MODEL = `${BACKGROUND}; also withheld from Opus 4.8 / Sonnet 5 / Fable 5 / Mythos 5 ` +
+    "and later unless CLAUDE_CODE_ENABLE_TODO_TOOLS=1";
+/**
+ * Tools the platform removes only under a stated condition — the qualified
+ * entries of the first filter, plus the built-ins that survive in the
+ * foreground but not in the background. Declaring one is legitimate, so none
+ * of these is scored; the condition is reported and vigiles stops there.
+ */
+exports.claudeCodeConditionalAgentToolNames = [
+    "Agent",
+    // The rename runs the OTHER WAY from what vigiles used to encode: `Task` is
+    // the old name and still works as an alias, `Agent` is the current one.
+    "Task",
+    "ExitPlanMode",
+    "ListAgents",
+    "LSP",
+    "ShareOnboardingGuide",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "TaskCreate",
+    "TaskGet",
+    "TaskList",
+    "TaskUpdate",
+];
+/**
+ * The vendor's qualifier for each conditional tool.
+ *
+ * Typed as a `Record` over the name tuple ON PURPOSE: a conditional tool with no
+ * stated condition cannot be reported as conditional (the condition IS the
+ * report), so adding a name above without a line here is a `tsc` error rather
+ * than a runtime surprise. The equivalent runtime check in
+ * `vocabularyProjectionProblems` stays for adapters that build a vocabulary
+ * dynamically, but for this one the gap is unrepresentable.
+ */
+const CONDITIONS = {
+    Agent: DEPTH_LIMIT,
+    Task: DEPTH_LIMIT,
+    ExitPlanMode: "unless the subagent's permissionMode is plan",
+    ListAgents: "from a background subagent; a foreground subagent inherits it only in " +
+        "sessions where cross-session messaging is enabled",
+    LSP: BACKGROUND,
+    ShareOnboardingGuide: BACKGROUND,
+    CronCreate: BACKGROUND,
+    CronDelete: BACKGROUND,
+    CronList: BACKGROUND,
+    TaskCreate: BACKGROUND_AND_MODEL,
+    TaskGet: BACKGROUND_AND_MODEL,
+    TaskList: BACKGROUND_AND_MODEL,
+    TaskUpdate: BACKGROUND_AND_MODEL,
+};
+/** Still-honoured deprecated spellings, pointing at the current name. */
+const ALIASES = { Task: "Agent" };
+/**
+ * The side-effecting subset of everything a subagent may declare (the
+ * complement is read-only). Two rules decided the additions here, both from the
+ * vendor's own tool descriptions rather than from the tool's name:
+ *
+ *  - `Monitor` "writes a small script, runs it in the background" and can open
+ *    a WebSocket — execution plus network, so it is side-effecting despite
+ *    reading like an observer.
+ *  - `LSP`, `ToolSearch`, `ListAgents`, `TaskGet`, `TaskList` and `CronList`
+ *    only report state, so they stay read-only.
+ *
+ * This matters beyond tidiness: `classifyToolEffect` treats "in the built-in
+ * catalog and NOT here" as read-only, so a name added to the catalog without a
+ * decision here would silently be declared harmless — and a spawning tool
+ * misfiled as read-only would let a subagent pass the lethal-trifecta check it
+ * should fail.
+ */
+exports.claudeCodeSideEffectingAgentTools = [
+    "Bash",
+    "PowerShell",
+    "Edit",
+    "Write",
+    "NotebookEdit",
+    "WebFetch",
+    "WebSearch",
+    "Skill",
+    "TodoWrite",
+    "Monitor",
+    "SendMessage",
+    "Artifact",
+    "EnterWorktree",
+    "ExitWorktree",
+    "TaskStop",
+    "Agent",
+    "Task",
+    "TaskCreate",
+    "TaskUpdate",
+    "CronCreate",
+    "CronDelete",
+    "ShareOnboardingGuide",
+];
+/** The hook-event vocabulary — every documented event, all currently available. */
+exports.claudeCodeHookEventVocabulary = {
+    kind: "claude-code hook event",
+    capturedFrom: `${CAPTURE} § hooks / Hook events`,
+    terms: exports.claudeCodeHookEventNames.map((name) => ({ name, status: "available" })),
+};
+/** The subagent-tool vocabulary — available / withheld / conditional. */
+exports.claudeCodeSubagentToolVocabulary = {
+    kind: "claude-code subagent tool",
+    capturedFrom: `${CAPTURE} § sub-agents / Available tools`,
+    terms: [
+        ...exports.claudeCodeAvailableAgentTools.map((name) => ({ name, status: "available" })),
+        ...exports.claudeCodeWithheldAgentTools.map((name) => ({ name, status: "withheld" })),
+        ...exports.claudeCodeConditionalAgentToolNames.map((name) => ({
+            name,
+            status: "conditional",
+            condition: CONDITIONS[name],
+            ...(ALIASES[name] !== undefined ? { aliasOf: ALIASES[name] } : {}),
+        })),
+    ],
+};
+//# sourceMappingURL=vocabulary.js.map

package/dist/core/compile.js

@@ -827,7 +827,12 @@ function compileSkill(spec, options = {}) {
  * detection lives in the shared `verifyToolContract` detector (one-detector-no-
  * drift: compile + scan + the subagent-tool-contract lint rule call the same code). */
 function validateAgentTools(tools, dialect) {
-    return (0, tool_contract_js_1.verifyToolContract)(tools, dialect).map((issue) => ({
+    // `authoringIssues` drops the `conditional` verdicts: `Agent`, `ExitPlanMode`
+    // and the foreground-only built-ins are REAL tools, legitimate to declare, and
+    // erroring on them is what made `tools: Agent, Read, Bash` — a worked example
+    // in the vendor's own docs — fail to compile. Everything else stays an error,
+    // because authoring your own spec is a closed world.
+    return (0, tool_contract_js_1.authoringIssues)((0, tool_contract_js_1.verifyToolContract)(tools, dialect)).map((issue) => ({
         type: "unknown-tool",
         message: issue.message,
     }));

package/dist/core/dialect.d.ts

@@ -22,6 +22,7 @@
  * Which SKILL.md frontmatter keys a harness understands — see
  * `HarnessDialect.skillFrontmatter`.
  */
+import type { HarnessVocabulary } from "./vocabulary.js";
 export type SkillFrontmatterProfile = "claude-code" | "minimal";
 export interface HarnessDialect {
     /** Stable identifier, e.g. "claude-code". */
@@ -83,5 +84,31 @@ export interface HarnessDialect {
      * Optional (additive, non-breaking) — absent ⇒ no tool is known-side-effecting.
      */
     readonly sideEffectingTools?: readonly string[];
+    /**
+     * The hook-event catalog as a {@link HarnessVocabulary} — a status and a
+     * recorded vendor capture per term, rather than bare membership in
+     * `hookEvents`. When present it is what `verifyHookEvents` classifies against,
+     * so a name the catalog doesn't hold produces an `unrecognised` ADVISORY
+     * (naming vigiles's capture as the possibly-stale party) instead of the old
+     * behaviour, where an unknown name drew an accusation or silence depending on
+     * its edit distance to the list.
+     *
+     * Optional (additive, non-breaking). Absent ⇒ one is synthesised from
+     * `hookEvents` via `vocabularyFromLists`, so a legacy adapter keeps working
+     * and its unknowns become advisories rather than silence.
+     */
+    readonly hookEventVocabulary?: HarnessVocabulary;
+    /**
+     * The subagent-tool catalog as a {@link HarnessVocabulary}. Same contract as
+     * `hookEventVocabulary`; absent ⇒ synthesised from `builtinAgentTools`
+     * (available) + `neverAvailableTools` (withheld).
+     *
+     * The third status is why this exists: the vendor removes `Agent` only at the
+     * spawn depth limit and `ExitPlanMode` only outside plan mode, and removes
+     * most built-ins from a background subagent but not a foreground one — so
+     * "available to a subagent" is not a property of the name, and a two-way
+     * split had to encode one of those conditions as an unconditional fact.
+     */
+    readonly subagentToolVocabulary?: HarnessVocabulary;
 }
 //# sourceMappingURL=dialect.d.ts.map