@tencent-ai/codebuddy-code 2.97.0-next.943311f.20260514 → 2.97.0-next.bcf636d.20260514

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

@@ -77,12 +77,13 @@
 
 `--agents` 参数接受定义一个或多个自定义子代理的 JSON 对象。每个子代理需要一个唯一的名称（作为键）和一个包含以下字段的定义对象：
 
-| 字段          | 必需 | 说明                                                                           |
-| :------------ | :--- | :----------------------------------------------------------------------------- |
-| `description` | 是   | 何时应调用子代理的自然语言描述                                                 |
-| `prompt`      | 是   | 指导子代理行为的系统提示词                                                     |
-| `tools`       | 否   | 子代理可以使用的特定工具数组（如 `["Read", "Edit", "Bash"]`)。省略则继承所有工具 |
-| `model`       | 否   | 要使用的模型别名: `sonnet`、`opus` 或 `haiku`。省略则使用默认子代理模型        |
+| 字段              | 必需 | 说明                                                                           |
+| :---------------- | :--- | :----------------------------------------------------------------------------- |
+| `description`     | 是   | 何时应调用子代理的自然语言描述                                                 |
+| `prompt`          | 是   | 指导子代理行为的系统提示词                                                     |
+| `tools`           | 否   | 子代理可以使用的特定工具数组（如 `["Read", "Edit", "Bash"]`)。省略则继承所有工具 |
+| `disallowedTools` | 否   | 子代理禁止使用的工具数组（黑名单），与 session 级 `--disallowedTools` 取并集生效 |
+| `model`           | 否   | 要使用的模型别名: `sonnet`、`opus` 或 `haiku`。省略则使用默认子代理模型        |
 
 示例：
 

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

@@ -93,8 +93,8 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 |---------|------|
 | `CODEBUDDY_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出 token 数 |
 | `CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 覆盖文件读取的默认 token 限制（默认：20000） |
-| `CODEBUDDY_STREAM_TIMEOUT_MS` | 流式响应中两个数据块之间允许的最大静默时间（毫秒）（默认：120000） |
-| `CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS` | 等待第一个模型输出的最大时间（毫秒）（默认：120000） |
+| `CODEBUDDY_STREAM_TIMEOUT_MS` | 流式响应中两个数据块之间允许的最大静默时间（毫秒）（默认：1200000） |
+| `CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS` | 等待第一个模型输出的最大时间（毫秒）（默认：1200000） |
 | `CODEBUDDY_SESSION_MAX_ITEMS` | `session/load` 回放时历史消息的最大条数（默认：1000）。达到阈值且遇到 user message 时停止逆序读取 JSONL。需要支持超长会话（如沙箱场景）时可调大（例如 2000 或更多）；零/负数/非数字会回退到默认值 |
 
 ## 文件系统和配置

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

@@ -5,5 +5,57 @@
 > 建议先阅读 [Hook 参考指南](./hooks.md)，了解所有事件、输入输出结构与安全要求。本指南聚焦于实际操作演练与常见示例，帮助你迅速在 CodeBuddy Code 项目中启用 Hooks 功能。
 > **注意**：Hook 功能目前处于 **Beta** 阶段，仍在持续打磨，请留意后续版本更新。
 
