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

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

@@ -129,19 +129,121 @@ codebuddy --agents '{
 | `name`           | 是   | 使用小写字母和连字符的唯一标识符                                                                                                                 |
 | `description`    | 是   | 子代理目的的自然语言描述                                                                                                                         |
 | `tools`          | 否   | 特定工具的逗号分隔列表。如果省略，继承主线程中的所有工具。可使用 `Defer(X)` / `NoDefer(X)` 修饰符调整工具的延迟加载状态，详见 [工具延迟加载覆盖](tool-defer-overlay.md) |
-| `model`          | 否   | 用于此子代理的模型。可以是模型别名（`gpt-5.1-codex`、`gemini-3.0-flash` 等）或 `'inherit'` 以使用主对话的模型。如果省略，默认为配置的子代理模型 |
+| `model`          | 否   | 模型 ID、名称或别名、场景变体 `lite` / `reasoning`，或 `inherit` / `default`。省略或设为 `inherit` / `default` 时，不强制具体模型，继续通过正常的子代理解析链选择模型 |
 | `permissionMode` | 否   | 子代理的权限模式。有效值:`default`、`acceptEdits`、`bypassPermissions`、`plan`、`ignore`。控制子代理如何处理权限请求                            |
 | `skills`         | 否   | 子代理启动时自动加载的技能名称，逗号分隔                                                                                                         |
+| `mcpServers`     | 否   | 子代理专属 MCP server 声明。支持引用已有全局 MCP server, 或声明当前子代理私有 inline MCP server。详见下方说明。                                  |
+
+### 子代理专属 MCP server
+
+`mcpServers` 用于给某个子代理声明只在该子代理运行期间可见的 MCP server。它不会写入全局 MCP 配置, 也不会让主对话或其他子代理自动看到。
+
+支持两种写法。
+
+**引用已有全局 MCP server**:
+
+```yaml
+---
+name: docs-searcher
+description: 使用已有 docs MCP 做检索
+tools:
+  - Read
+mcpServers:
+  - docs
+---
+```
+
+这里的 `docs` 必须已经是全局已连接的 MCP server。子代理只借用它, 子代理结束时不会关闭它。
+
+**声明 inline MCP server**:
+
+```yaml
+---
+name: browser-checker
+description: 使用私有 MCP 做浏览器检查
+tools:
+  - ToolSearch
+  - DeferExecuteTool
+mcpServers:
+  - browser_private:
+      type: stdio
+      command: node
+      args:
+        - /absolute/path/to/browser-mcp-server.js
+      defer_loading: true
+---
+```
+
+inline MCP server 只在该子代理 session 内创建, 子代理结束时自动关闭。它不会进入全局 MCP 池。
+
+#### 安全策略
+
+| 来源 | `mcpServers` 行为 |
+|---|---|
+| 用户子代理: `~/.codebuddy/agents/*.md` | 允许 inline MCP。 |
+| 项目子代理: `.codebuddy/agents/*.md` | 允许 inline MCP, 但需要项目本地批准。 |
+| Plugin agent | 忽略 `mcpServers`。 |
+| `strictMcpConfig=true` | 跳过所有 agent frontmatter/product `mcpServers`。 |
+
+项目子代理的 inline MCP 需要写入项目本地配置, 位置是当前 workspace 的 `.codebuddy/settings.local.json`:
+
+```json
+{
+  "enabledMcpjsonServers": ["browser_private"]
+}
+```
+
+也可以在本次启动时通过 CLI settings 批准:
+
+```bash
+codebuddy --settings '{"enabledMcpjsonServers":["browser_private"]}'
+```
+
+注意: 这里使用 server name, 与已有 PROJECT MCP 的审批方式保持一致。不要写到用户全局 `settings.json`, 因为项目 MCP 审批只读取项目本地和 CLI scope。
+
+#### Direct 和 deferred
+
+scoped MCP 使用与 CodeBuddy 全局 MCP 相同的延迟加载策略。默认情况下, MCP 工具会走 deferred loading: 模型先通过 `ToolSearch` 发现工具, 再通过 `DeferExecuteTool` 调用工具。
+
+默认 deferred 配置示例:
+
+```yaml
+tools:
+  - ToolSearch
+  - DeferExecuteTool
+mcpServers:
+  - finance_data:
+      type: stdio
+      command: node
+      args:
+        - /absolute/path/to/finance-mcp-server.js
+```
+
+如果希望 MCP 工具直接出现在子代理 tool list 中, 可以显式关闭 defer:
+
+```yaml
+mcpServers:
+  - finance_data:
+      type: stdio
+      command: node
+      args:
+        - /absolute/path/to/finance-mcp-server.js
+      defer_loading: false
+```
+
+也可以通过 `tools` 字段里的 `Defer(...)` / `NoDefer(...)` 修饰符对单个工具调整延迟加载行为。
+
+
 
 ### 模型选择
 
 `model` 字段允许您控制子代理使用的 [AI 模型](models.md)：
 
