@sayknow-cli/coding-agent 0.5.25 → 0.6.0

package/CHANGELOG.md

@@ -2,7 +2,42 @@
 
 ## [Unreleased]
 
-## [0.5.25] - 2026-09-21
+## [0.6.0] - 2026-09-24
+
+### Added
+
+- The 13 bundled UI skills are now part of the typed decision instead of 20 hand-written regexes. Measured recall of the pattern table on real Korean prompts was 5/8; a prompt like "이 부분 손보기 전에 어떻게 갈지부터 같이 정하고 넘어가자" matched nothing and the skill never activated. The picked skill still arrives as the same hidden `developer` reminder, now labelled `semantic match` when the model answered and `matched` when a pattern did.
+- Workflow routing and UI skill selection are **one** decision call, not two. The triage asks both questions in a single request (`questions: ["workflow", "uiSkill"]`), and a prompt the pattern table already answered drops that question from the request instead of paying for it — so adding UI routing cost zero extra round trips.
+- The skill keyword table now fills itself. Every answered routing decision mines ordered two-stem shingles from the prompt into `~/.skc/agent/learned-skill-keywords.json`. A shingle is promoted to a real keyword after 2 independent prompts when the backend reports calibrated confidence ≥ 0.9, or 3 when it only ranks; a single contradicting answer blocks that shingle permanently, so a coincidence cannot become a rule. Learned entries carry strictly negative priority — a hand-written keyword always wins — and a promoted pattern answers for free on the next matching prompt. `decisions.keywordLearning: false` turns the store off; `SKC_LEARNED_KEYWORDS_PATH` relocates it.
+- Routing and learning work in whatever language the prompt is written in. Mining uses the platform Unicode segmenter, so Chinese, Japanese and Thai prompts with no spaces come apart into words (Han runs the ICU dictionary misses fall back to character bigrams; hiragana-only tokens are dropped as grammar); non-ASCII alphabets are kept instead of discarded, and a learned stem gets a Unicode word boundary in spaced scripts and a bare substring match in unspaced ones. The length floor that skips the model on "ok thanks" is measured in signal rather than code units, so a six-character Chinese request is no longer thrown away. Measured against the hosted `jev` backend: 40/40 across ko, en, zh, ja, es and ru, and a ralplan phrasing repeated twice in Chinese, Japanese or Russian promotes a keyword that fires on an unseen sentence in that language.
+- The Codex host gets the same router. `skc codex-native-hook` ran the hand-written keyword table and nothing else: the semantic stage had a parameter waiting for it since it shipped, and learned keywords were never loaded there, so a phrasing learned in a CLI session did nothing under Codex. The hook now runs all three stages — hand-written keywords, learned keywords, then one typed decision for whatever those missed — on the same backend chain (TypeSafe key, else a running local runtime, else the small model of the provider you are logged into) and feeds the answer back into the learned table. Because the hook is a fresh process per prompt, credentials and the model registry are opened only on a prompt the tables did not fully answer and closed before it exits; a prompt they did answer still costs the same ~0.3s it did before. Measured through the real hook subprocess: a Chinese ralplan phrasing routed by the model on the first prompt fired from the learned table on the next one.
+
+### Changed
+
+- Typed decisions (`decisions.enabled`) are now **on by default**. The keyword stage of workflow routing still runs first and free; the model stage only spends a small-model call on turns the table did not answer. Set `decisions.enabled: false` to route on the keyword table alone.
+- The small-model fallback now ranks the **provider you are chatting with** first. Measured on a registry with Anthropic, Codex and Z.ai keys: price order put four free `zai/glm-*` reasoning tiers ahead of `claude-haiku-4-5`, and the first took 8.9s — past the 8s service deadline, so the answer was nothing. Haiku next to Opus, mini next to GPT is also the model you would have picked by hand.
+- The routing decision now goes through the session's own `streamFn` instead of a bare `completeSimple`, so it gets the same proxy, credential-invalidation and retry wrapping as the turn, and a host that injects a transport intercepts it. Hosts opt sessions in with `AgentSessionConfig.semanticWorkflowRouting` (`createAgentSession` does); a bare `AgentSession` never routes, so scripted transports are not consumed by a call they did not script. While the decision is in flight the session reports `isStreaming`, so a second `prompt()` queues or rejects as it would mid-turn, and `abort()` cancels the decision.
+- `task.modelRouting.enabled` now defaults to **true**. The tier lists it reads are empty until you set them, so nothing changes for anyone who has not configured them — but shipping it off meant a user who *had* configured tiers still got no routing, which made the whole feature dead code.
+
+### Fixed
+
+- The small-model fallback answered **nothing** on any registry with an Anthropic key: the cheapest qualifying entry, `claude-3-haiku-20240307`, is retired and returns 404, and the backend logged it as "model did not emit the forced tool call" and gave up. The three retired Claude 3.x ids are now dropped from the catalog *and* from stale on-disk cache rows, the backend logs the real status, and a candidate that errors or blows a 3.5s attempt budget is skipped for the next one and remembered for ten minutes so the stall is paid once, not per prompt.
+- A local runtime contributes **one** candidate — the smallest chat model — and embedding models (`nomic-embed-text`) are no longer offered a chat call. Measured with Ollama: five local models ranked ahead of every hosted one, each timed out on cold start, and the hosted model was never reached before the deadline.
+- A decision request whose caller had already aborted — measured: `abort()` landing during the previous backend's credential lookup — ran a full attempt budget of silence, because an abort listener added to a signal that has already fired never runs. Every backend now checks the signal after each await.
+
+## [0.5.26] - 2026-09-23
+### Added
+
+- `/model` role rows now open a second level so a model can be assigned to a *detailed use* rather than only to a whole role. `planner`/`architect` offer backend architecture and frontend design, `executor` offers implementation and testing, `critic` offers review; `default` has none and still assigns in one keystroke. The two bulk rows deliberately stay canonical-only — an action that also rewrote five detailed-use overrides could not be undone from the same menu. Assignments persist to the new `task.modelRouting.specialtyModels` record, whose keys are allowlisted to those five ids. Saving one while `task.modelRouting.enabled` is off persists it and says so instead of silently enabling a feature you did not ask for. First-level rows are now stable descriptors rather than positional index arithmetic, which is what previously made every added row a chance to assign a model to the wrong role.
+- Subagent model routing now runs **one classification per child task** instead of one per `task` call. A batch shares an agent but not a workload, so an implementation slice and a test slice in the same call no longer have to share a single verdict. Each child dispatches its own ordered chain — detailed-use model, then tier model, then the role's configured chain — so a detailed-use model that cannot authenticate still falls through to something the role can actually run. A high-risk assignment skips the detailed-use axis entirely, because a lateral swap can move sideways into something weaker.
+- Receipts and progress now carry what the router **requested** separately from what the spawn ran on. Because the dispatched value is a fallback chain, conflating the two would let a receipt claim a detailed-use model was used when the chain actually fell through to the baseline. When the decision backend is an ordinary LLM it returns no probabilities at all, so the record carries an ordinal clarity score and `calibrated: false` rather than a fabricated confidence.
+- The `task` tool accepts `.specialty` per task. Declaring the kind of work is the deterministic path to a detailed-use model: no classifier runs, `task.modelRouting.enabled` is not consulted, and no confidence bar applies — if the user assigned a model to that specialty under `/model`, the child runs on it and leaves it only on a transport error (429, 5xx, auth, quota), when the child session's fallback chain advances to the role baseline composed behind it. A declared specialty ignores the menu's role grouping on purpose: the setting is one flat map, and a frontend build delegated to `executor` should get the frontend model. Receipts mark these `declared: true` so they cannot be mistaken for a classifier verdict. Auto-detection from assignment text is unchanged and still opt-in.
+
+### Fixed
+
+- Model-selector suites that assert UI copy now pin the locale — and restore it. They previously inherited whatever `language` the developer had configured, because a sibling suite restores the real agent directory and reloads real settings, and one suite pinned Korean without putting it back — so whether they passed depended on test file ordering.
+- The first-level `/model` role rows (`Set as EXECUTOR (Executor)`) were hardcoded English inside an otherwise localized menu. They now go through i18n in all seven locales; the redundant `(Name)` suffix is dropped where the locale does not need it, and the role tag stays verbatim because it is the same identifier receipts and `/model` arguments use.
+- Login, `--list-models`, `/model`, and `/model provider/id` now refresh provider catalogs online so newly published Kimi/Grok (and other OpenAI-compatible) ids appear without waiting for a bundled `models.json` regen or a 2h cache TTL.
 
 ## [0.5.22] - 2026-09-19
 

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

