@cruxy/cli 0.14.0 → 0.17.0

package/dist/errors/constructors.js

@@ -1,4 +1,5 @@
 import { ApiError, AuthError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { scrubModelNames } from "../brand/index.js";
 import { CruxyError, ErrorCode } from "./types.js";
 /**
  * Helper constructors for {@link CruxyError}. Each encodes the title, the human
@@ -15,6 +16,18 @@ export function messageOf(underlying) {
         return undefined;
     return String(underlying);
 }
+/**
+ * {@link messageOf}, gag-scrubbed (U.8) for a gateway/provider-originated error.
+ * A gateway error body is an arbitrary EXTERNAL string, so it bypasses the
+ * structural tier gag — this is the boundary that scrubs any upstream model name
+ * out of it before it can reach a user-facing `cause`. Used by the provider-error
+ * constructors below (everything `classifyProviderError` routes through). The raw
+ * message stays on `underlying`, shown verbatim only under `--verbose`.
+ */
+function scrubbedMessageOf(underlying) {
+    const msg = messageOf(underlying);
+    return msg === undefined ? undefined : scrubModelNames(msg);
+}
 // ── usage (exit 2) ────────────────────────────────────────────────────────────
 export function usageError(title, nextSteps) {
     return new CruxyError({
@@ -57,6 +70,28 @@ export function providerUnsupported(provider) {
         meta: { provider },
     });
 }
+/**
+ * A task class is routed (C.30) to a tier the gateway does not offer. A usage
+ * error the user fixes in config — cruxy fails loud here rather than silently
+ * substituting a different tier (which would hand a user a model they never
+ * asked for). Distinct from runtime unavailability (overload/budget), which
+ * stays on the U.5 api codes. Params are tier/class NAMES only — never an
+ * upstream model id — so the message is gag-safe by construction (U.8).
+ */
+export function routingTierUnavailable(tier, taskClass, offered) {
+    return new CruxyError({
+        code: ErrorCode.RoutingTierUnavailable,
+        title: `the "${tier}" tier is not available for the "${taskClass}" task`,
+        cause: `routing maps "${taskClass}" to the "${tier}" tier, which this gateway does not currently offer`,
+        nextSteps: [
+            `route it to an available tier, e.g. \`cruxy config set routing.map.${taskClass} ${offered[0] ?? "vaani"}\``,
+            offered.length
+                ? `available tiers: ${offered.join(", ")}`
+                : "no tiers are currently available",
+        ],
+        meta: { tier, taskClass, offered },
+    });
+}
 // ── config (exit 3) ───────────────────────────────────────────────────────────
 export function configParse(path, underlying) {
     return new CruxyError({
@@ -99,7 +134,7 @@ export function authInvalid(underlying) {
     return new CruxyError({
         code: ErrorCode.AuthInvalid,
         title: "the provider rejected your credentials",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: [
             "verify your API key is correct and active",
             "re-export the key and try again",
@@ -112,7 +147,7 @@ export function gatewayUnreachable(underlying) {
     return new CruxyError({
         code: ErrorCode.GatewayUnreachable,
         title: "could not reach the model gateway",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: [
             "check your internet connection",
             "verify the gateway URL with `cruxy config get cruxy.gatewayUrl`",
@@ -129,7 +164,7 @@ export function apiError(underlying) {
         title: status
             ? `the model provider returned an error (HTTP ${status})`
             : "the model provider returned an error",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: [
             "retry in a moment; if it persists, check the provider's status",
         ],
@@ -142,7 +177,7 @@ export function apiRateLimit(underlying) {
     return new CruxyError({
         code: ErrorCode.ApiRateLimit,
         title: "rate limited by the model provider",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: [
             retryAfterMs
                 ? `wait ~${Math.ceil(retryAfterMs / 1000)}s and retry`
@@ -156,7 +191,7 @@ export function apiOverloaded(underlying) {
     return new CruxyError({
         code: ErrorCode.ApiOverloaded,
         title: "the model provider is overloaded",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: ["retry in a few moments"],
         underlying,
     });
@@ -165,7 +200,7 @@ export function budgetExhausted(underlying) {
     return new CruxyError({
         code: ErrorCode.BudgetExhausted,
         title: "your Cruxy budget is exhausted",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: ["top up or raise your budget, then retry"],
         underlying,
     });
@@ -282,6 +317,63 @@ export function sandboxExec(underlying) {
         underlying,
     });
 }
+// ── hooks + custom slash commands (exit 13) — C.19 ────────────────────────────
+/**
+ * A blocking hook failed (non-zero exit, gate-declined, or errored). The action
+ * that fired it is aborted fail-closed — a failing pre-check must stop, never
+ * proceed. Advisory hooks report but never raise this.
+ */
+export function hookFailed(name, reason, underlying) {
+    return new CruxyError({
+        code: ErrorCode.HookFailed,
+        title: `blocking hook "${name}" failed — action aborted`,
+        cause: reason,
+        nextSteps: [
+            `fix the hook command, or mark it advisory (blocking: false) if it should not block`,
+            "run `cruxy hooks list` to inspect the configured hooks",
+        ],
+        meta: { name },
+        underlying,
+    });
+}
+/**
+ * A project (a cloned/opened repo) defines hooks that have not been trusted for
+ * this machine. Cruxy NEVER runs another author's hooks silently — trust is an
+ * explicit, per-repo decision recorded in your home, not in the repo.
+ */
+export function hookUntrusted(root, count) {
+    return new CruxyError({
+        code: ErrorCode.HookUntrusted,
+        title: `this project defines ${count} hook${count === 1 ? "" : "s"} that are not trusted`,
+        cause: "project hooks are authored by whoever wrote the repo; cruxy will not run them until you review and trust them",
+        nextSteps: [
+            "review them with `cruxy hooks list`",
+            `trust them with \`cruxy hooks trust ${root}\` (after reviewing)`,
+            "or set hooks.enabled=false to disable hooks entirely",
+        ],
+        meta: { root, count },
+    });
+}
+/** A malformed hook definition — excluded from the catalog, never eval'd. */
+export function hookInvalid(reason, source) {
+    return new CruxyError({
+        code: ErrorCode.HookInvalid,
+        title: "a hook definition is malformed",
+        cause: reason,
+        nextSteps: ["fix the hook definition; see `cruxy hooks list` for details"],
+        meta: { source },
+    });
+}
+/** A malformed custom slash-command definition — excluded and surfaced. */
+export function slashInvalid(reason, source) {
+    return new CruxyError({
+        code: ErrorCode.SlashInvalid,
+        title: "a custom slash-command definition is malformed",
+        cause: reason,
+        nextSteps: ["fix the command definition (frontmatter + body)"],
+        meta: { source },
+    });
+}
 // ── approval (exit 10) ────────────────────────────────────────────────────────
 /**
  * A side-effecting action needs approval but cruxy can't ask (non-interactive,

package/dist/errors/types.d.ts

@@ -21,6 +21,9 @@ export declare const ErrorCode: {
     readonly PlanInvalid: "CRUXY_E_PLAN_INVALID";
     readonly PlanRevisionLimit: "CRUXY_E_PLAN_REVISION_LIMIT";
     readonly CheckpointNotFound: "CRUXY_E_CHECKPOINT_NOT_FOUND";
+    /** Routing (C.30): a task class is mapped to a tier the gateway does not
+     * offer — fix the config, NEVER a silent substitution to another tier. */
+    readonly RoutingTierUnavailable: "CRUXY_E_ROUTING_TIER_UNAVAILABLE";
     readonly ConfigParse: "CRUXY_E_CONFIG_PARSE";
     readonly ConfigInvalid: "CRUXY_E_CONFIG_INVALID";
     readonly AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY";
@@ -57,6 +60,17 @@ export declare const ErrorCode: {
     readonly SandboxUnavailable: "CRUXY_E_SANDBOX_UNAVAILABLE";
     readonly SandboxImage: "CRUXY_E_SANDBOX_IMAGE";
     readonly SandboxExec: "CRUXY_E_SANDBOX_EXEC";
+    /** A blocking hook failed (non-zero exit / declined / errored) → the action
+     * is aborted fail-closed. Advisory hooks never raise this. */
+    readonly HookFailed: "CRUXY_E_HOOK_FAILED";
+    /** A project defines hooks that have not been trusted for this repo — they are
+     * never run silently (supply-chain safety). */
+    readonly HookUntrusted: "CRUXY_E_HOOK_UNTRUSTED";
+    /** A malformed hook definition — excluded from the catalog and surfaced,
+     * never eval'd. */
+    readonly HookInvalid: "CRUXY_E_HOOK_INVALID";
+    /** A malformed custom slash-command definition — excluded and surfaced. */
+    readonly SlashInvalid: "CRUXY_E_SLASH_INVALID";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -23,6 +23,9 @@ export const ErrorCode = {
     PlanInvalid: "CRUXY_E_PLAN_INVALID",
     PlanRevisionLimit: "CRUXY_E_PLAN_REVISION_LIMIT",
     CheckpointNotFound: "CRUXY_E_CHECKPOINT_NOT_FOUND",
+    /** Routing (C.30): a task class is mapped to a tier the gateway does not
+     * offer — fix the config, NEVER a silent substitution to another tier. */
+    RoutingTierUnavailable: "CRUXY_E_ROUTING_TIER_UNAVAILABLE",
     // config (exit 3)
     ConfigParse: "CRUXY_E_CONFIG_PARSE",
     ConfigInvalid: "CRUXY_E_CONFIG_INVALID",
@@ -70,6 +73,18 @@ export const ErrorCode = {
     SandboxUnavailable: "CRUXY_E_SANDBOX_UNAVAILABLE",
     SandboxImage: "CRUXY_E_SANDBOX_IMAGE",
     SandboxExec: "CRUXY_E_SANDBOX_EXEC",
+    // hooks + custom slash commands (exit 13) — C.19
+    /** A blocking hook failed (non-zero exit / declined / errored) → the action
+     * is aborted fail-closed. Advisory hooks never raise this. */
+    HookFailed: "CRUXY_E_HOOK_FAILED",
+    /** A project defines hooks that have not been trusted for this repo — they are
+     * never run silently (supply-chain safety). */
+    HookUntrusted: "CRUXY_E_HOOK_UNTRUSTED",
+    /** A malformed hook definition — excluded from the catalog and surfaced,
+     * never eval'd. */
+    HookInvalid: "CRUXY_E_HOOK_INVALID",
+    /** A malformed custom slash-command definition — excluded and surfaced. */
+    SlashInvalid: "CRUXY_E_SLASH_INVALID",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -85,6 +100,7 @@ const EXIT_CODES = {
     [ErrorCode.PlanInvalid]: 2,
     [ErrorCode.PlanRevisionLimit]: 2,
     [ErrorCode.CheckpointNotFound]: 2,
+    [ErrorCode.RoutingTierUnavailable]: 2,
     [ErrorCode.ConfigParse]: 3,
     [ErrorCode.ConfigInvalid]: 3,
     [ErrorCode.AuthMissingKey]: 4,
@@ -123,6 +139,13 @@ const EXIT_CODES = {
     [ErrorCode.SandboxUnavailable]: 12,
     [ErrorCode.SandboxImage]: 12,
     [ErrorCode.SandboxExec]: 12,
+    // Hooks + custom slash commands (C.19). A blocking-hook failure and an
+    // untrusted project are execution-safety stops; malformed definitions are
+    // usage/config problems but share the category for a greppable exit code.
+    [ErrorCode.HookFailed]: 13,
+    [ErrorCode.HookUntrusted]: 13,
+    [ErrorCode.HookInvalid]: 13,
+    [ErrorCode.SlashInvalid]: 13,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/hooks/config.d.ts

@@ -0,0 +1,21 @@
+import { type HookCatalog } from "./types.js";
+/**
+ * Discovery for hooks + custom slash commands (C.19), mirroring the C.18 skills
+ * loader: scan layered sources (project > user), validate every definition
+ * fail-loud, exclude the malformed (collected as {@link HookConfigError}, never
+ * thrown past the loader, never eval'd), and resolve precedence. Hook
+ * definitions carry their {@link HookSource} — the trust model depends on
+ * telling a repo's hooks (project) apart from your own (user).
+ */
+/** The two source directories (each a `.cruxy` dir holding `hooks.json` and
+ * `commands/`). */
+export interface HookSources {
+    /** `<cwd>/.cruxy` */
+    project: string;
+    /** `~/.cruxy` */
+    user: string;
+}
+/** The real sources for a project root. */
+export declare function defaultHookSources(cwd: string): HookSources;
+/** Load and resolve the full hook + command catalog. */
+export declare function loadHookCatalog(sources: HookSources): Promise<HookCatalog>;

package/dist/hooks/config.js

@@ -0,0 +1,253 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { COMMANDS_DIR_NAME, GLOBAL_DIR_NAME, HOOKS_FILE_NAME, } from "../constants.js";
+import { defaultBlocking, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, SlashFrontmatterSchema, } from "./types.js";
+/** The real sources for a project root. */
+export function defaultHookSources(cwd) {
+    return {
+        project: path.join(path.resolve(cwd), GLOBAL_DIR_NAME),
+        user: globalDir(),
+    };
+}
+/** Load and resolve the full hook + command catalog. */
+export async function loadHookCatalog(sources) {
+    const hookCandidates = [];
+    const commandCandidates = [];
+    const errors = [];
+    // Precedence order: project first, then user.
+    for (const source of HOOK_SOURCE_PRECEDENCE) {
+        await scanHooksFile(source, sources[source], hookCandidates, errors);
+        await scanCommandsDir(source, sources[source], commandCandidates, errors);
+    }
+    return {
+        hooks: resolvePrecedence(hookCandidates),
+        commands: resolvePrecedence(commandCandidates),
+        errors,
+    };
+}
+// ── hooks.json ────────────────────────────────────────────────────────────────
+async function scanHooksFile(source, dir, out, errors) {
+    const file = path.join(dir, HOOKS_FILE_NAME);
+    let text;
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        // Missing file is normal (source absent); other errors are reported.
+        if (err.code !== "ENOENT") {
+            errors.push({
+                source,
+                file,
+                name: HOOKS_FILE_NAME,
+                message: `could not read ${HOOKS_FILE_NAME}: ${err.message}`,
+            });
+        }
+        return;
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        errors.push({
+            source,
+            file,
+            name: HOOKS_FILE_NAME,
+            message: `invalid JSON: ${err.message}`,
+        });
+        return;
+    }
+    // Top-level shape only; each hook is validated individually below so ONE bad
+    // entry is excluded + surfaced while the valid hooks in the same file survive
+    // (same discipline as the skills loader — never all-or-nothing).
+    if (json === null ||
+        typeof json !== "object" ||
+        !Array.isArray(json.hooks)) {
+        errors.push({
+            source,
+            file,
+            name: HOOKS_FILE_NAME,
+            message: 'hooks.json must be an object with a "hooks" array',
+        });
+        return;
+    }
+    const rawHooks = json.hooks;
+    const seen = new Set();
+    for (const [i, raw] of rawHooks.entries()) {
+        const label = raw &&
+            typeof raw === "object" &&
+            typeof raw.name === "string"
+            ? raw.name
+            : `entry #${i}`;
+        const parsed = HookSpecSchema.safeParse(raw);
+        if (!parsed.success) {
+            errors.push({
+                source,
+                file,
+                name: label,
+                message: `invalid hook: ${formatZod(parsed.error)}`,
+            });
+            continue;
+        }
+        const spec = parsed.data;
+        if (seen.has(spec.name)) {
+            errors.push({
+                source,
+                file,
+                name: spec.name,
+                message: `duplicate hook name "${spec.name}" within the ${source} source`,
+            });
+            continue;
+        }
+        seen.add(spec.name);
+        out.push({
+            name: spec.name,
+            event: spec.event,
+            command: spec.command,
+            blocking: spec.blocking ?? defaultBlocking(spec.event),
+            source,
+        });
+    }
+}
+// ── commands/*.md ─────────────────────────────────────────────────────────────
+async function scanCommandsDir(source, dir, out, errors) {
+    const commandsDir = path.join(dir, COMMANDS_DIR_NAME);
+    let entries;
+    try {
+        entries = await fs.readdir(commandsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            errors.push({
+                source,
+                file: commandsDir,
+                name: COMMANDS_DIR_NAME,
+                message: `could not read commands dir: ${err.message}`,
+            });
+        }
+        return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        const name = entry.name.slice(0, -".md".length);
+        const file = path.join(commandsDir, entry.name);
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+            errors.push({
+                source,
+                file,
+                name,
+                message: `command filename must be kebab-case: "${entry.name}"`,
+            });
+            continue;
+        }
+        let text;
+        try {
+            text = await fs.readFile(file, "utf8");
+        }
+        catch (err) {
+            errors.push({ source, file, name, message: err.message });
+            continue;
+        }
+        try {
+            out.push(parseCommand(text, name, source, file));
+        }
+        catch (err) {
+            errors.push({ source, file, name, message: err.message });
+        }
+    }
+}
+/** Parse + validate one `commands/<name>.md` into a {@link SlashCommandSpec}. */
+function parseCommand(text, name, source, file) {
+    const { raw, body } = splitFrontmatter(text);
+    const parsed = SlashFrontmatterSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`invalid frontmatter: ${formatZod(parsed.error)}`);
+    }
+    const fm = parsed.data;
+    if (fm.kind === "shell") {
+        if (!fm.command) {
+            throw new Error('a "shell" command requires a `command:` in frontmatter');
+        }
+        return {
+            name,
+            kind: "shell",
+            description: fm.description,
+            command: fm.command,
+            source,
+        };
+    }
+    // prompt (default): the markdown body IS the template.
+    const template = body.trim();
+    if (template === "") {
+        throw new Error('a "prompt" command needs a non-empty template body');
+    }
+    if (fm.command) {
+        throw new Error('a "prompt" command must not set `command:` (use kind: shell)');
+    }
+    void file;
+    return {
+        name,
+        kind: "prompt",
+        description: fm.description,
+        template,
+        source,
+    };
+}
+// ── shared helpers ────────────────────────────────────────────────────────────
+/**
+ * First occurrence of a name wins (candidates arrive in precedence order —
+ * project before user), so a project definition overrides a user one. A
+ * duplicate *within* a source was already reported by the scanner.
+ */
+function resolvePrecedence(candidates) {
+    const byName = new Map();
+    for (const c of candidates)
+        if (!byName.has(c.name))
+            byName.set(c.name, c);
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/;
+/** Split a `---`-delimited frontmatter block (flat `key: value` scalars) from
+ * the body. A strict, tiny YAML subset — anything else is a loud error. */
+function splitFrontmatter(text) {
+    if (!/^---[ \t]*\r?\n/.test(text)) {
+        throw new Error("must begin with a YAML frontmatter block delimited by '---'");
+    }
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match) {
+        throw new Error("frontmatter block is not terminated by a closing '---'");
+    }
+    const raw = {};
+    for (const rawLine of match[1].split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const colon = line.indexOf(":");
+        if (colon === -1) {
+            throw new Error(`invalid frontmatter line (expected "key: value"): ${JSON.stringify(rawLine)}`);
+        }
+        const key = line.slice(0, colon).trim();
+        if (key in raw)
+            throw new Error(`duplicate frontmatter key: ${JSON.stringify(key)}`);
+        raw[key] = stripQuotes(line.slice(colon + 1).trim());
+    }
+    return { raw, body: match[2] ?? "" };
+}
+function stripQuotes(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' || first === "'") && first === last) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+function formatZod(error) {
+    return error.issues
+        .map((i) => i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message)
+        .join("; ");
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,6 @@
+export { HOOK_EVENTS, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, HooksFileSchema, SlashFrontmatterSchema, defaultBlocking, type HookCatalog, type HookConfigError, type HookDefinition, type HookEvent, type HookSource, type HookSpec, type HookTrust, type SlashCommandSpec, type SlashKind, } from "./types.js";
+export { defaultHookSources, loadHookCatalog, type HookSources, } from "./config.js";
+export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPath, type TrustStore, } from "./trust.js";
+export { HookRunner, type HookRunnerDeps, type TrustPromptInfo, } from "./runner.js";
+export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, type SlashResolution, } from "./slash.js";
+export { buildHooksService, type BuildHooksServiceOptions, type HooksService, } from "./service.js";

package/dist/hooks/index.js

@@ -0,0 +1,6 @@
+export { HOOK_EVENTS, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, HooksFileSchema, SlashFrontmatterSchema, defaultBlocking, } from "./types.js";
+export { defaultHookSources, loadHookCatalog, } from "./config.js";
+export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPath, } from "./trust.js";
+export { HookRunner, } from "./runner.js";
+export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, } from "./slash.js";
+export { buildHooksService, } from "./service.js";

package/dist/hooks/runner.d.ts

@@ -0,0 +1,76 @@
+import type { ToolContext } from "../tools/types.js";
+import { type TrustStore } from "./trust.js";
+import type { HookDefinition, HookEvent } from "./types.js";
+/**
+ * The hook runner (C.19) — the security core. When a lifecycle event fires, it
+ * runs the matching user-authored hooks, but a hook is **never** an approval
+ * bypass:
+ *
+ * 1. **Project trust gate** (supply-chain safety). Before ANY project hook runs,
+ *    the repo must be trusted for its current hook fingerprint. Untrusted →
+ *    prompt (interactive) or `CRUXY_E_HOOK_UNTRUSTED` (non-interactive / declined
+ *    / `trustPrompt` off). A cloned repo's hooks never execute silently. User
+ *    hooks skip this prompt (you authored them) but NOT the gate below.
+ * 2. **Per-command gate + sandbox** — every hook command goes through the SAME
+ *    {@link runGatedShell} as `run_command`: the U.3 approval gate then the C.16
+ *    sandbox (or host). There is no privileged route.
+ * 3. **Blocking vs advisory** — a blocking hook that fails aborts the action
+ *    fail-closed (`CRUXY_E_HOOK_FAILED`); an advisory hook reports and continues.
+ */
+/** What the interactive trust prompt is shown. */
+export interface TrustPromptInfo {
+    root: string;
+    hooks: HookDefinition[];
+}
+export interface HookRunnerDeps {
+    /** Resolved hooks (with sources) for this project. */
+    hooks: HookDefinition[];
+    /** Persisted per-repo trust (see `trust.ts`). */
+    trust: TrustStore;
+    /** `config.hooks.enabled` — when false, nothing ever fires. */
+    enabled: boolean;
+    /** `config.hooks.trustPrompt` — when false, untrusted project hooks fail loud
+     * rather than prompting (never auto-trust). */
+    trustPrompt: boolean;
+    /** Whether cruxy can actually prompt (stdin is a TTY). */
+    interactive: boolean;
+    /** Project root — the trust key and fingerprint scope. */
+    cwd: string;
+    /** Interactive trust prompt (returns true to trust). Required only when a
+     * project defines hooks and `trustPrompt` + `interactive` are both on. */
+    promptTrust?: (info: TrustPromptInfo) => Promise<boolean>;
+    /** "running hook: <name>" surface (visible on every fire). */
+    announce?: (message: string) => void;
+    /** Advisory-failure surface (blocking failures throw instead). */
+    reportFailure?: (message: string) => void;
+    /** Injectable clock for the recorded trust timestamp (tests). */
+    now?: () => string;
+}
+export declare class HookRunner {
+    private readonly deps;
+    constructor(deps: HookRunnerDeps);
+    /** The project hooks — the trust-gated subset. */
+    private get projectHooks();
+    /**
+     * 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.
+     */
+    fire(event: HookEvent, ctx: ToolContext): Promise<void>;
+    /**
+     * 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).
+     */
+    private ensureProjectTrust;
+    /**
+     * 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.
+     */
+    private runOne;
+}