@cruxy/cli 0.16.0 → 0.17.0

package/dist/agent/loop.d.ts

@@ -2,6 +2,7 @@ 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
@@ -57,6 +58,17 @@ export interface RunAgentArgs {
      * 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,4 +1,5 @@
 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. */
@@ -17,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 —
@@ -28,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
@@ -80,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":

package/dist/agent/session.d.ts

@@ -1,6 +1,7 @@
 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, type LifecycleHookRunner } from "./loop.js";
@@ -42,6 +43,11 @@ export interface SessionArgs {
      * `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

package/dist/agent/session.js

@@ -1,4 +1,5 @@
 import { loadProjectInstructions } from "../config/index.js";
+import { resolveTaskModel } from "../routing/index.js";
 import { runAgent, } from "./loop.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
@@ -102,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
@@ -226,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

@@ -1 +1 @@
-export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, type ForbiddenTerm, type LexiconViolation, } from "./voice.js";
+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

@@ -1 +1 @@
-export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, } from "./voice.js";
+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

@@ -59,6 +59,26 @@ export declare const FORBIDDEN_TERMS: readonly ForbiddenTerm[];
  * 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). */

package/dist/brand/voice.js

@@ -55,6 +55,60 @@ export const FORBIDDEN_TERMS = [
  * 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

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
@@ -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/session-factory.js

@@ -7,6 +7,7 @@ import { shouldUseColor } from "../errors/index.js";
 import { buildDefaultRegistry } from "../tools/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
@@ -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,
@@ -167,6 +174,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             planMode: true,
             planRunner,
             hooks,
+            router,
         });
     }
     const approval = new ApprovalService({
@@ -183,5 +191,6 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         git,
         projectInstructions,
         hooks,
+        router,
     });
 }

package/dist/config/schema.d.ts

@@ -365,6 +365,27 @@ export declare const HooksConfigSchema: z.ZodObject<{
     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>;
@@ -697,6 +718,19 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         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">>;
@@ -732,6 +766,14 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     approval: {
         mode: "prompt";
     };
+    subagent: {
+        maxDepth: number;
+        defaultBudget: {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        };
+    };
     model: {
         provider: "cruxy" | "anthropic" | "openai" | "custom";
         model: string;
@@ -777,14 +819,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines: number;
         };
     };
-    subagent: {
-        maxDepth: number;
-        defaultBudget: {
-            maxTokens: number;
-            maxIterations: number;
-            timeoutMs?: number | undefined;
-        };
-    };
     test: {
         maxIterations: number;
         captureBytes: number;
@@ -794,6 +828,10 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         enabled: boolean;
         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;
         args?: string[] | undefined;
@@ -821,6 +859,14 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     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;
@@ -866,14 +912,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | 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;
@@ -883,6 +921,10 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         enabled?: boolean | 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;
         args?: 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",
@@ -254,6 +256,23 @@ export const HooksConfigSchema = z
     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({
@@ -278,6 +297,7 @@ export const CruxyConfigSchema = z
     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/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;

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,
     });

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";

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",
@@ -97,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,

package/dist/plan/service.d.ts

@@ -4,6 +4,7 @@ import type { PromptIO } from "../approval/index.js";
 import { ToolRegistry, type ToolContext } from "../tools/index.js";
 import { type AgentResult } from "../agent/loop.js";
 import type { StreamRenderer } from "../render/index.js";
+import type { Router } from "../routing/index.js";
 import { PlanExecutionPolicy } from "./policy.js";
 /**
  * Orchestrates a plan-mode turn (C.31): propose → approve/revise (capped) →
@@ -36,5 +37,10 @@ export interface PlanSessionArgs {
     renderer?: StreamRenderer;
     /** Revision cap (defaults to {@link MAX_PLAN_REVISIONS}). */
     maxRevisions?: number;
+    /**
+     * Multi-model routing (C.30). When set, the propose phase routes on `plan`
+     * and step execution on `main-turn`; omitted → the provider default.
+     */
+    router?: Router;
 }
 export declare function runPlanSession(args: PlanSessionArgs): Promise<AgentResult>;

package/dist/plan/service.js

@@ -75,6 +75,8 @@ export async function runPlanSession(args) {
             projectInstructions: args.projectInstructions,
             renderer: args.renderer,
             planMode: true,
+            router: args.router,
+            taskClass: "plan",
         }));
         if (!holder.plan) {
             throw planInvalid("the model ended its turn without calling submit_plan");
@@ -106,6 +108,8 @@ export async function runPlanSession(args) {
                     git: args.git,
                     projectInstructions: args.projectInstructions,
                     renderer: args.renderer,
+                    router: args.router,
+                    taskClass: "main-turn",
                 }));
             };
             await executePlan(plan, {

package/dist/render/state.js

@@ -39,9 +39,12 @@ export function describePhase(phase, glyph = UNICODE_GLYPHS) {
         case "thinking": {
             const t = phase.tokens;
             // Honest numbers only: no usage yet → no figure at all.
-            return t && t.input + t.output > 0
+            const base = t && t.input + t.output > 0
                 ? `thinking${e} ${glyph.sep} tokens ${glyph.caretUp}${formatTokens(t.input)} ${glyph.caretDown}${formatTokens(t.output)}`
                 : `thinking${e}`;
+            // The real routing tier (C.30), appended honestly when present — same
+            // ` · ` joiner as the token counts.
+            return phase.tier ? `${base} ${glyph.sep} ${phase.tier}` : base;
         }
         case "calling-tool":
             return `${phase.label}${e}`;

package/dist/render/types.d.ts

@@ -53,10 +53,16 @@ export interface TokenUsage {
  * One phase is live at a time — it is a register, not a queue.
  */
 export type RenderPhase = 
-/** Waiting on the model. `tokens` = usage accumulated so far, omitted at 0. */
+/**
+ * Waiting on the model. `tokens` = usage accumulated so far, omitted at 0.
+ * `tier` = the routing tier this turn runs on (C.30), shown only when routing
+ * is active — an honest signal of the real tier, never a fabricated one, and
+ * always a tier name (never an upstream model id, U.8).
+ */
 {
     kind: "thinking";
     tokens?: TokenUsage;
+    tier?: string;
 }
 /** A tool call is executing; `label` is the human form ("read_file src/x.ts"). */
  | {

package/dist/routing/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export { ConfigRouter, DEFAULT_TIER, routerForConfig, resolveTaskModel, } from "./router.js";

package/dist/routing/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { ConfigRouter, DEFAULT_TIER, routerForConfig, resolveTaskModel, } from "./router.js";
+// `resolve.ts` (tier → wire model-id) is deliberately NOT re-exported: the
+// mapping is internal to routing, so it can never be reached from a user-facing
+// render path (the internal-mapping-isolation guarantee, U.8).

package/dist/routing/resolve.d.ts

@@ -0,0 +1,17 @@
+import type { Tier } from "./types.js";
+/**
+ * Tier → gateway wire model-id. This is the SINGLE place the mapping lives, and
+ * it is INTERNAL to the routing package (deliberately not re-exported from the
+ * barrel) so it can never be called from a user-facing render path.
+ *
+ * For the Cruxy gateway a tier IS the wire model id — the gateway maps the tier
+ * to a concrete upstream model SERVER-SIDE. So this returns the tier name
+ * unchanged: the output is always a tier, and no upstream model name can
+ * originate here. That property is what keeps the U.8 gag structural rather than
+ * a filter — there is no upstream id in the process to leak (see the tier-gag
+ * test, which asserts this output is always a MODEL_TIERS member).
+ *
+ * The seam exists for a future provider whose tiers map to distinct wire ids;
+ * that mapping would live here and here only.
+ */
+export declare function resolveModelId(tier: Tier): string;

package/dist/routing/resolve.js

@@ -0,0 +1,18 @@
+/**
+ * Tier → gateway wire model-id. This is the SINGLE place the mapping lives, and
+ * it is INTERNAL to the routing package (deliberately not re-exported from the
+ * barrel) so it can never be called from a user-facing render path.
+ *
+ * For the Cruxy gateway a tier IS the wire model id — the gateway maps the tier
+ * to a concrete upstream model SERVER-SIDE. So this returns the tier name
+ * unchanged: the output is always a tier, and no upstream model name can
+ * originate here. That property is what keeps the U.8 gag structural rather than
+ * a filter — there is no upstream id in the process to leak (see the tier-gag
+ * test, which asserts this output is always a MODEL_TIERS member).
+ *
+ * The seam exists for a future provider whose tiers map to distinct wire ids;
+ * that mapping would live here and here only.
+ */
+export function resolveModelId(tier) {
+    return tier;
+}

package/dist/routing/router.d.ts

@@ -0,0 +1,47 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { Router, RoutingConfig, TaskClass, Tier } from "./types.js";
+/**
+ * The tier a config resolves to when nothing else pins one down — mirrors the
+ * gateway's `auto` fallback (`AUTO_FALLBACK_TIER` in the SDK), so an unrouted
+ * cruxy session lands on exactly the tier it does today.
+ */
+export declare const DEFAULT_TIER: Tier;
+/**
+ * The config-driven {@link Router}: maps a declared task class to a tier from
+ * `{ default, map }`, and fails loud when the resolved tier is not offered. It
+ * NEVER inspects prompt content — selection is purely `map[taskClass] ?? default`.
+ */
+export declare class ConfigRouter implements Router {
+    private readonly cfg;
+    private readonly offered;
+    /**
+     * @param cfg      the resolved routing table (default tier + per-task map)
+     * @param offered  the tiers this gateway/plan actually provides; a resolved
+     *                 tier outside this set fails loud. Defaults to all tiers — the
+     *                 seam a future entitlement check narrows (never a silent
+     *                 downgrade).
+     */
+    constructor(cfg: RoutingConfig, offered?: Iterable<Tier>);
+    select(taskClass: TaskClass): Tier;
+}
+/**
+ * Build a router from resolved config, or `null` when routing should stay
+ * inert. Routing is:
+ *
+ * - a cruxy-gateway concept — tiers do not apply to BYO providers, so non-cruxy
+ *   providers get `null` (no override, their `model.model` is used unchanged);
+ * - opt-in — with no `routing.default` and an empty `routing.map`, this returns
+ *   `null` so behavior (and the wire body, and the state line) is byte-identical
+ *   to today. Multi-tier routing activates only once the user configures it.
+ */
+export declare function routerForConfig(config: CruxyConfig): Router | null;
+/**
+ * Resolve a declared task class to `{ tier, model }`: the tier for honest
+ * surfacing (the U.4 state line), the wire model id for the request. The model
+ * id comes from the internal {@link resolveModelId} — callers never touch that
+ * mapping directly, so it stays the single source of truth.
+ */
+export declare function resolveTaskModel(router: Router, taskClass: TaskClass): {
+    tier: Tier;
+    model: string;
+};

package/dist/routing/router.js

@@ -0,0 +1,84 @@
+import { MODEL_TIERS } from "../brand/voice.js";
+import { routingTierUnavailable } from "../errors/index.js";
+import { resolveModelId } from "./resolve.js";
+/**
+ * The tier a config resolves to when nothing else pins one down — mirrors the
+ * gateway's `auto` fallback (`AUTO_FALLBACK_TIER` in the SDK), so an unrouted
+ * cruxy session lands on exactly the tier it does today.
+ */
+export const DEFAULT_TIER = "vaani";
+/**
+ * The config-driven {@link Router}: maps a declared task class to a tier from
+ * `{ default, map }`, and fails loud when the resolved tier is not offered. It
+ * NEVER inspects prompt content — selection is purely `map[taskClass] ?? default`.
+ */
+export class ConfigRouter {
+    cfg;
+    offered;
+    /**
+     * @param cfg      the resolved routing table (default tier + per-task map)
+     * @param offered  the tiers this gateway/plan actually provides; a resolved
+     *                 tier outside this set fails loud. Defaults to all tiers — the
+     *                 seam a future entitlement check narrows (never a silent
+     *                 downgrade).
+     */
+    constructor(cfg, offered = MODEL_TIERS) {
+        this.cfg = cfg;
+        this.offered = new Set(offered);
+    }
+    select(taskClass) {
+        // Explicit override, else the default — an unmapped/unknown class is not an
+        // error, it just takes the default (never a crash, never the cheapest).
+        const tier = this.cfg.map[taskClass] ?? this.cfg.default;
+        // Fail loud: a configured tier the gateway does not offer is a usage error
+        // to fix, NOT a silent substitution to some other tier (a user who asked for
+        // mira reasoning must never be quietly handed kavi).
+        if (!this.offered.has(tier)) {
+            throw routingTierUnavailable(tier, taskClass, [...this.offered]);
+        }
+        return tier;
+    }
+}
+/**
+ * The base tier implied by the session's `model.model`: a real tier passes
+ * through; `auto` (and any non-tier value) falls back to {@link DEFAULT_TIER}.
+ * Used so that when a user has pinned a single tier, an opt-in routing table
+ * that omits `routing.default` still defaults to THEIR tier, not a fixed one.
+ */
+function baseTierFromModel(model) {
+    return MODEL_TIERS.includes(model)
+        ? model
+        : DEFAULT_TIER;
+}
+/**
+ * Build a router from resolved config, or `null` when routing should stay
+ * inert. Routing is:
+ *
+ * - a cruxy-gateway concept — tiers do not apply to BYO providers, so non-cruxy
+ *   providers get `null` (no override, their `model.model` is used unchanged);
+ * - opt-in — with no `routing.default` and an empty `routing.map`, this returns
+ *   `null` so behavior (and the wire body, and the state line) is byte-identical
+ *   to today. Multi-tier routing activates only once the user configures it.
+ */
+export function routerForConfig(config) {
+    if (config.model.provider !== "cruxy")
+        return null;
+    const { default: def, map } = config.routing;
+    const configured = def !== undefined || Object.keys(map).length > 0;
+    if (!configured)
+        return null;
+    return new ConfigRouter({
+        default: def ?? baseTierFromModel(config.model.model),
+        map,
+    });
+}
+/**
+ * Resolve a declared task class to `{ tier, model }`: the tier for honest
+ * surfacing (the U.4 state line), the wire model id for the request. The model
+ * id comes from the internal {@link resolveModelId} — callers never touch that
+ * mapping directly, so it stays the single source of truth.
+ */
+export function resolveTaskModel(router, taskClass) {
+    const tier = router.select(taskClass);
+    return { tier, model: resolveModelId(tier) };
+}

package/dist/routing/types.d.ts

@@ -0,0 +1,42 @@
+import { MODEL_TIERS } from "../brand/voice.js";
+/**
+ * Multi-model routing (C.30): route each unit of work to the right tier instead
+ * of running one model for everything. The caller DECLARES a {@link TaskClass}
+ * at the call site; a {@link Router} maps that class to a {@link Tier} via config
+ * — it never sniffs the prompt to guess difficulty. The tier→gateway model-id
+ * mapping is internal (see `resolve.ts`); only tier names ever appear in config,
+ * logs, errors, or the state line (the U.8 tier gag).
+ */
+/**
+ * The unit-of-work classes a caller can declare. Each is an explicit intent —
+ * NOT a difficulty the router infers. Unknown/unset resolves to the router's
+ * default tier, never a crash.
+ */
+export declare const TASK_CLASSES: readonly ["main-turn", "subagent", "plan", "commit-msg", "classify", "summarize"];
+export type TaskClass = (typeof TASK_CLASSES)[number];
+/** A routing tier — the ONLY model vocabulary the user ever sees (U.8). */
+export type Tier = (typeof MODEL_TIERS)[number];
+/**
+ * Selects a tier for a declared task class. Deliberately one method: the caller
+ * passes intent, the router returns a tier from its configured mapping. No
+ * prompt-content inspection, ever — difficulty detection is explicitly out of
+ * scope (a caller declares; the router does not guess).
+ */
+export interface Router {
+    /**
+     * Map a task class to its tier. Falls back to the configured default when the
+     * class has no explicit mapping; throws `CRUXY_E_ROUTING_TIER_UNAVAILABLE`
+     * (fail loud, never a silent substitution) when the resolved tier is not
+     * offered.
+     */
+    select(taskClass: TaskClass): Tier;
+}
+/**
+ * The declarative routing table: a `default` tier plus per-task overrides. Lives
+ * in config (`routing.default`, `routing.map`). An empty map means every class
+ * resolves to `default` — a single tier, no traffic splitting.
+ */
+export interface RoutingConfig {
+    default: Tier;
+    map: Partial<Record<TaskClass, Tier>>;
+}

package/dist/routing/types.js

@@ -0,0 +1,27 @@
+/**
+ * Multi-model routing (C.30): route each unit of work to the right tier instead
+ * of running one model for everything. The caller DECLARES a {@link TaskClass}
+ * at the call site; a {@link Router} maps that class to a {@link Tier} via config
+ * — it never sniffs the prompt to guess difficulty. The tier→gateway model-id
+ * mapping is internal (see `resolve.ts`); only tier names ever appear in config,
+ * logs, errors, or the state line (the U.8 tier gag).
+ */
+/**
+ * The unit-of-work classes a caller can declare. Each is an explicit intent —
+ * NOT a difficulty the router infers. Unknown/unset resolves to the router's
+ * default tier, never a crash.
+ */
+export const TASK_CLASSES = [
+    /** An interactive main-agent turn. */
+    "main-turn",
+    /** A spawned subagent task (C.14). */
+    "subagent",
+    /** Plan proposal / revision (C.31). */
+    "plan",
+    /** Commit / pull-request text generation. */
+    "commit-msg",
+    /** A cheap one-shot classification. */
+    "classify",
+    /** Context compaction / summarization. */
+    "summarize",
+];

package/dist/subagent/orchestrator.d.ts

@@ -2,6 +2,7 @@ import type { Provider } from "@cruxy/sdk";
 import type { ApprovalDecision } from "../approval/types.js";
 import type { CruxyConfig } from "../config/index.js";
 import type { StreamRenderer } from "../render/index.js";
+import type { Router } from "../routing/index.js";
 import type { ApproveAction, ToolContext, ToolRegistry } from "../tools/index.js";
 import type { SandboxService } from "../sandbox/index.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
@@ -15,6 +16,11 @@ import type { SubagentResult, SubagentSpec } from "./types.js";
 export interface SubagentOrchestratorDeps {
     provider: Provider;
     config: CruxyConfig;
+    /**
+     * Multi-model routing (C.30). When set, child runs route on their spec's task
+     * class (default `subagent`); omitted → the provider default (unchanged).
+     */
+    router?: Router;
     /** The parent's registry — the ceiling every child scope derives from. */
     parentRegistry: ToolRegistry;
     cwd: string;

package/dist/subagent/orchestrator.js

@@ -91,6 +91,8 @@ export class SubagentOrchestrator {
                 projectInstructions: deps.projectInstructions,
                 subagent: true,
                 budget,
+                router: deps.router,
+                taskClass: spec.taskClass ?? "subagent",
             });
         }
         catch (err) {

package/dist/subagent/types.d.ts

@@ -1,4 +1,5 @@
 import type { Usage } from "@cruxy/sdk";
+import type { TaskClass } from "../routing/index.js";
 /**
  * Types for subagent orchestration (C.14): the main agent delegates a bounded
  * subtask to a child agent that runs the SAME loop with its own fresh history,
@@ -35,6 +36,11 @@ export interface SubagentSpec {
      * spawn can narrow its budget, never raise it past the configured ceilings.
      */
     budget?: Partial<BudgetLimits>;
+    /**
+     * Routing task class for this spawn (C.30); defaults to `subagent`. A
+     * declaration at the spawn call site — not something the router guesses.
+     */
+    taskClass?: TaskClass;
 }
 /**
  * What the parent gets back — compact structured data, never the transcript.

package/dist/vcs/generate.d.ts

@@ -59,7 +59,9 @@ export declare function fillContent(input: GenerateInput): GeneratedContent;
  * rules, then normalize + redact. Resilient: if the model's reply isn't the
  * expected JSON, the first line becomes the subject and the rest the body.
  */
-export declare function generateWithLlm(provider: Provider, input: GenerateInput): Promise<GeneratedContent>;
+export declare function generateWithLlm(provider: Provider, input: GenerateInput, opts?: {
+    model?: string;
+}): Promise<GeneratedContent>;
 interface ParsedGenerated {
     branchName?: string;
     commitSubject?: string;

package/dist/vcs/generate.js

@@ -154,7 +154,7 @@ export function fillContent(input) {
  * rules, then normalize + redact. Resilient: if the model's reply isn't the
  * expected JSON, the first line becomes the subject and the rest the body.
  */
-export async function generateWithLlm(provider, input) {
+export async function generateWithLlm(provider, input, opts = {}) {
     const redactedDiff = redactSecrets(input.diff);
     const system = buildSystemPrompt(input);
     const user = buildUserPrompt({ ...input, diff: redactedDiff });
@@ -162,6 +162,9 @@ export async function generateWithLlm(provider, input) {
     for await (const ev of provider.stream({
         system,
         messages: [{ role: "user", content: user }],
+        // The commit-msg tier's wire model (C.30), resolved by the caller; omitted →
+        // the provider default.
+        ...(opts.model ? { model: opts.model } : {}),
     })) {
         if (ev.type === "text_delta")
             text += ev.text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
     "tinyglobby": "^0.2.10",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
-    "@cruxy/sdk": "0.1.0"
+    "@cruxy/sdk": "0.2.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",