-* **模型别名**：使用可用别名之一，如 `gpt-5.1-codex`、`gemini-3.0-flash`、`gemini-3.1-pro`、`gpt-5.1-codex` 等
-* **`'inherit'`**：使用与主对话相同的模型（对于一致性很有用）
-* **省略**：如果未指定，使用为子代理配置的默认模型
+* **模型 ID、名称或别名**：直接选择一个可用模型
+* **场景变体**：使用 `lite` 或 `reasoning`，再由 `/model` 或 `variantModels` 映射到具体模型
+* **`inherit` / `default`，或省略**：不强制具体模型，继续按环境变量、单次调用、按子代理设置、内置声明和主对话模型的顺序解析
 
-> **注意**：当您希望子代理适应主对话的模型选择，确保整个会话中的功能和响应风格一致时，使用 `'inherit'` 特别有用。
+> **注意**：使用 `inherit` 时，如果没有更高优先级的配置，子代理最终会继承主对话模型，有助于保持功能和响应风格一致。
 
 ### 可用工具
 
@@ -169,6 +271,9 @@ codebuddy --agents '{
 这打开了一个交互式菜单，您可以在其中：
 
 * 查看所有可用的子代理（内置、用户和项目）
+* 查看内置子代理当前生效的路由值及其子代理层来源；场景变体对应的具体模型在 `/model` 中查看
+* 通过 **Edit Model** 为内置子代理设置模型或 `lite` / `reasoning` 场景变体
+* 通过 **View Definition** 查看内置子代理定义
 * 使用引导式设置创建新子代理
 * 编辑现有的自定义子代理，包括其工具访问权限
 * 删除自定义子代理
@@ -187,9 +292,9 @@ codebuddy --agents '{
    * 通用场景变体 `lite` / `reasoning`。
    * 全部可用模型（与 `/model` 一致）。
 3. 用 `Tab` 在 **Global（全局）** 与 **Project（项目）** 两个保存范围间切换，`Enter` 确认。
-4. 列表即时刷新为「生效模型 + 来源」。
+4. 列表即时刷新为「生效路由值 + 子代理层来源」。该值可能是具体模型，也可能是 `lite` / `reasoning`；场景变体最终映射到的具体模型和来源可在 `/model` 的 **Scenario Models** 区域查看。
 
-面板的 **SOURCE** 列展示每个子代理当前生效模型的来源，让默认编排透明化：
+面板的 **SOURCE** 列展示每个子代理路由值的来源，让默认编排透明化：
 
 | 来源标签 | 含义 |
 |---|---|
@@ -200,7 +305,7 @@ codebuddy --agents '{
 | `inherit` | 无任何声明，继承主对话模型 |
 | `fallback-main` | 配置的模型被禁用/本地未知，降级回主对话模型 |
 
-**配置存储**：写入 settings 的 `subagents.agents.<子代理名>.model` 字段（`agents` 的 key = 子代理名，`model` = 模型 ID / 别名 / 变体 / `inherit`）。也可手动编辑 `settings.json`，详见 [设置文档](settings.md)。
+**配置存储**：写入 settings 的 `subagents.agents.<子代理名>.model` 字段（`agents` 的 key = 子代理名，`model` = 模型 ID / 别名 / 变体 / `inherit` / `default`）。也可手动编辑 `settings.json`，详见 [设置文档](settings.md)。
 
 **优先级（从高到低）**：
 
@@ -267,7 +372,7 @@ General-Purpose 子代理是一个功能强大的代理，适用于需要探索
 
 **主要特征：**
 
