MoonshotAI · AidenNovak · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026
diff --git a/.changeset/subagent-model-selection.md b/.changeset/subagent-model-selection.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+Add experimental model selection for Agent and AgentSwarm subagents. Enable the `subagent-model-selection` experiment to use configured model aliases.
diff --git a/docs/en/configuration/env-vars.md b/docs/en/configuration/env-vars.md
@@ -127,6 +127,7 @@ Switches that control the behavior of subsystems such as telemetry, background t
 | `KIMI_CODE_PLUGIN_MARKETPLACE_URL` | Override the plugin marketplace JSON loaded by `/plugins`; useful for dev loopback servers, staging CDN files, or alternate marketplace directories | `https://code.kimi.com/kimi-code/plugins/marketplace.json`; also accepts `http://`, `file://` URLs, and local paths |
 | `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` | Cap how many AgentSwarm subagents run concurrently during the initial ramp; leave unset for no cap | Positive integer; invalid values fail fast |
 | `KIMI_SUBAGENT_TIMEOUT_MS` | Maximum wall-clock time (ms) a single subagent (`Agent` / `AgentSwarm`) may run; takes higher priority than `[subagent] timeout_ms` in `config.toml` (default `7200000`, i.e. 2 hours) | Positive integer; invalid values fall back to the config or default |
