vigiles 5.2.0 → 7.0.0

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

@@ -0,0 +1,459 @@
+/**
+ * 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.
+ */
+import { type BashEffect } from "./bash-effects.js";
+import { type SHA256Hash } from "./hash.js";
+import type { HarnessDialect } from "./dialect.js";
+import type { HookProtocol } from "./hook-protocol.js";
+import { type ProviderName, type NeedSpec, type HookCtx } from "./hook-providers.js";
+export type Decision = {
+    readonly kind: "allow";
+} | {
+    readonly kind: "deny";
+    readonly reason: string;
+} | {
+    readonly kind: "ask";
+    readonly reason: string;
+};
+export declare const allow: () => Decision;
+export declare const deny: (reason: string) => Decision;
+export declare const ask: (reason: string) => Decision;
+/**
+ * Whether a gate BLOCKS on a `deny` (`enforce`, the default) or only RECORDS what
+ * it WOULD block while letting everything through (`observe` — the shadow / rollout
+ * mode: trust a new gate by watching it first, then promote to `enforce`). This is
+ * the WAF "shadow mode" pattern, the one essential mode (block vs don't-block-but-
+ * record) — not a vocabulary of on-fail actions. HARNESS-NEUTRAL by construction:
+ * observe just exits 0 and writes a local record, so it behaves identically on
+ * Claude Code and Codex (no harness-specific field names involved).
+ */
+export type HookMode = "enforce" | "observe";
+/** A gate's runtime ACTION after applying its {@link HookMode} to its {@link Decision}. Pure. */
+export type GateAction = {
+    readonly kind: "block";
+    readonly reason: string;
+} | {
+    readonly kind: "ask";
+    readonly reason: string;
+} | {
+    readonly kind: "observe";
+    readonly would: "deny" | "ask";
+    readonly reason: string;
+} | {
+    readonly kind: "allow";
+};
+/**
+ * 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.
+ */
+export declare function gateAction(decision: Decision, mode?: HookMode): GateAction;
+/** An AST-backed view of a Bash command — the author never writes a regex. */
+export interface CommandView {
+    readonly raw: string;
+    /** True iff a leaf command runs `program` (e.g. "git push"), optionally with --force/-f. */
+    runs(program: string, opts?: {
+        readonly force?: boolean;
+    }): boolean;
+    /** True iff the command is provably side-effecting (bash-effects classifier). */
+    isSideEffecting(): boolean;
+    /**
+     * True iff a leaf command references a path under one of the prefixes (e.g.
+     * `~/.ssh`, `.env`) — the secret-read / sensitive-path matcher. Sees the path
+     * however the command is wrapped (`cd x && cat ~/.ssh/id_rsa`).
+     */
+    touches(prefixes: readonly string[]): boolean;
+    /**
+     * True iff the command pipes into a BARE shell interpreter (`curl … | sh`,
+     * `… | bash -s`) — the remote-code-execution shape. High-signal: a shell leaf
+     * WITH a script-file argument (`sh deploy.sh`) is NOT flagged; only a shell
+     * reading from stdin is, which only happens downstream of a pipe.
+     */
+    pipesToShell(): boolean;
+}
+export declare function commandView(raw: string): CommandView;
+/**
+ * The typed event a Bash gate decides over. Generic over the declared context
+ * `needs` (`N`) so `e.ctx` exposes ONLY the facts the hook declared — reading an
+ * undeclared one is a `tsc` error. The default is the erased (all-providers)
+ * shape used by the runtime/`AnyHook`.
+ */
+export interface BashToolEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
+    readonly event: string;
+    readonly tool: "Bash";
+    readonly command: CommandView;
+    /** Host-gathered, DECLARED read-only facts (git branch, …) — see `needs`. */
+    readonly ctx: HookCtx<N>;
+}
+/** A hook program: where it fires + the pure decision. */
+export interface HookProgram<N extends readonly NeedSpec[] = readonly ProviderName[]> {
+    readonly on: string;
+    readonly match: {
+        readonly tool: string;
+    };
+    /** `enforce` (default) blocks on a `deny`; `observe` records + allows. */
+    readonly mode?: HookMode;
+    /** Declared context providers the trusted runtime gathers into `e.ctx`. */
+    readonly needs?: N;
+    readonly decide: (e: BashToolEvent<N>) => Decision;
+}
+export declare const tool: (name: string) => {
+    tool: string;
+};
+export declare function defineHook<const N extends readonly NeedSpec[] = readonly []>(p: HookProgram<N>): HookProgram<N>;
+/** Build the typed event from a raw PreToolUse event, then decide. */
+export declare function decideProgram<N extends readonly NeedSpec[]>(program: HookProgram<N>, rawEvent: {
+    tool_name?: string;
+    tool_input?: {
+        command?: unknown;
+    };
+}, ctx?: Record<string, string | boolean>): Decision;
+/** Map a Decision to the CC hook exit code — the protocol the author never writes. */
+export declare function decisionExitCode(d: Decision): number;
+/**
+ * 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.)
+ */
+export declare function checkHookImports(source: string): string[];
+export declare class HookCompileError extends Error {
+}
+/** A compiled hook program: the harness block + a tamper-evident stamp. */
+export interface CompiledHookProgram {
+    readonly hooks: Record<string, readonly {
+        /** Tool matcher — omitted for tool-less events (SessionStart/UserPromptSubmit). */
+        readonly matcher?: string;
+        readonly hooks: readonly {
+            readonly type: "command";
+            readonly command: string;
+        }[];
+    }[]>;
+    /**
+     * The rendered settings block to add to the harness's hooks config — JSON for
+     * Claude Code (`.claude/settings.json`), TOML `[[hooks.<event>]]` for Codex
+     * (`config.toml`). The CLI prints this; the structured `hooks` above is the
+     * Claude-Code-shaped intermediate.
+     */
+    readonly settingsBlock: string;
+    /** SHA-256 of the sanctioned source — the runtime refuses an artifact whose stamp differs. */
+    readonly stamp: SHA256Hash;
+}
+/**
+ * Per-harness emit inputs (all optional, default to Claude Code) — the ports the
+ * CLI threads in from the resolved adapter. Keeps the core harness-agnostic:
+ * core depends only on these interfaces, never an adapter (core ⊄ adapter).
+ */
+export interface CompileHookOptions {
+    /** The command the emitted block routes the event to. */
+    readonly gateCommand?: string;
+    /** Validate `hook.on` against this harness's hook-event catalog (a typo won't compile). */
+    readonly dialect?: HarnessDialect;
+    /** Matcher style (exact vs anchored regex). Defaults to Claude Code's `"exact"`. */
+    readonly hookProtocol?: HookProtocol;
+    /** Settings encoding — `"json"` (Claude Code) or `"toml"` (Codex). From `PluginLayout.settingsFormat`. */
+    readonly settingsFormat?: "json" | "toml";
+    /** Names of registered providers (`.vigiles/providers/`) a `provider()` ref may resolve to. */
+    readonly registeredProviders?: readonly string[];
+}
+/**
+ * Every hook shape the closed vocabulary can express. `compileHookProgram`
+ * (emit) and the runtime dispatch both range over this union.
+ */
+/**
+ * The ERASED needs-generic for the {@link AnyHook} union. A gate's `decide`
+ * carries `N` contravariantly (in the event param), so no single concrete
+ * instantiation is a supertype of every authored hook (a built-in-needs hook and
+ * an inline-needs hook have no common `HookProgram<N>`). `any` erases the context
+ * generic for the runtime/union view; the decode functions re-narrow + cast `ctx`
+ * (they never trust this type). Author-facing types keep the precise `N`.
+ */
+type ErasedNeeds = readonly any[];
+export type AnyHook = HookProgram<ErasedNeeds> | FileGateHook<ErasedNeeds> | PromptGateHook<ErasedNeeds> | StopGateHook<ErasedNeeds> | InjectHook | ReactHook;
+/**
+ * The runtime dispatch shapes. A bare {@link HookProgram} (no `role`) is a Bash
+ * command gate; the role-keyed hooks carry their own shape. The runtime uses this
+ * to pick the right decode + output (a gate exits 2, an inject prints
+ * `additionalContext`, a react runs its classified command). `prompt-gate` and
+ * `stop-gate` are gates on non-tool events — they decode the prompt / stop signal
+ * and emit a `Decision` like the tool gates.
+ */
+export type DispatchKind = "bash-gate" | "file-gate" | "prompt-gate" | "stop-gate" | "inject" | "react";
+export declare function dispatchKind(hook: AnyHook): DispatchKind;
+/** A gate's {@link HookMode} (`enforce` default); non-gate roles report `enforce` too. */
+export declare function hookMode(hook: AnyHook): HookMode;
+/** The context providers a hook declared via `needs` ([] if none / not a gate). */
+export declare function hookNeeds(hook: AnyHook): readonly NeedSpec[];
+/** Where a hook fires + its tool matcher (undefined for tool-less events). */
+export declare function hookRouting(hook: AnyHook): {
+    on: string;
+    matcher?: string;
+};
+/**
+ * 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.
+ */
+export declare function compileHookProgram(source: string, hook: AnyHook, opts?: CompileHookOptions): CompiledHookProgram;
+/** Stamp a hook's source (the integrity.ts pattern, applied to a hook artifact). */
+export declare function stampHook(source: string): SHA256Hash;
+/** Verify a shipped hook artifact matches its stamp (tamper → false). */
+export declare function verifyHookStamp(source: string, stamp: SHA256Hash): boolean;
+/** An AST-free view of a file path — the matching primitive for file tools. */
+export interface PathView {
+    readonly raw: string;
+    /** True iff the path sits under at least one allowed prefix (e.g. "src/**"). */
+    under(prefixes: readonly string[]): boolean;
+}
+export declare function pathView(raw: string): PathView;
+/** The event a file-tool gate decides over (Edit/Write/Read carry `file_path`). */
+export interface FileToolEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
+    readonly event: string;
+    readonly tool: string;
+    readonly path: PathView;
+    /** Host-gathered, DECLARED read-only facts — see `needs`. */
+    readonly ctx: HookCtx<N>;
+}
+export interface FileGateHook<N extends readonly NeedSpec[] = readonly ProviderName[]> {
+    readonly role: "gate";
+    readonly on: string;
+    readonly match: {
+        readonly tools: readonly string[];
+    };
+    /** `enforce` (default) blocks on a `deny`; `observe` records + allows. */
+    readonly mode?: HookMode;
+    /** Declared context providers the trusted runtime gathers into `e.ctx`. */
+    readonly needs?: N;
+    readonly decide: (e: FileToolEvent<N>) => Decision;
+}
+export declare const tools: (...names: string[]) => {
+    tools: string[];
+};
+export declare function defineFileGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<FileGateHook<N>, "role">): FileGateHook<N>;
+/** Run a file-tool gate against a raw PreToolUse event (reads `file_path`). */
+export declare function decideFileGate<N extends readonly NeedSpec[]>(hook: FileGateHook<N>, raw: {
+    tool_name?: string;
+    tool_input?: {
+        file_path?: unknown;
+    };
+}, ctx?: Record<string, string | boolean>): Decision;
+/** The event a UserPromptSubmit gate decides over — it sees the prompt TEXT. */
+export interface PromptEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
+    readonly event: string;
+    /** The user's submitted prompt text (empty string if the event carried none). */
+    readonly prompt: string;
+    /** Host-gathered, DECLARED read-only facts — see `needs`. */
+    readonly ctx: HookCtx<N>;
+}
+export interface PromptGateHook<N extends readonly NeedSpec[] = readonly ProviderName[]> {
+    readonly role: "prompt-gate";
+    /** The event — `UserPromptSubmit`. */
+    readonly on: string;
+    /** `enforce` (default) blocks on a `deny`; `observe` records + allows. */
+    readonly mode?: HookMode;
+    /** Declared context providers the trusted runtime gathers into `e.ctx`. */
+    readonly needs?: N;
+    /** Decide over the prompt. `deny` blocks/erases the prompt; `ask` defers to the user. */
+    readonly decide: (e: PromptEvent<N>) => Decision;
+}
+export declare function definePromptGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<PromptGateHook<N>, "role">): PromptGateHook<N>;
+/** Run a prompt gate against a raw UserPromptSubmit event (reads `prompt`). */
+export declare function decidePromptGate<N extends readonly NeedSpec[]>(hook: PromptGateHook<N>, raw: {
+    prompt?: unknown;
+}, ctx?: Record<string, string | boolean>): Decision;
+/**
+ * The event a Stop gate decides over. `deny` BLOCKS the agent from ending its
+ * turn (the reason is surfaced to the agent — e.g. "tests are red, keep going").
+ */
+export interface StopEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
+    readonly event: string;
+    /**
+     * True when this Stop is itself the consequence of a PRIOR Stop-block — the
+     * loop guard. A gate MUST return `allow` when this is set, or it can wedge the
+     * agent in an infinite stop→continue→stop cycle.
+     */
+    readonly stopHookActive: boolean;
+    /** Host-gathered, DECLARED read-only facts — see `needs`. */
+    readonly ctx: HookCtx<N>;
+}
+export interface StopGateHook<N extends readonly NeedSpec[] = readonly ProviderName[]> {
+    readonly role: "stop-gate";
+    /** The event — `Stop` or `SubagentStop`. */
+    readonly on: string;
+    /** `enforce` (default) blocks on a `deny`; `observe` records + allows. */
+    readonly mode?: HookMode;
+    /** Declared context providers the trusted runtime gathers into `e.ctx`. */
+    readonly needs?: N;
+    /** Decide whether the agent may stop. `deny` keeps it going; `allow` lets it stop. */
+    readonly decide: (e: StopEvent<N>) => Decision;
+}
+export declare function defineStopGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<StopGateHook<N>, "role">): StopGateHook<N>;
+/** Run a Stop gate against a raw Stop/SubagentStop event (reads `stop_hook_active`). */
+export declare function decideStopGate<N extends readonly NeedSpec[]>(hook: StopGateHook<N>, raw: {
+    stop_hook_active?: unknown;
+}, ctx?: Record<string, string | boolean>): Decision;
+/** The output of an inject hook — text to add to context. NO allow/deny exists here. */
+export interface Injection {
+    readonly kind: "inject";
+    readonly context: string;
+}
+export declare const inject: (context: string) => Injection;
+/** The event an inject hook produces from (no tool — SessionStart/UserPromptSubmit). */
+export interface SessionEvent {
+    readonly event: string;
+    readonly source: string;
+}
+export interface InjectHook {
+    readonly role: "inject";
+    readonly on: string;
+    /** Produces context to add. Its return type (Injection) has no `deny` — by design. */
+    readonly produce: (e: SessionEvent) => Injection;
+}
+export declare const defineInject: (p: Omit<InjectHook, "role">) => InjectHook;
+/**
+ * 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.
+ */
+export declare function runInject(hook: InjectHook, raw: {
+    source?: string;
+}): {
+    hookSpecificOutput: {
+        hookEventName: string;
+        additionalContext: string;
+    };
+};
+/**
+ * A view of a tool's RESPONSE (PostToolUse) — the matching primitive a react hook
+ * reasons over (e.g. capture/notify only when a command FAILED). The author never
+ * parses the raw payload shape.
+ */
+export interface ResponseView {
+    /** The response as text (an object payload is JSON-stringified). */
+    readonly raw: string;
+    /**
+     * True iff the tool reported a failure — a truthy `error`/`is_error` field on a
+     * structured payload, or a leading `Error`/`error:` line on a text one.
+     */
+    isError(): boolean;
+    /** True iff the response text contains `needle`. */
+    contains(needle: string): boolean;
+}
+export declare function responseView(raw: unknown): ResponseView;
+/** The event a react hook reacts over — the tool, the file path, AND its response. */
+export interface ReactEvent {
+    readonly event: string;
+    readonly tool: string;
+    readonly path: PathView;
+    /** The tool's response (PostToolUse) — react only on an error, capture output, … */
+    readonly response: ResponseView;
+}
+export interface RunReaction {
+    readonly kind: "run";
+    readonly command: string;
+    readonly effect: BashEffect;
+}
+export type Reaction = RunReaction | {
+    readonly kind: "notice";
+    readonly message: string;
+} | {
+    readonly kind: "none";
+};
+/** Run a command in reaction — its effect is classified AT CONSTRUCTION (audit/diff-able). */
+export declare const run: (command: string) => RunReaction;
+/** Surface a non-blocking note (no execution). */
+export declare const notice: (message: string) => Reaction;
+/** Do nothing. */
+export declare const nothing: () => Reaction;
+export interface ReactHook {
+    readonly role: "react";
+    readonly on: string;
+    readonly match: {
+        readonly tools: readonly string[];
+    };
+    /** Reacts to a tool that already ran. Returns a Reaction — NO `deny` exists here. */
+    readonly react: (e: ReactEvent) => Reaction;
+}
+export declare const defineReact: (p: Omit<ReactHook, "role">) => ReactHook;
+/** Run a react hook against a raw PostToolUse event → the (classified) Reaction. */
+export declare function runReact(hook: ReactHook, raw: {
+    tool_name?: string;
+    tool_input?: {
+        file_path?: unknown;
+    };
+    tool_response?: unknown;
+}): Reaction;
+/** The raw event fields the decode functions read (the union across roles). */
+export interface RawHookEvent {
+    readonly tool_name?: string;
+    readonly tool_input?: {
+        readonly command?: unknown;
+        readonly file_path?: unknown;
+    };
+    /** PostToolUse response (react). */
+    readonly tool_response?: unknown;
+    /** SessionStart / UserPromptSubmit (inject). */
+    readonly source?: string;
+    /** UserPromptSubmit (prompt-gate). */
+    readonly prompt?: string;
+    /** Stop / SubagentStop (stop-gate) — the prior-block loop guard. */
+    readonly stop_hook_active?: boolean;
+}
+/** The normalized outcome of running a hook program — discriminated by role. */
+export type HookProgramOutcome = {
+    readonly kind: "decision";
+    readonly decision: Decision;
+} | {
+    readonly kind: "injection";
+    readonly context: string;
+} | {
+    readonly kind: "reaction";
+    readonly reaction: Reaction;
+};
+/**
+ * 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`).
+ */
+export declare function runHookProgram(hook: AnyHook, event: RawHookEvent, ctx?: Record<string, string | boolean>): HookProgramOutcome;
+export {};
+//# sourceMappingURL=hook-program.d.ts.map