MoonshotAI · AGSQ11 · Jun 9, 2026 · Jun 9, 2026 · Jun 9, 2026 · Jun 9, 2026
diff --git a/.changeset/subagent-model-selection.md b/.changeset/subagent-model-selection.md
@@ -0,0 +1,15 @@
+---
+"@moonshot-ai/agent-core": minor
+"@moonshot-ai/kimi-code": minor
+"@moonshot-ai/kosong": patch
+"@moonshot-ai/protocol": patch
+---
+
+Add per-role and per-invocation model selection for subagents.
+
+A new `[subagent_models]` config.toml section maps subagent profile names
+to model aliases so different roles (coder, explore, plan) can use
+different LLM models. The Agent tool also accepts an optional `model`
+parameter to override the model for a single invocation. When a subagent
+uses a model that does not support thinking, the thinking level is
+automatically disabled to avoid API errors.
diff --git a/.changeset/sysprompt-override.md b/.changeset/sysprompt-override.md
@@ -0,0 +1,6 @@
+---
+"@moonshot-ai/agent-core": minor
+"@moonshot-ai/kimi-code": minor
+---
+
+Support overriding the system prompt via `~/.kimi-code/sysprompt.md` or a project-level `.kimi-code/sysprompt.md` file.
diff --git a/apps/kimi-code/src/tui/controllers/subagent-event-handler.ts b/apps/kimi-code/src/tui/controllers/subagent-event-handler.ts
@@ -367,6 +367,7 @@ export class SubAgentEventHandler {
       parentToolCallId: event.parentToolCallId,
       agentName: event.subagentName,
       description: typeof description === 'string' ? description : undefined,
+      modelAlias: event.modelAlias,
     };
   }
 

diff --git a/apps/kimi-code/src/tui/types.ts b/apps/kimi-code/src/tui/types.ts
@@ -93,6 +93,7 @@ export interface BackgroundAgentMetadata {
   readonly parentToolCallId: string;
   readonly agentName?: string;
   readonly description?: string;
+  readonly modelAlias?: string;
 }
 
 export type BackgroundAgentStatusPhase = 'started' | 'completed' | 'failed';

