docs(reference): correct permission-modes precision per official en page (#16)
Verified against code.claude.com/docs/en/permission-modes and fixed 6 points: 1. acceptEdits: add PowerShell tool auto-approvals (Set-Content/Add-Content/ Clear-Content/Remove-Item + aliases) and env-prefix/process-wrapper note. 2. Protected paths: .claude exception is ONLY .claude/worktrees (was wrongly widened to commands/agents/skills); add per-mode protected-write table. 3. defaultMode:"auto" ignored from project files since v2.1.142+. 4. dontAsk: read-only Bash commands also run without allow rules; explicit ask rules are denied (not prompted). 5. auto conversational boundary: stays in force until user lifts it; Claude's own judgment doesn't lift it; lost on context compaction; use deny rule for hard. 6. auto consecutive-failure fallback: 3-in-a-row / 20-total pauses & re-prompts; -p non-interactive aborts the session. Plus dropped broad allow-rules on entry. Co-authored-by: chenchen <chenchen@xinghanlab.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -161,16 +161,19 @@ Claude Code 的企业管控可拆成三层 + 两条贯穿能力:
|
||||
| 模式 | 不问就放行的范围 | 写「受保护路径」 | 适用 |
|
||||
|---|---|---|---|
|
||||
| `default` | 仅只读 | 提示 | 入门 / 敏感工作 |
|
||||
| `acceptEdits` | 读 + 文件编辑 + 常见 FS 命令(`mkdir touch mv cp rm rmdir sed`) | 提示 | 迭代中的代码 |
|
||||
| `acceptEdits` | 读 + 文件编辑 + 常见 FS 命令(`mkdir touch rm rmdir mv cp sed`) | 提示 | 迭代中的代码 |
|
||||
| `plan` | 仅只读(先探索出计划,不改源码) | 提示 | 改动前探索 |
|
||||
| `auto` | **所有操作,但每次经后台分类器安全检查**(研究预览) | 路由到分类器 | 长任务、减少打扰 |
|
||||
| `dontAsk` | 仅预先批准的工具,其余**自动拒绝** | 拒绝 | 锁定的 CI / 脚本 |
|
||||
| `dontAsk` | 仅 `permissions.allow` 命中的工具 + **只读 Bash 命令**;其余**自动拒绝**(连 `ask` 规则也直接拒、不提示) | 拒绝 | 锁定的 CI / 脚本 |
|
||||
| `bypassPermissions` | 所有操作,跳过检查(`rm -rf /`、`rm -rf ~` 仍有断路器提示) | 允许(v2.1.126+) | **仅隔离容器/VM** |
|
||||
|
||||
- 切换:CLI 按 `Shift+Tab` 循环 `default → acceptEdits → plan`;`auto`/`dontAsk`/`bypassPermissions` 需 `claude --permission-mode <mode>` 或持久化 `permissions.defaultMode`。
|
||||
- **仓库无法自授**:`.claude/settings.json` / `.local.json` 里设 `defaultMode:"auto"` 会被**忽略**,必须放 `~/.claude/settings.json`(防检入仓库自我提权)。
|
||||
- **acceptEdits 细节**:自动批准的 FS 命令仅限**工作目录或 `additionalDirectories` 内**路径;命令带安全 env 前缀(`LANG=C`/`NO_COLOR=1`)或进程包装器(`timeout`/`nice`/`nohup`)仍自动批准;**启用 PowerShell 工具时**,还自动批准 `Set-Content`/`Add-Content`/`Clear-Content`/`Remove-Item` 及其常见别名(同样受作用域 + 受保护路径限制)。
|
||||
- **仓库无法自授**:**Claude Code v2.1.142+** 会**忽略** `.claude/settings.json` / `.local.json` 里的 `defaultMode:"auto"`(防检入仓库自我提权),必须放 `~/.claude/settings.json`。
|
||||
- `bypassPermissions` **不防提示注入**;想「无提示但有安全检查」用 `auto`。
|
||||
- **受保护路径**(除 bypass 外永不自动批准写):`.git .config/git .vscode .idea .husky .cargo .devcontainer .yarn .mvn .claude`(`.claude/commands|agents|skills|worktrees` 例外);及 `.mcp.json .claude.json .npmrc .bashrc/.zshrc` 等文件。
|
||||
- **受保护路径**(除 `bypassPermissions` 外永不自动批准写;`auto` 下路由到分类器、`dontAsk` 下直接拒):
|
||||
- 目录:`.git` `.config/git` `.vscode` `.idea` `.husky` `.cargo` `.devcontainer` `.yarn` `.mvn` `.claude`(**仅 `.claude/worktrees` 例外**——官方只列这一个,commands/agents/skills 不在例外内)。
|
||||
- 文件:`.gitconfig` `.gitmodules`、各种 shell rc(`.bashrc`/`.zshrc`/`.profile`/`.envrc` 等)、包管理器配置(`.npmrc`/`.yarnrc`/`bunfig.toml` 等)、`.mcp.json`、`.claude.json` 等。
|
||||
|
||||
### 3.6 auto-mode 的管理员启用与锁定 [PM]
|
||||
- **所有计划**都支持 auto mode,但 **Team / Enterprise 上管理员必须先在 `https://claude.ai/admin-settings/claude-code` 启用**,用户才能开。
|
||||
@@ -398,12 +401,22 @@ Claude Code 的企业管控可拆成三层 + 两条贯穿能力:
|
||||
3. `allow` 覆盖匹配的 `soft_deny`;
|
||||
4. **明确用户意图**覆盖剩余 soft_deny(须「直接且具体」,如「强制推送此分支」算,泛泛「清理代码库」不算)。
|
||||
|
||||
### 8.5 与权限系统的关系(重要)[AM]
|
||||
- **分类器是权限系统之后的「第二道门」**。`permissions.deny`(基于工具模式)在分类器**之前**先跑,是**硬边界**;`autoMode` 是其后的语义判断层。
|
||||
- `autoMode` 合并是**累加(additive)的,不是硬策略边界**:开发者能扩展 environment/allow/soft_deny/hard_deny,**不能删除托管条目**;但因 allow 是 soft_deny 的例外,**开发者新增 allow 可覆盖组织的 soft_deny**。
|
||||
- → **结论**:对「无论用户意图或分类器配置如何都必须永不运行」的操作,要用**托管设置里的 `permissions.deny`**(咨询分类器**之前**阻断,不可覆盖),而非 `autoMode`。
|
||||
### 8.5 对话边界(conversational boundary)[PM]
|
||||
- 你在对话里说的限制会被分类器当作 **block 信号**:说「别推送」「我 review 前别部署」后,即便默认规则允许,匹配操作也会被拦。
|
||||
- **关键**:「**边界一直生效,直到你在后续消息里主动解除;Claude 自己判断条件已满足并不能解除它**」(原文:*A boundary stays in force until you lift it in a later message. Claude's own judgment that a condition was met does not lift it.*)。
|
||||
- 对话边界**不是存成规则**——分类器每次从对话记录里重读;若 **context 压缩**把那条消息删了,边界可能丢失。要**硬保证**请改用托管 `permissions.deny`。
|
||||
|
||||
### 8.6 CLI 验证 [AM]
|
||||
### 8.6 与权限系统的关系 + 进入 auto 时丢弃宽规则(重要)[AM][PM]
|
||||
- **分类器是权限系统之后的「第二道门」**。`permissions.deny`(工具模式)在分类器**之前**跑,是**硬边界**;`autoMode` 是其后的语义判断层。
|
||||
- `autoMode` 合并是**累加的、不是硬边界**:开发者能扩展 environment/allow/soft_deny/hard_deny、不能删托管条目;但 allow 是 soft_deny 的例外,**开发者新增 allow 可覆盖组织 soft_deny**。
|
||||
- **进入 auto 模式时,授予任意代码执行的宽 allow 规则会被丢弃**:`Bash(*)`/`PowerShell(*)`、通配解释器 `Bash(python*)`、包管理器 run 命令、`Agent` allow 规则——离开 auto 时恢复;窄规则如 `Bash(npm test)` 保留。
|
||||
- → **结论**:「无论如何都绝不能跑」的操作,放托管 `permissions.deny`(分类器前阻断、不可覆盖),别只靠 `autoMode`。
|
||||
|
||||
### 8.7 连续失败回退 / -p 中止(CI 重要)[PM]
|
||||
- 分类器**连续阻止 3 次,或累计阻止 20 次**,auto 模式**暂停并恢复人工提示**;批准被提示的操作后恢复 auto。阈值**不可配**。任一允许操作重置「连续」计数器;「累计」计数器跨会话持续,只在自己触发回退时重置。
|
||||
- **`-p` 非交互模式下**:没有用户可问,**重复阻止会直接中止 session**——CI 场景务必注意。
|
||||
|
||||
### 8.8 CLI 验证 [AM]
|
||||
- `claude auto-mode defaults` —— 打印内置 environment/allow/soft_deny/hard_deny。
|
||||
- `claude auto-mode config` —— 打印应用设置后**实际生效**的规则(`$defaults` 已展开)。
|
||||
- `claude auto-mode critique` —— AI 审查自定义规则(标记模糊/冗余/易误报)。
|
||||
|
||||
Reference in New Issue
Block a user