@cruxy/cli 0.14.0 → 0.17.0

package/dist/hooks/runner.js

@@ -0,0 +1,114 @@
+import { hookFailed, hookUntrusted, messageOf } from "../errors/index.js";
+import { runGatedShell } from "../tools/shell/exec.js";
+import { fingerprintHooks, isTrusted } from "./trust.js";
+export class HookRunner {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The project hooks — the trust-gated subset. */
+    get projectHooks() {
+        return this.deps.hooks.filter((h) => h.source === "project");
+    }
+    /**
+     * Fire every hook registered for `event`, in catalog order. Resolves normally
+     * when all hooks pass (or advisory ones fail); THROWS `CRUXY_E_HOOK_FAILED`
+     * when a blocking hook fails, or `CRUXY_E_HOOK_UNTRUSTED` when a project's
+     * hooks are not trusted. A no-op when hooks are disabled or none match.
+     */
+    async fire(event, ctx) {
+        if (!this.deps.enabled)
+            return;
+        const applicable = this.deps.hooks.filter((h) => h.event === event);
+        if (applicable.length === 0)
+            return;
+        // Trust gate FIRST — before any project hook can reach execution.
+        if (applicable.some((h) => h.source === "project")) {
+            await this.ensureProjectTrust();
+        }
+        for (const hook of applicable) {
+            this.deps.announce?.(`running hook: ${hook.name}`);
+            const verdict = await this.runOne(hook, ctx);
+            if (verdict.ok)
+                continue;
+            if (hook.blocking) {
+                // Fail-closed: stop, do not run the remaining hooks, abort the action.
+                throw hookFailed(hook.name, verdict.reason ?? "hook failed");
+            }
+            // Advisory: the action already happened (or proceeds) — report, continue.
+            this.deps.reportFailure?.(`hook "${hook.name}" failed (advisory): ${verdict.reason ?? "unknown"}`);
+        }
+    }
+    /**
+     * Ensure this repo's project hooks are trusted for their current fingerprint.
+     * Records trust on an interactive accept; throws `CRUXY_E_HOOK_UNTRUSTED` on
+     * decline, when `trustPrompt` is off, or when non-interactive — NEVER
+     * auto-trusts. The fingerprint covers ALL project hooks, so a change to any of
+     * them invalidates a prior decision (stale → re-prompt).
+     */
+    async ensureProjectTrust() {
+        const projectHooks = this.projectHooks;
+        const fingerprint = fingerprintHooks(projectHooks);
+        if (isTrusted(this.deps.trust, this.deps.cwd, fingerprint))
+            return;
+        // Never auto-trust: no prompt possible → fail loud.
+        if (!this.deps.interactive ||
+            !this.deps.trustPrompt ||
+            !this.deps.promptTrust) {
+            throw hookUntrusted(this.deps.cwd, projectHooks.length);
+        }
+        const trusted = await this.deps.promptTrust({
+            root: this.deps.cwd,
+            hooks: projectHooks,
+        });
+        if (!trusted) {
+            // Decline is not recorded — the next run asks again. Nothing runs now.
+            throw hookUntrusted(this.deps.cwd, projectHooks.length);
+        }
+        this.deps.trust.record({
+            root: this.deps.cwd,
+            fingerprint,
+            at: this.deps.now?.() ?? nowIso(),
+        });
+    }
+    /**
+     * Run one hook command through the shared gate + sandbox path and reduce it to
+     * a pass/fail verdict. A throw from {@link runGatedShell} (non-interactive
+     * approval, sandbox start failure) is a failure whose policy the caller
+     * applies — so an advisory hook can never abort the run on an infra error.
+     */
+    async runOne(hook, ctx) {
+        let outcome;
+        try {
+            outcome = await runGatedShell(hook.command, ctx);
+        }
+        catch (err) {
+            return { ok: false, reason: messageOf(err) ?? "hook could not run" };
+        }
+        return evaluate(outcome);
+    }
+}
+/** Reduce a gated-shell outcome to pass/fail. Success is EXACTLY exit code 0. */
+function evaluate(outcome) {
+    if (!outcome.approved) {
+        return {
+            ok: false,
+            reason: outcome.rejection ?? "declined at the approval prompt",
+        };
+    }
+    const e = outcome.exec;
+    if (e.timedOut)
+        return { ok: false, reason: "timed out" };
+    if (e.spawnError !== undefined)
+        return { ok: false, reason: e.spawnError };
+    if (e.exitCode !== 0) {
+        return {
+            ok: false,
+            reason: `exited with code ${e.exitCode ?? e.signal ?? "unknown"}`,
+        };
+    }
+    return { ok: true };
+}
+function nowIso() {
+    return new Date().toISOString();
+}

