一、先讲结论

如果仅从表面看，Claude Code 的权限系统似乎只是几种模式的简单切换：默认模式弹窗提示、危险模式直接放行、自动模式减少打扰。

但深入源码就会发现，实际情况远比表面复杂得多。

一个工具调用从发起直到实际执行，至少要经历以下多个关卡：

1. 规则引擎
2. 工具自带的 checkPermissions()
3. 模式分支
4. 安全检查
5. AI 分类器
6. Hooks / UI / 多 Agent 转发

更重要的是，这并非一套简单的“单点 if-else”逻辑。内层的 hasPermissionsToUseToolInner() 负责主干裁决，外层的 hasPermissionsToUseTool() 负责 dontAsk、auto、headless fallback 这类模式化后处理。两层协同，构成了一套精密的决策系统。

在深入拆解之前，有一个最容易混淆的关键点必须先澄清：

• TypeScript 类型联合 InternalPermissionMode 确实包含 7 个值：default、acceptEdits、bypassPermissions、plan、dontAsk、auto、bubble。
• 但千万别把这 7 个值都当成“公开可选模式”。
• SDK schema 对外暴露的只有 5 个（EXTERNAL_PERMISSION_MODES）：default、acceptEdits、bypassPermissions、plan、dontAsk。
• bubble 仅存在于类型定义中，不在 PERMISSION_MODES 运行时验证集里，也没有对应的 PERMISSION_MODE_CONFIG 配置——它实际上是子 Agent 的纯内部占位符。
• auto 受 TRANSCRIPT_CLASSIFIER feature gate 约束，开启后才会被加入 PERMISSION_MODES，并非所有构建版本都对外开放。

这个区别如果不提前说明，后面整篇文章都会把“源码内部状态”和“产品公开能力”混为一谈。

二、完整执行路径：6 阶段决策流水线

一个工具调用的主干权限判定，发生在 hasPermissionsToUseToolInner() 里。它的决策流程可以用下面这张图来概括：

flowchart TDStart["工具调用发起"] --> S1asubgraph Stage1["阶段1：规则检查 + 工具自检"]S1a["1a. Deny Rule 命中？"] -->|是| DENY1["❌ 直接拒绝"]S1a -->|否| S1bS1b["1b. Ask Rule 命中？"] -->|是| ASK1["⚠️ 需要确认"]S1b -->|否| S1cS1c["1c. tool.checkPermissions()"] -->|allow| ALLOW0["✅ 工具直接放行"]S1c -->|deny| DENY2["❌ 工具拒绝"]S1c -->|ask| S1eS1c -->|passthrough| Stage2S1e["1e. requiresUserInteraction?"] -->|是| ASK2["⚠️ 必须人工交互"]S1e -->|否| S1fS1f["1f. 内容级 Ask Rule？"] -->|是| ASK3["⚠️ 内容级确认"]S1f -->|否| S1gS1g["1g. Safety Check？"] -->|是| ASK4["⚠️ 安全检查"]S1g -->|否| Stage2endsubgraph Stage2["阶段2：模式 / Always Allow"]S2a["2a. bypassPermissions 或特殊 plan？"] -->|是| ALLOW1["✅ 放行"]S2a -->|否| S2bS2b["2b. Always Allow 命中？"] -->|是| ALLOW2["✅ 放行"]S2b -->|否| Stage3endsubgraph Stage3["阶段3：标准化结果"]S3["passthrough -> ask"] --> Stage4endsubgraph Stage4["阶段4：外层后处理"]S4a["dontAsk 模式？"] -->|是| DENY3["❌ 自动拒绝"]S4a -->|否| S4bS4b["auto / plan+auto 语义？"] -->|是| ClassifierS4b -->|否| S4cS4c["shouldA voidPermissionPrompts?"] -->|是| HookOrDeny["Hooks -> 否则拒绝"]S4c -->|否| UserConfirm["展示确认对话框"]endsubgraph Classifier["Auto 模式分类器"]C1["不可分类的 safetyCheck？"] -->|是| DENY4["❌ 拒绝或保留人工确认"]C1 -->|否| C2C2["acceptEdits 快速路径？"] -->|通过| ALLOW3["✅ 放行"]C2 -->|否| C3C3["安全工具 allowlist？"] -->|是| ALLOW4["✅ 放行"]C3 -->|否| C4C4["调用 YOLO Classifier"] --> C5C5["分类器判定"] -->|允许| ALLOW5["✅ 放行"]C5 -->|阻止| C6C6["Denial 限制检查"] -->|超限| UserConfirm2["回退到人工确认"]C6 -->|未超限| DENY5["❌ 分类器拒绝"]end