+name: code-reviewer
+description: 代码审查 Skill，执行前检查 Bash 命令白名单
+context: fork
+agent: Explore
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: ${CODEBUDDY_SKILL_DIR}/scripts/check-bash.sh
+          timeout: 5
+  Stop:  # 自动重写为 SubagentStop
+    - hooks:
+        - type: command
+          command: echo "review done at $(date)" >> ${CODEBUDDY_PROJECT_DIR}/.cbc-review.log
+---
+
+请审查 $ARGUMENTS 涉及的代码...
+```
+
+**启用前**：在 `~/.codebuddy/settings.json` 中开启闸门（默认关闭，所有非内置来源的 frontmatter hooks 都会被静默跳过）：
+
+```json
+{
+  "allowUntrustedFrontmatterHooks": true
+}
+```
+
+更详细的字段语义、安全闸门与作用域规则见 [Skills 文档 - 在 Skill 中配置 Hooks](./skills.md#在-skill-中配置-hooks) 与 [Hook 参考指南 - Frontmatter Hooks](./hooks.md#agent--skill-frontmatter-hooks)。
+
+## 最佳实践与建议
+
+1. **小步验证**：先从日志类 hook 入手再逐步添加高风险操作。
+2. **控制超时**：默认 60 秒，如脚本存在长时间任务请确保及时输出或拆分处理。
+3. **使用 matcher 过滤**：合理设置 `matcher` 可减少无关 hook 执行次数。
+4. **统一脚本目录**：建议在项目根创建 `.codebuddy/hooks/` 目录集中管理脚本并纳入版本控制。
+5. **重视安全**：
+   * 避免在 hook 中直接使用未验证的用户输入。
+   * 对外部命令使用绝对路径，防止 PATH 劫持。
+   * 结合 `/hooks` 面板的安全确认机制，确保所有 hook 均被审核运行。
+6. **与 MCP 工具配合**：MCP 工具名称形如 `mcp__<server>__<tool>`,可在 `matcher` 中通过正则整批控制,如 `mcp__github__.*`。
+7. **面板是权威入口**：任何外部文件修改都需要在面板确认后生效，务必完成该步骤。
+8. **Python 脚本调用**：始终使用 `python3 your_script.py` 而不是直接执行 `.py` 文件，因为 Windows Git Bash 环境下不一定能正确识别 Python 脚本的 shebang 行。
+9. **Windows 兼容性**：Hook 命令在 Windows 上通过 Git Bash 执行。请确保命令使用 bash 语法，且避免依赖 cmd.exe 或 PowerShell 特有的语法。
+
+## 了解更多
+
+* 关于 hooks 的参考文档，请参阅 [Hook 参考指南](./hooks.md)。
+* 有关全面的安全最佳实践和安全指南，请参阅 Hook 参考指南中的[安全注意事项](./hooks.md#安全注意事项)。
+* 有关故障排除步骤和调试技术，请参阅 Hook 参考指南中的[调试](./hooks.md#调试)部分。
+
+---
 
 现在你已掌握在 CodeBuddy Code 中启用 hooks 的核心流程。更多事件字段细节、决策控制和安全注意事项请查阅 [Hook 参考指南](./hooks.md)。祝你构建出既强大又安全的自动化工作流！

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

@@ -802,7 +802,11 @@ MCP 工具遵循 `mcp__<server>__<tool>` 模式，例如：
 
 ## Agent / Skill Frontmatter Hooks
 
-除了全局 `~/.codebuddy/settings.json` 配置的 hooks 外，还可以直接在自定义 agent 的 `.md` 文件或 skill 的 `SKILL.md` 的 YAML frontmatter 里声明 `hooks` 字段。这些 hooks 只在对应的 subagent 或 fork skill 的生命周期内生效，结束后自动清理。
+除了在 `~/.codebuddy/settings.json` 中全局配置 hooks 外，还可以直接在自定义 Agent 的 `.md` 文件或 Skill 的 `SKILL.md` 的 YAML frontmatter 里声明 `hooks` 字段。这种方式让 Hook 与 Agent / Skill 一起作为"原子单位"分发，scope 自动随 subagent 生命周期开闭，不污染主会话。
+
+### 字段格式
+
+`hooks` 字段结构和 settings.json 完全一致——按事件名分组，每个事件下若干个 `{matcher?, hooks[]}` 配置；hook `type` 支持 `command` / `prompt` / `agent` / `http` 四种：
 
 ```yaml
 ---
@@ -819,13 +823,54 @@ hooks:
     - hooks:
         - type: command
           command: echo "reviewer finished"