package/dist/hooks/service.d.ts

@@ -0,0 +1,38 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { logger as Logger } from "../utils/logger.js";
+import { type HookSources } from "./config.js";
+import { HookRunner, type TrustPromptInfo } from "./runner.js";
+import { type TrustStore } from "./trust.js";
+import type { HookCatalog, SlashCommandSpec } from "./types.js";
+/**
+ * Construction/wiring for the hooks subsystem (C.19). Loads the layered catalog,
+ * builds the {@link HookRunner} with the real trust store + an interactive trust
+ * prompt, and exposes the resolved custom slash commands. Everything the runner
+ * needs is injectable so the security behavior is unit-testable without touching
+ * disk or a TTY.
+ */
+export interface HooksService {
+    /** The lifecycle firing seam (threaded into the loop / session). */
+    runner: HookRunner;
+    /** Resolved custom slash commands (project > user). */
+    commands: SlashCommandSpec[];
+    /** The full catalog (for `cruxy hooks list` + surfacing load errors). */
+    catalog: HookCatalog;
+}
+export interface BuildHooksServiceOptions {
+    cwd: string;
+    config: CruxyConfig;
+    /** Whether cruxy can prompt (stdin is a TTY). */
+    interactive: boolean;
+    logger: typeof Logger;
+    sources?: HookSources;
+    trust?: TrustStore;
+    promptTrust?: (info: TrustPromptInfo) => Promise<boolean>;
+    now?: () => string;
+}
+/**
+ * Load the catalog and assemble the {@link HooksService}. Malformed definitions
+ * are surfaced (never eval'd, never silently dropped) through the logger; the
+ * valid ones proceed.
+ */
+export declare function buildHooksService(opts: BuildHooksServiceOptions): Promise<HooksService>;

package/dist/hooks/service.js

@@ -0,0 +1,49 @@
+import { readSingleKey } from "../components/input.js";
+import { shouldUseColor } from "../errors/index.js";
+import { themeForColor } from "../theme/index.js";
+import { defaultHookSources, loadHookCatalog, } from "./config.js";
+import { HookRunner } from "./runner.js";
+import { fileTrustStore } from "./trust.js";
+/**
+ * Load the catalog and assemble the {@link HooksService}. Malformed definitions
+ * are surfaced (never eval'd, never silently dropped) through the logger; the
+ * valid ones proceed.
+ */
+export async function buildHooksService(opts) {
+    const sources = opts.sources ?? defaultHookSources(opts.cwd);
+    const catalog = await loadHookCatalog(sources);
+    for (const err of catalog.errors) {
+        opts.logger.warn(`ignoring malformed ${err.source} hook/command "${err.name}": ${err.message}`);
+    }
+    const trust = opts.trust ?? fileTrustStore();
+    const runner = new HookRunner({
+        hooks: catalog.hooks,
+        trust,
+        enabled: opts.config.hooks.enabled,
+        trustPrompt: opts.config.hooks.trustPrompt,
+        interactive: opts.interactive,
+        cwd: opts.cwd,
+        promptTrust: opts.promptTrust ?? defaultTrustPrompt,
+        announce: (message) => opts.logger.info(message),
+        reportFailure: (message) => opts.logger.warn(message),
+        now: opts.now,
+    });
+    return { runner, commands: catalog.commands, catalog };
+}
+/**
+ * The real interactive trust prompt: list the project's hooks (name → event →
+ * command) and read a single y/N key. Default-deny — anything but `y` (including
+ * EOF / Ctrl-C) declines, so an untrusted repo never runs on a stray keypress.
+ */
+async function defaultTrustPrompt(info) {
+    const t = themeForColor(shouldUseColor());
+    const out = process.stderr;
+    out.write(`\n${t.warning(t.strong("!"))} this project defines ${t.strong(String(info.hooks.length))} hook${info.hooks.length === 1 ? "" : "s"} (authored by the repo):\n`);
+    for (const h of info.hooks) {
+        out.write(`  ${t.muted(`${h.event}`)} ${t.strong(h.name)} ${t.muted("→")} ${h.command}\n`);
+    }
+    out.write(`${t.muted("review these carefully.")} trust and run this project's hooks? ${t.muted("[y/N]")} `);
+    const key = (await readSingleKey()).toLowerCase();
+    out.write("\n");
+    return key === "y";
+}