-* **模型**：使用默认模型进行更强大的推理
+* **模型**：使用默认编排，可通过 `/agents` 为该子代理独立调整
 * **工具**：可以访问所有工具
 * **模式**：可以读写文件、执行命令、进行修改
 * **用途**：复杂的研究任务、多步骤操作、代码修改
@@ -299,7 +404,7 @@ Plan 子代理是一个专门的内置代理，设计用于计划模式期间使
 
 **主要特征：**
 
-* **模型**：使用默认模型进行更强大的分析
+* **模型**：使用默认编排，可通过 `/agents` 为该子代理独立调整
 * **工具**：可以访问 Read、Glob、Grep 和 Bash 工具以进行代码库探索
 * **用途**：搜索文件、分析代码结构和收集上下文
 * **自动调用**：当 CodeBuddy Code 处于计划模式并需要研究代码库时，它会自动使用此代理
@@ -326,7 +431,7 @@ Explore 子代理是一个快速、轻量级的代理，专为搜索和分析代
 
 **主要特征：**
 
-* **模型**：使用 gemini-3.0-flash 进行快速、低延迟的搜索
+* **模型**：内置声明为 `lite` 场景变体；实际模型由对应的环境变量、项目和用户 `variantModels`、主模型 `relatedModels` 及默认编排共同决定
 * **模式**：严格只读 - 不能创建、修改或删除文件
 * **可用工具**：
   * Glob - 文件模式匹配

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

@@ -58,6 +58,61 @@ netstat -an | grep PORT_NUMBER
 
 ---
 
+## 内存溢出 (OOM) 排查
+
+**症状**：长时间运行的会话（尤其 `/goal` 这类自续跑循环、或超长上下文任务）跑数小时后进程崩溃，终端出现：
+
+```
+FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
+```
+
+### 为什么会发生
+
+- Node/V8 默认堆上限约 4GB（64 位）。超长会话里对话历史、工具结果等在内存中累积，堆可能一路涨到上限。
+- 自动上下文压缩按 **token 占模型窗口的比例**触发（约 92%）。**大窗口模型（如 1M 上下文）下，token 还远没到阈值，进程真实堆就已经先到 4GB 上限**——压缩来不及救场。
+- 硬 OOM（`FatalProcessOutOfMemory`）由 V8 直接终止进程，绕过所有 JS 异常处理，默认**不会留下堆快照**，事后难以定位是谁占了内存。
+
+### 先缓解
+
+- 用 `/clear` 清空上下文，或 `/compact` 主动压缩后再继续。
+- 把超大任务拆成多轮 / 多会话，避免单会话无限堆积。
+- 临时抬高堆上限（仅治标、推迟 OOM）：
+
+  ```bash
+  # 抬到 8GB 再启动(会被子进程继承)
+  NODE_OPTIONS=--max-old-space-size=8192 codebuddy
+  ```
+
+### 抓堆快照定位根因（默认关闭，按需开启）
+
+CodeBuddy 内置一个"近堆上限自愈快照"：当进程堆越过 V8 堆上限的高水位时，自动写一份 heap snapshot，供事后分析对象保留树。**因为快照文件很大（≈ 当时 heapUsed 的 1.5 倍，GB 级堆会写出数 GB 文件），默认关闭**，仅在复现/排查 OOM 时开启：
+
+```bash
+# 开启(默认 85% 水位)
+CODEBUDDY_CODE_HEAP_SNAPSHOT_NEAR_LIMIT_PCT=on codebuddy
+# 自定义水位:0.9 或 90 都表示 90%
+CODEBUDDY_CODE_HEAP_SNAPSHOT_NEAR_LIMIT_PCT=90 codebuddy
+# 关闭(默认): 不设 / 0 / off / false
+```
+
+- 快照落盘位置：`~/.codebuddy/diagnostics/<YYYY-MM-DD>/oom-nearlimit-<pid>-<时间戳>.heapsnapshot`（按天分层，同日志目录）。
+- 进程内**只抓一次**（越过水位后即写一份，避免濒临 OOM 时反复写 GB 级文件二次爆内存）。
+- 触发时会打一条告警日志：`[WorkflowMemProbe] near heap limit ...`。
+
+分析：用 Chrome DevTools → **Memory** → **Load** 载入该 `.heapsnapshot`，看 **Retainers / 对象保留树**，定位占用最大的对象及其引用链。
+
+> 说明：未采用 Node 内建的 `--heapsnapshot-near-heap-limit` / `v8.setHeapSnapshotNearHeapLimit`——它只能写到进程当前工作目录、无法指定路径，且在接近 100% 真上限才触发（那时再写 GB 级快照本身可能二次 OOM）。这里用 85% 高水位提前抓、并落到统一的 diagnostics 目录。
+
+### 反馈给开发
+
+请附上：
+
+- 终端里的 `FATAL ERROR: ... heap out of memory` 及其后的 native 栈；
+- `~/.codebuddy/logs/<date>/` 里崩溃前的 `[WorkflowMemProbe] tick ... heap=used/total` 心跳（能看出堆增长曲线）；
+- 若开启了快照：`~/.codebuddy/diagnostics/<date>/oom-nearlimit-*.heapsnapshot`。
+
+---
+
 ## 权限确认框无响应 / ESC 才能关
 
 **症状**：TUI 弹出工具权限确认框，按数字键 / 回车确认后弹框不消失，但 ESC 能正常关闭，且关闭后任务实际已在执行。

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

