@sayknow-cli/coding-agent 0.5.22 → 0.5.24

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [0.5.24] - 2026-09-21
+
 ## [0.5.22] - 2026-09-19
 
 ### Added

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

@@ -2418,9 +2418,45 @@ export declare const SETTINGS_SCHEMA: {
         readonly ui: {
             readonly tab: "context";
             readonly label: "Typed decisions";
-            readonly description: "Let a cheap model answer typed questions the deterministic rules cannot. Currently routes workflow skills when the keyword table finds nothing — which is every non-English phrasing. Costs one small model call on those prompts; every failure falls back to today's behaviour.";
+            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/skill-routing.d.ts

@@ -1,5 +1,7 @@
 import { type CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
 import type { DecisionService } from "./index";
+/** Exported so tests can assert the contract the model is actually given. */
+export declare function buildRoutingCriteria(): Record<string, string>;
 export type SkillRouter = (text: string) => Promise<CanonicalSkcWorkflowSkill | null>;
 /**
  * Build the semantic router. Returns null-resolving function when the service is

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/dist/types/modes/controllers/selector-controller.d.ts

@@ -81,6 +81,15 @@ export declare class SelectorController {
     }): void;
     showCommandPalette(commands: SlashCommand[], actions: CommandPaletteAction[], executeSlashCommand: (name: string) => Promise<void>): void;
     showProviderOnboarding(): void;
+    /**
+     * Take a TypeSafe key and verify it before storing.
+     *
+     * Verification is not optional here. The decision service fails open by design, so an
+     * unverified bad key produces no error anywhere: decisions silently keep coming from
+     * the user's own model while the UI claims TypeSafe is on. Better to keep the prompt
+     * open and say the key was rejected.
+     */
+    showTypeSafeKeyPrompt(): void;
     showCustomModelPresetWizard(snapshot: ModelProfileConfig): void;
     showCustomProviderWizard(): void;
     showEffortSelector(): void;

package/dist/types/modes/interactive-mode.d.ts

@@ -264,6 +264,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
         temporaryOnly?: boolean;
     }): void;
     showEffortSelector(): void;
+    showTypeSafeKeyPrompt(): void;
     showProviderOnboarding(): void;
     showPluginSelector(mode?: "install" | "uninstall"): void;
     showUserMessageSelector(): void;

package/dist/types/modes/types.d.ts

@@ -280,6 +280,8 @@ export interface InteractiveModeContext {
     }): void;
     showEffortSelector(): void;
     showProviderOnboarding(): void;
+    /** Open the TypeSafe key prompt (typed decisions; not a chat model). */
+    showTypeSafeKeyPrompt(): void;
     showPluginSelector(mode?: "install" | "uninstall"): void;
     showUserMessageSelector(): void;
     showTreeSelector(): void;

package/dist/types/setup/model-onboarding-guidance.d.ts

@@ -2,6 +2,11 @@ export declare const MODEL_ONBOARDING_API_PROVIDER_COMMAND = "/provider add --co
 export declare const MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND = "/provider add --preset <minimax|minimax-cn|glm>";
 export declare const MODEL_ONBOARDING_SETUP_COMMAND = "skc setup provider";
 export declare const MODEL_ONBOARDING_OAUTH_COMMAND = "/provider login [provider-id] or /login [provider-id]";
+/**
+ * TypeSafe is not a chat model and never appears in the model list, so the only way a
+ * user learns it exists is from the surfaces where they go to add credentials.
+ */
+export declare const MODEL_ONBOARDING_TYPESAFE_COMMAND = "/provider typesafe";
 export declare function formatModelOnboardingGuidance(): string;
 export declare function formatModelOnboardingInlineHint(): string;
 export declare function formatNoModelOnboardingError(): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/coding-agent",
-	"version": "0.5.22",
+	"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.22",
-		"@sayknow-cli/agent-core": "0.5.22",
-		"@sayknow-cli/ai": "0.5.22",
-		"@sayknow-cli/natives": "0.5.22",
-		"@sayknow-cli/tui": "0.5.22",
-		"@sayknow-cli/utils": "0.5.22",
+		"@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/scripts/eval-skill-routing.ts