package/dist/hooks/slash.d.ts

@@ -0,0 +1,48 @@
+import type { SlashCommandSpec } from "./types.js";
+/**
+ * Custom slash-command resolution (C.19). Builtins are reserved and always win —
+ * a custom command can never shadow `/help`, `/exit`, etc. A resolved custom
+ * command is either a `prompt` (expanded to safe text fed to the agent) or a
+ * `shell` binding (executed through the SAME gate + sandbox as everything else,
+ * by the caller). Nothing here executes anything; it only resolves + expands.
+ */
+/** The builtin slash commands (C.13) — reserved, not overridable. */
+export declare const BUILTIN_SLASH_COMMANDS: readonly ["help", "clear", "compact", "reload", "plan", "exit", "quit"];
+/** Is `name` (no leading slash) a reserved builtin? */
+export declare function isBuiltinSlash(name: string): boolean;
+/** The outcome of resolving a `/…` line against the custom catalog. */
+export type SlashResolution = 
+/** A builtin — the REPL's own dispatch handles it (custom never shadows it). */
+{
+    kind: "builtin";
+    name: string;
+}
+/** A prompt-template command, already expanded to the text to send the agent. */
+ | {
+    kind: "prompt";
+    spec: SlashCommandSpec;
+    prompt: string;
+}
+/** A shell-bound command — the caller runs `spec.command` through the gate. */
+ | {
+    kind: "shell";
+    spec: SlashCommandSpec;
+    args: string;
+}
+/** Not a slash line, or an unknown command. */
+ | {
+    kind: "none";
+};
+/**
+ * Resolve one input line. Non-slash input and unknown names → `none`. Builtins
+ * short-circuit to `builtin` BEFORE the custom catalog is consulted, so a custom
+ * command named after a builtin is inert (surfaced separately at load time).
+ */
+export declare function resolveSlash(line: string, commands: readonly SlashCommandSpec[]): SlashResolution;
+/**
+ * Expand a prompt template — substitute every `{{args}}` with the caller's args.
+ * Pure text in, pure text out: the result is fed to the agent as a user prompt,
+ * so a prompt command can never execute anything (that is the whole safety of
+ * the default `prompt` kind).
+ */
+export declare function expandTemplate(template: string, args: string): string;

package/dist/hooks/slash.js