@@ -79,6 +79,7 @@ Web UI 支持两种认证模式：
 - **问答面板**：回答 Agent 的多选问题
 - **任务进度**：实时监控后台任务和 Team 进度
 - **会话管理**：新建对话、浏览历史、切换会话
+- **工作目录管理**：添加/移除附加工作目录，扩展 Agent 的文件访问范围（底部工具栏堆叠图标）
 
 ### 终端视图
 

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

@@ -116,6 +116,12 @@ CodeBuddy automatically decides how many members to generate based on the task,
 Create a 4-person team to refactor these modules in parallel, each member using the lite model.
 ```
 
+Team members use the same model resolution rules as regular sub-agents, and match persistent configuration by `subagent_type`:
+
+- Models explicitly specified in the prompt are per-invocation settings and can still be overridden by `CODEBUDDY_CODE_SUBAGENT_MODEL`.
+- When no model is explicitly specified, the system sequentially considers project-level and user-global per-sub-agent settings, built-in declarations, and finally inherits the team lead's main model.
+- Use `/agents` to manage per-sub-agent settings, and `/model` to manage the concrete models for `lite` / `reasoning`.
+
 ### Requiring Plans Before Implementation
 
 For complex or high-risk tasks, you can require members to submit plans before implementation:

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

@@ -43,6 +43,7 @@ Command-line parameters to customize CodeBuddy Code behavior:
 | `--tools`                        | Restrict available built-in tool set (whitelist). Empty string `""` disables all built-in tools, `"default"` uses all tools, or specify comma-separated tool names. Supports `Defer(X)` / `NoDefer(X)` modifiers to adjust tool deferred loading status on demand; see [Tool Deferred Loading Override](tool-defer-overlay.md) | `codebuddy --tools "Bash,Read,Defer(Glob)"`                                                        |
 | `--mcp-config <fileOrString>`    | Load MCP server configuration from a JSON file or JSON string                                                                    | `codebuddy --mcp-config ./mcp.json`                                                                 |
 | `--strict-mcp-config`            | Only use MCP servers provided by `--mcp-config` or SDK `mcpServers`, ignoring user, project, and local `.mcp.json` file-based configurations; when not explicitly passed, interactive mode, `--serve`, and ACP will continue to load these file-based configurations | `codebuddy --serve --strict-mcp-config`                                                             |
+| `--no-session-persistence`       | Keep session context in memory only, without creating or updating local transcripts; existing sessions can still be loaded read-only                                      | `codebuddy --serve --no-session-persistence`                                                       |
 | `--print`, `-p`                  | Print response and exit without entering interactive mode                                                                        | `codebuddy -p "query"`                                                                             |
 | `--settings`                     | Load additional settings configuration from a JSON file or JSON string                                                           | `codebuddy --settings '{"model":"gpt-5"}' "query"`                                                 |
 | `--setting-sources`              | Specify which settings sources to load, comma-separated (options: `user`, `project`, `local`). Default: `user,project,local`    | `codebuddy --setting-sources project,local "query"`                                                |
@@ -92,7 +93,7 @@ The `--agents` parameter accepts a JSON object defining one or more custom Sub-A
 | `prompt`          | Yes      | System prompt that guides the Sub-Agent's behavior                                               |
 | `tools`           | No       | Array of specific tools the Sub-Agent can use (e.g., `["Read", "Edit", "Bash"]`). Omit to inherit all tools |
 | `disallowedTools` | No       | Array of tools the Sub-Agent is forbidden to use (blacklist), unioned with the session-level `--disallowedTools` |
-| `model`           | No       | Model alias to use: `sonnet`, `opus`, or `haiku`. Omit to use the default Sub-Agent model       |
+| `model`           | No       | Model ID, name or alias, scenario variant `lite` / `reasoning`, or `inherit` / `default`. When omitted or set to `inherit` / `default`, the model is selected through the normal sub-agent resolution chain |
 
 Example:
 
@@ -102,7 +103,7 @@ codebuddy --agents '{
     "description": "Professional code reviewer. Use proactively after code changes.",
     "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
     "tools": ["Read", "Grep", "Glob", "Bash"],
-    "model": "sonnet"
+    "model": "lite"
   },
   "debugger": {
     "description": "Debugging expert for errors and test failures.",

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

@@ -80,13 +80,13 @@ By automatically selecting different models for different scenarios, you can ach
 
 ### Automatic Model Selection
 
-CodeBuddy Code automatically selects appropriate scenario models based on task type. When sub-agents execute, the system automatically resolves the corresponding scenario model based on the user's currently selected main model.
+CodeBuddy Code resolves the appropriate scenario model based on task type. For example, the built-in declaration for `Explore` is `lite`, which delegates code search to a faster, more economical model; planning tasks can use `reasoning`.
 
-For example, lightweight sub-agents like `contentAnalyzer` automatically use the `lite` model, reducing costs and improving speed while maintaining functionality.
+In the **Scenario Models** section of `/model`, map `lite` and `reasoning` to concrete models; to configure a specific built-in sub-agent individually, use `/agents` to select a specific model or scenario variant. Project settings only override sub-agents or scenario keys with the same name and do not remove other global mappings.
 
 The Agent tool supports specifying scenario type via the `model` parameter:
 
-* `default`: Inherits parent model, suitable for general tasks
+* `default`: Continues using the default orchestration composed of per-sub-agent settings, built-in declarations, and the main model
 * `lite`: Fast and low-cost, suitable for simple searches and quick file operations
 * `reasoning`: Enhanced reasoning capability, suitable for complex analysis and architectural decisions
 
@@ -124,7 +124,7 @@ Key information preserved during compaction: code change records, important deci
 
 ### Choose Appropriate Models
 
-Select models based on task complexity. Use `/model` to switch models during a session, or set defaults in `/config`.
+Select models based on task complexity. Use `/model` to switch the main model, or configure `lite` / `reasoning` in the **Scenario Models** section; use `/agents` to select scenario variants or specific models for individual built-in sub-agents.
 
 * **Use lite for simple tasks**: File search, quick queries, code formatting
 * **Use reasoning for complex tasks**: Architectural design, performance optimization, complex debugging

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

@@ -259,12 +259,18 @@ Start a daemon in a CI pipeline as an Agent service, and have other steps call i
 # CI startup
 codebuddy daemon start --port 9090
 
-# Other CI steps call the API
+# Other CI steps call the API (body uses Gateway Protocol format, must include id/type)
 curl -X POST http://127.0.0.1:9090/api/v1/runs \
   -H "Content-Type: application/json" \
-  -d '{"prompt": "Review the code changes in this PR"}'
+  -H "X-CodeBuddy-Request: 1" \
+  -d '{"id": "run-1", "type": "message", "payload": {"text": "Review the code changes in this PR"}}'
+# Response: {"data": {"runId": "uuid-xxx", "status": "accepted"}}
 ```
 