@@ -104,6 +104,11 @@ interface RecordDef<T> {
     type: "record";
     default: Record<string, T>;
     valueSchema?: RecordValueDef;
+    /**
+     * Closed key set. When present, reconciliation rejects any other key instead of
+     * silently carrying a typo that no consumer will ever read.
+     */
+    keys?: readonly string[];
     ui?: UiBase;
 }
 type SettingDef = BooleanDef | StringDef | NumberDef | EnumDef<readonly string[]> | ArrayDef<unknown> | RecordDef<unknown>;
@@ -2414,11 +2419,29 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "decisions.enabled": {
         readonly type: "boolean";
-        readonly default: false;
+        readonly default: true;
         readonly ui: {
             readonly tab: "context";
             readonly label: "Typed decisions";
-            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.";
+            readonly description: "Model-backed second stage for workflow routing. The keyword table runs first 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, only on turns the keyword table did not already answer, on the cheapest backend available: TypeSafe when a key is stored, else a local runtime that is running, else the small model of the provider you are chatting with. 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. Turn off to route on the keyword table alone.";
+        };
+    };
+    /**
+     * Feed routing answers back into the deterministic keyword table.
+     *
+     * The hand-written table cannot be grown by hand for Korean — measured recall
+     * was 0/9 — so it grows itself instead: a two-stem pattern that produced the
+     * same routing answer on two distinct prompts, and was never contradicted, is
+     * promoted and thereafter fires for free. One contradiction retracts it
+     * permanently. Stems and hashes are stored; prompt text never is.
+     */
+    readonly "decisions.keywordLearning": {
+        readonly type: "boolean";
+        readonly default: true;
+        readonly ui: {
+            readonly tab: "context";
+            readonly label: "Learn routing keywords";
+            readonly description: "Remember the phrasings the routing model resolves, so repeating one stops costing a model call. A pattern must give the same answer on two different prompts before it fires on its own, and a single disagreement removes it for good. Only word stems and hashes are written to disk, never your prompts. Turn off to keep the keyword table frozen at its built-in entries.";
         };
     };
     /**
@@ -2430,12 +2453,14 @@ export declare const SETTINGS_SCHEMA: {
      * 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.
+     * Needs `decisions.enabled` and at least two tiers configured. The tiers are
+     * empty by default, so this is a no-op until the user sets them — which is why
+     * it defaults on: shipping it off meant the routing code existed and never ran
+     * even for users who had configured the tiers it needs.
      */
     readonly "task.modelRouting.enabled": {
         readonly type: "boolean";
-        readonly default: false;
+        readonly default: true;
         readonly ui: {
             readonly tab: "tasks";
             readonly label: "Route subagent models per task";
@@ -2471,6 +2496,27 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "string";
         readonly default: "";
     };
+    /**
+     * Per-specialty models — the **work-kind** axis.
+     *
+     * Keys are the bounded ids in `config/task-model-specialties.ts`; values use the
+     * same selector grammar as any other model setting, so a chain is allowed. A
+     * specialty with no entry inherits the role's resolved model unchanged, which is
+     * why the default is empty rather than pre-populated.
+     *
+     * These are routing hints, never agents: nothing here widens the canonical role
+     * roster, model-profile role keys, tool grants, or spawn permissions. Saving one
+     * does not enable `task.modelRouting.enabled`; the assignment surface reports the
+     * disabled state instead of silently turning routing on.
+     */
+    readonly "task.modelRouting.specialtyModels": {
+        readonly type: "record";
+        readonly default: Record<string, ModelSelectorValue>;
+        readonly valueSchema: {
+            readonly type: "model-selector-value";
+        };
+        readonly keys: readonly ["backendArchitecture", "frontendDesign", "implementation", "testing", "review"];
+    };
     readonly "ttsr.enabled": {
         readonly type: "boolean";
         readonly default: true;

package/dist/types/config/task-model-specialties.d.ts

@@ -0,0 +1,55 @@
+/** Stable configuration/routing identifiers. Display strings are localized separately. */
+export declare const TASK_MODEL_SPECIALTY_IDS: readonly ["backendArchitecture", "frontendDesign", "implementation", "testing", "review"];
+export type TaskModelSpecialty = (typeof TASK_MODEL_SPECIALTY_IDS)[number];
+/**
+ * Which canonical role agents may receive each specialty.
+ *
+ * Planning roles share the two design specialties on purpose: the user's intent is
+ * "a backend-strong model plans backend work", not "planner and architect each get
+ * their own private backend model". Implementation roles never take a design
+ * specialty, mirroring the existing frontend-domain rule.
+ */
+export declare const TASK_MODEL_SPECIALTY_ROLES: Readonly<Record<TaskModelSpecialty, readonly string[]>>;
+/** Neutral classifier outcome: the work does not clearly belong to one specialty. */
+export declare const TASK_MODEL_SPECIALTY_NONE: "none";
+/** Bounded-key predicate for the `task.modelRouting.specialtyModels` record. */
+export declare function isTaskModelSpecialty(value: unknown): value is TaskModelSpecialty;
+/** Specialties a given canonical role agent is allowed to receive, in declaration order. */
+export declare function specialtiesForRole(agentName: string): TaskModelSpecialty[];
+/** Whether a specialty may be applied to work routed to this canonical role agent. */
+export declare function specialtySupportsRole(specialty: TaskModelSpecialty, agentName: string): boolean;
+/** Where a composed candidate came from, so a receipt never overstates what was selected. */
+export type TaskRoutingSource = "specialty" | "legacy-frontend" | "tier" | "baseline";
+export interface TaskRoutingCandidate {
+    /** The configured selector, normalized but otherwise untouched. */
+    selector: string;
+    source: TaskRoutingSource;
+    /** Set when `source` is `specialty` or `legacy-frontend`. */
+    specialty?: TaskModelSpecialty;
+    /** Set when `source` is `tier`. */
+    tier?: string;
+}
+/**
+ * Identity used for deduplication.
+ *
+ * An explicit thinking suffix is part of the identity: `provider/model:high` and
+ * `provider/model:low` are different configured intents, and collapsing them would
+ * silently drop the user's effort choice from a chain.
+ */
+export declare function specialtySelectorIdentity(selector: string): string;
+/** The `provider/model` part, ignoring any thinking suffix. Used for "same model" checks. */
+export declare function specialtySelectorHead(selector: string): string;
+/** Expand a configured selector value into normalized candidates tagged with their origin. */
+export declare function toRoutingCandidates(value: string | readonly string[] | undefined, source: TaskRoutingSource, extra?: {
+    specialty?: TaskModelSpecialty;
+    tier?: string;
+}): TaskRoutingCandidate[];
+/**
+ * Concatenate candidate segments, keeping the first occurrence of each identity.
+ *
+ * A selector that also exists in the baseline segment is attributed to `baseline`
+ * even when an earlier specialty segment introduced it. Resolving that entry proves
+ * only that the role's own configured model was usable — reporting it as a specialty
+ * hit would claim a routing decision that never happened.
+ */
+export declare function dedupeRoutingCandidates(segments: readonly TaskRoutingCandidate[][]): TaskRoutingCandidate[];

package/dist/types/decisions/keyword-learning.d.ts

@@ -0,0 +1,61 @@
+import type { SkillKeywordDefinition } from "../hooks/skill-keywords";
+import type { CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
+export declare const LEARNED_KEYWORD_STORE_VERSION = 1;
+/** Test seam. Also lets a host keep the table out of the user's home. */
+export declare function setLearnedKeywordStorePath(value: string | undefined): void;
+export declare function resetLearnedKeywordCache(): void;
+/**
+ * Where the learned table lives.
+ *
+ * User-global on purpose: a phrasing you use is a phrasing you use, and making it
+ * per-repository would mean relearning the same rule in every checkout.
+ * `SKC_LEARNED_KEYWORDS_PATH` redirects it, so a test driving a real session under
+ * a temp agent dir cannot write into the developer's actual home.
+ */
+export declare function getLearnedKeywordStorePath(): string;
+/**
+ * Ordered stem pairs within a three-token window.
+ *
+ * The gap is what makes a learned pattern generalize where the literal table
+ * cannot: a prompt that says "make me a plan document" mines `plan … document`,
+ * which then also matches "make the plan into a document" — the phrasing that
+ * made the hand-written entry miss.
+ */
+export declare function mineShingles(text: string): string[];
+/**
+ * Promoted patterns, in the shape the deterministic stage consumes.
+ *
+ * Priority sits one below the hand-written entry for the same workflow: when a
+ * learned pattern and an enumerated keyword disagree, the human wins.
+ */
+export declare function loadLearnedKeywordDefinitions(): Promise<SkillKeywordDefinition[]>;
+export interface RoutingObservation {
+    text: string;
+    /** Null means the router deliberately chose no workflow — a negative example. */
+    skill: CanonicalSkcWorkflowSkill | null;
+    confidence?: number | undefined;
+    calibrated?: boolean | undefined;
+}
+export interface LearningOutcome {
+    promoted: SkillKeywordDefinition[];
+    retracted: number;
+}
+/**
+ * Feed one routing answer into the table.
+ *
+ * Best-effort by construction: it runs after the turn's routing decision is
+ * already made, so a failure here changes nothing the user can observe.
+ */
+export declare function observeRouting(observation: RoutingObservation): Promise<LearningOutcome>;
+export interface LearnedKeywordSummary {
+    entries: {
+        keyword: string;
+        skill: CanonicalSkcWorkflowSkill;
+        positives: number;
+        lastSeen: number;
+    }[];
+    candidates: number;
+    blocked: number;
+}
+/** What the table has actually learned, for `skc` surfaces and tests. */
+export declare function summarizeLearnedKeywords(): Promise<LearnedKeywordSummary>;

package/dist/types/decisions/llm-backend.d.ts

@@ -16,7 +16,7 @@
  * 2. Every question goes in **one** call. Splitting them multiplies cost and latency
  *    while the enum constraint already keeps each field independent.
  */
-import { type Api, type Model } from "@sayknow-cli/ai";
+import { type Api, completeSimple, type Model } from "@sayknow-cli/ai";
 import type { ModelRegistry } from "../config/model-registry";
 import type { Settings } from "../config/settings";
 import { type DecisionBackend } from "./types";
@@ -40,12 +40,24 @@ export interface LlmBackendDeps {
     maxInputCostPerMTok?: number;
     /** Injected in tests to make the local-runtime probe deterministic. */
     fetchImpl?: typeof fetch;
+    /** Injected in tests to script provider answers without a network. */
+    completeImpl?: typeof completeSimple;
+    /** Per-candidate deadline; injected in tests so a hung provider does not cost real seconds. */
+    attemptTimeoutMs?: number;
     registry: ModelRegistry;
     settings: Settings;
     sessionId?: string;
     /** Overrides role resolution; used by callers that already picked a model. */
     model?: Model<Api>;
+    /**
+     * Provider of the model the caller is already talking to. Its small model is tried
+     * first when nothing was configured; see `rankSmallModels` for why. A thunk is
+     * accepted so a long-lived backend follows the session when the user switches model.
+     */
+    preferredProvider?: string | (() => string | undefined);
 }
 /** Reset between tests; also lets a caller force a fresh probe after starting a runtime. */
 export declare function clearLocalRuntimeLivenessCache(): void;
+/** Reset between tests. */
+export declare function clearDeadModelCache(): void;
 export declare function createLlmDecisionBackend(deps: LlmBackendDeps): DecisionBackend;

package/dist/types/decisions/prompt-triage.d.ts

@@ -0,0 +1,42 @@
+import { type BundledSkcUiSkillName } from "../defaults/skc-ui-skills";
+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 buildUiSkillCriteria(): Record<string, string>;
+export interface PromptTriage {
+    /** Null means the router deliberately chose no workflow, not that it failed. */
+    workflow: CanonicalSkcWorkflowSkill | null;
+    uiSkill: BundledSkcUiSkillName | null;
+    /** Only meaningful when {@link calibrated} is true. */
+    workflowConfidence: number | undefined;
+    calibrated: boolean;
+}
+export interface PromptTriageRequest {
+    text: string;
+    /** Skip the workflow question — the keyword table already answered it. */
+    skipWorkflow?: boolean;
+    /** Skip the UI question — the regex table already matched. */
+    skipUiSkill?: boolean;
+    signal?: AbortSignal | undefined;
+}
+export type PromptTriager = (request: PromptTriageRequest) => Promise<PromptTriage | null>;
+/**
+ * Build the per-turn triager.
+ *
+ * Returns null when the service is disabled, the prompt is too short to carry
+ * intent, every question was already answered for free, or the backend did not
+ * produce a usable result. Null means "no information", which is different from
+ * a result whose fields are all null — that one is the router saying "none", and
+ * the keyword learner treats it as a negative example.
+ */
+export declare function createPromptTriage(service: DecisionService): PromptTriager;
+export type SkillRouter = (text: string, signal?: AbortSignal) => Promise<CanonicalSkcWorkflowSkill | null>;
+/**
+ * Workflow-only view of the triager.
+ *
+ * A few lines over the same implementation rather than a second one: the eval
+ * harness in `scripts/eval-skill-routing.ts` and the routing tests want
+ * text-in/skill-out and have no UI question to ask, and a parallel router would
+ * be free to drift away from the thresholds this one enforces.
+ */
+export declare function createSemanticSkillRouter(service: DecisionService): SkillRouter;

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

@@ -1,10 +1,45 @@
-import { type CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
-import type { DecisionService } from "./index";
+/** Shared across every routing question so one answer shape covers them all. */
+export declare const NONE_CHOICE = "none";
+export declare const ROUTING_INSTRUCTIONS = "Which workflow should handle this user request? Choose none unless the request clearly calls for one of the workflows.";
 /** 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
- * disabled so the caller keeps its existing behaviour with no branching.
+ * Prompts below this length never carry enough signal to justify a model round-trip.
+ * Measured with {@link promptSignalLength}, not `String.length`: the floor was fitted
+ * to English and Korean, and in code units a complete Chinese request is shorter than
+ * "ok thanks".
  */
-export declare function createSemanticSkillRouter(service: DecisionService): SkillRouter;
+export declare const MIN_PROMPT_CHARS = 12;
+/** Only the opening of a prompt decides its workflow; the rest is payload. */
+export declare const MAX_PROMPT_CHARS = 4000;
+/**
+ * Prompt length in Latin-letter equivalents.
+ *
+ * One Han character, kana or Hangul syllable carries what two or three Latin letters
+ * do, so each counts double. "先做架构设计" (6 code units) is a whole request; "谢谢" and
+ * "고마워요" still fall under the floor, which is the point of having one.
+ */
+export declare function promptSignalLength(text: string): number;
+/**
+ * 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.
+ */
+export declare const MIN_CALIBRATED_CONFIDENCE = 0.75;

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

@@ -1,3 +1,6 @@
+import type { ModelSelectorValue } from "../config/model-selector-value";
+import type { Settings } from "../config/settings";
+import { type TaskModelSpecialty, type TaskRoutingCandidate, type TaskRoutingSource } from "../config/task-model-specialties";
 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"];
@@ -22,26 +25,57 @@ export interface TaskRoutingPolicy {
     /**
      * Model for frontend planning, when the assignment reads as frontend work.
      *
-     * This is the **domain** axis, not a rung on the ladder: a design-strong model
-     * is not "better" than a code-strong one, it is a different specialty. Only
-     * planning roles ever take it, and only laterally — the implementation roles
-     * stay on the difficulty ladder.
+     * Superseded by `specialtyModels.frontendDesign`; kept as the fallback source
+     * so an existing configuration keeps working untouched until it is migrated.
      */
     frontendModel?: string;
     /**
-     * Bar for the lateral swap above. Directional bars do not apply here because
-     * neither direction is "spending more": being wrong either way costs quality,
-     * symmetrically, so one bar is the whole story.
+     * Per-specialty models — the work-kind axis.
+     *
+     * Absent entries inherit the role's own chain, which is why an unset specialty
+     * is not an error and does not suppress the difficulty ladder.
+     */
+    specialtyModels?: Partial<Record<TaskModelSpecialty, ModelSelectorValue>>;
+    /**
+     * Bar for a lateral swap on a **calibrated** backend. Directional bars do not
+     * apply here because neither direction is "spending more": being wrong either
+     * way costs quality, symmetrically, so one bar is the whole story.
      */
     minDomainConfidence: number;
+    /**
+     * Bar for a lateral swap on an **uncalibrated** backend.
+     *
+     * The ordinary logged-in model cannot report a probability, and asking it for
+     * one measurably degrades the answer, so its choice carries no `confidence`.
+     * What it *can* report is an ordinal strength. Requiring a high ordinal is not
+     * the same guarantee as a calibrated threshold, and the result is recorded as
+     * uncalibrated — but refusing to route at all would make a user's explicit
+     * specialty selection silently inert on the default backend.
+     */
+    minSpecialtyOrdinal: number;
 }
 export declare const DEFAULT_TASK_ROUTING_POLICY: Omit<TaskRoutingPolicy, "tiers">;
+/**
+ * The settings surface this module reads.
+ *
+ * Narrowed to `get` so the router cannot quietly start writing settings, and so
+ * a caller only has to supply a reader rather than a whole `Settings` instance.
+ */
+export type TaskRoutingSettingsReader = Pick<Settings, "get">;
+/**
+ * Build the routing policy from settings, or null when routing must not run.
+ *
+ * Null is returned for two distinct reasons that both mean "leave the configured
+ * model alone": the feature is off, or it is on but nothing is configured to
+ * route *to*. A lone tier is not an axis — there is nowhere to move from it —
+ * so two tiers is the floor unless a specialty or the legacy frontend model
+ * supplies a lateral target instead.
+ */
+export declare function buildTaskRoutingPolicyFromSettings(settings: TaskRoutingSettingsReader): TaskRoutingPolicy | null;
 /**
  * Roles whose output is a plan or a design review.
  *
- * These are the only roles the domain swap applies to — the user's intent is
- * "a design-strong model *plans* the frontend; implementation stays where it
- * is". Executor keeps the difficulty ladder regardless of domain.
+ * Derived from the specialty compatibility map so the two never drift apart.
  */
 export declare const PLANNING_ROLES: ReadonlySet<string>;
 export interface TaskRoutingRequest {
@@ -50,14 +84,65 @@ export interface TaskRoutingRequest {
     assignment: string;
     /** Whatever the role is configured to use today, used as the direction baseline. */
     currentModel: string | undefined;
+    /**
+     * The role's fully resolved chain, in order. The composed candidate list ends
+     * with this, so a specialty or tier that cannot be authenticated falls through
+     * to the model the role would have used anyway.
+     */
+    baselineChain?: readonly string[];
     signal?: AbortSignal;
 }
 export interface TaskRoutingResult {
+    /** Head of the composed chain — what the spawn runs on if it authenticates. */
     model: string;
-    /** Null when the move was a domain swap — that axis has no ladder. */
+    /** Null when the move was a specialty swap — that axis has no ladder. */
     tier: TaskTier | null;
     reason: string;
+    /** Ordered, provenance-tagged chain for the existing auth-aware resolver. */
+    candidates: TaskRoutingCandidate[];
+    /** What the classifier asked for. The *effective* source is only known after resolution. */
+    requestedSource: TaskRoutingSource;
+    requestedSpecialty?: TaskModelSpecialty;
+    requestedTier?: TaskTier;
+    /**
+     * True when the caller named the specialty on the spawn itself. No classifier
+     * ran, so `calibrated`/`confidence`/`ordinalStrength` describe nothing here.
+     */
+    declared: boolean;
+    /** False means `ordinalStrength` ranks, and no probability was available. */
+    calibrated: boolean;
+    confidence?: number;
+    ordinalStrength?: number;
+}
+export interface DeclaredSpecialtyRequest {
+    agentName: string;
+    specialty: TaskModelSpecialty;
+    /** Whatever the role is configured to use today. */
+    currentModel: string | undefined;
+    /** The role's fully resolved chain; always the tail so a dead specialty model falls through. */
+    baselineChain?: readonly string[];
 }
+/**
+ * Route a spawn whose caller *declared* the kind of work.
+ *
+ * This is the deterministic half of the specialty axis. Nothing here asks a
+ * classifier, reads `task.modelRouting.enabled`, or applies a confidence bar:
+ * the user put a model on this specialty in `/model`, the caller says this is
+ * that work, and the only remaining reason not to run on it is that it fails —
+ * which the child session's fallback chain handles at the transport boundary
+ * (429, 5xx, auth, quota) by advancing to the role's baseline behind it.
+ *
+ * Role eligibility is deliberately not checked. The menu groups specialties
+ * under the roles that usually do that work, but the setting is one flat map:
+ * a frontend model the user chose for design is the same frontend model they
+ * expect when the *implementation* of that frontend is delegated. Refusing
+ * here would make "frontend uses a different model" false for exactly the
+ * spawns where it matters most.
+ *
+ * Returns null only when nothing is configured for the specialty, or when the
+ * configured model is already what the role would run on anyway.
+ */
+export declare function resolveDeclaredSpecialtyRouting(settings: TaskRoutingSettingsReader, request: DeclaredSpecialtyRequest): TaskRoutingResult | null;
 /**
  * Decide the model for one subagent spawn, or null to leave the configured one alone.
  *

package/dist/types/hooks/native-prompt-routing.d.ts

@@ -0,0 +1,21 @@
+import type { PromptTriager } from "../decisions/prompt-triage";
+import { type SkillActiveState } from "./skill-state";
+export interface NativePromptRoutingInput {
+    cwd: string;
+    text: string;
+    sessionId?: string;
+    threadId?: string;
+    turnId?: string;
+    stateDir?: string;
+    /** `config.yml` files in precedence order, lowest first; resolved by the hook. */
+    configPaths: readonly string[];
+    agentDir?: string;
+    /** Injected in tests so routing is exercised without credentials or a network. */
+    triager?: PromptTriager;
+}
+export interface NativePromptRoutingResult {
+    skillState: SkillActiveState | null;
+    /** Directive for a UI skill the model picked because the pattern table missed. */
+    uiSkillContext: string | null;
+}
+export declare function routeNativePrompt(input: NativePromptRoutingInput): Promise<NativePromptRoutingResult>;

package/dist/types/hooks/native-skill-hook.d.ts

@@ -1,3 +1,4 @@
+import type { PromptTriager } from "../decisions/prompt-triage";
 import { type EffectiveSkillConfigInput } from "./skill-state";
 export type SkcNativeHookEventName = "UserPromptSubmit" | "Stop";
 export interface SkcNativeHookDispatchResult {
@@ -11,6 +12,8 @@ interface SkcNativeHookDispatchOptions {
     stateDir?: string;
     effectiveSkillConfig?: EffectiveSkillConfigInput;
     configPaths?: string[];
+    /** Injected in tests so the model stage runs without credentials or a network. */
+    triager?: PromptTriager;
 }
 export declare function clearSkcNativeSkillHookCachesForTesting(): void;
 export declare function getSkcNativeSkillHookCacheStatsForTesting(): {

package/dist/types/hooks/skill-keywords.d.ts

@@ -4,6 +4,15 @@ export interface SkillKeywordDefinition {
     skill: SkcWorkflowSkill;
     priority: number;
     guidance: string;
+    /**
+     * Pre-compiled matcher, replacing the literal-substring compilation of
+     * `keyword`. Only learned entries set it: they are two stems with a bounded
+     * gap, which a literal string cannot express. `keyword` stays human-readable
+     * for logs and for the guidance line.
+     */
+    pattern?: RegExp;
+    /** Mined from routing answers rather than written by hand. */
+    learned?: boolean;
 }
 export declare const SKC_WORKFLOW_SKILLS: readonly ["deep-interview", "ralplan", "ultragoal", "team"];
 export type SkcWorkflowSkill = CanonicalSkcWorkflowSkill;

package/dist/types/hooks/skill-state.d.ts

@@ -2,7 +2,7 @@ import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
 import { type SkillActiveState } from "../skill-state/active-state";
 import { initialPhaseForSkill } from "../skill-state/initial-phase";
 export { initialPhaseForSkill };
-import { type SkcWorkflowSkill } from "./skill-keywords";
+import { type SkcWorkflowSkill, type SkillKeywordDefinition } from "./skill-keywords";
 export declare const SKC_STATE_DIR = ".skc";
 export declare const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
 export interface EffectiveSkillConfigInput {
@@ -15,6 +15,8 @@ export interface SkillKeywordMatch {
     keyword: string;
     skill: SkcWorkflowSkill;
     priority: number;
+    /** Matched a pattern mined from routing answers, not a hand-written keyword. */
+    learned?: boolean;
 }
 export type { SkillActiveEntry, SkillActiveState } from "../skill-state/active-state";
 export interface ModeState {
@@ -38,6 +40,12 @@ export interface RecordSkillActivationInput {
     turnId?: string;
     nowIso?: string;
     stateDir?: string;
+    /**
+     * Patterns promoted by the keyword learner, appended after the hand-written
+     * table. The caller loads them because it knows whether learning is on; see
+     * `detectSkillKeywords`.
+     */
+    learned?: readonly SkillKeywordDefinition[];
     /**
      * Semantic fallback, consulted only when no keyword matched. Supplying it turns the
      * literal keyword table into a two-stage router; omitting it keeps the historical
@@ -60,8 +68,17 @@ export interface UserPromptSubmitStateInput {
     prompt?: string;
     sessionFile?: string;
 }
-export declare function detectSkillKeywords(text: string): SkillKeywordMatch[];
-export declare function detectPrimarySkillKeyword(text: string): SkillKeywordMatch | null;
+/**
+ * Match a prompt against the keyword table.
+ *
+ * `learned` carries patterns mined from semantic routing answers (see
+ * `decisions/keyword-learning.ts`). It is a parameter rather than a module-level
+ * load because this file is imported by the hook process, where a synchronous
+ * disk read on every prompt is not acceptable and the caller already knows
+ * whether learning is enabled.
+ */
+export declare function detectSkillKeywords(text: string, learned?: readonly SkillKeywordDefinition[]): SkillKeywordMatch[];
+export declare function detectPrimarySkillKeyword(text: string, learned?: readonly SkillKeywordDefinition[]): SkillKeywordMatch | null;
 export declare function resolveSkcStateDir(cwd: string, stateDir?: string): string;
 export interface StateRecoveryDiagnostic {
     kind: "skill-active-state" | "mode-state";