# 权限模式

> 控制 CodeBuddy 在编辑文件、运行命令、发起网络请求前要不要先停下来询问。模式决定整段会话的节奏：保守模式逐次审批，宽松模式让 CodeBuddy 长时间不打断地推进、最后回报。敏感操作选严格、信任方向时选宽松。

## 可用模式

CodeBuddy Code 提供以下权限模式。前 4 个是用户可在 CLI 中直接切换或指定的；后几个用于 IDE 集成与子代理场景。

### 用户可手动切换的模式

| 模式                                                         | 不询问就能跑什么                                                                                              | 适用场景                                              |
| :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------- |
| `default`                                                    | 信任目录内的 Read 工具                                                                                        | 默认；适合敏感工作 / 上手期                            |
| [`acceptEdits`](#auto-edits自动批准文件编辑)                  | 信任目录内的 Read + Edit 系列工具                                                                             | 边写边走 git diff 复核                                |
| [`plan`](#plan探索后再改)                                     | 委托给"进入 plan 前"的那个模式（默认 = `default`）；额外允许写入会话计划文件                                  | 落手改动前先摸清代码再决定                            |
| [`bypassPermissions`](#bypasspermissions跳过所有检查)         | 全部工具，无询问                                                                                              | 沙箱容器 / VM / 离线 dev container 才用               |
| [`delegate`](#delegate多代理协调模式)                         | 仅协调类工具（如 Agent / TaskCreate / SendMessage / 团队管理），实现类工具被屏蔽                               | 主代理只做拆派、把执行交给子代理                      |

### 程序化 / 集成模式（不在 Shift+Tab 循环里）

| 模式            | 何时出现                                                                                                                          |
| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `fullAccess`    | IDE 客户端通过协议传入；语义上等价于 `bypassPermissions` 的全局放行                                                                 |
| `work`          | IDE 客户端传入。Read 直接放行（不查信任目录），Edit 一律询问，Bash 仅安全命令直接放行，其他询问                                     |
| `ignore`        | 仅在子代理（subagent / teammate）场景生效，表示"用主会话的模式，不要被子代理自己的 frontmatter 覆盖"；主会话用不到                  |

## 切换权限模式

模式不是用对话告诉 CodeBuddy 来切的，而是通过下面三个入口设置。

### 会话中切换：Shift+Tab

CLI 里按 `Shift+Tab` 在以下 5 个模式之间循环：

```
default → bypassPermissions → acceptEdits → plan → delegate → default → ...
```

切换后会话状态栏左下角会显示当前模式：

| 模式                 | 状态栏文案                              | 颜色                                |
| :------------------- | :-------------------------------------- | :---------------------------------- |
| `default`            | 不显示                                  | —                                   |
| `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` + 前置        | `⏸ plan + accept edits (shift+tab to cycle)` 等  | planMode                      |
| `delegate`           | `⇢ delegate mode on (shift+tab to cycle)`        | delegateMode                  |

### 启动时指定：`--permission-mode`

```bash
codebuddy --permission-mode plan
codebuddy --permission-mode acceptEdits
codebuddy --permission-mode bypassPermissions
codebuddy --permission-mode default
```

CLI 选项 `--permission-mode` 只接受这 4 个字面量。其他模式（`delegate` / `work` / `fullAccess` / `ignore`）不能在命令行传入。

`-p`（[非交互模式](headless.md)）下同样有效：

```bash
codebuddy -p --permission-mode acceptEdits "重构 src/utils/foo.ts"
```

启动时还可以追加：

- `-y` / `--dangerously-skip-permissions`：等价于 `--permission-mode bypassPermissions`，跳过全部权限检查

### 持久化默认值：`defaultMode`

写到 `~/.codebuddy/settings.json` 或仓库 `.codebuddy/settings.json`：

```json
{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}
```

启动时同时给 `--permission-mode` 时，CLI 参数优先。优先级顺序为：会话当前值 → `permissions.defaultMode` → `default`。

### 计划进入前的"前置模式"自动记忆

进入 `plan` 时，CodeBuddy 会记住当前模式，离开 plan 时还原。这意味着：

- 你在 `acceptEdits` 下按 `Shift+Tab` 进 `plan`，plan 期间 Read/Edit/Bash 的审批策略仍然按 `acceptEdits` 的规则做（计划文件除外，永不询问）
- 离开 plan 时回到 `acceptEdits`，不会被强行掉到 `default`

## 各模式语义详解

### default（默认）

逐次审批模式，是初学者和处理敏感工作时的安全选项。

| 工具类型 | 决定                                                                                                |
| :------- | :-------------------------------------------------------------------------------------------------- |
| Read     | 路径在信任目录内（cwd + `permissions.additionalDirectories` + 用户加的 `addDir`）→ 放行；否则询问  |
| Edit     | 一律询问                                                                                            |
| Bash     | 一律询问                                                                                            |
| 其他     | 一律询问                                                                                            |

### acceptEdits（自动批准文件编辑）

适合"想边写边过 diff，不想被每个 Edit 弹窗打断"。

| 工具类型 | 决定                                                                                                |
| :------- | :-------------------------------------------------------------------------------------------------- |
| Read     | 信任目录内 → 放行；否则询问                                                                        |
| Edit     | **一律放行**                                                                                        |
| Bash     | 一律询问                                                                                            |
| 其他     | 一律询问                                                                                            |

注意：

- 仅自动批准 **`Edit` 类工具**（Edit / Write / NotebookEdit 等），不影响 Bash —— Bash 永远走单独的安全分级
- "信任目录"以工作区根 + 用户配置的 `permissions.additionalDirectories` + 启动时 `--add-dir` 为准
- 读写[受保护文件](#受保护的关键文件)仍照原模式询问，不走自动放行

### plan（探索后再改）

CodeBuddy 在 plan 模式下专心读代码、跑只读 Bash 命令探查，把方案写成计划再回来征求你的同意；不会落地修改你的源码。

plan 模式不是独立的"全块只读"，而是**委托给前置模式**：

- Read：把决定权交给前置模式（默认是 `default`）
- Edit：仅当目标路径是当前会话的**计划文件**时放行；否则委托给前置模式
- Bash：委托给前置模式
- 进入 plan 通过 `Shift+Tab` 或工具 `EnterPlanMode`；退出通过再次 `Shift+Tab` 或 `ExitPlanMode`

启动时直接进 plan：

```bash
codebuddy --permission-mode plan
```

### bypassPermissions（跳过所有检查）

字面意思：**全部跳过审批**。所有 Bash、Edit、网络、MCP 都立刻执行。仅在以下场景使用：

- 隔离的容器 / VM / dev container
- 没有外网的 sandbox
- 你完全清楚后果的脚本化场景

启动方式：

```bash
codebuddy --permission-mode bypassPermissions
# 等价
codebuddy -y
codebuddy --dangerously-skip-permissions
```

#### 关闭通道（管理员）

把 `permissions.disableBypassPermissionsMode: "disable"` 写到任一层 settings：

```json
{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}
```

写入后即使会话切到 `bypassPermissions`，权限策略也会**降级回 `default` 的判定**；多层 settings（user / project / local / CLI 启动参数）任一层为 `"disable"` 即生效。

### delegate（多代理协调模式）

主代理在 `delegate` 模式下**只能调度**：发任务、起子代理、跨成员通信，自己不动手编辑或跑命令。

行为：

- 主代理可用的工具集中只保留协调类工具（Agent / TaskCreate / SendMessage 等），全部自动放行
- 实现类工具（Read / Write / Edit / Bash 等）会被屏蔽，由子代理执行

适合的场景：你明确要做"主代理只规划、各专业子代理实施"的协作任务（[Agent Teams](agent-teams.md) / [子代理](sub-agents.md)）。

按 `Shift+Tab` 循环到 `delegate` 即可进入。

### work（IDE 集成）

由 IDE 客户端通过协议设置，CLI 用户不直接接触。语义：

| 工具类型 | 决定                                                |
| :------- | :-------------------------------------------------- |
| Read     | **直接放行**（不检查信任目录）                      |
| Edit     | 一律询问                                            |
| Bash     | 安全命令直接放行；危险或需要审批的命令询问          |
| 其他     | 放行                                                |

### fullAccess（IDE 集成）

仅由 IDE 客户端通过协议传入；与 `bypassPermissions` 同语义。

### ignore（子代理专用）

仅子代理的 frontmatter / option 用到 —— 子代理把 `permissionMode: ignore` 写在自己的元信息里时，会被识别为"不要覆盖父代理的模式"，沿用父会话当前模式。主会话不会出现这个值。

## 受保护的关键文件

下列路径的写入操作即使在 `acceptEdits` / `bypassPermissions` 也会保留特殊处理：

- 仓库自身：`.git`、`.gitconfig`、`.gitmodules`
- shell 配置：`.bashrc` / `.bash_profile` / `.zshrc` / `.zprofile` / `.envrc` 等
- 包管理：`.npmrc` / `.yarnrc` / `.pnpmfile.cjs` / `bunfig.toml` 等
- IDE / 工具：`.vscode` / `.idea` / `.husky` / `.devcontainer` / `.cargo` / `.yarn` / `.mvn`
- CodeBuddy 自身：`.codebuddy`（除 `.codebuddy/worktrees`）
- MCP / 配置：`.mcp.json` / `.codebuddy.json`

## 子代理的权限模式继承

子代理（[Agent](sub-agents.md) 工具调用、[Agent Teams](agent-teams.md) 队员）默认继承主会话的权限模式。要在团队 / 项目层强制覆盖：

```json
{
  "permissions": {
    "subagentPermissionMode": "bypassPermissions"
  }
}
```

写入后所有子代理都会按 `bypassPermissions` 跑。注意：

- Agent 工具调用时显式传 `mode` 参数 → **优先级最高**，覆盖此设置
- 子代理 frontmatter 里写 `permissionMode: ignore` → 仍按主会话模式跑（不被本设置影响）

## 与 Permissions 规则配合

权限模式定义"基线"。在 `~/.codebuddy/settings.json` 或仓库 `.codebuddy/settings.json` 的 `permissions` 下还可以叠加规则：

```json
{
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm test)", "Read(/etc/hosts)"],
    "ask": ["WebFetch"],
    "deny": ["Bash(rm -rf *)", "Edit(.git/**)"]
  }
}
```

- `allow` / `ask` / `deny` 三层优先级高于 mode 的判定（除 `bypassPermissions` 整段跳过权限层）
- 详细规则语法见 [Settings 配置](settings.md)、[安全](security.md) 与 [IAM](iam.md)

## 相关资源

- [Agent Teams：多代理协作](agent-teams.md)：在 `delegate` 模式下让主代理专注调度
- [子代理（Sub-agents）](sub-agents.md)：子代理的工具与权限模式继承
- [Hooks 钩子系统](hooks-guide.md)：用 `PreToolUse` 钩子做自定义放行 / 拦截
- [Bash 沙箱化](bash-sandboxing.md)：在 Bash 命令层加文件系统 / 网络隔离
- [Settings 配置](settings.md)：权限规则、信任目录、`disableBypassPermissionsMode` 等完整字段
- [CLI 参考](cli-reference.md)：`--permission-mode` / `-y` / `--add-dir` 等启动参数
- [非交互模式](headless.md)：`-p` 流程下使用权限模式