@@ -0,0 +1,58 @@
+/**
+ * Custom slash-command resolution (C.19). Builtins are reserved and always win —
+ * a custom command can never shadow `/help`, `/exit`, etc. A resolved custom
+ * command is either a `prompt` (expanded to safe text fed to the agent) or a
+ * `shell` binding (executed through the SAME gate + sandbox as everything else,
+ * by the caller). Nothing here executes anything; it only resolves + expands.
+ */
+/** The builtin slash commands (C.13) — reserved, not overridable. */
+export const BUILTIN_SLASH_COMMANDS = [
+    "help",
+    "clear",
+    "compact",
+    "reload",
+    "plan",
+    "exit",
+    "quit",
+];
+const BUILTINS = new Set(BUILTIN_SLASH_COMMANDS);
+/** Is `name` (no leading slash) a reserved builtin? */
+export function isBuiltinSlash(name) {
+    return BUILTINS.has(name);
+}
+/**
+ * Resolve one input line. Non-slash input and unknown names → `none`. Builtins
+ * short-circuit to `builtin` BEFORE the custom catalog is consulted, so a custom
+ * command named after a builtin is inert (surfaced separately at load time).
+ */
+export function resolveSlash(line, commands) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("/"))
+        return { kind: "none" };
+    const space = trimmed.indexOf(" ");
+    const name = (space === -1 ? trimmed.slice(1) : trimmed.slice(1, space)).trim();
+    const args = space === -1 ? "" : trimmed.slice(space + 1).trim();
+    if (name === "")
+        return { kind: "none" };
+    if (isBuiltinSlash(name))
+        return { kind: "builtin", name };
+    const spec = commands.find((c) => c.name === name);
+    if (!spec)
+        return { kind: "none" };
+    if (spec.kind === "shell")
+        return { kind: "shell", spec, args };
+    return {
+        kind: "prompt",
+        spec,
+        prompt: expandTemplate(spec.template ?? "", args),
+    };
+}
+/**
+ * Expand a prompt template — substitute every `{{args}}` with the caller's args.
+ * Pure text in, pure text out: the result is fed to the agent as a user prompt,
+ * so a prompt command can never execute anything (that is the whole safety of
+ * the default `prompt` kind).
+ */
+export function expandTemplate(template, args) {
+    return template.replaceAll("{{args}}", args);
+}

package/dist/hooks/trust.d.ts

@@ -0,0 +1,46 @@
+import type { HookDefinition, HookTrust } from "./types.js";
+/**
+ * The project-hook trust model (C.19). Trust is recorded in the GLOBAL dir
+ * (`~/.cruxy/trust.json`) — in the user's home, NEVER inside a repo — so cloning
+ * a repo carries zero trust and an attacker cannot ship a pre-trusted marker.
+ *
+ * Trust is bound to a {@link fingerprintHooks fingerprint} of the exact project
+ * hook commands seen at trust time. It is re-checked on every run: if the
+ * project's hooks change (a command / event / blocking edit), the fingerprint no
+ * longer matches and trust is stale → the user is re-prompted. This is what
+ * defeats trust-then-swap.
+ */
+/** ~/.cruxy/trust.json */
+export declare function trustPath(): string;
+/**
+ * A stable content fingerprint of a repo's PROJECT hook definitions. Canonical
+ * by construction so a benign reformat of `hooks.json` (reindent, reordered
+ * keys, extra whitespace inside a command) does NOT change it, while any real
+ * change to a command, event, or blocking flag DOES:
+ * - only the meaning-bearing fields are hashed (name, event, command, blocking);
+ * - the command string is whitespace-normalized (trim + collapse runs);
+ * - specs are sorted by name and serialized with a fixed key order.
+ */
+export declare function fingerprintHooks(hooks: readonly HookDefinition[]): string;
+/** The persisted trust seam — a file-backed store in production, injectable for
+ * tests. `get`/`record` are synchronous (the record is tiny). */
+export interface TrustStore {
+    /** The recorded decision for a repo root, or undefined if never trusted. */
+    get(root: string): HookTrust | undefined;
+    /** Persist a trust decision (overwrites any prior one for the same root). */
+    record(trust: HookTrust): void;
+}
+/**
+ * Is this repo's current project-hook set trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — a changed hook set is
+ * treated as untrusted (stale), forcing a fresh decision.
+ */
+export declare function isTrusted(store: TrustStore, root: string, currentFingerprint: string): boolean;
+/**
+ * The real store, persisting to `~/.cruxy/trust.json` as `{ [root]: HookTrust }`.
+ * Reads are lazy + cached; a corrupt file is treated as "no trust recorded"
+ * (fail-closed — a broken trust file must never grant trust).
+ */
+export declare function fileTrustStore(file?: string): TrustStore;
+/** An in-memory store for tests (and any ephemeral run). */
+export declare function memoryTrustStore(seed?: HookTrust[]): TrustStore;

