@tencent-ai/codebuddy-code 2.125.4-next.41bad82.202607231203 → 2.126.0

package/dist/web-ui/docs/en/cli/release-notes/v2.125.0.md

@@ -0,0 +1,44 @@
+# 🚀 CodeBuddy Code v2.125.0 Release
+
+## 📦 Version Information
+
+| Component | Version |
+|-----------|---------|
+| CodeBuddy Code CLI | v2.125.0 |
+| Agent SDK JS | v0.3.222 |
+| Agent SDK Python | v0.3.221 |
+
+## ✨ New Features
+
+### Infinite Scroll for Plugin List
+
+The installed and marketplace browse lists now use infinite scroll with load-more on reaching the bottom, along with a one-click back-to-top button, making it smoother to browse large numbers of plugins.
+
+### Subagent-scoped MCP Support
+
+Subagents can now declare dedicated `mcpServers` configurations in their definitions:
+
+- Inline MCP servers are only created when the current subagent starts, visible only to that subagent, and automatically cleaned up when finished — without polluting the main agent or other subagents
+- String references can reuse existing global MCP servers
+- ToolSearch / DeferExecuteTool can discover and invoke tools provided by scoped MCP within the current subagent
+- When `--strict-mcp-config` strict mode is enabled, scoped MCP for trusted built-in product subagents is allowed via a whitelist
+
+## 🔧 Improvements
+
+- **OOM forensics fallback**: Long-running sessions (e.g., `/goal`) can automatically write a heap snapshot when approaching the heap limit for post-mortem analysis. Disabled by default; enable via environment variable when needed
+- **Skill visibility isolation**: Skills with `disable: true` are no longer hard-removed from the menu. Instead, they are excluded from the model's default context but can still be manually triggered by users via the `/` menu
+
+## 🐛 Bug Fixes
+
+- **Custom model tool image results**: Fixed an issue where overly strict image validation by some third-party gateways on tool-returned images caused request failures
+- **Daemon restart host loss**: Fixed an issue where `daemon restart` without arguments silently fell back to the default host configuration
+- **Session file recovery**: Fixed a memory exception caused by internal artifact index files when loading/rewinding old sessions
+- **stream-json resume replay timestamps**: Fixed an issue where replayed historical messages during session resume showed the replay time instead of the original creation time
+- **File watcher ENOSPC**: Fixed a crash on Linux when mounting file watchers on large project directories exhausted the system's inotify limit
+- **WebSearch time keywords**: Fixed an issue where time-related searches such as "today", "this year", and "latest" did not use the current time to construct queries
+- **Plugin session isolation**: Fixed an issue where plugin management operations could incorrectly reuse the previous session's plugin combination in a new session
+- **AskUserQuestion interaction**: Fixed an issue where ACP clients skipping questions could cause approval waits to hang
+
+## 📝 Documentation Updates
+
+- Improved documentation for built-in subagents and scenario model configuration methods, parsing priorities, and usage entry points

package/dist/web-ui/docs/en/cli/release-notes/v2.125.1.md

@@ -0,0 +1,22 @@
+# 🚀 CodeBuddy Code v2.125.1 Release
+
+## 📦 Version Information
+
+| Component | Version |
+|-----------|---------|
+| CodeBuddy Code CLI | v2.125.1 |
+| Agent SDK JS | v0.3.223 |
+| Agent SDK Python | v0.3.222 |
+
+## 🔧 Improvements
+
+- **No-persistence session mode**: Added the `--no-session-persistence` flag. Session context is kept in memory only, without creating or appending to local session records, while retaining read-only access to existing history. Suitable for temporary or privacy-sensitive scenarios.
+
+## 🐛 Bug Fixes
+
+- **More reliable managed session startup**: The system now automatically assigns available ports and establishes connections only after the service is truly ready, avoiding session startup failures caused by port conflicts.
+- **Sub-agent registration**: Fixed an issue where a plugin-designated main session agent was duplicated as an invocable sub-agent, while preserving the normal invocation of member agents within the same plugin.
+- **Agent team tool visibility**: When the agent team feature is disabled, the related team creation, deletion tools, and team collaboration prompts are now hidden synchronously to prevent accidental triggers.
+- **Chinese/encoding garbled text fix**: Restored encoding detection for file reads and Shell output, resolving the issue where Chinese content displayed as garbled text in some non-UTF-8 (GBK/CP936, etc.) scenarios.
+- **Clearer local hook blocking messages**: When a workspace-configured hook is missing or actively blocks execution, it no longer shows a generic "service error." Instead, the conversation now clearly indicates that a local hook intercepted the request along with the reason, aligning with mainstream implementations.
+- **WebUI cross-origin access**: Fixed an issue where the automatic CORS relaxation logic did not take effect when starting WebUI with `--host 0.0.0.0`. The `--serve` / daemon startup modes can now be accessed directly in cloud VM environments such as anydev without manually configuring CORS origins.

