权限系统

一、系统概述

每次 Claude 想要使用工具（运行 bash 命令、编辑文件、调用 MCP 端点）时，权限系统都会运行多步骤决策管道。 该管道产生以下三种结果之一：

管道的三个输入是： tool 经要求，其 input （例如 shell 命令）和当前 权限上下文 （模式、所有来源的规则、会话状态）。

2. 决策流程

该管道实施于 hasPermissionsToUseToolInner() in permissions.ts。 步骤已编号以匹配源中的内联注释。

每个编号的步骤直接对应于 // 1a, 1b, 1c... 中的评论 permissions.ts，使源代码自我记录。

3. 5种权限模式

该模式控制对任何管道执行哪个分支 ask 结果。 它存储在 toolPermissionContext.mode.

const PERMISSION_MODE_CONFIG = {
  default:           { title: 'Default',            color: 'text',       external: 'default' },
  plan:              { title: 'Plan Mode',          color: 'planMode',  external: 'plan' },
  acceptEdits:       { title: 'Accept edits',       color: 'autoAccept', external: 'acceptEdits' },
  bypassPermissions: { title: 'Bypass Permissions', color: 'error',      external: 'bypassPermissions' },
  dontAsk:           { title: "Don't Ask",          color: 'error',      external: 'dontAsk' },
  // auto is ANT-only, enabled by feature('TRANSCRIPT_CLASSIFIER')
  auto:              { title: 'Auto mode',          color: 'warning',    external: 'default' },
}

4. 规则匹配系统

每个规则都是以下形式的字符串 ToolName or ToolName(content)，存储在允许/拒绝/询问列表中。 解析由以下处理： permissionRuleParser.ts.

规则字符串格式

// Tool-wide rule — no content
"Bash"                 // match any Bash command
"mcp__myserver"        // match all tools from myserver MCP
"mcp__myserver__*"     // same, wildcard variant

// Content-specific rules (three types)
"Bash(npm install)"    // exact match
"Bash(npm:*)"          // legacy prefix — matches anything starting with "npm"
"Bash(git add *)"      // wildcard — * matches any sequence of chars
"Bash(git ad\* file)"  // escaped * — matches literal asterisk

三种内容规则类型（shellRuleMatching.ts)

// Rule: "git *"
// Matches both:
"git add"     // command with argument
"git"         // bare command — optional trailing match
// This aligns wildcard semantics with legacy prefix "git:*"

// "Bash(python -c \"print\\(1\\)\")"  →
function permissionRuleValueFromString(ruleString) {
  const openIdx  = findFirstUnescapedChar(ruleString, '(')
  const closeIdx = findLastUnescapedChar(ruleString, ')')

  if (openIdx === -1) return { toolName: normalizeLegacyToolName(ruleString) }

  const toolName   = ruleString.substring(0, openIdx)
  const rawContent = ruleString.substring(openIdx + 1, closeIdx)

  // Empty or standalone "*" → treat as tool-wide rule
  if (rawContent === '' || rawContent === '*')
    return { toolName: normalizeLegacyToolName(toolName) }

  return { toolName: normalizeLegacyToolName(toolName), ruleContent: unescapeRuleContent(rawContent) }
}

const LEGACY_TOOL_NAME_ALIASES = {
  Task:            AGENT_TOOL_NAME,     // → "Agent"
  KillShell:       TASK_STOP_TOOL_NAME, // → "TaskStop"
  AgentOutputTool: TASK_OUTPUT_TOOL_NAME,
  BashOutputTool:  TASK_OUTPUT_TOOL_NAME,
}

5. 规则来源和优先级

规则从多个源加载并合并。 什么时候 allowManagedPermissionRulesOnly 设置于 policySettings，所有非政策来源都被忽略。

设置 JSON 格式

{
  "permissions": {
    "allow": ["Bash(npm:*)", "Bash(git status)"],
    "deny":  ["WebFetch"],
    "ask":   ["Bash(npm publish:*)"]
  }
}

6. 自动模式和人工智能分类器

当模式为 auto，Claude 没有提示用户，而是通过辅助 Claude 模型（“YOLO 分类器”）路由不明确的工具使用，该模型根据描述允许和禁止的操作类别的系统提示来决定允许/拒绝。

快速路径（跳过分类器 API 调用）

1. 不可分类的安全检查： 写信给 .git/ 或 shell 配置 - 即使分类器也不会自动批准。
2. 接受编辑快速路径： 如果该工具被允许进入 acceptEdits 模式（CWD 内的文件编辑），立即允许而不调用分类器。
3. 安全工具白名单： 只读工具（FileRead、Grep、Glob、LSP、TodoWrite、sleep 等）完全跳过分类器。 该列表位于 classifierDecision.ts.

