权限状态机与渐进式授权：从用户体验到子 Agent 代理

权限状态机与渐进式授权：从用户体验到子 Agent 代理

《Claude Code 架构解密》精读笔记 · 第08篇
覆盖章节：第5章后半（5.8-5.14）| 页码：p.127-140

导语

前两篇我们拆解了权限系统的"骨架"（14步决策树）和"智能层"（YOLO Classifier + 断路器）。但一个安全系统是否真正可用，最终取决于运行时的状态流转和用户的实际体验。

权限不只是"允许/拒绝"的二元判断。它是一种动态的信任关系——用户对 Agent 的信任会随着使用逐步建立，Agent 的自主权限也应该随之扩大。同时，当多个 Agent 协作时，权限如何在父子之间传播？当模式切换时，如何防止竞态条件？这些问题远比"写规则"复杂。

本篇是第5章权限深潜的收官之作，我们将深入：

1. 六种权限模式——从 default 到 dontAsk 的完整状态机
2. 渐进式信任 UX——如何在安全性和流畅性之间找到平衡
3. 子 Agent 的权限代理——多 Agent 场景下的权限传播
4. 8 个可复用设计模式——从判别联合到渐进式信任

一、权限模式状态机

1.1 六种权限模式

Claude Code 定义了六种权限模式，每种对"默认行为"有不同处理策略：

六种模式不是简单的枚举——它们是一个有结构的状态机：

Shift+Tab Shift+Tab default ────────→ acceptEdits ────────→ bypassPermissions │ │ │ /plan │ └──→ plan 模式 ←──────────────────────────────┘ 保存 prePlanMode = 之前的模式 退出时恢复到 prePlanMode auto 模式（与 acceptEdits/bypass 互相切换） 进入: stripDangerousPermissions() 退出: restoreDangerousPermissions() 门控: 断路器 + 设置 + 模型检查

几个关键设计：

• plan 模式是"保存点"模式：进入 plan 时记住之前的模式，退出时恢复。用户不会因为"先想再干"而丢失之前的信任设置。
• auto 模式有"门控"：不是任何用户都能进入 auto——需要通过verifyAutoModeGateAccess()检查权限。
• bypassPermissions 不是"无权限"：免疫检查（如危险路径保护）仍然生效，即使在这个模式下也无法修改.bashrc或.claude/settings.json。

1.2 模式切换的副作用处理

模式切换不是简单地改变一个枚举值——它涉及复杂的副作用。permissionSetup.ts中的transitionPermissionMode函数处理了这些副作用：

进入 Auto 模式：

1. 异步调用verifyAutoModeGateAccess()检查用户是否有权使用 Auto 模式
2. 调用stripDangerousPermissionsForAutoMode()临时剥离危险规则
3. 调用setAutoModeActive(true)激活分类器

退出 Auto 模式：

1. 调用restoreDangerousPermissions()恢复被剥离的规则
2. 调用setAutoModeActive(false)停用分类器
3. 设置退出标记setNeedsAutoModeExitAttachment()

进入 Plan 模式：

1. 保存当前模式到prePlanMode
2. 如果配置了useAutoModeDuringPlan，保持分类器激活

退出 Plan 模式：

1. 恢复到prePlanMode保存的模式
2. 清除prePlanMode

1.3 变换函数防竞态

Auto 模式的门控检查（verifyAutoModeGateAccess）是一个异步操作——它需要联网验证用户的访问权限。这里存在一个微妙的竞态条件：

时间 T0：用户按 Shift+Tab 进入 Auto 模式 → 开始异步门控检查 时间 T1：用户又按 Shift+Tab，切换回 default 模式 时间 T2：门控检查完成，返回结果 → 此时应该应用到哪个模式？

如果verifyAutoModeGateAccess直接返回修改后的上下文快照，T2 时刻应用的将是基于 T0 状态的快照——但用户在 T1 已经切换了模式，快照已经过时了。

Claude Code 的解决方案是让门控检查返回一个变换函数（Transform Function），而非预计算的结果：

// 概念示意consttransform=awaitverifyAutoModeGateAccess()// transform 是一个函数：(currentContext) => newContext// 应用时基于最新的 context，而非 T0 时刻的快照updateContext(prevContext=>transform(prevContext))