实际上，源码中还单独抽出了一个 checkRuleBasedPermissions()，把 1a-1g 这段“纯规则逻辑”进行了复用。不过，真正决定最终结果的，仍然是上面这条主干路径。

阶段 1：规则检查不是一层，而是一组有优先级的闸门

1a. Deny Rule

这一层是最硬的。一旦命中，就直接拒绝，没有任何商量余地。

更值得注意的是，Deny Rule 不只是“运行时拒绝”，它在工具池构建阶段就已经把工具直接过滤掉了。看看这段代码：

export function filterToolsByDenyRules(tools, permissionContext) {return tools.filter(tool => !getDenyRuleForTool(permissionContext, tool))}

这意味着，模型看到的不是“有个工具但你不能用”，而是“这个工具根本不存在”。

这个设计非常强大，因为它从根本上降低了模型尝试绕过限制的动机。

而这些 Deny / Ask / Allow 规则的来源也远不止配置文件那几层。源码里，权限规则的来源一共有 8 种：

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

注意，千万别漏掉 command 这一层——它来自内置命令（如 /init、/config），和 cliArg（CLI 启动参数）是完全不同的来源。

1b. Ask Rule

如果工具整体命中了 Ask Rule，会先得到一个 ask 的判定。

但这里有一个重要的例外：Bash 的沙箱自动放行机制。

• 当 SandboxManager.isSandboxingEnabled() 为真
• 且 autoAllowBashIfSandboxed 开启
• 且当前命令确实会进入沙箱执行（shouldUseSandbox(input) 返回真）
• 也就是没有 excludedCommand / dangerouslyDisableSandbox 这类绕开沙箱的情况

满足所有这些条件时，Ask Rule 会被跳过，继续交给 Bash 自己的 checkPermissions() 进行更细致的检查。沙箱本身已经提供了额外的安全层，因此没必要再弹一次确认框。

1c. tool.checkPermissions()

这是 Claude Code 权限系统最重要的扩展点之一。

它的默认实现并不是 passthrough，而是直接返回 allow：

checkPermissions: (input) =>Promise.resolve({ beha vior: 'allow', updatedInput: input })

也就是说，默认语义是“没有额外限制”。真正复杂的工具，比如 Bash、PowerShell、文件读写、Notebook 编辑，都会重写这一层。

这里还藏着一个很精巧的类型设计：PermissionResult 比 PermissionDecision 多了一个 passthrough 状态。

type PermissionResult =| PermissionDecision| { beha vior: 'passthrough', ... }

passthrough 的含义不是“允许”，而是“我不做决定，交回给通用流程去处理”。

这让每个工具的作者可以不用硬着头皮去选 allow / deny / ask，只需要在自己真正有把握的那部分做出判断。

1e-1g. ask 结果的再细分

工具一旦返回 ask，系统还要继续往下分三种情况：

• requiresUserInteraction()：有些工具，即使在 bypass 模式下也必须由人工确认。
• 内容级 Ask Rule：比如 Bash(npm publish:*) 这样的规则。
• safetyCheck：例如涉及 .git/、.claude/、.vscode/、shell 配置文件、跨机器桥接消息等敏感操作。

这里最核心的规则是：

• 内容级 Ask Rule 对 bypassPermissions 是免疫的。
• safetyCheck 对 bypassPermissions 也是免疫的。

换句话说，所谓的“危险模式”并不是“所有检查都跳过”，只是跳过了后半段的通用确认逻辑。前面的那些硬闸门，依然牢固地锁在那里。

阶段 2：模式和 Always Allow

通过了阶段 1 之后，系统会再检查两件事。

