Skip to content

08-permissions-and-safety.md

Latest commit

 

History

History
150 lines (101 loc) · 5.8 KB

08-permissions-and-safety.md

File metadata and controls

150 lines (101 loc) · 5.8 KB

08. 权限与安全控制

这篇讲什么

这一章解释 Claude Code 里最重要的一道边界：权限模式、规则系统、危险规则拦截，以及 plan mode 在这里扮演的角色。

先给结论

Claude Code 的权限系统不是一个简单的“是否弹窗确认”开关，而是一套有模式、有规则来源、有危险规则检测、有会话切换逻辑的完整安全层。

源码依据

Mermaid 图：权限决策流程图

flowchart TD
    A[tool call] --> B[读取 ToolPermissionContext]
    B --> C[检查 mode / allow deny ask 规则]
    C --> D[检查 working directories / path rules]
    D --> E[危险规则检测]
    E --> F{决策}
    F -- allow --> G[直接执行]
    F -- ask --> H[请求用户批准]
    F -- deny --> I[拒绝并返回]
    J[EnterPlanMode] --> K[切换到 plan mode]
    L[ExitPlanMode] --> M[校验当前 mode]
    M --> N[请求批准或 leader 审批]
Loading

可见的权限模式

从 src/types/permissions.ts 可以直接确认外部可见模式包括：

  • acceptEdits
  • bypassPermissions
  • default
  • dontAsk
  • plan

内部还可能有：

  • auto
  • bubble

其中 auto 是否存在受 TRANSCRIPT_CLASSIFIER feature gate 控制。

ToolPermissionContext 里有什么

从 src/Tool.ts 可确认，一个完整的权限上下文至少包含：

  • 当前 mode
  • 额外工作目录
  • allow/deny/ask 规则
  • 是否可用 bypassPermissions
  • 是否应避免显示权限提示
  • prePlanMode

这意味着权限不是零散判断，而是整个工具调用环境的一部分。

规则从哪里来

src/types/permissions.ts 里定义了规则来源和更新目标。来源包括：

  • userSettings
  • projectSettings
  • localSettings
  • flagSettings
  • policySettings
  • cliArg
  • command
  • session

更新目标包括：

  • userSettings
  • projectSettings
  • localSettings
  • session
  • cliArg

这套设计说明权限规则既可以长期持久化，也可以只对当前会话生效。

危险规则检测不是事后补救

src/utils/permissions/permissionSetup.ts 明确实现了危险规则检测，例如：

  • 允许过宽的 Bash 规则
  • 允许 PowerShell 执行任意代码的规则
  • 自动批准 Agent/Sub-agent 的规则

这些规则会削弱 auto mode/classifier 的安全边界，因此系统会专门识别它们。

为什么 plan mode 属于权限系统

plan 在这个项目里不是纯 UI 模式，而是权限模式的一种。

src/tools/EnterPlanModeTool/EnterPlanModeTool.ts 显示：

  • 进入 plan mode 时，会把当前权限模式切换为 plan。
  • 调用方被要求进入只读的探索和设计阶段。
  • 工具描述明确强调先探索、后设计、再退出 plan mode 请求批准。

这意味着 plan mode 的核心作用不是“写计划”，而是把会话暂时切换到一个更保守的权限语义中。

退出 plan mode 时会发生什么

src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts 显示：

  • 该工具只应在当前确实处于 plan 模式时使用。
  • 对普通会话，它会要求用户确认退出 plan mode。
  • 对 teammate/leader 场景，它会走不同的审批路径。
  • 该工具不是只读工具，因为它现在会写 plan 文件到磁盘。

这说明“计划模式”在这里已经不仅是对话约定，而是带有持久化和审批语义的正式工作流。

/permissions 命令的角色

src/commands/permissions/index.ts 明确将其描述为：

  • 管理 allow/deny 工具权限规则。

对使用者来说，这意味着权限系统有明确的用户操作入口，而不是只能靠配置文件或内部状态改变。

设计观察

如果只看机制名，你可能会觉得 plan mode、dangerous rules、tool approval 是三套平行功能；但从 Anthropic 的设计语义看，它们更像同一套 agent 工作流的不同面向。这里的核心不是“给模型加护栏”，而是把 agent 何时探索、何时写入、何时需要批准、哪些自动化规则会变危险，都做成正式的运行制度。也就是说，安全在 Claude Code 里不是外围插件，而是 agent 设计本体。

阅读这部分源码时要注意什么

  • 很多权限行为与 settings、feature gate、auth 状态耦合。
  • bypassPermissions 是否可用不完全是本地静态值，还可能受远程 gate 影响。
  • auto 和 plan 的关系要结合 permissionSetup.ts 去看。

这一章的工作结论

权限层是 Claude Code 的真实安全边界。命令、工具、子代理、plan mode、工作目录扩展，最终都要回到这里接受模式和规则约束。

延伸阅读