# Claude Code 权限系统详解

## 概述

Claude Code 的权限系统管理工具调用的授权流程。当 Claude 尝试执行危险操作（如运行 Bash 命令、写入文件）时，系统会请求用户确认。权限系统支持多种授权模式和来源，确保用户对工具执行有完全控制。

---

## 核心架构

```
┌─────────────────────────────────────────────────────────────────┐
│                     权限请求入口                                 │
│                                                                  │
│  hasPermissionsToUseTool(tool, input, context, message, id)    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    权限模式检查 (PermissionMode)                 │
│                                                                  │
│  default | plan | bypassPermissions | auto | localAssistant     │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
      ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
      │   Coordinator │ │  Interactive │ │ Swarm Worker │
      │    Handler   │ │   Handler    │ │   Handler    │
      └──────────────┘ └──────────────┘ └──────────────┘
              │               │               │
              └───────────────┼───────────────┘
                              ▼
              ┌──────────────────────────────────────┐
              │           权限决策结果               │
              │                                      │
              │  allow | deny | ask | skip          │
              └──────────────────────────────────────┘
```

---

## 1. 权限模式 (PermissionMode)

**文件位置**: `src/utils/permissions/PermissionMode.ts`

### 模式类型

```typescript
type PermissionMode =
  | 'default'        // 标准交互式权限确认
  | 'plan'           // 计划模式，只读操作
  | 'bypassPermissions'  // 跳过所有权限检查
  | 'auto'           // 自动批准基于分类器
  | 'localAssistant' // 本地助手模式
```

### 模式转换

```typescript
export function transitionPermissionMode(
  from: PermissionMode,
  to: PermissionMode,
  options?: { skipAutoGate?: boolean }
): { ok: true } | { ok: false; error: string }
```

---

## 2. PermissionContext - 权限上下文

**文件位置**: `src/hooks/toolPermission/PermissionContext.ts`

### 创建权限上下文

```typescript
function createPermissionContext(
  tool: ToolType,
  input: Record<string, unknown>,
  toolUseContext: ToolUseContext,
  assistantMessage: AssistantMessage,
  toolUseID: string,
  setToolPermissionContext: (context: ToolPermissionContext) => void,
  queueOps?: PermissionQueueOps,
)
```

### 上下文方法

```typescript
type PermissionContext = {
  // 工具信息
  tool: ToolType
  input: Record<string, unknown>
  toolUseContext: ToolUseContext
  assistantMessage: AssistantMessage
  messageId: string
  toolUseID: string

  // 日志记录
  logDecision(args: PermissionDecisionArgs, opts?: {...}): void
  logCancelled(): void

  // 权限持久化
  async persistPermissions(updates: PermissionUpdate[]): Promise<boolean>

  // 决策构建
  buildAllow(
    updatedInput: Record<string, unknown>,
    opts?: {...}
  ): PermissionAllowDecision

  buildDeny(
    message: string,
    decisionReason: PermissionDecisionReason
  ): PermissionDenyDecision

  // 用户处理
  async handleUserAllow(
    updatedInput: Record<string, unknown>,
    permissionUpdates: PermissionUpdate[],
    feedback?: string,
    ...
  ): Promise<PermissionAllowDecision>

  // Hook 执行
  async runHooks(
    permissionMode: string | undefined,
    suggestions: PermissionUpdate[] | undefined,
    updatedInput?: Record<string, unknown>,
    ...
  ): Promise<PermissionDecision | null>

  // 分类器尝试
  async tryClassifier(
    pendingClassifierCheck: PendingClassifierCheck | undefined,
    updatedInput: Record<string, unknown> | undefined
  ): Promise<PermissionDecision | null>

  // 队列操作
  pushToQueue(item: ToolUseConfirm): void
  removeFromQueue(): void
  updateQueueItem(patch: Partial<ToolUseConfirm>): void

  // 中止处理
  resolveIfAbort(resolve: (decision: PermissionDecision) => void): boolean
  cancelAndAbort(
    feedback?: string,
    isAbort?: boolean,
    contentBlocks?: ContentBlockParam[]
  ): PermissionDecision
}
```

---

## 3. 权限决策类型