2a. bypassPermissions

这里不仅包含直接的 bypassPermissions，还包含一种容易被忽略的特殊情况：

• 当前模式是 plan。
• 但上下文里的 isBypassPermissionsModeA vailable 仍然为真。

源码会把它视为“权限可旁路”的场景。

所以，不要把 plan 简单理解成权限系统里的一个“只读 if 分支”。plan 更像是一个流程模式，它的实际行为还和工具池、ExitPlanMode、auto 语义复用等机制紧紧缠绕在一起。

2b. Always Allow

这一层才是我们传统意义上理解的白名单。

但也别把它简单理解为“用户点一次 always allow，就永远新增一条 allow 规则”。Claude Code 的 permission prompt 返回的是结构化的 suggestions，某些“永远允许”会被翻译成更高层级的权限更新，而不是简单地加一条裸 allow rule。

阶段 3：把 passthrough 标准化成 ask

走到这一步，如果工具还没有给出明确的裁决，passthrough 会被统一转换成 ask。

这一步很关键，因为后面的 UI、Hooks、classifier 逻辑只处理三种确定的状态：

• allow
• deny
• ask

阶段 4：真正复杂的是外层后处理

外层 hasPermissionsToUseTool() 拿到内层的结果后，才会根据不同的模式进行分流：

再次强调，auto 不是所有构建版本都可见，bubble 更是纯粹的内部模式。如果把这 7 个值直接当成“用户可选的模式”，会极大夸大产品表面的能力。

这里还有第二个容易混淆的点：

• dontAsk 是一种 mode。
• shouldA voidPermissionPrompts 是一个上下文字段。

它们不是一回事。

许多异步子 Agent、后台 Agent 没法弹出 UI，并不是因为它们处在 dontAsk 模式，而是因为上下文被打上了 shouldA voidPermissionPrompts: true 的标记。这时，系统会先尝试运行 PermissionRequest Hooks，如果 Hooks 也没能做出决定，才会自动拒绝。

三、Auto 模式：不是所有 ask 都交给分类器

auto 是 Claude Code 最有意思的权限创新之一。它不会直接弹窗，而是把“要不要拦”这个问题交给另一个模型来判断。

但它也不是“所有 ask 都无脑调分类器”。源码里做了大量的短路和特殊分支处理。

快速路径 1：模拟 acceptEdits

如果某个操作在 acceptEdits 模式下本来就能被放行，那 auto 模式就没必要再浪费一次 classifier 调用的成本。

const acceptEditsResult = await tool.checkPermissions(parsedInput, {...context,getAppState: () => ({...state,toolPermissionContext: {...state.toolPermissionContext,mode: 'acceptEdits',},}),})

这条快速路径非常实用，尤其针对工作目录内的编辑操作。

但 Claude Code 也刻意把 Agent 和 REPL 排除在外了，因为在这两个模式下，操作太容易“看起来安全，但实际上绕过了 classifier”。

快速路径 2：安全工具 allowlist

源码里有一组 SAFE_YOLO_ALLOWLISTED_TOOLS，覆盖了所有只读、元数据、协调类的工具：

• 文件只读：FileRead
• 搜索：Grep、Glob、LSP、ToolSearch
• MCP 资源：ListMcpResources、ReadMcpResource
• 任务管理：TodoWrite、TaskCreate、TaskGet、TaskUpdate、TaskList、TaskStop、TaskOutput
• 交互 / 流程：AskUserQuestion、EnterPlanMode、ExitPlanMode
• Swarm 协调：TeamCreate、TeamDelete、SendMessage
• 其他安全工具：Sleep、Workflow（条件编译）、以及若干 ant-only 的内部工具

这些工具不需要 transcript classifier 介入，可以直接放行。

快速路径 3：真正调用 classifyYoloAction()

只有前两层都不命中时，才会进入真正的 classifier。

这时，Claude Code 会把：

1. 当前动作格式化成一个 action。
2. 把对话历史压缩成 classifier transcript。
3. 通过一个独立的 side query 来调用模型。
4. 最终得到一个 shouldBlock 的结果及其原因。

