vigiles 6.0.0 → 8.0.0

package/dist/core/orphans.js

@@ -30,7 +30,7 @@ const DEFAULT_IGNORE = [
 ];
 /**
  * A doc carrying this marker opts out of orphan detection — the inline escape
- * hatch, mirroring `vigiles-disable require-spec` and `vigiles:ignore-test`.
+ * hatch, mirroring `vigiles-disable require-instructions-spec` and `vigiles:ignore-test`.
  * Use it for an intentionally-unreferenced doc (a changelog, a top-level index)
  * that nothing else links to but is not rot.
  */

package/dist/core/spec.d.ts

@@ -135,7 +135,7 @@ export declare function guidance(text: string): GuidanceRule;
  * Declare a reactive guard: runs a command when watched files change.
  *
  *   guard({ watch: "*.spec.ts", run: "npx vigiles compile" }, "Recompile on spec change")
- *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate-types" }, "Regen types")
+ *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate types" }, "Regen types")
  */
 export declare function guard(options: {
     watch: string | readonly string[];
@@ -237,6 +237,9 @@ export declare function glob(pattern: string): GlobRef;
  * the region the unit is treated as read-only (the `"pure"` effective floor),
  * inside it the declared purity floor applies. The position-aware companion to
  * the per-call `purity` floor. See `research/effect-boundary-design.md`.
+ *
+ * @internal Experimental (parked P3) — NOT part of the frozen public surface;
+ * may change or be removed without a major bump pre-1.0.
  */
 export interface EffectRegion {
     readonly _ref: "effect";
@@ -269,6 +272,9 @@ export declare function instructions(strings: TemplateStringsArray, ...values: I
  * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
  * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
  * surface — it does not block on it.
+ *
+ * @internal Experimental (parked P3) — NOT part of the frozen public surface;
+ * may change or be removed without a major bump pre-1.0.
  */
 export declare function effect(strings: TemplateStringsArray, ...values: InstructionFragment[]): EffectRegion;
 /**
@@ -732,6 +738,9 @@ export declare function railway(spec: Omit<Railway, "_specType">): Railway;
  * Declared via `needs(...)` and threaded into the typed agent so `pipe` can
  * cross-reference it. Independent of `result()` (the output) — an agent both
  * `needs` an input shape and produces an `ok`/`err` output shape.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export type NeedsContract<N extends Shape> = N;
 /**
@@ -740,12 +749,18 @@ export type NeedsContract<N extends Shape> = N;
  * step with no upstream requirement — valid as the FIRST step of a pipeline.
  *
  *   needs({ plan: "string", files: "string[]" })
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function needs<const N extends Shape>(shape: N): NeedsContract<N>;
 /**
  * A typed pipeline step: a `TypedAgentSpec` paired with the input `needs` it
  * reads from the prior step's `ok`. `step()` builds one; `pipe` checks that the
  * prior step's `ok` shape supplies this step's `needs`.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape> {
     readonly _step: "typed-delegate";
@@ -758,6 +773,9 @@ export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Sha
  * second is the `needs(...)` input contract.
  *
  *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function pipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape>(a: TypedAgentSpec<Ok, Err>, needsContract?: Needs): PipeStep<Needs, Ok, Err>;
 /**
@@ -766,6 +784,9 @@ export declare function pipeStep<Needs extends Shape, Ok extends Shape, Err exte
  * descriptive error object naming the offending field (`__missing` /
  * `__mismatch`), which surfaces at the mismatched call. Shallow (a per-field
  * mapped type, not a recursion) to avoid TS2589.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export type Supplies<Producer extends Shape, Consumer extends Shape> = {
     [K in keyof Consumer]: K extends keyof Producer ? Producer[K] extends Consumer[K] ? true : {
@@ -788,12 +809,17 @@ export type Supplies<Producer extends Shape, Consumer extends Shape> = {
  * assigning `true` to it is a `tsc` error at edit time. Shallow (one wrap over
  * the per-field `Supplies` mapped type, no recursion); the generator emits one
  * assertion per consecutive step pair (O(N)), keeping clear of TS2589.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export type Handoff<Producer extends Shape, Consumer extends Shape> = Supplies<Producer, Consumer> extends true ? true : {
     readonly __handoff_error: Supplies<Producer, Consumer>;
 };
 /** A typed pipeline value — carries the LAST step's `ok` and the UNION of every
- *  step's `err` (any step can short-circuit to the error track). */
+ *  step's `err` (any step can short-circuit to the error track).
+ *  @internal Experimental typed-composition surface — NOT part of the frozen
+ *  public API (pre-1.0); may change without a major bump. */
 export interface Pipeline<Ok extends Shape, Err extends Shape> {
     readonly _specType: "pipeline";
     /** Ordered agent names — the resolved compose order. */
@@ -809,6 +835,9 @@ export interface Pipeline<Ok extends Shape, Err extends Shape> {
  * Begin a typed pipeline from its first step. The first step has no upstream, so
  * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
  * carrying that step's `ok`/`err` forward.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function start<Ok extends Shape, Err extends Shape>(first: PipeStep<Record<string, never>, Ok, Err> | TypedAgentSpec<Ok, Err>): Pipeline<Ok, Err>;
 /**
@@ -821,6 +850,9 @@ export declare function start<Ok extends Shape, Err extends Shape>(first: PipeSt
  * Named `andThen` (Wlaschin's railway `bind`/`andThen`), NOT `then`: a module
  * exporting a function called `then` becomes a thenable, so `await import()` of
  * any barrel re-exporting it would invoke it — a footgun the rename avoids.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function andThen<PriorOk extends Shape, PriorErr extends Shape, Needs extends Shape, Ok extends Shape, Err extends Shape>(prior: Pipeline<PriorOk, PriorErr>, next: Supplies<PriorOk, Needs> extends true ? PipeStep<Needs, Ok, Err> : {
     readonly __HANDOFF_ERROR: Supplies<PriorOk, Needs>;
@@ -841,6 +873,9 @@ export declare function andThen<PriorOk extends Shape, PriorErr extends Shape, N
  *     pipeStep(implementer, needs({ plan: "string", files: "string[]" })),
  *     pipeStep(reviewer, needs({ diff: "string" })),
  *   ) // ← won't compile if a handoff doesn't line up
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function pipe<A extends Shape, AE extends Shape>(a: TypedAgentSpec<A, AE>): Pipeline<A, AE>;
 export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
@@ -866,6 +901,9 @@ export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape
  * object naming the dangling target + the railway it came from — so assigning
  * `true` to it is a `tsc` error at edit time. Shallow (one conditional, no
  * recursion); the generator emits one assertion per edge (O(N)).
+ *
+ * @internal Experimental whole-harness-codegen surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export type KnownAgentName<Target extends string, Names extends string, From extends string = string> = [Target] extends [Names] ? true : {
     readonly __dangling_delegate: Target;

package/dist/core/spec.js

@@ -73,7 +73,7 @@ function guidance(text) {
  * Declare a reactive guard: runs a command when watched files change.
  *
  *   guard({ watch: "*.spec.ts", run: "npx vigiles compile" }, "Recompile on spec change")
- *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate-types" }, "Regen types")
+ *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate types" }, "Regen types")
  */
 function guard(options, description) {
     return {
@@ -166,6 +166,9 @@ function instructions(strings, ...values) {
  * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
  * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
  * surface — it does not block on it.
+ *
+ * @internal Experimental (parked P3) — NOT part of the frozen public surface;
+ * may change or be removed without a major bump pre-1.0.
  */
 function effect(strings, ...values) {
     const body = [];
@@ -304,6 +307,9 @@ function railway(spec) {
  * step with no upstream requirement — valid as the FIRST step of a pipeline.
  *
  *   needs({ plan: "string", files: "string[]" })
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 function needs(shape) {
     return shape;
@@ -314,6 +320,9 @@ function needs(shape) {
  * second is the `needs(...)` input contract.
  *
  *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 function pipeStep(a, needsContract = {}) {
     return { _step: "typed-delegate", agent: a, needs: needsContract };
@@ -322,6 +331,9 @@ function pipeStep(a, needsContract = {}) {
  * Begin a typed pipeline from its first step. The first step has no upstream, so
  * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
  * carrying that step's `ok`/`err` forward.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 function start(first) {
     const step = "_step" in first ? first : pipeStep(first, {});
@@ -347,6 +359,9 @@ function start(first) {
  * Named `andThen` (Wlaschin's railway `bind`/`andThen`), NOT `then`: a module
  * exporting a function called `then` becomes a thenable, so `await import()` of
  * any barrel re-exporting it would invoke it — a footgun the rename avoids.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 function andThen(prior, next) {
     const real = next;

package/dist/core/types.d.ts

@@ -82,12 +82,23 @@ export interface TestCoverageConfig {
     exclude?: readonly string[];
 }
 export interface RulesConfig {
-    /** Require .spec.ts for CLAUDE.md / AGENTS.md. Default: "warn". */
-    "require-spec"?: RuleSeverity;
     /**
-     * @deprecated Skills are legitimately hand-written; use `untested-skill`
-     * ("every skill ships with a test/eval") instead. Default: false (off). The
-     * check still runs if you set this explicitly.
+     * Require a `.spec.ts` behind each instruction file (CLAUDE.md / AGENTS.md) —
+     * the file must be compiled from a typed spec, not hand-written. NARROW: only a
+     * `.spec.ts` sibling (or an explicit `<!-- vigiles-disable
+     * require-instructions-spec -->` marker) satisfies it; inline
+     * `<!-- vigiles:enforce -->` comments do NOT (the rule name says "spec"). Default:
+     * "warn". `vigiles init` auto-adopts every instruction file into a spec, so this
+     * is GREEN by construction after setup — a safety net for a NEW hand-added file,
+     * not a nag. The workflow-tier opt-in (gated under `--strict`).
+     */
+    "require-instructions-spec"?: RuleSeverity;
+    /**
+     * Require a `.spec.ts` behind each SKILL.md — the consistent
+     * `require-<surface>-spec` parallel to `require-instructions-spec`. Default:
+     * false (OFF): skills are legitimately hand-written, and the coverage that
+     * matters ("every skill ships with a test/eval") is the `untested-skill` rule.
+     * Set it explicitly if your team wants every skill spec-managed.
      */
     "require-skill-spec"?: RuleSeverity;
     /** Detect hand-edits to compiled markdown via SHA-256 hash. Default: "warn". */
@@ -161,6 +172,18 @@ export interface RulesConfig {
      * "warn"; "error" gates CI. Same detector as `scan` (hooks status "missing").
      */
     "hook-script-exists"?: RuleSeverity;
+    /**
+     * A single repo-level RECOMMENDATION (one finding regardless of hook count):
+     * when a plugin/repo ships hand-written hook commands that aren't compiled
+     * `vigiles/hook` artifacts, nudge toward compiled hooks — they make whole hook
+     * bug classes (exit-1-not-2, wrong decision field, matcher bypass) UNREPRESENTABLE
+     * at authoring time, and `guardrail-check` proves an existing one blocks. A
+     * discovery nudge, not a defect: the hand-written shell lane stays first-class,
+     * so it's opt-out and fires ONCE (never per-hook). The message links
+     * `docs/compiled-hooks.md`. Default "warn"; set "off" to silence or "error" to
+     * enforce. Same detector as `scan` (manualHookCount).
+     */
+    "prefer-compiled-hooks"?: RuleSeverity;
     /**
      * Cross-reference a subagent's `disallowedTools:` block-list against the
      * catalog — the deny-side mirror of `subagent-tool-contract`. A close typo there
@@ -221,6 +244,15 @@ export interface VigilesConfig {
     }>;
     /** Orphan-docs check configuration. Include/exclude globs, tsconfig-style. */
     orphans?: OrphansConfig;
+    /**
+     * Glob patterns of instruction/skill files to EXCLUDE from `lint` discovery
+     * (tsconfig-style, relative to the repo root). Use it for vendored or
+     * benchmark fixtures the repo's own lint shouldn't police — e.g.
+     * `["bench/**"]` so a third-party `CLAUDE.md` injected verbatim as a benchmark
+     * arm isn't held to `require-instructions-spec`. `node_modules`/`dist` are always
+     * excluded.
+     */
+    exclude?: readonly string[];
     /**
      * The harness(es) this repo targets — selects the compile dialect / skill
      * frontmatter profile / instruction-file shape, instead of sniffing the cwd.

package/dist/core/validate.js

@@ -11,8 +11,6 @@ const node_fs_1 = require("node:fs");
 const glob_1 = require("glob");
 const node_path_1 = require("node:path");
 const cosmiconfig_1 = require("cosmiconfig");
-const inline_js_1 = require("./inline.js");
-const frontmatter_js_1 = require("./frontmatter.js");
 // ---------------------------------------------------------------------------
 // Constants & regex
 // ---------------------------------------------------------------------------
@@ -31,13 +29,13 @@ const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 // The default instruction file to validate when no config names one.
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
 const DEFAULT_RULES = {
-    "require-spec": "warn",
-    // DEPRECATED — default OFF. Skills are legitimately hand-written (Level 0/1),
-    // so requiring a .spec.ts per SKILL.md was the wrong constraint and only added
-    // noise (it also nagged about vendored/fixture/bench skills). Use the
-    // `untested-*` rules instead — "every skill/agent/hook ships with a test or
-    // eval" is the coverage that matters. The implementation is kept: setting
-    // `require-skill-spec` explicitly still works for anyone who wants it.
+    "require-instructions-spec": "warn",
+    // Default OFF — the consistent `require-<surface>-spec` parallel. Skills are
+    // legitimately hand-written, so requiring a .spec.ts per SKILL.md is the wrong
+    // default (it would nag about vendored/fixture/bench skills); the coverage that
+    // matters is the `untested-*` rules ("every skill/agent/hook ships with a test
+    // or eval"). Set `require-skill-spec` explicitly if your team wants every skill
+    // spec-managed.
     "require-skill-spec": false,
     integrity: "warn",
     coverage: false,
@@ -60,6 +58,10 @@ const DEFAULT_RULES = {
     "mcp-tool-resolves": "warn",
     // A hook script referenced but missing never runs — on by default at warn.
     "hook-script-exists": "warn",
+    // Discovery nudge toward compiled hooks (one finding) — default OFF: it's a
+    // recommendation, not a defect (the hand-written shell lane stays first-class),
+    // so it shouldn't fire unasked. Set "warn"/"error" to opt in.
+    "prefer-compiled-hooks": false,
     // High-precision (close-typo only) deny-list mirror of subagent-tool-contract.
     "disallowed-tools-contract": "warn",
     // Deterministic NCD precision proxy (near-identical skill descriptions) — warn.
@@ -176,26 +178,25 @@ function validate(content, { ruleMarkers, rules: rulesConfig, filePath, dialect
     const missingCount = parsedRules.filter((r) => r.enforcement === "missing").length;
     const errors = [];
     const warnings = [];
-    const disableComment = /<!--\s*vigiles-disable\s+require-spec\s*-->/;
+    const disableComment = /<!--\s*vigiles-disable\s+require-instructions-spec\s*-->/;
     if (filePath) {
         const basename = (0, node_path_1.basename)(filePath);
         const recognized = dialect?.instructionTargets ?? INSTRUCTION_FILES;
         const isInstruction = recognized.includes(basename);
         const isSkill = basename === "SKILL.md";
-        // --- require-spec (CLAUDE.md / AGENTS.md) ---
-        const specSeverity = activeRules["require-spec"];
+        // --- require-instructions-spec (CLAUDE.md / AGENTS.md) ---
+        // NARROW: only a `.spec.ts` sibling satisfies it. The rule name says "spec",
+        // so inline `<!-- vigiles:enforce -->` / `vigiles:` frontmatter do NOT count
+        // (a user on inline mode keeps this rule off — it's a workflow-tier opt-in).
+        // `vigiles init` auto-adopts every instruction file into a spec, so this is
+        // green by construction after setup.
+        const specSeverity = activeRules["require-instructions-spec"];
         if (specSeverity && isInstruction && !disableComment.test(content)) {
             const specPath = filePath + ".spec.ts";
-            // Inline mode counts as a spec — any parseable
-            // `<!-- vigiles:enforce ... -->` comment means the file is
-            // verified on `vigiles lint` even without a .spec.ts sibling.
-            // Delegate to the real parser so a malformed marker can't
-            // satisfy require-spec with a rule that lint can't verify.
-            const hasInline = (0, inline_js_1.hasInlineRules)(content) || (0, frontmatter_js_1.hasFrontmatterRules)(content);
-            if (!(0, node_fs_1.existsSync)(specPath) && !hasInline) {
+            if (!(0, node_fs_1.existsSync)(specPath)) {
                 const msg = {
-                    rule: "require-spec",
-                    message: `No spec file found for "${filePath}". Expected "${specPath}". Run \`npx vigiles init --target=${filePath}\` to create one, add inline \`<!-- vigiles:enforce ... -->\` comments or a \`vigiles:\` frontmatter block, or disable with <!-- vigiles-disable require-spec -->.`,
+                    rule: "require-instructions-spec",
+                    message: `No spec file found for "${filePath}". Expected "${specPath}". Run \`npx vigiles init --target=${filePath}\` to adopt it into a spec, or disable with <!-- vigiles-disable require-instructions-spec -->.`,
                     line: 1,
                 };
                 if (specSeverity === "error") {
@@ -206,9 +207,8 @@ function validate(content, { ruleMarkers, rules: rulesConfig, filePath, dialect
                 }
             }
         }
-        // --- require-skill-spec (SKILL.md) — DEPRECATED but still honored when a
-        // user sets it explicitly, so reading the deprecated key here is intentional.
-        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        // --- require-skill-spec (SKILL.md) — the consistent require-<surface>-spec
+        // parallel, off by default; honored when a user sets it explicitly.
         const skillSeverity = activeRules["require-skill-spec"];
         if (skillSeverity && isSkill && !disableComment.test(content)) {
             const specPath = filePath + ".spec.ts";
@@ -302,7 +302,7 @@ function validatePaths(paths, { followSymlinks = false, ruleMarkers, rules: rule
     let allValid = true;
     // Maps a real (symlink-resolved) path → the first path validated for it, so a
     // symlinked/synced CLAUDE.md⇄AGENTS.md mirror is validated ONCE on the real
-    // file instead of double-firing require-spec on the mirror's name (sync-tool-
+    // file instead of double-firing require-instructions-spec on the mirror's name (sync-tool-
     // compatibility.md req 7). Recorded only on a successful validation, so a
     // symlink seen first (and skipped) never shadows its real target.
     const seenReal = new Map();
@@ -338,7 +338,7 @@ function validatePaths(paths, { followSymlinks = false, ruleMarkers, rules: rule
                 allValid = false;
             continue;
         }
-        // Attribute require-spec/integrity to the REAL file when this path is a
+        // Attribute require-instructions-spec/integrity to the REAL file when this path is a
         // symlink, so a symlinked AGENTS.md resolves to CLAUDE.md's spec rather than
         // a nonexistent AGENTS.md.spec.ts. Non-symlinks keep the original path
         // verbatim (behaviour-preserving).

package/dist/dialect-drift.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The Claude Code version `ACKNOWLEDGED_TOOL_INPUT_TYPES` + the dialect were last
+ * validated against. SINGLE SOURCE OF TRUTH for the pin: CI installs
+ * `@anthropic-ai/claude-code@<this>` (grepped from this line) in every job that
+ * drives the real binary, so the dialect-drift alarm fires only on a DELIBERATE
+ * bump — not on every unpinned CC release landing on an unrelated PR — and the
+ * real-`claude` harness/eval tests stay reproducible. Bump this together with
+ * `ACKNOWLEDGED_TOOL_INPUT_TYPES` (the gated test cross-checks them).
+ */
+export declare const VALIDATED_CC_VERSION = "2.1.187";
+/**
+ * The `<X>Input` interface names we've ACKNOWLEDGED from `sdk-tools.d.ts` (Claude
+ * Code 2.1.187). The drift test fails when the installed set differs — a loud nudge
+ * to re-check `claudeCodeDialect` (and update this set) when CC adds/removes a tool.
+ * NOT a redistribution of their file: a list of bare identifiers (facts), authored here.
+ *
+ * 2.1.187 added the agent-PLATFORM surface (cron/scheduling/worktrees/web-app):
+ * Artifact, Cron{Create,Delete,List}, Enter/ExitWorktree, EnterPlanMode, Monitor,
+ * Projects, PushNotification, REPL, ReadMcpResourceDir, RemoteTrigger,
+ * ScheduleWakeup, ShowOnboardingRolePicker, Task{Create,Get,List,Update}, Workflow;
+ * and removed Config. These are HOST/platform tools, NOT subagent-grantable, so
+ * `claudeCodeDialect.builtinAgentTools` (the `tools:` frontmatter catalog) is
+ * intentionally unchanged — they're acknowledged here as facts, nothing more.
+ */
+export declare const ACKNOWLEDGED_TOOL_INPUT_TYPES: readonly string[];
+/** Parse `export interface <X>Input {` names from sdk-tools.d.ts → sorted [<X>]. Pure. */
+export declare function parseToolInputTypes(dts: string): string[];
+/**
+ * Locate a READABLE JavaScript bundle inside the installed CC package, or null.
+ * Older CC shipped `cli.js` — a readable JS bundle whose hook-event names appear as
+ * string literals, greppable by `eventsMissingFromBundle`. CC ≥ ~2.1.18x switched to
+ * a NATIVE-BINARY distribution (`bin/claude.exe` copied from a platform
+ * `optionalDependencies` package) with NO readable JS bundle, so there is nothing to
+ * text-scan. Returns the bundle path when present, else null — callers then SKIP the
+ * event-drift check loudly rather than crash on a missing `cli.js`.
+ */
+export declare function findClaudeCodeBundle(pkg: string): string | null;
+/** Which of `events` do NOT appear as a whole-word literal in the bundle. Pure. */
+export declare function eventsMissingFromBundle(bundle: string, events: readonly string[]): string[];
+/**
+ * Locate the user's installed `@anthropic-ai/claude-code` package dir, or null.
+ * Tries the global npm root, then the `claude` binary's real path. Read-only —
+ * we only read files the user already installed under their own CC license.
+ */
+export declare function findClaudeCodePackage(): string | null;
+/** A runtime drift report: how the INSTALLED CC's tool surface compares to ours. */
+export interface DialectDriftReport {
+    readonly installedVersion: string;
+    readonly validatedVersion: string;
+    /** Tool-input types present in the install but not in ACKNOWLEDGED (CC added). */
+    readonly newToolTypes: string[];
+    /** Acknowledged types absent from the install (CC removed/renamed). */
+    readonly removedToolTypes: string[];
+}
+/**
+ * Best-effort, read-local drift check for `scan` (and other runtime callers). Reads
+ * only the small `sdk-tools.d.ts` (fast — no `cli.js` bundle scan; events are the
+ * CI test's job). Returns null when CC isn't installed or anything is unreadable —
+ * NEVER throws, so it can't break the command. ToS-clean: reads the user's own
+ * install, ships nothing.
+ */
+export declare function checkDialectDrift(): DialectDriftReport | null;
+/** A one-line freshness warning if the dialect drifted from the install, else null. */
+export declare function formatDialectDrift(r: DialectDriftReport | null): string | null;
+//# sourceMappingURL=dialect-drift.d.ts.map

package/dist/dialect-drift.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACKNOWLEDGED_TOOL_INPUT_TYPES = exports.VALIDATED_CC_VERSION = void 0;
+exports.parseToolInputTypes = parseToolInputTypes;
+exports.findClaudeCodeBundle = findClaudeCodeBundle;
+exports.eventsMissingFromBundle = eventsMissingFromBundle;
+exports.findClaudeCodePackage = findClaudeCodePackage;
+exports.checkDialectDrift = checkDialectDrift;
+exports.formatDialectDrift = formatDialectDrift;
+/**
+ * Dialect freshness / drift detection against the INSTALLED Claude Code.
+ *
+ * Claude Code is a black box (only `settings.json` has an official schema), so
+ * `claudeCodeDialect` is hand-maintained — see the licensing decision in
+ * research/code-adapter-architecture.md. But the installed `@anthropic-ai/claude-code`
+ * package ships a semi-machine source: `sdk-tools.d.ts` (the tool-input type set). We
+ * READ THE USER'S LOCAL INSTALL (ToS-clean — no copying, no redistribution; same
+ * posture as driving the user's own `claude` CLI) to ALARM when CC's surface drifts
+ * from our catalog. We never ship or vendor their types — only diff against them at
+ * test/runtime.
+ *
+ * Why not `import type` from the SDK? `@anthropic-ai/claude-code` and
+ * `@anthropic-ai/claude-agent-sdk` DO ship a clean `ToolInputSchemas` union (on a
+ * types-only `./sdk-tools` subpath), but both are "© Anthropic PBC. All rights
+ * reserved." — proprietary. vigiles is MIT and multi-harness, so taking a hard dep
+ * and re-exporting their types into our published `.d.ts` would (a) bake a
+ * proprietary package into an MIT dep tree, (b) couple the harness-agnostic core to
+ * a Claude-Code-only package, and (c) not even give us `builtinAgentTools` (the SDK
+ * union is input-SCHEMA names like `FileReadInput`/`CronCreateInput` — a superset in
+ * a different vocabulary than the subagent `tools:` catalog). Reading the local file
+ * + a hand-authored list of bare identifiers (facts) is the deliberate ToS-clean
+ * design; this drift alarm is what keeps the hand-list honest.
+ *
+ * NOTE (CC ≥ ~2.1.18x): CC switched to a NATIVE-BINARY distribution — the npm
+ * package ships `bin/claude.exe` (from a platform `optionalDependencies` package),
+ * NOT a readable `cli.js` JS bundle. So the old "grep hook-event string literals out
+ * of cli.js" check has no bundle to read and degrades to a LOUD SKIP (see
+ * `findClaudeCodeBundle`); `sdk-tools.d.ts` is still shipped, so the tool-type drift
+ * alarm keeps working.
+ *
+ * Pure parsers (testable with fixtures) + a local-install locator. TWO consumers:
+ * the gated CI test in `dialect-drift.test.ts` (fails loud on tool/event drift), and
+ * `vigiles scan` at runtime via `checkDialectDrift`/`formatDialectDrift` (a best-effort,
+ * read-local freshness WARN when the installed CC's tool surface drifts from ours).
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+/**
+ * The Claude Code version `ACKNOWLEDGED_TOOL_INPUT_TYPES` + the dialect were last
+ * validated against. SINGLE SOURCE OF TRUTH for the pin: CI installs
+ * `@anthropic-ai/claude-code@<this>` (grepped from this line) in every job that
+ * drives the real binary, so the dialect-drift alarm fires only on a DELIBERATE
+ * bump — not on every unpinned CC release landing on an unrelated PR — and the
+ * real-`claude` harness/eval tests stay reproducible. Bump this together with
+ * `ACKNOWLEDGED_TOOL_INPUT_TYPES` (the gated test cross-checks them).
+ */
+exports.VALIDATED_CC_VERSION = "2.1.187";
+/**
+ * The `<X>Input` interface names we've ACKNOWLEDGED from `sdk-tools.d.ts` (Claude
+ * Code 2.1.187). The drift test fails when the installed set differs — a loud nudge
+ * to re-check `claudeCodeDialect` (and update this set) when CC adds/removes a tool.
+ * NOT a redistribution of their file: a list of bare identifiers (facts), authored here.
+ *
+ * 2.1.187 added the agent-PLATFORM surface (cron/scheduling/worktrees/web-app):
+ * Artifact, Cron{Create,Delete,List}, Enter/ExitWorktree, EnterPlanMode, Monitor,
+ * Projects, PushNotification, REPL, ReadMcpResourceDir, RemoteTrigger,
+ * ScheduleWakeup, ShowOnboardingRolePicker, Task{Create,Get,List,Update}, Workflow;
+ * and removed Config. These are HOST/platform tools, NOT subagent-grantable, so
+ * `claudeCodeDialect.builtinAgentTools` (the `tools:` frontmatter catalog) is
+ * intentionally unchanged — they're acknowledged here as facts, nothing more.
+ */
+exports.ACKNOWLEDGED_TOOL_INPUT_TYPES = [
+    "Agent",
+    "Artifact",
+    "AskUserQuestion",
+    "Bash",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "EnterPlanMode",
+    "EnterWorktree",
+    "ExitPlanMode",
+    "ExitWorktree",
+    "FileEdit",
+    "FileRead",
+    "FileWrite",
+    "Glob",
+    "Grep",
+    "ListMcpResources",
+    "Mcp",
+    "Monitor",
+    "NotebookEdit",
+    "Projects",
+    "PushNotification",
+    "REPL",
+    "ReadMcpResource",
+    "ReadMcpResourceDir",
+    "RemoteTrigger",
+    "ScheduleWakeup",
+    "ShowOnboardingRolePicker",
+    "TaskCreate",
+    "TaskGet",
+    "TaskList",
+    "TaskOutput",
+    "TaskStop",
+    "TaskUpdate",
+    "TodoWrite",
+    "WebFetch",
+    "WebSearch",
+    "Workflow",
+];
+/** Parse `export interface <X>Input {` names from sdk-tools.d.ts → sorted [<X>]. Pure. */
+function parseToolInputTypes(dts) {
+    const out = new Set();
+    for (const m of dts.matchAll(/export\s+interface\s+(\w+)Input\b/g))
+        out.add(m[1]);
+    return [...out].sort();
+}
+/**
+ * Locate a READABLE JavaScript bundle inside the installed CC package, or null.
+ * Older CC shipped `cli.js` — a readable JS bundle whose hook-event names appear as
+ * string literals, greppable by `eventsMissingFromBundle`. CC ≥ ~2.1.18x switched to
+ * a NATIVE-BINARY distribution (`bin/claude.exe` copied from a platform
+ * `optionalDependencies` package) with NO readable JS bundle, so there is nothing to
+ * text-scan. Returns the bundle path when present, else null — callers then SKIP the
+ * event-drift check loudly rather than crash on a missing `cli.js`.
+ */
+function findClaudeCodeBundle(pkg) {
+    const cli = (0, node_path_1.join)(pkg, "cli.js");
+    return (0, node_fs_1.existsSync)(cli) ? cli : null;
+}
+/** Which of `events` do NOT appear as a whole-word literal in the bundle. Pure. */
+function eventsMissingFromBundle(bundle, events) {
+    return events.filter((e) => !new RegExp(`\\b${e}\\b`).test(bundle));
+}
+/**
+ * Locate the user's installed `@anthropic-ai/claude-code` package dir, or null.
+ * Tries the global npm root, then the `claude` binary's real path. Read-only —
+ * we only read files the user already installed under their own CC license.
+ */
+function findClaudeCodePackage() {
+    const tryDir = (dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, "sdk-tools.d.ts")) ? dir : null;
+    const candidates = [
+        () => {
+            const root = (0, node_child_process_1.execSync)("npm root -g", { encoding: "utf-8" }).trim();
+            return tryDir((0, node_path_1.join)(root, "@anthropic-ai", "claude-code"));
+        },
+        () => {
+            const bin = (0, node_child_process_1.execSync)('readlink -f "$(command -v claude)"', {
+                encoding: "utf-8",
+            }).trim();
+            const marker = "/@anthropic-ai/claude-code/";
+            const i = bin.indexOf(marker);
+            return i >= 0 ? tryDir(bin.slice(0, i + marker.length - 1)) : null;
+        },
+    ];
+    for (const probe of candidates) {
+        try {
+            const hit = probe();
+            if (hit)
+                return hit;
+        }
+        catch {
+            /* probe unavailable (no npm / no claude) — try the next */
+        }
+    }
+    return null;
+}
+/**
+ * Best-effort, read-local drift check for `scan` (and other runtime callers). Reads
+ * only the small `sdk-tools.d.ts` (fast — no `cli.js` bundle scan; events are the
+ * CI test's job). Returns null when CC isn't installed or anything is unreadable —
+ * NEVER throws, so it can't break the command. ToS-clean: reads the user's own
+ * install, ships nothing.
+ */
+function checkDialectDrift() {
+    const pkg = findClaudeCodePackage();
+    if (!pkg)
+        return null;
+    try {
+        const installed = new Set(parseToolInputTypes((0, node_fs_1.readFileSync)((0, node_path_1.join)(pkg, "sdk-tools.d.ts"), "utf-8")));
+        const ack = new Set(exports.ACKNOWLEDGED_TOOL_INPUT_TYPES);
+        let installedVersion = "unknown";
+        try {
+            installedVersion =
+                JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(pkg, "package.json"), "utf-8")).version ?? "unknown";
+        }
+        catch {
+            /* version optional */
+        }
+        return {
+            installedVersion,
+            validatedVersion: exports.VALIDATED_CC_VERSION,
+            newToolTypes: [...installed].filter((t) => !ack.has(t)).sort(),
+            removedToolTypes: [...ack].filter((t) => !installed.has(t)).sort(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** A one-line freshness warning if the dialect drifted from the install, else null. */
+function formatDialectDrift(r) {
+    if (!r || (r.newToolTypes.length === 0 && r.removedToolTypes.length === 0))
+        return null;
+    const parts = [];
+    if (r.newToolTypes.length > 0)
+        parts.push(`CC added tool type(s): ${r.newToolTypes.join(", ")}`);
+    if (r.removedToolTypes.length > 0)
+        parts.push(`removed: ${r.removedToolTypes.join(", ")}`);
+    return (`⚠ dialect freshness: vigiles's tool catalog was validated against ` +
+        `claude-code ${r.validatedVersion}, you have ${r.installedVersion} — ` +
+        `${parts.join("; ")}. Tool/contract checks may be stale; a vigiles update may be needed.`);
+}
+//# sourceMappingURL=dialect-drift.js.map