package/dist/web-ui/docs/en/cli/release-notes/v2.125.2.md

@@ -0,0 +1,13 @@
+# 🚀 CodeBuddy Code v2.125.2 Release
+
+## 📦 Version Information
+
+| Component | Version |
+|-----------|---------|
+| CodeBuddy Code CLI | v2.125.2 |
+| Agent SDK JS | v0.3.224 |
+| Agent SDK Python | v0.3.223 |
+
+## 🐛 Bug Fixes
+
+- **Custom model conversation reporting**: Fixed an issue where conversations using custom models in WorkBuddy Desktop were not counted in activity statistics (activity map, consecutive login days, etc.). Custom model conversations now report normally.

package/dist/web-ui/docs/en/cli/release-notes/v2.125.3.md

@@ -0,0 +1,30 @@
+# 🚀 CodeBuddy Code v2.125.3 Release
+
+> This is a re-published release: v2.125.1 and v2.125.2 failed to publish due to release process anomalies, and the production environment remained at v2.125.0. v2.125.3 has been rebuilt and published, fully including all changes from the two aforementioned versions.
+
+## 📦 Version Information
+
+| Component | Version |
+|-----------|---------|
+| CodeBuddy Code CLI | v2.125.3 |
+| Agent SDK JS | v0.3.225 |
+| Agent SDK Python | v0.3.224 |
+
+## ✨ New Features
+
+### No-Persistence Session
+
+Added the `--no-session-persistence` option. Session context is kept in memory only, without creating or appending to local transcripts, while retaining read-only access to existing history. Suitable for temporary sessions and sensitive scenarios.
+
+## 🔧 Improvements
+
+- **WorkBuddy managed session startup**: The system now assigns available ports and establishes connections only after the service is truly ready, avoiding session startup failures caused by port conflicts.
+
+## 🐛 Bug Fixes
+
+- **Custom model conversation reporting**: Fixed an issue where conversations using custom models in WorkBuddy Desktop were not counted in activity statistics (activity map, consecutive login days, etc.). Custom model conversations now report normally.
+- **Sub-agent registration**: Fixed an issue where a plugin-designated main session agent via `settings.agent` was duplicated as an invocable sub-agent, while preserving the invocation of member agents within the same plugin.
+- **Agent team tools**: When agent teams are disabled, lazily loaded TeamCreate, TeamDelete, and Agent tools' team collaboration prompts are now hidden synchronously.
+- **Chinese/encoding garbled text**: Restored encoding detection for file reads and Shell output, resolving the issue where Chinese content displayed as garbled text in some non-UTF-8 (GBK/CP936, etc.) scenarios.
+- **Local hook blocking visibility**: When a workspace hook script is missing or blocks with a non-zero exit code, the blocking reason is now written to history as a message and the session terminates cleanly. The client can precisely identify it as a local hook interception, instead of only seeing a generic service error.
+- **WebUI CORS**: Fixed an issue where the automatic CORS relaxation logic did not take effect when starting WebUI with `--host 0.0.0.0`. The `--serve` / daemon startup modes can now be accessed normally in cloud VM environments without manually setting environment variables.

