@tencent-ai/agent-sdk 0.3.169 → 0.3.171

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

@@ -0,0 +1,15 @@
+# 🚀 CodeBuddy Code v2.103.3 发布
+
+## 📦 版本信息
+
+| 组件 | 版本 |
+|------|------|
+| CodeBuddy Code CLI | v2.103.3 |
+| Agent SDK JS | v0.3.168 |
+| Agent SDK Python | v0.3.167 |
+
+## 🐛 问题修复
+
+- **自定义模型认证错误识别**：自定义模型 API key 失效（401/403）不再被误判为平台登录失效，避免出现"重新登录"弹窗中断会话
+- **会话历史重放稳定性**：会话被中断（如强退、崩溃）后再打开，未收尾的工具调用现在正确渲染为「已取消」状态，而非消失或显示为不可本地化的文本；仍存活的待答问题不再被误判为孤儿调用，保留正常交互能力
+- **OTel metrics 稳定性**：回滚此前的 metrics 修复改动，恢复稳定的遥测行为，避免主线回归

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

@@ -0,0 +1,13 @@
+# 🚀 CodeBuddy Code v2.103.4 发布
+
+## 📦 版本信息
+
+| 组件 | 版本 |
+|------|------|
+| CodeBuddy Code CLI | v2.103.4 |
+| Agent SDK JS | v0.3.169 |
+| Agent SDK Python | v0.3.168 |
+
+## 🔧 改进优化
+
+- **帮助优化模型开关**：新增 `enableModelOptimization` 全局设置项，可控制是否参与模型优化。开启后请求会携带相应标识，自定义模型不发送该标识，让你对数据使用范围拥有更明确的掌控。

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