const SAFE_YOLO_ALLOWLISTED_TOOLS = new Set([
  // Read-only file operations
  FILE_READ_TOOL_NAME,
  GREP_TOOL_NAME, GLOB_TOOL_NAME, LSP_TOOL_NAME,
  TOOL_SEARCH_TOOL_NAME, LIST_MCP_RESOURCES_TOOL_NAME,
  // Task management (metadata only)
  TODO_WRITE_TOOL_NAME,
  TASK_CREATE_TOOL_NAME, TASK_GET_TOOL_NAME, TASK_UPDATE_TOOL_NAME,
  TASK_LIST_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_TOOL_NAME,
  // Plan mode / UI
  ASK_USER_QUESTION_TOOL_NAME,
  ENTER_PLAN_MODE_TOOL_NAME, EXIT_PLAN_MODE_TOOL_NAME,
  // Misc
  SLEEP_TOOL_NAME,
  YOLO_CLASSIFIER_TOOL_NAME, // the classifier itself
])

拒绝追踪

分类器跟踪连续和完全拒绝以检测失控循环。 当达到限制时，它会回退到提示用户：

const DENIAL_LIMITS = {
  maxConsecutive: 3,   // 3 denials in a row → prompt user
  maxTotal:      20,   // 20 total denials this session → prompt user
}

function shouldFallbackToPrompting(state) {
  return state.consecutiveDenials >= DENIAL_LIMITS.maxConsecutive
      || state.totalDenials       >= DENIAL_LIMITS.maxTotal
}

成功使用工具会重置连续计数（但不会重置总数）。

进入自动模式时去除危险图案

进入自动模式时， permissionSetup.ts strips 允许允许 Claude 完全绕过分类器的规则：

const DANGEROUS_BASH_PATTERNS = [
  // Script interpreters (arbitrary code execution)
  'python', 'node', 'deno', 'ruby', 'perl', 'php', 'lua',
  // Package runners
  'npx', 'bunx', 'npm run', 'yarn run', 'bun run',
  // Shells & execution multipliers
  'bash', 'sh', 'eval', 'exec', 'sudo', 'xargs',
  // ... plus ANT-only: gh, curl, wget, git, kubectl, aws, gcloud
]

激活自动模式时，匹配这些模式的现有允许规则将从上下文中删除，确保分类器看到所有 shell 命令。

分类器失败模式

7. 影子规则检测

权限规则可以是 unreachable - 写得正确但从未评估过，因为更通用的规则首先被触发。 shadowedRuleDetection.ts 检测并报告这些冲突。

// Example: allow rule is deny-shadowed
permissions.deny  = ["Bash"]      // ← fires first, blocks everything
permissions.allow = ["Bash(ls:*)"] // ← never reached → shadowed!

// Fix: remove the tool-wide "Bash" from deny,
// or add more specific deny rules instead.

8. 权限解释器

当出现权限提示时， permissionExplainer.ts 进行侧面 API 调用（使用当前模型）以生成人类可读的解释，说明命令的作用、Claude 为何要运行它以及风险级别。

// Structured output schema returned by the explainer model
{
  explanation: "What this command does (1-2 sentences)",
  reasoning:   "I need to check the file contents",  // starts with "I"
  risk:        "Modifies files outside the working directory",
  riskLevel:   "HIGH"  // LOW | MEDIUM | HIGH
}

• Uses sideQuery() — 单独的 API 调用，不计入主会话的令牌总数。
• 该模型被迫使用特定工具（explain_command）以保证结构化输出。
• 可以通过禁用 permissionExplainerEnabled: false 在全局配置中。
• 包括最多 1,000 个字符的最近对话上下文，因此“为什么”答案基于 Claude 正在做的事情。

9. 要点

• 拒绝规则总是首先检查 — 在旁路模式之前、在允许规则之前、在特定于工具的逻辑之前。 它们是唯一的无条件块。
• bypassPermissions 并不是真正无条件的 - 它无法绕过拒绝规则、特定于内容的询问规则、受保护路径的安全检查或需要用户交互的工具。
• 安全检查路径在设计上不受旁路影响 — .git/, .claude/, .vscode/，并且 shell 配置文件始终提示，防止静默配置损坏。
• 规则的特殊性对影子很重要 — 工具范围内的拒绝或询问规则会默默地使该工具的所有特定允许规则无法访问。 阴影探测器对此发出警告。
• 自动模式具有分层快速路径 — 安全白名单 → 接受编辑检查 → 分类器。 只有最后一步需要 API 调用。
• 分类器拒绝限制可防止无限循环 — 在连续 3 次或总共 20 次分类器拒绝后，系统会回退到提示人类。
• 规则源形成分层覆盖系统 — 企业策略可以完全锁定规则 allowManagedPermissionRulesOnly，防止任何用户覆盖。
• 旧规则名称会自动迁移 — 使用旧工具名称的规则（Task, KillShell) 在解析时被透明地重写为当前规范名称。