feat: replace the secondary-model experiment with a declarative subagent model pool

[7Sageer]

Related Issue

No tracking issue — the problem is explained below.

Problem

The experimental secondary model ([secondary_model] recipe + KIMI_SECONDARY_MODEL / KIMI_SECONDARY_EFFORT env vars + the agent-file model_preference field) gives subagents a single fallback model and is wired through SDK session-apply APIs (Session.applyPersistedSecondaryModel, a synthesized __secondary__ model entry). The main agent cannot choose a subagent model per spawn, and the recipe does not fit the v2 engine's config-section architecture.

What changed

v2 engine — declarative subagent model pool in [secondary_model]

• [secondary_model.models] maps configured [models] aliases to the selection hints shown to the main agent; [secondary_model] default_model names the fallback used when a spawn passes no model. A lone default_model (no models table) forms an implicit single-entry pool — the minimal "secondary model" configuration.
• The Agent / AgentSwarm tools gain a model parameter (advertised only when a pool exists): any pool alias, or the reserved symbolic primary, which binds the caller's own model and thinking level. Pool-alias bindings carry no explicit thinking level — thinking resolves naturally (global [thinking] config → the bound model's default effort). Per-entry thinking levels reuse the existing model-overrides mechanism: register a variant alias with [models."<alias>".overrides] default_effort and list it in the pool.
• Pool validation fails loudly (CONFIG_INVALID) at session create / resume / fork on a missing or out-of-pool default_model, an unresolvable alias, or a reserved primary key, with a Session-scope validation service as backstop. Tool descriptions mark [default] / [main model]; the caller's alias stays a normal pool entry because only primary inherits the caller's thinking level.
• The pool keys briefly lived under [subagent] during this PR's iteration; leftover [subagent] default_model / models keys are declared as deprecations pointing to [secondary_model] and no longer apply.
• The secondary-model experiment is removed from the v2 engine, the SDK (Session.applyPersistedSecondaryModel, SECONDARY_DERIVED_MODEL_ALIAS), kap-server, and the agent-file model_preference field on v2.

TUI

• /secondary-model (renamed from /secondary_model): opens a model picker and persists [secondary_model] default_model, adding the picked alias to an existing [secondary_model.models] pool with an empty description when missing (the engine requires the default to be a pool key). The picker hides the no-op Thinking footer; the reserved primary alias is rejected with a rename hint. No live-apply step — the pool resolves per spawn, so the next subagent dispatch picks the new value up.

kap-server

• /api/v1/config accepts and echoes the subagent and secondary_model domains; the snake→camel patch conversion now preserves user-defined map keys under providers / models / experimental / raw (an alias like fast_model previously became fastModel), without leaking preserve mode into a colliding alias's own fields. The __secondary__ derived-entry hiding is gone together with the synthesized entry itself.

Default (v1) engine

• The section is now shared: the v1 schema learns secondary_model.defaultModel / models so a shared config.toml round-trips, and secondaryModelPatch excludes them from the recipe patch. v1 keeps resolving subagent models through the recipe keys (model, default_effort, the env vars) and ignores the pool at runtime.

Docs & changesets: en/zh config-files pages document the pool semantics, the deprecation path from [subagent], and the thinking-variant recipe (a second alias with an overridden default_effort); tools and slash-commands pages updated; two changesets (minor for @moonshot-ai/kimi-code and @moonshot-ai/kimi-code-sdk).

Behavior examples

Configuration — minimal form (every subagent binds kimi-hs by default) vs a full pool:

# Minimal: a lone default_model is an implicit single-entry pool
[secondary_model]
default_model = "kimi-hs"

# Full pool: the main agent picks per spawn
[secondary_model]
default_model = "kimi-hs"
[secondary_model.models]
kimi-hs = "fast and cheap; daily refactoring, explanations, small edits"
k3 = "frontend work"
fable = "hard reasoning tasks"

What the main agent sees — the Agent / AgentSwarm tool description gains a model parameter and renders the pool (here the caller itself runs k3):

Available models (pass via model):
- kimi-hs [default]: fast and cheap; daily refactoring, explanations, small edits
- k3 [main model]: frontend work
- fable: hard reasoning tasks
- primary (k3): the main model you are running on, bound with your current thinking level; use it for hard, quality-sensitive subagent tasks

The two k3 lines differ only in thinking inheritance: a pool-alias binding carries no explicit thinking level (the subagent resolves it from global config / the model's default effort), while primary inherits the caller's model and current thinking level.

/secondary-model — interactive-only path to the minimal form:

• Opens the model picker with the Thinking footer hidden (the selection carries no thinking level); picking a model writes [secondary_model] default_model.
• If a [secondary_model.models] table exists and the picked alias is not in it, the alias is added with an empty description (the engine requires the default to be a pool key); without a table only default_model is written.
• The reserved alias primary is rejected with a rename hint instead of writing a pool the engine would refuse.
• No live-apply step: the pool resolves per spawn, so the next subagent dispatch picks the new value up without a session restart.
• v2 engine only — the default engine ignores [secondary_model] default_model and keeps resolving subagent models through the recipe keys (model, default_effort).

Checklist

• I have read the CONTRIBUTING document.
• I have linked a related issue, or explained the problem above.
• I have added tests that prove my feature works.
• Ran gen-changesets skill, or this PR needs no changeset.
• Ran gen-docs skill, or this PR needs no doc update.

[changeset-bot]

🦋 Changeset detected

Latest commit: add3738

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@moonshot-ai/kimi-code-sdk	Minor
@moonshot-ai/kimi-code	Minor
@moonshot-ai/acp-adapter	Patch
kimi-code	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

pnpm dlx https://pkg.pr.new/@moonshot-ai/kimi-code@add3738

npx https://pkg.pr.new/@moonshot-ai/kimi-code@add3738

commit: add3738