@@ -0,0 +1,281 @@
+# Dynamic Workflows：用脚本编排成规模的子代理
+
+> Dynamic Workflows 让 CodeBuddy 写一段 JavaScript 编排脚本，由运行时在后台调度数十甚至数百个子代理协作完成任务。脚本本身可读、可改、可重跑，适合代码库审计、大型迁移、需要交叉验证的研究类任务。
+
+<Note>
+Dynamic Workflows 目前为研究预览阶段，要求 CodeBuddy Code v2.1.154 或更高版本。在 `/config` 中通过 "Dynamic workflows" 开关启用。
+</Note>
+
+Dynamic Workflow 是一段由 CodeBuddy 为你的任务现场编写的 JavaScript 脚本，运行时在后台执行它，你的会话保持响应。脚本里包含一个或多个 [`agent()`](#脚本-api) 调用，每次调用都派出一个独立的子代理工作；脚本拿到中间结果后，可以分支、可以并行、可以再投递给下一批子代理。
+
+当一项任务大到一个会话装不下，或者你希望编排逻辑被记录成"可重跑的脚本"时，就该用 Workflow。典型场景：
+
+- 全代码库的 Bug 巡检
+- 跨 500 个文件的迁移
+- 一个需要从多源交叉印证的研究问题
+- 一个值得从多个独立角度先草拟、再对比择优的复杂方案
+
+本页介绍：
+
+- [何时该用 Workflow](#何时该用-workflow)（与子代理 / Skills / Agent Teams 的取舍）
+- [运行内置 Workflow](#运行内置-workflow)：`/deep-research`
+- [让 CodeBuddy 为你的任务写一个 Workflow](#让-codebuddy-写-workflow)，并保存复用
+- [Workflow 的运行机制](#workflow-的运行机制) 与 [运行管理](#运行管理)
+
+## 何时该用 Workflow
+
+[子代理](sub-agents.md)、[Skills](skills.md)、[Agent Teams](agent-teams.md) 与 Workflows 都能跑多步任务，差别在于"谁握着计划"：
+
+|                       | 子代理                       | Skills                    | Agent Teams                       | Workflows                       |
+| :-------------------- | :--------------------------- | :------------------------ | :-------------------------------- | :------------------------------ |
+| 本质                  | CodeBuddy 派出去的工人       | CodeBuddy 遵循的指令      | 一个领导监管一组同侪会话          | 运行时执行的一段脚本            |
+| 谁决定下一步做什么    | CodeBuddy，逐轮决策          | CodeBuddy，按提示执行     | 领导代理，逐轮决策                | 脚本                            |
+| 中间结果存在哪        | CodeBuddy 的上下文窗口       | CodeBuddy 的上下文窗口    | 共享任务列表                      | 脚本变量                        |
+| 可重复的是什么        | 工人定义                     | 指令本身                  | 团队定义                          | 编排过程本身                    |
+| 规模                  | 每轮少量委派                 | 同子代理                  | 几位长任务的同侪                  | 单次运行数十到数百个代理        |
+| 中断                  | 重新开一轮                   | 重新开一轮                | 队友继续跑                        | 在同一会话内可恢复              |
+
+Workflow 把"计划"挪进了代码。子代理 / Skills / Agent Teams 的编排者都是 CodeBuddy，每一轮它都要决定下一步派谁、做什么，所有结果都落进上下文窗口；而 Workflow 把循环、分支、中间结果都交给脚本本身管理，CodeBuddy 的上下文里只剩**最终答案**。
+
+把计划变成代码还有第二个好处：你可以让脚本应用一种**重复可执行的质量模式**，而不只是单纯多派代理。比如让若干代理对彼此的发现做对抗式互评再上报、或者从多个角度同时起草方案再相互对比择优 —— 单次结果的可信度会比"一遍过"高得多。
+
+## 运行内置 Workflow
+
+最快感受 Workflow 的方式是跑 `/deep-research`，这是 CodeBuddy Code 内置的"多源交叉印证研究"工作流。会话里你会看到代理在后台分阶段推进，跑完后只拿到一份合成报告，而不是一长串逐轮对话。
+
+### 步骤
+
+1. **发起 Workflow**
+
+   带一个想调研的问题运行 `/deep-research`。它会从多个角度并行搜索、抓取并交叉印证来源，最终合成一份带引用的报告。
+
+   ```text
+   /deep-research Node.js 的 permission model 在 v20 到 v22 之间有什么变化？
+   ```
+
+2. **批准运行**
+
+   CodeBuddy Code 会询问是否允许此 Workflow 运行。选择 **Yes** 继续。具体提示取决于你的[权限模式](iam.md#权限系统)。详见 [运行前批准计划](#运行前批准计划)。
+
+3. **观察进度**
+
+   运行在后台启动。`/workflows` 打开 Workflows 视图，方向键选中本次 run，回车进入进度页：
+
+   ```text
+   /workflows
+   ```
+
+   进度页按"阶段（phase）"展示，每个阶段标注代理数量、Token 总量与已耗时。下钻进任意阶段可以看每个代理的提示与产出。完整快捷键见 [观察运行](#观察运行)。
+
+   你也可以从输入框下方的任务面板里直接看到一行进度摘要。按方向键 ↓ 把焦点切到任务面板，回车展开。
+
+4. **阅读报告**
+
+   运行结束后，报告自动落回会话。每一条主张都标注了引用来源，未通过交叉印证的主张会被剔除。
+
+要把 Workflow 应用到你自己的任务，先 [让 CodeBuddy 写一个](#让-codebuddy-写-workflow)；当某次运行结果令人满意，可以把它[保存为命令](#保存-workflow-以便复用)。
+
+### 内置 Workflow
+
+CodeBuddy Code 内置如下 Workflow：
+
+| 命令                          | 作用                                                                                                                                                                                                              |
+| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/deep-research <问题>`       | 多角度并行搜索、抓取并交叉印证来源，对每条主张投票，剔除未通过印证的部分，输出一份带引用的报告。需要 [WebSearch 工具](tools-reference.md#websearch-tool-behavior) 可用。                                            |
+
+[你自己保存的 Workflow](#保存-workflow-以便复用) 会以同样方式注册成命令，在 `/` 自动补全里与内置 Workflow 一同出现。
+
+### 观察运行
+
+Workflow 在后台运行，会话保持响应。任何时候 `/workflows` 都能列出活跃 / 已完成的 run，选中后进入进度视图。
+
+```text
+/workflows
+```
+
+进度视图按阶段展示，每个阶段标注代理数量、Token 总量、已耗时。底部状态栏列出全部快捷键：
+
+| 按键          | 作用                                                                                              |
+| :------------ | :------------------------------------------------------------------------------------------------ |
+| `↑` / `↓`     | 选中阶段或代理                                                                                    |
+| `Enter` 或 `→` | 下钻到所选阶段，再下钻到代理可读其提示、最近的工具调用与最终结果                                  |
+| `Esc`         | 回退一级                                                                                          |
+| `j` / `k`     | 在代理详情溢出时滚动                                                                              |
+| `p`           | 暂停或恢复运行                                                                                    |
+| `x`           | 中止所选代理；焦点在 run 上时中止整个 Workflow                                                    |
+| `r`           | 重启所选的运行中代理                                                                              |
+| `s`           | 把当前 run 的脚本[保存](#保存-workflow-以便复用)为命令                                            |
+
+## 让 CodeBuddy 写 Workflow
+
+让 CodeBuddy 为你的任务写 Workflow，有两种方式：
+
+- [在提示里直接要 Workflow](#在提示里要-workflow)：用自然语言或者关键词 `ultracode`，CodeBuddy 会为这个任务写一份。
+- [让 CodeBuddy 自己决定（ultracode 模式）](#ultracode-模式让-codebuddy-自己决定)：`/effort ultracode` 把 effort 等级设到 ultracode，会话里的每一个有分量的任务 CodeBuddy 都会先规划成 Workflow。
+
+也可以直接运行已有的 Workflow 命令：内置如 `/deep-research`，或你[保存](#保存-workflow-以便复用)过的。
+
+### 在提示里要 Workflow
+
+不想改会话整体 effort 等级，只想让某次任务走 Workflow，在提示里加上关键词 `ultracode`。用自然语言说"用一个 workflow 跑这个"或者 "use a workflow"，效果一样：CodeBuddy 把直接请求当作同等的显式 opt-in。
+
+```text
+ultracode：审计 src/routes/ 下每个 API 端点是否漏了鉴权检查
+```
+
+CodeBuddy Code 会高亮你输入里的关键词，CodeBuddy 收到这个提示后，会为该任务写一段 Workflow 脚本，而不是逐轮地展开工作。如果你不想触发 Workflow，按 macOS 的 `Option+W`、Windows / Linux 的 `Alt+W` 取消本次提示的高亮；或者光标停在关键词后面按 Backspace 删掉它即可。要彻底关闭关键词触发，到 `/config` 关掉 "Ultracode keyword trigger"。
+
+如果运行结果满足需要，事后可以把它[保存为命令](#保存-workflow-以便复用)。
+
+如果你已经有用其他方式搭好的编排器（一个子代理提示词文件夹、或一个分发任务的 Skill），可以让 CodeBuddy 看一下并写一段等价的 Workflow。
+
+### Ultracode 模式：让 CodeBuddy 自己决定
+
+Ultracode 是 CodeBuddy Code 的一个组合配置：把 [推理强度](models.md#调整推理强度) 推到 `xhigh`，并叠加自动 Workflow 编排。开启后，CodeBuddy 会主动判断哪些任务值得走 Workflow，不必你每次提醒。
+
+```text
+/effort ultracode
+```
+
+进入 ultracode 后，一个请求可能被拆成连续多个 Workflow：先一个 run 摸代码现状、再一个 run 实施改动、再一个 run 验证。会话里**每个**任务都按这个模式跑，每条请求消耗的 Token 会比低 effort 等级显著更多、耗时也更长。
+
+ultracode 仅在当前会话生效，新开会话自动重置。回到日常工作时用 `/effort high` 回退即可。它仅在支持 `xhigh` [推理强度](models.md#调整推理强度) 的模型上可用；不支持的模型上 `/effort` 菜单不会展示该选项。
+
+### 运行前批准计划
+
+CLI 里，每次启动都会弹出运行前确认：
+
+- **Yes, run it**：开始运行
+- **Yes, and don't ask again for `<name>` in `<path>`**：开始运行，并对该项目内同名 Workflow 不再询问
+- **View raw script**：先读脚本再决定
+- **No**：取消
+
+`Ctrl+G` 在你的编辑器里打开脚本；`Tab` 可以在运行前调整提示。
+
+是否会出现这个询问，取决于你的 [权限模式](permission-modes.md)：
+
+| 权限模式                                   | 何时询问                                                                                                                          |
+| :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
+| Default、Accept edits                      | 每次都询问；除非你为该 Workflow 在该项目下选过 **Yes, and don't ask again**                                                       |
+| Auto                                       | 只在首次启动时询问；任何 **Yes** 都会写入用户设置，后续直接启动。ultracode 开启时整个询问被跳过                                   |
+| Bypass permissions、`codebuddy -p`、Agent SDK | 永不询问，运行直接开始                                                                                                            |
+
+权限模式只影响**启动前**这个询问。Workflow 派出去的子代理始终在 `acceptEdits` 模式下跑，并继承你的[工具白名单](settings.md#permission-settings)，与你会话当前模式无关。文件改动是自动批准的。
+
+不在白名单里的 Shell 命令、Web Fetch、MCP 工具调用，仍可能在运行中弹询问。要避免长任务被打断，启动前把代理需要的命令加进白名单。
+
+`codebuddy -p` 与 Agent SDK 没有人机交互入口，工具调用按你配置的权限规则执行，没有交互式确认。
+
+### 保存 Workflow 以便复用
+
+当一段 Workflow 是你会反复跑的（比如每个分支都要做一遍的 review 流程），可以把它的脚本保存为命令。
+
+`/workflows` 选中要保留的 run，按 `s`，在保存对话里 `Tab` 切换两个保存位置：
+
+- 项目下 `.codebuddy/workflows/`：随仓库分发，团队所有人都看得到
+- 用户目录 `~/.codebuddy/workflows/`：在所有项目都可用，仅你可见
+
+回车保存。之后在任意会话里通过 `/<name>` 调用。
+
+如果项目级和用户级 Workflow 重名，**项目级**优先。
+
+### 给已保存的 Workflow 传参
+
+保存的 Workflow 通过 `args` 接收输入。脚本里它是一个名为 `args` 的全局变量。这样不必每次改脚本就能传研究问题、目标路径列表、配置对象等。
+
+下面这段提示触发一个保存的 Workflow，并把 issue 列表作为参数传入：
+
+```text
+> 用 /triage-issues 跑一下 issue 1024、1025、1030
+```
+
+CodeBuddy 把列表作为结构化数据传入，脚本可以直接对 `args` 用数组 / 对象方法，无需自己解析。如果调用方没传 `args`，脚本里 `args` 是 `undefined`。
+
+## Workflow 的运行机制
+
+运行时在一个隔离环境里执行脚本，与你的会话完全分离。中间结果留在脚本变量里，不会落进 CodeBuddy 的上下文。
+
+每次 run 都会把脚本写到会话目录（`~/.codebuddy/projects/<session>/`）下的一个文件里。CodeBuddy 在 run 启动时拿到该路径，所以你可以问它"脚本在哪"。打开它可以读 CodeBuddy 写的编排逻辑、和上一次 run 做 diff、或者编辑后让 CodeBuddy 用编辑后的版本重新启动。
+
+运行时持续记录每个代理的结果，这就是同一会话内 run [可恢复](#恢复-pause-后的-run) 的基础。
+
+### 行为与限制
+
+运行时施加以下约束：
+
+| 约束                                                                 | 原因                                                                                                                       |
+| :------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
+| 运行中不接受用户输入                                                 | 唯一能让 run 暂停的是代理的权限询问。若需要阶段间签字确认，把每个阶段拆成独立 Workflow                                     |
+| Workflow 自身没有直接的文件系统 / Shell 访问能力                     | 文件读写、执行命令一律由代理完成；脚本只负责协调代理                                                                       |
+| 同时最多 16 个并发代理（CPU 核数少的机器上更少）                     | 限制本地资源消耗                                                                                                           |
+| 单次 run 最多 1000 个代理                                            | 防止脚本失控的循环                                                                                                         |
+
+### 确定性沙箱
+
+运行时强制确定性，避免同一脚本两次跑出不同结果（也是 [resume 缓存命中](#恢复-pause-后的-run) 的前提）。沙箱拒绝以下不确定性 / 任意代码生成 API（编译期扫描 + 运行时拦截）：
+
+- 时间相关：`Date.now()`、`new Date()`、`performance.now()`
+- 随机数：`Math.random()`
+- 任意代码生成：动态字符串求值与动态 Function 构造（沙箱关闭了 `codeGeneration.strings`）
+- Node 全局：沙箱里看不到 `require` / `process` / `__dirname` / `Buffer`
+
+需要时间戳或随机数时，用 `agent()` 让子代理拉取真实信息（搜索、读文件、调 API），把不确定性"装进"代理的结果里。
+
+### 脚本 API
+
+脚本是一个自包含的 JavaScript 模块，可以使用以下全局函数：
+
+| 全局                          | 作用                                                                                                                                  |
+| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
+| `agent(prompt, options?)`     | 派一个子代理执行 `prompt`；返回它的结果。`options` 可指定 `tools` / `maxTurns` / `schema`（结构化输出）/ `model` 等                   |
+| `parallel(items, options?)`   | 对 `items` 并行 fan-out，等同于 `Promise.all`，但受 16 个并发上限约束                                                                 |
+| `pipeline(items, options?)`   | 顺序串联，前一段的结果传给下一段；任一段失败时其余段返回 `null`                                                                        |
+| `phase(name, body)`           | 把一段编排标注成一个阶段，进度视图里会按阶段聚合显示。`body` 可以是同步或异步函数                                                     |
+| `log(...)`                    | 写一条带时间戳的日志，会出现在进度视图的 Run log 里                                                                                   |
+| `args`                        | 调用方传入的参数（见 [给已保存的 Workflow 传参](#给已保存的-workflow-传参)）                                                           |
+| `workflow(name, args?)`       | 嵌套调用一个**已保存**的 Workflow（仅父级可调用，子级不再暴露此 hook，禁止深度嵌套）                                                    |
+
+更多模式见 [`build/patches/cli-saas/templates/workflow-tool-description.tpl`](../../../build/patches/cli-saas/templates/workflow-tool-description.tpl) 与 [`workflow-subagent-system-preamble.tpl`](../../../build/patches/cli-saas/templates/workflow-subagent-system-preamble.tpl)。
+
+## 运行管理
+
+run 一旦启动，从 `/workflows` 视图管理；也可以展开输入框下方任务面板里的进度行。
+
+### 恢复 pause 后的 run
+
+如果你停下了一个 run，可以再恢复：已经完成的代理直接返回缓存结果，剩余部分继续跑。`/workflows` 选中已暂停的 run 按 `p` 恢复；也可以让 CodeBuddy 用同一脚本重启 run。
+
+恢复仅限**同一 CodeBuddy Code 会话内**。如果你退出了 CodeBuddy Code 时 Workflow 还在跑，下次会话会从头开始。
+
+### 成本
+
+Workflow 会派出大量代理，因此一次 run 的 Token 消耗可能远高于以对话方式做同样的任务。这些消耗按你套餐的限额计入。
+
+要在动手做大任务前估成本，先在小切片上跑一遍：一个目录而不是整个 repo，一个具体问题而不是宽泛主题。`/workflows` 视图里每个代理的 Token 用量实时可见，随时可以 `x` 中止 run 而不丢已完成的结果。运行时的 [代理上限](#行为与限制) 也限制了一次 run 能消耗的最大代价，避免脚本写错时跑飞。
+
+每个代理默认沿用会话当前的模型；如果脚本显式给某阶段路由到了别的模型则不同。控制成本可以从几个方面入手：
+
+- 大任务前 `/model` 检查一遍当前模型，如果你平时切到便宜模型，注意切回来或维持
+- 描述任务时主动告诉 CodeBuddy："对不需要最强模型的阶段用更便宜的模型"
+
+### 关闭 Workflow
+
+Workflow 在 CLI、桌面端、IDE 扩展、`codebuddy -p` 非交互模式与 [Agent SDK](sdk.md) 都可用，关闭方式在所有形态下一致。
+
+仅对自己关闭：
+
+- `/config` 里把 "Dynamic workflows" 关掉。会持久化到设置
+- `~/.codebuddy/settings.json` 设 `"disableWorkflows": true`，会持久化
+- 设环境变量 `CODEBUDDY_DISABLE_WORKFLOWS=1`，启动时读取，在哪儿设就在哪儿生效
+
+为整个组织关闭：在 [托管设置](settings.md#enterprise-managed-policy-settings) 里设 `"disableWorkflows": true`。
+
+关闭后，内置 Workflow 命令不可用，关键词 `ultracode` 不再触发，`/effort` 菜单也不再展示 ultracode 选项。
+
+## 相关资源
+
+- [子代理](sub-agents.md)：Workflow 编排的底层"工人"原语
+- [Agent Teams](agent-teams.md)：另一种多代理协作形态，由领导代理管计划
+- [Skills 技能系统](skills.md)：把"指令"沉淀成可复用 Skill
+- [推理强度调整（含 ultracode）](models.md#调整推理强度)
+- [Hooks 钩子系统](hooks-guide.md)：在工具调用与会话事件上挂钩子

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

@@ -0,0 +1,260 @@
+# Permission Modes
+
+> Controls whether CodeBuddy should stop and ask before editing files, running commands, or making network requests. The mode determines the pace of the entire session: conservative modes require approval step by step, while more permissive modes let CodeBuddy continue for longer without interruption and report back at the end. Use strict modes for sensitive operations, and permissive modes when you trust the direction.
+
+## Available Modes
+
+All modes actually defined by CodeBuddy Code in the `src/node/settings/settings-protocol.ts::PermissionMode` enum are listed below. The first four are directly exposed to CLI users, and the remaining modes are for programmatic or integration scenarios.
+
+### Modes You Can Switch Manually
+
+| Mode                                                         | What can run without asking                                                                                   | Use case                                                    |
+| :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------- |
+| `default`                                                    | Read tool inside trusted directories                                                                          | Default; suitable for sensitive work / getting started       |
+| [`acceptEdits`](#acceptedits-auto-approve-file-edits)        | Read + Edit-family tools inside trusted directories                                                           | Keep writing, then review with git diff                     |
+| [`plan`](#plan-explore-before-changing)                      | Delegates to the mode active before entering plan (default = `default`); additionally allows writing session plan files | Explore the code before deciding what to change              |
+| [`bypassPermissions`](#bypasspermissions-skip-all-checks)    | All tools, without asking                                                                                     | Use only in sandbox containers / VMs / offline dev containers |
+| [`delegate`](#delegate-multi-agent-coordination-mode)        | Coordination tools only (such as Agent / TaskCreate / SendMessage / team management); implementation tools are blocked by the assembly layer | The main agent only decomposes and delegates work to subagents |
+
+### Programmatic / Integration Modes (Not in the Shift+Tab Cycle)
+
+| Mode            | When it appears                                                                                                                   |
+| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
+| `fullAccess`    | Passed by an ACP client (IDE integration) through the protocol; semantically equivalent to globally allowing everything like `bypassPermissions` (see `sandbox-orchestrator.ts:946`) |
+| `work`          | Passed by an ACP client. Read is allowed directly (without checking trusted directories), Edit always asks, Bash allows only safe commands directly, and other tools ask |
+| `ignore`        | Only takes effect for subagents / teammates. It means “use the main session’s mode; do not let the subagent’s own frontmatter override it”. Main sessions do not use it |
+
+## Switching Permission Modes
+
+You do not switch modes by telling CodeBuddy in chat. Set them through the following three entry points instead.
+
+### Switch During a Session: Shift+Tab
+
+In the CLI, press `Shift+Tab` to cycle through the following five modes (order defined in `input-hint-box.tsx:72`):
+
+```
+default → bypassPermissions → acceptEdits → plan → delegate → default → ...
+```
+
+After switching, the current mode is shown in the lower-left status bar:
+
+| Mode                 | Status bar text                              | Color                                |
+| :------------------- | :------------------------------------------- | :----------------------------------- |
+| `default`            | Not shown                                    | —                                    |
+| `bypassPermissions`  | `⏵⏵ bypass permissions on (shift+tab to cycle)` | warning                       |
+| `acceptEdits`        | `⏵⏵ accept edits on (shift+tab to cycle)`       | info                          |
+| `plan`               | `⏸ plan mode on (shift+tab to cycle)`           | planMode                      |
+| `plan` + pre-mode    | `⏸ plan + accept edits (shift+tab to cycle)` and similar | planMode              |
+| `delegate`           | `⇢ delegate mode on (shift+tab to cycle)`        | delegateMode                  |
+
+### Specify at Startup: `--permission-mode`
+
+```bash
+codebuddy --permission-mode plan
+codebuddy --permission-mode acceptEdits
+codebuddy --permission-mode bypassPermissions
+codebuddy --permission-mode default
+```
+
+The CLI option `--permission-mode` accepts only these four literals (see `cli-provider.ts:36`). Other modes (`delegate` / `work` / `fullAccess` / `ignore`) cannot be passed on the command line.
+
+It also works under `-p` ([headless mode](headless.md)):
+
+```bash
+codebuddy -p --permission-mode acceptEdits "refactor src/utils/foo.ts"
+```
+
+You can also add the following at startup:
+
+- `-y` / `--dangerously-skip-permissions`: equivalent to `--permission-mode bypassPermissions`; skips all permission checks (see `cli-provider.ts:35`)
+
+### Persistent Default: `defaultMode`
+
+Write it to `~/.codebuddy/settings.json` or repository `.codebuddy/settings.json`:
+
+```json
+{
+  "permissions": {
+    "defaultMode": "acceptEdits"
+  }
+}
+```
+
+If `--permission-mode` is also provided at startup, the CLI argument takes precedence (see the fallback chain in `stream-json-view.ts:525`: `current session value → permissions.defaultMode → PermissionMode.Default`).
+
+### Automatic Memory of the “Pre-Plan Mode”
+
+When entering `plan`, CodeBuddy saves the current mode to `session.meta.prePlanPermissionMode` and restores it when leaving plan. This means:
+
+- If you press `Shift+Tab` from `acceptEdits` into `plan`, the approval strategy for Read/Edit/Bash during plan still follows `acceptEdits` rules (except for the plan file, which never asks)
+- When leaving plan, you return to `acceptEdits`; it will not be forcibly dropped to `default`
+
+The implementation is `delegateToPrePlanStrategy` in `tool-permission-strategy.ts:92`.
+
+## Detailed Semantics by Mode
+
+### default (Default)
+
+A step-by-step approval mode. This is the safe option for beginners and for sensitive work.
+
+| Tool type | Decision                                                                                            |
+| :-------- | :-------------------------------------------------------------------------------------------------- |
+| Read      | Path is inside a trusted directory (cwd + `permissions.additionalDirectories` + user-added `addDir`) → allow; otherwise ask |
+| Edit      | Always ask                                                                                          |
+| Bash      | Always ask                                                                                          |
+| Other     | Always ask                                                                                          |
+
+### acceptEdits (Auto-Approve File Edits)
+
+Suitable when you want to keep writing and review the diff later, without being interrupted by every Edit approval prompt.
+
+| Tool type | Decision                                                                                            |
+| :-------- | :-------------------------------------------------------------------------------------------------- |
+| Read      | Inside trusted directories → allow; otherwise ask                                                   |
+| Edit      | **Always allow**                                                                                    |
+| Bash      | Always ask                                                                                          |
+| Other     | Always ask                                                                                          |
+
+Notes:
+
+- Only **Edit-family tools** are auto-approved (Edit / Write / NotebookEdit, etc.). This does not affect Bash — Bash always follows a separate safety classification (`command-utils.ts::checkCommandSafety`)
+- “Trusted directories” are based on the workspace root + user-configured `permissions.additionalDirectories` + startup `--add-dir` (see `permission-utils.ts:561`)
+- Writes to [protected files](#protected-critical-files) still ask according to the original mode and do not use automatic allow
+
+### plan (Explore Before Changing)
+
+In plan mode, CodeBuddy focuses on reading code and running read-only Bash commands to investigate, writes the proposal as a plan, and then comes back for your approval. It does not apply changes to your source code.
+
+See `tool-permission-strategy.ts:75` for the implementation idea — plan mode is not an independent “fully read-only block”; it **delegates to the pre-plan mode**:
+
+- Read: delegates the decision to the pre-plan mode (default is `default`)
+- Edit: first checks whether the target path is the current session’s **plan file** (`PlanStorageService.getPlanFilePath`) → if yes, allow; otherwise delegate to the pre-plan mode
+- Bash: delegates to the pre-plan mode
+- Enter plan through `Shift+Tab` or the `EnterPlanMode` tool; exit through another `Shift+Tab` or `ExitPlanMode` (see `enter-planmode-tool.ts:94` and `exit-planmode-tool.ts:73`)
+
+Start directly in plan mode:
+
+```bash
+codebuddy --permission-mode plan
+```
+
+### bypassPermissions (Skip All Checks)
+
+Literally: **skip all approvals**. All Bash, Edit, network, and MCP operations execute immediately. Use only in the following scenarios:
+
+- Isolated containers / VMs / dev containers
+- Sandboxes with no external network access
+- Scripted scenarios where you fully understand the consequences
+
+Startup methods:
+
+```bash
+codebuddy --permission-mode bypassPermissions
+# Equivalent
+codebuddy -y
+codebuddy --dangerously-skip-permissions
+```
+
+#### Disable Channel (Administrators)
+
+Write `permissions.disableBypassPermissionsMode: "disable"` to settings at any layer:
+
+```json
+{
+  "permissions": {
+    "disableBypassPermissionsMode": "disable"
+  }
+}
+```
+
+After this is written, even if the session switches to `bypassPermissions`, the permission strategy will **fall back to `default` decisions** (see `tool-permission-strategy.ts:192`). If any layer of settings disables it, it takes effect (user / project / local / cli flagSettings with any layer set to `"disable"`; see `tool-permission-service.ts:670`).
+
+### delegate (Multi-Agent Coordination Mode)
+
+In `delegate` mode, the main agent can **only coordinate**: assign tasks, start subagents, and communicate across members. It does not edit files or run commands itself.
+
+Implementation idea:
+
+- The assembly layer (tool-manager) removes “implementation tools” (Read/Write/Edit/Bash, etc.) from the main agent’s available tool set
+- By the time execution reaches the `delegate` strategy layer (`tool-permission-strategy.ts:244`), only coordination tools remain (Agent / TaskCreate / SendMessage, etc.), and they are all allowed automatically
+
+This is suitable when you explicitly want the main agent to “plan only, with specialized subagents doing the implementation” ([Agent Teams](agent-teams.md) / [Subagents](sub-agents.md)).
+
+Press `Shift+Tab` until `delegate` appears to enter it.
+
+### work (IDE Integration)
+
+Set by the ACP client (IDE extension) through the protocol (see `acp-agent.ts:3407`), and not directly exposed to CLI users. Semantics:
+
+| Tool type | Decision                                                                            |
+| :-------- | :---------------------------------------------------------------------------------- |
+| Read      | **Allow directly** (does not check trusted directories)                              |
+| Edit      | Always ask                                                                          |
+| Bash      | Safe commands (marked by `checkCommandSafety` as `isSafe && !requiresApproval`) are allowed; others ask |
+| Other     | Allow                                                                               |
+
+### fullAccess (IDE Integration)
+
+Only passed through the ACP protocol; same semantics as `bypassPermissions` (the sandbox orchestrator short-circuits it together with `BypassPermissions`, see `sandbox-orchestrator.ts:946`).
+
+### ignore (Subagent Only)
+
+Only used by subagent frontmatter / options. When a subagent writes `permissionMode: ignore` in its metadata, agent-task assembly treats it as “do not override the parent agent’s mode” and continues using the parent session’s current mode (see `agent-task.ts:1009`). This value does not appear in main sessions.
+
+## Protected Critical Files
+
+Write operations to the following paths retain special handling even under `acceptEdits` / `bypassPermissions` (aligned with cc):
+
+- Repository itself: `.git`, `.gitconfig`, `.gitmodules`
+- Shell config: `.bashrc` / `.bash_profile` / `.zshrc` / `.zprofile` / `.envrc`, etc.
+- Package management: `.npmrc` / `.yarnrc` / `.pnpmfile.cjs` / `bunfig.toml`, etc.
+- IDE / tools: `.vscode` / `.idea` / `.husky` / `.devcontainer` / `.cargo` / `.yarn` / `.mvn`
+- CodeBuddy itself: `.codebuddy` (except `.codebuddy/worktrees`)
+- MCP / config: `.mcp.json` / `.codebuddy.json`
+
+The exact list and decision logic are defined by `tool-permission-service.ts`.
+
+## Permission Mode Inheritance for Subagents
+
+Subagents ([Agent](sub-agents.md) tool calls and [Agent Teams](agent-teams.md) members) inherit the main session’s permission mode by default. To force an override at the team / project layer:
+
+```json
+{
+  "permissions": {
+    "subagentPermissionMode": "bypassPermissions"
+  }
+}
+```
+
+After this is written, all subagents run under `bypassPermissions` (implementation priority chain in `agent-task.ts:1009`). Notes:
+
+- Passing the `mode` parameter explicitly in an Agent tool call → **highest priority**, overrides this setting
+- Writing `permissionMode: ignore` in subagent frontmatter → still runs under the main session mode (not affected by this setting)
+
+## Working with Permission Rules
+
+Permission modes define the “baseline”. You can layer additional rules under `permissions` in `~/.codebuddy/settings.json` or repository `.codebuddy/settings.json`:
+
+```json
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": ["Bash(npm test)", "Read(/etc/hosts)"],
+    "ask": ["WebFetch"],
+    "deny": ["Bash(rm -rf *)", "Edit(.git/**)"]
+  }
+}
+```
+
+- The `allow` / `ask` / `deny` layers have higher priority than mode decisions (except that `bypassPermissions` skips the entire permission layer)
+- For detailed rule syntax, see [Settings](settings.md), [Security](security.md), and [IAM](iam.md)
+
+## Related Resources
+
+- [Agent Teams: Multi-Agent Collaboration](agent-teams.md): let the main agent focus on coordination in `delegate` mode
+- [Subagents](sub-agents.md): subagent tools and permission mode inheritance
+- [Hooks](hooks-guide.md): use `PreToolUse` hooks for custom allow / block behavior
+- [Bash sandboxing](bash-sandboxing.md): add filesystem / network isolation at the Bash command layer
+- [Settings](settings.md): complete fields for permission rules, trusted directories, `disableBypassPermissionsMode`, and more
+- [CLI reference](cli-reference.md): startup parameters such as `--permission-mode` / `-y` / `--add-dir`
+- [Headless mode](headless.md): use permission modes under the `-p` flow