Agent SDK 提供多层权限控制体系，精确管理 Claude 可以使用哪些工具以及是否需要审批。权限评估按固定顺序执行，理解这个顺序是正确配置权限的关键。
核心机制
权限评估顺序（从高到低优先级）：
- Hooks - 可拦截或放行，但 allow 不跳过后续步骤
- Deny 规则（disallowed_tools）- 任何模式下都强制拒绝
- Permission Mode - 全局模式决策
- Allow 规则（allowed_tools）- 预批准列表
- canUseTool 回调 - 运行时动态决策（dontAsk 模式跳过此步）
五种 Permission Mode：
| 模式 | 行为 |
|---|---|
default | 未匹配工具触发 canUseTool 回调 |
acceptEdits | 自动批准文件编辑和 mkdir/rm/mv/cp 等文件系统命令 |
dontAsk | 未预批准的工具直接拒绝，不调用 canUseTool |
bypassPermissions | 跳过所有权限检查（慎用，不能以 root 运行） |
plan | 只读模式，Claude 只分析不修改文件 |
关键细节
锁定 Agent 的标准配置：
options = ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep"],
permission_mode="dontAsk", # 未列出的工具直接拒绝
)重要警告：allowed_tools 不能约束 bypassPermissions 模式。设置 allowed_tools=["Read"] + permission_mode="bypassPermissions" 仍然允许所有工具（包括 Bash、Write、Edit）。如需在 bypassPermissions 下屏蔽特定工具，必须用 disallowed_tools。
动态切换权限模式（Python）：
async with ClaudeSDKClient(options=ClaudeAgentOptions(permission_mode="default")) as client:
await client.query("Help me refactor this code")
await client.set_permission_mode("acceptEdits") # 动态切换
async for message in client.receive_response():
...acceptEdits 模式自动批准的操作：
- Edit、Write 工具（文件编辑）
- Bash 中的 mkdir、touch、rm、rmdir、mv、cp、sed 命令
- 仅限工作目录或 additionalDirectories 内的路径
子 Agent 继承：当父 Agent 使用 bypassPermissions、acceptEdits 或 auto 时，所有子 Agent 继承该模式且无法覆盖。
与其他概念的关联
- hooks - 权限评估的第一步
- user-input - canUseTool 回调实现
- agent-loop - 工具被拒绝时 Claude 的行为
- subagents - 子 Agent 权限继承
实践要点
plan模式适合”先分析后执行”的工作流，Claude 可用 AskUserQuestion 澄清需求- 声明式规则也可在
.claude/settings.json中配置，通过settingSources加载 - 工具被拒绝时，Claude 会收到拒绝消息并通常尝试其他方案或报告无法继续
- 生产环境建议从
default模式开始，逐步放宽权限，而非从bypassPermissions收紧