@cruxy/cli 0.14.0 → 0.17.0

package/dist/cli/commands/run.js

@@ -6,12 +6,13 @@ import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { CheckpointService } from "../../checkpoint/index.js";
 import { SandboxService } from "../../sandbox/index.js";
+import { buildHooksService } from "../../hooks/index.js";
 import { runInteractive } from "../repl.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 export function runCommand() {
     return new Command("run")
-        .description("run cruxy on a prompt (one-shot), or with no prompt for an interactive session")
+        .description("run a task once, or start an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
         .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
         .option("--sandbox", "run shell + test commands inside an isolated container (fails loud if no runtime)")
@@ -79,9 +80,18 @@ export function runCommand() {
         if (sandbox) {
             logger.info(t.muted(`sandbox: ${sandbox.runtimeName} (network ${config.sandbox.network})`));
         }
-        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox);
+        // Hooks + custom slash commands (C.19). Built once per run: loads the
+        // layered catalog and yields the lifecycle runner (threaded into the
+        // session) + the resolved custom slash commands (given to the REPL).
+        const hooksService = await buildHooksService({
+            cwd: process.cwd(),
+            config,
+            interactive: Boolean(process.stdin.isTTY),
+            logger,
+        });
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksService.runner);
         if (interactive) {
-            await runInteractive(session, undefined, renderer, checkpoints);
+            await runInteractive(session, undefined, renderer, checkpoints, hooksService.commands);
             return;
         }
         checkpoints?.beginRun(prompt);

package/dist/cli/commands/skills.js

@@ -33,9 +33,9 @@ export function skillsCommand() {
             resetSkillServices();
             return;
         }
