@sayknow-cli/coding-agent 0.5.23 → 0.5.25

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## [Unreleased]
 
-## [0.5.23] - 2026-09-20
+## [0.5.25] - 2026-09-21
 
 ## [0.5.22] - 2026-09-19
 

package/dist/types/config/settings-schema.d.ts

@@ -2421,6 +2421,56 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Add a model-backed second stage to workflow routing. The keyword table already runs on every turn and costs nothing; this handles the phrasings it cannot express, which is most wording that is not a literal match. Costs one small model call, and only on turns the keyword table did not already answer. Any failure falls back to keyword-only behaviour, but a successful answer can also select a different workflow than the deep-interview ambiguity detector would have.";
         };
     };
+    /**
+     * Per-spawn model routing for subagents.
+     *
+     * A role's configured model is a standing guess about the average task that
+     * role gets; this moves it when a particular assignment is clearly harder or
+     * clearly more mechanical. Subagents only — routing the main loop's model
+     * mid-session invalidates the prompt cache, which on a long context costs
+     * more than the cheaper tier saves.
+     *
+     * Needs `decisions.enabled` and at least two tiers configured. Without both
+     * it never fires and the configured role models are used unchanged.
+     */
+    readonly "task.modelRouting.enabled": {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly ui: {
+            readonly tab: "tasks";
+            readonly label: "Route subagent models per task";
+            readonly description: "Ask a cheap model how demanding each subagent assignment is, and move that spawn to a cheaper or stronger model. Needs typed decisions on and the tier models below set. Moving to a cheaper model requires more confidence than moving to a stronger one, because being wrong about it costs a retry.";
+        };
+    };
+    /** Cheapest tier. Mechanical, local, single-file work. */
+    readonly "task.modelRouting.fastModel": {
+        readonly type: "string";
+        readonly default: "";
+    };
+    /** Middle tier. Ordinary engineering against an existing pattern. */
+    readonly "task.modelRouting.balancedModel": {
+        readonly type: "string";
+        readonly default: "";
+    };
+    /** Most capable tier. Unclear cause, cross-cutting design, hard to undo. */
+    readonly "task.modelRouting.deepModel": {
+        readonly type: "string";
+        readonly default: "";
+    };
+    /**
+     * Frontend planning model — the **domain** axis.
+     *
+     * When a planning role (planner/architect) is handed work that clearly reads
+     * as frontend/UI, it takes this model instead of the ladder's answer. A
+     * design-strong model is not "more capable" than a code-strong one; this is a
+     * lateral swap. Unset disables it entirely, and implementation roles are
+     * never swapped by domain — the user asked for the design model to plan the
+     * frontend, not to write it.
+     */
+    readonly "task.modelRouting.frontendModel": {
+        readonly type: "string";
+        readonly default: "";
+    };
     readonly "ttsr.enabled": {
         readonly type: "boolean";
         readonly default: true;

package/dist/types/decisions/task-routing.d.ts

@@ -0,0 +1,68 @@
+import type { DecisionService } from "./index";
+/** Ordered cheapest to most capable. The order *is* the policy's direction. */
+export declare const TASK_TIERS: readonly ["fast", "balanced", "deep"];
+export type TaskTier = (typeof TASK_TIERS)[number];
+export interface TaskTierModels {
+    fast?: string;
+    balanced?: string;
+    deep?: string;
+}
+export interface TaskRoutingPolicy {
+    tiers: TaskTierModels;
+    /**
+     * Bar to move to a more capable model. Being wrong costs money.
+     */
+    minUpgradeConfidence: number;
+    /**
+     * Bar to move to a cheaper model. Being wrong means real work handled by a
+     * model too small for it, which is discovered late and costs a retry — so
+     * this bar sits higher than the upgrade bar on purpose.
+     */
+    minDowngradeConfidence: number;
+    /**
+     * Model for frontend planning, when the assignment reads as frontend work.
+     *
+     * This is the **domain** axis, not a rung on the ladder: a design-strong model
+     * is not "better" than a code-strong one, it is a different specialty. Only
+     * planning roles ever take it, and only laterally — the implementation roles
+     * stay on the difficulty ladder.
+     */
+    frontendModel?: string;
+    /**
+     * Bar for the lateral swap above. Directional bars do not apply here because
+     * neither direction is "spending more": being wrong either way costs quality,
+     * symmetrically, so one bar is the whole story.
+     */
+    minDomainConfidence: number;
+}
+export declare const DEFAULT_TASK_ROUTING_POLICY: Omit<TaskRoutingPolicy, "tiers">;
+/**
+ * Roles whose output is a plan or a design review.
+ *
+ * These are the only roles the domain swap applies to — the user's intent is
+ * "a design-strong model *plans* the frontend; implementation stays where it
+ * is". Executor keeps the difficulty ladder regardless of domain.
+ */
+export declare const PLANNING_ROLES: ReadonlySet<string>;
+export interface TaskRoutingRequest {
+    agentName: string;
+    /** The assignment text the subagent will act on. */
+    assignment: string;
+    /** Whatever the role is configured to use today, used as the direction baseline. */
+    currentModel: string | undefined;
+    signal?: AbortSignal;
+}
+export interface TaskRoutingResult {
+    model: string;
+    /** Null when the move was a domain swap — that axis has no ladder. */
+    tier: TaskTier | null;
+    reason: string;
+}
+/**
+ * Decide the model for one subagent spawn, or null to leave the configured one alone.
+ *
+ * Every failure path returns null: no tiers configured, decisions disabled, no
+ * backend, a timeout, an answer outside the enum. A subagent that runs on its
+ * configured model is the status quo, and the status quo is always acceptable.
+ */
+export declare function routeTaskModel(service: DecisionService, policy: TaskRoutingPolicy, request: TaskRoutingRequest): Promise<TaskRoutingResult | null>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/coding-agent",
-	"version": "0.5.23",
+	"version": "0.5.25",
 	"description": "Sayknow-CLI CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -54,12 +54,12 @@
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@sayknow-cli/stats": "0.5.23",
-		"@sayknow-cli/agent-core": "0.5.23",
-		"@sayknow-cli/ai": "0.5.23",
-		"@sayknow-cli/natives": "0.5.23",
-		"@sayknow-cli/tui": "0.5.23",
-		"@sayknow-cli/utils": "0.5.23",
+		"@sayknow-cli/stats": "0.5.25",
+		"@sayknow-cli/agent-core": "0.5.25",
+		"@sayknow-cli/ai": "0.5.25",
+		"@sayknow-cli/natives": "0.5.25",
+		"@sayknow-cli/tui": "0.5.25",
+		"@sayknow-cli/utils": "0.5.25",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/config/settings-schema.ts

@@ -2011,6 +2011,46 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	/**
+	 * Per-spawn model routing for subagents.
+	 *
+	 * A role's configured model is a standing guess about the average task that
+	 * role gets; this moves it when a particular assignment is clearly harder or
+	 * clearly more mechanical. Subagents only — routing the main loop's model
+	 * mid-session invalidates the prompt cache, which on a long context costs
+	 * more than the cheaper tier saves.
+	 *
+	 * Needs `decisions.enabled` and at least two tiers configured. Without both
+	 * it never fires and the configured role models are used unchanged.
+	 */
+	"task.modelRouting.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tasks",
+			label: "Route subagent models per task",
+			description:
+				"Ask a cheap model how demanding each subagent assignment is, and move that spawn to a cheaper or stronger model. Needs typed decisions on and the tier models below set. Moving to a cheaper model requires more confidence than moving to a stronger one, because being wrong about it costs a retry.",
+		},
+	},
+	/** Cheapest tier. Mechanical, local, single-file work. */
+	"task.modelRouting.fastModel": { type: "string", default: "" },
+	/** Middle tier. Ordinary engineering against an existing pattern. */
+	"task.modelRouting.balancedModel": { type: "string", default: "" },
+	/** Most capable tier. Unclear cause, cross-cutting design, hard to undo. */
+	"task.modelRouting.deepModel": { type: "string", default: "" },
+	/**
+	 * Frontend planning model — the **domain** axis.
+	 *
+	 * When a planning role (planner/architect) is handed work that clearly reads
+	 * as frontend/UI, it takes this model instead of the ladder's answer. A
+	 * design-strong model is not "more capable" than a code-strong one; this is a
+	 * lateral swap. Unset disables it entirely, and implementation roles are
+	 * never swapped by domain — the user asked for the design model to plan the
+	 * frontend, not to write it.
+	 */
+	"task.modelRouting.frontendModel": { type: "string", default: "" },
+
 	// TTSR
 	"ttsr.enabled": {
 		type: "boolean",

package/src/decisions/task-routing.ts

@@ -0,0 +1,258 @@
+/**
+ * Pick the model a subagent runs on from the work it was handed.
+ *
+ * A role's configured model is a standing guess about the *average* task that
+ * role gets. It cannot be right for every one: the same executor is handed both
+ * a one-line rename and a migration across twelve files. This asks about the
+ * actual assignment and moves the model when the answer is clear enough.
+ *
+ * Only subagents. The main loop's model is deliberately out of scope — changing
+ * it mid-session invalidates the prompt cache, and on a long context re-caching
+ * routinely costs more than the cheaper tier saves. A subagent starts with its
+ * own context, so there is nothing to invalidate.
+ */
+import { logger } from "@sayknow-cli/utils";
+import type { DecisionService } from "./index";
+import type { Question } from "./types";
+
+/** Ordered cheapest to most capable. The order *is* the policy's direction. */
+export const TASK_TIERS = ["fast", "balanced", "deep"] as const;
+export type TaskTier = (typeof TASK_TIERS)[number];
+
+export interface TaskTierModels {
+	fast?: string;
+	balanced?: string;
+	deep?: string;
+}
+
+export interface TaskRoutingPolicy {
+	tiers: TaskTierModels;
+	/**
+	 * Bar to move to a more capable model. Being wrong costs money.
+	 */
+	minUpgradeConfidence: number;
+	/**
+	 * Bar to move to a cheaper model. Being wrong means real work handled by a
+	 * model too small for it, which is discovered late and costs a retry — so
+	 * this bar sits higher than the upgrade bar on purpose.
+	 */
+	minDowngradeConfidence: number;
+	/**
+	 * Model for frontend planning, when the assignment reads as frontend work.
+	 *
+	 * This is the **domain** axis, not a rung on the ladder: a design-strong model
+	 * is not "better" than a code-strong one, it is a different specialty. Only
+	 * planning roles ever take it, and only laterally — the implementation roles
+	 * stay on the difficulty ladder.
+	 */
+	frontendModel?: string;
+	/**
+	 * Bar for the lateral swap above. Directional bars do not apply here because
+	 * neither direction is "spending more": being wrong either way costs quality,
+	 * symmetrically, so one bar is the whole story.
+	 */
+	minDomainConfidence: number;
+}
+
+export const DEFAULT_TASK_ROUTING_POLICY: Omit<TaskRoutingPolicy, "tiers"> = {
+	// Deliberately higher than the reference implementation's 0.3/0.6. That one
+	// assumes a frontier default with a cheap tier to fall to, so "up" is the
+	// rare move. Here the configured role models are already chosen per role, so
+	// overriding one needs a stronger signal in either direction.
+	minUpgradeConfidence: 0.5,
+	minDowngradeConfidence: 0.75,
+	minDomainConfidence: 0.6,
+};
+
+/**
+ * Roles whose output is a plan or a design review.
+ *
+ * These are the only roles the domain swap applies to — the user's intent is
+ * "a design-strong model *plans* the frontend; implementation stays where it
+ * is". Executor keeps the difficulty ladder regardless of domain.
+ */
+export const PLANNING_ROLES: ReadonlySet<string> = new Set(["planner", "architect"]);
+
+/**
+ * The questions describe the *work*, never a model name.
+ *
+ * Naming models in the criteria would bind the classifier to one lineup and
+ * make every model swap a prompt change. It also invites the model to reason
+ * about price, which is not what it is good at.
+ */
+function buildQuestions(): Record<string, Question> {
+	return {
+		tier: {
+			type: "choice",
+			instructions: "How demanding is this assignment?",
+			criteria: {
+				fast: "Mechanical and local. A rename, a typo, a one-file edit, running a command and reporting what it printed.",
+				balanced: "Ordinary engineering. Several files, an existing pattern to follow, normal debugging.",
+				deep: "Hard or high-stakes. Unclear cause, cross-cutting design, subtle correctness, or work that is hard to undo.",
+			},
+		},
+		risky: {
+			type: "noul",
+			instructions:
+				"Does this assignment touch production, money, credentials, published releases, or state that cannot be undone?",
+		},
+		domain: {
+			type: "noul",
+			instructions:
+				"Is this assignment frontend/UI work — interfaces, components, visual design, styling or interaction — rather than data, APIs, infrastructure or business logic?",
+		},
+	};
+}
+
+export interface TaskRoutingRequest {
+	agentName: string;
+	/** The assignment text the subagent will act on. */
+	assignment: string;
+	/** Whatever the role is configured to use today, used as the direction baseline. */
+	currentModel: string | undefined;
+	signal?: AbortSignal;
+}
+
+export interface TaskRoutingResult {
+	model: string;
+	/** Null when the move was a domain swap — that axis has no ladder. */
+	tier: TaskTier | null;
+	reason: string;
+}
+
+/** Where a concrete model id sits in the ladder, or null when it is not one of ours. */
+function rankOf(model: string | undefined, tiers: TaskTierModels): number | null {
+	if (!model) return null;
+	const index = TASK_TIERS.findIndex(tier => tiers[tier] && matchesModel(tiers[tier] as string, model));
+	return index === -1 ? null : index;
+}
+
+/**
+ * Compare a configured tier model against the role's current selector.
+ *
+ * Selectors carry a thinking suffix (`provider/id:high`) that the tier table
+ * may or may not repeat, so compare the part before it.
+ */
+function matchesModel(a: string, b: string): boolean {
+	const base = (value: string) => value.split(":")[0]?.trim().toLowerCase() ?? "";
+	return base(a) === base(b);
+}
+
+/**
+ * Is a move from `current` to `wanted` allowed at this confidence?
+ *
+ * A backend that cannot report a calibrated confidence may only move a request
+ * **up**. Spending less on an unmeasured hunch is the bad trade: the upgrade's
+ * worst case is an overpriced answer, the downgrade's is a wrong one.
+ */
+function allowed(
+	wanted: number,
+	current: number | null,
+	confidence: number | undefined,
+	calibrated: boolean,
+	policy: TaskRoutingPolicy,
+): boolean {
+	if (current !== null && wanted === current) return false;
+	const isDowngrade = current !== null && wanted < current;
+	if (!calibrated || confidence === undefined) return !isDowngrade;
+	return confidence >= (isDowngrade ? policy.minDowngradeConfidence : policy.minUpgradeConfidence);
+}
+
+/**
+ * Decide the model for one subagent spawn, or null to leave the configured one alone.
+ *
+ * Every failure path returns null: no tiers configured, decisions disabled, no
+ * backend, a timeout, an answer outside the enum. A subagent that runs on its
+ * configured model is the status quo, and the status quo is always acceptable.
+ */
+export async function routeTaskModel(
+	service: DecisionService,
+	policy: TaskRoutingPolicy,
+	request: TaskRoutingRequest,
+): Promise<TaskRoutingResult | null> {
+	const configured = TASK_TIERS.filter(tier => policy.tiers[tier]);
+	const frontendModel = policy.frontendModel?.trim() || undefined;
+	// Neither axis has anything to move on: no ladder and no domain model.
+	if (configured.length < 2 && !frontendModel) return null;
+
+	const assignment = request.assignment.trim();
+	if (assignment.length < 24) return null;
+
+	const result = await service.decide({
+		state: `Agent: ${request.agentName}\n\nAssignment:\n${assignment.slice(0, 4_000)}`,
+		questions: buildQuestions(),
+		signal: request.signal,
+	});
+	if (!result) return null;
+
+	// --- Domain axis: lateral swap for planning roles ---
+	//
+	// A design-strong model is not "more capable" than a code-strong one, so this
+	// is not a rung on the ladder and the directional bars do not apply. When the
+	// assignment clearly reads as frontend work and a frontend model is
+	// configured, planning roles take it — that is the whole of the user's
+	// intent: the design model *plans* the frontend, implementation stays put.
+	// When the swap fires, the difficulty ladder is skipped entirely for this
+	// spawn; for planning, design judgment is the point, not raw capability.
+	const domainAnswer = result.answers.domain;
+	if (
+		frontendModel &&
+		PLANNING_ROLES.has(request.agentName) &&
+		domainAnswer?.type === "noul" &&
+		domainAnswer.noul >= policy.minDomainConfidence
+	) {
+		if (request.currentModel && matchesModel(frontendModel, request.currentModel)) return null;
+		logger.debug("decisions/task-routing: routed", {
+			agent: request.agentName,
+			model: frontendModel,
+			reason: `frontend (domain ${domainAnswer.noul.toFixed(2)})`,
+		});
+		return {
+			model: frontendModel,
+			tier: null,
+			reason: `frontend (domain ${domainAnswer.noul.toFixed(2)})`,
+		};
+	}
+
+	// --- Difficulty axis: the ladder ---
+	if (configured.length < 2) return null;
+	const answer = result.answers.tier;
+	if (answer?.type !== "choice") return null;
+	let tier = TASK_TIERS.find(candidate => candidate === answer.choice);
+	if (!tier) return null;
+
+	// Work that cannot be undone takes the most capable tier available and skips
+	// the confidence bars — this one is not a confidence question. It may only
+	// ever raise the tier, never lower it, or "this is risky" would end up
+	// *downgrading* an assignment already running deep.
+	const riskAnswer = result.answers.risky;
+	const forcedByRisk = riskAnswer?.type === "noul" && riskAnswer.noul > 0.7;
+	if (forcedByRisk) {
+		const deepest = configured[configured.length - 1] as TaskTier;
+		const currentRank = rankOf(request.currentModel, policy.tiers);
+		const wantedRank = Math.max(TASK_TIERS.indexOf(deepest), currentRank ?? 0);
+		tier = TASK_TIERS[wantedRank] as TaskTier;
+	}
+
+	const model = policy.tiers[tier];
+	if (!model || (request.currentModel && matchesModel(model, request.currentModel))) return null;
+
+	const currentRank = rankOf(request.currentModel, policy.tiers);
+	const wantedRank = TASK_TIERS.indexOf(tier);
+	if (!forcedByRisk && !allowed(wantedRank, currentRank, answer.confidence, result.calibrated, policy)) {
+		logger.debug("decisions/task-routing: below the bar, keeping the configured model", {
+			agent: request.agentName,
+			wanted: tier,
+			current: request.currentModel,
+			confidence: answer.confidence,
+			calibrated: result.calibrated,
+		});
+		return null;
+	}
+
+	const reason = forcedByRisk
+		? `${tier}, forced by risk`
+		: `${tier} (confidence ${answer.confidence?.toFixed(2) ?? "n/d"})`;
+	logger.debug("decisions/task-routing: routed", { agent: request.agentName, model, reason });
+	return { model, tier, reason };
+}

package/src/task/index.ts

@@ -17,7 +17,7 @@ import * as os from "node:os";
 import path from "node:path";
 import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@sayknow-cli/agent-core";
 import type { Model, Usage } from "@sayknow-cli/ai";
-import { $pickenv, prompt, Snowflake } from "@sayknow-cli/utils";
+import { $pickenv, logger, prompt, Snowflake } from "@sayknow-cli/utils";
 import type { ToolSession } from "..";
 import { AsyncJobManager, OwnerSubagentShutdownError, type ResumeRunner } from "../async";
 import { resolveAgentModelPatterns } from "../config/model-resolver";
@@ -461,6 +461,62 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		return this.session.settings.get("task.simple");
 	}
 