package/dist/hooks/trust.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { TRUST_FILE_NAME } from "../constants.js";
+/**
+ * The project-hook trust model (C.19). Trust is recorded in the GLOBAL dir
+ * (`~/.cruxy/trust.json`) — in the user's home, NEVER inside a repo — so cloning
+ * a repo carries zero trust and an attacker cannot ship a pre-trusted marker.
+ *
+ * Trust is bound to a {@link fingerprintHooks fingerprint} of the exact project
+ * hook commands seen at trust time. It is re-checked on every run: if the
+ * project's hooks change (a command / event / blocking edit), the fingerprint no
+ * longer matches and trust is stale → the user is re-prompted. This is what
+ * defeats trust-then-swap.
+ */
+/** ~/.cruxy/trust.json */
+export function trustPath() {
+    return path.join(globalDir(), TRUST_FILE_NAME);
+}
+/**
+ * A stable content fingerprint of a repo's PROJECT hook definitions. Canonical
+ * by construction so a benign reformat of `hooks.json` (reindent, reordered
+ * keys, extra whitespace inside a command) does NOT change it, while any real
+ * change to a command, event, or blocking flag DOES:
+ * - only the meaning-bearing fields are hashed (name, event, command, blocking);
+ * - the command string is whitespace-normalized (trim + collapse runs);
+ * - specs are sorted by name and serialized with a fixed key order.
+ */
+export function fingerprintHooks(hooks) {
+    const canonical = hooks
+        .map((h) => ({
+        name: h.name,
+        event: h.event,
+        command: h.command.trim().replace(/\s+/g, " "),
+        blocking: h.blocking,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        // Fixed key order — JSON of an object literal preserves insertion order.
+        .map((h) => [h.name, h.event, h.command, h.blocking]);
+    return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+/**
+ * Is this repo's current project-hook set trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — a changed hook set is
+ * treated as untrusted (stale), forcing a fresh decision.
+ */
+export function isTrusted(store, root, currentFingerprint) {
+    const record = store.get(path.resolve(root));
+    return record !== undefined && record.fingerprint === currentFingerprint;
+}
+// ── file-backed store ─────────────────────────────────────────────────────────
+/**
+ * The real store, persisting to `~/.cruxy/trust.json` as `{ [root]: HookTrust }`.
+ * Reads are lazy + cached; a corrupt file is treated as "no trust recorded"
+ * (fail-closed — a broken trust file must never grant trust).
+ */
+export function fileTrustStore(file = trustPath()) {
+    let cache = null;
+    const load = () => {
+        if (cache)
+            return cache;
+        try {
+            const raw = JSON.parse(readFileSync(file, "utf8"));
+            cache =
+                raw && typeof raw === "object"
+                    ? raw
+                    : {};
+        }
+        catch {
+            // Missing or corrupt → no trust (fail-closed).
+            cache = {};
+        }
+        return cache;
+    };
+    return {
+        get(root) {
+            return load()[path.resolve(root)];
+        },
+        record(trust) {
+            const store = load();
+            store[path.resolve(trust.root)] = {
+                ...trust,
+                root: path.resolve(trust.root),
+            };
+            mkdirSync(path.dirname(file), { recursive: true });
+            // 0600: trust records name local paths; keep them owner-only.
+            writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+            if (existsSync(file))
+                cache = store;
+        },
+    };
+}
+/** An in-memory store for tests (and any ephemeral run). */
+export function memoryTrustStore(seed = []) {
+    const store = new Map();
+    for (const t of seed)
+        store.set(path.resolve(t.root), t);
+    return {
+        get: (root) => store.get(path.resolve(root)),
+        record: (trust) => void store.set(path.resolve(trust.root), {
+            ...trust,
+            root: path.resolve(trust.root),
+        }),
+    };
+}

package/dist/hooks/types.d.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+/**
+ * Types for hooks + custom slash commands (C.19). Everything here is **data**:
+ * hook and command definitions are validated (fail-loud, malformed excluded) and
+ * NEVER eval'd — a hook's `command` string only ever reaches execution through
+ * the shared U.3-gated + C.16-sandboxed shell path (see `runner.ts`), exactly
+ * like an agent-run command.
+ */
+/**
+ * The core hook lifecycle events. Deliberately a small, closed set for this
+ * build; the enum is the extension point for future events (out of scope).
+ * - `before-run` / `after-run` — around a whole user turn (the agent loop).
+ * - `before-tool` / `after-tool` — around each tool call.
+ * - `on-file-change` — after a file-mutating tool (write/edit/patch) succeeds.
+ */
+export declare const HOOK_EVENTS: readonly ["before-run", "after-run", "before-tool", "after-tool", "on-file-change"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** `before-*` events default to blocking (fail-closed pre-checks); everything
+ * that fires *after* an action defaults to advisory. Overridable per hook. */
+export declare function defaultBlocking(event: HookEvent): boolean;
+/** Where a hook / command was discovered. `project` is the supply-chain-risky
+ * source (another author); `user` is your own `~/.cruxy`. */
+export type HookSource = "project" | "user";
+/** Precedence: a project definition overrides a user one of the same name. */
+export declare const HOOK_SOURCE_PRECEDENCE: readonly HookSource[];
+/** Strict schema for one hook definition in a `hooks.json`. Unknown keys are a
+ * loud error (`.strict()`); `blocking` is optional (resolved from the event). */
+export declare const HookSpecSchema: z.ZodObject<{
+    name: z.ZodString;
+    event: z.ZodEnum<["before-run", "after-run", "before-tool", "after-tool", "on-file-change"]>;
+    command: z.ZodString;
+    blocking: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    command: string;
+    event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+    blocking?: boolean | undefined;
+}, {
+    name: string;
+    command: string;
+    event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+    blocking?: boolean | undefined;
+}>;
+export type HookSpec = z.infer<typeof HookSpecSchema>;
+/** The whole `hooks.json` file shape. */
+export declare const HooksFileSchema: z.ZodObject<{
+    hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        event: z.ZodEnum<["before-run", "after-run", "before-tool", "after-tool", "on-file-change"]>;
+        command: z.ZodString;
+        blocking: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }, {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    hooks: {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }[];
+}, {
+    hooks?: {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }[] | undefined;
+}>;
+/** A validated hook, tagged with its source and with `blocking` resolved. */
+export interface HookDefinition {
+    name: string;
+    event: HookEvent;
+    command: string;
+    /** Resolved (event default applied) — the value the runner acts on. */
+    blocking: boolean;
+    source: HookSource;
+}
+/**
+ * A custom slash command. `prompt` (the safe default) expands a text template
+ * fed to the agent; `shell` binds a command that runs through the SAME gate +
+ * sandbox as everything else. Never arbitrary code by default.
+ */
+export type SlashKind = "prompt" | "shell";
+/** Strict frontmatter for a `commands/<name>.md`. The command NAME comes from
+ * the filename; the markdown BODY is the prompt template (kind `prompt`). */
+export declare const SlashFrontmatterSchema: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodEnum<["prompt", "shell"]>>;
+    description: z.ZodString;
+    /** Required (and only meaningful) when `kind: "shell"`. */
+    command: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    kind: "shell" | "prompt";
+    description: string;
+    command?: string | undefined;
+}, {
+    description: string;
+    command?: string | undefined;
+    kind?: "shell" | "prompt" | undefined;
+}>;
+export type SlashFrontmatter = z.infer<typeof SlashFrontmatterSchema>;
+/** A validated custom slash command, tagged with source. */
+export interface SlashCommandSpec {
+    name: string;
+    kind: SlashKind;
+    description: string;
+    /** Prompt template (kind `prompt`); `{{args}}` is substituted at expansion. */
+    template?: string;
+    /** Shell command (kind `shell`) — gated + sandboxed when run. */
+    command?: string;
+    source: HookSource;
+}
+/** A malformed hook / command, excluded from the catalog and surfaced loudly
+ * (never eval'd, never silently dropped). */
+export interface HookConfigError {
+    source: HookSource;
+    /** Absolute path of the offending file. */
+    file: string;
+    /** The would-be name (filename / spec name), for display. */
+    name: string;
+    message: string;
+}
+/** The resolved hook catalog: valid definitions (deduped by precedence) + the
+ * malformed ones that were excluded. */
+export interface HookCatalog {
+    hooks: HookDefinition[];
+    commands: SlashCommandSpec[];
+    errors: HookConfigError[];
+}
+/** One repo's recorded trust decision (persisted in `~/.cruxy/trust.json`). The
+ * `fingerprint` binds trust to the exact hook commands seen at trust time. */
+export interface HookTrust {
+    /** Absolute project root. */
+    root: string;
+    /** sha256 of the canonicalized project hook specs (see `trust.ts`). */
+    fingerprint: string;
+    /** ISO timestamp the decision was recorded. */
+    at: string;
+}

package/dist/hooks/types.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+/**
+ * Types for hooks + custom slash commands (C.19). Everything here is **data**:
+ * hook and command definitions are validated (fail-loud, malformed excluded) and
+ * NEVER eval'd — a hook's `command` string only ever reaches execution through
+ * the shared U.3-gated + C.16-sandboxed shell path (see `runner.ts`), exactly
+ * like an agent-run command.
+ */
+// ── lifecycle events ──────────────────────────────────────────────────────────
+/**
+ * The core hook lifecycle events. Deliberately a small, closed set for this
+ * build; the enum is the extension point for future events (out of scope).
+ * - `before-run` / `after-run` — around a whole user turn (the agent loop).
+ * - `before-tool` / `after-tool` — around each tool call.
+ * - `on-file-change` — after a file-mutating tool (write/edit/patch) succeeds.
+ */
+export const HOOK_EVENTS = [
+    "before-run",
+    "after-run",
+    "before-tool",
+    "after-tool",
+    "on-file-change",
+];
+/** `before-*` events default to blocking (fail-closed pre-checks); everything
+ * that fires *after* an action defaults to advisory. Overridable per hook. */
+export function defaultBlocking(event) {
+    return event === "before-run" || event === "before-tool";
+}
+/** Precedence: a project definition overrides a user one of the same name. */
+export const HOOK_SOURCE_PRECEDENCE = [
+    "project",
+    "user",
+];
+// ── hook specs ────────────────────────────────────────────────────────────────
+/** Strict schema for one hook definition in a `hooks.json`. Unknown keys are a
+ * loud error (`.strict()`); `blocking` is optional (resolved from the event). */
+export const HookSpecSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "hook name must be kebab-case (lowercase letters, digits, hyphens)"),
+    event: z.enum(HOOK_EVENTS),
+    command: z.string().min(1, "hook command must be a non-empty string"),
+    blocking: z.boolean().optional(),
+})
+    .strict();
+/** The whole `hooks.json` file shape. */
+export const HooksFileSchema = z
+    .object({ hooks: z.array(HookSpecSchema).default([]) })
+    .strict();
+/** Strict frontmatter for a `commands/<name>.md`. The command NAME comes from
+ * the filename; the markdown BODY is the prompt template (kind `prompt`). */
+export const SlashFrontmatterSchema = z
+    .object({
+    kind: z.enum(["prompt", "shell"]).default("prompt"),
+    description: z.string().min(1),
+    /** Required (and only meaningful) when `kind: "shell"`. */
+    command: z.string().min(1).optional(),
+})
+    .strict();