权限与安全
Claude Code 的执行能力很强，所以权限与安全不是附属机制，而是主流程的一部分。你可以把它理解成一套贯穿输入、工具、主循环与 UI 的控制链。
系统如何决定哪些动作可以执行、哪些动作必须限制或确认。
优先看工具协议、工具注册、权限规则系统和 QueryEngine 回流。
理解默认模式、计划模式、自动模式为何会影响整条执行链。
权限贯穿路径
如果把 Claude Code 看成一条“输入 -> 主循环 -> 工具 -> 状态 -> 渲染”的执行链，那么权限和安全逻辑几乎嵌在每一层里。它不是单点拦截器，而是一套贯穿整个执行过程的控制系统。权限控制主要落在哪
src/Tool.ts：统一承载工具权限上下文。
src/tools.ts：决定当前环境下哪些工具可用。
src/utils/permissions/：规则解析、危险模式识别、自动模式控制。
src/utils/processUserInput/：在进入主循环前做部分前置拦截。
权限为什么必须和工具层绑定
- 真正危险的动作发生在工具调用阶段，而不是纯文本生成阶段。
- 不同工具的风险模型不同，必须保留细粒度控制。
- 自动模式、计划模式、默认模式等权限策略都要统一落在可执行能力上。
输入层安全透视
模块定位
输入层的安全职责不是最终拍板是否放行，而是尽量在进入高成本主循环前完成基础分流和部分前置约束。关键文件
src/utils/processUserInput/processUserInput.ts- 输入与命令层模块页
上游 / 下游
- 上游：用户输入、桥接输入、系统生成 prompt
- 下游：本地命令、QueryEngine、hook 链
运行时行为
- 决定某次输入究竟是普通 prompt、slash command 还是 meta prompt
- 执行 prompt submit hooks
- 在进入主循环前形成更稳定的输入语义，减少后续安全控制的歧义
常见误区
输入层不会代替工具层做最终授权判断，它更多负责“先分清输入要去哪条路”。建议阅读顺序
processUserInput- hook 执行相关逻辑
- 再看 QueryEngine 如何消费结果
工具协议与注册层安全透视
模块定位
Tool.ts 和 tools.ts 是安全边界最核心的两层：前者定义权限上下文和工具抽象，后者决定哪些能力在当前会话里真正暴露。关键文件
src/Tool.tssrc/tools.ts- 工具执行层模块页
上游 / 下游
- 上游：QueryEngine 的工具请求
- 下游：具体工具实现、权限规则、环境依赖
运行时行为
- 统一工具调用协议
- 根据环境、feature gate 和会话配置裁剪可用工具集合
- 为后续权限系统提供一致的工具名、规则匹配和上下文入口
常见误区
很多人把安全逻辑全归到utils/permissions/，但如果没有 Tool 协议和工具注册层提供统一接口，后面的权限系统很难做到细粒度而一致的控制。建议阅读顺序
Tool.ts的类型与上下文tools.ts的注册和 feature gate- 再进入具体权限规则
权限规则与模式透视
模块定位
src/utils/permissions/ 是权限系统的策略层，负责把“允许什么、不允许什么、在什么模式下允许”表达成可执行规则。关键文件
src/utils/permissions/permissionSetup.tssrc/utils/permissions/PermissionMode.tssrc/utils/permissions/permissions.ts- 工具执行层模块页
上游 / 下游
- 上游：Tool 协议、工具名、用户配置、环境变量、GrowthBook / policy 条件
- 下游：具体工具放行 / 拒绝、自动模式限制、危险规则过滤
运行时行为
- 解析 permission mode
- 从磁盘与配置源加载规则
- 识别危险 Bash / PowerShell 规则
- 在自动模式或受限模式下收窄能力边界
常见误区
权限模式不是单纯的 UI 文案状态，而是会真实改变工具暴露面和规则集的运行时配置。建议阅读顺序
PermissionMode.tspermissionSetup.tspermissions.ts和危险模式定义
QueryEngine 回流透视
模块定位
安全系统不能只负责“拒绝动作”，还必须负责把拒绝结果正确回流到会话主循环，否则模型和用户都无法理解刚刚发生了什么。关键文件
src/QueryEngine.tssrc/query.ts- QueryEngine 模块页
上游 / 下游
- 上游：工具执行结果、权限拒绝结果
- 下游：消息历史、后续轮次、状态更新、UI 反馈
运行时行为
- 将权限拒绝或工具错误编码进消息流
- 维护 tool use / tool result 的配对关系
- 让模型在后续轮次感知“某个工具为什么没被执行”
常见误区
如果只看权限规则本身，很容易忽略“被拒绝之后系统怎么继续运行”。而这恰恰是 QueryEngine 很重要的职责。建议阅读顺序
- QueryEngine 的消息持有与提交逻辑
query.ts中工具结果与错误处理路径- 再回头看工具权限上下文
状态与 UI 反馈透视
模块定位
权限系统最后必须把内部判断转成用户可理解的反馈，否则安全策略就只是黑箱。关键文件
src/state/AppStateStore.tssrc/components/- 状态与任务系统模块页
- UI 渲染模块页
上游 / 下游
- 上游：QueryEngine、工具层、权限规则系统
- 下游：终端 UI、状态栏、提示信息、后续用户交互
运行时行为
- 在 AppState 中保存
toolPermissionContext - 把授权状态、拒绝状态和相关提示展示到 UI
- 让用户理解当前模式下为什么某类动作被允许或被限制
常见误区
安全反馈不只是弹一次确认框。对于长会话、后台任务、bridge 或自动模式来说，持续可见的状态表达同样重要。建议阅读顺序
AppStateStore.ts中与权限相关的状态- 相关 UI 组件
- 再回看工具层如何更新这些状态
默认模式、计划模式、自动模式的落点差异
三种模式的差异，不只是“严格程度不同”，而是落在流程中的位置不同：- 默认模式：以工具执行时的逐次判断为主，强调显式授权
- 计划模式：偏向限制执行、鼓励先分析后实施，因此会影响工具使用边界和用户预期
- 自动模式：最依赖规则系统、危险模式识别和工具裁剪，因为它要减少人工确认同时避免越界
你应该重点关注什么
- 权限模式如何表示
- 危险规则如何定义
- 工具授权失败后如何反馈回 QueryEngine
- 权限状态如何影响后续消息与 UI