@@ -126,12 +126,12 @@ async function main(): Promise<void> {
 
 	console.log("\n=== stage comparison ===");
 	for (const [label, pick] of [
-		["keyword only (today)", (row: (typeof rows)[number]) => row.keyword],
-		["semantic only", (row: (typeof rows)[number]) => row.semantic],
-		["hybrid (shipped)", hybrid],
+		["keyword only (Codex hook)", (row: (typeof rows)[number]) => row.keyword],
+		["semantic only (SHIPPED)", (row: (typeof rows)[number]) => row.semantic],
+		["keyword+semantic (upper bound)", hybrid],
 	] as const) {
 		console.log(
-			`${label.padEnd(22)} all ${pct(...score(pick, () => true))}  ko ${pct(...score(pick, ko))}  en ${pct(...score(pick, en))}  clean-negatives ${pct(...score(pick, negatives))}`,
+			`${label.padEnd(32)} all ${pct(...score(pick, () => true))}  ko ${pct(...score(pick, ko))}  en ${pct(...score(pick, en))}  clean-negatives ${pct(...score(pick, negatives))}`,
 		);
 	}
 
@@ -140,12 +140,13 @@ async function main(): Promise<void> {
 		`\nlatency p50 ${latencies[Math.floor(latencies.length / 2)]}ms  p95 ${latencies[Math.max(0, Math.ceil(latencies.length * 0.95) - 1)]}ms  max ${latencies.at(-1)}ms`,
 	);
 
-	const misses = rows.filter(row => hybrid(row) !== row.case.expect);
+	// Report against what actually ships in this host, not against the upper bound.
+	const misses = rows.filter(row => row.semantic !== row.case.expect);
 	if (misses.length > 0) {
-		console.log("\n=== hybrid misses ===");
+		console.log("\n=== misses in shipped configuration (semantic only) ===");
 		for (const row of misses)
 			console.log(
-				`  [${row.case.lang}] want=${row.case.expect ?? "none"} got=${hybrid(row) ?? "none"} :: ${row.case.prompt}`,
+				`  [${row.case.lang}] want=${row.case.expect ?? "none"} got=${row.semantic ?? "none"} :: ${row.case.prompt}`,
 			);
 	}
 

package/src/config/settings-schema.ts

@@ -2007,10 +2007,39 @@ export const SETTINGS_SCHEMA = {
 			tab: "context",
 			label: "Typed decisions",
 			description:
-				"Let a cheap model answer typed questions the deterministic rules cannot. Currently routes workflow skills when the keyword table finds nothing — which is every non-English phrasing. Costs one small model call on those prompts; every failure falls back to today's behaviour.",
+				"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.
+	 */
+	"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/skill-routing.ts

@@ -26,8 +26,13 @@ const NONE = "none";
  * are the whole contract with the model — the enum ids alone carry almost no signal.
  */
 const WORKFLOW_MEANINGS: Record<CanonicalSkcWorkflowSkill, string> = {
+	// Scoped to the *behaviour* the user is asking for, not only to the state of the
+	// request. The earlier wording ("vague about what to build") described a property of
+	// the spec, so a direct instruction to ask rather than assume — the request is not
+	// vague, it is an order about how to proceed — landed on `none`. Measured: that one
+	// prompt was the sole miss in the 23-case set.
 	"deep-interview":
-		"The request is vague about what to build. The user wants to be interviewed and have requirements elicited before anything is designed or written.",
+		"The user wants requirements drawn out of them by questioning before anything is built. Includes explicit instructions to ask rather than assume.",
 	ralplan:
 		"The user wants a deliberate plan, design comparison, or approval before any code is touched. Architecture or sequencing risk is involved.",
 	ultragoal:
@@ -38,7 +43,8 @@ const WORKFLOW_MEANINGS: Record<CanonicalSkcWorkflowSkill, string> = {
 const ROUTING_INSTRUCTIONS =
 	"Which workflow should handle this user request? Choose none unless the request clearly calls for one of the workflows.";
 
-function buildCriteria(): Record<string, string> {
+/** Exported so tests can assert the contract the model is actually given. */
+export function buildRoutingCriteria(): Record<string, string> {
 	const criteria: Record<string, string> = {};
 	for (const skill of CANONICAL_SKC_WORKFLOW_SKILLS) criteria[skill] = WORKFLOW_MEANINGS[skill];
 	criteria[NONE] =
@@ -51,6 +57,30 @@ const MIN_PROMPT_CHARS = 12;
 /** Only the opening of a prompt decides its workflow; the rest is payload. */
 const MAX_PROMPT_CHARS = 4_000;
 
+/**
+ * Minimum calibrated confidence required to activate a workflow.
+ *
+ * Activation is a strong move: it switches on the mutation guard, the Stop hook and the
+ * ask tool. Getting it wrong is worse than missing, because the user did not ask for any
+ * of that and has no obvious way to see why it appeared.
+ *
+ * Measured over ten routing prompts against the hosted model: every answer it reported
+ * at 1.00 was correct, and its single wrong answer reported 0.71. The lowest *correct*
+ * confidence was 0.67 — and that case was "none", so gating it out costs nothing. A
+ * floor here therefore removes the observed error without removing a real activation.
+ *
+ * One prompt sits close to this line. "추측하지 말고 모르는 건 다 물어봐" resolves to
+ * deep-interview in 8/8 samples but at 0.76-0.83, so the floor has roughly 0.01 of
+ * headroom on it. Raising the floor would drop a correct activation; lowering it would
+ * re-admit the 0.71 error. Treat 0.75 as fitted to a small sample and re-derive it from
+ * real usage rather than nudging it on a hunch.
+ *
+ * Only applied when the backend reports `calibrated: true`. An ordinary LLM answering
+ * through a forced enum has no meaningful confidence to compare against, so gating on a
+ * number it did not really produce would just be superstition.
+ */
+const MIN_CALIBRATED_CONFIDENCE = 0.75;
+
 export type SkillRouter = (text: string) => Promise<CanonicalSkcWorkflowSkill | null>;
 
 /**
@@ -58,7 +88,7 @@ export type SkillRouter = (text: string) => Promise<CanonicalSkcWorkflowSkill |
  * disabled so the caller keeps its existing behaviour with no branching.
  */
 export function createSemanticSkillRouter(service: DecisionService): SkillRouter {
-	const criteria = buildCriteria();
+	const criteria = buildRoutingCriteria();
 	return async (text: string): Promise<CanonicalSkcWorkflowSkill | null> => {
 		if (!service.enabled) return null;
 		const trimmed = text.trim();
@@ -73,9 +103,19 @@ export function createSemanticSkillRouter(service: DecisionService): SkillRouter
 		if (!result || answer?.type !== "choice" || answer.choice === NONE) return null;
 		const skill = CANONICAL_SKC_WORKFLOW_SKILLS.find(candidate => candidate === answer.choice);
 		if (!skill) return null;
+		if (result.calibrated && (answer.confidence ?? 0) < MIN_CALIBRATED_CONFIDENCE) {
+			logger.debug("decisions/skill-routing: below confidence floor, leaving routing alone", {
+				skill,
+				confidence: answer.confidence,
+				floor: MIN_CALIBRATED_CONFIDENCE,
+			});
+			return null;
+		}
 		logger.debug("decisions/skill-routing: semantic match", {
 			skill,
 			backend: result.backend,
+			confidence: answer.confidence,
+			calibrated: result.calibrated,
 			durationMs: result.durationMs,
 		});
 		return skill;

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/modes/controllers/selector-controller.ts

@@ -881,7 +881,7 @@ export class SelectorController {
 					} else if (action === "import-credentials") {
 						void this.#handleCredentialImport();
 					} else if (action === "typesafe-key") {
-						this.#showTypeSafeKeyPrompt();
+						this.showTypeSafeKeyPrompt();
 					} else {
 						this.ctx.showStatus(formatProviderOnboardingCommandGuide());
 					}
@@ -903,7 +903,7 @@ export class SelectorController {
 	 * the user's own model while the UI claims TypeSafe is on. Better to keep the prompt
 	 * open and say the key was rejected.
 	 */
-	#showTypeSafeKeyPrompt(): void {
+	showTypeSafeKeyPrompt(): void {
 		this.showSelector(done => {
 			let prompt: TypeSafeKeyPromptComponent | undefined;
 			prompt = new TypeSafeKeyPromptComponent(

package/src/modes/interactive-mode.ts

@@ -2133,6 +2133,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#selectorController.showEffortSelector();
 	}
 
+	showTypeSafeKeyPrompt(): void {
+		this.#selectorController.showTypeSafeKeyPrompt();
+	}
+
 	showProviderOnboarding(): void {
 		this.#selectorController.showProviderOnboarding();
 	}

package/src/modes/types.ts

@@ -321,6 +321,8 @@ export interface InteractiveModeContext {
 	showModelSelector(options?: { temporaryOnly?: boolean }): void;
 	showEffortSelector(): void;
 	showProviderOnboarding(): void;
+	/** Open the TypeSafe key prompt (typed decisions; not a chat model). */
+	showTypeSafeKeyPrompt(): void;
 	showPluginSelector(mode?: "install" | "uninstall"): void;
 	showUserMessageSelector(): void;
 	showTreeSelector(): void;

package/src/prompts/agents/architect.md

@@ -1,7 +1,7 @@
 ---
 name: architect
 description: Read-only architecture and code-review agent with severity-rated findings and status verdicts
-tools: read, search, find, lsp, ast_grep, web_search, bash, report_finding, irc
+tools: read, search, find, lsp, ast_grep, web_search, bash, report_finding, skill, irc
 thinking-level: high
 blocking: true
 forkContext: allowed

package/src/prompts/agents/critic.md

@@ -1,7 +1,7 @@
 ---
 name: critic
 description: Read-only plan critic that approves only actionable, verifiable execution plans
-tools: read, search, find, lsp, ast_grep, web_search, bash, irc
+tools: read, search, find, lsp, ast_grep, web_search, bash, skill, irc
 thinking-level: high
 bashAllowedPrefixes:
   - skc ralplan --write

package/src/prompts/agents/planner.md

@@ -1,7 +1,7 @@
 ---
 name: planner
 description: Read-only planning agent for sequencing, acceptance criteria, risks, and handoff shape
-tools: read, search, find, lsp, ast_grep, web_search, bash, irc
+tools: read, search, find, lsp, ast_grep, web_search, bash, skill, irc
 thinking-level: medium
 bashAllowedPrefixes:
   - skc ralplan --write

package/src/session/agent-session.ts

@@ -267,6 +267,7 @@ import {
 	detectPrimarySkillKeyword,
 	ensureWorkflowSkillActivationState,
 } from "../hooks/skill-state";
+import { buildUiSkillActivationContext } 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";
@@ -313,6 +314,7 @@ import {
 } from "../skc-runtime/session-state-sidecar";
 import { requestSkcWorkerIntegrationAttempt } from "../skc-runtime/team-runtime";
 import {
+	type CanonicalSkcWorkflowSkill,
 	isCanonicalSkcWorkflowSkill,
 	readVisibleSkillActiveState,
 	syncSkillActiveState,
@@ -7558,18 +7560,41 @@ export class AgentSession {
 	 * @throws Error if no model selected or no API key available (when not streaming)
 	 */
 	/**
-	 * Second-stage workflow routing for prompts the keyword table cannot see.
+	 * Semantic workflow routing for prompts the keyword table cannot express.
 	 *
 	 * 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.
 	 *
-	 * Deliberately best-effort — a disabled setting, a missing credential, a timeout or
-	 * a nonsense answer all resolve to "no activation", which is precisely the
-	 * behaviour before this stage existed.
+	 * **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.
+	 *
+	 * 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.
+	 *
+	 * 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);
+		if (keyword) {
+			await this.#activateWorkflowSkill(keyword.skill);
+			return;
+		}
+
+		// Stage two costs a model call, so it stays opt-in.
 		if (!this.settings.get("decisions.enabled")) return;
-		if (detectPrimarySkillKeyword(text)) return; // deterministic stage already decided
 		try {
 			this.#semanticSkillRouter ??= createSemanticSkillRouter(
 				createDecisionService({
@@ -7581,6 +7606,20 @@ export class AgentSession {
 			);
 			const skill = await this.#semanticSkillRouter(text);
 			if (!skill) return;
+			await this.#activateWorkflowSkill(skill);
+		} catch (error) {
+			logger.debug("agent-session: semantic workflow routing failed", { error: String(error) });
+		}
+	}
+
+	/**
+	 * Seed workflow state and attach the ask tool.
+	 *
+	 * Both routing stages funnel through here, and both are best-effort: a failure to
+	 * write state must never take down the user's turn, so it is logged and swallowed.
+	 */
+	async #activateWorkflowSkill(skill: CanonicalSkcWorkflowSkill): Promise<void> {
+		try {
 			await ensureWorkflowSkillActivationState({
 				cwd: this.sessionManager.getCwd(),
 				skill,
@@ -7588,7 +7627,7 @@ export class AgentSession {
 			});
 			this.#attachAskTool();
 		} catch (error) {
-			logger.debug("agent-session: semantic workflow routing failed", { error: String(error) });
+			logger.debug("agent-session: workflow activation failed", { skill, error: String(error) });
 		}
 	}
 
@@ -7650,10 +7689,18 @@ export class AgentSession {
 		const deepInterviewUserIntentEpoch =
 			claimsGenuineUserIntent && !this.isStreaming ? this.#claimDeepInterviewUserIntent() : undefined;
 
-		// The keyword table in `hooks/skill-keywords.ts` is thirteen literal strings, so a
+		// The keyword table in `hooks/skill-keywords.ts` is a list of literal strings, so a
 		// Korean phrasing of "plan this before you touch code" activates nothing. Ask a
-		// cheap model only when the deterministic stage found nothing, and only for real
-		// user turns. Any failure leaves routing to the system prompt, exactly as before.
+		// cheap model instead, and only for real user turns. Any failure leaves routing to
+		// the system prompt, exactly as before.
+		//
+		// Ordering matters: this runs *after* the deep-interview intent claim above but
+		// before streaming, so a workflow it activates is in place before the ambiguity
+		// detector in `skc-runtime/deep-interview-ambiguity.ts` would otherwise seed one.
+		// Verified end to end: "설계가 위험해 보여 … 승인받을 문서부터 만들자" seeds
+		// 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 streaming, queue via steer() or followUp() based on option
@@ -7689,6 +7736,7 @@ export class AgentSession {
 			const hasPendingUserDirective = this.#toolChoiceQueue.inspect().includes("user-force");
 			const eagerTodoPrelude =
 				!options?.synthetic && !hasPendingUserDirective ? this.#createEagerTodoPrelude(expandedText) : undefined;
+			const uiSkillPrelude = options?.synthetic ? undefined : this.#createUiSkillPrelude(expandedText);
 
 			const userContent: (TextContent | ImageContent)[] = [{ type: "text", text: expandedText }];
 			if (options?.images) {
@@ -7717,7 +7765,13 @@ export class AgentSession {
 			try {
 				await this.#promptWithMessage(message, expandedText, {
 					...options,
-					prependMessages: eagerTodoPrelude ? [eagerTodoPrelude.message] : undefined,
+					prependMessages:
+						eagerTodoPrelude || uiSkillPrelude
+							? [
+									...(uiSkillPrelude ? [uiSkillPrelude] : []),
+									...(eagerTodoPrelude ? [eagerTodoPrelude.message] : []),
+								]
+							: undefined,
 					admissionLease: admission,
 					resetRetryReplaySafety: true,
 				});
@@ -11964,6 +12018,35 @@ export class AgentSession {
 		});
 	}
 
+	/**
+	 * Deterministic activation for the bundled frontend UI/UX skills.
+	 *
+	 * `hooks/ui-skill-keywords.ts` already knows how to match a prompt against all
+	 * thirteen bundled skills in Korean and English, but the only caller was the Codex
+	 * `UserPromptSubmit` hook — which this host never fires. In an SKC session the skills
+	 * were therefore advertised solely by a sentence in the system prompt, leaving it to
+	 * the model to notice and obey. That is not activation, it is hope.
+	 *
+	 * The matcher is deliberately conservative and measured that way: on sixteen real
+	 * prompts it caught 5 of 8 frontend requests and produced **zero** false positives on
+	 * the 8 backend ones. Missing a match costs nothing — the system-prompt sentence is
+	 * 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.
+	 */
+	#createUiSkillPrelude(promptText: string): AgentMessage | undefined {
+		if (this.#planModeState?.enabled) return undefined;
+		const directive = buildUiSkillActivationContext(promptText);
+		if (!directive) return undefined;
+		logger.debug("agent-session: bundled UI skill matched", { promptChars: promptText.length });
+		return {
+			role: "developer",
+			content: [{ type: "text", text: `<system-reminder>\n${directive}\n</system-reminder>` }],
+			attribution: "agent",
+			timestamp: Date.now(),
+		};
+	}
+
 	#createEagerTodoPrelude(promptText: string): { message: AgentMessage; toolChoice?: ToolChoice } | undefined {
 		const eagerTodosEnabled = this.settings.get("todo.eager");
 		const todosEnabled = this.settings.get("todo.enabled");

package/src/setup/model-onboarding-guidance.ts

@@ -6,6 +6,11 @@ export const MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND = "/provider add --preset
 
 export const MODEL_ONBOARDING_SETUP_COMMAND = "skc setup provider";
 export const MODEL_ONBOARDING_OAUTH_COMMAND = "/provider login [provider-id] or /login [provider-id]";
+/**
+ * TypeSafe is not a chat model and never appears in the model list, so the only way a
+ * user learns it exists is from the surfaces where they go to add credentials.
+ */
+export const MODEL_ONBOARDING_TYPESAFE_COMMAND = "/provider typesafe";
 
 export function formatModelOnboardingGuidance(): string {
 	return [
@@ -15,12 +20,13 @@ export function formatModelOnboardingGuidance(): string {
 		`Provider presets: ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND} --preset <preset>).`,
 		`API-compatible custom providers: ${MODEL_ONBOARDING_API_PROVIDER_COMMAND}.`,
 		`OAuth/subscription providers: ${MODEL_ONBOARDING_OAUTH_COMMAND}.`,
+		`Typed decisions (not a chat model): ${MODEL_ONBOARDING_TYPESAFE_COMMAND} adds a TypeSafe key.`,
 		"Then run /model to select a configured model or assign it to a target.",
 	].join("\n");
 }
 
 export function formatModelOnboardingInlineHint(): string {
-	return `Add MiniMax/GLM presets with ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND}; custom API providers with ${MODEL_ONBOARDING_API_PROVIDER_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND}); OAuth/subscription with ${MODEL_ONBOARDING_OAUTH_COMMAND}; then run /model for DEFAULT, EXECUTOR, ARCHITECT, PLANNER, and CRITIC.`;
+	return `Add MiniMax/GLM presets with ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND}; custom API providers with ${MODEL_ONBOARDING_API_PROVIDER_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND}); OAuth/subscription with ${MODEL_ONBOARDING_OAUTH_COMMAND}; TypeSafe typed decisions with ${MODEL_ONBOARDING_TYPESAFE_COMMAND}; then run /model for DEFAULT, EXECUTOR, ARCHITECT, PLANNER, and CRITIC.`;
 }
 
 export function formatNoModelOnboardingError(): string {

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

@@ -1288,7 +1288,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	{
 		name: "provider",
 		description: "Set up API-compatible providers or login providers",
-		inlineHint: "add|login",
+		inlineHint: "add|login|typesafe",
 		allowArgs: true,
 		handle: async (command, runtime) => {
 			const args = command.args.trim();
@@ -1296,6 +1296,15 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 				await runtime.output(providerSetupUsage());
 				return commandConsumed();
 			}
+			if (args === "typesafe") {
+				await runtime.output(
+					"TypeSafe key entry needs an interactive terminal.\n" +
+						"Run it in the TUI (/provider typesafe) or from a shell:\n" +
+						"  TYPESAFE_API_KEY=<key> skc setup typesafe\n" +
+						"  skc setup typesafe --remove",
+				);
+				return commandConsumed();
+			}
 			if (args === "login" || args.startsWith("login ")) {
 				const providerId = args.slice("login".length).trim();
 				const loginCommand = providerId ? `/login ${providerId}` : "/login [provider-id]";
@@ -1361,6 +1370,14 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 				runtime.ctx.editor.setText("");
 				return;
 			}
+			// TypeSafe is not a chat model, so it cannot live in the model list. A direct
+			// subcommand keeps it one step away from `/model`, where users actually look
+			// for "add a key", instead of buried in the onboarding menu.
+			if (args === "typesafe") {
+				runtime.ctx.showTypeSafeKeyPrompt();
+				runtime.ctx.editor.setText("");
+				return;
+			}
 			if (args.startsWith("add ")) {
 				const parsed = parseProviderSetupSlashArgs(args.slice(4));
 				try {

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,