package/dist/web-ui/docs/en/cli/release-notes/v2.125.4.md

@@ -0,0 +1,33 @@
+# 🚀 CodeBuddy Code v2.125.4 Release
+
+> This is a re-published release: v2.125.1, v2.125.2, and v2.125.3 all failed to publish due to release process anomalies, and the production environment remained at v2.125.0. v2.125.4 has been rebuilt and published, fully including all changes from the three aforementioned versions, plus a new interaction experience fix.
+
+## 📦 Version Information
+
+| Component | Version |
+|-----------|---------|
+| CodeBuddy Code CLI | v2.125.4 |
+| Agent SDK JS | v0.3.226 |
+| Agent SDK Python | v0.3.225 |
+
+## ✨ New Features
+
+### No-Persistence Session
+
+Added the `--no-session-persistence` option. Session context is kept in memory only, without creating or appending to local transcripts, while retaining read-only access to existing history. Suitable for temporary sessions and sensitive scenarios.
+
+## 🔧 Improvements
+
+- **WorkBuddy managed session startup**: The system now assigns available ports and establishes connections only after the service is truly ready, avoiding session startup failures caused by port conflicts.
+
+## 🐛 Bug Fixes
+
+- **Main page tab switching lag**: Fixed an issue where switching tabs on the main page caused lag, improving page interaction smoothness.
+- **MCP OAuth token exchange**: Fixed an issue where, in HTTP/SSE type MCP server scenarios through a gateway proxy, the token exchange returned a 404 after successful OAuth authorization. The callback phase now reuses the discovery results cached during the initial authorization flow, ensuring the token request is sent to the correct authorization server.
+- **MCP config path isolation**: Fixed an issue where the `CODEBUDDY_CONFIG_DIR` environment variable could not isolate user/local-level MCP configuration file paths. MCP configuration now follows this environment variable override consistently with other configurations, preventing accidental writes to the host machine's real configuration in multi-instance and automated testing isolation scenarios.
+- **Custom model conversation reporting**: Fixed an issue where conversations using custom models in WorkBuddy Desktop were not counted in activity statistics (activity map, consecutive login days, etc.). Custom model conversations now report normally.
+- **Sub-agent registration**: Fixed an issue where a plugin-designated main session agent via `settings.agent` was duplicated as an invocable sub-agent, while preserving the invocation of member agents within the same plugin.
+- **Agent team tools**: When agent teams are disabled, lazily loaded TeamCreate, TeamDelete, and Agent tools' team collaboration prompts are now hidden synchronously.
+- **Chinese/encoding garbled text**: Restored encoding detection for file reads and Shell output, resolving the issue where Chinese content displayed as garbled text in some non-UTF-8 (GBK/CP936, etc.) scenarios.
+- **Local hook blocking visibility**: When a workspace hook script is missing or blocks with a non-zero exit code, the blocking reason is now written to history as a message and the session terminates cleanly. The client can precisely identify it as a local hook interception, instead of only seeing a generic service error.
+- **WebUI CORS**: Fixed an issue where the automatic CORS relaxation logic did not take effect when starting WebUI with `--host 0.0.0.0`. The `--serve` / daemon startup modes can now be accessed normally in cloud VM environments without manually setting environment variables.

package/dist/web-ui/docs/en/cli/sdk-hooks.md

