权限控制

概述

Claude Code 拥有一个多层权限系统，确保工具执行的安全性。权限决策从规则匹配到 ML 分类器，层层把关。

Source: src/types/permissions.ts, src/utils/permissions/

权限模式

type PermissionMode =
  | 'default'           // 每次都询问用户
  | 'plan'              // 仅在计划模式中询问
  | 'dontAsk'           // 跳过权限检查
  | 'bypassPermissions' // 自动允许危险操作
  | 'acceptEdits'       // 自动接受文件编辑
  | 'auto'              // 基于分类器自动审批

权限决策流程

权限规则

规则来源

type PermissionRuleSource =
  | 'userSettings'     // ~/.claude/settings.json
  | 'projectSettings'  // /project/.claude/settings.json
  | 'localSettings'    // .claude/settings.local.json
  | 'flagSettings'     // 远程功能标志
  | 'policySettings'   // 企业策略
  | 'cliArg'           // 命令行参数
  | 'command'          // 斜杠命令
  | 'session'          // 会话内规则

规则格式

type PermissionRule = {
  source: PermissionRuleSource
  ruleBehavior: 'allow' | 'deny' | 'ask'
  ruleValue: {
    toolName: string      // 工具名或模式
    ruleContent?: string  // 可选：内容模式
  }
}

规则匹配示例

规则	匹配
"Bash"	所有 BashTool 调用
"Bash(git *)"	git clone, git push, ...
"Bash(npm install)"	仅 npm install
"FileEdit(package.json)"	编辑 package.json
"FileEdit(*)"	所有文件编辑

通配符匹配使用 glob 风格语法（* 匹配任意序列）。

工具级权限检查

每个工具通过 checkPermissions() 实现特定的权限逻辑：

// BashTool 的权限检查
async checkPermissions(input, context) {
  // 调用专门的 bash 权限模块
  return bashToolHasPermission(input.command, context.toolPermissionContext);
}

// FileEditTool 的权限检查
async checkPermissions(input, context) {
  return checkWritePermissionForTool(
    FileEditTool, input, context.toolPermissionContext
  );
}

// GrepTool 的权限检查
async checkPermissions(input, context) {
  return checkReadPermissionForTool(
    GrepTool, input, context.toolPermissionContext
  );
}

完整执行管线

Source: src/utils/toolExecution.ts

权限上下文

type ToolPermissionContext = {
  mode: PermissionMode
  alwaysAllowRules: { [source]: PermissionRule[] }
  alwaysDenyRules: { [source]: PermissionRule[] }
  alwaysAskRules: { [source]: PermissionRule[] }
  additionalWorkingDirectories: Map<string, AdditionalWorkingDirectory>
  isBypassPermissionsModeAvailable: boolean
}

BashTool 的安全模块

BashTool 拥有最复杂的权限系统：

模块	大小	功能
bashPermissions.ts	98KB	模式匹配、通配符规则
bashSecurity.ts	102KB	AST 解析，检测危险命令
readOnlyValidation.ts	68KB	正则检测写操作
sedValidation.ts	21KB	解析 sed 编辑操作
pathValidation.ts	43KB	路径范围检查

下一步

• 内置工具详解 — 代表性工具的实现分析