@cruxy/cli 0.13.0 → 0.16.0

package/dist/cli/repl.js

@@ -1,5 +1,7 @@
 import readline from "node:readline";
 import { makeReplCompleter } from "../components/index.js";
+import { resolveSlash } from "../hooks/index.js";
+import { runGatedShell } from "../tools/shell/exec.js";
 import { themeForColor } from "../theme/index.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { createRenderer } from "../render/index.js";
@@ -70,6 +72,35 @@ function readLine(io, prompt) {
         });
     });
 }
+/**
+ * Run a shell-bound custom slash command (C.19) through the SAME gated +
+ * sandboxed path as `run_command` (`runGatedShell` over the session's tool
+ * context) — never a privileged route. Prints the result like a shell run; a
+ * gate rejection or a thrown coded error (e.g. sandbox) is surfaced, not fatal.
+ */
+async function runSlashShell(spec, session) {
+    logger.print(theme.muted(`running /${spec.name}${theme.glyph.ellipsis}`));
+    try {
+        const outcome = await runGatedShell(spec.command ?? "", session.toolContext);
+        if (!outcome.approved) {
+            logger.print(theme.muted(outcome.rejection ?? "command denied by the user"));
+            return;
+        }
+        const e = outcome.exec;
+        if (e.timedOut) {
+            logger.print(theme.warning("timed out"));
+            return;
+        }
+        if (e.spawnError !== undefined) {
+            logger.print(theme.danger(e.spawnError));
+            return;
+        }
+        logger.print(`exit code ${e.exitCode ?? e.signal ?? "unknown"}\n${e.output}`);
+    }
+    catch (err) {
+        printReplError(err);
+    }
+}
 /**
  * Render a non-fatal error inline (classified + formatted, the same 4-part
  * shape as the fatal boundary) and return to the prompt — the REPL must survive
@@ -93,16 +124,16 @@ function printReplError(err) {
  * live region, anything else the plain append-only renderer); `cruxy run`
  * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export async function runInteractive(session, io = defaultIO(), renderer = createRenderer(io.output, process.stderr), checkpoints) {
+export async function runInteractive(session, io = defaultIO(), renderer = createRenderer(io.output, process.stderr), checkpoints, slashCommands = []) {
     logger.print(theme.muted("interactive session — /help for commands, /exit or Ctrl+D to quit"));
     try {
-        await replLoop(session, io, renderer, checkpoints);
+        await replLoop(session, io, renderer, checkpoints, slashCommands);
     }
     finally {
         renderer.close();
     }
 }
-async function replLoop(session, io, renderer, checkpoints) {
+async function replLoop(session, io, renderer, checkpoints, slashCommands = []) {
     for (;;) {
         const line = await readLine(io, PROMPT);
         // EOF / Ctrl+D.
@@ -151,6 +182,26 @@ async function replLoop(session, io, renderer, checkpoints) {
             logger.print(HELP);
             continue;
         }
+        // Custom slash commands (C.19) — consulted AFTER builtins, so a custom
+        // command can never shadow /help, /exit, etc. A `prompt` command expands to
+        // text fed to the agent (safe); a `shell` command runs through the SAME
+        // gate + sandbox as any command (never a bypass). Unknown "/…" input falls
+        // through to a normal turn, preserving prior behavior.
+        const slash = resolveSlash(trimmed, slashCommands);
+        if (slash.kind === "prompt") {
+            try {
+                checkpoints?.beginRun(slash.prompt);
+                await session.send(slash.prompt, renderer);
+            }
+            catch (err) {
+                printReplError(err);
+            }
+            continue;
+        }
+        if (slash.kind === "shell") {
+            await runSlashShell(slash.spec, session);
+            continue;
+        }
         // A real turn. Assistant text streams through the renderer delta by delta
         // (leading blank lines trimmed, code fences highlighted); the agent loop
         // closes each segment with one newline, so the next prompt lands on its own

package/dist/cli/session-factory.d.ts

@@ -4,7 +4,7 @@ import type { CheckpointService } from "../checkpoint/index.js";
 import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
 import { type ApproveAction } from "../tools/index.js";
-import { Session } from "../agent/index.js";
+import { Session, type LifecycleHookRunner } from "../agent/index.js";
 /**
  * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
  * whole point: a tool mutates only *after* `requestApproval` resolves, so
@@ -24,4 +24,4 @@ export declare function withCheckpointGate(requestApproval: (action: ApproveActi
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService, hooks?: LifecycleHookRunner): Session;

package/dist/cli/session-factory.js

@@ -5,7 +5,7 @@ import { getGitInfo } from "../utils/git.js";
 import { ApprovalService, InteractivePolicy, SessionAllowlist, classify, defaultPromptIO, } from "../approval/index.js";
 import { shouldUseColor } from "../errors/index.js";
 import { buildDefaultRegistry } from "../tools/index.js";
-import { Session } from "../agent/index.js";
+import { Session, } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
 import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
 /**
@@ -87,7 +87,7 @@ export function withCheckpointGate(requestApproval, checkpoints, cwd) {
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints, sandbox) {
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints, sandbox, hooks) {
     const provider = createProvider({
         provider: config.model.provider,
         apiKey,
@@ -166,6 +166,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             projectInstructions,
             planMode: true,
             planRunner,
+            hooks,
         });
     }
     const approval = new ApprovalService({
@@ -181,5 +182,6 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         ctx,
         git,
         projectInstructions,
+        hooks,
     });
 }

package/dist/components/fuzzy.js

@@ -106,7 +106,9 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
             lines.push(t.heading(opts.title));
         lines.push(`${t.accent(g.caret)} ${query}${t.muted(g.cursorBar)}`);
         if (ranked.length === 0) {
-            lines.push(t.muted("  no results — backspace to widen"));
+            // No dead-end: the only escapes (backspace, esc) stay advertised even
+            // when nothing matches — the user is never stranded with no visible exit.
+            lines.push(t.muted("  no results — backspace to widen · esc cancel"));
         }
         else {
             // Keep the highlighted row inside the viewport.
@@ -122,6 +124,10 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
             if (hidden > 0)
                 lines.push(t.muted(`  ${g.ellipsis} ${hidden} more`));
         }
+        // Persistent key hint (U.11 keyboard-completeness): every operable key is
+        // advertised, mirroring selectList — type filters, arrows move, enter
+        // selects, esc cancels. Present in both the results and no-results states.
+        lines.push(t.muted(`  type to filter ${g.sep} ${g.caretUp}/${g.caretDown} move ${g.sep} enter select ${g.sep} esc cancel`));
         frame.render(lines);
     };
     io.keys.begin();

package/dist/config/schema.d.ts

@@ -339,6 +339,32 @@ export declare const SandboxConfigSchema: z.ZodObject<{
     mounts?: string[] | undefined;
 }>;
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
+/**
+ * Hooks + custom slash commands (C.19). Hooks run user-authored shell commands
+ * on lifecycle events — a real execution surface — so they are OFF by default
+ * and, when on, still funnel through the SAME U.3 gate + C.16 sandbox as any
+ * agent command (never a bypass). The hook *definitions* live in layered
+ * `hooks.json` files (project > user, source-tracked for the trust model); this
+ * schema holds only the global toggles.
+ */
+export declare const HooksConfigSchema: z.ZodObject<{
+    /** Master switch. When false, NO hook ever fires (config with hooks stays
+     * inert until explicitly enabled). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Whether to interactively prompt to trust a project's hooks the first time
+     * they would run. When false, untrusted project hooks fail loud
+     * (CRUXY_E_HOOK_UNTRUSTED) instead of prompting — never auto-trust.
+     */
+    trustPrompt: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    enabled: boolean;
+    trustPrompt: boolean;
+}, {
+    enabled?: boolean | undefined;
+    trustPrompt?: boolean | undefined;
+}>;
+export type HooksConfig = z.infer<typeof HooksConfigSchema>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -654,6 +680,23 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         timeout?: number | undefined;
         mounts?: string[] | undefined;
     }>>;