这是函数式编程中"延迟计算"思想在并发场景的实用应用——将"做什么"和"基于什么状态做"分离。React 的setState(prev => next)也采用了同样的模式。

💡核心洞察：当异步操作的结果需要应用到可变状态时，返回变换函数而非快照，是防止竞态的通用模式。

1.4 危险权限的剥离与恢复

Auto 模式有一个核心安全问题：如果用户在设置中配置了Bash(python:*)这样的宽泛 allow 规则，它会在分类器检查之前就允许执行python -c 'import os; os.system("rm -rf /")'——因为 allow 规则匹配在分类器调用之前。

解决方案是在进入 Auto 模式时，扫描并"剥离"所有被认定为危险的 allow 规则：

进入 Auto 模式： 1. 扫描所有 allow 规则 2. isDangerousBashPermission() 检测危险模式 3. 从上下文中剥离危险规则 → 保存到 strippedDangerousRules 4. 通知用户："以下规则在 Auto 模式中被暂时禁用" 退出 Auto 模式： 1. 从 strippedDangerousRules 恢复规则 2. 重新应用到上下文

"危险模式"的定义（dangerousPatterns.ts）包括：

• 30+ 种代码执行入口：python、node、bash、eval、exec、sudo 等
• 5 种匹配变体：精确匹配、前缀语法、通配符后缀、空格后缀、选项通配符
• 内部扩展的敏感工具：curl、wget、git、kubectl、aws 等

💡设计哲学：系统不是"禁止"用户配置宽泛规则——在非 Auto 模式下这些规则正常生效。只是在 Auto 模式这个特定场景下，因为分类器替代了人工判断，才需要额外的安全措施。剥离-恢复而非删除，尊重了用户的原始配置意图。

二、渐进式信任 UX

2.1 设计哲学：按需打断、记住偏好、透明可控

权限系统的后端再精巧，如果 UX 设计不好，用户要么"一路狂点 Yes"（失去安全意义），要么"受够了弹框关掉 Agent"（失去产品价值）。Claude Code 的权限 UX 围绕三个原则设计：

1. 按需打断——只在真正需要用户决策时才弹出权限对话框
2. 记住偏好——提供"下次不再询问"机制，减少重复打断
3. 透明可控——解释为什么需要权限，允许事后管理规则

2.2 三层组件架构

权限 UI 采用三层架构，将关注点清晰分离：

PermissionRequest（路由层） 根据 tool 类型分发到对应权限组件 PermissionDialog（容器层） 统一的对话框外壳：圆角顶边框 + 标题 + 内容区 PermissionPrompt（交互层） Select 组件 + 反馈输入 + 快捷键绑定

路由层通过permissionComponentForTool()实现"一个工具一个 UI"策略：

为什么不用一个通用的"确认框"处理所有工具？因为不同工具的风险谱和用户关注点完全不同：

• Bash 命令的风险跨度最大（从ls到rm -rf），需要最精细的 UI，包括命令高亮、前缀规则建议、破坏性命令警告
• 文件编辑的用户关注点是"改了什么"，最好的展示方式是 diff
• 网络请求的用户关注点是"访问了哪个 URL"

通用确认框会丢失这些上下文信息，迫使用户在缺乏信息的情况下做决策——这正是"权限疲劳"（Permission Fatigue）的根源。

2.3 Bash 权限的渐进式信任

Bash 权限对话框是整个 UX 中最精心设计的部分，体现了"渐进式信任"的核心思想：

Bash npm run build > Yes ← 一次性允许 Yes, and don't ask again for [npm run:*] ← 可编辑的前缀规则 No ← 拒绝

四个选项对应四种信任级别：

可编辑前缀规则是一个极为精巧的设计。当系统检测到命令符合"主命令+子命令"模式时（如npm run build），会预填充一个可编辑的通配符规则npm run:*。用户可以：

• 保留默认npm run:*→ 允许所有 npm run 子命令
• 缩小范围npm run build→ 只允许这个特定命令
• 扩大范围npm:*→ 允许所有 npm 命令