值得注意的是，从 telemetry 代码来看，这个 classifier 实际上是两阶段（stage1 + stage2）的，有独立的 token 用量和延迟追踪。也就是说，它不是简单的一次 API 调用，内部有更复杂的判定链路。这部分设计得非常工程化，因为它不只是“调个模型”，还充分考虑了许多失败分支：

• transcript 过长
• API 不可用
• fail-open / fail-closed 策略
• denial tracking（拒绝计数限制）

两个容易忽视的边界

边界 1：不是所有 safetyCheck 都一样

在 safetyCheck 里，有一个字段非常关键：

classifierApprovable: boolean

这意味着：

• 有些 safety check 可以交给 classifier，让它结合上下文来决定。
• 有些则完全不行，必须人工确认，或者直接拒绝。

举个例子：

• 像 .git/、.claude/、shell 配置文件这类敏感文件路径，通常 classifierApprovable 为 true。
• 而可疑的 Windows 路径模式、跨机器桥接消息这类更硬的场景，classifierApprovable 则会设为 false。

换句话说，不是“auto 模式会吃掉 safety check”，而是“auto 模式只接手其中可以被分类的那一部分”。

边界 2：PowerShell 默认根本不进 auto classifier

源码里还有一个特殊分支：PowerShell 默认要求显式人工确认，除非 ant-only 的 POWERSHELL_AUTO_MODE feature 被打开。

这说明，Claude Code 的权限系统虽然有一个统一的主干，但并不是“所有工具一视同仁”。工具自身的特性仍然有能力把某些动作拉回更保守的路径。

容错机制

这部分有两个关键细节：

• 当 transcript 过长时，交互式场景会回退到人工确认；而 headless 场景则会直接 throw AbortError（这是一个永久条件，因为 transcript 只会递增，重试没有意义）。
• 当 classifier 连续拒绝 3 次，或者累计拒绝 20 次时，系统会降级到人工确认；如果是 headless 场景，同样会直接 abort。

export const DENIAL_LIMITS = {maxConsecutive: 3,maxTotal: 20,}

这套 denial tracking 非常有价值，因为它清晰地承认了一件事：分类器会误判，所以系统必须留好退路。

四、Bash：真正和确认对话框竞速的是专用 allow classifier

关于“Bash 命令的双重分类器竞速”这个说法，需要更精确地解释清楚。

更准确的事实是：

• Claude Code 里确实存在两套 classifier 家族。
• 一套是 auto 模式下的 transcript classifier。
• 另一套是 Bash 专用的 allow classifier。
• 但它们不会在同一次 Bash 权限判定中同时上场。

因为 Bash 的推测性 allow classifier 有明确的守卫条件：

• 在 auto 模式下不跑。
• 在 bypassPermissions 下不跑。
• 没有提供 prompt allow descriptions 的时候也不跑。

真正会和用户确认对话框竞速的，其实是这个 Bash 专用的 allow classifier。

sequenceDiagramparticipant TE as toolExecutionparticipant B as BashTool.checkPermissionsparticipant SC as 推测性 Bash Allow Classifierparticipant IH as interactiveHandlerparticipant D as 确认对话框participant U as 用户TE->>SC: startSpeculativeClassifierCheck（更早阶段预启动）TE->>B: 执行权限检查B-->>TE: 返回 { ask, pendingClassifierCheck }TE->>IH: 进入交互式权限处理IH->>D: 展示确认对话框par 异步竞速SC->>IH: executeAsyncClassifierCheck 消费结果alt 高置信度允许 && 用户尚未交互IH-->>D: ✅ 自动放行，展示 ✓ 后移除对话框else 不匹配 / 低置信度IH-->>D: 清除 classifier 指示器endand 用户操作U->>D: 手动批准或拒绝（200ms 宽限期后生效）end

这块实现有三个非常精巧的细节：

