@sayknow-cli/coding-agent 0.5.23 → 0.5.24

package/CHANGELOG.md

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

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

@@ -2421,6 +2421,42 @@ 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: "";
+    };
     readonly "ttsr.enabled": {
         readonly type: "boolean";
         readonly default: true;

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

@@ -0,0 +1,44 @@
+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;
+}
+export declare const DEFAULT_TASK_ROUTING_POLICY: Omit<TaskRoutingPolicy, "tiers">;
+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;
+    tier: TaskTier;
+    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.24",
 	"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.24",
+		"@sayknow-cli/agent-core": "0.5.24",
+		"@sayknow-cli/ai": "0.5.24",
+		"@sayknow-cli/natives": "0.5.24",
+		"@sayknow-cli/tui": "0.5.24",
+		"@sayknow-cli/utils": "0.5.24",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/config/settings-schema.ts

@@ -2011,6 +2011,35 @@ 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: "" },
+
 	// TTSR
 	"ttsr.enabled": {
 		type: "boolean",

package/src/decisions/task-routing.ts

@@ -0,0 +1,196 @@
+/**
+ * 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;
+}
+
+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,
+};
+
+/**
+ * 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?",
+		},
+	};
+}
+
+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;
+	tier: TaskTier;
+	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]);
+	// One tier is not a ladder; with nothing to move between there is no decision
+	// worth paying a model call for.
+	if (configured.length < 2) 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;
+
+	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,61 @@ 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,
+		};
+		if (Object.values(tiers).filter(Boolean).length < 2) 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 },
+				// 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 +1169,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,