+> **Note**: `/api/v1/runs` requests must include the `X-CodeBuddy-Request` header, and the body must use
+> the [Gateway Protocol](./http-api.md) format (`id` and `type` are required; the prompt text goes in
+> `payload.text`). See the [HTTP API documentation](./http-api.md) for field details.
+
 ### Shared Agent for Teams
 
 Start a daemon on a development machine bound to a LAN address, allowing team members to share the same Agent environment through the Web UI.

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

@@ -32,10 +32,15 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `CODEBUDDY_CODE_SUBAGENT_MODEL` | **Blanket override** of the model for all built-in sub-agents (highest priority, overrides the `subagents` setting). To configure per sub-agent, use the `/agents` panel or `settings.json`'s `subagents.agents.<subagent-name>.model` |
 | `MAX_THINKING_TOKENS` | Enable extended thinking and set the token budget for the thinking process. Disabled by default |
 
-> **Relationship between env and settings**: Model-related environment variables are **ops/CI-level highest-priority overrides**.
-> - `CODEBUDDY_CODE_SUBAGENT_MODEL` applies a blanket override to **all** sub-agents; to specify **per sub-agent**, use `settings.json`'s `subagents.agents.<subagent-name>.model` (supports both global + project scope, editable in the `/agents` panel). See [Sub-Agents](sub-agents.md) for details.
-> - `CODEBUDDY_SMALL_FAST_MODEL` / `CODEBUDDY_BIG_SLOW_MODEL` are set **per variant** independently (the former only affects `lite`, the latter only affects `reasoning`); the corresponding persistable setting is `variantModels` (editable in the `/model` panel's "Scenario Variants" section). See [Settings](settings.md) for details.
-> - Priority: env (highest) > `settings` (project > global) > built-in default. Removing the env var restores the settings' effect.
+> **Relationship between env and settings**: Model-related environment variables are for ops/CI-level overrides.
+>
+> - Built-in sub-agents: `CODEBUDDY_CODE_SUBAGENT_MODEL` > the `model` parameter of the current Agent tool call > project-level `subagents` > user-global `subagents` > product built-in declaration > main model.
+> - Scenario variants: corresponding variant env var > project-level `variantModels` > user-global `variantModels` > main model's `relatedModels` > applicable product built-in default > main model.
+>
+> - `CODEBUDDY_CODE_SUBAGENT_MODEL` uniformly overrides all sub-agents. To specify individually, use `/agents` or `subagents.agents.<subagent-name>.model`; see [Sub-Agents](sub-agents.md) for details.
+> - `CODEBUDDY_SMALL_FAST_MODEL` only affects `lite`, `CODEBUDDY_BIG_SLOW_MODEL` only affects `reasoning`. The corresponding persistent settings can be managed via `/model` or `variantModels`; see [Settings](settings.md) for details.
+>
+> Removing the environment variable restores the lower-priority configuration, which may not directly fall back to the main model.
 
 ## Bash Tool Configuration
 
@@ -67,6 +72,7 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `CODEBUDDY_PLUGIN_DIRS` | Colon-separated list of local plugin directory paths (equivalent to `--plugin-dir`). The `bin/` directory of each plugin is automatically injected into `PATH` |
 | `CODEBUDDY_IMAGE_GEN_ENABLED` | Set to `false` or `0` to disable image generation |
 | `CODEBUDDY_IMAGE_EDIT_ENABLED` | Set to `false` or `0` to disable image editing |
+| `CODEBUDDY_SHARE_LINK_ENABLED` | Set to `false` or `0` to disable the ShareLink tool (uploads a local single HTML file and returns a shareable public link). Enabled by default. This environment variable has the highest priority; when unset, falls back to the cloud-side `productFeatures.ShareLink` toggle (default `true`) |
 | `CODEBUDDY_COMPUTER_USE_ENABLED` | **Experimental**: Set to `true` or `1` to enable the macOS desktop control tool (screenshot, mouse, keyboard). Available only on macOS, disabled by default. The first invocation of keyboard/mouse actions requires authorizing the terminal in System Settings → Privacy & Security → Accessibility and Screen Recording |
 | `CODEBUDDY_WAIT_FOR_MCP_SERVERS_ENABLED` | Set to `0` or `false` to disable the WaitForMcpServers tool. Enabled by default. In interactive mode, MCP connections are not awaited blockingly; when the LLM needs an MCP tool that is not yet ready, it can proactively call this tool to wait on demand. Set to `0` to disable in WorkBuddy scenarios |
 | `CODEBUDDY_DEFERRED_TOOLS_MCP_READY_WAIT_MS` | Maximum milliseconds to wait for MCP servers to be ready before rendering deferred tool descriptions, default `2500`. Set to `0` to skip waiting entirely — if connections are slow, the "still connecting" hint is immediately baked into the description; increase to give remote MCP servers more time to complete the handshake before the first prompt. Continues immediately once the server is ready; the timeout serves only as an upper bound |
@@ -75,6 +81,7 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `CODEBUDDY_DISABLE_CRON` | Set to `1` to disable scheduled tasks |
 | `CODEBUDDY_DISABLE_FORK_SUBAGENT` | Set to `1` to disable the Agent tool's fork sub-agent mode (`subagent_type="fork"`). When enabled, the fork-mode section is automatically hidden from the Agent tool description, so the model will not see this feature; if the model still passes `subagent_type="fork"`, the runtime falls back to a custom agent named `fork` (e.g., one defined by the user at `.codebuddy/agents/fork.md`), or otherwise rewrites it to a `general-purpose` regular sub-agent. Useful for host scenarios that need to avoid request amplification caused by recursive fork spawning |
 | `CODEBUDDY_REHYDRATE_IMAGE_BLOB_REFS` | Set to `true` to rehydrate image blob references to full base64 data in `-p` mode streaming output. Useful for downstream integrations that need direct access to image data |
+| `CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS` | Set to `1` / `true` to disable background tasks for the Agent, Bash, and PowerShell tools (`run_in_background=true`). When enabled, the `run_in_background` parameter is hidden from these tools' schemas so the model will not see it; even if historical/cached tool calls or direct callers pass this parameter, the runtime falls back to synchronous (Agent) / foreground (Bash, PowerShell) execution. Suitable for request-response SDK / one-shot task scenarios—where the main process exits immediately after the main turn ends and any background agent/background command results cannot flow back to the final response. Aligns with Claude Code's `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` (which also governs Agent + Bash + PowerShell). Unset by default (background tasks remain available). Independent from the print-mode guard (which always blocks background execution under `-p`) |
 
 ## Context and Memory
 
@@ -207,7 +214,7 @@ CodeBuddy Code supports reporting internal traces to your own Collector via the
 | `CODEBUDDY_GATEWAY_PASSWORD` | Gateway access password |
 | `CODEBUDDY_GATEWAY_FORCE_TUNNEL` | Set to `1` to force tunnel mode |
 | `CODEBUDDY_DISABLE_REQUEST_VALIDATION` | Set to `1` to disable Gateway custom request header validation (`X-CodeBuddy-Request`). See [HTTP API Security](./http-api.md#security) |
-| `CODEBUDDY_CODE_CORS_ORIGINS` | Additional CORS allowed origins (comma-separated). Supports exact origins, `*.domain` subdomain wildcards, and `*` for all. E.g., `https://*.example.com,https://specific.com` |
+| `CODEBUDDY_CODE_CORS_ORIGINS` | Additional CORS allowed origins (comma-separated). Supports exact origins, `*.domain` subdomain wildcards, and `*` for all. E.g., `https://*.example.com,https://specific.com`. When unset, if the service is bound to `0.0.0.0` (`--host 0.0.0.0`), all origins are automatically allowed |
 | `SERVER__HOST` | Listen address for `--serve` mode (default: `127.0.0.1`) |
 | `SERVER__PORT` | Listen port for `--serve` mode |
 
@@ -246,6 +253,8 @@ CodeBuddy Code supports reporting internal traces to your own Collector via the
 | `CODEBUDDY_DEBUG_SDK` | Set to `1`/`true`/`yes`/`on` to enable SDK debugging |
 | `CODEBUDDY_DEBUG_REQUEST` | Set to `1` to enable request debugging |
 | `CODEBUDDY_STARTUP_PROFILE` | Set to `1` to enable startup profiling |
+| `CODEBUDDY_CODE_HEAP_SNAPSHOT_NEAR_LIMIT_PCT` | **OOM forensics** (off by default). When enabled, if the process heap crosses the V8 heap limit high-water mark, a heap snapshot is automatically written to `~/.codebuddy/diagnostics/<date>/oom-nearlimit-<pid>-<ts>.heapsnapshot` (written only once per process). Values: `on`/`true`/`1` for the default 85% threshold; `0.9` or `90` for a custom threshold; unset / `0` / `off` / `false` to disable. ⚠️ Snapshot files are ~1.5× the heapUsed at that time (multi-GB heaps produce multi-GB files); only enable when troubleshooting OOM. See [Troubleshooting · OOM](troubleshooting.md#memory-overflow-oom-troubleshooting) |
+| `CBC_HEAP_SNAPSHOT_ON_WORKFLOW_END` | Set to `1` to write a heap snapshot after each workflow (e.g., `ultracode`) completes, saved to `~/.codebuddy/diagnostics/<date>/`. Off by default (consumes disk); only enable when troubleshooting workflow memory leaks |
 
 ## E2E Testing (Record/Replay)
 
@@ -316,7 +325,8 @@ export CODEBUDDY_BIG_SLOW_MODEL="deepseek-v4-pro"
 # Small model for background/lightweight tasks
 export CODEBUDDY_SMALL_FAST_MODEL="deepseek-v4-flash"
 
-# Model used by sub-agents (inherits from the main Agent when unset)
+# Ops-level blanket override for all sub-agents.
+# When unset, per-invocation, per-sub-agent settings, and product built-in orchestration are used.
 export CODEBUDDY_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
 
 # Optionally specify the main model explicitly via --model at startup

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

@@ -322,7 +322,7 @@ When `continueOnBlock` is `false` (default):
 | Event | Trigger | Matcher support | Typical use cases |
 | --- | --- | --- | --- |
 | `PreToolUse` | Before a tool executes | Yes (tool name) | Command validation, approvals, logging |
-| `PostToolUse` | After a tool succeeds | Yes | Auto-formatting, context enrichment |
+| `PostToolUse` | After a tool succeeds | Yes | Auto-formatting, context enrichment, compress/replace tool results |
 | `Notification` | Permission prompts or 60s idle reminders | Partial | Desktop alerts, IM pings |
 | `UserPromptSubmit` | User message submitted<br/>*(internal commands excluded)* | No | Content review, context injection |
 | `Stop` | Main agent reply finishes | No | Force continuation, add reminders |
@@ -591,7 +591,7 @@ Use exit status, stdout, and stderr to convey results:
 | Event | Effect |
 | --- | --- |
 | PreToolUse | Blocks the tool call and surfaces message to Agent |
-| PostToolUse | Surfaces message to Agent (tool already ran, used for context injection) |
+| PostToolUse | Surfaces message to Agent (tool already ran, used for context injection); can use `updatedToolOutput` to replace tool results |
 | Notification | N/A – message shown to the user |
 | UserPromptSubmit | Blocks the prompt, clears it, message shown to user only |
 | Stop | Blocks the stop action, surfaces message to Agent and continues conversation |
@@ -645,9 +645,14 @@ PreToolUse hooks can control whether the tool call proceeds.
 - `"ask"` – Force the UI to prompt the user, `permissionDecisionReason` is shown in the confirmation dialog
 - `modifiedInput` – Mutate tool arguments before execution (partial field override)
 
-#### PostToolUse Context Injection
+#### PostToolUse Context Injection & Result Replacement
 
-PostToolUse fires **after** the tool has executed, so it cannot truly "block" the operation. Instead, use it to inject additional context to the Agent.
+PostToolUse fires **after** the tool has executed, so it cannot truly "block" the operation. Instead, it can:
+
+1. **Append** additional context to the Agent (`additionalContext`);
+2. **Replace** the tool result that will be sent to the Agent (`updatedToolOutput`).
+
+**Append context** (original tool result is preserved, with an additional note appended):
 
 ```jsonc
 {
@@ -658,6 +663,23 @@ PostToolUse fires **after** the tool has executed, so it cannot truly "block" th
 }
 ```
 
+**Replace tool result** (the return value entirely replaces the original tool output before sending to the Agent):
+
+```jsonc
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "updatedToolOutput": "Compressed tool output"
+  }
+}
+```
+
+- `updatedToolOutput` works for **all tools** (both built-in and MCP tools).
+- Typical use case: compress verbose tool output (e.g., oversized command logs, very long file contents) to save context tokens — this kind of "compression" hook relies on the replacement capability.
+- Difference from `additionalContext`: `additionalContext` **appends** (the result only gets longer), while `updatedToolOutput` **replaces** (the result can get shorter).
+- Both can be returned simultaneously: `updatedToolOutput` replaces first, then `additionalContext` is appended to the replaced content.
+- For MCP tools, if the returned `updatedToolOutput` is an array, it is used as-is as the MCP content array; otherwise it is wrapped as a single text block.
+
 > **Note:** The `decision: "block"` field is deprecated. Since the tool has already executed, blocking has no effect.
 
 #### UserPromptSubmit Decision Control