1. 推测性预执行：startSpeculativeClassifierCheck() 在 toolExecution.ts 的更早阶段就启动了（输入解析后、权限检查前），结果缓存进 Map，后续由 consumeSpeculativeClassifierCheck() 消费。
2. 纯异步竞速：没有固定的超时时间——classifier 和用户操作 / Hooks / Bridge 完全并行竞争，谁先完成谁赢。通过 createResolveOnce() 的 claim() 方法实现原子抢占。
3. 200ms 交互宽限期：用户一旦碰到对话框，自动批准逻辑就会失效（userInteracted = true）。但前 200ms 的误触碰不会取消 classifier，以此防止意外按键打断自动流程。

这意味着，Claude Code 并不是简单地“弹个窗，顺便后台跑个异步任务”，它是在非常认真地尝试减少弹窗频率，同时避免 UI 抢走用户的控制权。

五、Hooks 和 Permission Suggestions：它不是 yes/no，而是可编排的权限口袋

Hooks 和权限系统的关系，值得精准地描述一下。

更准确地说：

• PreToolUse / PostToolUse / PostToolUseFailure 属于更广义的工具生命周期。
• 真正直接插入权限决策流程的，是 PermissionRequest。

PermissionRequest 不只服务于 headless

容易把它理解成“headless agent 的兜底方案”，但实际上它在两种场景下都会运行：

1. 交互式场景：对话框已经显示出来，但 PermissionRequest Hook 会在后台异步执行。如果 Hook 比用户点击按钮更快做出决定，就直接接管这次权限决策。

2. headless / async 场景：无法展示 UI，于是先跑 Hook；如果 Hook 也无法决定，才会自动拒绝。

对应的源码逻辑大致如下：

if (appState.toolPermissionContext.shouldA voidPermissionPrompts) {const hookDecision = await runPermissionRequestHooksForHeadlessAgent(...)if (hookDecision) return hookDecisionreturn { beha vior: 'deny', message: AUTO_REJECT_MESSAGE(tool.name) }}

所以，更准确的总结不是“dontAsk 模式下先给 Hook 一次机会”，而是：

• dontAsk 会把 ask 转成 deny。
• shouldA voidPermissionPrompts 会触发 headless fallback 流程。
• 在这个 fallback 路径上，系统仍然优先给 PermissionRequest Hook 一次接管的机会。

Permission prompt 返回的不是布尔值，而是结构化更新

Claude Code 的 permission prompt 不只是一个简单的“允许 / 拒绝”开关，它还可能附带结构化的 suggestions。在文件权限的场景下尤其明显：

const updates = shouldSuggestAcceptEdits? [{ type: 'setMode', mode: 'acceptEdits', destination: 'session' }]: []if (isOutsideWorkingDir) {updates.push({type: 'addDirectories',directories: dirsToAdd,destination: 'session',})}

这意味着，当用户点下“Always allow”时，系统不一定是在做“加一条 allow 规则”这么粗糙的事情。

它可能做的是：

• 把当前 session 切换到 acceptEdits 模式。
• 把目标目录加入 working directories。
• 或者持久化一组 updatedPermissions。

这是一个非常重要的工程细节。它说明 Claude Code 不是在堆砌规则，而是在维护一份结构化的权限上下文。

六、多 Agent：同一套权限系统，被接成了三种分流模型

在 Claude Code 里，多 Agent 并不是权限系统之外的附属功能，它直接改变了权限请求的去向。

1. Fork Subagent：bubble

Fork 出来的子 Agent 会继承父 Agent 的完整上下文，但会把权限模式设置成 bubble：

export const FORK_AGENT = {permissionMode: 'bubble',tools: ['*'],model: 'inherit',}

含义非常直接：

• 子 Agent 可以继续正常工作。
• 但它没有独立的权限 UI。
• 所有需要确认的请求，都会“冒泡”回到父终端。

2. Coordinator Worker：自动检查优先，弹窗靠后

在协调者模式下，worker 会先按顺序执行：

1. PermissionRequest Hooks
2. Bash classifier
3. 如果都没能决定，再回退到交互式对话框。

这对应着 awaitAutomatedChecksBeforeDialog: true 的语义。

为什么这里是顺序 await，而不是像主线程那样竞速？

因为 worker 自己没有独立的终端，先把自动化分支跑完，能最大程度地减少对主 Agent 的打扰。

3. Swarm Worker：先 classifier，再 mailbox 转发给 leader

Swarm worker 的路径也不同：