+	/**
+	 * Pick a model for this spawn from the assignment, or null to keep the configured one.
+	 *
+	 * Opt-in twice over: `decisions.enabled` must be on *and* at least two tier
+	 * models configured. That double gate is deliberate — a user who set explicit
+	 * per-role models chose them on purpose, and silently overriding those from a
+	 * classifier would be a worse default than doing nothing.
+	 *
+	 * One decision per spawn, not per task: every task in a call runs on the same
+	 * agent and the same model, so asking per task would pay N times for a value
+	 * that can only be set once.
+	 */
+	async #routeSpawnModel(
+		agentName: string,
+		tasks: ReadonlyArray<{ description?: string; assignment?: string }> | undefined,
+		currentModel: string | readonly string[] | undefined,
+	): Promise<string | undefined> {
+		if (!this.session.settings.get("task.modelRouting.enabled")) return undefined;
+		const tiers = {
+			fast: this.session.settings.get("task.modelRouting.fastModel") || undefined,
+			balanced: this.session.settings.get("task.modelRouting.balancedModel") || undefined,
+			deep: this.session.settings.get("task.modelRouting.deepModel") || undefined,
+		};
+		const frontendModel = this.session.settings.get("task.modelRouting.frontendModel") || undefined;
+		if (Object.values(tiers).filter(Boolean).length < 2 && !frontendModel) return undefined;
+
+		const assignment = (tasks ?? [])
+			.map(task => [task.description, task.assignment].filter(Boolean).join("\n"))
+			.filter(Boolean)
+			.join("\n\n");
+		if (!assignment) return undefined;
+
+		try {
+			const { createDecisionService } = await import("../decisions");
+			const { DEFAULT_TASK_ROUTING_POLICY, routeTaskModel } = await import("../decisions/task-routing");
+			const registry = this.session.modelRegistry;
+			if (!registry) return undefined;
+			const routed = await routeTaskModel(
+				createDecisionService({ registry, settings: this.session.settings, enabled: true }),
+				{ ...DEFAULT_TASK_ROUTING_POLICY, tiers, frontendModel },
+				// A role may be configured with a fallback chain; the first entry is what it
+				// actually runs on, so that is the baseline the direction is measured from.
+				{
+					agentName,
+					assignment,
+					currentModel: Array.isArray(currentModel) ? currentModel[0] : currentModel,
+				},
+			);
+			return routed?.model;
+		} catch (error) {
+			// Routing is an optimisation. A failure here must never stop a spawn.
+			logger.debug("task: spawn model routing failed", { agent: agentName, error: String(error) });
+			return undefined;
+		}
+	}
+
 	/**
 	 * Create a TaskTool instance.
 	 * Repository authority is captured from session cwd *before* agent discovery so
@@ -1114,9 +1170,14 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		// Apply per-agent model override from settings (highest priority)
 		const agentModelOverrides = this.session.settings.get("task.agentModelOverrides");
 		const settingsModelOverride = agentModelOverrides[agentName];
+		// Per-spawn routing sits *above* the configured role model but uses it as the
+		// baseline: the decision is "is this particular assignment heavier or lighter
+		// than what this role normally gets", not "pick a model from scratch". Declining
+		// leaves the configured value exactly as it was.
+		const routedModelOverride = await this.#routeSpawnModel(agentName, boundParams.tasks, settingsModelOverride);
 		const parentActiveModelPattern = this.session.getActiveModelString?.();
 		const modelOverride = resolveAgentModelPatterns({
-			settingsOverride: settingsModelOverride,
+			settingsOverride: routedModelOverride ?? settingsModelOverride,
 			agentModel: effectiveAgent.model,
 			settings: this.session.settings,
 			activeModelPattern: parentActiveModelPattern,