+    hooks: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When false, NO hook ever fires (config with hooks stays
+         * inert until explicitly enabled). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Whether to interactively prompt to trust a project's hooks the first time
+         * they would run. When false, untrusted project hooks fail loud
+         * (CRUXY_E_HOOK_UNTRUSTED) instead of prompting — never auto-trust.
+         */
+        trustPrompt: z.ZodDefault<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        trustPrompt: boolean;
+    }, {
+        enabled?: boolean | undefined;
+        trustPrompt?: boolean | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -672,6 +715,23 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy: {
         gatewayUrl: string;
     };
+    checkpoint: {
+        enabled: boolean;
+        retention: number;
+    };
+    sandbox: {
+        image: string;
+        enabled: boolean;
+        memory: string;
+        network: "none" | "host-loopback" | "full";
+        pids: number;
+        cpus: number;
+        mounts: string[];
+        timeout?: number | undefined;
+    };
+    approval: {
+        mode: "prompt";
+    };
     model: {
         provider: "cruxy" | "anthropic" | "openai" | "custom";
         model: string;
@@ -702,9 +762,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         compactThreshold: number;
         keepRecentMessages: number;
     };
-    approval: {
-        mode: "prompt";
-    };
     index: {
         search: {
             defaultK: number;
@@ -720,10 +777,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines: number;
         };
     };
-    checkpoint: {
-        enabled: boolean;
-        retention: number;
-    };
     subagent: {
         maxDepth: number;
         defaultBudget: {
@@ -737,15 +790,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         captureBytes: number;
         command?: string | undefined;
     };
-    sandbox: {
-        image: string;
+    hooks: {
         enabled: boolean;
-        memory: string;
-        network: "none" | "host-loopback" | "full";
-        pids: number;
-        cpus: number;
-        mounts: string[];
-        timeout?: number | undefined;
+        trustPrompt: boolean;
     };
     mcpServers: Record<string, {
         command?: string | undefined;
@@ -757,6 +804,23 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy?: {
         gatewayUrl?: string | undefined;
     } | undefined;
+    checkpoint?: {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+    } | undefined;
+    sandbox?: {
+        image?: string | undefined;
+        enabled?: boolean | undefined;
+        memory?: string | undefined;
+        network?: "none" | "host-loopback" | "full" | undefined;
+        pids?: number | undefined;
+        cpus?: number | undefined;
+        timeout?: number | undefined;
+        mounts?: string[] | undefined;
+    } | undefined;
+    approval?: {
+        mode?: "prompt" | undefined;
+    } | undefined;
     model?: {
         provider?: "cruxy" | "anthropic" | "openai" | "custom" | undefined;
         model?: string | undefined;
@@ -787,9 +851,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         compactThreshold?: number | undefined;
         keepRecentMessages?: number | undefined;
     } | undefined;
-    approval?: {
-        mode?: "prompt" | undefined;
-    } | undefined;
     index?: {
         search?: {
             defaultK?: number | undefined;
@@ -805,10 +866,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     } | undefined;
-    checkpoint?: {
-        enabled?: boolean | undefined;
-        retention?: number | undefined;
-    } | undefined;
     subagent?: {
         maxDepth?: number | undefined;
         defaultBudget?: {
@@ -822,15 +879,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         command?: string | undefined;
         captureBytes?: number | undefined;
     } | undefined;
-    sandbox?: {
-        image?: string | undefined;
+    hooks?: {
         enabled?: boolean | undefined;
-        memory?: string | undefined;
-        network?: "none" | "host-loopback" | "full" | undefined;
-        pids?: number | undefined;
-        cpus?: number | undefined;
-        timeout?: number | undefined;
-        mounts?: string[] | undefined;
+        trustPrompt?: boolean | undefined;
     } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;

package/dist/config/schema.js

@@ -233,6 +233,27 @@ export const SandboxConfigSchema = z
     mounts: z.array(z.string().min(1)).default([]),
 })
     .strict();
+/**
+ * Hooks + custom slash commands (C.19). Hooks run user-authored shell commands
+ * on lifecycle events — a real execution surface — so they are OFF by default
+ * and, when on, still funnel through the SAME U.3 gate + C.16 sandbox as any
+ * agent command (never a bypass). The hook *definitions* live in layered
+ * `hooks.json` files (project > user, source-tracked for the trust model); this
+ * schema holds only the global toggles.
+ */
+export const HooksConfigSchema = z
+    .object({
+    /** Master switch. When false, NO hook ever fires (config with hooks stays
+     * inert until explicitly enabled). */
+    enabled: z.boolean().default(false),
+    /**
+     * Whether to interactively prompt to trust a project's hooks the first time
+     * they would run. When false, untrusted project hooks fail loud
+     * (CRUXY_E_HOOK_UNTRUSTED) instead of prompting — never auto-trust.
+     */
+    trustPrompt: z.boolean().default(true),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -256,6 +277,7 @@ export const CruxyConfigSchema = z
     subagent: SubagentConfigSchema.default({}),
     test: TestConfigSchema.default({}),
     sandbox: SandboxConfigSchema.default({}),
+    hooks: HooksConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/constants.d.ts

@@ -21,6 +21,15 @@ export declare const PROJECT_INSTRUCTION_FILENAMES: string[];
  * root for shipped builtins.
  */
 export declare const SKILLS_DIR_NAME = "skills";
+/** Hook definitions file, under the project dir (`<cwd>/.cruxy/hooks.json`) and
+ * the global dir (`~/.cruxy/hooks.json`). Pure data, validated, never eval'd (C.19). */
+export declare const HOOKS_FILE_NAME = "hooks.json";
+/** Custom slash-command directory (`<cwd>/.cruxy/commands`, `~/.cruxy/commands`);
+ * one `<name>.md` per command (frontmatter + template body), mirroring skills. */
+export declare const COMMANDS_DIR_NAME = "commands";
+/** Per-repo hook-trust record, in the GLOBAL dir only (`~/.cruxy/trust.json`) —
+ * never in a repo, so cloning carries no trust (C.19 supply-chain safety). */
+export declare const TRUST_FILE_NAME = "trust.json";
 /**
  * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
  * Anchored the same way as the package.json lookup above: both `dist/` and

package/dist/constants.js

@@ -41,6 +41,15 @@ export const PROJECT_INSTRUCTION_FILENAMES = ["CRUXY.md", "AGENTS.md"];
  * root for shipped builtins.
  */
 export const SKILLS_DIR_NAME = "skills";
+/** Hook definitions file, under the project dir (`<cwd>/.cruxy/hooks.json`) and
+ * the global dir (`~/.cruxy/hooks.json`). Pure data, validated, never eval'd (C.19). */
+export const HOOKS_FILE_NAME = "hooks.json";
+/** Custom slash-command directory (`<cwd>/.cruxy/commands`, `~/.cruxy/commands`);
+ * one `<name>.md` per command (frontmatter + template body), mirroring skills. */
+export const COMMANDS_DIR_NAME = "commands";
+/** Per-repo hook-trust record, in the GLOBAL dir only (`~/.cruxy/trust.json`) —
+ * never in a repo, so cloning carries no trust (C.19 supply-chain safety). */
+export const TRUST_FILE_NAME = "trust.json";
 /**
  * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
  * Anchored the same way as the package.json lookup above: both `dist/` and

package/dist/errors/constructors.d.ts

@@ -46,6 +46,22 @@ export declare function sandboxImage(image: string, underlying?: unknown): Cruxy
  * can't launch is never papered over with a host run.
  */
 export declare function sandboxExec(underlying?: unknown): CruxyError;
+/**
+ * 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 declare function hookFailed(name: string, reason: string, underlying?: unknown): CruxyError;
+/**
+ * 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 declare function hookUntrusted(root: string, count: number): CruxyError;
+/** A malformed hook definition — excluded from the catalog, never eval'd. */
+export declare function hookInvalid(reason: string, source?: string): CruxyError;
+/** A malformed custom slash-command definition — excluded and surfaced. */
+export declare function slashInvalid(reason: string, source?: string): CruxyError;
 /**
  * A side-effecting action needs approval but cruxy can't ask (non-interactive,
  * no policy). Default-deny — never auto-approve. A distinct exit code (10) so CI

package/dist/errors/constructors.js

@@ -282,6 +282,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

@@ -57,6 +57,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

@@ -70,6 +70,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
@@ -123,6 +135,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>;