这种设计让用户主动参与安全决策，而非被动接受系统的二选一。

前缀提取算法（getSimpleCommandPrefix）有一个安全防护：BARE_SHELL_PREFIXES集合阻止生成过于宽泛的规则。例如，当命令是bash -c "rm -rf /"时，不会生成bash:*这样的规则——因为bash:*允许执行任何 shell 脚本，风险不可控。

2.4 Diff 驱动的文件权限决策

文件编辑权限不展示原始的编辑指令，而是展示变更的 diff：

Edit src/config.ts - const timeout = 5000 + const timeout = 10000 > Yes Yes, allow all edits during this session No

类似地，当 Bash 命令是sed -i 's/old/new/' file格式时，系统不展示 sed 命令本身，而是路由到SedEditPermissionRequest，以 diff 形式展示变更。

💡UX 原则：展示用户关心的信息，而非技术细节。用户关心的是"文件会怎么改"，而非 sed 命令的正则语法。

当用户在 VS Code/Cursor 等 IDE 中使用 Claude Code 时，文件编辑权限请求会通过 RPC 自动在 IDE 中打开 diff 视图。用户可以在最熟悉的编辑器环境中审阅变更，甚至修改 Claude 的编辑后再接受——这让用户从**“审批者"升级为"协作者”**。

2.5 Tab 键反馈：渐进式披露的典范

权限对话框中有一个隐藏的高级功能——Tab 键展开文本输入框：

> Yes ← 聚焦时显示 "Tab to amend" tell Claude what to ← 按 Tab 后展开输入框 do next No tell Claude what to ← 拒绝时的反馈 do differently

两个细节：

1. 上下文敏感的占位符文案——接受时提示"tell Claude what to do next"（引导下一步），拒绝时提示"tell Claude what to do differently"（引导替代方案）。微妙的措辞差异引导用户提供不同类型的反馈。
2. 空提交取消——在输入模式下空提交会退出输入模式，而非提交空反馈。防止了意外提交。

这是**渐进式披露（Progressive Disclosure）**在 CLI 环境中的优秀实践：默认展示简洁的选项，高级功能通过发现性较弱但不碍事的方式提供。

2.6 AI 解释与三层透明度

权限对话框提供了三层透明度机制：

① Ctrl+E——AI 操作解释

用户按 Ctrl+E 后，系统调用 Haiku 模型（小型快速模型）来生成操作的风险评估：

- Explanation ───────────────────────── | Med risk | | Removes all installed packages and | | reinstalls them from scratch. | | Reasoning: I need to resolve | | dependency conflicts that can't be | | fixed incrementally. | | Risk: Temporary loss of dependencies | ────────────────────────────────────────

三级风险着色（LOW、MEDIUM、HIGH）让用户无需阅读详细文字就能快速判断风险程度。

这个功能是懒加载的——仅在用户按 Ctrl+E 时才调用 AI，避免每次权限请求都消耗 token。加载时展示 shimmer 动画（字符逐个高亮的流动效果），视觉上暗示"AI 正在思考"。

② 规则溯源展示

每个权限对话框解释"为什么需要确认"：

Matched ask rule: Bash(rm:*) (/permissions to update rules)

不仅告诉用户"需要确认"，还告诉"为什么需要确认"和"如何修改这个行为"。配置提示（/permissions）直接指向修改入口。

③ Ctrl+D——调试信息

高级用户按 Ctrl+D 可以看到完整的权限决策路径，用于排查复杂的权限问题。

2.7 分类器自动审批的 UX 反馈

当启用 Auto 模式时，AI 分类器在后台异步运行。UI 层面的处理：

1. 等待中：标题区域显示 shimmer 动画，文字"Attempting to auto-approve…"以 20fps 闪烁
2. 自动通过：显示勾选标记，命令自动执行
3. 用户覆盖：即使分类器自动通过，用户仍可手动操作

shimmer 动画被提取到独立的classifierCheckingSubtitle组件，避免 20fps 的时钟刷新导致整个对话框重渲染——这是性能感知影响 UX 的典型例子（详见第11章终端渲染引擎的性能优化策略）。

2.8 离席通知