1. 首先尝试 classifier 自动放行。
2. 如果不成功，就把 permission request 通过 mailbox 转发给 leader。
3. leader 这边会弹出和本地一模一样的确认 UI。
4. 用户的决策结果再回传给 worker。

这一层设计说明，Claude Code 把“谁来确认”这个问题也抽象成了权限系统的一部分。

4. 反递归保护

多 Agent 最怕的不是某一次危险操作，而是无限的套娃。

Claude Code 也注意到了这一点：

• 外部构建默认限制了 Agent 工具递归嵌套的深度。
• Fork 出来的 child 会通过历史中的 fork 标记来检测递归。

也就是说，多 Agent 的权限设计不只是“把确认框转发一下”，还得顺手把递归爆炸的风险给堵上。

七、和 VS Code Agent / Copilot 的差别在哪

这个对比仅基于 2026 年 3 月能看到的官方公开文档，不猜测任何未公开的实现：

如果只看产品界面，你会觉得两者都在做“权限模式”。

但往源码里走，差异会非常明显：

• VS Code 这类产品：更像是在做“用户可理解的权限档位”。
• Claude Code：更像是在做“给长时间自主运行的 Agent 用的 runtime permission engine”。

这也是为什么 Claude Code 会有那么多你在 UI 上根本看不到的内部状态，比如 passthrough、bubble、shouldA voidPermissionPrompts、awaitAutomatedChecksBeforeDialog。

八、给 Agent 开发者的几个设计启示

从源码里学到的，Claude Code 权限系统最值得借鉴的不是某一条具体的规则，而是几条工程原则。

1. Deny 最好直接隐藏工具，而不是靠报错来教育模型

只要模型知道一个工具存在，它就会不断尝试去靠近那条能力边界。直接从工具池里把它删掉，比“拒绝一次”要有效得多。

2. passthrough 很有用

权限系统里很多复杂的麻烦，都来自于工具被过早地逼着做决定。给工具一个“我没意见”的中间态，主干架构会变得干净很多。

3. safetyCheck 不该只有一个布尔值

Claude Code 用 classifierApprovable 把 safety check 又细分成了两层：

• 可以交给 classifier，让它结合上下文来判断。
• 不能交，必须由人工处理。

这比“所有敏感路径一律弹窗”更精细，也比“一律交给模型判断”更稳妥。

4. “Always allow” 不一定等于“加一条 allow rule”

很多系统的权限实现还停留在布尔开关上。但 Claude Code 会把用户的批准动作翻译成：

• 切换模式。
• 添加目录。
• 持久化规则。

这才像是在维护一个长期会话的权限状态，而不是在堆砌例外规则。

5. headless 需要单独建模

仅仅有一个 dontAsk 是不够的。你还需要一个类似 shouldA voidPermissionPrompts 的上下文字段，明确地告诉系统：这个 Agent 到底有没有能力展示 UI。

6. classifier 一定要有退路

Claude Code 很清醒地承认了一点：AI classifier 会误判、会超时、会超出上下文、会不可用。

所以它为此准备了：

• 快速路径，来减少不必要的调用次数。
• fail-open / fail-closed 策略。
• denial limit（拒绝次数限制）。
• headless abort 机制。

这比“调一个模型试试看”的做法要成熟得多。

九、最后总结

如果必须用一句话来概括 Claude Code 的权限系统，我们会说：

它不是一个“权限弹窗模块”，而是一套把规则引擎、工具的局部知识、模型分类器、Hooks、UI 和多 Agent 编排紧密结合在一起的运行时决策系统。

这套设计最厉害的地方，不在于某个具体的 classifier 或某条规则本身，而在于层与层之间分工非常清晰：

• 哪些判断必须前置。
• 哪些判断可以下放给工具。
• 哪些危险不能被绕过。
• 哪些场景该交给模型。
• 模型错了以后，又应该如何优雅地退回给人类。

从工程的成熟度来看，这比“多加几条白名单规则”高了不止一个层级。

如果你正在设计 Agent 的安全架构，这篇源码里最值得借鉴的，并不是它的具体实现，而是这套清晰的分层思路。