canUseTool 回调 在运行时处理其他所有情况。
权限如何被评估
当 Claude 请求一个工具时,SDK 按以下顺序检查权限:1
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 或更高版本。您的组织设置为 ask 的 claude.ai connector 工具也在此步骤离开流程。每个调用都传递到回调,即使在 bypassPermissions 模式下,即使当允许规则匹配时也是如此。回调接收原因 Your organization requires approval for this tool。在 dontAsk 模式下,调用被拒绝,因为该模式从不提示。4
5
允许规则
检查
allow 规则(来自 allowed_tools 和 settings.json)。如果规则匹配,工具被批准。工具自己批准的调用也在此步骤被解决,无需规则:例如在您的工作目录内的文件读取或 只读 Bash 命令。针对 关键路径 的 rm 和 rmdir 删除永远不会被允许规则批准。它们是否随后到达您的回调取决于权限模式:例如在 auto 模式的 Agent SDK 会话中,Claude Code 默认拒绝它们而不调用它。关键路径 模式表列出了每种模式对它们的处理方式。6
canUseTool 回调
如果上述任何步骤都未解决,调用您的
canUseTool 回调 以获得决定。在 dontAsk 模式下,此步骤被跳过,工具被拒绝。在 TypeScript SDK 中,如果您设置了 permissionPrompts: 'none',您的回调在此步骤不会被调用。PermissionRequest hook 仍然有机会决定,如果它不决定,Claude Code 拒绝调用。该选项需要 Claude Code v2.1.259 或更高版本。canUseTool 回调,SDK 在构造查询时会发出一次 Node.js 进程警告。警告的代码是 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED。两个配置会触发它:
permissionMode: 'bypassPermissions',它自动批准到达权限模式步骤的每个调用,除了 任何模式都不自动批准的操作- 每个裸
allowedTools条目,如"Read",它在回调被咨询之前自动批准整个工具,除了 任何模式都不自动批准的操作
Bash(ls *) 和 acceptEdits 模式不会触发它,来自设置文件的允许规则对检查不可见。
使用 process.on('warning', ...) 监听并匹配代码以记录或抑制它。要对所有工具调用进行门控,无论模式和规则如何,请改用 PreToolUse hook。
此页面重点关注 允许和拒绝规则 和 权限模式。对于其他步骤:
- Hooks: 运行自定义代码以允许、拒绝或修改工具请求。请参阅 使用 hooks 控制执行。
- canUseTool 回调: 在运行时提示用户批准,当没有更早的步骤解决调用时。请参阅 处理批准和用户输入。
允许和拒绝规则
allowed_tools 和 disallowed_tools(TypeScript:allowedTools / disallowedTools)在上述评估流程中向允许和拒绝规则列表添加条目。如果你在 allowed_tools 中命名了某个任务跟踪工具,Claude Code 也会选择加入该会话。任何其他未在 allowed_tools 中列出的工具仍然可供 Claude 使用,对其的调用如果需要批准,则会进入权限模式。拒绝规则的行为取决于它们是命名工具还是在工具内限定模式。
允许规则仅在字面
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" 配对:
default 模式中不需要批准的调用会运行,无论你是否列出它们,例如只读 Bash 命令、不在运行前询问的 Agent 等工具,以及工作目录内的文件读取。要使工具完全超出 Claude 的范围,请将其裸名称添加到 disallowedTools。
你也可以在 .claude/settings.json 中声明式地配置允许、拒绝和询问规则。当启用 project 设置源时会读取这些规则,默认 query() 选项就是这样。如果你显式设置 setting_sources(TypeScript:settingSources),请包含 "project" 以使其应用。请参阅权限设置了解规则语法。
权限模式
权限模式提供对 Claude 如何使用工具的全局控制。您可以在调用query() 时设置权限模式,或在流式会话期间动态更改它。
如果您没有设置权限模式,Claude Code 会根据会话启动时的模式中的规则选择起始权限模式:
在自动模式下启动的会话会放弃广泛的允许规则,例如裸 Bash 条目,如自动模式如何评估操作所述。如果您的应用程序依赖于 default 模式或此类规则,请显式传递 default。
在 TypeScript Agent SDK v0.3.286 之前,省略 permissionMode 与传递 default 相同。
可用模式
SDK 支持以下权限模式:设置权限模式
您可以在启动查询时设置一次权限模式,或在会话活跃时动态更改它。- 在查询时
- 在流式传输期间
在创建查询时传递
permission_mode(Python)或 permissionMode(TypeScript)。此模式适用于整个会话,除非动态更改。模式详情
接受编辑模式(acceptEdits)
自动批准文件操作,以便 Claude 可以编辑代码而无需提示。其他工具(如不是文件系统操作的 Bash 命令)仍需要正常权限。
自动批准的操作:
- 文件编辑(Edit、Write 工具)
- 文件系统命令:
mkdir、touch、rm、rmdir、mv、cp、sed
additionalDirectories 内的路径。在 acceptEdits 模式下,当 Claude 执行以下操作时,Claude Code 不会自动批准请求:
- 在该范围之外的路径上工作
- 写入受保护的路径
- 使用
rm或rmdir删除关键路径
不要询问模式(dontAsk)
将任何权限提示转换为拒绝,而不调用 canUseTool。由 allowed_tools、settings.json 允许规则或钩子预先批准的工具会正常运行,default 模式下不需要批准的调用也会运行,例如在您的工作目录内的文件读取和对 Agent 的调用。连接器工具您的组织设置为 ask、需要用户交互的工具,以及 rm 和 rmdir 针对关键路径的删除即使允许规则匹配也会被拒绝。PreToolUse 钩子允许也不会清除关键路径删除。
使用场景: 您希望为无头代理提供固定的、明确的工具表面,并且更喜欢硬拒绝而不是依赖 canUseTool 不存在的无声依赖。
绕过权限模式(bypassPermissions)
自动批准工具使用而无需提示,除了下面警告中列出的情况。钩子仍会执行,如果需要可以阻止操作。在 Linux 和 macOS 上,Claude Code 拒绝在此模式下以 root 身份或在已识别的沙箱外的 sudo 下启动,查询在第一轮之前失败。
规划模式(plan)
Claude 探索代码库并生成计划,而不编辑您的源文件。只读工具的运行方式与 default 权限模式相同。
在规划模式下,文件编辑永远不会自动批准,即使允许规则匹配。它们会通过您的 canUseTool 回调提示。 在 Claude Code v2.1.212 或更高版本上,修改文件的 shell 命令(如 touch 和 rm)会以相同方式到达您的 canUseTool 回调。
在 TypeScript SDK 中,如果您在 permissionMode: 'plan' 旁边设置 allowDangerouslySkipPermissions: true,文件编辑和修改文件的 shell 命令仍然会到达您的 canUseTool 回调。该选项让您稍后可以使用 setPermissionMode() 切换到 bypassPermissions。
Claude 可能会使用 AskUserQuestion 在最终确定计划之前澄清需求。有关处理这些提示的信息,请参阅处理批准和用户输入。
使用场景: 您希望 Claude 提议更改而不执行它们,例如在代码审查期间或当您需要在进行更改之前批准更改时。