@sayknow-cli/coding-agent 0.5.25 → 0.6.0

package/src/session/agent-session.ts

@@ -203,7 +203,9 @@ import type { SettingPath } from "../config/settings-schema";
 import { getDefault } from "../config/settings-schema";
 import { RawSseDebugBuffer } from "../debug/raw-sse-buffer";
 import { createDecisionService } from "../decisions";
-import { createSemanticSkillRouter, type SkillRouter } from "../decisions/skill-routing";
+import { loadLearnedKeywordDefinitions, observeRouting } from "../decisions/keyword-learning";
+import { createPromptTriage, type PromptTriager } from "../decisions/prompt-triage";
+import type { BundledSkcUiSkillName } from "../defaults/skc-ui-skills";
 import { loadCapability } from "../discovery";
 import { expandApplyPatchToEntries, normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../edit";
 import { MAX_EDIT_FILE_BYTES } from "../edit/read-file";
@@ -267,7 +269,11 @@ import {
 	detectPrimarySkillKeyword,
 	ensureWorkflowSkillActivationState,
 } from "../hooks/skill-state";
-import { buildUiSkillActivationContext } from "../hooks/ui-skill-keywords";
+import {
+	buildUiSkillActivationContext,
+	buildUiSkillDirectiveForSkill,
+	detectUiSkillKeywords,
+} from "../hooks/ui-skill-keywords";
 import { initializeLocalRoot, type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import { shutdownAll as shutdownAllLspClients } from "../lsp/client";
 import { resolveMemoryBackend } from "../memory-backend";
@@ -533,6 +539,14 @@ export interface AgentSessionConfig {
 	toolRegistry?: Map<string, AgentTool>;
 	/** Tool-session factory context used to lazily attach workflow-gate-only tools. */
 	workflowGateToolSession?: ToolSession;
+	/**
+	 * Stage two of workflow routing: before a genuine user turn, ask a small model
+	 * through the session's own transport which SKC workflow the prompt calls for.
+	 * Hosts that own an interactive user (`createAgentSession`) turn this on; a bare
+	 * session leaves it off so a scripted or injected transport is never consumed by a
+	 * call the host did not script. `decisions.enabled` still governs the user side.
+	 */
+	semanticWorkflowRouting?: boolean;
 	/** Current session pre-LLM message transform pipeline */
 	transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => AgentMessage[] | Promise<AgentMessage[]>;
 	/** Provider payload hook used by the active session request path */
@@ -1851,11 +1865,18 @@ export class AgentSession {
 	#modelRegistry: ModelRegistry;
 
 	/** Built on first use; the decision service resolves model and credential lazily. */
-	#semanticSkillRouter?: SkillRouter;
+	#promptTriager?: PromptTriager;
+
+	/**
+	 * UI skill the semantic stage picked for this turn, when the regex table did
+	 * not. Cleared per prompt: it describes one sentence, not the session.
+	 */
+	#semanticUiSkill?: BundledSkcUiSkillName;
 
 	// Tool registry and prompt builder for extensions
 	#toolRegistry: Map<string, AgentTool>;
 	#workflowGateToolSession: ToolSession | undefined;
+	#semanticWorkflowRouting: boolean;
 	#transformContext: (messages: AgentMessage[], signal?: AbortSignal) => AgentMessage[] | Promise<AgentMessage[]>;
 	#onPayload: SimpleStreamOptions["onPayload"] | undefined;
 	#onResponse: SimpleStreamOptions["onResponse"] | undefined;
@@ -1979,6 +2000,12 @@ export class AgentSession {
 		nonEditDeterminations: 0,
 	};
 	#promptInFlightCount = 0;
+	/**
+	 * A genuine user prompt is being routed to a workflow before its turn starts. Counts
+	 * as streaming so a second `prompt()` queues or rejects exactly as it would mid-turn,
+	 * and `abort()` cancels the routing through the preflight signal.
+	 */
+	#workflowRoutingInFlight = false;
 	#agentEventHandlersInFlight = 0;
 	#queuedExtensionEventCount = 0;
 	#extensionTurnGeneration = 0;
@@ -2405,6 +2432,7 @@ export class AgentSession {
 		}
 		this.#toolRegistry = config.toolRegistry ?? new Map();
 		this.#workflowGateToolSession = config.workflowGateToolSession;
+		this.#semanticWorkflowRouting = config.semanticWorkflowRouting ?? false;
 		this.#requestedToolNames = config.requestedToolNames;
 		this.#explicitlyDisabledTools = config.explicitlyDisabledTools === true;
 		this.#transformContext = config.transformContext ?? (messages => messages);
@@ -5497,7 +5525,7 @@ export class AgentSession {
 
 	/** Whether agent is currently streaming a response */
 	get isStreaming(): boolean {
-		return this.agent.state.isStreaming || this.#promptInFlightCount > 0;
+		return this.agent.state.isStreaming || this.#promptInFlightCount > 0 || this.#workflowRoutingInFlight;
 	}
 
 	/** Wait until streaming and session settlement work are fully settled. */
@@ -7560,55 +7588,112 @@ export class AgentSession {
 	 * @throws Error if no model selected or no API key available (when not streaming)
 	 */
 	/**
-	 * Semantic workflow routing for prompts the keyword table cannot express.
+	 * Per-turn prompt triage: every routing question SKC asks about a user's
+	 * sentence, answered in one place.
 	 *
 	 * Runs in this process, not the hook process: the hook only receives paths and
 	 * config, so it has no model registry and no credentials to call anything with.
 	 *
-	 * **The keyword table is not consulted here, and that is deliberate.** An earlier
-	 * version returned early on a keyword hit, on the assumption that the deterministic
-	 * stage had already activated the workflow. That assumption holds only under the
-	 * Codex host, where `skc codex-native-hook` runs on `UserPromptSubmit`. This session
-	 * never fires that hook, so the early return meant a prompt containing an enumerated
-	 * keyword activated *nothing at all* — strictly worse than before the keywords
-	 * existed, because the semantic stage had been handling those phrasings.
+	 * Three stages, cheapest first, and each one shrinks the next:
+	 *
+	 * 1. **Hand-written tables.** The eighteen workflow keywords and the twenty UI
+	 *    regexes. Free, deterministic, measured at zero false positives, so they
+	 *    are not gated behind the opt-in setting.
+	 * 2. **Learned patterns.** Two-stem rules mined from previous semantic answers
+	 *    (`decisions/keyword-learning.ts`). Also free, also deterministic, and the
+	 *    reason a phrasing the user repeats stops costing a model call.
+	 * 3. **One typed decision** for whatever stages 1 and 2 left unanswered. Both
+	 *    questions ride the same call, so adding UI routing cost no round trip.
 	 *
-	 * Keywords remain advisory in this host, as they always were: the routing rules in
-	 * the system prompt describe them to the model. Only this stage activates, and only
-	 * when it is confident enough to be worth the mutation guard and Stop hook that
-	 * activation switches on.
+	 * Whatever stage three answers is fed back into stage two, which is what makes
+	 * the keyword table self-populating rather than a list somebody has to grow by
+	 * hand — the original list recalled 0/9 on Korean prompts for exactly that
+	 * reason.
 	 *
-	 * Deliberately best-effort — a disabled setting, a missing credential, a timeout, a
-	 * nonsense answer or low confidence all resolve to "no activation", which is
-	 * precisely the behaviour before this stage existed.
+	 * Keyword hits activate here rather than returning early. An earlier version
+	 * returned early on the assumption that the deterministic stage had already
+	 * activated the workflow, which holds only under the Codex host where `skc
+	 * codex-native-hook` runs on `UserPromptSubmit`. This session never fires that
+	 * hook, so the early return meant an enumerated keyword activated *nothing*.
+	 *
+	 * Deliberately best-effort — a disabled setting, a missing credential, a
+	 * timeout, a nonsense answer or low confidence all resolve to "no activation",
+	 * which is precisely the behaviour before this stage existed.
 	 */
-	async #routeWorkflowSemantically(text: string): Promise<void> {
-		// Stage one: the keyword table. Free, deterministic, and measured at zero false
-		// positives, so it is not gated behind the opt-in setting — gating it was why an
-		// enumerated phrase activated nothing in this host while the Codex hook activated
-		// it fine. Activating here makes the two hosts agree.
-		const keyword = detectPrimarySkillKeyword(text);
+	async #routeWorkflowSemantically(text: string, signal: AbortSignal): Promise<void> {
+		this.#semanticUiSkill = undefined;
+		const learningEnabled = this.settings.get("decisions.keywordLearning");
+		// Loaded per turn rather than cached on the session: a second session in the
+		// same repo promotes patterns too, and a user who watched one get learned
+		// expects the next prompt to use it, not the next restart.
+		const learned = learningEnabled ? await loadLearnedKeywordDefinitions() : [];
+		const keyword = detectPrimarySkillKeyword(text, learned);
 		if (keyword) {
+			logger.debug("agent-session: workflow keyword match", {
+				skill: keyword.skill,
+				learned: keyword.learned === true,
+			});
 			await this.#activateWorkflowSkill(keyword.skill);
-			return;
 		}
-
-		// Stage two costs a model call, so it stays opt-in.
-		if (!this.settings.get("decisions.enabled")) return;
+		// The regex table answers the UI question for free when it matches; asking
+		// the model as well would pay for an answer already in hand.
+		const uiMatched = detectUiSkillKeywords(text).length > 0;
+		if (keyword && uiMatched) return;
+
+		// Stage three costs a model call: the host must have opted the session in and
+		// the user must not have turned the setting (on by default) off.
+		if (!this.#semanticWorkflowRouting || !this.settings.get("decisions.enabled")) return;
+		// Only the model call counts as streaming. Flagging the keyword stage too made
+		// `isStreaming` flicker true for one microtask on every prompt, which a poller
+		// mistook for the turn having started.
+		this.#workflowRoutingInFlight = true;
 		try {
-			this.#semanticSkillRouter ??= createSemanticSkillRouter(
+			this.#promptTriager ??= createPromptTriage(
 				createDecisionService({
 					registry: this.#modelRegistry,
 					settings: this.settings,
 					sessionId: this.sessionManager.getSessionId(),
+					preferredProvider: () => this.model?.provider,
+					// The turn's own transport, not a bare `completeSimple`: the same proxy,
+					// credential-invalidation and retry wrapping the main request gets, and
+					// a host that injects a stream function (tests, embedders) intercepts the
+					// decision too instead of watching it go to the network behind its back.
+					completeImpl: async (model, context, options) =>
+						(await this.agent.streamFn(model, context, options)).result(),
 					enabled: true,
 				}),
 			);
-			const skill = await this.#semanticSkillRouter(text);
-			if (!skill) return;
-			await this.#activateWorkflowSkill(skill);
+			const started = Date.now();
+			const triage = await this.#promptTriager({
+				text,
+				skipWorkflow: Boolean(keyword),
+				skipUiSkill: uiMatched,
+				signal,
+			});
+			logger.debug("agent-session: prompt triage", {
+				workflow: triage?.workflow ?? null,
+				uiSkill: triage?.uiSkill ?? null,
+				durationMs: Date.now() - started,
+			});
+			if (!triage || signal.aborted) return;
+			if (triage.uiSkill) this.#semanticUiSkill = triage.uiSkill;
+			if (keyword) return;
+			if (triage.workflow) await this.#activateWorkflowSkill(triage.workflow);
+			if (learningEnabled) {
+				// Awaited, not fired and forgotten: an unawaited write racing the next
+				// turn's read is how a learned pattern gets lost on the prompt that was
+				// supposed to promote it. The store is a few KB and already in memory.
+				await observeRouting({
+					text,
+					skill: triage.workflow,
+					confidence: triage.workflowConfidence,
+					calibrated: triage.calibrated,
+				});
+			}
 		} catch (error) {
-			logger.debug("agent-session: semantic workflow routing failed", { error: String(error) });
+			logger.debug("agent-session: prompt triage failed", { error: String(error) });
+		} finally {
+			this.#workflowRoutingInFlight = false;
 		}
 	}
 
@@ -7701,7 +7786,12 @@ export class AgentSession {
 		// deep-interview with the setting off and ralplan with it on. Both are plausible
 		// readings and ralplan is the better one here, but the point is that enabling this
 		// can *change* an activation rather than only add one where there was none.
-		if (claimsGenuineUserIntent && !this.isStreaming) await this.#routeWorkflowSemantically(expandedText);
+		if (claimsGenuineUserIntent && !this.isStreaming) {
+			const routingGeneration = this.#promptGeneration;
+			const routingSignal = this.#promptPreflightAbortController.signal;
+			await this.#routeWorkflowSemantically(expandedText, routingSignal);
+			this.#throwIfPromptPreflightCancelled(routingGeneration, routingSignal);
+		}
 
 		// If streaming, queue via steer() or followUp() based on option
 		if (this.isStreaming) {
@@ -12033,12 +12123,22 @@ export class AgentSession {
 	 * still there — while a wrong match would load a design skill onto a database task.
 	 * That asymmetry is why a reminder is the right shape here and a forced tool call is
 	 * not.
+	 *
+	 * The three frontend prompts the patterns missed are now covered by the typed
+	 * decision in `#routeWorkflowSemantically`, which rides the same call as workflow
+	 * routing and therefore costs nothing extra. The patterns stay in front of it: when
+	 * they match, the model is never asked.
 	 */
 	#createUiSkillPrelude(promptText: string): AgentMessage | undefined {
 		if (this.#planModeState?.enabled) return undefined;
-		const directive = buildUiSkillActivationContext(promptText);
+		const matched = buildUiSkillActivationContext(promptText);
+		const directive =
+			matched ?? (this.#semanticUiSkill ? buildUiSkillDirectiveForSkill(this.#semanticUiSkill) : null);
 		if (!directive) return undefined;
-		logger.debug("agent-session: bundled UI skill matched", { promptChars: promptText.length });
+		logger.debug("agent-session: bundled UI skill matched", {
+			promptChars: promptText.length,
+			source: matched ? "pattern" : "semantic",
+		});
 		return {
 			role: "developer",
 			content: [{ type: "text", text: `<system-reminder>\n${directive}\n</system-reminder>` }],

package/src/session/auth-storage-discovery.ts

@@ -0,0 +1,83 @@
+/**
+ * Credential store discovery, on its own so a short-lived process can open the
+ * store without importing the SDK.
+ *
+ * `sdk/session.ts` re-exports `discoverAuthStorage` and remains the public entry
+ * point. Measured: importing `sdk/session` costs ~400ms of module graph; the
+ * Codex prompt hook runs once per prompt and already spends 260ms, so it opens
+ * credentials through this file instead.
+ */
+import { getAgentDbPath, getAgentDir } from "@sayknow-cli/utils";
+import { resolveConfigValue } from "../config/resolve-config-value";
+import { resolveAuthBrokerConfig } from "./auth-broker-config";
+import { AuthBrokerClient, AuthStorage, RemoteAuthCredentialStore } from "./auth-storage";
+
+/**
+ * Create an AuthStorage instance.
+ *
+ * Default: local SQLite store at `<agentDir>/agent.db`.
+ *
+ * Broker mode: when `SKC_AUTH_BROKER_URL` is set, credentials are pulled from
+ * a remote auth-broker over the wire. Refresh tokens never leave the broker;
+ * the client receives access tokens with `refresh = "__remote__"` and calls
+ * back into the broker through the {@link AuthStorageOptions.refreshOAuthCredential}
+ * override to re-mint access tokens when needed.
+ */
+export async function discoverAuthStorage(agentDir: string = getAgentDir()): Promise<AuthStorage> {
+	const brokerConfig = await resolveAuthBrokerConfig();
+	const credentialRankingMode = resolveCredentialRankingMode();
+	if (brokerConfig) {
+		const client = new AuthBrokerClient({ url: brokerConfig.url, token: brokerConfig.token });
+		const initialResult = await client.fetchSnapshot();
+		if (initialResult.status !== 200) throw new Error("Auth broker returned no initial snapshot");
+		const store = new RemoteAuthCredentialStore({ client, initialSnapshot: initialResult.snapshot });
+		// Refresh + usage hooks live on RemoteAuthCredentialStore; AuthStorage
+		// discovers them automatically when no explicit option overrides them.
+		const storage = new AuthStorage(store, {
+			configValueResolver: resolveConfigValue,
+			sourceLabel: `broker ${brokerConfig.url}`,
+			credentialRankingMode,
+		});
+		try {
+			await storage.reload();
+		} catch (error) {
+			try {
+				storage.close();
+			} catch {
+				// Preserve the initial reload failure.
+			}
+			throw error;
+		}
+		return storage;
+	}
+	const dbPath = getAgentDbPath(agentDir);
+	const storage = await AuthStorage.create(dbPath, {
+		configValueResolver: resolveConfigValue,
+		sourceLabel: `local ${dbPath}`,
+		credentialRankingMode,
+	});
+	try {
+		await storage.reload();
+	} catch (error) {
+		try {
+			storage.close();
+		} catch {
+			// Preserve the initial reload failure.
+		}
+		throw error;
+	}
+	return storage;
+}
+
+/**
+ * Opt-in multi-account credential ranking mode, read from the
+ * `SKC_CREDENTIAL_RANKING_MODE` env var. Unset/unknown → `undefined`, leaving
+ * {@link AuthStorage}'s default (`balanced`) untouched. `earliest-reset`
+ * switches to earliest-expiry-first selection so soon-to-reset tumbling-window
+ * quota is drained before it is lost.
+ */
+function resolveCredentialRankingMode(): "balanced" | "earliest-reset" | undefined {
+	const raw = process.env.SKC_CREDENTIAL_RANKING_MODE?.trim();
+	if (raw === "balanced" || raw === "earliest-reset") return raw;
+	return undefined;
+}

package/src/slash-commands/builtin-registry.ts

@@ -360,9 +360,8 @@ async function resolveModelCommandSelection(
 	}
 
 	const providerRef = parseProviderQualifiedSelector(selector);
-	const discoverableProviders = runtime.session.modelRegistry?.getDiscoverableProviders?.() ?? [];
-	if (providerRef && discoverableProviders.includes(providerRef.provider)) {
-		await runtime.session.modelRegistry.refreshProvider?.(providerRef.provider, "online");
+	if (providerRef && runtime.session.modelRegistry?.refreshProvider) {
+		await runtime.session.modelRegistry.refreshProvider(providerRef.provider, "online");
 		availableModels = runtime.session.getAvailableModels?.() ?? [];
 		const refreshedSelection = resolveModelCommandSelectionFromAvailable(
 			runtime,
@@ -372,12 +371,15 @@ async function resolveModelCommandSelection(
 		if (refreshedSelection) {
 			return { ok: true, selection: refreshedSelection };
 		}
-		return {
-			ok: false,
-			failure: {
-				message: formatDiscoverableProviderFailure(selector, providerRef.provider, providerRef.modelId, runtime),
-			},
-		};
+		const discoverableProviders = runtime.session.modelRegistry.getDiscoverableProviders?.() ?? [];
+		if (discoverableProviders.includes(providerRef.provider)) {
+			return {
+				ok: false,
+				failure: {
+					message: formatDiscoverableProviderFailure(selector, providerRef.provider, providerRef.modelId, runtime),
+				},
+			};
+		}
 	}
 
 	return {

package/src/task/index.ts

@@ -21,6 +21,9 @@ 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";
+import { normalizeModelSelectorValue } from "../config/model-selector-value";
+import type { TaskModelSpecialty } from "../config/task-model-specialties";
+import type { TaskRoutingResult } from "../decisions/task-routing";
 import type { Theme } from "../modes/theme/theme";
 import planModeSubagentPrompt from "../prompts/system/plan-mode-subagent.md" with { type: "text" };
 import taskDescriptionTemplate from "../prompts/tools/task.md" with { type: "text" };
@@ -37,6 +40,7 @@ import {
 	type SingleResult,
 	type TaskItem,
 	type TaskParams,
+	type TaskRoutingAttribution,
 	type TaskToolDetails,
 	type TaskToolSchemaInstance,
 } from "./types";
@@ -212,6 +216,7 @@ export type {
 	SubagentLifecyclePayload,
 	SubagentProgressPayload,
 	TaskParams,
+	TaskRoutingAttribution,
 	TaskToolDetails,
 } from "./types";
 export {
@@ -462,54 +467,80 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 	}
 
 	/**
-	 * Pick a model for this spawn from the assignment, or null to keep the configured one.
+	 * Route a child whose caller declared the kind of work.
 	 *
-	 * 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.
+	 * Deterministic by design: no classifier, no `task.modelRouting.enabled`
+	 * gate. The user assigned a model to this specialty in `/model`; if the caller
+	 * says the work is that specialty, the child runs on that model and leaves it
+	 * only when it errors — the child session's fallback chain advances to the
+	 * role baseline composed behind it.
+	 */
+	async #routeDeclaredSpecialty(
+		agentName: string,
+		specialty: TaskModelSpecialty,
+		baselineChain: readonly string[],
+	): Promise<TaskRoutingResult | undefined> {
+		try {
+			const { resolveDeclaredSpecialtyRouting } = await import("../decisions/task-routing");
+			return (
+				resolveDeclaredSpecialtyRouting(this.session.settings, {
+					agentName,
+					specialty,
+					currentModel: baselineChain[0],
+					baselineChain,
+				}) ?? undefined
+			);
+		} catch (error) {
+			// A declared specialty with nothing behind it still spawns on the role model.
+			logger.debug("task: declared specialty routing failed", { agent: agentName, specialty, error: String(error) });
+			return undefined;
+		}
+	}
+
+	/**
+	 * Pick a model for one child assignment, or undefined to keep the configured one.
 	 *
-	 * 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.
+	 * This is the *guessing* half: a classifier reads the assignment and decides.
+	 * Opt-in twice over: `task.modelRouting.enabled` must be on *and* an axis must
+	 * have something to move on. 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. A caller that
+	 * *knows* the kind of work declares it instead (`#routeDeclaredSpecialty`).
+	 *
+	 * One decision per *child*, not per call. Every task in a call shares an agent,
+	 * but not a workload: a batch can hold an implementation slice and a test slice,
+	 * and a single joined classification would have to answer for both at once.
 	 */
 	async #routeSpawnModel(
 		agentName: string,
-		tasks: ReadonlyArray<{ description?: string; assignment?: string }> | undefined,
-		currentModel: string | readonly string[] | undefined,
-	): Promise<string | undefined> {
+		assignment: string | undefined,
+		baselineChain: readonly string[],
+	): Promise<TaskRoutingResult | undefined> {
+		// Cheap guard before the dynamic import so a disabled feature costs nothing.
 		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;
+		const trimmed = assignment?.trim();
+		if (!trimmed) return undefined;
 
 		try {
 			const { createDecisionService } = await import("../decisions");
-			const { DEFAULT_TASK_ROUTING_POLICY, routeTaskModel } = await import("../decisions/task-routing");
+			const { buildTaskRoutingPolicyFromSettings, routeTaskModel } = await import("../decisions/task-routing");
+			const policy = buildTaskRoutingPolicyFromSettings(this.session.settings);
+			if (!policy) return undefined;
 			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.
+				policy,
 				{
 					agentName,
-					assignment,
-					currentModel: Array.isArray(currentModel) ? currentModel[0] : currentModel,
+					assignment: trimmed,
+					// 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.
+					currentModel: baselineChain[0],
+					baselineChain,
 				},
 			);
-			return routed?.model;
+			return routed ?? undefined;
 		} 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) });
@@ -1170,19 +1201,18 @@ 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);
+		// The role's own resolved chain. Per-child routing composes *in front of* this
+		// and never replaces it: a specialty or tier that cannot be authenticated must
+		// still fall through to the model the role would have used anyway.
 		const parentActiveModelPattern = this.session.getActiveModelString?.();
 		const modelOverride = resolveAgentModelPatterns({
-			settingsOverride: routedModelOverride ?? settingsModelOverride,
+			settingsOverride: settingsModelOverride,
 			agentModel: effectiveAgent.model,
 			settings: this.session.settings,
 			activeModelPattern: parentActiveModelPattern,
 			fallbackModelPattern: this.session.getModelString?.(),
 		});
+		const baselineChain = normalizeModelSelectorValue(modelOverride);
 		const thinkingLevelOverride = effectiveAgent.thinkingLevel;
 
 		// Output schema priority: task call > agent frontmatter > inherited parent session.
@@ -1474,6 +1504,28 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					sessionFile?: string | null;
 				},
 			) => {
+				// Route THIS child. A declared specialty is deterministic; otherwise a
+				// batch shares an agent but not a workload, so a joined classification
+				// would have to answer for an implementation slice and a test slice at
+				// the same time.
+				const routed = task.specialty
+					? await this.#routeDeclaredSpecialty(agentName, task.specialty, baselineChain)
+					: await this.#routeSpawnModel(agentName, task.assignment, baselineChain);
+				const taskModelOverride = routed ? routed.candidates.map(candidate => candidate.selector) : modelOverride;
+				// Requested, not effective: the chain above can still fall through to a
+				// later candidate, so this records intent and nothing more.
+				const taskRouting: TaskRoutingAttribution | undefined = routed
+					? {
+							source: routed.requestedSource,
+							specialty: routed.requestedSpecialty,
+							tier: routed.requestedTier,
+							declared: routed.declared,
+							calibrated: routed.calibrated,
+							confidence: routed.confidence,
+							ordinalStrength: routed.ordinalStrength,
+							reason: routed.reason,
+						}
+					: undefined;
 				const forkContextSeed = prebuiltForkContextSeeds?.get(task.id) ?? (await buildForkContextSeed(task));
 				const forkContext = requestsForkContext(task)
 					? { mode: task.inheritContext, clonedTokens: forkContextSeed?.metadata.approximateTokens ?? 0 }
@@ -1516,7 +1568,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						resumeMessage: overrides?.resumeMessage ?? executionOverrides?.resumeMessage,
 						subagentId: task.id,
 						taskDepth,
-						modelOverride,
+						modelOverride: taskModelOverride,
 						parentActiveModelPattern,
 						parentSessionId: this.session.getSessionId?.() ?? undefined,
 						thinkingLevel: thinkingLevelOverride,
@@ -1533,6 +1585,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						onProgress: progress => {
 							progressMap.set(index, {
 								...structuredClone(progress),
+								modelOverride: taskModelOverride,
+								...(taskRouting ? { routing: taskRouting } : {}),
 							});
 							AsyncJobManager.instance()?.recordSubagentProgress(task.id, progress);
 							emitProgress();
@@ -1589,7 +1643,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						resumeMessage: overrides?.resumeMessage ?? executionOverrides?.resumeMessage,
 						subagentId: task.id,
 						taskDepth,
-						modelOverride,
+						modelOverride: taskModelOverride,
 						parentActiveModelPattern,
 						parentSessionId: this.session.getSessionId?.() ?? undefined,
 						thinkingLevel: thinkingLevelOverride,
@@ -1606,6 +1660,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						onProgress: progress => {
 							progressMap.set(index, {
 								...structuredClone(progress),
+								modelOverride: taskModelOverride,
+								...(taskRouting ? { routing: taskRouting } : {}),
 							});
 							AsyncJobManager.instance()?.recordSubagentProgress(task.id, progress);
 							emitProgress();
@@ -1629,6 +1685,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					const resultWithForkContext = {
 						...result,
 						...(forkContext ? { forkContext } : {}),
+						...(taskRouting ? { routing: taskRouting } : {}),
 						forkContextAdvisory,
 						repositoryBinding: publicRepositoryBinding(taskRepositoryBinding),
 					};
@@ -1709,7 +1766,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						truncated: false,
 						durationMs: Date.now() - taskStart,
 						tokens: 0,
-						modelOverride,
+						modelOverride: taskModelOverride,
+						...(taskRouting ? { routing: taskRouting } : {}),
 						forkContext,
 						error: message,
 					};

package/src/task/receipt.ts

@@ -28,6 +28,8 @@ export interface TaskResultReceipt {
 	contextTokens?: number;
 	contextWindow?: number;
 	modelOverride?: string | string[];
+	/** What the router asked for, kept separate from what the spawn ran on. */
+	routing?: SingleResult["routing"];
 	modelSubstitutionWarning?: SingleResult["modelSubstitutionWarning"];
 	usage?: SingleResult["usage"];
 	cost?: number;
@@ -245,6 +247,7 @@ export function buildTaskReceipt(raw: SingleResult): TaskResultReceipt {
 		contextTokens: raw.contextTokens,
 		contextWindow: raw.contextWindow,
 		modelOverride: raw.modelOverride,
+		routing: raw.routing,
 		modelSubstitutionWarning: raw.modelSubstitutionWarning,
 		usage: raw.usage,
 		cost: raw.usage?.cost.total,