+        - type: http
+          url: https://example.com/notify
+          method: POST
 ---
 ```
 
-- **范围限定**：skill 仅 `context: fork` 时支持 frontmatter hooks（注入路径无清晰生命周期边界，不接入）。
-- **`Stop` 自动转 `SubagentStop`**：agent 里写的 `Stop` event 会被转为 `SubagentStop` 以对齐 subagent 语义。
-- **安全闸门（默认关闭）**：出于安全考虑，来自**非 product 内置**来源的 frontmatter hooks 默认不会被注册，包括用户本地 `.codebuddy/agents|skills/*.md` 以及插件市场分发的 agent/skill。启用需在 `~/.codebuddy/settings.json` 中设置 `"allowUntrustedFrontmatterHooks": true`。只有 product 内置 agent/skill 自动放行。
-- **格式容错**：非法的 hook 定义会被静默丢弃，完全破损的 YAML 会在日志中输出 `Malformed YAML frontmatter in '<path>'` 诊断信息。
+### 生命周期与作用域
+
+- **范围限定**：Skill 仅 `context: fork` 时支持 frontmatter hooks（注入路径无清晰生命周期边界，不接入）；自定义 Agent 总是支持。
+- **自动注册/清理**：subagent 启动时把 frontmatter hooks 注册到 `ScopedHookRegistry`，subagent 退出时自动注销。Hooks 仅对该 subagent 自身的工具调用 / 生命周期事件生效。
+- **`Stop` → `SubagentStop` 重写**：在 frontmatter 中写 `Stop` 事件会被自动重写为 `SubagentStop`——subagent 完成时不会触发主会话的 `Stop`，写 `Stop` 是想表达"subagent 自己结束"的语义。
+- **与全局 hooks 合并**：相同事件下，frontmatter hooks 与 `settings.json` / 插件 `hooks/hooks.json` 会**叠加**（不覆盖），全部并行触发。
+
+### 安全闸门（`allowUntrustedFrontmatterHooks`）
+
+frontmatter hooks 可以静默触发 Shell 命令，因此**来自非内置来源的 frontmatter hooks 默认不会被注册**：
+
+| 来源 | 默认是否注册 |
+| --- | --- |
+| Product 内置 Agent / Skill | ✅ 自动放行 |
+| `.codebuddy/agents/*.md`（用户/项目本地 Agent） | ❌ 默认拒绝 |
+| `.codebuddy/skills/SKILL.md`（用户/项目本地 Skill） | ❌ 默认拒绝 |
+| 插件市场分发的 Agent / Skill | ❌ 默认拒绝 |
+| 插件 `hooks/hooks.json`（不是 frontmatter） | ✅ 不受闸门约束 |
+
+需要启用时，在 `~/.codebuddy/settings.json` 设置：
+
+```json
+{
+  "allowUntrustedFrontmatterHooks": true
+}
+```
+
+被闸门拦截时 CLI 会输出 warning：
+
+```
+[AgentTask] Frontmatter hooks from skill 'xxx' skipped
+(source not admin-trusted; enable `allowUntrustedFrontmatterHooks` in settings to allow)
+```
+
+### 容错与诊断
+
+- **静默丢弃非法定义**：单条 hook 不符合 schema 时只跳过该条，不影响整段 hooks 解析；warning 中包含 `event 'YYY' invalid: <详细原因>` 便于定位。
+- **未知事件名**：会被 warning 跳过（`unknown event 'XXX'`），不会让整个 frontmatter 报废。
+- **YAML 完全破损**：日志会输出 `Malformed YAML frontmatter in '<path>'`。
+- **运行时调试**：`CODEBUDDY_DEBUG=1` 启动后可以看到 `[ScopedHookRegistry] registered N hook config(s) for scope '<sessionId>' (...)` 这样的注册日志，确认 hooks 是否就位。
+
+> 在 Skill 中使用 frontmatter hooks 的完整示例见 [Skills 文档 - 在 Skill 中配置 Hooks](./skills.md#在-skill-中配置-hooks)。
 
 ---
 

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

@@ -94,6 +94,17 @@ disallowedTools: Write, Edit
 - `prompt`：使用 LLM 评估提示词（使用 `$ARGUMENTS` 占位符获取上下文）
 - `agent`：运行带工具的代理验证器，用于复杂验证任务
 
+**与 Skill / Agent frontmatter hooks 的区别**:
+
+插件可以通过两条不同的路径携带 hooks：
+
+| 路径 | 作用域 | 安全闸门 |
+| --- | --- | --- |
+| `hooks/hooks.json`（本节描述） | 整个会话（插件启用时） | 不受 `allowUntrustedFrontmatterHooks` 约束，启用插件即生效 |
+| `agents/*.md` 或 `skills/SKILL.md` 中的 `hooks` frontmatter | 仅在该 subagent / fork skill 生命周期内 | 受 `allowUntrustedFrontmatterHooks` 闸门约束，默认拒绝；用户需在 `settings.json` 显式开启 |
+
+由于 frontmatter hooks 受安全闸门拦截，插件分发的 Skill / Agent 如果依赖 frontmatter hooks 才能正常工作，应在插件 README 中明确告知用户开启 `allowUntrustedFrontmatterHooks` 设置。详见 [Hook 参考指南 - Frontmatter Hooks](./hooks.md#agent--skill-frontmatter-hooks)。
+
 ### 4. MCP Servers（MCP 服务器）
 
 插件可以捆绑 Model Context Protocol (MCP) 服务器，将 CodeBuddy 与外部工具和服务连接。

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

@@ -272,6 +272,10 @@ Hooks 允许在特定事件发生时自动执行操作。命令通过标准输
 }
 ```
 
+插件 `hooks/hooks.json` 中的 hooks 在插件启用时自动与用户和项目级 hooks **合并**（不会覆盖），并且**不**受 `allowUntrustedFrontmatterHooks` 闸门约束（该闸门只针对 Agent / Skill frontmatter 中声明的 hooks）。
+
+除了 `command`，hook 也支持 `type: prompt`（小模型语义判定）、`type: agent`（subagent 验证）、`type: http`（POST/PUT/PATCH 到指定 URL）三种执行方式，详见 [Hooks 文档](hooks.md)。如果你的插件还需要随 Skill 一起携带 frontmatter hooks，请参考 [Skills 文档 - 在 Skill 中配置 Hooks](skills.md#在-skill-中配置-hooks)（注意此路径受安全闸门约束）。
+
 详细说明请参考 [Hooks 文档](hooks.md)。
 
 ### 添加 LSP 服务器

package/dist/web-ui/docs/cn/cli/release-notes/README.md

@@ -17,6 +17,8 @@ Release Notes 记录了每个版本的用户可见变更，包括：
 
 <!-- 新版本自动添加到此处 -->
 
+- [v2.96.0](./v2.96.0.md) - 2026-05-11
+- [v2.95.1](./v2.95.1.md) - 2026-05-07
 - [v2.95.0](./v2.95.0.md) - 2026-05-01
 - [v2.94.4](./v2.94.4.md) - 2026-05-01
 - [v2.94.3](./v2.94.3.md) - 2026-04-29

package/dist/web-ui/docs/cn/cli/release-notes/v2.95.1.md

@@ -0,0 +1,27 @@
+# 🚀 CodeBuddy Code v2.95.1 发布
+
+## ✨ 新功能
+
+### 通用 Agent 支持图像生成与编辑
+
+general-purpose 子 agent 的工具清单新增 ImageGen 和 ImageEdit，可在子任务中直接生成图像或基于已有图像进行编辑。是否可用仍由模型能力 tag 决定。
+
+## 🔧 改进优化
+
+- **Skill 工具描述截断**：采用三阶段均衡截断策略，大量 skills 场景下工具描述自动按字符预算收敛，不再无限膨胀。新增 env `CODEBUDDY_SKILL_TOOL_CHAR_BUDGET` 独立控制 Skill 工具描述预算（默认 8000）。⚠️ **破坏性变更**：SlashCommand 工具默认字符预算由 15000 调整为 8000，可设 `SLASH_COMMAND_TOOL_CHAR_BUDGET=15000` 恢复
+- **MCP 大响应处理**：MCP 工具响应超出 token 上限时不再直接报错中断会话，改为把完整内容保存到会话目录并返回读取指引，模型可按 offset/limit 分段读取。可通过环境变量 `CODEBUDDY_DISABLE_MCP_LARGE_OUTPUT_FILES=1` 始终走截断降级
+- **流式响应超时**：将首 token 等待和流间静默两项默认超时由 10 分钟提升至 20 分钟，避免长上下文请求或慢响应模型在首 token 阶段被误判为连接丢失
+- **Windows 粘贴体验**：提升 Windows 终端中大段文本和剪贴板内容粘贴的稳定性，减少输入闪烁和内容分片问题
+- **统一 cancel 清理编排器**：收到 cancel 信号时按六个维度统一清理 session 运行时状态（交互、模式、Todo、工具广播、压缩状态位、UI 进度信号），彻底消除"取消后脏状态残留到下一轮 prompt"和"取消后压缩 loading 横幅不消失"类 bug
+- **内部生成器 agent 优化**：上下文压缩、标题生成、摘要生成等内部任务的 agent 不再自动注入 SendMessage 工具，节省 prompt token 并避免污染结构化输出
+
+## 🐛 问题修复
+
+- **取消压缩后 UI 状态显示**：修复流式压缩中点取消按钮，分隔线 UI 不能正确反映"被取消"语义的问题——之前会显示"上下文已压缩 ✓"误判或继续显示"正在压缩..."shimmer。自动 compact 与手动 `/compact` 双路径均已覆盖
+- **ACP 自动压缩静默语义**：自动压缩期间触发的内部 abort/error 不再向 ACP 客户端暴露 `stopReason='cancelled'`，外部消费方（IDE/Web UI/Desktop）不再看到一次无意义的"已取消"闪现；用户主动 Ctrl-C / ACP cancel 仍正常发取消信号
+- **桌面操作工具可见性**：桌面操作工具在未启用或非 macOS 场景下不再出现在工具搜索描述里，避免模型尝试调用后被拒绝
+
+## 📝 文档更新
+
+- **CLI 文档同步**：同步更新 bash-sandboxing、env-vars、hooks、interactive-mode、mcp、plugins-reference、settings、skills 等多语言版本（cn/en/zh）
+- **历史 release notes 补齐**：发布 v2.94.0~v2.94.4 历史版本的 release notes 文档

package/dist/web-ui/docs/cn/cli/release-notes/v2.96.0.md

@@ -0,0 +1,21 @@
+# 🚀 CodeBuddy Code v2.96.0 发布
+
+## ✨ 新功能
+
+### SDK 自定义子代理支持
+
+通过 SDK `initialize` 传入的 `agents` / `systemPrompt` / `appendSystemPrompt` 现在会正确注入产品配置，与 CLI 的 `--agents` / `--system-prompt` / `--append-system-prompt` 等价生效，SDK 用户也能便捷地自定义子代理和系统提示词。
+
+### 子代理黑名单
+
+`AgentDefinition` 新增 `disallowedTools` 字段，可以为单个子代理配置禁用工具清单，并与 session 级 `--disallowedTools` 自动取并集生效，更精细地控制子代理能力边界。
+
+## 🔧 改进优化
+
+- **会话标题国际化**：AI 自动生成的会话标题现在会遵循用户的语言设置，中文环境生成中文标题，不再固定输出英文。
+
+## 🐛 问题修复
+
+- **Web UI 刷新丢失会话标题**：恢复已有会话时，顶部标题立即显示原标题，不再短暂退回到"新对话"。
+- **MCP 列表缓存**：修复 `list()` 返回空结果后再 `add()` 时新服务器不会出现在缓存里的问题。
+- **流式输出模型展示**：`stream-json` 输出现在优先采用 provider 实际上报的 model id，避免在转发子代理事件时显示父 agent 的配置 id，提升可观察性。

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

@@ -79,6 +79,8 @@ Skill 文件使用 Markdown 格式，支持 YAML Frontmatter 定义元数据：
 | `user-invocable` | 否 | 设置为 `false` 时，Skill 从 `/` 菜单中隐藏，仅供 AI 内部调用或其他 Skill 引用，默认 `true` | `false` |
 | `context` | 否 | 设置为 `fork` 时，Skill 在独立的 subagent 上下文中执行 | `fork` |
 | `agent` | 否 | 指定 subagent 类型，仅在 `context: fork` 时有效 | `Explore` |
+| `model` | 否 | 指定 Skill 执行时使用的模型（仅 `context: fork` 时生效，未配置时回退到 agent 默认模型） | `claude-sonnet-4` |
+| `hooks` | 否 | 在 SKILL.md 中声明 Skill 专属的 Hooks，仅 `context: fork` 时生效，详见 [在 Skill 中配置 Hooks](#在-skill-中配置-hooks) | 见下文 |
 
 ## 变量占位符
 
@@ -201,6 +203,95 @@ user-invocable: false
 
 > **注意**：`context: fork` 只适用于包含明确任务的 Skill。仅有指导方针没有具体任务时，不会产生有意义的输出。
 
+## 在 Skill 中配置 Hooks
+
+> **版本要求**：Skill frontmatter `hooks` 字段需要 CodeBuddy Code 支持 Frontmatter Hooks 的版本（Beta）。
+
+除了在 `~/.codebuddy/settings.json` 中全局配置 Hooks，Skill 还可以直接在 SKILL.md 的 frontmatter 里声明 `hooks` 字段，把 Hook 与 Skill 自身打包在一起。这对于 fork 类 Skill 尤其有用——可以在 fork subagent 内部加守卫、日志、回调，且不污染主会话。
+
+### 适用范围
+
+- **仅 `context: fork` 生效**：注入路径（默认 inline 模式）的 Skill 没有清晰的生命周期边界，frontmatter hooks 会被解析但不会注册到运行时。
+- **生命周期与 fork subagent 绑定**：fork subagent 启动时注册 hooks，结束时自动清理，不影响主会话和其他 Skill。
+- **`Stop` 自动转 `SubagentStop`**：在 frontmatter 中写 `Stop` event 会被自动重写为 `SubagentStop`，对齐 subagent 完成的真实事件。
+
+### 字段格式
+
+`hooks` 字段的结构和 `settings.json` 中的 `hooks` 完全一致——按事件名分组、每条配置可带 `matcher` 和 `hooks[]` 数组：
+
+```yaml
+---
+name: secure-reviewer
+description: 代码审查 Skill，在执行前检查文件白名单
+context: fork
+agent: Explore
+hooks:
+  PreToolUse:
+    - matcher: "Read|Glob|Grep"
+      hooks:
+        - type: command
+          command: ${CODEBUDDY_SKILL_DIR}/scripts/check-paths.sh
+          timeout: 10
+  PostToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: prompt
+          prompt: "检查 Bash 输出是否包含敏感信息，发现则在 reason 字段说明。"
+  Stop:  # 自动重写为 SubagentStop
+    - hooks:
+        - type: command
+          command: echo "review skill finished" >> ${CODEBUDDY_PROJECT_DIR}/.cbc-review.log
+---
+
+请审查 $ARGUMENTS 中提到的文件...
+```
+
+支持的 hook `type`：
+
+- `command`：执行 Shell 命令（含 `shell: bash | powershell`、`timeout`、`if`、`once`、`async` 等可选字段）
+- `prompt`：交给小模型（默认 Haiku 级）做语义判定
+- `agent`：起一个 subagent 做更复杂的判定，可以指定 `agentType` / `model`
+- `http`：把事件 payload 通过 POST/PUT/PATCH 发到指定 URL
+
+完整字段语义请参考 [Hook 参考指南](./hooks.md)。
+
+### 安全闸门：admin-trusted
+
+出于安全考虑，**来自非内置来源的 Skill frontmatter hooks 默认不会被注册**。当前所有通过 `.codebuddy/skills/`、项目本地、插件市场加载的 Skill 都属于"非可信来源"——它们可以静默触发 Shell 命令，因此需要用户显式同意。
+
+启用方式：在 `~/.codebuddy/settings.json` 中设置
+
+```json
+{
+  "allowUntrustedFrontmatterHooks": true
+}
+```
+
+启用后所有来源的 Skill / Agent frontmatter hooks 才会被注册；否则 CLI 会输出类似下面的 warning 并跳过该 Skill 的 hooks：
+
+```
+[AgentTask] Frontmatter hooks from skill 'secure-reviewer' skipped
+(source not admin-trusted; enable `allowUntrustedFrontmatterHooks` in settings to allow)
+```
+
+> 内置 product-bundled 的 Skill 不受此闸门约束，自动放行。Plugin 通过 `hooks/hooks.json` 配置的 hooks 走另一条路径，**不**受该闸门控制。
+
+### 与全局 hooks 的合并
+
+Skill frontmatter hooks 和 `settings.json` 中的全局 hooks 是**叠加合并**关系——同一事件下两边的所有匹配 hooks 都会被并行触发，不存在覆盖。区别在于：
+
+| 来源 | 作用域 | 受 admin-trusted 闸门约束 |
+| --- | --- | --- |
+| `settings.json` (全局/项目/local) | 整个会话 | 否 |
+| Plugin `hooks/hooks.json` | 整个会话（插件启用时） | 否 |
+| Agent `.md` frontmatter | 该 subagent 生命周期 | 是 |
+| Skill `SKILL.md` frontmatter（仅 fork） | 该 fork subagent 生命周期 | 是 |
+
+### 调试
+
+- 启动时设置 `CODEBUDDY_DEBUG=1`，可以在日志看到 `[ScopedHookRegistry] registered N hook config(s) for scope ...` 等注册行。
+- frontmatter 里非法的 hook 定义会被静默丢弃，但会在日志输出 `[parseFrontmatterHooks] skill 'xxx': event 'YYY' invalid: ...`，仔细看日志即可定位。
+
 ## 使用示例
 
 ### 示例 1：PDF 处理 Skill

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

@@ -82,6 +82,7 @@ The `--agents` parameter accepts a JSON object defining one or more custom Sub-A
 | `description` | Yes      | Natural language description of when the Sub-Agent should be invoked                             |
 | `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       |
 
 Example:

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

@@ -93,8 +93,8 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 |---------|------|
 | `CODEBUDDY_CODE_MAX_OUTPUT_TOKENS` | Set the maximum output tokens for most requests |
 | `CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override the default token limit for file reads (default: 20000) |
-| `CODEBUDDY_STREAM_TIMEOUT_MS` | Maximum silent time between two data chunks in streaming responses (milliseconds) (default: 120000) |
-| `CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS` | Maximum time to wait for the first model output (milliseconds) (default: 120000) |
+| `CODEBUDDY_STREAM_TIMEOUT_MS` | Maximum silent time between two data chunks in streaming responses (milliseconds) (default: 1200000) |
+| `CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS` | Maximum time to wait for the first model output (milliseconds) (default: 1200000) |
 | `CODEBUDDY_SESSION_MAX_ITEMS` | Maximum number of history messages to replay during `session/load` (default: 1000). Stops reading the JSONL in reverse when the threshold is reached and a user message is encountered. Increase (e.g., 2000 or more) when very long sessions need to be supported (such as sandbox scenarios); zero/negative/non-numeric values fall back to the default |
 
 ## Filesystem and Configuration

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

@@ -5,5 +5,57 @@ Learn how to customize and extend CodeBuddy Code's behavior by registering shell
 > We recommend reading the [Hook Reference Guide](./hooks.md) first to understand all events, input/output structures, and security requirements. This guide focuses on practical walkthroughs and common examples to help you quickly enable Hooks functionality in your CodeBuddy Code projects.
 > **Note**: The Hooks feature is currently in **Beta** and is being actively refined. Please watch for updates in future releases.
 
+name: code-reviewer
+description: Code review Skill that checks the Bash command whitelist before execution
+context: fork
+agent: Explore
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: ${CODEBUDDY_SKILL_DIR}/scripts/check-bash.sh
+          timeout: 5
+  Stop:  # Automatically rewritten as SubagentStop
+    - hooks:
+        - type: command
+          command: echo "review done at $(date)" >> ${CODEBUDDY_PROJECT_DIR}/.cbc-review.log
+---
+
+Please review the code involved in $ARGUMENTS...
+```
+
+**Before enabling**: Open the gate in `~/.codebuddy/settings.json` (off by default; all frontmatter hooks from non-built-in sources are silently skipped):
+
+```json
+{
+  "allowUntrustedFrontmatterHooks": true
+}
+```
+
+For more detailed field semantics, security gates, and scope rules, see [Skills Documentation - Configuring Hooks in Skills](./skills.md#configuring-hooks-in-skills) and [Hook Reference Guide - Frontmatter Hooks](./hooks.md#agent--skill-frontmatter-hooks).
+
+## Best Practices and Recommendations
+
+1. **Validate incrementally**: Start with logging hooks before gradually adding high-risk operations.
+2. **Control timeouts**: Default is 60 seconds; if your script has long-running tasks, ensure timely output or split processing.
+3. **Use matcher filtering**: Properly setting `matcher` can reduce unnecessary hook executions.
+4. **Centralize script directory**: Recommend creating a `.codebuddy/hooks/` directory in the project root to centrally manage scripts and include them in version control.
+5. **Prioritize security**:
+   * Avoid using unvalidated user input directly in hooks.
+   * Use absolute paths for external commands to prevent PATH hijacking.
+   * Combine with the `/hooks` panel's security confirmation mechanism to ensure all hooks are reviewed before running.
+6. **Work with MCP tools**: MCP tool names follow the pattern `mcp__<server>__<tool>` and can be batch-controlled in `matcher` using regex, e.g., `mcp__github__.*`.
+7. **The panel is the authoritative entry point**: Any external file modifications need to be confirmed in the panel before taking effect; be sure to complete this step.
+8. **Python script invocation**: Always use `python3 your_script.py` instead of directly executing `.py` files, because the Windows Git Bash environment may not correctly recognize the shebang line of Python scripts.
+9. **Windows compatibility**: Hook commands are executed via Git Bash on Windows. Ensure commands use bash syntax and avoid relying on cmd.exe or PowerShell-specific syntax.
+
+## Learn More
+
+* For reference documentation on hooks, see the [Hook Reference Guide](./hooks.md).
+* For comprehensive security best practices and safety guidelines, see [Security Considerations](./hooks.md#security-notes) in the Hook Reference Guide.
+* For troubleshooting steps and debugging techniques, see the [Debugging](./hooks.md#debugging) section in the Hook Reference Guide.
+
+---
 
 Now you've mastered the core workflow for enabling hooks in CodeBuddy Code. For more details on event fields, decision control, and security considerations, check out the [Hook Reference Guide](./hooks.md). Happy building powerful and secure automated workflows!

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

@@ -289,9 +289,9 @@ The LLM must return JSON:
 | `UserPromptSubmit` | User message submitted<br/>*(internal commands excluded)* | No | Content review, context injection |
 | `Stop` | Main agent reply finishes | No | Force continuation, add reminders |
 | `SubagentStop` | Sub-agent (Task tool) completes | No | Extend or annotate sub-tasks |
-| `PreCompact` | Before context compaction | Yes <br/>(`manual` <br/>/ `auto`) | Preserve key info, avoid lossy compression |
-| `SessionStart` | Session creation or resume | Yes <br/>(`startup` <br/>/ `resume` <br/>/ `clear` <br/>/ `compact`) | Env bootstrap, variable injection |
-| `SessionEnd` | Session terminated | Yes <br/>(`clear` <br/>/ `logout` <br/>/ `prompt_input_exit` <br/>/ `other`) | Cleanup, log persistence |
+| `PreCompact` | Before context compaction | Yes (`manual` / `auto`) | Preserve key info, avoid lossy compression |
+| `SessionStart` | Session creation or resume | Yes (`startup` / `resume` / `clear` / `compact`) | Env bootstrap, variable injection |
+| `SessionEnd` | Session terminated | Yes (`clear` / `logout` / `prompt_input_exit` / `other`) | Cleanup, log persistence |
 
 ### PreToolUse
 
@@ -318,10 +318,10 @@ Runs when CodeBuddy emits a notification. Matchers filter by notification type.
 
 **Supported matchers (partial):**
 
-- `permission_prompt` – Permission dialogs
-- `idle_prompt` – Idle > 60 seconds
+- `permission_prompt` – Permission requests from CodeBuddy Code
+- `idle_prompt` – When CodeBuddy is waiting for user input (after idle > 60 seconds)
 - `auth_success` – Auth success notification
-- `elicitation_dialog` – MCP tool elicitation dialogs (not yet supported)
+- `elicitation_dialog` – When CodeBuddy Code needs MCP tool–elicited input (not yet supported)
 
 Example:
 
@@ -566,6 +566,8 @@ Write structured JSON to stdout for granular control.
 
 #### Common JSON Fields
 
+All hook types may include these optional fields:
+
 ```jsonc
 {
   "continue": true,        // Whether CodeBuddy proceeds after the hook (default true)
@@ -598,9 +600,9 @@ PreToolUse hooks can control whether the tool call proceeds.
 }
 ```
 
-- `allow` – Skip the built-in permission dialog, execute tool directly
-- `deny` – Block the tool call, `permissionDecisionReason` is passed to Agent
-- `ask` – Force the UI to prompt the user, `permissionDecisionReason` is shown in the confirmation dialog
+- `"allow"` – Bypass the permission system and execute the tool directly
+- `"deny"` – Block the tool call, `permissionDecisionReason` is passed to Agent
+- `"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
@@ -798,7 +800,11 @@ Progress messages appear in transcript mode (Ctrl+R), showing:
 
 ## Agent / Skill Frontmatter Hooks
 
-In addition to hooks configured via the global `~/.codebuddy/settings.json`, you can declare a `hooks` field directly in the YAML frontmatter of a custom agent `.md` file or a skill's `SKILL.md`. These hooks only take effect during the lifecycle of the corresponding subagent or forked skill, and are automatically cleaned up when it ends.
+In addition to configuring hooks globally in `~/.codebuddy/settings.json`, you can declare a `hooks` field directly in the YAML frontmatter of a custom Agent's `.md` file or a Skill's `SKILL.md`. This way, hooks are distributed together with the Agent / Skill as an "atomic unit"; the scope automatically opens and closes with the subagent lifecycle, and does not pollute the main session.
+
+### Field Format
+
+The `hooks` field has exactly the same structure as in `settings.json` — grouped by event name, each event containing several `{matcher?, hooks[]}` configurations. The hook `type` supports four kinds: `command` / `prompt` / `agent` / `http`:
 
 ```yaml
 ---
@@ -815,13 +821,54 @@ hooks:
     - hooks:
         - type: command
           command: echo "reviewer finished"
+        - type: http
+          url: https://example.com/notify
+          method: POST
 ---
 ```
 
-- **Scoping**: Frontmatter hooks are only supported on skills when `context: fork` (the injection path lacks a clear lifecycle boundary and is not wired in).
-- **`Stop` auto-converted to `SubagentStop`**: `Stop` events written in an agent are converted to `SubagentStop` to align with subagent semantics.
-- **Safety gate (disabled by default)**: For security reasons, frontmatter hooks from **non-product-builtin** sources are not registered by default. This includes user-local `.codebuddy/agents|skills/*.md` as well as agents/skills distributed via the plugin marketplace. To enable them, set `"allowUntrustedFrontmatterHooks": true` in `~/.codebuddy/settings.json`. Only product-builtin agents/skills are automatically allowed.
-- **Format tolerance**: Invalid hook definitions are silently dropped. Completely broken YAML produces a `Malformed YAML frontmatter in '<path>'` diagnostic in the logs.
+### Lifecycle and Scope
+
+- **Scope restriction**: Skills only support frontmatter hooks when `context: fork` (the injection path lacks a clear lifecycle boundary, so it is not wired in); custom Agents always support them.
+- **Auto register/cleanup**: When a subagent starts, frontmatter hooks are registered into `ScopedHookRegistry`, and are automatically deregistered when the subagent exits. Hooks only take effect for that subagent's own tool calls / lifecycle events.
+- **`Stop` → `SubagentStop` rewrite**: Writing a `Stop` event in the frontmatter is automatically rewritten as `SubagentStop` — the main session's `Stop` is not triggered when the subagent completes; writing `Stop` is intended to express "the subagent itself ends" semantics.
+- **Merged with global hooks**: Under the same event, frontmatter hooks **stack** (do not override) with `settings.json` / plugin `hooks/hooks.json`, and all are triggered in parallel.
+
+### Safety Gate (`allowUntrustedFrontmatterHooks`)
+
+Frontmatter hooks can silently trigger shell commands, so **frontmatter hooks from non-builtin sources are not registered by default**:
+
+| Source | Registered by default |
+| --- | --- |
+| Product-builtin Agent / Skill | ✅ Auto-allowed |
+| `.codebuddy/agents/*.md` (user/project local Agent) | ❌ Denied by default |
+| `.codebuddy/skills/SKILL.md` (user/project local Skill) | ❌ Denied by default |
+| Agent / Skill distributed via plugin marketplace | ❌ Denied by default |
+| Plugin `hooks/hooks.json` (not frontmatter) | ✅ Not subject to the gate |
+
+To enable, set the following in `~/.codebuddy/settings.json`:
+
+```json
+{
+  "allowUntrustedFrontmatterHooks": true
+}
+```
+
+When blocked by the gate, the CLI emits a warning:
+
+```
+[AgentTask] Frontmatter hooks from skill 'xxx' skipped
+(source not admin-trusted; enable `allowUntrustedFrontmatterHooks` in settings to allow)
+```
+
+### Fault Tolerance and Diagnostics
+
+- **Silently drop invalid definitions**: When a single hook does not match the schema, only that entry is skipped without affecting the rest of hooks parsing; the warning includes `event 'YYY' invalid: <detailed reason>` for easy debugging.
+- **Unknown event names**: Skipped with a warning (`unknown event 'XXX'`); does not invalidate the entire frontmatter.
+- **Completely broken YAML**: The log emits `Malformed YAML frontmatter in '<path>'`.
+- **Runtime debugging**: Launch with `CODEBUDDY_DEBUG=1` to see registration logs like `[ScopedHookRegistry] registered N hook config(s) for scope '<sessionId>' (...)`, confirming hooks are in place.
+
+> For a complete example of using frontmatter hooks in a Skill, see [Skills documentation – Configuring Hooks in a Skill](./skills.md#configuring-hooks-in-a-skill).
 
 ---
 

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

@@ -94,6 +94,17 @@ Plugin hooks respond to the same lifecycle events as user-defined hooks:
 - `prompt`: Uses an LLM to evaluate a prompt (use the `$ARGUMENTS` placeholder for context).
 - `agent`: Runs an agent validator with tools, for complex validation tasks.
 
+**Differences from Skill / Agent frontmatter hooks**:
+
+A plugin can carry hooks via two distinct paths:
+
+| Path | Scope | Safety gate |
+| --- | --- | --- |
+| `hooks/hooks.json` (described in this section) | Entire session (while the plugin is enabled) | Not subject to `allowUntrustedFrontmatterHooks`; takes effect as soon as the plugin is enabled |
+| `hooks` frontmatter in `agents/*.md` or `skills/SKILL.md` | Only within that subagent / fork skill lifecycle | Subject to the `allowUntrustedFrontmatterHooks` gate, denied by default; users must explicitly enable it in `settings.json` |
+
+Because frontmatter hooks are intercepted by the safety gate, plugin-distributed Skills / Agents that rely on frontmatter hooks to function correctly should clearly notify users in the plugin README to enable the `allowUntrustedFrontmatterHooks` setting. See [Hook Reference Guide - Frontmatter Hooks](./hooks.md#agent--skill-frontmatter-hooks) for details.
+
 ### 4. MCP Servers
 
 Plugins can bundle Model Context Protocol (MCP) servers to connect CodeBuddy with external tools and services.