-        logger.print(`\n${t.strong("sources")} ${t.muted("(precedence high → low):")}`);
+        logger.print(`\n${t.heading("sources")} ${t.muted("(precedence, high to low)")}`);
         for (const { source, dir } of status.sources) {
-            logger.print(`  ${source.padEnd(8)} ${t.muted(dir)}`);
+            logger.print(`  ${t.kv(source, t.muted(dir), 8)}`);
         }
         logger.print("");
         if (status.errors.length === 0) {

package/dist/cli/program.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
-import { APP_NAME, APP_VERSION, APP_DESCRIPTION } from "../constants.js";
+import { APP_NAME, APP_VERSION } from "../constants.js";
+import { PRODUCT_MASTHEAD } from "../brand/index.js";
 import { logger } from "../utils/logger.js";
 import { shouldUseColor, usageError } from "../errors/index.js";
 import { themeForColor } from "../theme/index.js";
@@ -13,13 +14,14 @@ import { initCommand } from "./commands/init.js";
 import { checkpointCommand } from "./commands/checkpoint.js";
 import { rollbackCommand } from "./commands/rollback.js";
 import { testCommand } from "./commands/test.js";
+import { hooksCommand } from "./commands/hooks.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
     const program = new Command();
     program
         .name(APP_NAME)
-        .description(`cruxy-code — ${APP_DESCRIPTION}`)
+        .description(PRODUCT_MASTHEAD)
         .version(APP_VERSION, "-v, --version", "print the cruxy version")
         .option("-c, --config <path>", "use a specific config file")
         .option("--log-level <level>", "debug | info | warn | error | silent")
@@ -42,6 +44,7 @@ export function buildProgram() {
     program.addCommand(checkpointCommand());
     program.addCommand(rollbackCommand());
     program.addCommand(testCommand());
+    program.addCommand(hooksCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.

package/dist/cli/repl.d.ts

@@ -1,6 +1,7 @@
 import type { Readable, Writable } from "node:stream";
 import type { Session } from "../agent/index.js";
 import type { CheckpointService } from "../checkpoint/index.js";
+import { type SlashCommandSpec } from "../hooks/index.js";
 import { type StreamRenderer } from "../render/index.js";
 /**
  * The REPL's slash commands — the autocomplete candidate set (U.7). Keep in
@@ -23,4 +24,4 @@ export interface ReplIO {
  * 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 declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer, checkpoints?: CheckpointService): Promise<void>;
+export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer, checkpoints?: CheckpointService, slashCommands?: readonly SlashCommandSpec[]): Promise<void>;

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,8 +5,9 @@ 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 { routerForConfig } from "../routing/index.js";
 import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
 /**
  * Wrap a PromptIO so the live region yields before any prompt text lands
@@ -87,7 +88,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,
@@ -96,6 +97,10 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         temperature: config.model.temperature,
         gatewayUrl: config.cruxy.gatewayUrl,
     });
+    // Multi-model routing (C.30): null unless routing is configured on a cruxy
+    // session, so the default path threads `undefined` and behaves exactly as
+    // before. One router is shared by the main loop, subagents, and plan mode.
+    const router = routerForConfig(config) ?? undefined;
     const execRegistry = buildDefaultRegistry();
     const git = getGitInfo(cwd);
     const projectInstructions = loadProjectInstructions(cwd);
@@ -114,6 +119,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     const orchestrator = new SubagentOrchestrator({
         provider,
         config,
+        router,
         parentRegistry: execRegistry,
         cwd,
         logger,
@@ -156,6 +162,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             git,
             projectInstructions,
             renderer: turnRenderer,
+            router,
         });
         return new Session({
             provider,
@@ -166,6 +173,8 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             projectInstructions,
             planMode: true,
             planRunner,
+            hooks,
+            router,
         });
     }
     const approval = new ApprovalService({
@@ -181,5 +190,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         ctx,
         git,
         projectInstructions,
+        hooks,
+        router,
     });
 }

package/dist/config/schema.d.ts

@@ -339,6 +339,53 @@ 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>;
+/**
+ * Multi-model routing (C.30): map declared task classes to tiers so mechanical
+ * work runs on a cheap tier and hard reasoning on a strong one. Fully opt-in —
+ * with an empty `map` and no `default`, every task class routes to the session's
+ * single tier and behavior is unchanged (routing stays inert until configured).
+ * Only tier names appear here; upstream model names never do (U.8). Keys are the
+ * fixed {@link TASK_CLASSES}, so a mistyped class is rejected at config load.
+ */
+export declare const RoutingConfigSchema: z.ZodObject<{
+    /** Tier for any task class not in `map`. Unset → the tier implied by
+     * `model.model` (a real tier, or the auto-fallback tier). */
+    default: z.ZodOptional<z.ZodEnum<["kavi", "vaani", "mira"]>>;
+    /** Per-task-class tier overrides; anything omitted takes `default`. */
+    map: z.ZodDefault<z.ZodRecord<z.ZodEnum<["main-turn", "subagent", "plan", "commit-msg", "classify", "summarize"]>, z.ZodEnum<["kavi", "vaani", "mira"]>>>;
+}, "strict", z.ZodTypeAny, {
+    map: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">>;
+    default?: "kavi" | "vaani" | "mira" | undefined;
+}, {
+    map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
+    default?: "kavi" | "vaani" | "mira" | undefined;
+}>;
 /** 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 +701,36 @@ 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;
+    }>>;
+    routing: z.ZodDefault<z.ZodObject<{
+        /** Tier for any task class not in `map`. Unset → the tier implied by
+         * `model.model` (a real tier, or the auto-fallback tier). */
+        default: z.ZodOptional<z.ZodEnum<["kavi", "vaani", "mira"]>>;
+        /** Per-task-class tier overrides; anything omitted takes `default`. */
+        map: z.ZodDefault<z.ZodRecord<z.ZodEnum<["main-turn", "subagent", "plan", "commit-msg", "classify", "summarize"]>, z.ZodEnum<["kavi", "vaani", "mira"]>>>;
+    }, "strict", z.ZodTypeAny, {
+        map: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">>;
+        default?: "kavi" | "vaani" | "mira" | undefined;
+    }, {
+        map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
+        default?: "kavi" | "vaani" | "mira" | 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 +749,31 @@ 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";
+    };
+    subagent: {
+        maxDepth: number;
+        defaultBudget: {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        };
+    };
     model: {
         provider: "cruxy" | "anthropic" | "openai" | "custom";
         model: string;
@@ -702,9 +804,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         compactThreshold: number;
         keepRecentMessages: number;
     };
-    approval: {
-        mode: "prompt";
-    };
     index: {
         search: {
             defaultK: number;
@@ -720,32 +819,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines: number;
         };
     };
-    checkpoint: {
-        enabled: boolean;
-        retention: number;
-    };
-    subagent: {
-        maxDepth: number;
-        defaultBudget: {
-            maxTokens: number;
-            maxIterations: number;
-            timeoutMs?: number | undefined;
-        };
-    };
     test: {
         maxIterations: number;
         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;
+    };
+    routing: {
+        map: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">>;
+        default?: "kavi" | "vaani" | "mira" | undefined;
     };
     mcpServers: Record<string, {
         command?: string | undefined;
@@ -757,6 +842,31 @@ 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;
+    subagent?: {
+        maxDepth?: number | undefined;
+        defaultBudget?: {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        } | undefined;
+    } | undefined;
     model?: {
         provider?: "cruxy" | "anthropic" | "openai" | "custom" | undefined;
         model?: string | undefined;
@@ -787,9 +897,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,32 +912,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     } | undefined;
-    checkpoint?: {
-        enabled?: boolean | undefined;
-        retention?: number | undefined;
-    } | undefined;
-    subagent?: {
-        maxDepth?: number | undefined;
-        defaultBudget?: {
-            maxTokens?: number | undefined;
-            maxIterations?: number | undefined;
-            timeoutMs?: number | undefined;
-        } | undefined;
-    } | undefined;
     test?: {
         maxIterations?: number | undefined;
         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;
+    routing?: {
+        map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
+        default?: "kavi" | "vaani" | "mira" | undefined;
     } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;

package/dist/config/schema.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { LOG_LEVELS } from "../utils/logger.js";
+import { MODEL_TIERS } from "../brand/voice.js";
+import { TASK_CLASSES } from "../routing/types.js";
 export const ProviderSchema = z.enum([
     "cruxy",
     "anthropic",
@@ -233,6 +235,44 @@ 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();
+/**
+ * Multi-model routing (C.30): map declared task classes to tiers so mechanical
+ * work runs on a cheap tier and hard reasoning on a strong one. Fully opt-in —
+ * with an empty `map` and no `default`, every task class routes to the session's
+ * single tier and behavior is unchanged (routing stays inert until configured).
+ * Only tier names appear here; upstream model names never do (U.8). Keys are the
+ * fixed {@link TASK_CLASSES}, so a mistyped class is rejected at config load.
+ */
+export const RoutingConfigSchema = z
+    .object({
+    /** Tier for any task class not in `map`. Unset → the tier implied by
+     * `model.model` (a real tier, or the auto-fallback tier). */
+    default: z.enum(MODEL_TIERS).optional(),
+    /** Per-task-class tier overrides; anything omitted takes `default`. */
+    map: z.record(z.enum(TASK_CLASSES), z.enum(MODEL_TIERS)).default({}),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -256,6 +296,8 @@ export const CruxyConfigSchema = z
     subagent: SubagentConfigSchema.default({}),
     test: TestConfigSchema.default({}),
     sandbox: SandboxConfigSchema.default({}),
+    hooks: HooksConfigSchema.default({}),
+    routing: RoutingConfigSchema.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

@@ -11,6 +11,15 @@ export declare function usageError(title: string, nextSteps?: string[]): CruxyEr
 export declare function interactiveRequired(what: string, alternatives?: string[]): CruxyError;
 export declare function configKeyUnknown(key: string): CruxyError;
 export declare function providerUnsupported(provider: string): CruxyError;
+/**
+ * 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 declare function routingTierUnavailable(tier: string, taskClass: string, offered: string[]): CruxyError;
 export declare function configParse(path: string, underlying?: unknown): CruxyError;
 export declare function configInvalid(issues: string, path?: string): CruxyError;
 export declare function authMissingKey(provider: string, envVar: string): CruxyError;
@@ -46,6 +55,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