**文件位置**: `src/types/permissions.ts`

### 决策类型

```typescript
type PermissionDecision =
  | { behavior: 'allow'; updatedInput?: Record<string, unknown>; ... }
  | { behavior: 'deny'; message: string; ... }
  | { behavior: 'ask' }
  | { behavior: 'skip' }
```

### 决策来源

```typescript
type PermissionDecisionSource =
  | { type: 'hook'; permanent?: boolean }
  | { type: 'user'; permanent: boolean }
  | { type: 'classifier' }
  | 'config'  // 配置自动允许
```

### 待处理分类器检查

```typescript
type PendingClassifierCheck = {
  input: Record<string, unknown>
  command: string
  // ...
}
```

---

## 4. 权限处理器

### 4.1 Coordinator Handler

**文件位置**: `src/hooks/toolPermission/handlers/coordinatorHandler.ts`

用于协调者工作进程（coordinator worker）的权限处理流程。

```typescript
async function handleCoordinatorPermission(
  params: CoordinatorPermissionParams
): Promise<PermissionDecision | null>
```

**处理流程**:

1. **尝试权限 Hooks**（快速，本地）
   ```typescript
   const hookResult = await ctx.runHooks(
     permissionMode,
     suggestions,
     updatedInput
   )
   if (hookResult) return hookResult
   ```

2. **尝试分类器**（慢速，推理）
   ```typescript
   const classifierResult = feature('BASH_CLASSIFIER')
     ? await ctx.tryClassifier?.(pendingClassifierCheck, updatedInput)
     : null
   if (classifierResult) return classifierResult
   ```

3. **降级到交互式对话框**
   ```typescript
   return null  // 交给交互式处理
   ```

### 4.2 Interactive Handler

**文件位置**: `src/hooks/toolPermission/handlers/interactiveHandler.ts`

用于主代理的交互式权限处理。

```typescript
function handleInteractivePermission(
  params: InteractivePermissionParams,
  resolve: (decision: PermissionDecision) => void,
): void
```

**处理流程**:

1. **推送确认队列项**
   ```typescript
   ctx.pushToQueue({
     assistantMessage,
     tool,
     description,
     input: displayInput,
     toolUseID,
     permissionResult: result,
     permissionPromptStartTimeMs,
     onUserInteraction: () => { ... },
     onAbort: () => { ... },
     onAllow: () => { ... },
     onReject: () => { ... },
     recheckPermission: () => { ... },
   })
   ```

2. **桥接权限转发**（远程控制）
   ```typescript
   if (bridgeCallbacks && bridgeRequestId) {
     bridgeCallbacks.sendRequest(
       bridgeRequestId,
       ctx.tool.name,
       displayInput,
       ctx.toolUseID,
       description,
       result.suggestions,
       result.blockedPath
     )
   }
   ```

3. **通道权限转发**（KAIROS）
   ```typescript
   if (channelCallbacks && !ctx.tool.requiresUserInteraction?.()) {
     // 发送到通道（Telegram, iMessage 等）
     client.notification({
       method: CHANNEL_PERMISSION_REQUEST_METHOD,
       params
     })
   }
   ```

4. **异步 Hook 执行**
   ```typescript
   void (async () => {
     const hookDecision = await ctx.runHooks(...)
     if (hookDecision && claim()) {
       resolveOnce(hookDecision)
     }
   })()
   ```

5. **异步分类器执行**
   ```typescript
   if (feature('BASH_CLASSIFIER') && result.pendingClassifierCheck) {
     setClassifierChecking(ctx.toolUseID)
     void executeAsyncClassifierCheck(...)
   }
   ```

### 4.3 Swarm Worker Handler

**文件位置**: `src/hooks/toolPermission/handlers/swarmWorkerHandler.ts`

用于 Swarm Worker 的权限处理（简化的仅拒绝处理）。

---

## 5. 权限回调 (Bridge Permission Callbacks)

**文件位置**: `src/bridge/bridgePermissionCallbacks.ts`

### 回调接口

```typescript
type BridgePermissionCallbacks = {
  sendRequest(
    requestId: string,
    toolName: string,
    input: Record<string, unknown>,
    toolUseId: string,
    description: string,
    permissionSuggestions?: PermissionUpdate[],
    blockedPath?: string,
  ): void

  sendResponse(requestId: string, response: BridgePermissionResponse): void

  cancelRequest(requestId: string): void

  onResponse(
    requestId: string,
    handler: (response: BridgePermissionResponse) => void,
  ): () => void
}
```

### 权限响应

```typescript
type BridgePermissionResponse = {
  behavior: 'allow' | 'deny'
  updatedInput?: Record<string, unknown>
  updatedPermissions?: PermissionUpdate[]
  message?: string
}
```

---

## 6. 权限规则管理

### 6.1 PermissionUpdate

**文件位置**: `src/utils/permissions/PermissionUpdateSchema.ts`

```typescript
type PermissionUpdate = {
  destination: 'alwaysAllowRules' | 'alwaysDenyRules' | 'command'
  rule: {
    tool: string
    input?: Record<string, unknown>
    matchers?: InputMatcher[]
  }
  Permanente: boolean
}
```

### 6.2 规则应用

```typescript
export function applyPermissionUpdates(
  context: ToolPermissionContext,
  updates: PermissionUpdate[]
): ToolPermissionContext
```

### 6.3 规则持久化

```typescript
export function persistPermissionUpdates(updates: PermissionUpdate[]): void
export function supportsPersistence(
  destination: 'alwaysAllowRules' | 'alwaysDenyRules' | 'command'
): boolean
```

---

## 7. Bash 分类器

**文件位置**: `src/tools/BashTool/bashPermissions.ts`

### 分类器决策

```typescript
type ClassifierDecision =
  | { type: 'classifier'; classifier: 'auto-mode'; reason: string }
  | { type: 'classifier'; classifier: 'pattern-match'; reason: string }
  | { type: 'user-defined'; reason: string }
  | { type: 'deny'; reason: string }
```

### 分类器检查

```typescript
export async function awaitClassifierAutoApproval(
  pendingClassifierCheck: PendingClassifierCheck,
  signal: AbortSignal,
  isNonInteractiveSession: boolean,
): Promise<ClassifierDecision | null>
```

---

## 8. 权限日志

**文件位置**: `src/hooks/toolPermission/permissionLogging.ts`

### 日志函数

```typescript
export function logPermissionDecision(
  args: PermissionDecisionArgs,
  decision: {
    decision: 'accept' | 'reject'
    source: PermissionApprovalSource | PermissionRejectionSource
  },
  permissionPromptStartTimeMs?: number
): void
```

### 事件类型

```typescript
// 接受
logEvent('tengu_tool_permission_accepted', {...})
logEvent('tengu_tool_permission_auto_approved', {...})

// 拒绝
logEvent('tengu_tool_permission_rejected', {...})
logEvent('tengu_tool_use_cancelled', {...})
```

---

## 9. 权限检查入口

**文件位置**: `src/utils/permissions/permissions.ts`

### 主检查函数

```typescript
export async function hasPermissionsToUseTool(
  tool: Tool,
  input: Record<string, unknown>,
  toolUseContext: ToolUseContext,
  assistantMessage: AssistantMessage,
  toolUseID: string,
): Promise<PermissionDecision>
```

**决策流程**:

1. **模式检查**
   - `bypassPermissions`: 直接允许
   - `plan`: 计划模式规则
   - `auto`: 分类器自动决策

2. **规则匹配**
   - `alwaysAllowRules`: 匹配则允许
   - `alwaysDenyRules`: 匹配则拒绝

3. **会话状态**
   - 非交互式会话可能有不同行为

4. **分类器检查**
   - 仅 Bash 工具支持
   - 异步执行

5. **Hook 检查**
   - 执行 PermissionRequest hooks

6. **降级到交互式**
   - 返回 `{ behavior: 'ask' }`

---

## 10. 权限队列

### ToolUseConfirm

```typescript
type ToolUseConfirm = {
  assistantMessage: AssistantMessage
  tool: Tool
  description: string
  input: Record<string, unknown>
  toolUseContext: ToolUseContext
  toolUseID: string
  permissionResult: PermissionDecision & { behavior: 'ask' }
  permissionPromptStartTimeMs: number
  classifierCheckInProgress?: boolean
  classifierAutoApproved?: boolean
  classifierMatchedRule?: string

  onUserInteraction(): void
  onDismissCheckmark(): void
  onAbort(): void
  onAllow(
    updatedInput: Record<string, unknown>,
    permissionUpdates: PermissionUpdate[],
    feedback?: string,
    contentBlocks?: ContentBlockParam[]
  ): Promise<void>
  onReject(feedback?: string, contentBlocks?: ContentBlockParam[]): void
  recheckPermission(): Promise<void>
}
```

---

## 11. 权限处理流程图

```
用户执行工具
     │
     ▼
hasPermissionsToUseTool()
     │
     ▼
┌─────────────────────┐
│ 权限模式检查        │
│ bypassPermissions?  │ ───是──▶ 直接允许
└─────────────────────┘
     │否
     ▼
┌─────────────────────┐
│ 规则检查           │
│ alwaysAllowRules?   │ ───是──▶ 直接允许
│ alwaysDenyRules?    │ ───是──▶ 直接拒绝
└─────────────────────┘
     │
     ▼
┌─────────────────────┐
│ 分类器检查          │
│ BASH_CLASSIFIER?    │ ───是──▶ 异步推理
└─────────────────────┘
     │
     ▼
┌─────────────────────┐
│ Hook 检查           │
│ executePermission   │ ───允许──▶ 返回允许
│ RequestHooks        │ ───拒绝──▶ 返回拒绝
└─────────────────────┘
     │
     ▼
交互式确认对话框
     │
     ├─── 用户允许 ───▶ handleUserAllow()
     │                      │
     │                      ▼
     │                 persistPermissions()
     │                      │
     │                      ▼
     │                 logPermissionDecision()
     │                      │
     │                      ▼
     │                 返回 PermissionAllowDecision
     │
     ├─── 用户拒绝 ───▶ onReject()
     │                      │
     │                      ▼
     │                 cancelAndAbort()
     │                      │
     │                      ▼
     │                 返回 PermissionDenyDecision
     │
     └─── 用户中断 ───▶ Esc 按键
                            │
                            ▼
                       abortController.abort()
                            │
                            ▼
                       返回 PermissionDenyDecision
```

---

## 12. 远程权限流程

```
CLI 端 (handleInteractivePermission)
     │
     ▼
bridgeCallbacks.sendRequest(bridgeRequestId, ...)
     │
     │ WebSocket / HTTP
     ▼
IDE Extension / Web UI
     │
     ▼
显示权限对话框
     │
     ▼
用户允许/拒绝
     │
     ▼
bridgeCallbacks.sendResponse(bridgeRequestId, response)
     │
     │ WebSocket / HTTP
     ▼
CLI 端 (onResponse 回调)
     │
     ▼
resolveOnce(decision)
```

---

## 13. 关键常量

```typescript
// 200ms 宽限期后用户交互取消分类器
const GRACE_PERIOD_MS = 200

// 分类器自动批准后显示 ✓ 的时间
const CHECKMARK_DISPLAY_MS = 3000  // 终端聚焦时
const CHECKMARK_DISPLAY_MS = 1000  // 终端未聚焦时
```

---

## 相关源码文件

| 文件 | 功能 |
|------|------|
| `PermissionContext.ts` | 权限上下文创建和管理 |
| `handlers/coordinatorHandler.ts` | 协调者处理器 |
| `handlers/interactiveHandler.ts` | 交互式处理器 |
| `handlers/swarmWorkerHandler.ts` | Swarm Worker 处理器 |
| `permissionLogging.ts` | 权限日志记录 |
| `src/utils/permissions/permissions.ts` | 权限检查入口 |
| `src/utils/permissions/PermissionUpdate.ts` | 权限更新管理 |
| `src/utils/permissions/PermissionMode.ts` | 权限模式定义 |
| `src/bridge/bridgePermissionCallbacks.ts` | 桥接权限回调 |
| `src/tools/BashTool/bashPermissions.ts` | Bash 分类器 |
| `src/types/permissions.ts` | 权限类型定义 |