vigiles 5.2.0 → 7.0.0

package/dist/core/hook-program.js

@@ -0,0 +1,468 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineReact = exports.nothing = exports.notice = exports.run = exports.defineInject = exports.inject = exports.tools = exports.HookCompileError = exports.tool = exports.ask = exports.deny = exports.allow = void 0;
+exports.gateAction = gateAction;
+exports.commandView = commandView;
+exports.defineHook = defineHook;
+exports.decideProgram = decideProgram;
+exports.decisionExitCode = decisionExitCode;
+exports.checkHookImports = checkHookImports;
+exports.dispatchKind = dispatchKind;
+exports.hookMode = hookMode;
+exports.hookNeeds = hookNeeds;
+exports.hookRouting = hookRouting;
+exports.compileHookProgram = compileHookProgram;
+exports.stampHook = stampHook;
+exports.verifyHookStamp = verifyHookStamp;
+exports.pathView = pathView;
+exports.defineFileGate = defineFileGate;
+exports.decideFileGate = decideFileGate;
+exports.definePromptGate = definePromptGate;
+exports.decidePromptGate = decidePromptGate;
+exports.defineStopGate = defineStopGate;
+exports.decideStopGate = decideStopGate;
+exports.runInject = runInject;
+exports.responseView = responseView;
+exports.runReact = runReact;
+exports.runHookProgram = runHookProgram;
+/**
+ * Compiled hooks — a hook as a CONSTRAINED TYPED PROGRAM, not arbitrary shell.
+ *
+ * The pure core behind the public `vigiles/hook` surface (re-exported in
+ * `src/hook.ts`; compiled by `vigiles compile`, run by `vigiles hook-runtime
+ * run-program`). A hook today is opaque shell (`bash guard.sh`) —
+ * un-analyzable (Rice), and the author hand-writes the fragile parts (exit code,
+ * JSON field, a `grep` matcher) that the verified #1 pains come from. Invert it:
+ * the author writes a PURE typed function `(event) => Decision` against a CLOSED
+ * API; vigiles compiles it. The constraint ELIMINATES whole bug classes by
+ * construction and buys testability / safety / matching / portability:
+ *
+ *  - TESTABILITY: `decide` is a pure fn — unit-test in-process, no subprocess, no
+ *    exit-code/JSON plumbing. The false-confidence bug class (exit 1≠2, wrong field)
+ *    is UNREPRESENTABLE — the author never writes the protocol; `compile` emits it.
+ *  - SAFETY: capability = API surface. `checkHookImports` rejects any import outside
+ *    `vigiles/hook` at compile (so the hook can't reach `child_process`/`net`), and
+ *    `stampHook`/`verifyHookStamp` make the compiled artifact TAMPER-EVIDENT (the
+ *    integrity.ts pattern) — a hand-edit that smuggles a capability breaks the stamp.
+ *  - MATCHING: `command.runs("git push", { force })` is AST-backed (leafCommands),
+ *    so it catches `cd x && git push -f` that the native `Bash(git:*)` glob (#30519)
+ *    and a hand-written `grep` both miss.
+ *  - PORTABILITY: one program → each harness's protocol (CC exit-2 here; Codex /
+ *    OpenCode via the HookProtocol port later — OpenCode hooks ARE in-process TS).
+ *
+ * Pure core, harness-neutral. HONEST SCOPE (kept in every doc): compile/verify fix
+ * the hook's AUTHORING + LOGIC, not DELIVERY — CC's subagent-bypass (#34692) means
+ * a PreToolUse hook does not fire for a subagent's tool calls, so a gate is a strong
+ * default, never an unbypassable wall. Limits (buy-in, node-startup latency) +
+ * full record in research/hook-pain-points.md.
+ */
+const bash_effects_js_1 = require("./bash-effects.js");
+const hash_js_1 = require("./hash.js");
+const toml_1 = require("@iarna/toml");
+const hook_events_js_1 = require("./hook-events.js");
+const hook_providers_js_1 = require("./hook-providers.js");
+const allow = () => ({ kind: "allow" });
+exports.allow = allow;
+const deny = (reason) => ({ kind: "deny", reason });
+exports.deny = deny;
+const ask = (reason) => ({ kind: "ask", reason });
+exports.ask = ask;
+/**
+ * Map a gate's {@link Decision} + {@link HookMode} to what the runtime actually does.
+ * `enforce`: deny→block (exit 2), ask→ask, allow→allow. `observe`: a deny/ask is
+ * recorded as a no-op `observe` (would-have-blocked) and allowed; allow stays allow.
+ * Pure, so a test asserts "in observe mode this deny does NOT block" with no process.
+ */
+function gateAction(decision, mode = "enforce") {
+    if (mode === "observe")
+        return decision.kind === "allow"
+            ? { kind: "allow" }
+            : { kind: "observe", would: decision.kind, reason: decision.reason };
+    switch (decision.kind) {
+        case "deny":
+            return { kind: "block", reason: decision.reason };
+        case "ask":
+            return { kind: "ask", reason: decision.reason };
+        case "allow":
+            return { kind: "allow" };
+        default:
+            return (0, hash_js_1.assertNever)(decision);
+    }
+}
+const FORCE_FLAG = /^-(?:-force$|[a-z]*f[a-z]*$)/;
+const hasForce = (argv) => argv.some((a) => FORCE_FLAG.test(a));
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+/** Does `argv` run `tokens` in order (head exact, rest present after it)? */
+function runsSeq(argv, tokens) {
+    if (argv[0] !== tokens[0])
+        return false;
+    let i = 1;
+    for (let j = 1; j < argv.length && i < tokens.length; j++) {
+        if (argv[j] === tokens[i])
+            i++;
+    }
+    return i === tokens.length;
+}
+/** Does a single token name a path at/under `prefix` (boundary-aware)? */
+function tokenUnder(token, prefix) {
+    const t = token.replace(/^\.\//, "");
+    return t === prefix || t.startsWith(prefix + "/") || t.endsWith("/" + prefix);
+}
+/** A leaf whose head is a shell reading stdin (no script-file argument). */
+function isBareShellLeaf(argv) {
+    return (SHELLS.has(argv[0] ?? "") && argv.slice(1).every((a) => a.startsWith("-")));
+}
+function commandView(raw) {
+    const leaves = (0, bash_effects_js_1.leafCommands)(raw);
+    return {
+        raw,
+        runs(program, opts) {
+            const tokens = program.split(/\s+/).filter(Boolean);
+            return leaves.some((argv) => runsSeq(argv, tokens) && (opts?.force ? hasForce(argv) : true));
+        },
+        isSideEffecting: () => (0, bash_effects_js_1.classifyBashCommand)(raw) === "side-effecting",
+        touches: (prefixes) => leaves.some((argv) => argv.slice(1).some((tok) => prefixes.some((p) => tokenUnder(tok, p)))),
+        pipesToShell: () => leaves.some(isBareShellLeaf),
+    };
+}
+const tool = (name) => ({ tool: name });
+exports.tool = tool;
+function defineHook(p) {
+    return p;
+}
+// ---------------------------------------------------------------------------
+// Run the program against a raw PreToolUse event (the runtime half)
+// ---------------------------------------------------------------------------
+/** Build the typed event from a raw PreToolUse event, then decide. */
+function decideProgram(program, rawEvent, ctx = {}) {
+    if (rawEvent.tool_name !== program.match.tool)
+        return (0, exports.allow)();
+    const command = typeof rawEvent.tool_input?.command === "string"
+        ? rawEvent.tool_input.command
+        : "";
+    return program.decide({
+        event: program.on,
+        tool: "Bash",
+        command: commandView(command),
+        ctx: ctx,
+    });
+}
+/** Map a Decision to the CC hook exit code — the protocol the author never writes. */
+function decisionExitCode(d) {
+    return d.kind === "deny" ? 2 : 0;
+}
+// ---------------------------------------------------------------------------
+// Compile-time safety: capability = the API surface
+// ---------------------------------------------------------------------------
+const ALLOWED_IMPORT = "vigiles/hook";
+/**
+ * Reject any import/require outside `vigiles/hook` + textual escape hatches
+ * (eval / Function / dynamic import). The hook's capabilities are then EXACTLY the
+ * sanctioned API — it cannot reach `child_process`, `fs`, or the network. Returns
+ * the offending specifiers/constructs (empty = clean). (Probe: a regex scan; a
+ * production impl walks the TS AST.)
+ */
+function checkHookImports(source) {
+    const out = [];
+    const importRe = /\b(?:import|require)\s*(?:\(|[^'"]*from)?\s*['"]([^'"]+)['"]/g;
+    for (const m of source.matchAll(importRe)) {
+        if (m[1] !== ALLOWED_IMPORT)
+            out.push(m[1]);
+    }
+    if (/\beval\s*\(|\bnew\s+Function\b|\bimport\s*\(/.test(source)) {
+        out.push("dynamic-eval");
+    }
+    return out;
+}
+class HookCompileError extends Error {
+}
+exports.HookCompileError = HookCompileError;
+function dispatchKind(hook) {
+    if ("role" in hook)
+        return hook.role === "gate" ? "file-gate" : hook.role;
+    return "bash-gate";
+}
+/** A gate's {@link HookMode} (`enforce` default); non-gate roles report `enforce` too. */
+function hookMode(hook) {
+    return "mode" in hook && hook.mode ? hook.mode : "enforce";
+}
+/** The context providers a hook declared via `needs` ([] if none / not a gate). */
+function hookNeeds(hook) {
+    return "needs" in hook && Array.isArray(hook.needs)
+        ? hook.needs
+        : [];
+}
+/** Where a hook fires + its tool matcher (undefined for tool-less events). */
+function hookRouting(hook) {
+    if ("role" in hook) {
+        // inject / prompt-gate / stop-gate fire on a whole EVENT — no tool matcher.
+        if (hook.role === "inject" ||
+            hook.role === "prompt-gate" ||
+            hook.role === "stop-gate")
+            return { on: hook.on };
+        return { on: hook.on, matcher: hook.match.tools.join("|") };
+    }
+    return { on: hook.on, matcher: hook.match.tool };
+}
+/** Apply a harness's matcher style to the neutral `A|B` matcher join. */
+function styleMatcher(matcher, protocol) {
+    if (matcher === undefined)
+        return undefined;
+    return protocol?.matcherStyle === "regex" ? `^(${matcher})$` : matcher;
+}
+/**
+ * Render the settings block a user pastes into their hooks config. JSON for
+ * Claude Code (the nested `{event:[{matcher,hooks:[{type,command}]}]}` shape);
+ * TOML `[[hooks.<event>]]` with a flat `command` for Codex.
+ */
+function renderSettingsBlock(on, matcher, gateCommand, format) {
+    if (format === "toml") {
+        const entry = matcher === undefined
+            ? { command: gateCommand }
+            : { matcher, command: gateCommand };
+        return (0, toml_1.stringify)({ hooks: { [on]: [entry] } }).trim();
+    }
+    const entry = matcher === undefined
+        ? { hooks: [{ type: "command", command: gateCommand }] }
+        : { matcher, hooks: [{ type: "command", command: gateCommand }] };
+    return JSON.stringify({ hooks: { [on]: [entry] } }, null, 2);
+}
+/**
+ * Compile a hook program from its source. Runs the capability check FIRST (an
+ * out-of-API import does NOT compile), validates the event against the target
+ * harness (a typo won't compile), then stamps the source so the shipped artifact
+ * is tamper-evident. The hook supplies the routing (event + matcher), which
+ * differs per role — a tool gate matches its tool, a react matches its tools, an
+ * inject (SessionStart) has no tool matcher at all.
+ *
+ * Harness-agnostic by injection: with no `opts` it emits the Claude Code block
+ * (back-compatible); pass `{ dialect, hookProtocol, settingsFormat }` from a
+ * resolved adapter and it emits that harness's block (e.g. Codex TOML + regex
+ * matcher). Core never imports an adapter — only the port interfaces.
+ */
+function compileHookProgram(source, hook, opts = {}) {
+    const violations = checkHookImports(source);
+    if (violations.length > 0) {
+        throw new HookCompileError(`hook program uses capabilities outside \`${ALLOWED_IMPORT}\`: ${violations.join(", ")} — only the sanctioned API is allowed (capability = API surface).`);
+    }
+    const { on, matcher: rawMatcher } = hookRouting(hook);
+    // A hook registered under an event the harness never fires is dead — reject it.
+    if (opts.dialect) {
+        const issues = (0, hook_events_js_1.verifyHookEvents)([on], opts.dialect);
+        if (issues.length > 0) {
+            throw new HookCompileError(issues[0].message);
+        }
+    }
+    // A `needs` entry that isn't a built-in provider never resolves — reject it
+    // (the typo-won't-compile guarantee, for JS authors the type can't reach).
+    const needs = hookNeeds(hook);
+    const unknownNeeds = (0, hook_providers_js_1.unknownProviders)(needs, opts.registeredProviders);
+    if (unknownNeeds.length > 0) {
+        throw new HookCompileError(`unknown context provider(s): ${unknownNeeds.join(", ")} — built-ins are ${Object.keys(hook_providers_js_1.BUILTIN_PROVIDERS).join(", ")}; a provider() ref must resolve to a .vigiles/providers/ file, or use provide()/dangerously() inline (see research/hook-context-providers.md).`);
+    }
+    // An inline provide() whose command isn't provably read-only must be acknowledged.
+    const unsafe = (0, hook_providers_js_1.unsafeInlineProviders)(needs);
+    if (unsafe.length > 0) {
+        throw new HookCompileError(`inline provider(s) not provably read-only: ${unsafe
+            .map((u) => `${u.name} ("${u.run}")`)
+            .join(", ")} — use dangerously(name, cmd) to acknowledge a side-effecting/undecidable command, or keep provide() only for a read-only one.`);
+    }
+    const gateCommand = opts.gateCommand ?? "npx vigiles hook-runtime run-program";
+    const matcher = styleMatcher(rawMatcher, opts.hookProtocol);
+    const entry = matcher === undefined
+        ? { hooks: [{ type: "command", command: gateCommand }] }
+        : {
+            matcher,
+            hooks: [{ type: "command", command: gateCommand }],
+        };
+    return {
+        hooks: { [on]: [entry] },
+        settingsBlock: renderSettingsBlock(on, matcher, gateCommand, opts.settingsFormat ?? "json"),
+        stamp: stampHook(source),
+    };
+}
+/** Stamp a hook's source (the integrity.ts pattern, applied to a hook artifact). */
+function stampHook(source) {
+    return (0, hash_js_1.sha256short)(source);
+}
+/** Verify a shipped hook artifact matches its stamp (tamper → false). */
+function verifyHookStamp(source, stamp) {
+    return stampHook(source) === stamp;
+}
+function pathView(raw) {
+    const norm = raw.replace(/^\.\//, "");
+    return {
+        raw,
+        under: (prefixes) => prefixes.some((p) => {
+            const base = p.replace(/\/?\*+$/, "").replace(/\/$/, "");
+            return base === "" || norm === base || norm.startsWith(base + "/");
+        }),
+    };
+}
+const tools = (...names) => ({
+    tools: names,
+});
+exports.tools = tools;
+function defineFileGate(p) {
+    return { role: "gate", ...p };
+}
+/** Run a file-tool gate against a raw PreToolUse event (reads `file_path`). */
+function decideFileGate(hook, raw, ctx = {}) {
+    const t = raw.tool_name ?? "";
+    if (!hook.match.tools.includes(t))
+        return (0, exports.allow)();
+    const fp = typeof raw.tool_input?.file_path === "string"
+        ? raw.tool_input.file_path
+        : "";
+    return hook.decide({
+        event: hook.on,
+        tool: t,
+        path: pathView(fp),
+        ctx: ctx,
+    });
+}
+function definePromptGate(p) {
+    return { role: "prompt-gate", ...p };
+}
+/** Run a prompt gate against a raw UserPromptSubmit event (reads `prompt`). */
+function decidePromptGate(hook, raw, ctx = {}) {
+    const prompt = typeof raw.prompt === "string" ? raw.prompt : "";
+    return hook.decide({
+        event: hook.on,
+        prompt,
+        ctx: ctx,
+    });
+}
+function defineStopGate(p) {
+    return { role: "stop-gate", ...p };
+}
+/** Run a Stop gate against a raw Stop/SubagentStop event (reads `stop_hook_active`). */
+function decideStopGate(hook, raw, ctx = {}) {
+    return hook.decide({
+        event: hook.on,
+        stopHookActive: raw.stop_hook_active === true,
+        ctx: ctx,
+    });
+}
+const inject = (context) => ({
+    kind: "inject",
+    context,
+});
+exports.inject = inject;
+const defineInject = (p) => ({
+    role: "inject",
+    ...p,
+});
+exports.defineInject = defineInject;
+/**
+ * Run an inject hook → the CC JSON the author never hand-writes. The compiler
+ * targets `additionalContext` (the RIGHT field for this event), so the
+ * wrong-JSON-field pain can't occur.
+ */
+function runInject(hook, raw) {
+    const out = hook.produce({ event: hook.on, source: raw.source ?? "startup" });
+    return {
+        hookSpecificOutput: {
+            hookEventName: hook.on,
+            additionalContext: out.context,
+        },
+    };
+}
+/** Normalize an arbitrary tool_response payload to text (object → JSON). */
+function responseText(raw) {
+    if (typeof raw === "string")
+        return raw;
+    if (raw == null)
+        return "";
+    return JSON.stringify(raw);
+}
+function responseView(raw) {
+    const text = responseText(raw);
+    const flagged = typeof raw === "object" &&
+        raw !== null &&
+        (Boolean(raw.error) ||
+            raw.is_error === true);
+    return {
+        raw: text,
+        isError: () => flagged || /^\s*error[:\s]/i.test(text),
+        contains: (needle) => text.includes(needle),
+    };
+}
+/** Run a command in reaction — its effect is classified AT CONSTRUCTION (audit/diff-able). */
+const run = (command) => ({
+    kind: "run",
+    command,
+    effect: (0, bash_effects_js_1.classifyBashCommand)(command),
+});
+exports.run = run;
+/** Surface a non-blocking note (no execution). */
+const notice = (message) => ({
+    kind: "notice",
+    message,
+});
+exports.notice = notice;
+/** Do nothing. */
+const nothing = () => ({ kind: "none" });
+exports.nothing = nothing;
+const defineReact = (p) => ({
+    role: "react",
+    ...p,
+});
+exports.defineReact = defineReact;
+/** Run a react hook against a raw PostToolUse event → the (classified) Reaction. */
+function runReact(hook, raw) {
+    const t = raw.tool_name ?? "";
+    if (!hook.match.tools.includes(t))
+        return (0, exports.nothing)();
+    const fp = typeof raw.tool_input?.file_path === "string"
+        ? raw.tool_input.file_path
+        : "";
+    return hook.react({
+        event: hook.on,
+        tool: t,
+        path: pathView(fp),
+        response: responseView(raw.tool_response),
+    });
+}
+/**
+ * Evaluate a compiled hook against a raw event, in-process, dispatching by role:
+ * a gate → its `Decision`, an inject → the injected context text, a react → its
+ * (effect-classified) `Reaction`. Pure — no subprocess, no model. The ergonomic
+ * base for testing a compiled hook (see `assertHookDenies` / `assertHookAllows`).
+ */
+function runHookProgram(hook, event, ctx = {}) {
+    const kind = dispatchKind(hook);
+    switch (kind) {
+        case "bash-gate":
+            return {
+                kind: "decision",
+                decision: decideProgram(hook, event, ctx),
+            };
+        case "file-gate":
+            return {
+                kind: "decision",
+                decision: decideFileGate(hook, event, ctx),
+            };
+        case "prompt-gate":
+            return {
+                kind: "decision",
+                decision: decidePromptGate(hook, event, ctx),
+            };
+        case "stop-gate":
+            return {
+                kind: "decision",
+                decision: decideStopGate(hook, event, ctx),
+            };
+        case "inject":
+            return {
+                kind: "injection",
+                context: runInject(hook, event).hookSpecificOutput
+                    .additionalContext,
+            };
+        case "react":
+            return { kind: "reaction", reaction: runReact(hook, event) };
+        default:
+            return (0, hash_js_1.assertNever)(kind);
+    }
+}
+//# sourceMappingURL=hook-program.js.map

package/dist/core/hook-protocol.d.ts

@@ -24,5 +24,12 @@ export interface HookProtocol {
      * Code passes the event on stdin only; Codex adds session_id/cwd/PLUGIN_ROOT/…).
      */
     readonly eventEnvVars: readonly string[];
+    /**
+     * How a tool matcher is written in the emitted hooks block — `"exact"` (Claude
+     * Code: the tool name / `A|B` alternation) or `"regex"` (Codex: an anchored
+     * regex `^(A|B)$`). Optional (additive, non-breaking) — absent ⇒ `"exact"`.
+     * Used by `compileHookProgram` when rendering the settings block.
+     */
+    readonly matcherStyle?: "exact" | "regex";
 }
 //# sourceMappingURL=hook-protocol.d.ts.map

package/dist/core/hook-providers.d.ts

@@ -0,0 +1,138 @@
+/** The closed set of built-in facts a gate may declare via `needs`, with value types. */
+export interface ProviderResults {
+    /** The current git branch, or "" outside a git repo / on an unborn HEAD. */
+    readonly "git.branch": string;
+    /** True iff the working tree has uncommitted changes (false if not a repo). */
+    readonly "git.isDirty": boolean;
+    /** The repo's top-level directory, or "" outside a git repo. */
+    readonly "git.root": string;
+    /** The directory the hook runs in. */
+    readonly cwd: string;
+    /** The OS platform (`process.platform`: "darwin" | "linux" | "win32" | …). */
+    readonly "os.platform": NodeJS.Platform;
+    /** True iff running on a CI server (detected via the `ci-info` library). */
+    readonly "env.isCI": boolean;
+}
+/** A declarable built-in provider name. */
+export type ProviderName = keyof ProviderResults;
+/**
+ * An INLINE one-off provider: a command declared right in `needs` (no registered
+ * file), run by the trusted runtime, its stdout becoming `e.ctx[name]` (a string).
+ * `dangerous` marks the loud escape — a command not provably read-only. Built via
+ * {@link provide} (read-only) or {@link dangerously} (acknowledged).
+ */
+export interface InlineProvider<Name extends string = string> {
+    readonly kind: "inline";
+    readonly name: Name;
+    readonly run: string;
+    readonly dangerous: boolean;
+}
+/** A `needs` entry — a built-in name, an inline `provide`/`dangerously`, or a `provider()` ref. */
+export type NeedSpec = ProviderName | InlineProvider | RegisteredRef;
+/**
+ * Declare an INLINE read-only fact: `provide("k8sCtx", "kubectl config current-context")`.
+ * The command MUST be provably read-only (compile rejects it otherwise — use
+ * {@link dangerously} to acknowledge a side-effecting/undecidable one). Its stdout
+ * is `e.ctx[name]`.
+ */
+export declare const provide: <const Name extends string>(name: Name, run: string) => InlineProvider<Name>;
+/**
+ * Declare an INLINE fact whose command ISN'T provably read-only — the loud,
+ * greppable escape hatch (the `dangerouslySetInnerHTML` / `unsafe` / `http.send`
+ * convention; sibling of `purity:'dangerously-unrestricted'`). A security review
+ * searches for this one word.
+ */
+export declare const dangerously: <const Name extends string>(name: Name, run: string) => InlineProvider<Name>;
+/**
+ * A REGISTERED provider — a reusable, named fact authored once in
+ * `.vigiles/providers/<name>.{mjs,ts}` (default-exported via {@link defineProvider})
+ * and referenced from many hooks by {@link provider} name. The reusable sibling of
+ * the one-off inline {@link provide}; same read-only-by-default rule.
+ */
+export interface RegisteredProvider<Name extends string = string> {
+    readonly kind: "provider-def";
+    readonly name: Name;
+    readonly run: string;
+    readonly dangerous: boolean;
+}
+/** Author a registered provider: `export default defineProvider({ name, run })`. */
+export declare const defineProvider: <const Name extends string>(p: {
+    readonly name: Name;
+    readonly run: string;
+    /** Acknowledge a command that isn't provably read-only (the loud escape). */
+    readonly dangerous?: boolean;
+}) => RegisteredProvider<Name>;
+/** A reference to a registered provider, used in a hook's `needs`: `provider("myFact")`. */
+export interface RegisteredRef<Name extends string = string> {
+    readonly kind: "provider-ref";
+    readonly name: Name;
+}
+/** Reference a registered provider (from `.vigiles/providers/`) by name in `needs`. */
+export declare const provider: <const Name extends string>(name: Name) => RegisteredRef<Name>;
+/** name → its registered provider; the runtime resolves a `provider(name)` ref against this. */
+export type ProviderRegistry = Record<string, RegisteredProvider>;
+type NeedName<E extends NeedSpec> = E extends ProviderName ? E : E extends InlineProvider<infer Nm> ? Nm : E extends RegisteredRef<infer Rn> ? Rn : never;
+type NeedValue<E extends NeedSpec> = E extends ProviderName ? ProviderResults[E] : string;
+/**
+ * The typed `e.ctx` for a hook that declared `needs: N` — ONLY the declared facts
+ * are present (built-in name → its typed value, inline → string), so reading an
+ * undeclared one is a `tsc` error (the typed-purity trick). With `N = readonly []`
+ * the ctx is empty. The default `readonly ProviderName[]` is the erased runtime
+ * shape (built-ins only — an inline `string` name would force an index signature
+ * that clashes with `git.isDirty: boolean`; concrete authored inline names are
+ * literals, so they never clash).
+ */
+export type HookCtx<N extends readonly NeedSpec[] = readonly ProviderName[]> = {
+    readonly [E in N[number] as NeedName<E>]: NeedValue<E>;
+};
+/** The read-only capabilities a provider may use to gather its fact. */
+export interface ProviderIO {
+    /** Run a read-only command, return stdout (throws on non-zero exit). */
+    readonly exec: (command: string) => string;
+    /** The hook's working directory. */
+    readonly cwd: string;
+    /** The OS platform (`process.platform`). */
+    readonly platform: NodeJS.Platform;
+    /** Whether the process is on a CI server (the CLI injects `ci-info`'s verdict). */
+    readonly isCI: boolean;
+}
+interface ProviderDef<K extends ProviderName> {
+    /**
+     * The read-only command the provider runs (for audit + the read-only
+     * soundness test). Absent for an ambient fact gathered without a subprocess.
+     */
+    readonly run?: string;
+    /** Produce the fact; TOTAL — returns a sensible default on failure, never throws. */
+    readonly gather: (io: ProviderIO) => ProviderResults[K];
+}
+/** The closed built-in registry. Each `run` is provably read-only (see the test). */
+export declare const BUILTIN_PROVIDERS: {
+    readonly [K in ProviderName]: ProviderDef<K>;
+};
+/**
+ * `needs` entries that don't resolve: a built-in NAME that isn't a built-in (a
+ * typo), or a `provider()` ref whose name isn't in `registeredNames` (a dangling
+ * ref). Inline `provide`/`dangerously` are always self-defined, so never flagged.
+ */
+export declare function unknownProviders(needs: readonly NeedSpec[], registeredNames?: readonly string[]): string[];
+/**
+ * Inline `provide()` entries whose command ISN'T provably read-only — these must
+ * switch to `dangerously()` (the acknowledged escape) or compile is rejected. A
+ * `dangerously()` entry is never flagged (it already acknowledged the risk).
+ */
+export declare function unsafeInlineProviders(needs: readonly NeedSpec[]): InlineProvider[];
+/**
+ * Is a REGISTERED provider's command unsafe (not read-only and not acknowledged
+ * `dangerous`)? Reused when compiling a `.vigiles/providers/` file.
+ */
+export declare function unsafeProvider(def: RegisteredProvider): boolean;
+/**
+ * Gather the DECLARED facts into a context object (the trusted-host step). Only
+ * the names in `needs` are gathered, each at most once; a built-in, inline, or
+ * registered provider that can't resolve yields its default ("" / false), never
+ * throws. Pure over the injected `io` (CLI passes a real execSync; tests a fake)
+ * and the `registry` (the loaded `.vigiles/providers/`, for `provider()` refs).
+ */
+export declare function gatherContext(needs: readonly NeedSpec[], io: ProviderIO, registry?: ProviderRegistry): Record<string, string | boolean>;
+export {};
+//# sourceMappingURL=hook-providers.d.ts.map