当权限对话框等待用户响应超过 6 秒且无用户交互时，系统发送桌面通知：

constDEFAULT_INTERACTION_THRESHOLD_MS=6000;useNotifyAfterTimeout(notificationMessage,"permission_prompt");

通知消息根据工具类型定制：Plan Mode 提示"Claude Code needs your approval for the plan"，其他工具提示"Claude needs your permission to use {toolName}"。定制的通知让用户即使在其他应用中也能快速判断是否需要立即回来。

三、权限规则管理：事后可控

3.1 /permissions 命令

权限规则不仅可以在对话中实时创建，还可以通过/permissions命令进行事后管理：

allow ─ ask ─ deny │ workspace ─ recent ───────────────────────────────────────── Bash(npm run:*) localSettings Bash(git:*) projectSettings Read userSettings Edit(*.md) session [a] Add rule [d] Delete rule [/] Search

五个标签页覆盖了权限管理的所有维度：

• allow/ask/deny：查看和管理三种行为的规则
• workspace：管理额外的工作目录
• recent：查看 Auto 模式最近拒绝的命令，支持快速授权

3.2 规则保存位置的选择

添加新规则时，系统询问保存位置：

projectSettings 和 localSettings 的分层让个人偏好与团队规范共存——projectSettings（.claude/settings.json）提交到 Git，团队成员共享；localSettings（.claude/settings.local.json）被 gitignore，存放个人偏好。

3.3 阴影规则检测

当用户添加新的 allow 规则时，系统调用detectUnreachableRules()检测是否被已有的 ask/deny 规则遮蔽。

例如，如果用户添加Bash(rm:*) → allow，但已经存在Bash(rm:*) → deny，系统会警告：“此规则被优先级更高的 deny 规则遮蔽，不会生效。”

这防止了一个常见的用户困惑：“我明明添加了规则，为什么不生效？”

四、多 Agent 场景的权限处理

4.1 子 Agent 的权限继承

当主 Agent 派生子 Agent 执行任务时（详见第6章），权限如何传递？Claude Code 的策略是：

• 子 Agent 继承父 Agent 的权限上下文（包括所有规则和当前模式）
• 子 Agent 不能自行提升权限级别
• 子 Agent 的权限请求会上报到主会话的 UI 中

这三个规则形成了一个权限下降原则——权限只能被继承或限制，不能被提升。这防止了子 Agent 通过"委托"来绕过父 Agent 的权限限制。

4.2 Worker Badge

当权限请求来自子 Agent 时，对话框标题区域显示 Worker 徽章：

Bash @test-runner npm test

徽章标识了权限请求的来源——是主 Agent 自己发出的，还是某个子 Agent 的请求。这让用户可以基于上下文做出更明智的决策——例如，一个名为@test-runner的子 Agent 执行npm test可能比主 Agent 直接执行更可信。

五、设计模式提炼

第5章蕴含了 8 个可复用的设计模式，值得系统梳理：

模式一：判别联合 + 决策溯源

• 问题：决策系统需要返回不同类型的结果，且每个结果需要携带不同的附加信息
• 方案：使用 TypeScript 判别联合类型，按 behavior 字段区分，每种变体携带特定的附加数据。同时为每个决策附加 decisionReason，形成完整的审计链
• 适用场景：任何需要可解释性的决策系统——权限、审批、推荐引擎

模式二：分级配置合并（Layered Config Merge）

• 问题：配置来自多个来源（个人、团队、企业），可能存在冲突
• 方案：定义明确的来源优先级序列，按来源分组存储规则（而非扁平化），支持策略级别的全局覆盖
• 适用场景：IDE 插件、CLI 工具（多层 dotfile）、企业 SaaS

模式三：快路径/慢路径分离

• 问题：AI 分类需要兼顾延迟和准确性
• 方案：Stage 1 用极少的 token 做快速判断；只有"不确定"时才进入 Stage 2 的深度推理
• 适用场景：任何需要 LLM 辅助决策的系统——内容审核、意图识别、异常检测

模式四：断路器防 AI 卡死

