feat(subagent): v0.7.5 — 适配 kimi-code 0.36.0 子代理模型池（双写兼容/池管理/force/前置校验）+ 热力图详情按需加载 + models.dev 刷新（GLM-5.3）

src/components/SubagentSettingsPage.tsx

@@ -8,12 +8,19 @@ import {
   clearSecondaryModel,
   forcedEnvValue,
   getExperimentalFlags,
-  getSecondaryModel,
+  getSubagentModelPool,
   isFlagLockedByEnv,
   isMasterEnvOn,
+  removeSubagentPoolEntry,
   setExperimentalFlag,
   setSecondaryModelOnly,
+  setSubagentDefault,
+  setSubagentForce,
+  upsertSubagentPoolEntry,
+  validateSubagentPool,
   type ExperimentalFlagDef,
+  type PoolValidationError,
+  type ValidationErrorKey,
 } from "../lib/subagent-settings";
 import { Card, Toggle } from "./ui/controls";
 
@@ -44,6 +51,97 @@ const FLAG_LABELS: Record<string, { name: TranslationKey; desc: TranslationKey }
   },
 };
 
+/** Validation-error i18n key per engine rule, for the pre-write self-check. */
+const POOL_ERROR_KEYS: Record<ValidationErrorKey, TranslationKey> = {
+  primaryReserved: "secondaryPoolErrorPrimaryReserved",
+  defaultRequired: "secondaryPoolErrorDefaultRequired",
+  defaultNotInPool: "secondaryPoolErrorDefaultNotInPool",
+  aliasNotInModels: "secondaryPoolErrorAliasNotInModels",
+  forceRequiresDefault: "secondaryPoolErrorForceRequiresDefault",
+  forceExcludesModels: "secondaryPoolErrorForceExcludesModels",
+};
+
+/**
+ * One row of the subagent model pool: default radio + alias + editable
+ * description (saved on blur/Enter via the parent's write chain) + remove.
+ * The description input keeps a local draft so typing is not persisted per
+ * keystroke; everything else is derived from `rawOther` on each render.
+ */
+function PoolEntryRow({
+  alias,
+  displayName,
+  description,
+  isDefault,
+  canRemove,
+  onSetDefault,
+  onSave,
+  onRemove,
+}: {
+  alias: string;
+  displayName: string | null;
+  description: string;
+  isDefault: boolean;
+  canRemove: boolean;
+  onSetDefault: (alias: string) => void;
+  onSave: (alias: string, description: string) => void;
+  onRemove: (alias: string) => void;
+}) {
+  const { t } = useTranslation();
+  const [draft, setDraft] = useState(description);
+
+  const commit = () => {
+    if (draft === description) return;
+    onSave(alias, draft);
+  };
+
+  return (
+    <div className="flex items-center gap-2 text-sm">
+      <input
+        type="radio"
+        checked={isDefault}
+        aria-label={t("setDefault")}
+        onChange={() => onSetDefault(alias)}
+        className="shrink-0 accent-blue-600 focus:ring-blue-500"
+      />
+      <span className="shrink-0 font-medium text-content-primary">{alias}</span>
+      {displayName && (
+        <span className="shrink-0 text-xs text-content-muted">{displayName}</span>
+      )}
+      {isDefault && (
+        <span className="shrink-0 text-xs text-blue-600 dark:text-blue-400 border border-blue-500/30 rounded px-1">
+          {t("default")}
+        </span>
+      )}
+      <input
+        type="text"
+        value={draft}
+        placeholder={t("secondaryPoolDescPlaceholder")}
+        onChange={(e) => setDraft(e.target.value)}
+        onBlur={commit}
+        onKeyDown={(e) => {
+          if (e.key === "Enter") {
+            e.preventDefault();
+            (e.currentTarget as HTMLInputElement).blur();
+          } else if (e.key === "Escape") {
+            setDraft(description);
+            (e.currentTarget as HTMLInputElement).blur();
+          }
+        }}
+        className="flex-1 min-w-0 bg-input border border-border rounded px-2 py-1 text-xs focus:ring-2 focus:ring-blue-500 focus:outline-none"
+      />
+      {canRemove && (
+        <button
+          type="button"
+          onClick={() => onRemove(alias)}
+          className="shrink-0 px-2 py-1 text-xs border border-border rounded hover:bg-hover-2 text-content-muted focus:ring-2 focus:ring-blue-500 focus:outline-none"
+        >
+          {t("secondaryPoolRemove")}
+        </button>
+      )}
+    </div>
+  );
+}
+
 export function SubagentSettingsPage({
   rawOther,
   models,
@@ -52,6 +150,10 @@ export function SubagentSettingsPage({
 }: SubagentSettingsPageProps) {
   const { t } = useTranslation();
   const [env, setEnv] = useState<ExperimentalEnvStatus | null>(null);
+  /** Pre-write validation failures (fallback guard; normal flows stay clear). */
+  const [poolErrors, setPoolErrors] = useState<PoolValidationError[]>([]);
+  /** Local draft for the "add pool entry" select (reset after each pick). */
+  const [addSelection, setAddSelection] = useState("");
 
   useEffect(() => {
     invoke<ExperimentalEnvStatus>("get_experimental_env_status")
@@ -60,7 +162,17 @@ export function SubagentSettingsPage({
   }, []);
 
   const flags = getExperimentalFlags(rawOther);
-  const secondary = getSecondaryModel(rawOther);
+  const pool = getSubagentModelPool(rawOther);
+  const poolKeys = pool ? Object.keys(pool.models) : [];
+  // View selection: no/empty section or a bare legacy `model` → simple view;
+  // a `models` table or `default_model` → pool management view.
+  const isPoolView =
+    !!pool && (poolKeys.length > 0 || pool.defaultModel !== undefined);
+  // Effective default: v2 pool key first, legacy v1 recipe key as fallback.
+  const effectiveDefault = pool ? pool.defaultModel ?? pool.model : undefined;
+  // "Upgrade" only makes sense for the bare legacy form and when `force` is
+  // off — upgrading with force would create an invalid force+pool-table combo.
+  const canUpgrade = !!pool && !isPoolView && pool.model !== undefined && !pool.force;
   const masterOn = isMasterEnvOn(env);
   const secondaryFlag = EXPERIMENTAL_FLAGS[0]; // "secondary-model"
   const otherFlags = EXPERIMENTAL_FLAGS.slice(1);
@@ -75,10 +187,25 @@ export function SubagentSettingsPage({
 
   const aliasList = Object.keys(models).sort();
 
+  const aliasLabel = (alias: string): string =>
+    models[alias]?.display_name
+      ? `${alias}（${models[alias].display_name}）`
+      : alias;
+
+  // Rows of the pool view: every `models` table key plus the effective default
+  // when it is not already in the table (the implicit single-entry form).
+  const implicitDefault =
+    pool && effectiveDefault && !(effectiveDefault in pool.models)
+      ? [effectiveDefault]
+      : [];
+  const poolEntries = [...poolKeys, ...implicitDefault];
+  // Aliases that can still be added to the pool (not already in the table).
+  const addableAliases = aliasList.filter((a) => !(a in (pool?.models ?? {})));
+
   // Inherited settings shown for the picked model: subagents bind the pointed
   // entry directly (no patch fields), so context size and effort come from the
   // model entry / global [thinking], not from a `[secondary_model]` patch.
-  const selectedEntry = secondary.model ? models[secondary.model] : undefined;
+  const selectedEntry = effectiveDefault ? models[effectiveDefault] : undefined;
   const inheritedContext = selectedEntry?.max_context_size;
   const modelEffort =
     selectedEntry &&
@@ -106,6 +233,61 @@ export function SubagentSettingsPage({
     return key ? t(key) : e;
   };
 
+  /**
+   * Fallback guard before any pool-related write: validate the *target* state
+   * against the engine rules (mirrored by `validateSubagentPool`) and block the
+   * write when it would produce an invalid config. Normal UI flows never trip
+   * this — it protects against stale/divergent configs.
+   */
+  const validateWrite = (nextRaw: unknown): boolean => {
+    const nextPool = getSubagentModelPool(nextRaw);
+    const errors = nextPool ? validateSubagentPool(nextPool, aliasList) : [];
+    setPoolErrors(errors);
+    return errors.length === 0;
+  };
+
+  const handleUpgrade = () => {
+    if (!effectiveDefault) return;
+    const nextRaw = setSubagentDefault(rawOther, effectiveDefault);
+    if (validateWrite(nextRaw)) onChange(nextRaw);
+  };
+
+  const handleSetDefault = (alias: string) => {
+    if (alias === effectiveDefault) return;
+    const nextRaw = setSubagentDefault(rawOther, alias);
+    if (validateWrite(nextRaw)) onChange(nextRaw);
+  };
+
+  const handleSaveDescription = (alias: string, description: string) => {
+    const nextRaw = upsertSubagentPoolEntry(rawOther, alias, description);
+    if (validateWrite(nextRaw)) onChange(nextRaw);
+  };
+
+  const handleRemoveEntry = (alias: string) => {
+    const nextRaw = removeSubagentPoolEntry(rawOther, alias);
+    if (validateWrite(nextRaw)) onChange(nextRaw);
+  };
+
+  const handleAddEntry = (alias: string) => {
+    const nextRaw = upsertSubagentPoolEntry(rawOther, alias, "");
+    if (validateWrite(nextRaw)) onChange(nextRaw);
+  };
+
+  const handleForceChange = (next: boolean) => {
+    if (!pool) return;
+    // Turning force on drops the `models` table — confirm when it is non-empty.
+    if (next && Object.keys(pool.models).length > 0) {
+      if (!confirm(t("secondaryPoolForceConfirm"))) return;
+    }
+    const nextRaw = setSubagentForce(rawOther, next);
+    if (validateWrite(nextRaw)) onChange(nextRaw);
+  };
+
+  const handleClear = () => {
+    setPoolErrors([]);
+    onChange(clearSecondaryModel(rawOther));
+  };
+
   const renderFlagRow = (flag: ExperimentalFlagDef) => {
     const labels = FLAG_LABELS[flag.id];
     const locked = masterOn || isFlagLockedByEnv(env, flag);
@@ -194,36 +376,154 @@ export function SubagentSettingsPage({
           </div>
         </Card>
 
-        {/* Subagent: secondary model picker + inherited settings */}
+        {/* Subagent: secondary model picker / pool + inherited settings */}
         <Card title={t("secondaryModelSection")}>
-          <label className="flex items-center gap-3 text-sm text-content-primary">
-            <span className="text-content-muted">{t("secondaryModelLabel")}</span>
-            <select
-              className="flex-1 max-w-md bg-input border border-border rounded px-2 py-1 text-sm focus:ring-2 focus:ring-blue-500 focus:outline-none"
-              value={secondary.model ?? ""}
-              onChange={(e) => {
-                const alias = e.target.value;
-                if (alias === "") {
-                  onChange(clearSecondaryModel(rawOther));
-                } else {
-                  // Only the model reference is persisted — no patch fields.
-                  // Subagents bind the pointed entry directly and inherit its
-                  // settings; usage records stay keyed on the real alias
-                  // instead of Kimi Code's synthesized `__secondary__` entry.
-                  onChange(setSecondaryModelOnly(rawOther, alias));
-                }
-              }}
+          {isPoolView && pool ? (
+            <>
+              {pool.force ? (
+                /* Force on: the `models` table was dropped — only the pinned
+                   default is shown, entries and "add" are hidden. */
+                <div className="rounded-lg border border-border bg-input/40 px-3 py-2.5">
+                  <div className="text-sm font-medium text-content-primary">
+                    🔒{" "}
+                    {t("secondaryPoolForceOn", {
+                      alias: aliasLabel(effectiveDefault ?? ""),
+                    })}
+                  </div>
+                </div>
+              ) : (
+                <>
+                  <div className="space-y-2">
+                    {poolEntries.map((alias) => (
+                      <PoolEntryRow
+                        key={alias}
+                        alias={alias}
+                        displayName={models[alias]?.display_name ?? null}
+                        description={pool.models[alias] ?? ""}
+                        isDefault={alias === effectiveDefault}
+                        canRemove={alias in pool.models}
+                        onSetDefault={handleSetDefault}
+                        onSave={handleSaveDescription}
+                        onRemove={handleRemoveEntry}
+                      />
+                    ))}
+                  </div>
+                  <p className="text-xs text-content-muted">
+                    {t("secondaryPoolDescHint")}
+                  </p>
+                  <label className="flex items-center gap-3 text-sm text-content-primary">
+                    <span className="shrink-0 text-content-muted">
+                      {t("secondaryPoolAddLabel")}
+                    </span>
+                    <select
+                      className="flex-1 max-w-md bg-input border border-border rounded px-2 py-1 text-sm focus:ring-2 focus:ring-blue-500 focus:outline-none"
+                      value={addSelection}
+                      onChange={(e) => {
+                        const alias = e.target.value;
+                        setAddSelection("");
+                        if (alias) handleAddEntry(alias);
+                      }}
+                    >
+                      <option value="">{t("secondaryPoolAddPlaceholder")}</option>
+                      {addableAliases.map((alias) => (
+                        <option key={alias} value={alias}>
+                          {aliasLabel(alias)}
+                        </option>
+                      ))}
+                    </select>
+                  </label>
+                </>
+              )}
+
+              <div className="flex items-center gap-3">
+                <div className="flex-1 min-w-0">
+                  <div className="text-sm text-content-primary">
+                    {t("secondaryPoolForce")}
+                  </div>
+                  <div className="text-xs text-content-muted">
+                    {t("secondaryPoolForceDesc")}
+                  </div>
+                </div>
+                <Toggle
+                  checked={pool.force}
+                  ariaLabel={t("secondaryPoolForce")}
+                  onChange={handleForceChange}
+                />
+              </div>
+
+              <button
+                type="button"
+                onClick={handleClear}
+                className="px-3 py-1.5 text-sm border border-border rounded hover:bg-hover-2 focus:ring-2 focus:ring-blue-500 focus:outline-none"
+              >
+                {t("secondaryModelClear")}
+              </button>
+            </>
+          ) : (
+            <>
+              <label className="flex items-center gap-3 text-sm text-content-primary">
+                <span className="shrink-0 text-content-muted">
+                  {t("secondaryModelLabel")}
+                </span>
+                <select
+                  className="flex-1 max-w-md bg-input border border-border rounded px-2 py-1 text-sm focus:ring-2 focus:ring-blue-500 focus:outline-none"
+                  value={effectiveDefault ?? ""}
+                  onChange={(e) => {
+                    const alias = e.target.value;
+                    if (alias === "") {
+                      setPoolErrors([]);
+                      onChange(clearSecondaryModel(rawOther));
+                    } else {
+                      // Only the model reference is persisted — no patch fields.
+                      // Subagents bind the pointed entry directly and inherit
+                      // its settings; usage records stay keyed on the real
+                      // alias instead of the synthesized `__secondary__` entry.
+                      const nextRaw = setSecondaryModelOnly(rawOther, alias);
+                      if (validateWrite(nextRaw)) onChange(nextRaw);
+                    }
+                  }}
+                >
+                  <option value="">{t("secondaryModelUnset")}</option>
+                  {aliasList.map((alias) => (
+                    <option key={alias} value={alias}>
+                      {aliasLabel(alias)}
+                    </option>
+                  ))}
+                </select>
+                {pool?.force && (
+                  <span className="shrink-0 text-xs text-content-muted">
+                    🔒 {t("secondaryModelForceBadge")}
+                  </span>
+                )}
+              </label>
+
+              {canUpgrade && (
+                <div className="flex items-center gap-2">
+                  <button
+                    type="button"
+                    onClick={handleUpgrade}
+                    className="px-3 py-1.5 text-sm border border-border rounded hover:bg-hover-2 focus:ring-2 focus:ring-blue-500 focus:outline-none"
+                  >
+                    {t("secondaryPoolUpgrade")}
+                  </button>
+                  <span className="text-xs text-content-muted">
+                    {t("secondaryPoolUpgradeDesc")}
+                  </span>
+                </div>
+              )}
+            </>
+          )}
+
+          {poolErrors.length > 0 && (
+            <div
+              role="alert"
+              className="bg-red-100 dark:bg-red-900/20 border border-red-300 dark:border-red-500/30 rounded-lg px-3 py-2 text-sm text-red-700 dark:text-red-400 space-y-1"
             >
-              <option value="">{t("secondaryModelUnset")}</option>
-              {aliasList.map((alias) => (
-                <option key={alias} value={alias}>
-                  {models[alias]?.display_name
-                    ? `${alias}（${models[alias].display_name}）`
-                    : alias}
-                </option>
+              {poolErrors.map((err, i) => (
+                <div key={i}>{t(POOL_ERROR_KEYS[err.key], err.params)}</div>
               ))}
-            </select>
-          </label>
+            </div>
+          )}
 
           <div className="border-t border-border" />
           <div className="flex items-center gap-3">
@@ -248,7 +548,7 @@ export function SubagentSettingsPage({
             />
           </div>
 
-          {secondary.model !== undefined && (
+          {effectiveDefault !== undefined && (
             <div className="rounded-lg border border-border bg-input/40 px-3 py-2.5 space-y-2">
               <div className="flex items-baseline gap-2 text-sm">
                 <span className="shrink-0 text-content-muted">

src/components/dashboard/DashboardPage.tsx

@@ -1,10 +1,11 @@
-import { useMemo, useState, type ReactNode } from "react";
+import { useState, type ReactNode } from "react";
 import { createPortal } from "react-dom";
+import { invoke } from "@tauri-apps/api/core";
 import { useDashboard, type DashboardRange } from "../../hooks/useDashboard";
 import { useCurrency } from "../../hooks/useCurrency";
 import { useTranslation } from "../../i18n";
 import { fmtInt, fmtPct, fmtTime, fmtTokens } from "../../lib/dashboard-format";
-import { DailyBars, modelColor } from "./DailyBars";
+import { DailyBars } from "./DailyBars";
 import { DailyDetailModal } from "./DailyDetailModal";
 import { Heatmap } from "./Heatmap";
 import { TrendLineChart } from "./TrendLineChart";
@@ -62,11 +63,6 @@ export function DashboardPage() {
   const [heatmapSelected, setHeatmapSelected] = useState<DailyRow | null>(null);
 
   const daily = data?.stats.daily ?? [];
-  const detailDates = useMemo(() => new Set(daily.map((d) => d.date)), [daily]);
-  const heatmapColorMap = useMemo(() => {
-    const unique = [...new Set(daily.flatMap((d) => Object.keys(d.byModel || {})))];
-    return Object.fromEntries(unique.map((m, i) => [m, modelColor(i)]));
-  }, [daily]);
 
   const RANGE_LABELS: Record<DashboardRange, string> = {
     today: t("rangeToday"),
@@ -109,9 +105,21 @@ export function DashboardPage() {
   const rangeTotals = data.rangeTotals;
   const visibleModels = showAllModels ? models : models.slice(0, 8);
 
-  const onHeatmapCellDoubleClick = (cell: HeatmapCell) => {
-    const row = daily.find((d) => d.date === cell.date);
-    if (row) setHeatmapSelected(row);
+  const onHeatmapCellDoubleClick = async (cell: HeatmapCell) => {
+    try {
+      const row = await invoke<DailyRow | null>("get_day_detail", {
+        date: cell.date,
+      });
+      if (row) {
+        setHeatmapSelected(row);
+      } else {
+        setHeatmapSelected(null);
+        alert(t("dayDetailNoData", { date: cell.date }));
+      }
+    } catch (err) {
+      setHeatmapSelected(null);
+      alert(err instanceof Error ? err.message : String(err));
+    }
   };
 
   // Recent pagination
@@ -221,7 +229,7 @@ export function DashboardPage() {
 
       {/* Heatmap — full row */}
       <Card title={t("cardHeatmap")} subtitle={t("cardHeatmapSub")}>
-        <Heatmap heatmap={heatmap} detailDates={detailDates} onCellDoubleClick={onHeatmapCellDoubleClick} />
+        <Heatmap heatmap={heatmap} onCellDoubleClick={onHeatmapCellDoubleClick} />
       </Card>
 
       {/* Usage-trend tabs + Model table side by side */}
@@ -473,7 +481,7 @@ export function DashboardPage() {
           <DailyDetailModal
             day={heatmapSelected}
             dimension="model"
-            colorMap={heatmapColorMap}
+            colorMap={{}}
             unknownProviderLabel={t("providerUnknown")}
             onClose={() => setHeatmapSelected(null)}
           />,

src/components/dashboard/Heatmap.tsx

@@ -7,9 +7,7 @@ import type { HeatmapCell, HeatmapData } from "../../types/dashboard";
 
 interface HeatmapProps {
   heatmap: HeatmapData;
-  /** Set of dates (YYYY-MM-DD) that have detail data in the current range. */
-  detailDates?: Set<string>;
-  /** Called when a cell with detail data is double-clicked. */
+  /** Called when a cell with data (level > 0) is double-clicked. */
   onCellDoubleClick?: (cell: HeatmapCell) => void;
 }
 
@@ -34,7 +32,7 @@ interface HoverState {
   y: number;
 }
 
-export function Heatmap({ heatmap, detailDates, onCellDoubleClick }: HeatmapProps) {
+export function Heatmap({ heatmap, onCellDoubleClick }: HeatmapProps) {
   const { t, lang } = useTranslation();
   const cells = heatmap?.cells || [];
   const monthLabels = heatmap?.monthLabels || [];
@@ -176,7 +174,7 @@ export function Heatmap({ heatmap, detailDates, onCellDoubleClick }: HeatmapProp
                       );
                     }
                     const level = cell.level ?? 0;
-                    const hasDetail = detailDates ? detailDates.has(cell.date) : level > 0;
+                    const hasDetail = level > 0;
                     return (
                       <button
                         key={cell.date}

src/i18n/en.ts

@@ -227,6 +227,7 @@ export const enTranslations: Record<TranslationKey, string> = {
 
   // Daily detail modal
   dayDetail: "Daily usage detail",
+  dayDetailNoData: "No usage data for {date}",
   close: "Close",
   totalTokens: "Total tokens",
   cost: "Cost",
@@ -477,7 +478,35 @@ export const enTranslations: Record<TranslationKey, string> = {
   secondaryModelHint:
     "Second model config bound to subagents by default; when unset, subagents inherit the primary model. Only the model reference is stored; subagents inherit all of that model's settings",
   secondaryModelPriorityHint:
-    "Priority: explicit tool model param > profile model_preference > this config > inherit primary model",
+    "Priority (v2): tool model param (pool alias or primary) > default_model > inherit primary; (v1 legacy): tool param > model_preference > model > inherit primary",
+
+  // Subagent model pool (secondary_model v2 keys)
+  secondaryPoolUpgrade: "Upgrade to model pool",
+  secondaryPoolUpgradeDesc:
+    "Writes default_model in sync with model (dual-write for both engines); more pool entries can be added afterwards",
+  secondaryPoolAddLabel: "Add pool entry",
+  secondaryPoolAddPlaceholder: "Select a model to add to the pool…",
+  secondaryPoolRemove: "Remove",
+  secondaryPoolDescPlaceholder: "Subagent routing description for this model…",
+  secondaryPoolDescHint:
+    "The description is rendered into the main agent's tool description (Agent/AgentSwarm) and directly affects how well the main model routes to subagent models",
+  secondaryPoolForce: "Force default model",
+  secondaryPoolForceDesc:
+    "When enabled, all subagents are forced onto the default model; force excludes pool entries, which are removed",
+  secondaryPoolForceOn: "Force is on: subagents always use \"{alias}\"",
+  secondaryPoolForceConfirm:
+    "Enabling force removes every pool entry, keeping only the default model. Continue?",
+  secondaryModelClear: "Clear subagent config",
+  secondaryModelForceBadge: "Force on: subagents always use this model",
+  secondaryPoolErrorPrimaryReserved:
+    "\"{alias}\" is a reserved alias and cannot be a pool entry",
+  secondaryPoolErrorDefaultRequired: "default_model is required when pool entries exist",
+  secondaryPoolErrorDefaultNotInPool: "Default model \"{alias}\" is not in the pool",
+  secondaryPoolErrorAliasNotInModels: "Model \"{alias}\" is not registered in [models]",
+  secondaryPoolErrorForceRequiresDefault:
+    "A default model is required before enabling force",
+  secondaryPoolErrorForceExcludesModels:
+    "force is mutually exclusive with pool entries",
 
   // Kimi Code WebUI quick open
   webuiSection: "Kimi Code WebUI",

src/i18n/zh.ts

@@ -222,6 +222,7 @@ export const zhTranslations = {
 
   // Daily detail modal
   dayDetail: "每日用量详情",
+  dayDetailNoData: "「{date}」当日无用量数据",
   close: "关闭",
   totalTokens: "总 Token",
   cost: "费用",
@@ -472,7 +473,32 @@ export const zhTranslations = {
   secondaryModelHint:
     "子代理默认绑定的第二份模型配置；未配置时子代理继承主模型；仅保存模型引用，子代理继承该模型的全部设置",
   secondaryModelPriorityHint:
-    "优先级：工具显式 model 参数 > 子代理 profile 的 model_preference > 本配置 > 继承主模型",
+    "优先级（v2）：工具 model 参数（池别名或 primary）> default_model > 继承主模型；（v1 legacy）：工具参数 > model_preference > model > 继承主模型",
+
+  // Subagent model pool (secondary_model v2 keys)
+  secondaryPoolUpgrade: "升级为模型池",
+  secondaryPoolUpgradeDesc:
+    "为旧式配置补写 default_model，与 model 双写一致；之后可继续添加多个池条目",
+  secondaryPoolAddLabel: "添加池条目",
+  secondaryPoolAddPlaceholder: "选择要加入模型池的模型…",
+  secondaryPoolRemove: "移除",
+  secondaryPoolDescPlaceholder: "该模型的子代理路由描述…",
+  secondaryPoolDescHint:
+    "描述会渲染进主 Agent 的工具描述（Agent/AgentSwarm），直接影响主模型挑选子代理模型的路由质量",
+  secondaryPoolForce: "强制使用默认模型",
+  secondaryPoolForceDesc:
+    "开启后所有子代理固定使用默认模型；force 与模型池条目互斥，条目将被移除",
+  secondaryPoolForceOn: "force 已开启：子代理固定使用「{alias}」",
+  secondaryPoolForceConfirm:
+    "开启 force 将移除模型池中的所有条目，只保留默认模型。确定继续？",
+  secondaryModelClear: "不再配置",
+  secondaryModelForceBadge: "force 已开启：子代理固定使用该模型",
+  secondaryPoolErrorPrimaryReserved: "「{alias}」是保留别名，不能用作模型池条目",
+  secondaryPoolErrorDefaultRequired: "存在模型池条目时 default_model 必填",
+  secondaryPoolErrorDefaultNotInPool: "默认模型「{alias}」不在模型池中",
+  secondaryPoolErrorAliasNotInModels: "模型「{alias}」未在 [models] 中注册",
+  secondaryPoolErrorForceRequiresDefault: "开启 force 前必须设置默认模型",
+  secondaryPoolErrorForceExcludesModels: "force 与模型池条目互斥",
 
   // Kimi Code WebUI quick open
   webuiSection: "Kimi Code WebUI",

src/lib/subagent-settings.test.ts

@@ -0,0 +1,426 @@
+import { describe, expect, it } from "vitest";
+import {
+  getSecondaryModel,
+  getSubagentModelPool,
+  removeSubagentPoolEntry,
+  setSecondaryModelOnly,
+  setSubagentDefault,
+  setSubagentForce,
+  setSubagentModelPool,
+  upsertSubagentPoolEntry,
+  validateSubagentPool,
+  type SubagentModelPool,
+} from "./subagent-settings";
+
+// ---------------------------------------------------------------------------
+// Helpers — drill into the `[secondary_model]` section of the written result
+// ---------------------------------------------------------------------------
+
+function rawWith(section: Record<string, unknown>): unknown {
+  return { secondary_model: section };
+}
+
+function section(raw: unknown): Record<string, unknown> {
+  const root = raw as { secondary_model?: unknown };
+  const sec = root?.secondary_model;
+  return sec && typeof sec === "object" && !Array.isArray(sec)
+    ? (sec as Record<string, unknown>)
+    : {};
+}
+
+function modelsOf(raw: unknown): Record<string, unknown> {
+  const m = section(raw)["models"];
+  return m && typeof m === "object" && !Array.isArray(m)
+    ? (m as Record<string, unknown>)
+    : {};
+}
+
+// ---------------------------------------------------------------------------
+// Reading — four config combinations + effective-default normalization
+// ---------------------------------------------------------------------------
+
+describe("getSecondaryModel / getSubagentModelPool", () => {
+  it("returns an empty config / undefined pool when the section is absent or empty", () => {
+    expect(getSecondaryModel({})).toEqual({});
+    expect(getSubagentModelPool({})).toBeUndefined();
+    expect(getSubagentModelPool(rawWith({}))).toBeUndefined();
+  });
+
+  it("legacy `model` alone forms the effective default", () => {
+    const raw = rawWith({ model: "kimi-k2" });
+    expect(getSecondaryModel(raw)).toEqual({ model: "kimi-k2" });
+    const pool = getSubagentModelPool(raw);
+    expect(pool).toEqual({ model: "kimi-k2", models: {}, force: false });
+    expect(pool?.defaultModel ?? pool?.model).toBe("kimi-k2");
+  });
+
+  it("`default_model` alone forms the effective default", () => {
+    const raw = rawWith({ default_model: "kimi-k2" });
+    expect(getSecondaryModel(raw)).toEqual({ default_model: "kimi-k2" });
+    const pool = getSubagentModelPool(raw);
+    expect(pool?.defaultModel).toBe("kimi-k2");
+    expect(pool?.model).toBeUndefined();
+    expect(pool?.defaultModel ?? pool?.model).toBe("kimi-k2");
+  });
+
+  it("a divergent `model` + `default_model` resolves the effective default to `default_model`", () => {
+    const raw = rawWith({ model: "kimi-k2", default_model: "kimi-k1" });
+    expect(getSecondaryModel(raw)).toEqual({
+      model: "kimi-k2",
+      default_model: "kimi-k1",
+    });
+    const pool = getSubagentModelPool(raw);
+    expect(pool?.model).toBe("kimi-k2");
+    expect(pool?.defaultModel).toBe("kimi-k1");
+    expect(pool?.defaultModel ?? pool?.model).toBe("kimi-k1");
+  });
+
+  it("reads the models table filtering non-string values, and force", () => {
+    const raw = rawWith({
+      default_model: "kimi-k2",
+      models: { "kimi-k2": "Kimi K2", "kimi-k2-thinking": 42, broken: true },
+      force: true,
+    });
+    expect(getSecondaryModel(raw).models).toEqual({ "kimi-k2": "Kimi K2" });
+    expect(getSecondaryModel(raw).force).toBe(true);
+    expect(getSubagentModelPool(raw)).toMatchObject({
+      models: { "kimi-k2": "Kimi K2" },
+      force: true,
+    });
+  });
+
+  it("reports `force` only when true and tolerates a malformed models table", () => {
+    expect(getSecondaryModel(rawWith({ force: false })).force).toBeUndefined();
+    expect(getSubagentModelPool(rawWith({ force: false }))?.force).toBe(false);
+    const pool = getSubagentModelPool(rawWith({ models: "nope", model: "kimi-k2" }));
+    expect(pool?.models).toEqual({});
+    expect(pool?.model).toBe("kimi-k2");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// setSecondaryModelOnly — pool-aware pick
+// ---------------------------------------------------------------------------
+
+describe("setSecondaryModelOnly", () => {
+  it("creates the section when absent", () => {
+    const next = setSecondaryModelOnly({}, "kimi-k2");
+    expect(section(next)).toEqual({ model: "kimi-k2" });
+  });
+
+  it("without a pool: writes only `model`, drops known patch fields, keeps unknown fields", () => {
+    const raw = rawWith({
+      model: "old",
+      default_effort: "high",
+      max_output_size: 64000,
+      max_context_size: 128000,
+      custom_field: "keep",
+    });
+    const next = setSecondaryModelOnly(raw, "kimi-k2");
+    expect(section(next)).toEqual({ model: "kimi-k2", custom_field: "keep" });
+  });
+
+  it("pool via default_model: syncs both keys, adds a missing alias to the table, preserves the rest", () => {
+    const raw = rawWith({
+      default_model: "kimi-k1",
+      models: { "kimi-k1": "K1" },
+      force: true,
+      unknown_field: "keep",
+    });
+    const next = setSecondaryModelOnly(raw, "kimi-k2");
+    expect(section(next)).toEqual({
+      default_model: "kimi-k2",
+      model: "kimi-k2",
+      models: { "kimi-k1": "K1", "kimi-k2": "" },
+      force: true,
+      unknown_field: "keep",
+    });
+  });
+
+  it("pool via models table: keeps existing descriptions", () => {
+    const raw = rawWith({ models: { "kimi-k1": "K1", "kimi-k2": "K2" } });
+    const next = setSecondaryModelOnly(raw, "kimi-k2");
+    expect(modelsOf(next)).toEqual({ "kimi-k1": "K1", "kimi-k2": "K2" });
+    expect(section(next).default_model).toBe("kimi-k2");
+    expect(section(next).model).toBe("kimi-k2");
+  });
+
+  it("heals a divergent legacy + pool default to the picked alias", () => {
+    const raw = rawWith({
+      model: "kimi-k1",
+      default_model: "kimi-k2",
+      models: { "kimi-k1": "K1", "kimi-k2": "K2" },
+    });
+    const next = setSecondaryModelOnly(raw, "kimi-k1");
+    expect(section(next).model).toBe("kimi-k1");
+    expect(section(next).default_model).toBe("kimi-k1");
+    expect(modelsOf(next)).toEqual({ "kimi-k1": "K1", "kimi-k2": "K2" });
+  });
+
+  it("preserves other top-level raw_other sections", () => {
+    const raw = {
+      experimental: { "secondary-model": true },
+      secondary_model: { model: "kimi-k1" },
+    };
+    const next = setSecondaryModelOnly(raw, "kimi-k2") as {
+      experimental?: unknown;
+    };
+    expect(next.experimental).toEqual({ "secondary-model": true });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Pool mutations — rebuild / upsert / remove / default
+// ---------------------------------------------------------------------------
+
+describe("pool mutations", () => {
+  it("setSubagentModelPool rebuilds with dual-written default (effective wins) and force", () => {
+    const raw = rawWith({ model: "stale", custom: "keep" });
+    const next = setSubagentModelPool(raw, {
+      defaultModel: "kimi-k2",
+      model: "kimi-k1", // divergent — effective default (`defaultModel`) wins
+      models: { "kimi-k2": "K2" },
+      force: true,
+    });
+    expect(section(next)).toEqual({
+      default_model: "kimi-k2",
+      model: "kimi-k2",
+      models: { "kimi-k2": "K2" },
+      force: true,
+      custom: "keep",
+    });
+  });
+
+  it("setSubagentModelPool omits the models table when the pool has no entries", () => {
+    const next = setSubagentModelPool(rawWith({}), {
+      defaultModel: "kimi-k2",
+      models: {},
+      force: false,
+    });
+    expect(section(next)).toEqual({
+      default_model: "kimi-k2",
+      model: "kimi-k2",
+      force: false,
+    });
+  });
+
+  it("setSubagentModelPool is idempotent", () => {
+    const pool: SubagentModelPool = {
+      defaultModel: "kimi-k2",
+      models: { "kimi-k2": "K2" },
+      force: true,
+    };
+    const once = setSubagentModelPool(rawWith({ custom: "keep" }), pool);
+    const twice = setSubagentModelPool(once, pool);
+    expect(once).toEqual(twice);
+  });
+
+  it("upsertSubagentPoolEntry adds and updates aliases, preserving the rest", () => {
+    const raw = rawWith({
+      default_model: "kimi-k1",
+      models: { "kimi-k1": "K1" },
+      force: false,
+    });
+    const added = upsertSubagentPoolEntry(raw, "kimi-k2", "K2");
+    expect(modelsOf(added)).toEqual({ "kimi-k1": "K1", "kimi-k2": "K2" });
+    const updated = upsertSubagentPoolEntry(added, "kimi-k2", "K2 thinking");
+    expect(modelsOf(updated)).toEqual({
+      "kimi-k1": "K1",
+      "kimi-k2": "K2 thinking",
+    });
+    expect(section(updated).default_model).toBe("kimi-k1");
+  });
+
+  it("removeSubagentPoolEntry keeps the default when removing a non-default alias", () => {
+    const raw = rawWith({
+      default_model: "kimi-k1",
+      model: "kimi-k1",
+      models: { "kimi-k1": "K1", "kimi-k2": "K2", "kimi-k3": "K3" },
+    });
+    const next = removeSubagentPoolEntry(raw, "kimi-k3");
+    expect(modelsOf(next)).toEqual({ "kimi-k1": "K1", "kimi-k2": "K2" });
+    expect(section(next).default_model).toBe("kimi-k1");
+    expect(section(next).model).toBe("kimi-k1");
+  });
+
+  it("removeSubagentPoolEntry falls the default back to the first remaining key", () => {
+    const raw = rawWith({
+      default_model: "kimi-k1",
+      model: "kimi-k1",
+      models: { "kimi-k1": "K1", "kimi-k2": "K2" },
+    });
+    const next = removeSubagentPoolEntry(raw, "kimi-k1");
+    expect(modelsOf(next)).toEqual({ "kimi-k2": "K2" });
+    expect(section(next).default_model).toBe("kimi-k2");
+    expect(section(next).model).toBe("kimi-k2");
+  });
+
+  it("removeSubagentPoolEntry collapses an emptied pool to the implicit form", () => {
+    const raw = rawWith({
+      default_model: "kimi-k1",
+      model: "kimi-k1",
+      models: { "kimi-k1": "K1" },
+    });
+    const next = removeSubagentPoolEntry(raw, "kimi-k1");
+    const sec = section(next);
+    expect(sec).not.toHaveProperty("models");
+    expect(sec.default_model).toBe("kimi-k1");
+    expect(sec.model).toBe("kimi-k1");
+  });
+
+  it("setSubagentDefault syncs both keys and adds a missing alias with an empty description", () => {
+    const raw = rawWith({ models: { "kimi-k2": "K2" } });
+    const next = setSubagentDefault(raw, "kimi-k1");
+    expect(section(next).default_model).toBe("kimi-k1");
+    expect(section(next).model).toBe("kimi-k1");
+    expect(modelsOf(next)).toEqual({ "kimi-k2": "K2", "kimi-k1": "" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// setSubagentForce — mutual exclusion with the models table
+// ---------------------------------------------------------------------------
+
+describe("setSubagentForce", () => {
+  it("turning force on drops the models table but keeps the default and unknown fields", () => {
+    const raw = rawWith({
+      default_model: "kimi-k1",
+      model: "kimi-k1",
+      models: { "kimi-k1": "K1", "kimi-k2": "K2" },
+      custom: "keep",
+    });
+    const next = setSubagentForce(raw, true);
+    const sec = section(next);
+    expect(sec).not.toHaveProperty("models");
+    expect(sec.force).toBe(true);
+    expect(sec.default_model).toBe("kimi-k1");
+    expect(sec.model).toBe("kimi-k1");
+    expect(sec.custom).toBe("keep");
+  });
+
+  it("turning force off leaves the models table untouched", () => {
+    const raw = rawWith({
+      default_model: "kimi-k1",
+      models: { "kimi-k1": "K1", "kimi-k2": "K2" },
+      force: true,
+    });
+    const next = setSubagentForce(raw, false);
+    expect(section(next).force).toBe(false);
+    expect(modelsOf(next)).toEqual({ "kimi-k1": "K1", "kimi-k2": "K2" });
+  });
+
+  it("is idempotent in both directions", () => {
+    const raw = rawWith({ force: false, custom: "keep" });
+    expect(setSubagentForce(raw, true)).toEqual(
+      setSubagentForce(setSubagentForce(raw, true), true)
+    );
+    expect(setSubagentForce(raw, false)).toEqual(
+      setSubagentForce(setSubagentForce(raw, false), false)
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateSubagentPool — mirror of the 6 engine rules
+// ---------------------------------------------------------------------------
+
+describe("validateSubagentPool", () => {
+  const aliases = ["kimi-k1", "kimi-k2", "kimi-k3"];
+
+  const pool = (p: Partial<SubagentModelPool>): SubagentModelPool => ({
+    models: {},
+    force: false,
+    ...p,
+  });
+
+  it("accepts a valid pool", () => {
+    expect(
+      validateSubagentPool(
+        pool({
+          defaultModel: "kimi-k2",
+          models: { "kimi-k2": "K2", "kimi-k3": "K3" },
+        }),
+        aliases
+      )
+    ).toEqual([]);
+  });
+
+  it("accepts the implicit single-entry form when the model resolves", () => {
+    expect(validateSubagentPool(pool({ model: "kimi-k2" }), aliases)).toEqual([]);
+  });
+
+  it("accepts force with a model fallback when no pool table exists", () => {
+    expect(
+      validateSubagentPool(pool({ force: true, model: "kimi-k2" }), aliases)
+    ).toEqual([]);
+  });
+
+  it("flags `primary` as a reserved pool key", () => {
+    const byDefault = validateSubagentPool(pool({ defaultModel: "primary" }), aliases);
+    expect(byDefault).toContainEqual({
+      key: "primaryReserved",
+      params: { alias: "primary" },
+    });
+    const byEntry = validateSubagentPool(
+      pool({ defaultModel: "kimi-k1", models: { primary: "" } }),
+      aliases
+    );
+    expect(byEntry).toContainEqual({
+      key: "primaryReserved",
+      params: { alias: "primary" },
+    });
+  });
+
+  it("requires `default_model` when the models table exists", () => {
+    // Strict mirror of the engine: a `model` fallback does not satisfy the
+    // `default_model` requirement once a `models` table is present.
+    expect(
+      validateSubagentPool(
+        pool({ model: "kimi-k2", models: { "kimi-k2": "K2" } }),
+        aliases
+      )
+    ).toEqual([{ key: "defaultRequired" }]);
+  });
+
+  it("flags a default that is not a key of the pool table", () => {
+    const errors = validateSubagentPool(
+      pool({ defaultModel: "kimi-k3", models: { "kimi-k2": "K2" } }),
+      aliases
+    );
+    expect(errors).toContainEqual({
+      key: "defaultNotInPool",
+      params: { alias: "kimi-k3" },
+    });
+  });
+
+  it("flags pool keys that do not resolve in the [models] registry", () => {
+    const errors = validateSubagentPool(
+      pool({ defaultModel: "kimi-k2", models: { "kimi-k2": "K2", ghost: "?" } }),
+      aliases
+    );
+    expect(errors).toContainEqual({
+      key: "aliasNotInModels",
+      params: { alias: "ghost" },
+    });
+    // the implicit single-entry default is checked against the registry too
+    const implicit = validateSubagentPool(pool({ model: "ghost" }), aliases);
+    expect(implicit).toContainEqual({
+      key: "aliasNotInModels",
+      params: { alias: "ghost" },
+    });
+  });
+
+  it("flags force without any default", () => {
+    expect(validateSubagentPool(pool({ force: true }), aliases)).toEqual([
+      { key: "forceRequiresDefault" },
+    ]);
+  });
+
+  it("flags force coexisting with the models table", () => {
+    const errors = validateSubagentPool(
+      pool({ force: true, defaultModel: "kimi-k2", models: { "kimi-k2": "K2" } }),
+      aliases
+    );
+    expect(errors).toContainEqual({ key: "forceExcludesModels" });
+  });
+});

src/lib/subagent-settings.ts

@@ -99,15 +99,48 @@ export function setExperimentalFlag(
 }
 
 // ---------------------------------------------------------------------------
-// [secondary_model] — subagent secondary model
+// [secondary_model] — subagent model pool
 // ---------------------------------------------------------------------------
 
+/**
+ * Parsed subagent model pool (`[secondary_model]` v2 keys). The currently
+ * effective default is `defaultModel ?? model` (v2 pool key first, legacy v1
+ * recipe key as fallback).
+ */
+export interface SubagentModelPool {
+  /** v2 pool default (`default_model`). */
+  defaultModel?: string;
+  /** Legacy v1 recipe key (`model`), kept in sync with `defaultModel`. */
+  model?: string;
+  /** `[models]` table (alias → description); non-string values dropped. */
+  models: Record<string, string>;
+  /** Force subagents onto the default alias. */
+  force: boolean;
+}
+
+/** Known v1 patch fields, dropped when re-picking without a pool so stale
+ *  patches are cleaned up. */
+const PATCH_FIELDS: ReadonlySet<string> = new Set([
+  "default_effort",
+  "max_output_size",
+  "max_context_size",
+]);
+
 /** Read `[secondary_model]` from raw_other; `{}` when absent. */
 export function getSecondaryModel(rawOther: unknown): SecondaryModelConfig {
   const section = asRecord(rawOther)["secondary_model"];
   const cfg = asRecord(section);
   const out: SecondaryModelConfig = {};
+  if (typeof cfg.default_model === "string" && cfg.default_model !== "")
+    out.default_model = cfg.default_model;
   if (typeof cfg.model === "string" && cfg.model !== "") out.model = cfg.model;
+  const models = asRecord(cfg.models);
+  const pool: Record<string, string> = {};
+  for (const [k, v] of Object.entries(models)) {
+    if (typeof v === "string") pool[k] = v;
+  }
+  if (Object.keys(pool).length > 0) out.models = pool;
+  if (cfg.force === true) out.force = true;
   if (typeof cfg.default_effort === "string" && cfg.default_effort !== "")
     out.default_effort = cfg.default_effort;
   if (typeof cfg.max_output_size === "number" && cfg.max_output_size > 0)
@@ -117,15 +150,40 @@ export function getSecondaryModel(rawOther: unknown): SecondaryModelConfig {
   return out;
 }
 
+/** Read the v2 subagent model pool from raw_other; `undefined` when there is
+ *  no `[secondary_model]` section or it is empty. The effective default is
+ *  `defaultModel ?? model`. */
+export function getSubagentModelPool(
+  rawOther: unknown
+): SubagentModelPool | undefined {
+  const section = asRecord(asRecord(rawOther)["secondary_model"]);
+  if (Object.keys(section).length === 0) return undefined;
+  const models: Record<string, string> = {};
+  for (const [k, v] of Object.entries(asRecord(section["models"]))) {
+    if (typeof v === "string") models[k] = v;
+  }
+  const out: SubagentModelPool = { models, force: section["force"] === true };
+  if (typeof section["default_model"] === "string" && section["default_model"] !== "")
+    out.defaultModel = section["default_model"];
+  if (typeof section["model"] === "string" && section["model"] !== "")
+    out.model = section["model"];
+  return out;
+}
+
 /**
- * Write `[secondary_model]` with only the `model` field — no patch fields.
- * Subagents then bind the pointed model entry directly and inherit its
- * settings (context size, capabilities, effort fallback), which also keeps
- * usage records keyed on the real model alias instead of the synthesized
- * `__secondary__` derived entry. Unknown fields already present in the
- * section are preserved; the known patch fields (`default_effort`,
- * `max_output_size`, `max_context_size`) are dropped so stale patches are
- * cleaned up when the model is re-picked.
+ * Write `[secondary_model]` picking the given alias as the subagent model.
+ *
+ * Pool-aware: when a pool exists (`models` table or `default_model` present)
+ * the alias becomes the v2 default (added to the `models` table with an empty
+ * description when missing) and the legacy `model` key is synced; the rest of
+ * the section — `force`, patch fields, unknown fields — is preserved. This
+ * keeps usage records keyed on the real model alias instead of the
+ * synthesized `__secondary__` derived entry.
+ *
+ * Without a pool the legacy single-model form is written: only `model`, with
+ * the known patch fields (`default_effort`, `max_output_size`,
+ * `max_context_size`) dropped so stale patches are cleaned up when the model
+ * is re-picked; unknown fields are preserved.
  */
 export function setSecondaryModelOnly(
   rawOther: unknown,
@@ -133,20 +191,237 @@ export function setSecondaryModelOnly(
 ): unknown {
   const root = { ...asRecord(rawOther) };
   const section = asRecord(asRecord(rawOther)["secondary_model"]);
-  const next: Record<string, unknown> = { model: alias };
-  const knownFields: ReadonlySet<string> = new Set([
-    "model",
-    "default_effort",
-    "max_output_size",
-    "max_context_size",
-  ]);
-  for (const [k, v] of Object.entries(section)) {
-    if (!knownFields.has(k)) next[k] = v;
+  const next: Record<string, unknown> = {};
+  const hasPool =
+    section["models"] !== undefined || section["default_model"] !== undefined;
+  if (hasPool) {
+    for (const [k, v] of Object.entries(section)) next[k] = v;
+    next.default_model = alias;
+    next.model = alias;
+    const models: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(asRecord(next.models))) models[k] = v;
+    if (!(alias in models)) models[alias] = "";
+    next.models = models;
+  } else {
+    for (const [k, v] of Object.entries(section)) {
+      if (!PATCH_FIELDS.has(k)) next[k] = v;
+    }
+    next.model = alias;
   }
   root.secondary_model = next;
   return root;
 }
 
+/**
+ * Rebuild the subagent model pool atomically. `default_model` and `model` are
+ * written with the same value — the effective default, `defaultModel ?? model`
+ * — plus the `models` table and `force`; unknown fields in the section are
+ * preserved. An empty `models` table is omitted: the engine requires
+ * `default_model` to be a key of the table, so an empty table can never be
+ * valid, and omitting it keeps the implicit single-entry form.
+ */
+export function setSubagentModelPool(
+  rawOther: unknown,
+  pool: SubagentModelPool
+): unknown {
+  const root = { ...asRecord(rawOther) };
+  const section = asRecord(asRecord(rawOther)["secondary_model"]);
+  const next: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(section)) next[k] = v;
+  const effective = pool.defaultModel ?? pool.model;
+  if (effective) {
+    next.default_model = effective;
+    next.model = effective;
+  } else {
+    delete next.default_model;
+    delete next.model;
+  }
+  if (Object.keys(pool.models).length > 0) {
+    next.models = { ...pool.models };
+  } else {
+    delete next.models;
+  }
+  next.force = pool.force === true;
+  root.secondary_model = next;
+  return root;
+}
+
+/** Add or update one alias in the pool `models` table. The rest of the
+ *  section (default, force, unknown fields) is preserved untouched. */
+export function upsertSubagentPoolEntry(
+  rawOther: unknown,
+  alias: string,
+  description: string
+): unknown {
+  const root = { ...asRecord(rawOther) };
+  const section = asRecord(asRecord(rawOther)["secondary_model"]);
+  const next: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(section)) next[k] = v;
+  const models: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(asRecord(next.models))) models[k] = v;
+  models[alias] = description;
+  next.models = models;
+  root.secondary_model = next;
+  return root;
+}
+
+/**
+ * Remove one alias from the pool `models` table. If it was the default, the
+ * default falls back to the first remaining key (`default_model` and `model`
+ * are both synced). Removing the last entry drops the `models` table and
+ * leaves `default_model`/`model` in place — the implicit single-entry pool.
+ */
+export function removeSubagentPoolEntry(
+  rawOther: unknown,
+  alias: string
+): unknown {
+  const root = { ...asRecord(rawOther) };
+  const section = asRecord(asRecord(rawOther)["secondary_model"]);
+  const next: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(section)) next[k] = v;
+  const models: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(asRecord(next.models))) {
+    if (k !== alias) models[k] = v;
+  }
+  const remaining = Object.keys(models);
+  if (remaining.length === 0) {
+    delete next.models;
+  } else {
+    next.models = models;
+    if (next.default_model === alias) {
+      next.default_model = remaining[0];
+      next.model = remaining[0];
+    }
+  }
+  root.secondary_model = next;
+  return root;
+}
+
+/** Set the pool default alias, syncing `default_model` and `model`; the alias
+ *  is added to the `models` table with an empty description when missing. */
+export function setSubagentDefault(
+  rawOther: unknown,
+  alias: string
+): unknown {
+  const root = { ...asRecord(rawOther) };
+  const section = asRecord(asRecord(rawOther)["secondary_model"]);
+  const next: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(section)) next[k] = v;
+  const models: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(asRecord(next.models))) models[k] = v;
+  if (!(alias in models)) models[alias] = "";
+  next.models = models;
+  next.default_model = alias;
+  next.model = alias;
+  root.secondary_model = next;
+  return root;
+}
+
+/**
+ * Set the `force` flag. Turning force on drops the `models` table — `force`
+ * and the pool table are mutually exclusive per the engine (the implicit
+ * `default_model`/`model` form stays); turning it off leaves the table
+ * untouched. Everything else in the section is preserved.
+ */
+export function setSubagentForce(
+  rawOther: unknown,
+  force: boolean
+): unknown {
+  const root = { ...asRecord(rawOther) };
+  const section = asRecord(asRecord(rawOther)["secondary_model"]);
+  const next: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(section)) {
+    if (force && k === "models") continue;
+    next[k] = v;
+  }
+  next.force = force;
+  root.secondary_model = next;
+  return root;
+}
+
+/** Keys of validation errors, mirroring the kimi-code engine checks. */
+export type ValidationErrorKey =
+  | "primaryReserved"
+  | "defaultRequired"
+  | "defaultNotInPool"
+  | "aliasNotInModels"
+  | "forceRequiresDefault"
+  | "forceExcludesModels";
+
+/** A pool validation error; `params` carries the offending alias. */
+export interface PoolValidationError {
+  key: ValidationErrorKey;
+  params?: Record<string, string>;
+}
+
+/**
+ * Mirror the kimi-code engine validation for the subagent model pool
+ * (violations fail the kimi session with CONFIG_INVALID):
+ * 1. `"primary"` is reserved and cannot be a pool key;
+ * 2. a `models` table requires `default_model`;
+ * 3. `default_model` must be a key of the `models` table;
+ * 4. every pool key must resolve in the top-level `[models]` registry;
+ * 5. `force` requires a default (`default_model` or the `model` fallback);
+ * 6. `force` and a `models` table are mutually exclusive.
+ *
+ * `availableAliases` is the set of top-level `[models]` aliases. A pool
+ * without a `models` table is the implicit single-entry form: only the
+ * effective default is checked against the registry.
+ */
+export function validateSubagentPool(
+  pool: SubagentModelPool,
+  availableAliases: string[]
+): PoolValidationError[] {
+  const errors: PoolValidationError[] = [];
+  const { defaultModel, model, models, force } = pool;
+  const effectiveDefault = defaultModel ?? model;
+  const poolKeys = Object.keys(models);
+  const hasPoolTable = poolKeys.length > 0;
+  const registry = new Set(availableAliases);
+
+  const aliasError = (alias: string) => {
+    if (alias !== "primary" && !registry.has(alias)) {
+      errors.push({ key: "aliasNotInModels", params: { alias } });
+    }
+  };
+
+  // Rule 1: "primary" is reserved as a pool key.
+  if (effectiveDefault === "primary") {
+    errors.push({ key: "primaryReserved", params: { alias: "primary" } });
+  }
+  for (const key of poolKeys) {
+    if (key === "primary") {
+      errors.push({ key: "primaryReserved", params: { alias: key } });
+    }
+  }
+
+  // Rule 2: a `models` table requires `default_model`.
+  if (hasPoolTable && !defaultModel) {
+    errors.push({ key: "defaultRequired" });
+  }
+
+  // Rule 3: `default_model` must be a key of the `models` table.
+  if (hasPoolTable && defaultModel && !(defaultModel in models)) {
+    errors.push({ key: "defaultNotInPool", params: { alias: defaultModel } });
+  }
+
+  // Rule 4: every pool key must resolve in the `[models]` registry.
+  for (const key of poolKeys) aliasError(key);
+  if (!hasPoolTable && effectiveDefault) aliasError(effectiveDefault);
+
+  // Rule 5: `force` requires a default (`default_model` or `model` fallback).
+  if (force && !effectiveDefault) {
+    errors.push({ key: "forceRequiresDefault" });
+  }
+
+  // Rule 6: `force` and a `models` table are mutually exclusive.
+  if (force && hasPoolTable) {
+    errors.push({ key: "forceExcludesModels" });
+  }
+
+  return errors;
+}
+
 /** Remove `[secondary_model]` entirely (the "not configured" option). */
 export function clearSecondaryModel(rawOther: unknown): unknown {
   const root = { ...asRecord(rawOther) };

src/types/index.ts

@@ -134,13 +134,28 @@ export interface AgentSettings {
 }
 
 /**
- * Kimi Code `[secondary_model]` section of config.toml: the secondary model
- * bound to newly spawned subagents (experimental feature).
- * `model` points at an alias defined in `[models]`; the remaining fields are
- * a patch applied on top of the referenced entry (subagents only).
+ * Kimi Code `[secondary_model]` section of config.toml: the subagent model
+ * pool (experimental feature).
+ *
+ * v2 engine (default) reads the pool keys: `default_model` + `[models]` table
+ * (alias → description) + `force`. `model` is ignored by the v2 validator when
+ * pool keys are present, but is kept in sync with `default_model` so the v1
+ * engine (KIMI_CODE_LEGACY_FLAG=1) resolves the same alias.
+ *
+ * v1 engine reads only the recipe key `model` plus the patch fields; pool keys
+ * are ignored by it. Pool resolution order: `models` table → `default_model` →
+ * `model`.
  */
 export interface SecondaryModelConfig {
+  /** v2: default subagent alias in the pool (a key of `models`). */
+  default_model?: string;
+  /** v2: alias → description table for the subagent model pool. */
+  models?: Record<string, string>;
+  /** v2: force subagents onto the default alias (excludes `models`). */
+  force?: boolean;
+  /** Legacy v1 recipe key — written in sync so KIMI_CODE_LEGACY_FLAG=1 works. */
   model?: string;
+  /** v1 patch fields, applied on top of the referenced entry (v1 only). */
   default_effort?: string;
   max_output_size?: number;
   max_context_size?: number;