@cruxy/cli 0.14.0 → 0.17.0

package/dist/agent/loop.d.ts

@@ -1,8 +1,16 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
+import type { HookEvent } from "../hooks/index.js";
 import type { StreamRenderer } from "../render/index.js";
+import { type Router, type TaskClass } from "../routing/index.js";
 import type { ToolContext } from "../tools/index.js";
 import { ToolRegistry } from "../tools/index.js";
+/** The lifecycle-hook firing seam (C.19). Structural so the loop stays
+ * decoupled from the concrete `HookRunner`. `fire` resolves when hooks pass (or
+ * advisory ones fail) and throws `CRUXY_E_HOOK_FAILED` on a blocking failure. */
+export interface LifecycleHookRunner {
+    fire(event: HookEvent, ctx: ToolContext): Promise<void>;
+}
 export interface RunAgentArgs {
     /**
      * The full running conversation. The caller owns history and must append the
@@ -43,6 +51,24 @@ export interface RunAgentArgs {
      * histories stay coherent — overshoot is bounded by one turn.
      */
     budget?: LoopBudget;
+    /**
+     * Lifecycle hooks (C.19). When set, `before-tool` fires before each tool call
+     * (a blocking failure fails the call closed — the tool does NOT run), and
+     * `after-tool` / `on-file-change` fire after. Omitted for subagents and the
+     * no-hooks path, so their tools never fire hooks.
+     */
+    hooks?: LifecycleHookRunner;
+    /**
+     * Multi-model routing (C.30): when set, the tier for `taskClass` is resolved
+     * ONCE up front (fail loud before any model turn) and its wire model overrides
+     * the provider default for every turn in this run; the tier is surfaced on the
+     * live line. Omitted → no override, the provider's default model is used
+     * (unchanged behavior).
+     */
+    router?: Router;
+    /** The declared task class for routing; defaults to `main-turn`. Ignored
+     * unless `router` is set. */
+    taskClass?: TaskClass;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps

package/dist/agent/loop.js

@@ -1,5 +1,9 @@
-import { providerUnsupported } from "../errors/index.js";
+import { CruxyError, providerUnsupported } from "../errors/index.js";
+import { resolveTaskModel, } from "../routing/index.js";
 import { buildSystemPrompt } from "./prompts.js";
+/** Tools whose successful call is a file change (drives the `on-file-change`
+ * hook). Kept in sync with the file-mutating tool set. */
+const FILE_MUTATING_TOOLS = new Set(["write_file", "edit_file", "apply_patch"]);
 /**
  * Drive the model/tool loop over an existing conversation. Streams each turn,
  * renders assistant text, reassembles tool calls, executes them, feeds the
@@ -14,9 +18,16 @@ export async function runAgent(args) {
     if (!provider.supportsTools) {
         throw providerUnsupported(config.model.provider);
     }
+    // Resolve the routing tier ONCE, before any model turn (C.30). A tier the
+    // gateway does not offer throws CRUXY_E_ROUTING_TIER_UNAVAILABLE here — so a
+    // misrouted run never reaches provider.stream (no request sent with the wrong
+    // tier), and never silently falls back to a different one.
+    const routed = args.router
+        ? resolveTaskModel(args.router, args.taskClass ?? "main-turn")
+        : null;
     renderer?.beginTurn();
     try {
-        return await driveLoop(args, renderer);
+        return await driveLoop(args, renderer, routed);
     }
     finally {
         // Always leave the terminal clean: no orphaned status line, no held text —
@@ -25,7 +36,7 @@ export async function runAgent(args) {
     }
 }
 /** The body of {@link runAgent}, split out so turn cleanup lives in one finally. */
-async function driveLoop(args, renderer) {
+async function driveLoop(args, renderer, routed) {
     const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
@@ -77,11 +88,13 @@ async function driveLoop(args, renderer) {
             tokens: usage.input_tokens + usage.output_tokens > 0
                 ? { input: usage.input_tokens, output: usage.output_tokens }
                 : undefined,
+            tier: routed?.tier,
         });
         for await (const ev of provider.stream({
             system,
             messages,
             tools,
+            ...(routed ? { model: routed.model } : {}),
         })) {
             switch (ev.type) {
                 case "text_delta":
@@ -146,9 +159,26 @@ async function driveLoop(args, renderer) {
             // long calls), end commits the ✓/✗ trail note. Same information as the
             // old status/note pair, now typed and duration-aware.
             renderer?.toolLifecycle({ event: "start", label });
+            // before-tool (C.19): a blocking pre-check that fails aborts THIS tool
+            // fail-closed — the tool never runs; the model is told via an error
+            // result. The hook command itself went through the U.3 gate + C.16 sandbox
+            // (same path as run_command), so a hook is never an approval bypass.
+            const blocked = await fireBeforeTool(args.hooks, ctx, call.id);
+            if (blocked) {
+                renderer?.toolLifecycle({ event: "end", label, ok: false });
+                toolResults.push(blocked);
+                continue;
+            }
             const result = await runToolCall(call, registry, ctx);
             renderer?.toolLifecycle({ event: "end", label, ok: !result.is_error });
             toolResults.push(result);
+            // after-tool + on-file-change (C.19): fire once the action is done.
+            // Advisory by default (report, don't rewrite history); a hook explicitly
+            // marked blocking here throws and aborts the run.
+            await args.hooks?.fire("after-tool", ctx);
+            if (!result.is_error && FILE_MUTATING_TOOLS.has(call.name)) {
+                await args.hooks?.fire("on-file-change", ctx);
+            }
         }
         messages.push({ role: "user", content: toolResults });
     }
@@ -192,6 +222,32 @@ function describeToolCall(call) {
  * results rather than thrown exceptions, so the model can read the error and
  * self-correct on the next turn.
  */
+/**
+ * Fire `before-tool` hooks. Returns `null` to proceed, or a ready-made error
+ * {@link ToolResultBlock} when a blocking hook failed — the tool is then skipped
+ * (fail-closed) and the model is told, carrying the CRUXY_E_HOOK_FAILED code so
+ * the failure is greppable. A non-blocking (advisory) hook failure never reaches
+ * here — the runner reports it and resolves normally.
+ */
+async function fireBeforeTool(hooks, ctx, toolUseId) {
+    if (!hooks)
+        return null;
+    try {
+        await hooks.fire("before-tool", ctx);
+        return null;
+    }
+    catch (err) {
+        const content = CruxyError.is(err)
+            ? `${err.code}: ${err.title}${err.cause ? ` — ${err.cause}` : ""}`
+            : `before-tool hook failed: ${err.message}`;
+        return {
+            type: "tool_result",
+            tool_use_id: toolUseId,
+            content,
+            is_error: true,
+        };
+    }
+}
 async function runToolCall(call, registry, ctx) {
     const tool = registry.get(call.name);
     if (!tool) {

package/dist/agent/session.d.ts

@@ -1,9 +1,10 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
 import type { StreamRenderer } from "../render/index.js";
+import { type Router } from "../routing/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
-import { type AgentResult } from "./loop.js";
+import { type AgentResult, type LifecycleHookRunner } from "./loop.js";
 /**
  * Plan-mode turn runner (C.31), injected so the agent package doesn't depend on
  * the plan package. When plan mode is on, `send` delegates the whole turn to
@@ -35,6 +36,18 @@ export interface SessionArgs {
     planMode?: boolean;
     /** The plan-mode turn runner; required for plan mode to actually engage. */
     planRunner?: PlanRunner;
+    /**
+     * Lifecycle hooks (C.19). When set, `before-run` fires before each turn (a
+     * blocking failure — including an untrusted project — aborts the turn) and
+     * `after-run` fires after; the same runner is threaded into the agent loop for
+     * `before-tool`/`after-tool`/`on-file-change`.
+     */
+    hooks?: LifecycleHookRunner;
+    /**
+     * Multi-model routing (C.30). When set, main turns route on `main-turn` and
+     * context compaction on `summarize`; omitted → the provider default (unchanged).
+     */
+    router?: Router;
 }
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -65,6 +78,9 @@ export declare class Session {
     /** Mutable so `/plan` can toggle plan mode mid-session. */
     private planMode;
     constructor(args: SessionArgs);
+    /** The ambient tool capabilities (gate + sandbox + cwd/config). Exposed so a
+     * shell-bound custom slash command (C.19) runs through the SAME gated path. */
+    get toolContext(): ToolContext;
     /** Whether plan mode is currently on. */
     getPlanMode(): boolean;
     /**

package/dist/agent/session.js

@@ -1,5 +1,6 @@
 import { loadProjectInstructions } from "../config/index.js";
-import { runAgent } from "./loop.js";
+import { resolveTaskModel } from "../routing/index.js";
+import { runAgent, } from "./loop.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -58,6 +59,11 @@ export class Session {
         // state where the plan directive is injected but nothing orchestrates it).
         this.planMode = (args.planMode ?? false) && args.planRunner !== undefined;
     }
+    /** The ambient tool capabilities (gate + sandbox + cwd/config). Exposed so a
+     * shell-bound custom slash command (C.19) runs through the SAME gated path. */
+    get toolContext() {
+        return this.args.ctx;
+    }
     /** Whether plan mode is currently on. */
     getPlanMode() {
         return this.planMode;
@@ -82,6 +88,10 @@ export class Session {
         this.messages.push({ role: "user", content: userPrompt });
         // Compact *before* the agent call so the turn runs against a bounded history.
         await this.maybeCompact();
+        // before-run (C.19): a blocking pre-run hook — or an untrusted project's
+        // hooks — throws here and aborts the turn before the model is engaged
+        // (fail-closed). No-op when hooks are disabled or none are registered.
+        await this.args.hooks?.fire("before-run", this.args.ctx);
         // Plan mode (C.31) delegates the whole turn to the injected runner: propose a
         // plan, approve/revise, then execute step-by-step. Falls back to the normal
         // single-shot loop when off or unwired, so existing behavior is untouched.
@@ -93,7 +103,8 @@ export class Session {
             })
             : await runAgent({
                 messages: this.messages,
-                ...this.args,
+                ...this.args, // carries `router` through to the loop
+                taskClass: "main-turn",
                 // After the spread so a mid-session `/reload` wins over the initial value.
                 projectInstructions: this.projectInstructions,
                 planMode: false, // the plan directive belongs only to the runner's propose phase
@@ -102,6 +113,10 @@ export class Session {
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
         this.usage.output_tokens += result.usage.output_tokens;
+        // after-run (C.19): advisory by default (a blocking after-run hook throws
+        // and surfaces at the boundary). The turn already completed and its history
+        // is adopted above — an advisory failure never rewrites it.
+        await this.args.hooks?.fire("after-run", this.args.ctx);
         return result;
     }
     /**
@@ -213,9 +228,15 @@ export class Session {
         const transcript = renderTranscript(prefix);
         const usage = { input_tokens: 0, output_tokens: 0 };
         let text = "";
+        // Compaction is mechanical work — route it on `summarize` (C.30) when routing
+        // is active; omitted → the provider default, unchanged.
+        const routed = this.args.router
+            ? resolveTaskModel(this.args.router, "summarize")
+            : null;
         for await (const ev of this.args.provider.stream({
             system: SUMMARY_SYSTEM,
             messages: [{ role: "user", content: transcript }],
+            ...(routed ? { model: routed.model } : {}),
         })) {
             switch (ev.type) {
                 case "text_delta":

package/dist/brand/index.d.ts

@@ -0,0 +1 @@
+export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_NAME_PLACEHOLDER, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, scrubModelNames, type ForbiddenTerm, type LexiconViolation, } from "./voice.js";

package/dist/brand/index.js

@@ -0,0 +1 @@
+export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_NAME_PLACEHOLDER, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, scrubModelNames, } from "./voice.js";

package/dist/brand/voice.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The cruxy brand voice (U.8) — a tiny living document, enforced by a test, not
+ * vibes. It centralizes the product name/tagline, the canonical lexicon, and the
+ * forbidden set (deprecated synonyms + the base-model gag) so every user-facing
+ * surface reads as one product. Presentation/copy only — nothing here changes
+ * behavior; the {@link scanForbidden} helper backs the lexicon test.
+ *
+ * Voice, in one breath: concise, direct, second-person for guidance,
+ * lowercase-leaning for status, no marketing fluff, no exclamation-spam. The
+ * product name is ALWAYS lowercase `cruxy`.
+ */
+/** The product name — always lowercase, in running text, banners, and help. */
+export declare const PRODUCT_NAME = "cruxy";
+/** The one-line tagline (mirrors package.json's description). */
+export declare const PRODUCT_TAGLINE = "an agentic coding CLI";
+/** The `cruxy --help` / banner masthead: `cruxy — an agentic coding CLI`. */
+export declare const PRODUCT_MASTHEAD = "cruxy \u2014 an agentic coding CLI";
+/**
+ * The ONLY model names cruxy ever shows a user. The upstream model powering a
+ * tier is never named — a hard rule asserted by the lexicon test.
+ */
+export declare const MODEL_TIERS: readonly ["kavi", "vaani", "mira"];
+/**
+ * The canonical term for each concept — the words every surface must use.
+ * Documented here so the lexicon is reviewable in one place; the forbidden
+ * synonyms below are what the test actually enforces.
+ */
+export declare const CANONICAL_TERMS: {
+    readonly product: "cruxy";
+    readonly backend: "gateway";
+    readonly extension: "skill";
+    readonly lifecycleHook: "hook";
+    readonly undoUnit: "checkpoint";
+    readonly isolation: "sandbox";
+    readonly secret: "API key";
+    readonly pullRequest: "pull request";
+    readonly permission: "approval";
+};
+/** One deprecated/off-voice term the copy must not use, and what to use instead. */
+export interface ForbiddenTerm {
+    /** Matches the forbidden term (word-bounded, case-insensitive). */
+    pattern: RegExp;
+    /** The forbidden term, for the failure message. */
+    term: string;
+    /** The canonical term to use instead. */
+    use: string;
+}
+/**
+ * Deprecated synonyms banned from user-facing copy. Scoped to the curated
+ * surfaces the lexicon test scans (command descriptions, error output, brand +
+ * onboarding constants) — NOT a raw source grep — so legitimate internal uses
+ * (`mcpServers` config key, docker `.Server.Version`, code comments) never
+ * false-trip, while every string a user reads is covered.
+ */
+export declare const FORBIDDEN_TERMS: readonly ForbiddenTerm[];
+/**
+ * Upstream model names — the base-model gag. None may appear in user-facing
+ * copy; only {@link MODEL_TIERS} ever do. `anthropic`/`openai` are deliberately
+ * absent: they are real bring-your-own-provider config values, not model names.
+ */
+export declare const FORBIDDEN_MODEL_NAMES: RegExp;
+/** The neutral token an upstream model name is replaced with in user-facing copy. */
+export declare const MODEL_NAME_PLACEHOLDER = "\u00ABmodel\u00BB";
+/**
+ * Replace every upstream model IDENTIFIER in an arbitrary, externally-sourced
+ * string with {@link MODEL_NAME_PLACEHOLDER}, collapsing a whole `name-name-vers`
+ * run to a single token.
+ *
+ * The U.8 gag is structural *inside the process* (the routing package can't
+ * produce an upstream id — see `resolveModelId`), but a gateway/provider error
+ * body is an arbitrary external string that bypasses that guarantee. This is the
+ * scrub applied at the error-construction boundary so no upstream id reaches a
+ * user-facing `CruxyError.cause`.
+ *
+ * Scrubs model ids as whole TOKENS, never a bare vendor word or a substring
+ * inside an unrelated word/path — so legitimate output (`/home/claude`, the
+ * `opus` codec, a `claude-bot` username) is left intact (see {@link isModelId}).
+ * Provider names (`anthropic`/`openai`) are absent from the set, so bring-your-own
+ * provider config values survive too.
+ */
+export declare function scrubModelNames(text: string): string;
+/** One lexicon violation found in a scanned string. */
+export interface LexiconViolation {
+    /** The forbidden term (or "model-name" for a gag violation). */
+    term: string;
+    /** The canonical replacement, when the term is a deprecated synonym. */
+    use?: string;
+}
+/**
+ * Scan one user-facing string for lexicon violations — deprecated synonyms and
+ * upstream model names. Returns every violation (empty ⇒ on-voice). Pure; the
+ * lexicon test runs it over the curated surfaces.
+ */
+export declare function scanForbidden(text: string): LexiconViolation[];

package/dist/brand/voice.js

@@ -0,0 +1,127 @@
+/**
+ * The cruxy brand voice (U.8) — a tiny living document, enforced by a test, not
+ * vibes. It centralizes the product name/tagline, the canonical lexicon, and the
+ * forbidden set (deprecated synonyms + the base-model gag) so every user-facing
+ * surface reads as one product. Presentation/copy only — nothing here changes
+ * behavior; the {@link scanForbidden} helper backs the lexicon test.
+ *
+ * Voice, in one breath: concise, direct, second-person for guidance,
+ * lowercase-leaning for status, no marketing fluff, no exclamation-spam. The
+ * product name is ALWAYS lowercase `cruxy`.
+ */
+/** The product name — always lowercase, in running text, banners, and help. */
+export const PRODUCT_NAME = "cruxy";
+/** The one-line tagline (mirrors package.json's description). */
+export const PRODUCT_TAGLINE = "an agentic coding CLI";
+/** The `cruxy --help` / banner masthead: `cruxy — an agentic coding CLI`. */
+export const PRODUCT_MASTHEAD = `${PRODUCT_NAME} — ${PRODUCT_TAGLINE}`;
+/**
+ * The ONLY model names cruxy ever shows a user. The upstream model powering a
+ * tier is never named — a hard rule asserted by the lexicon test.
+ */
+export const MODEL_TIERS = ["kavi", "vaani", "mira"];
+/**
+ * The canonical term for each concept — the words every surface must use.
+ * Documented here so the lexicon is reviewable in one place; the forbidden
+ * synonyms below are what the test actually enforces.
+ */
+export const CANONICAL_TERMS = {
+    product: "cruxy",
+    backend: "gateway",
+    extension: "skill",
+    lifecycleHook: "hook",
+    undoUnit: "checkpoint",
+    isolation: "sandbox",
+    secret: "API key",
+    pullRequest: "pull request",
+    permission: "approval",
+};
+/**
+ * Deprecated synonyms banned from user-facing copy. Scoped to the curated
+ * surfaces the lexicon test scans (command descriptions, error output, brand +
+ * onboarding constants) — NOT a raw source grep — so legitimate internal uses
+ * (`mcpServers` config key, docker `.Server.Version`, code comments) never
+ * false-trip, while every string a user reads is covered.
+ */
+export const FORBIDDEN_TERMS = [
+    { pattern: /\bplug-?ins?\b/i, term: "plugin", use: "skill" },
+    { pattern: /\btriggers?\b/i, term: "trigger", use: "hook" },
+    { pattern: /\bservers?\b/i, term: "server", use: "gateway" },
+    { pattern: /\bcruxy[- ]code\b/i, term: "cruxy-code", use: "cruxy" },
+];
+/**
+ * Upstream model names — the base-model gag. None may appear in user-facing
+ * copy; only {@link MODEL_TIERS} ever do. `anthropic`/`openai` are deliberately
+ * absent: they are real bring-your-own-provider config values, not model names.
+ */
+export const FORBIDDEN_MODEL_NAMES = /\b(claude|sonnet|opus|haiku|gpt-?\d|gemini|llama|mistral)\b/i;
+/** The neutral token an upstream model name is replaced with in user-facing copy. */
+export const MODEL_NAME_PLACEHOLDER = "«model»";
+/**
+ * A model-id-SHAPED run in free text: a self-identifying `gpt-4`/`gpt-4o`, or a
+ * model word carrying a hyphen/dot tail (`claude-sonnet-4-6`, `gemini-1.5-pro`).
+ * Deliberately GENEROUS — it also matches bare words and non-model hyphenated
+ * tokens; {@link isModelId} does the real filtering in the scrub callback, and
+ * matching the whole run (not each word) is what collapses `claude-sonnet-4-6`
+ * to ONE placeholder instead of `«model»-«model»-4-6`. The leading
+ * `(?<![/\\\w])` stops it firing inside a longer word (`gptools`) or on a path
+ * segment (`/home/claude/…`) — both of which the bare `\b` form corrupts.
+ */
+const MODEL_ID_CANDIDATE = /(?<![/\\\w])(?:gpt-?\d[a-z0-9]*(?:[-.][a-z0-9]+)*|(?:claude|sonnet|opus|haiku|gemini|llama|mistral|gpt)(?:[-.][a-z0-9]+)*)/gi;
+/** The bare model words, for the digitless-compound test in {@link isModelId}. */
+const MODEL_WORD = /(?:claude|sonnet|opus|haiku|gemini|llama|mistral|gpt)/gi;
+/**
+ * Is a {@link MODEL_ID_CANDIDATE} run an actual upstream model reference (scrub),
+ * or a legitimate token that merely contains a model word (keep)? A reference is:
+ * a self-identifying `gpt-<n>`; OR a hyphen/dot run carrying a version digit
+ * (`claude-sonnet-4-6`, `gemini-1.5-pro`); OR a digitless compound of ≥2 distinct
+ * model words (`claude-sonnet`). A bare word (`opus`, `haiku`), a path segment
+ * (`/home/claude`), or a plain hyphenated token (`claude-bot`) is none of these,
+ * so it survives verbatim — the gag scrubs model IDS, never legitimate output.
+ */
+function isModelId(run) {
+    if (/^gpt-?\d/i.test(run))
+        return true; // gpt-4, gpt4, gpt-4o
+    if (!/[-.]/.test(run))
+        return false; // bare word — never a model reference here
+    if (/\d/.test(run))
+        return true; // version digit ⇒ an id
+    const words = run.match(MODEL_WORD) ?? [];
+    return new Set(words.map((w) => w.toLowerCase())).size >= 2; // claude-sonnet
+}
+/**
+ * Replace every upstream model IDENTIFIER in an arbitrary, externally-sourced
+ * string with {@link MODEL_NAME_PLACEHOLDER}, collapsing a whole `name-name-vers`
+ * run to a single token.
+ *
+ * The U.8 gag is structural *inside the process* (the routing package can't
+ * produce an upstream id — see `resolveModelId`), but a gateway/provider error
+ * body is an arbitrary external string that bypasses that guarantee. This is the
+ * scrub applied at the error-construction boundary so no upstream id reaches a
+ * user-facing `CruxyError.cause`.
+ *
+ * Scrubs model ids as whole TOKENS, never a bare vendor word or a substring
+ * inside an unrelated word/path — so legitimate output (`/home/claude`, the
+ * `opus` codec, a `claude-bot` username) is left intact (see {@link isModelId}).
+ * Provider names (`anthropic`/`openai`) are absent from the set, so bring-your-own
+ * provider config values survive too.
+ */
+export function scrubModelNames(text) {
+    return text.replace(MODEL_ID_CANDIDATE, (run) => isModelId(run) ? MODEL_NAME_PLACEHOLDER : run);
+}
+/**
+ * Scan one user-facing string for lexicon violations — deprecated synonyms and
+ * upstream model names. Returns every violation (empty ⇒ on-voice). Pure; the
+ * lexicon test runs it over the curated surfaces.
+ */
+export function scanForbidden(text) {
+    const violations = [];
+    for (const { pattern, term, use } of FORBIDDEN_TERMS) {
+        if (pattern.test(text))
+            violations.push({ term, use });
+    }
+    const model = text.match(FORBIDDEN_MODEL_NAMES);
+    if (model)
+        violations.push({ term: `model-name "${model[0]}"` });
+    return violations;
+}

package/dist/cli/commands/checkpoint.js

@@ -10,7 +10,7 @@ import { logger } from "../../utils/logger.js";
  * this command only lists.
  */
 export function checkpointCommand() {
-    const cmd = new Command("checkpoint").description("working-tree checkpoints — the undo units behind `cruxy rollback`");
+    const cmd = new Command("checkpoint").description("inspect working-tree checkpoints (the undo units behind rollback)");
     cmd
         .command("list")
         .description("list saved checkpoints, newest first")

package/dist/cli/commands/hooks.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy hooks` — inspect and trust hooks + custom slash commands (C.19).
+ * `list` shows the resolved catalog (including which project hooks are trusted
+ * and any malformed definitions); `trust <path>` records the explicit,
+ * reviewed decision to run a project's hooks, bound to their current fingerprint.
+ */
+export declare function hooksCommand(): Command;

package/dist/cli/commands/hooks.js

@@ -0,0 +1,83 @@
+import path from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../../config/index.js";
+import { shouldUseColor } from "../../errors/index.js";
+import { themeForColor } from "../../theme/index.js";
+import { defaultHookSources, fileTrustStore, fingerprintHooks, isTrusted, loadHookCatalog, } from "../../hooks/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy hooks` — inspect and trust hooks + custom slash commands (C.19).
+ * `list` shows the resolved catalog (including which project hooks are trusted
+ * and any malformed definitions); `trust <path>` records the explicit,
+ * reviewed decision to run a project's hooks, bound to their current fingerprint.
+ */
+export function hooksCommand() {
+    const cmd = new Command("hooks").description("inspect and trust hooks and custom slash commands");
+    cmd
+        .command("list", { isDefault: true })
+        .description("list configured hooks, custom commands, and load errors")
+        .action(async () => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        const cwd = process.cwd();
+        const catalog = await loadHookCatalog(defaultHookSources(cwd));
+        logger.print(`${t.strong("hooks:")} ${config.hooks.enabled ? t.success("enabled") : t.warning("disabled (hooks.enabled = false)")}`);
+        const projectHooks = catalog.hooks.filter((h) => h.source === "project");
+        if (projectHooks.length > 0) {
+            const trusted = isTrusted(fileTrustStore(), cwd, fingerprintHooks(projectHooks));
+            logger.print(`${t.strong("project trust:")} ${trusted ? t.success("trusted") : t.danger("NOT trusted — run `cruxy hooks trust .`")}`);
+        }
+        printHooks(catalog.hooks, t);
+        printCommands(catalog.commands, t);
+        printErrors(catalog.errors, t);
+    });
+    cmd
+        .command("trust <path>")
+        .description("trust a project's hooks after reviewing them (records the decision)")
+        .action(async (target) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const root = path.resolve(target);
+        const catalog = await loadHookCatalog(defaultHookSources(root));
+        const projectHooks = catalog.hooks.filter((h) => h.source === "project");
+        if (projectHooks.length === 0) {
+            logger.print(t.muted(`no project hooks found under ${root}`));
+            return;
+        }
+        logger.print(t.strong(`trusting ${projectHooks.length} project hook(s):`));
+        printHooks(projectHooks, t);
+        fileTrustStore().record({
+            root,
+            fingerprint: fingerprintHooks(projectHooks),
+            at: new Date().toISOString(),
+        });
+        logger.print(`${t.success("trusted")} — these hooks may now run for ${root}. ` +
+            t.muted("changing any of them will require re-trusting."));
+    });
+    return cmd;
+}
+function printHooks(hooks, t) {
+    if (hooks.length === 0) {
+        logger.print(t.muted("  no hooks configured"));
+        return;
+    }
+    for (const h of hooks) {
+        const policy = h.blocking ? t.danger("blocking") : t.muted("advisory");
+        logger.print(`  ${t.muted(`[${h.source}]`)} ${t.strong(h.name)} ${t.muted(h.event)} ${policy}\n      ${t.muted("$")} ${h.command}`);
+    }
+}
+function printCommands(commands, t) {
+    if (commands.length === 0)
+        return;
+    logger.print(`\n${t.heading("custom slash commands:")}`);
+    for (const c of commands) {
+        logger.print(`  ${t.muted(`[${c.source}]`)} ${t.strong(`/${c.name}`)} ${t.muted(`(${c.kind})`)} — ${c.description}`);
+    }
+}
+function printErrors(errors, t) {
+    if (errors.length === 0)
+        return;
+    logger.print(`\n${t.danger(t.heading("malformed (excluded, never run):"))}`);
+    for (const e of errors) {
+        logger.print(`  ${t.muted(`[${e.source}]`)} ${t.strong(e.name)} — ${e.message}`);
+    }
+}

package/dist/cli/commands/init.js

@@ -12,7 +12,7 @@ import { runFirstWinTask } from "../onboard.js";
  */
 export function initCommand() {
     return new Command("init")
-        .description("set up cruxy in this project (key + CRUXY.md + a first run)")
+        .description("set up cruxy in this project (API key, CRUXY.md, and a first run)")
         .action(async () => {
         const t = themeForColor(shouldUseColor(process.stdout));
         if (!process.stdin.isTTY) {

package/dist/cli/commands/pr.js

@@ -5,6 +5,7 @@ import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, shouldUseColor } from "../../errors/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { ApprovalService } from "../../approval/index.js";
+import { resolveTaskModel, routerForConfig } from "../../routing/index.js";
 import { createForgeProvider, createPrService, generateWithLlm, loadCommitGuidance, resolveForgeToken, } from "../../vcs/index.js";
 /**
  * `cruxy pr` — turn the current changes into a pull request (C.15). Generates the
@@ -14,7 +15,7 @@ import { createForgeProvider, createPrService, generateWithLlm, loadCommitGuidan
  */
 export function prCommand() {
     return new Command("pr")
-        .description("open a pull request from the current changes (generated + gated)")
+        .description("open a pull request from the current changes (generated and gated)")
         .option("-b, --base <branch>", "base branch to merge into")
         .option("-t, --title <title>", "PR title (conventional-commit subject)")
         .option("--body <body>", "PR body")
@@ -37,6 +38,13 @@ export function prCommand() {
             temperature: config.model.temperature,
             gatewayUrl: config.cruxy.gatewayUrl,
         });
+        // Multi-model routing (C.30): PR/commit text is `commit-msg` work. Null
+        // unless routing is configured → the provider default, unchanged. A
+        // misrouted tier fails loud here before any request.
+        const router = routerForConfig(config);
+        const genModel = router
+            ? resolveTaskModel(router, "commit-msg").model
+            : undefined;
         // resolveForgeToken throws CRUXY_E_FORGE_AUTH (exit 4) if none is found.
         const forge = createForgeProvider(resolveForgeToken());
         const guidance = await loadCommitGuidance(cwd);
@@ -53,7 +61,7 @@ export function prCommand() {
                 ...i,
                 scopes: guidance.scopes,
                 skillBody: guidance.skillBody,
-            }),
+            }, { model: genModel }),
         });
         logger.info(t.muted("generating pull request content…"));
         const outcome = await service.openPullRequest({

package/dist/cli/commands/rollback.js

@@ -50,7 +50,7 @@ async function pickCheckpoint(service) {
  */
 export function rollbackCommand() {
     return new Command("rollback")
-        .description("restore the working tree to a checkpoint, undoing an agent run's file changes")
+        .description("restore the working tree to a checkpoint, undoing a run's file changes")
         .argument("[id]", "checkpoint id (defaults to the most recent)")
         .action(async (id) => {
         const interactive = Boolean(process.stdin.isTTY);