@@ -512,6 +512,36 @@ return {
 
 :::
 
+### PostToolUse Special Output
+
+You can append context to the Agent (`additionalContext`), or use `updatedToolOutput` to **replace** the tool result that will be sent to the Agent (applies to all tools, commonly used to compress verbose output to save tokens):
+
+::: code-group
+
+```typescript [TypeScript]
+return {
+  continue: true,
+  hookSpecificOutput: {
+    hookEventName: 'PostToolUse',
+    // Replace tool result (result may become shorter); alternatively use additionalContext to append (result only grows longer)
+    updatedToolOutput: compress(input.tool_response)
+  }
+};
+```
+
+```python [Python]
+return {
+    "continue_": True,
+    "hookSpecificOutput": {
+        "hookEventName": "PostToolUse",
+        # Replace tool result (result may become shorter); alternatively use additionalContext to append (result only grows longer)
+        "updatedToolOutput": compress(input_data.get("tool_response"))
+    }
+}
+```
+
+:::
+
 ## Examples
 
 ### Complete Example: Bash Command Auditing

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

@@ -37,6 +37,16 @@ The `settings.json` file is the official mechanism for configuring CodeBuddy Cod
     "DEBUG": "codebuddy:*"
   },
   "model": "gpt-5",
+  "subagents": {
+    "agents": {
+      "Explore": { "model": "lite" },
+      "Plan": { "model": "reasoning" }
+    }
+  },
+  "variantModels": {
+    "lite": "<fast-model-id>",
+    "reasoning": "<reasoning-model-id>"
+  },
   "cleanupPeriodDays": 30,
   "includeCoAuthoredBy": false,
   "statusLine": {
@@ -65,8 +75,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"}` |
+| `subagents` | Specify models per built-in sub-agent name. Structure: `{"agents": {"<sub-agent-name>": {"model": "..."}}}`; `model` supports model ID, alias, `lite` / `reasoning` or `inherit` / `default`. Each sub-agent is independent, supporting both global and project scopes. Can be visually edited in the `/agents` panel. Priority: `CODEBUDDY_CODE_SUBAGENT_MODEL` > tool invocation `model` parameter for this call > project settings > global user settings > built-in declaration > main model. See [Sub-Agents Documentation](sub-agents.md) | `{"agents": {"Explore": {"model": "lite"}, "Plan": {"model": "reasoning"}}}` |
+| `variantModels` | Map common scenario variants to models. Key is `lite` or `reasoning`, value is model ID or alias. This mapping affects all logic using the corresponding variant. Can be edited in the **Scenario Models** section of `/model`. Priority: corresponding variant environment variable > project settings > global user settings > main model's `relatedModels` > applicable product built-in default > main model | `{"lite": "<fast-model-id>", "reasoning": "<reasoning-model-id>"}` |
 | `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` |
@@ -448,7 +458,31 @@ Set to `0` or a negative value to disable timeout protection (not recommended; a
 
 ## Sub-Agent Configuration
 
-CodeBuddy Code supports custom AI sub-agents configurable at user and project levels. These sub-agents are stored as Markdown files with YAML frontmatter:
+CodeBuddy Code supports independently selecting models for built-in sub-agents, as well as creating custom sub-agents via Markdown files.
+
+Built-in sub-agents and scenario models can be combined in user-level or project-level `settings.json`:
+
+```json
+{
+  "subagents": {
+    "agents": {
+      "Explore": { "model": "lite" },
+      "Plan": { "model": "reasoning" }
+    }
+  },
+  "variantModels": {
+    "lite": "<fast-model-id>",
+    "reasoning": "<reasoning-model-id>"
+  }
+}
+```
+
+* Use `/agents` to edit built-in sub-agent mappings; use the **Scenario Models** section of `/model` to edit `lite` and `reasoning` mappings.
+* **Global** writes to user settings, **Project** writes to shared project settings.
+* `subagents` merges by sub-agent name, `variantModels` merges by variant name. Project-level overriding `Explore` will not delete other sub-agent configurations at the user level; project-level overriding `reasoning` will not delete user-level `lite` either.
+* Selecting **Inherit / Default** in `/agents`, or selecting **Default** in `/model`, will delete the corresponding entry for the selected scope and restore the lower-priority resolution chain.
+
+Custom sub-agents are stored as Markdown files with YAML frontmatter:
 
 * **User sub-agents**: `~/.codebuddy/agents/` - Available across all projects
 * **Project sub-agents**: `.codebuddy/agents/` - Project-specific, shareable with the team

package/dist/web-ui/docs/en/cli/slash-commands.md

@@ -15,7 +15,7 @@ These commands are used to manage your CodeBuddy Code sessions. Here is the curr
 | `/doctor` | | ✅ Supported | Check the status and environment of CodeBuddy Code. |
 | `/status` | | ✅ Supported | Display the status of the current repository and session. |
 | `/add-dir` | `<path>` | ✅ Supported | Add a working directory. Specify the path of the directory to add. |
-| `/agents` | | ✅ Supported | Manage experimental AI agents |
+| `/agents` | | ✅ Supported | Manage built-in and custom AI agents; view the effective routing values and their sources for built-in sub-agents, and save model settings to Global or Project scope. Specific scenario models can be viewed in `/model`. |
 | `/branch` | `[name]` | ✅ Supported | Create a branch at the current conversation point, copying active conversation history to a new session and automatically switching to it. Optionally specify a branch name. |
 | `/btw` | `<question>` | ✅ Supported | Quick side question without interrupting the current Agent workflow. Useful for asking brief questions while the Agent is executing a task. Answers are generated based on existing context. |
 | `/compact`| | ✅ Supported | Compress context. |
@@ -25,7 +25,7 @@ These commands are used to manage your CodeBuddy Code sessions. Here is the curr
 | `/init` | | ✅ Supported | Initialize a new CodeBuddy repository. |
 | `/mcp` | | ✅ Supported | Manage MCP connections. |
 | `/memory`| | ✅ Supported | Manage long-term memory |
-| `/model` | `[list \| model-name]` | ✅ Supported | Switch or view the currently used AI model. Opens an interactive selection interface when used without parameters, `list` lists available models, or directly switches to the specified model when provided with a model name (e.g., `/model gpt-4o`). |
+| `/model` | `[list \| model-name]` | ✅ Supported | Switch or view the main model. Opens an interactive interface when used without parameters; you can also view or edit the effective models, sources, and Global / Project settings for `lite` / `reasoning` in the **Scenario Models** section. `list` lists available models; when provided with a model name, directly switches the main model. |
 | `/model:text-to-image` | `[list \| model-id]` | ✅ Supported | Switch or view the currently used text-to-image model. Opens an interactive selection interface when used without parameters, `list` lists available models, or directly switches to the specified model when provided with a model ID. |
 | `/model:image-to-image` | `[list \| model-id]` | ✅ Supported | Switch or view the currently used image-to-image model. Opens an interactive selection interface when used without parameters, `list` lists available models, or directly switches to the specified model when provided with a model ID. |
 | `/permissions` | | ✅ Supported | Manage tool permissions and workspace directory access permissions. |

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

@@ -131,19 +131,121 @@ the sub-agent should follow.
 | `name` | Yes | Unique identifier using lowercase letters and hyphens |
 | `description` | Yes | Natural language description of the sub-agent's purpose |
 | `tools` | No | Comma-separated list of specific tools. If omitted, inherits all tools from the main thread. You can use `Defer(X)` / `NoDefer(X)` modifiers to adjust the deferred loading status of tools. See [Tool Deferred Loading Override](tool-defer-overlay.md) for details |
-| `model` | No | Model to use for this sub-agent. Can be a model alias (`gpt-5.1-codex`, `gemini-3.0-flash`, etc.) or `'inherit'` to use the main conversation's model. If omitted, defaults to configured sub-agent model |
+| `model` | No | Model ID, name or alias, scenario variant `lite` / `reasoning`, or `inherit` / `default`. When omitted or set to `inherit` / `default`, no specific model is forced and model selection continues through the normal sub-agent resolution chain |
 | `permissionMode` | No | Permission mode for the sub-agent. Valid values: `default`, `acceptEdits`, `bypassPermissions`, `plan`, `ignore`. Controls how the sub-agent handles permission requests |
 | `skills` | No | Comma-separated skill names to auto-load when the sub-agent starts |
+| `mcpServers` | No | Sub-agent dedicated MCP server declarations. Supports referencing existing global MCP servers, or declaring private inline MCP servers for the current sub-agent. See details below. |
+
+### Sub-Agent Dedicated MCP Servers
+
+`mcpServers` is used to declare MCP servers that are only visible during a specific sub-agent's runtime. It does not write to the global MCP configuration, nor does it make the MCP servers automatically visible to the main conversation or other sub-agents.
+
+Two syntaxes are supported.
+
+**Referencing an existing global MCP server**:
+
+```yaml
+---
+name: docs-searcher
+description: Use existing docs MCP for retrieval
+tools:
+  - Read
+mcpServers:
+  - docs
+---
+```
+
+Here `docs` must already be a globally connected MCP server. The sub-agent only borrows it; when the sub-agent ends, it will not close it.
+
+**Declaring an inline MCP server**:
+
+```yaml
+---
+name: browser-checker
+description: Use private MCP for browser checks
+tools:
+  - ToolSearch
+  - DeferExecuteTool
+mcpServers:
+  - browser_private:
+      type: stdio
+      command: node
+      args:
+        - /absolute/path/to/browser-mcp-server.js
+      defer_loading: true
+---
+```
+
+Inline MCP servers are only created within that sub-agent's session and automatically closed when the sub-agent ends. They do not enter the global MCP pool.
+
+#### Security Strategy
+
+| Source | `mcpServers` Behavior |
+|---|---|
+| User sub-agent: `~/.codebuddy/agents/*.md` | Inline MCP allowed. |
+| Project sub-agent: `.codebuddy/agents/*.md` | Inline MCP allowed, but requires project-local approval. |
+| Plugin agent | `mcpServers` is ignored. |
+| `strictMcpConfig=true` | Skip all agent frontmatter/product `mcpServers`. |
+
+Project sub-agent inline MCP requires writing to project-local configuration, located at the current workspace's `.codebuddy/settings.local.json`:
+
+```json
+{
+  "enabledMcpjsonServers": ["browser_private"]
+}
+```
+
+You can also approve via CLI settings at launch:
+
+```bash
+codebuddy --settings '{"enabledMcpjsonServers":["browser_private"]}'
+```
+
+Note: Here we use the server name, consistent with the existing PROJECT MCP approval method. Do not write to the user's global `settings.json`, because project MCP approval only reads project-local and CLI scope.
+
+#### Direct and Deferred
+
+Scoped MCP uses the same deferred loading strategy as CodeBuddy's global MCP. By default, MCP tools use deferred loading: the model first discovers tools via `ToolSearch`, then invokes them via `DeferExecuteTool`.
+
+Default deferred configuration example:
+
+```yaml
+tools:
+  - ToolSearch
+  - DeferExecuteTool
+mcpServers:
+  - finance_data:
+      type: stdio
+      command: node
+      args:
+        - /absolute/path/to/finance-mcp-server.js
+```
+
+If you want MCP tools to appear directly in the sub-agent's tool list, you can explicitly disable defer:
+
+```yaml
+mcpServers:
+  - finance_data:
+      type: stdio
+      command: node
+      args:
+        - /absolute/path/to/finance-mcp-server.js
+      defer_loading: false
+```
+
+You can also use the `Defer(...)` / `NoDefer(...)` modifiers in the `tools` field to adjust the deferred loading behavior of individual tools.
+
+
 
 ### Model Selection
 
 The `model` field allows you to control which [AI model](models.md) the sub-agent uses:
 
-* **Model Alias**: Use one of the available aliases: `gpt-5.1-codex`, `gemini-3.0-flash`, `gemini-3.1-pro`, `gpt-5.1-codex`, etc.
-* **`'inherit'`**: Use the same model as the main conversation (useful for consistency)
-* **Omitted**: If not specified, uses the default model configured for sub-agents
+* **Model ID, name or alias**: Directly select an available model
+* **Scenario variant**: Use `lite` or `reasoning`, then map to a specific model via `/model` or `variantModels`
+* **`inherit` / `default`, or omitted**: No specific model is forced; model selection continues through the resolution chain in order of environment variables, per-invocation parameters, sub-agent settings, built-in declarations, and main conversation model
 
-> **Note**: Using `'inherit'` is particularly useful when you want the sub-agent to adapt to the main conversation's model choice, ensuring consistent capabilities and response styles throughout the session.
+> **Note**: When using `inherit`, if there is no higher-priority configuration, the sub-agent will ultimately inherit the main conversation model, which helps maintain consistent functionality and response style.
 
 ### Available Tools
 
@@ -171,6 +273,9 @@ The `/agents` command provides a comprehensive sub-agent management interface:
 This opens an interactive menu where you can:
 
 * View all available sub-agents (built-in, user, and project)
+* View the effective routing values and their sub-agent layer sources for built-in sub-agents; specific scenario variant models can be viewed in `/model`
+* Set models or `lite` / `reasoning` scenario variants for built-in sub-agents via **Edit Model**
+* View built-in sub-agent definitions via **View Definition**
 * Create new sub-agents with guided setup
 * Edit existing custom sub-agents, including their tool access
 * Delete custom sub-agents
@@ -189,7 +294,7 @@ Built-in sub-agents (such as `Explore`, `general-purpose`, `Plan`) can also have
    * 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".
+4. The list instantly refreshes to show "effective routing value + sub-agent layer source". The value may be a specific model, or `lite` / `reasoning`; the specific model that the scenario variant ultimately maps to and its source can be viewed in the **Scenario Models** section of `/model`.
 
 The **SOURCE** column in the panel shows the source of each sub-agent's currently effective model, making default orchestration transparent:
 
@@ -269,7 +374,7 @@ The General-Purpose sub-agent is a powerful agent suitable for complex multi-ste
 
 **Key Features:**
 
-* **Model**: Uses default model for more robust reasoning
+* **Model**: Uses default orchestration, can be independently adjusted for this sub-agent via `/agents`
 * **Tools**: Has access to all tools
 * **Mode**: Can read and write files, execute commands, make modifications
 * **Purpose**: Complex research tasks, multi-step operations, code modifications
@@ -301,7 +406,7 @@ The Plan sub-agent is a specialized built-in agent designed for use during plan
 
 **Key Features:**
 
-* **Model**: Uses default model for more robust analysis
+* **Model**: Uses default orchestration, can be independently adjusted for this sub-agent via `/agents`
 * **Tools**: Has access to Read, Glob, Grep, and Bash tools for codebase exploration
 * **Purpose**: Search files, analyze code structure, and gather context
 * **Automatic Invocation**: When CodeBuddy Code is in plan mode and needs to research the codebase, it will automatically use this agent
@@ -328,7 +433,7 @@ The Explore sub-agent is a fast, lightweight agent optimized for searching and a
 
 **Key Features:**
 
-* **Model**: Uses gemini-3.0-flash for fast, low-latency searches
+* **Model**: Built-in declaration is `lite` scenario variant; actual model is determined by corresponding environment variables, project and user `variantModels`, main model `relatedModels`, and default orchestration
 * **Mode**: Strict read-only - cannot create, modify, or delete files
 * **Available Tools**:
   * Glob - File pattern matching

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

@@ -58,6 +58,61 @@ netstat -an | grep PORT_NUMBER
 
 ---
 
+## Memory Overflow (OOM) Troubleshooting
+
+**Symptom**: Long-running sessions (especially self-continuing loops like `/goal`, or ultra-long context tasks) crash after running for several hours, with the terminal showing:
+
+```
+FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
+```
+
+### Why It Happens
+
+- Node/V8 default heap limit is approximately 4GB (64-bit). In ultra-long sessions, conversation history, tool results, etc. accumulate in memory, and the heap may climb to the limit.
+- Auto context compression triggers based on **the ratio of tokens to the model window** (approximately 92%). **With large-window models (e.g., 1M context), tokens are far from the threshold, but the process's actual heap has already hit the 4GB limit** — compression cannot save it in time.
+- Hard OOM (`FatalProcessOutOfMemory`) is terminated directly by V8, bypassing all JS exception handling. By default, **no heap snapshot is left behind**, making it difficult to determine post-mortem what consumed memory.
+
+### Immediate Relief
+
+- Use `/clear` to clear context, or `/compact` to proactively compress before continuing.
+- Break large tasks into multiple rounds / multiple sessions to avoid unbounded accumulation in a single session.
+- Temporarily raise the heap limit (only treats the symptom, delays OOM):
+
+  ```bash
+  # Raise to 8GB and start (will be inherited by child processes)
+  NODE_OPTIONS=--max-old-space-size=8192 codebuddy
+  ```
+
+### Heap Snapshot for Root Cause Analysis (Disabled by Default, Enable as Needed)
+
+CodeBuddy has a built-in "near-heap-limit self-heal snapshot": when the process heap exceeds a high watermark of the V8 heap limit, it automatically writes a heap snapshot for post-mortem analysis of object retention trees. **Because snapshot files are very large (≈ 1.5x the heapUsed at the time; GB-scale heaps produce multi-GB files), it is disabled by default** and only enabled when reproducing/investigating OOM:
+
+```bash
+# Enable (default 85% watermark)
+CODEBUDDY_CODE_HEAP_SNAPSHOT_NEAR_LIMIT_PCT=on codebuddy
+# Custom watermark: 0.9 or 90 both mean 90%
+CODEBUDDY_CODE_HEAP_SNAPSHOT_NEAR_LIMIT_PCT=90 codebuddy
+# Disable (default): not set / 0 / off / false
+```
+
+- Snapshot location: `~/.codebuddy/diagnostics/<YYYY-MM-DD>/oom-nearlimit-<pid>-<timestamp>.heapsnapshot` (layered by day, same as log directory).
+- Only **one snapshot per process** (written once after exceeding the watermark, to avoid repeatedly writing GB-scale files and causing secondary OOM when near the limit).
+- A warning log is emitted on trigger: `[WorkflowMemProbe] near heap limit ...`.
+
+Analysis: Use Chrome DevTools → **Memory** → **Load** to load the `.heapsnapshot`, and examine **Retainers / object retention trees** to identify the largest objects and their reference chains.
+
+> Note: Node's built-in `--heapsnapshot-near-heap-limit` / `v8.setHeapSnapshotNearHeapLimit` was not used — it can only write to the process's current working directory, cannot specify a path, and only triggers when approaching the 100% true limit (by which point writing a GB-scale snapshot itself may cause secondary OOM). Here we use 85% high watermark to capture early and save to a unified diagnostics directory.
+
+### Feedback to Developers
+
+Please attach:
+
+- The terminal's `FATAL ERROR: ... heap out of memory` and the native stack trace that follows;
+- The `[WorkflowMemProbe] tick ... heap=used/total` heartbeat from `~/.codebuddy/logs/<date>/` before the crash (shows the heap growth curve);
+- If snapshot was enabled: `~/.codebuddy/diagnostics/<date>/oom-nearlimit-*.heapsnapshot`.
+
+---
+
 ## Permission Confirmation Dialog Unresponsive / Only ESC Closes It
 
 **Symptom**: The TUI shows a tool permission confirmation dialog. Pressing number keys / Enter to confirm doesn't dismiss the dialog, but ESC closes it normally — and after closing, the task has actually already started executing.

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

@@ -79,6 +79,9 @@ The default view for conversing with the Agent. Key features:
 - **Question panels**: Answer multi-choice questions from the Agent
 - **Task progress**: Monitor background tasks and team progress in real time
 - **Session management**: Create new chats, browse history, and switch sessions
+- **Working directory management**: Add/remove additional working directories, expanding the Agent's file access scope (stacked icon in bottom toolbar)
+- **Working directory management**: Add/remove additional working directories to expand the Agent's file access scope (bottom toolbar stacked icon)
+- **Working directory management**: Add/remove additional working directories to expand the Agent's file access scope (stacked icon in the bottom toolbar)
 
 ### Terminal View