diff --git a/apps/kimi-code/src/tui/utils/background-agent-status.ts b/apps/kimi-code/src/tui/utils/background-agent-status.ts
@@ -28,7 +28,8 @@ export function formatBackgroundAgentTranscript(
         ? `${subject} completed in background`
         : `${subject} failed in background`;
   const tail = phase === 'failed' ? normalizeBackgroundField(extras?.error) : undefined;
-  const detailParts = [normalizeBackgroundField(meta.description), tail].filter(
+  const modelPart = meta.modelAlias !== undefined ? `model: ${meta.modelAlias}` : undefined;
+  const detailParts = [normalizeBackgroundField(meta.description), modelPart, tail].filter(
     (part): part is string => part !== undefined,
   );
 

diff --git a/docs/en/configuration/config-files.md b/docs/en/configuration/config-files.md
@@ -84,6 +84,7 @@ Fields in the config file fall into two categories: **top-level scalars** that d
 | `telemetry` | `boolean` | `true` | Whether anonymous telemetry is enabled; disabled only when explicitly set to `false` |
 | `providers` | `table` | `{}` | API provider table → [`providers`](#providers) |
 | `models` | `table` | — | Model alias table → [`models`](#models) |
+| `subagent_models` | `table` | — | Subagent role-to-model mapping → [`subagent_models`](#subagent_models) |
 | `thinking` | `table` | — | Default parameters for Thinking mode → [`thinking`](#thinking) |
 | `loop_control` | `table` | — | Agent loop control parameters → [`loop_control`](#loop_control) |
 | `background` | `table` | — | Background task runtime parameters → [`background`](#background) |
@@ -143,6 +144,26 @@ max_context_size = 1047576
 
 You can also switch models temporarily without touching the config file — by setting `KIMI_MODEL_*` environment variables, the CLI synthesizes a temporary provider in memory that does not persist after restart. See [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi_model).
 
+## `subagent_models`
+
+`subagent_models` maps subagent profile names to model aliases, so different roles can use different LLMs. When a subagent is spawned, the model is resolved in this priority order:
+
+1. Per-invocation `model` parameter on the `Agent` tool (if the parent agent explicitly requests a model)
+2. Role-based mapping in `[subagent_models]` (if the profile name has an entry)
+3. Parent agent's model (default inheritance)
+
+When a subagent uses a model that does not support Thinking, the thinking level is automatically disabled to avoid API errors.
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<profile_name>` | `string` | No | Model alias to use for the given profile; valid names are `coder`, `explore`, and `plan` |
+
+```toml
+[subagent_models]
+coder = "gpt-5.2"
+explore = "glm-4.7"
+```
+
 ## `thinking`
 
 `thinking` sets the global default behavior for Thinking mode. `mode = "off"` forces Thinking off even when the top-level `default_thinking = true`.

diff --git a/docs/en/configuration/data-locations.md b/docs/en/configuration/data-locations.md
@@ -30,6 +30,7 @@ $KIMI_CODE_HOME  (default: ~/.kimi-code)
 ├── config.toml             # User configuration
 ├── tui.toml                # Terminal UI preferences (including auto-update toggle)
 ├── AGENTS.md               # Global Kimi-specific agent instructions (optional)
+├── sysprompt.md            # Global system prompt override (optional)
 ├── mcp.json                # User-level MCP server declarations (optional)
 ├── skills/                 # Kimi-specific user-level Skills (optional)
 ├── plugins/
@@ -62,6 +63,7 @@ Each top-level file under the data root serves a specific purpose; most are mana
 - **`config.toml`**: the main runtime configuration file, storing user-level settings such as providers, models, and loop control. See [Configuration files](./config-files.md).
 - **`tui.toml`**: terminal UI client preferences, including `[upgrade].auto_install` (auto-update, on by default). You can disable it in `/settings` or by manually setting `auto_install = false`.
 - **`AGENTS.md`**: global Kimi-specific agent instructions. This file moves with `KIMI_CODE_HOME`; generic cross-tool instructions can still live under `~/.agents/AGENTS.md`.
+- **`sysprompt.md`**: global system prompt override. When present, its contents replace the built-in profile system prompt for every session. Project-level `.kimi-code/sysprompt.md` takes precedence over this global file. See [Agents and Sub-Agents](../customization/agents.md#system-prompt-override).
 - **`mcp.json`**: user-level MCP server declarations, merged with the project-local `.kimi-code/mcp.json` on startup. See [MCP](../customization/mcp.md).
 - **`skills/`**: Kimi-specific user-level Skills. This directory moves with `KIMI_CODE_HOME`; generic cross-tool Skills can still live under `~/.agents/skills/`. See [Agent Skills](../customization/skills.md).
 - **`plugins/installed.json`**: records installed plugins, each plugin's enabled state, and MCP server capability state changes made via `/plugins` or `/plugins mcp disable|enable`. Files installed from local paths or zip URLs are copied to `plugins/managed/<id>/`. See [Plugins](../customization/plugins.md).

diff --git a/docs/en/customization/agents.md b/docs/en/customization/agents.md
@@ -41,6 +41,21 @@ If you need a particular type of tool to be permanently unavailable inside sub-a
 
 Global Kimi-specific instructions can live at `$KIMI_CODE_HOME/AGENTS.md` (default: `~/.kimi-code/AGENTS.md`). When you relocate the data root with `KIMI_CODE_HOME`, this global instruction file moves with it. Generic cross-tool instructions can still live under `~/.agents/AGENTS.md` in the real OS home, and project-level instructions remain under the project tree, for example `.kimi-code/AGENTS.md` or `AGENTS.md`.
 
+## System Prompt Override
+
+You can replace the default system prompt (the high-level behavior profile sent to the model at the start of every turn) with your own text. This is useful when you want a consistent persona, coding style, or set of ground rules across all sessions.
+
+Two override files are supported:
+
+- **Global**: `$KIMI_CODE_HOME/sysprompt.md` (default: `~/.kimi-code/sysprompt.md`)
+- **Project-level**: `.kimi-code/sysprompt.md` in the current working directory
+
+If a project-level file exists, it takes precedence over the global file. If neither exists, the CLI falls back to its built-in profile system prompt. The file content is used verbatim, so write it as plain Markdown text.
+
+::: tip Note
+`AGENTS.md` is appended as supplementary context; `sysprompt.md` replaces the entire system prompt. You can use both together — for example, put your base persona in `sysprompt.md` and project-specific conventions in `AGENTS.md`.
+:::
+
 ## Storage Location in the Session Directory
 
 Sub-agent runtime state is persisted to the `agents/` subdirectory of the current session directory. Each sub-agent instance has its own directory, which contains a `wire.jsonl` file that records prompts, message history, and final state in chronological order. Background sub-agents also expose their lifecycle status through a `tasks/` subdirectory.

diff --git a/docs/en/reference/tools.md b/docs/en/reference/tools.md
@@ -89,7 +89,7 @@ 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 have a fixed 30-minute timeout. 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`), `run_in_background` (defaults to false), and `model` (a model alias defined in `config.toml` to use for this subagent instead of the inherited model). Agent tasks have a fixed 30-minute timeout. 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.
 

diff --git a/docs/zh/configuration/config-files.md b/docs/zh/configuration/config-files.md
@@ -84,6 +84,7 @@ timeout = 5
 | `telemetry` | `boolean` | `true` | 是否启用匿名遥测；显式设为 `false` 时关闭 |
 | `providers` | `table` | `{}` | API 供应商表 → [`providers`](#providers) |
 | `models` | `table` | — | 模型别名表 → [`models`](#models) |
+| `subagent_models` | `table` | — | 子 Agent 角色到模型的映射 → [`subagent_models`](#subagent_models) |
 | `thinking` | `table` | — | Thinking 模式默认参数 → [`thinking`](#thinking) |
 | `loop_control` | `table` | — | Agent 循环控制参数 → [`loop_control`](#loop_control) |
 | `background` | `table` | — | 后台任务运行参数 → [`background`](#background) |
@@ -143,6 +144,26 @@ max_context_size = 1047576
 
 无需修改配置文件也可以临时切换模型——通过 `KIMI_MODEL_*` 环境变量在内存里合成一个临时供应商，详见[用环境变量定义模型](./env-vars.md#用环境变量定义模型-kimi-model)。
 
+## `subagent_models`
+
+`subagent_models` 将子 Agent profile 名称映射到模型别名，让不同角色可以使用不同的 LLM。子 Agent 启动时，模型按以下优先级解析：
+
+1. `Agent` 工具的 `model` 参数（父 Agent 显式指定模型时）
+2. `[subagent_models]` 中的角色映射（该 profile 有配置项时）
+3. 父 Agent 的模型（默认继承）
+
+当子 Agent 使用的模型不支持 Thinking 时，Thinking 级别会自动关闭，以避免 API 报错。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `<profile_name>` | `string` | 否 | 该 profile 使用的模型别名；有效名称包括 `coder`、`explore`、`plan` |
+
+```toml
+[subagent_models]
+coder = "gpt-5.2"
+explore = "glm-4.7"
+```
+
 ## `thinking`
 
 `thinking` 设置 Thinking 模式的全局默认行为。`mode = "off"` 会强制关闭 Thinking，即使顶层 `default_thinking = true` 也不例外。

diff --git a/docs/zh/configuration/data-locations.md b/docs/zh/configuration/data-locations.md
@@ -30,6 +30,7 @@ $KIMI_CODE_HOME  （默认 ~/.kimi-code）
 ├── config.toml             # 用户配置
 ├── tui.toml                # 终端界面偏好（含自动更新开关）
 ├── AGENTS.md               # 全局 Kimi 专属 Agent 指令（可选）
+├── sysprompt.md            # 全局系统提示词覆盖（可选）
 ├── mcp.json                # 用户级 MCP server 声明（可选）
 ├── skills/                 # Kimi 专属用户级 Skills（可选）
 ├── plugins/
@@ -62,6 +63,7 @@ $KIMI_CODE_HOME  （默认 ~/.kimi-code）
 - **`config.toml`**：主运行时配置，存放供应商、模型、循环控制等用户级设置。详见[配置文件](./config-files.md)。
 - **`tui.toml`**：终端界面客户端偏好，包括 `[upgrade].auto_install`（自动更新，默认开启）。可在 `/settings` 关闭，或手动设为 `auto_install = false`。
 - **`AGENTS.md`**：全局 Kimi 专属 Agent 指令。该文件会随 `KIMI_CODE_HOME` 移动；跨工具通用指令仍可放在 `~/.agents/AGENTS.md`。
+- **`sysprompt.md`**：全局系统提示词覆盖。存在时，其内容会替换每次会话的内置 profile 系统提示词。项目级 `.kimi-code/sysprompt.md` 优先于此全局文件。详见 [Agent 与子 Agent](../customization/agents.md#系统提示词覆盖)。
 - **`mcp.json`**：用户级 MCP server 声明，启动时与项目内的 `.kimi-code/mcp.json` 合并加载。详见 [MCP](../customization/mcp.md)。
 - **`skills/`**：Kimi 专属用户级 Skills。该目录会随 `KIMI_CODE_HOME` 移动；跨工具通用 Skills 仍可放在 `~/.agents/skills/`。详见 [Agent Skills](../customization/skills.md)。
 - **`plugins/installed.json`**：记录已安装的 plugin、每个 plugin 的启用状态，以及通过 `/plugins` 或 `/plugins mcp disable|enable` 修改的 MCP server 能力状态。本地路径和 zip URL 安装的文件会复制到 `plugins/managed/<id>/`。详见 [Plugins](../customization/plugins.md)。

diff --git a/docs/zh/customization/agents.md b/docs/zh/customization/agents.md
@@ -41,6 +41,21 @@ Kimi Code CLI 内置三种子 Agent，开箱即用，分别面向不同任务形
 
 全局 Kimi 专属指令可放在 `$KIMI_CODE_HOME/AGENTS.md`（默认：`~/.kimi-code/AGENTS.md`）。当你用 `KIMI_CODE_HOME` 移动数据根时，这份全局指令文件也会一起移动。跨工具通用指令仍可放在真实 OS home 下的 `~/.agents/AGENTS.md`，项目级指令仍放在项目目录中，例如 `.kimi-code/AGENTS.md` 或 `AGENTS.md`。
 
+## 系统提示词覆盖
+
+你可以用自己的文本替换默认的系统提示词（每轮开始时发送给模型的高层行为画像）。当你希望所有会话都保持一致的人格、编码风格或基本规则时，这会很有用。
+
+支持两类覆盖文件：
+
+- **全局**：`$KIMI_CODE_HOME/sysprompt.md`（默认：`~/.kimi-code/sysprompt.md`）
+- **项目级**：当前工作目录下的 `.kimi-code/sysprompt.md`
+
+如果项目级文件存在，它会优先于全局文件；如果都不存在，CLI 会回退到内置的 profile 系统提示词。文件内容会原样使用，因此直接以普通 Markdown 文本书写即可。
+
+::: tip 提示
+`AGENTS.md` 是作为补充上下文追加的；`sysprompt.md` 会替换整个系统提示词。两者可以一起使用——例如，把基础人格放在 `sysprompt.md` 里，把项目专属约定放在 `AGENTS.md` 里。
+:::
+
 ## 会话目录中的存储位置
 
 子 Agent 的运行状态持久化到当前会话目录的 `agents/` 子目录下，每个子 Agent 实例对应一个独立目录，其中包含按时间顺序记录提示词、消息历史与最终状态的 `wire.jsonl` 文件。后台子 Agent 还会通过 `tasks/` 子目录暴露生命周期状态。