SpyBara
Go Premium

agent-sdk/permissions.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 50 additions and 31 deletions.

2026
Thu 10 23:00 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Fri 25 23:58

配置权限

使用权限模式、hooks 和声明式允许/拒绝规则来控制您的代理如何使用工具。

Claude Agent SDK 提供权限控制来管理 Claude 如何使用工具。使用权限模式和规则来定义自动允许的内容，以及使用 canUseTool 回调 在运行时处理其他所有情况。

权限如何被评估

当 Claude 请求一个工具时，SDK 按以下顺序检查权限：

1

Hooks

首先运行 hooks。一个 hook 可以直接拒绝调用或将其传递下去。返回 allow 的 hook 不会跳过下面的拒绝和询问规则；无论 hook 结果如何，这些规则都会被评估。一个 PreToolUse hook allow 也不能批准针对 关键路径 的 rm 或 rmdir 删除。

2

拒绝规则

检查 deny 规则（来自 disallowed_tools 和 settings.json）。如果拒绝规则匹配，工具被阻止，即使在 bypassPermissions 模式下也是如此。裸名称拒绝规则（如 Bash）在此评估开始之前将工具从 Claude 的上下文中移除，因此只有作用域规则（如 Bash(rm *)）在此步骤中被检查。

3

询问规则

检查来自 settings.json 的 ask 规则。如果询问规则匹配，调用会传递到您的 canUseTool 回调 以获得确认，即使在 bypassPermissions 模式下也是如此。

需要用户交互的工具行为相同：AskUserQuestion 和 MCP 工具，其服务器设置 _meta["anthropic/requiresUserInteraction"] 总是传递到回调，即使当允许规则匹配时。在 dontAsk 模式下，两种情况都被拒绝，因为该模式从不提示。MCP 注解需要 Claude Code v2.1.199 或更高版本。

claude.ai connector 工具，您的组织已设置为 ask 也会在此步骤离开流程。每个调用都会传递到回调，即使在 bypassPermissions 模式下，即使当允许规则匹配时。回调接收原因 Your organization requires approval for this tool。在 dontAsk 模式下，调用被拒绝，因为该模式从不提示。

4

权限模式

应用活跃的 权限模式：

  • 在 bypassPermissions 模式下，Claude Code 批准到达此步骤的所有内容，除了针对 关键路径 的 rm 和 rmdir 删除，这些会传递下去。
  • 在 acceptEdits 模式下，Claude Code 批准 Accept edits mode 下列出的文件操作。
  • 在 plan 模式下，Claude Code 将文件编辑和 shell 写入工具发送到您的 canUseTool 回调，无论允许规则如何，因此在规划时写入操作无法自动批准。
  • 在其他模式下，请求会传递下去。
5

允许规则

检查 allow 规则（来自 allowed_tools 和 settings.json）。如果规则匹配，工具被批准。针对 关键路径 的 rm 和 rmdir 删除永远不会被允许规则批准：它们在提示的模式下到达您的回调，在 Claude Code v2.1.218 或更高版本的 auto 模式下进入 分类器，并在 dontAsk 模式下被拒绝。

6

canUseTool 回调

如果上述任何步骤都未解决，调用您的 canUseTool 回调 以获得决定。在 dontAsk 模式下，此步骤被跳过，工具被拒绝。

在 TypeScript SDK 中，如果您设置 permissionPrompts: 'none'，您的回调在此步骤不会被调用。一个 PermissionRequest hook 仍然有机会决定，如果它不决定，Claude Code 拒绝调用。该选项需要 Claude Code v2.1.259 或更高版本。