+| `KIMI_CODE_EXPERIMENTAL_SUBAGENT_MODEL_SELECTION` | Enable the optional `model` parameter and safe configured-model directory for [`Agent` and `AgentSwarm`](../customization/agents.md#how-to-invoke) | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` |
 | `KIMI_CODE_EXPERIMENTAL_FLAG` | Enable all registered experimental features for this process | `1`, `true`, `yes`, `on` |
 | `KIMI_SHELL_PATH` | Override the Git Bash path on Windows (used when auto-detection fails) | Absolute path |
 | `KIMI_MODEL_MAX_COMPLETION_TOKENS` | Hard cap on `max_completion_tokens` per LLM step; applies to the `kimi` provider only | Positive integer; `0` or negative disables clamping |

diff --git a/docs/en/customization/agents.md b/docs/en/customization/agents.md
@@ -22,6 +22,25 @@ Each dispatch is presented in the terminal as an approval request (unless it mat
 
 Sub-agents support running in the background: results are automatically returned to the main Agent upon completion, with no manual polling needed. You can also call back an existing sub-agent instance to continue the same task.
 
+Choosing a model for delegated work is experimental and disabled by default. Enable it persistently in `config.toml`:
+
+```toml
+[experimental]
+subagent-model-selection = true
+```
+
+To enable it only for the current process, set the dedicated environment variable instead:
+
+```sh
+export KIMI_CODE_EXPERIMENTAL_SUBAGENT_MODEL_SELECTION=1
+```
+
+When enabled, the `Agent` and `AgentSwarm` tool schemas (the argument definitions shown to the model) gain an optional `model` parameter. The calling Agent sees a directory built from the model aliases in your configuration and may choose an alias that better fits the delegated task. `Agent` applies the selected alias to the new or resumed sub-agent; `AgentSwarm` applies one alias to every new and resumed sub-agent in the batch. If `model` is omitted, delegated work uses the calling Agent's current model, and resumed sub-agents are realigned to that model.
+
+The directory exposes up to 64 ASCII-safe model aliases plus a restricted set of non-sensitive metadata: known capabilities, context/output limits, and only the fixed thinking-effort values `off`, `on`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Other aliases and metadata values are omitted rather than rewritten, so every displayed alias remains an exact configuration key. The directory never includes display names, API keys, base URLs, custom headers, provider identifiers, provider wire model names, or `passthrough` configuration.
+
+Enabling this experiment allows the calling Agent to choose any alias shown in that directory without a separate model-specific confirmation. When an `Agent` or `AgentSwarm` call still requires approval, the effective model alias is included in the approval label and is frozen for that approved execution. After changing `config.toml`, run `/reload`; the existing session then updates the collaboration tool schemas immediately. Starting a new session works too. Because providers and models can differ in price, context-window size, and capabilities, check the relevant provider's pricing and limits before delegating large batches.
+
 ## Context Isolation and Resource Cost
 
 Each sub-agent has a fully independent context window. It can only see the task description explicitly passed by the main Agent and cannot see the main Agent's conversation history. The sub-agent's own intermediate reasoning and tool call records do not flow back; only the final result appears in the main Agent's context.

diff --git a/docs/en/reference/tools.md b/docs/en/reference/tools.md
@@ -89,9 +89,9 @@ Collaboration tools handle inter-Agent coordination, user interaction, and Skill
 | `AskUserQuestion` | Auto-allow | Ask the user a question to gather structured input |
 | `Skill` | Auto-allow | Invoke a registered inline Skill |
 
-**`Agent`** delegates a subtask to a sub-Agent. Required parameters: `prompt` (complete task description) and `description` (a 3–5 word short summary). Optional parameters: `subagent_type` (defaults to `coder`), `resume` (ID of an existing Agent to resume; mutually exclusive with `subagent_type`), and `run_in_background` (defaults to false). Agent tasks time out after 2 hours by default; the limit is configurable via `[subagent] timeout_ms` in `config.toml` (`0` = no timeout, or the `KIMI_SUBAGENT_TIMEOUT_MS` env var), and defaults to no timeout in print mode (`kimi -p`). In foreground mode the parent Agent waits for the sub-Agent to complete before continuing; in background mode a task ID is returned immediately and the result is automatically delivered back to the main Agent via a synthetic User message when done. When several foreground `Agent` calls run in the same step, the TUI groups them and shows each subagent's running, waiting, completed, or failed status with elapsed time. See [Agent & Sub-Agents](../customization/agents.md) for details.
+**`Agent`** delegates a subtask to a sub-Agent. Required parameters: `prompt` (complete task description) and `description` (a 3–5 word short summary). Optional parameters: `subagent_type` (defaults to `coder`), `resume` (ID of an existing Agent to resume; mutually exclusive with `subagent_type`), and `run_in_background` (defaults to false). When [experimental sub-agent model selection](../customization/agents.md#how-to-invoke) is enabled, the optional `model` parameter selects a configured model alias for a new or resumed subagent; omitting it uses the calling Agent's current model and realigns a resumed subagent to that model. Agent tasks time out after 2 hours by default; the limit is configurable via `[subagent] timeout_ms` in `config.toml` (`0` = no timeout, or the `KIMI_SUBAGENT_TIMEOUT_MS` env var), and defaults to no timeout in print mode (`kimi -p`). In foreground mode the parent Agent waits for the sub-Agent to complete before continuing; in background mode a task ID is returned immediately and the result is automatically delivered back to the main Agent via a synthetic User message when done. When several foreground `Agent` calls run in the same step, the TUI groups them and shows each subagent's running, waiting, completed, or failed status with elapsed time. See [Agent & Sub-Agents](../customization/agents.md) for details.
 
-**`AgentSwarm`** launches subagents from a shared `prompt_template` and an `items` array, resumes existing subagents through `resume_agent_ids`, or combines both in one call. The template must contain the `{{item}}` placeholder; each item replaces that placeholder and launches one new subagent. Pass `subagent_type` to choose the profile used by every spawned subagent in the swarm, or omit it to use `coder`. Without `resume_agent_ids`, the tool requires at least 2 items; with `resume_agent_ids`, it can resume one or more existing subagents. The tool supports up to 128 total subagents, waits for all subagents to finish, and returns an aggregated report. In the TUI, foreground swarms show a live `Agent swarm` progress panel above the input box. If a model response calls `AgentSwarm`, that call must be the only tool call in the response; to run multiple swarms, call one `AgentSwarm`, wait for its result, then call the next, or combine the work into one swarm when a single template can cover it. In `manual` permission mode, `AgentSwarm` calls outside active swarm mode request approval unless a permission rule allows them; while swarm mode is active, `AgentSwarm` itself is auto-approved. Permission rules match `AgentSwarm` by tool name only — argument patterns such as `AgentSwarm(swarm)` are not supported. By default the tool ramps up concurrency without an upper limit (5 subagents start immediately, then 1 more every 700 ms); set `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` to a positive integer to cap how many subagents run at the same time during that ramp, or leave it unset for no cap. If it is set to a value that is not a positive integer, the AgentSwarm call fails fast.
+**`AgentSwarm`** launches subagents from a shared `prompt_template` and an `items` array, resumes existing subagents through `resume_agent_ids`, or combines both in one call. The template must contain the `{{item}}` placeholder; each item replaces that placeholder and launches one new subagent. Pass `subagent_type` to choose the profile used by every spawned subagent in the swarm, or omit it to use `coder`. When [experimental sub-agent model selection](../customization/agents.md#how-to-invoke) is enabled, the optional `model` parameter selects one configured model alias for the entire batch, including both new and resumed subagents; omitting it uses the calling Agent's current model. Without `resume_agent_ids`, the tool requires at least 2 items; with `resume_agent_ids`, it can resume one or more existing subagents. The tool supports up to 128 total subagents, waits for all subagents to finish, and returns an aggregated report. In the TUI, foreground swarms show a live `Agent swarm` progress panel above the input box. If a model response calls `AgentSwarm`, that call must be the only tool call in the response; to run multiple swarms, call one `AgentSwarm`, wait for its result, then call the next, or combine the work into one swarm when a single template can cover it. In `manual` permission mode, `AgentSwarm` calls outside active swarm mode request approval unless a permission rule allows them; while swarm mode is active, `AgentSwarm` itself is auto-approved. Permission rules match `AgentSwarm` by tool name only — argument patterns such as `AgentSwarm(swarm)` are not supported. By default the tool ramps up concurrency without an upper limit (5 subagents start immediately, then 1 more every 700 ms); set `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` to a positive integer to cap how many subagents run at the same time during that ramp, or leave it unset for no cap. If it is set to a value that is not a positive integer, the AgentSwarm call fails fast.
 
 **`AskUserQuestion`** asks the user a structured multiple-choice question — useful for disambiguation or option selection. The `questions` parameter accepts 1–4 questions; each question requires `question` (ending with `?`), `options` (2–4 choices, each with a `label` and `description`), and optional `header` (max 12 characters) and `multi_select` (defaults to false). An "Other" option is appended automatically. Setting `background` to true starts a background question task and returns a task ID immediately. When the host does not support interactive questioning, a failure message is returned and the Agent should ask the user directly in a text reply instead.
 

diff --git a/docs/zh/configuration/env-vars.md b/docs/zh/configuration/env-vars.md
@@ -127,6 +127,7 @@ kimi
 | `KIMI_CODE_PLUGIN_MARKETPLACE_URL` | 覆盖 `/plugins` 加载的 plugin marketplace JSON，适合 dev loopback server、测试 CDN 文件或替换 marketplace 目录 | `https://code.kimi.com/kimi-code/plugins/marketplace.json`；也接受 `http://`、`file://` URL 和本地路径 |
 | `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` | 限制 AgentSwarm 初始提升并发阶段可同时运行的子 Agent 数量；不设置表示不限制 | 正整数；非法值会立即失败 |
 | `KIMI_SUBAGENT_TIMEOUT_MS` | 单个子 Agent（`Agent` / `AgentSwarm`）可运行的最长时间（毫秒）；优先级高于 `config.toml` 的 `[subagent] timeout_ms`（默认 `7200000`，即 2 小时） | 正整数；非法值回退到配置或默认值 |
+| `KIMI_CODE_EXPERIMENTAL_SUBAGENT_MODEL_SELECTION` | 为 [`Agent` 和 `AgentSwarm`](../customization/agents.md#调用方式) 启用可选的 `model` 参数及安全的已配置模型目录 | 真值：`1`/`true`/`yes`/`on`；假值：`0`/`false`/`no`/`off` |
 | `KIMI_CODE_EXPERIMENTAL_FLAG` | 在当前进程启用所有已注册的实验功能 | `1`、`true`、`yes`、`on` |
 | `KIMI_SHELL_PATH` | Windows 上覆盖 Git Bash 路径（自动探测失败时使用） | 绝对路径 |
 | `KIMI_MODEL_MAX_COMPLETION_TOKENS` | 单步 LLM 请求的 `max_completion_tokens` 硬上限，仅对 `kimi` 供应商生效 | 正整数；`0` 或负数禁用 clamp |

diff --git a/docs/zh/customization/agents.md b/docs/zh/customization/agents.md
@@ -22,6 +22,25 @@ Kimi Code CLI 内置三种子 Agent，开箱即用，分别面向不同任务形
 
 子 Agent 支持在后台运行：完成后结果自动回到主 Agent，无需手动轮询。也可以唤回已有的子 Agent 实例继续推进同一任务。
 
+为委派任务选择模型是一项默认关闭的实验功能。如需持久启用，在 `config.toml` 中写入：
+
+```toml
+[experimental]
+subagent-model-selection = true
+```
+
+如果只想为当前进程启用，也可以改用专用环境变量：
+
+```sh
+export KIMI_CODE_EXPERIMENTAL_SUBAGENT_MODEL_SELECTION=1
+```
+
+启用后，`Agent` 和 `AgentSwarm` 工具的参数定义会增加可选的 `model`。调用方 Agent 会看到一个根据配置中模型别名生成的目录，并可选择更适合委派任务的别名。`Agent` 会把所选别名应用到新建或恢复的子 Agent；`AgentSwarm` 则会让整个 batch 中新建和恢复的所有子 Agent 共用同一个别名。省略 `model` 时，委派任务使用调用方 Agent 的当前模型，恢复的子 Agent 也会重新对齐到该模型。
+
+这个目录最多展示 64 个 ASCII 安全的模型别名，以及一组受限的非敏感信息：已知能力、上下文/输出上限，以及固定集合中的 Thinking 强度 `off`、`on`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。其他别名和元数据值会被整条省略而不是改写，因此每个已展示的别名仍是精确的配置键。目录不会包含显示名称、API 密钥、base URL、自定义 HTTP header、供应商标识、供应商侧模型名或 `passthrough` 配置。
+
+启用这项实验功能，即表示允许调用方 Agent 在不进行额外的按模型确认的情况下，选择目录中展示的任意别名。如果 `Agent` 或 `AgentSwarm` 调用仍需审批，审批标签会显示有效模型别名，并将它固定给本次已审批的执行。修改 `config.toml` 后运行 `/reload`，当前会话中的协作工具参数定义会立即更新；新建会话也可以。不同供应商和模型的价格、上下文窗口与能力可能不同；在大批量委派前，请先查看对应供应商的计费与限制。
+
 ## 上下文隔离与资源开销
 
 每个子 Agent 拥有完全独立的上下文窗口，只能看到主 Agent 显式传入的任务描述，看不到主 Agent 的对话历史。子 Agent 自己的中间思考和工具调用记录不会回流，只有最终结果会出现在主 Agent 的上下文里。