• 问题：AI 分类器可能在某些上下文下产生系统性偏见，反复拒绝合理操作
• 方案：双重计数器（连续拒绝 + 总计拒绝），任一超限则回退到人工确认
• 适用场景：任何依赖 AI 自动决策的系统

模式五：变换函数防竞态

• 问题：异步操作的结果需要应用到可变状态，但状态可能在异步期间被修改
• 方案：异步操作返回变换函数而非快照，应用时基于最新状态计算
• 适用场景：React setState、任何异步状态更新场景

模式六：危险权限的剥离-恢复

• 问题：某些模式下需要临时限制用户配置的宽泛权限，但不应永久删除
• 方案：进入限制模式时将危险规则移入暂存区，退出时恢复
• 适用场景：需要在不同安全级别间切换的系统

模式七：渐进式信任 UX

• 问题：安全确认框太多会导致"权限疲劳"，太少会丧失安全性
• 方案：提供多级信任选项（一次性 → 模式化 → 持久化），让用户逐步建立信任关系。可编辑规则让用户参与安全决策
• 适用场景：任何需要用户审批的 CLI/GUI 工具

模式八：纵深防御漏斗

• 问题：单一安全检查不够，但多层检查的延迟如何控制？
• 方案：按成本从低到高排列检查层，每一层只处理上一层无法判定的请求，形成漏斗式过滤
• 适用场景：任何需要多层安全检查的系统——WAF、API 网关、权限网关

模式速查表

横向对比：三大框架的权限模型

Claude Code 的独特之处：

1. AI 分类器集成——用 LLM 的语义理解补充规则引擎的覆盖盲区
2. 8 层优先级——支持从个人到企业的完整治理链
3. 工具专属 UX——每种工具有定制的权限交互界面
4. 安全免疫设计——关键路径不受 bypass 模式影响
5. 权限下降原则——子 Agent 只能继承或受限，不能提升

这些特性使得 Claude Code 的权限系统不只是一个简单的门控层，而是一个完整的"Agent 治理框架"。

实战启示

启示一：安全与体验不是零和博弈

"越安全越难用"是一个常见但错误的假设。Claude Code 的渐进式信任设计证明了安全性和流畅性可以共存：

• Bash 四选项让用户在"一次性放行"和"持久化规则"之间有精细选择
• 可编辑前缀规则让用户从被动审批者变为主动规则制定者
• Diff 驱动决策展示用户关心的信息（变更内容），而非技术细节（sed 语法）
• Tab 反馈让高级用户有更多控制，但不增加初级用户的认知负担

核心原则：好的安全 UX 不是"减少确认框"，而是"让每个确认框都有价值"。

启示二：权限下降原则是 Agent 治理的基石

子 Agent 只能继承或受限权限，不能提升——这个"单向阀"防止了一系列攻击：

• 子 Agent 不能通过"委托"绕过父 Agent 的权限限制
• 子 Agent 不能自主切换到更宽松的权限模式
• 即使子 Agent 被恶意 Prompt 注入，其破坏范围也被权限边界限制

核心原则：权限的传播方向应该是"从高到低"——从用户到 Agent，从父 Agent 到子 Agent。永远不应该有"逆向提升"的路径。

启示三：剥离-恢复优于删除-重建

Auto 模式临时剥离危险规则，退出时恢复——而非直接删除让用户重新配置。这个设计选择体现了一个重要的工程原则：对用户配置的修改应该是可逆的。

删除-重建的问题在于：用户可能记不住之前的配置，重建可能引入错误或遗漏。而剥离-恢复确保了用户的原始意图不被丢失——即使他们频繁在模式之间切换。

下期预告

第09篇：让 AI 带 AI——Fork-and-Delegate 多 Agent 协作架构全解

第5章权限深潜到此结束！接下来进入阶段四（协作与上下文篇），第09篇将深入第6章前半（6.1-6.5）：

• Fork-and-Delegate——轻量级并行分叉的机制与权衡
• Agent Type Registry——动态类型注册的扩展性设计
• Tool Sandboxing——子 Agent 的工具权限隔离
• Scoped Memory——分区化上下文记忆，防止信息串扰

从"一个 Agent 的权限"到"多个 Agent 的协作"，架构的复杂度将再次跃升。