六步权限评估流程图，与上述步骤相匹配：工具请求通过 hooks、拒绝规则、询问规则、权限模式、允许规则和 canUseTool。Hooks、拒绝规则和 canUseTool 可以路由到阻止；权限模式绕过、允许规则和 canUseTool 可以路由到执行；询问规则路由到 canUseTool。 六步权限评估流程图，与上述步骤相匹配：工具请求通过 hooks、拒绝规则、询问规则、权限模式、允许规则和 canUseTool。Hooks、拒绝规则和 canUseTool 可以路由到阻止；权限模式绕过、允许规则和 canUseTool 可以路由到执行；询问规则路由到 canUseTool。

如果您在 TypeScript SDK 期望评估顺序在咨询回调之前自动批准调用的配置中传递 canUseTool 回调，SDK 在构造查询时会发出一次 Node.js 进程警告。警告的代码是 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED。两种配置会触发它：

带有说明符的条目（如 Bash(ls *)）和 acceptEdits 模式不会触发它，来自设置文件的允许规则对检查不可见。

使用 process.on('warning', ...) 监听并匹配代码以记录或抑制它。要无论模式和规则如何都控制每个工具调用，请改用 PreToolUse hook。

本页面重点关注 允许和拒绝规则 以及 权限模式。对于其他步骤：

允许和拒绝规则

allowed_tools 和 disallowed_tools（TypeScript：allowedTools / disallowedTools）向上面评估流程中的允许和拒绝规则列表添加条目。如果您在 allowed_tools 中命名任务跟踪工具之一，Claude Code 也会选择加入会话。任何其他未在 allowed_tools 中列出的工具仍然可供 Claude 使用，并继续进行权限模式。拒绝规则的行为取决于它们是命名工具还是在工具内范围化模式。

选项 效果
allowed_tools=["Read", "Grep"] Read 和 Grep 被自动批准。此处未列出的其他工具仍然存在并继续进行权限模式和 canUseTool。
disallowed_tools=["Bash"] Bash 工具定义从请求中移除。Claude 看不到该工具，无法尝试它。
disallowed_tools=["Bash(rm *)"] Bash 保持可用。与 rm * 如所写 匹配的调用在每个权限模式中都被拒绝，包括 bypassPermissions。其他 Bash 调用，包括 /bin/rm，继续进行权限模式。
disallowed_tools=["*"] 每个工具定义都从请求中移除。工具名称通配符在拒绝规则中受支持："*" 匹配每个工具，"mcp__*" 匹配所有服务器中的每个 MCP 工具。

允许规则仅在字面 mcp__<server>__ 前缀之后接受工具名称通配符。服务器段必须无通配符，以便规则命名您配置的特定服务器：mcp__puppeteer__* 匹配来自 puppeteer 服务器的每个工具，mcp__github__get_* 匹配其 get_ 工具。未锚定的条目如 allowed_tools=["*"] 或 allowed_tools=["mcp__*"] 被忽略并显示启动警告，不会自动批准任何内容。

范围化规则用于 Read 和 Edit 采用路径模式。Edit(path) 规则管理所有写入文件的内置工具，包括 Write 和 NotebookEdit；Write(path) 规则永远不会被文件权限检查匹配。

使用 //path 表示绝对文件系统路径：Edit(//secrets/**) 的拒绝规则阻止在磁盘上 /secrets 下任何位置的写入。使用单个前导斜杠，Edit(/secrets/**) 在规则的源处锚定。对于通过 allowed_tools 或 disallowed_tools 传递的规则，这意味着会话的工作目录，因此规则不会阻止磁盘上的 /secrets。请参阅 Read 和 Edit 规则 了解四种锚定形式以及来自设置文件的规则如何解析。

对于锁定的代理，将 allowedTools 与 permissionMode: "dontAsk" 配对。列出的工具被批准，除了上面警告中的始终提示工具；其他任何内容都被直接拒绝，而不是提示：

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

您也可以在 .claude/settings.json 中声明式地配置允许、拒绝和询问规则。当启用 project 设置源时，这些规则被读取，默认 query() 选项就是这样。如果您显式设置 setting_sources（TypeScript：settingSources），请包含 "project" 以使其应用。请参阅 权限设置 了解规则语法。

权限模式

权限模式提供对 Claude 如何使用工具的全局控制。您可以在调用 query() 时设置权限模式，或在流式会话期间动态更改它。

可用模式

SDK 支持这些权限模式：

模式 描述 工具行为
default 标准权限行为 无自动批准；不匹配的工具触发您的 canUseTool 回调
dontAsk 拒绝而不是提示 任何未被 allowed_tools 或规则预批准的内容都被拒绝；连接器工具您的组织设置为 ask和需要用户交互的工具即使您已预批准它们也被拒绝，rm 和 rmdir 移除针对关键路径也被拒绝。canUseTool 永远不会被调用
acceptEdits 自动接受文件编辑 文件编辑和 文件系统操作（mkdir、rm、mv 等）被自动批准
bypassPermissions 绕过权限检查 工具运行而无需权限提示，除了任何模式都不自动批准的操作。谨慎使用
plan 规划模式 Claude 在不编辑源文件的情况下探索和规划；文件编辑永远不会自动批准，并通过您的 canUseTool 回调提示
auto 模型分类批准 模型分类器批准或拒绝权限提示。请参阅Auto 模式了解可用性

设置权限模式

您可以在启动查询时设置权限模式一次，或在会话活跃时动态更改它。

在创建查询时传递 permission_mode（Python）或 permissionMode（TypeScript）。此模式应用于整个会话，除非动态更改。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
async for message in query(
prompt="Help me refactor this code",
options=ClaudeAgentOptions(
permission_mode="default",  # 在此处设置模式
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

模式详情

接受编辑模式（`acceptEdits`）

自动批准文件操作，以便 Claude 可以编辑代码而无需提示。其他工具（如不是文件系统操作的 Bash 命令）仍然需要正常权限。

自动批准的操作：

  • 文件编辑（Edit、Write 工具）
  • 文件系统命令：mkdir、touch、rm、rmdir、mv、cp、sed

两者都仅适用于工作目录或 additionalDirectories 内的路径。在 acceptEdits 模式下，当 Claude 时，Claude Code 不会自动批准请求：

  • 在该范围之外的路径上工作
  • 写入受保护的路径
  • 使用 rm 或 rmdir 移除关键路径

使用时机： 您信任 Claude 的编辑并希望更快的迭代，例如在原型设计期间或在隔离目录中工作时。

不询问模式（`dontAsk`）

将任何权限提示转换为拒绝。由 allowed_tools、settings.json 允许规则或作为 hook 运行的工具正常运行。连接器工具您的组织设置为 ask、需要用户交互的工具，以及 rm 和 rmdir 移除针对关键路径即使允许规则匹配也被拒绝。PreToolUse hook 允许也不会清除关键路径移除。其他所有内容都被拒绝，无需调用 canUseTool。

使用时机： 您想要为无头代理提供固定的、明确的工具表面，并且更喜欢硬拒绝而不是默默依赖 canUseTool 不存在。

绕过权限模式（`bypassPermissions`）

自动批准工具使用而无需提示，除了下面警告中列出的情况。Hooks 仍然执行，如果需要可以阻止操作。

规划模式（`plan`）

Claude 探索代码库并生成计划而不编辑您的源文件。只读工具在 default 权限模式下运行。

文件编辑在规划模式下永远不会自动批准，即使允许规则匹配。它们通过您的 canUseTool 回调提示。在 Claude Code v2.1.212 或更高版本上，修改文件的 shell 命令，如 touch 和 rm，以相同方式到达您的 canUseTool 回调。

Claude 可能使用 AskUserQuestion 在最终确定计划之前澄清需求。请参阅处理批准和用户输入以处理这些提示。

使用时机： 您想要 Claude 提议更改而不执行它们，例如在代码审查期间或当您需要在进行更改之前批准更改时。

对于权限评估流程中的其他步骤：