权限审核机制

1. 决策主链路#

工具执行前调用 useCanUseTool(),核心顺序是:

useCanUseTool()
  -> hasPermissionsToUseTool()
     -> hasPermissionsToUseToolInner()
        1. deny/ask rules
        2. tool.checkPermissions(input, context)
        3. bypass/acceptEdits/default/auto/dontAsk 等模式
        4. allow rules
        5. passthrough => ask
  -> allow: 直接执行
  -> deny: 记录并返回拒绝
  -> ask: 进入 interactive / coordinator / swarm / bridge / channel / hook / classifier 竞态

Tool 自己的 checkPermissions() 是安全第一道业务门,比如:

• Read/Edit/Write 走路径权限与危险目录检查。
• Bash 会解析命令、拆 subcommand、匹配 prefix rule、读写/危险语义检查、sandbox 判断。
• MCPTool 按 server/tool 名称检查 MCP 权限。
• SkillTool 单独检查技能名 allow/deny。
• AgentTool 检查 Agent(type) deny rule。

2. 权限规则来源与语法#

utils/permissions/permissions.ts 把 allow/deny/ask 规则按来源合并:

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

规则值经过 permissionRuleValueFromString() 解析,支持工具级规则、内容级规则,例如:

• Bash(git status:*)
• Edit(/some/path/**)
• Read(...)
• Agent(code-reviewer)
• Skill(commit) / Skill(review:*)
• mcp__server / mcp__server__tool

deny 优先级最高;ask 规则可强制弹窗;allow 在工具自身安全检查之后才生效。

3. 路径权限的重点安全点#

utils/permissions/filesystem.ts 的路径检查非常重:

• 同时检查原始路径与 symlink resolved path。
• UNC/network path、防 Windows ADS/短路径/long path prefix、shell expansion 变体。
• .git、.claude、shell profile、敏感配置等 safety check 会绕过 bypass/auto 的普通放行。
• read 规则和 edit 规则分开;显式 read deny/ask 优先于"edit implies read"。
• acceptEdits 只自动允许工作目录内写入。
• .claude/** 有 session-scoped 特殊放行,但不会永久广泛授权。

4. Bash 权限#

tools/BashTool/bashPermissions.ts 做了多层判断:

• 提取稳定 prefix,给用户建议可复用规则,避免保存整条临时命令。
• compound command 最多拆 MAX_SUBCOMMANDS_FOR_SECURITY_CHECK = 50,超过则 ask,防 CPU/事件循环卡死。
• 拦截危险 prefix:裸 shell、解释器、sudo、env、xargs、timeout 等。
• 对 read-only / write / destructive 语义做 AST 和静态规则判断。
• 支持 speculative classifier:弹窗前最多等 2 秒让分类器自动批准。
• sandbox 模式下部分 Bash 可自动允许。

5. ask 后的"竞态"处理#

hooks/toolPermission/handlers/interactiveHandler.ts 中,一个 ask 请求会同时等待多个可能结果:

• 本地 TUI 用户点击 allow/deny。
• bridge/CCR 远程网页返回。
• channel permission relay(Telegram/iMessage 等)返回 yes/no。
• PermissionRequest hooks 返回 allow/deny/ask。
• Bash classifier 异步批准。
• swarm worker 把权限请求转发给 leader。

所有路径用 claim()/resolve-once 保证只有第一个结果生效,并会取消其他 pending prompt。

6. permission modes#

主要模式:

• default:读工作目录通常允许,写/危险操作询问。
• acceptEdits:工作目录内编辑自动允许。
• bypassPermissions:跳过大部分权限,但 safetyCheck、content-specific ask/deny 仍可阻断。
• dontAsk:ask 转 deny,适合不可交互环境。
• auto：用分类器代替用户弹窗。默认两阶段 XML；HARD（外泄）翻不过，SOFT 才允许点名放行。AskUserQuestion 默认也交给分类器。失败 fail-closed。详见 Auto Mode 深度解析。
• plan:计划模式下部分权限策略变化,退出 plan 需要审批。