@tencent-ai/codebuddy-code 2.119.4 → 2.120.0

package/dist/web-ui/docs/en/cli/settings.md

@@ -65,6 +65,8 @@ The `settings.json` file is the official mechanism for configuring CodeBuddy Cod
 | `disableAllHooks` | Disable all [hooks](hooks.md) | `true` |
 | `allowUntrustedFrontmatterHooks` | Whether to allow execution of frontmatter `hooks` fields from agents/skills with **non-product-builtin** sources (including local user `.codebuddy/agents\|skills/*.md` and the plugin marketplace). Defaults to `false` to prevent untrusted md files from silently launching shell commands; only product-builtin agents/skills are unaffected. | `true` |
 | `model` | Override the default model used by CodeBuddy Code | `"gpt-5"` |
+| `subagents` | Specify models per built-in sub-agent granularity. Structure: `{"agents": {"<sub-agent-name>": {"model": "..."}}}` (`agents` key = sub-agent name, e.g. `Explore`; `model` = model ID / alias / variant `lite`\|`reasoning` / `inherit`). Each sub-agent is independent, supporting both global and project scopes. Can be visually edited in the `/agents` panel. Priority: env `CODEBUDDY_CODE_SUBAGENT_MODEL` (applies to all) > project > global > built-in default > inherit main model. See [Sub-Agents Documentation](sub-agents.md) | `{"agents": {"Explore": {"model": "gpt-5.1-codex"}, "general-purpose": {"model": "claude-opus-4"}}}` |
+| `variantModels` | Mapping from scenario variant to model (key = `lite`\|`reasoning`; value = model ID / alias). Affects all logic using that variant (e.g., sub-agents like `Explore` that declare `lite`). Can be edited in the "Scenario Variants" section of the `/model` panel. Priority: env (`CODEBUDDY_SMALL_FAST_MODEL` / `CODEBUDDY_BIG_SLOW_MODEL`, per variant) > project > global > model-level `relatedModels` > main model fallback | `{"lite": "gpt-5.1-codex-lite", "reasoning": "gpt-5.5"}` |
 | `agent` | Override the agent name used by the main thread (built-in or custom agent), applying that agent's system prompt, tool restrictions, and model configuration. Priority: `product.json default` → `plugin agent` → `settings.json agent` → `CLI --agent` | `"my-reviewer"` |
 | `statusLine` | Configure a custom status line to display context. See [statusLine documentation](#status-line-configuration) | `{"type": "command", "command": "~/.codebuddy/statusline.sh"}` |
 | `enableAllProjectMcpServers` | Auto-approve all MCP servers defined in the project's `.mcp.json` file | `false` |

package/dist/web-ui/docs/en/cli/sub-agents.md

@@ -177,6 +177,44 @@ This opens an interactive menu where you can:
 * See which sub-agents are active when duplicates exist
 * **Manage tool permissions** with a complete list of all available tools
 
+### Configuring Models for Built-in Sub-Agents (per-Agent Model)
+
+Built-in sub-agents (such as `Explore`, `general-purpose`, `Plan`) can also have **models specified independently per sub-agent granularity**, with each sub-agent independent and freely combinable. This solves the previous limitation of "only being able to set all sub-agents at once via environment variables without differentiation."
+
+**Visual Configuration in the `/agents` Panel**:
+
+1. Run `/agents`, use `↑/↓` to select a built-in sub-agent, press `Enter` to enter its action menu.
+2. Select **Edit Model** to enter the model selector:
+   * First option **Inherit / Default** — clears the sub-agent's configuration, falling back to default orchestration.
+   * Scenario variants `lite` / `reasoning`.
+   * All available models (same as `/model`).
+3. Use `Tab` to switch between **Global** and **Project** save scopes, `Enter` to confirm.
+4. The list instantly refreshes to show "effective model + source".
+
+The **SOURCE** column in the panel shows the source of each sub-agent's currently effective model, making default orchestration transparent:
+
+| Source Label | Meaning |
+|---|---|
+| `env-global` | Environment variable `CODEBUDDY_CODE_SUBAGENT_MODEL` overrides all (see priority below) |
+| `settings-project` | Project-level configuration (`.codebuddy/settings.json`) |
+| `settings-user` | Global-level configuration (`~/.codebuddy/settings.json`) |
+| `product-default` | Built-in default declaration (e.g., `Explore` = `lite`) |
+| `inherit` | No declaration, inherits main conversation model |
+| `fallback-main` | Configured model is disabled/locally unknown, falls back to main conversation model |
+
+**Configuration Storage**: Written to the `subagents.agents.<sub-agent-name>.model` field in settings (`agents` key = sub-agent name, `model` = model ID / alias / variant / `inherit`). Can also be manually edited in `settings.json`, see [Settings Documentation](settings.md).
+
+**Priority (highest to lowest)**:
+
+1. Environment variable `CODEBUDDY_CODE_SUBAGENT_MODEL` (**applies to all** sub-agents uniformly, highest priority)
+2. Tool invocation parameters for this call (`default` / `lite` / `reasoning`, per-invocation)
+3. **Project-level** `subagents.agents.<sub-agent-name>.model`
+4. **Global-level** `subagents.agents.<sub-agent-name>.model`
+5. Built-in default declaration (`agents[].models[0]` in `product.json`, e.g., `Explore` = `lite`)
+6. Inherit main conversation model (fallback)
+
+> **Note**: When `CODEBUDDY_CODE_SUBAGENT_MODEL` is set, the panel still allows saving per-Agent configurations (no error), but displays a "overridden by environment variable" notice; per-Agent configurations take effect again after the environment variable is removed.
+
 ### Direct File Management
 
 You can also manage sub-agents by working directly with their files: