第10章：权限模型 —— 六种模式与被外包的沙箱

export const EXTERNAL_PERMISSION_MODES = [
  'acceptEdits',
  'bypassPermissions',
  'default',
  'dontAsk',
  'plan',
] as const

export type InternalPermissionMode = ExternalPermissionMode | 'auto' | 'bubble'
export const INTERNAL_PERMISSION_MODES = [
  ...EXTERNAL_PERMISSION_MODES,
  ...(feature('TRANSCRIPT_CLASSIFIER') ? (['auto'] as const) : ([] as const)),
] as const

export function isExternalPermissionMode(mode: PermissionMode): mode is ExternalPermissionMode {
  // External users can't have auto, so always true for them
  if (process.env.USER_TYPE !== 'ant') return true
  return mode !== 'auto' && mode !== 'bubble'
}

export type PermissionBehavior = 'allow' | 'deny' | 'ask'

export type PermissionRule = {
  source: PermissionRuleSource     // 从哪来
  ruleBehavior: PermissionBehavior // allow / deny / ask
  ruleValue: {
    toolName: string
    ruleContent?: string           // 可选的内容匹配，如 Bash(git push:*)
  }
}

export type PermissionRuleSource =
  | 'userSettings' | 'projectSettings' | 'localSettings'
  | 'flagSettings' | 'policySettings'
  | 'cliArg' | 'command' | 'session'

function permissionRuleValueFromString(ruleString: string): PermissionRuleValue {
  const matches = ruleString.match(/^([^(]+)\(([^)]+)\)$/)
  if (!matches) return { toolName: ruleString }
  return { toolName: matches[1], ruleContent: matches[2] }
}

/**
 * Filters out tools that are blanket-denied by the permission context.
 * A tool is filtered out if there's a deny rule matching its name with no
 * ruleContent (i.e., a blanket deny for that tool).
 *
 * Uses the same matcher as the runtime permission check (step 1a), so MCP
 * server-prefix rules like `mcp__server` strip all tools from that server
 * before the model sees them — not just at call time.
 */

1a. 整个工具被 deny 规则拦     → deny
1b. 整个工具有 ask 规则         → ask（除非沙箱可自动放行，见 §4）
1c. tool.checkPermissions()     → 工具自己的判断
1d. 工具说 deny                 → deny
1e. 工具需要真人交互且说 ask    → ask ★ bypass 也拦不住
1f. 内容级 ask 规则             → ask ★ bypass 也拦不住
1g. 安全检查（.git/ .claude/…） → ask ★ bypass 也拦不住
2a. 模式说 bypass               → allow
2b. 整个工具被 allow 规则允许    → allow
3.  passthrough → ask

// 1e. Tool requires user interaction even in bypass mode
if (tool.requiresUserInteraction?.() && toolPermissionResult?.behavior === 'ask') {
  return toolPermissionResult
}

// Content-specific ask rules from tool.checkPermissions take precedence
// over bypassPermissions mode. When a user explicitly configures a
// content-specific ask rule (e.g. Bash(npm publish:*)), … This must be
// respected even in bypass mode, just as deny rules are respected at step 1d.

// 1g. Safety checks (e.g. .git/, .claude/, .vscode/, shell configs) are
// bypass-immune — they must prompt even in bypassPermissions mode.
// checkPathSafetyForAutoEdit returns {type:'safetyCheck'} for these paths.

const shouldBypassPermissions =
  appState.toolPermissionContext.mode === 'bypassPermissions' ||
  (appState.toolPermissionContext.mode === 'plan' &&
    appState.toolPermissionContext.isBypassPermissionsModeAvailable)

/**
 * Adapter layer that wraps @anthropic-ai/sandbox-runtime with Claude CLI-specific
 * integrations. This file provides the bridge between the external sandbox-runtime
 * package and Claude CLI's settings system, tool integration, and additional features.
 */
import {
  SandboxManager as BaseSandboxManager,
  SandboxRuntimeConfigSchema,
  SandboxViolationStore,
} from '@anthropic-ai/sandbox-runtime'

export const SandboxNetworkConfigSchema = lazySchema(() => z.object({
  allowedDomains: z.array(z.string()).optional(),
  allowManagedDomainsOnly: z.boolean().optional().describe(
    'When true (and set in managed settings), only allowedDomains and WebFetch(domain:...) allow rules from managed settings are respected. ' +
    'User, project, local, and flag settings domains are ignored. Denied domains are still respected from all sources.'),
  allowUnixSockets: z.array(z.string()).optional().describe(
    'macOS only: Unix socket paths to allow. Ignored on Linux (seccomp cannot filter by path).'),
  allowAllUnixSockets: z.boolean().optional(),
  allowLocalBinding: z.boolean().optional(),
  httpProxyPort: z.number().optional(),
  socksProxyPort: z.number().optional(),
}).optional())

const canSandboxAutoAllow =
  tool.name === BASH_TOOL_NAME &&
  SandboxManager.isSandboxingEnabled() &&
  SandboxManager.isAutoAllowBashIfSandboxedEnabled() &&
  shouldUseSandbox(input)

if (!canSandboxAutoAllow) {
  return { behavior: 'ask', … }
}
// Fall through to let Bash's checkPermissions handle command-specific rules

// NOTE: excludedCommands is a user-facing convenience feature, not a security boundary.
// It is not a security bug to be able to bypass excludedCommands — the sandbox permission
// system (which prompts users) is the actual security control.
function containsExcludedCommand(command: string): boolean

const BASE_PROMPT: string = feature('TRANSCRIPT_CLASSIFIER')
  ? txtRequire(require('./yolo-classifier-prompts/auto_mode_system_prompt.txt'))
  : ''

/**
 * An allow rule like `Bash(python:*)` or `PowerShell(node:*)` lets the model
 * run arbitrary code via that interpreter, bypassing the auto-mode classifier.
 * These lists feed the isDangerous{Bash,PowerShell}Permission predicates in
 * permissionSetup.ts, which strip such rules at auto-mode entry.
 */
export const CROSS_PLATFORM_CODE_EXEC = [
  'python', 'python3', 'python2', 'node', 'deno', 'tsx', 'ruby', 'perl', 'php', 'lua',
  'npx', 'bunx', 'npm run', 'yarn run', 'pnpm run', 'bun run',
  'bash', 'sh',
  'ssh',
] as const

export const DANGEROUS_BASH_PATTERNS = [
  ...CROSS_PLATFORM_CODE_EXEC,
  'zsh', 'fish', 'eval', 'exec', 'env', 'xargs', 'sudo',
  ...(process.env.USER_TYPE === 'ant' ? ['fa run', 'coo', 'gh', 'gh api', 'curl', 'wget', 'git', 'kubectl', 'aws', 'gcloud', 'gsutil'] : []),
]

export const DENIAL_LIMITS = {
  maxConsecutive: 3,
  maxTotal: 20,
} as const

export function shouldFallbackToPrompting(state: DenialTrackingState): boolean

export async function checkAndDisableBypassPermissionsIfNeeded(…) {
  if (bypassPermissionsCheckRan) return
  bypassPermissionsCheckRan = true
  if (!toolPermissionContext.isBypassPermissionsModeAvailable) return

  const shouldDisable = await shouldDisableBypassPermissions()   // Statsig gate
  if (!shouldDisable) return

  setAppState(prev => ({ ...prev, toolPermissionContext: createDisabledBypassPermissionsContext(prev.toolPermissionContext) }))
}

/** When true, permission prompts are auto-denied (e.g., background agents that can't show UI) */
shouldAvoidPermissionPrompts?: boolean

cd claude-code-deep-dive/extracted-source

# 1. 六种模式
cat src/utils/permissions/PermissionMode.ts
sed -n '1,60p' src/types/permissions.ts

# 2. 决策流水线（带 1a/1b/1c… 编号）
sed -n '1158,1310p' src/utils/permissions/permissions.ts

# 3. 给钩子用的精简版，对比看裁剪了什么
sed -n '1071,1155p' src/utils/permissions/permissions.ts

# 4. 三条 bypass 免疫
grep -n -B3 -A8 'bypass-immune\|even in bypass mode\|requiresUserInteraction' src/utils/permissions/permissions.ts

# 5. 沙箱：只有适配层
head -50 src/utils/sandbox/sandbox-adapter.ts
cat src/entrypoints/sandboxTypes.ts | head -80

# 6. 「这不是安全边界」的声明
grep -n -B2 -A4 'not a security boundary' src/tools/BashTool/shouldUseSandbox.ts

# 7. 危险 allow 规则清单
cat src/utils/permissions/dangerousPatterns.ts

# 8. 分类器止损与 bypass killswitch
cat src/utils/permissions/denialTracking.ts
cat src/utils/permissions/bypassPermissionsKillswitch.ts

# 看当前生效的规则及其来源
# （在 Claude Code 里敲）
/permissions

# 看沙箱状态
/sandbox-toggle