SpyBara
Go Premium

agent-sdk/permissions.md 2026-10-21 23:02 UTC to 2026-10-22 22:58 UTC

This page contains 40 additions and 38 deletions.

2026
Thu 1 23:59 Fri 9 23:02 Sat 10 23:01 Sat 17 23:57 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Mon 26 22:57 Tue 27 22:59 Fri 30 23:01

配置权限

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

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

权限如何被评估

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

1. Hooks

首先运行 hooks。Hook 可以直接拒绝调用或将其传递下去。返回 allow 的 hook 不会跳过下面的拒绝和询问规则；无论 hook 结果如何，这些规则都会被评估。

返回 allow 的 PreToolUse hook 也不能批准目标被 Claude Code 识别为 关键路径 的 rm 或 rmdir 命令，例如 rm -rf ~。关于该 allow 在计划模式下的作用，请参阅 计划模式下的 hook 批准。

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. 权限模式

应用活跃的 权限模式：

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

5. 允许规则

检查 allow 规则（来自 allowed_tools 和 settings.json）。如果规则匹配，工具被批准。工具自己批准的调用也在此步骤被解决，无需规则：例如在您的工作目录内的文件读取或 只读 Bash 命令。

被识别出的 关键路径删除 不会被允许规则批准。它们是否随后到达您的回调取决于权限模式：例如在 auto 模式的 Agent SDK 会话中，Claude Code 默认拒绝它们而不调用它。关键路径模式表 列出了每种模式对它们的处理方式。

允许规则不会批准从 网络路径 进行的读取。

6. canUseTool 回调

如果上述任何步骤都未解决，调用您的 canUseTool 回调 以获得决定。在 dontAsk 模式下，此步骤被跳过，工具被拒绝，不过您安装的 mod 仍然可以批准部分此类调用。

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

六步权限评估流程的图表，与上述步骤匹配：工具请求通过 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 规则 了解四种锚定形式以及来自设置文件的规则如何解析。

[!WARNING]

自动批准的工具永远不会到达 canUseTool。 在任何早期步骤中被批准的工具调用，通过 acceptEdits 或 bypassPermissions，或通过允许规则，会跳过你的 canUseTool 回调，因此你在那里放置的权限检查会被该工具无声地绕过。

允许规则永远不会自动批准 AskUserQuestion、标记为 _meta["anthropic/requiresUserInteraction"] 的 MCP 工具、您的组织设置为 ask 的连接器工具，或被识别出的 rm 和 rmdir 关键路径移除。在 dontAsk 模式中，Claude Code 拒绝这些调用而不调用回调。在其他模式中，前三个会到达回调。关键路径模式表列出了每种模式如何处理关键路径移除。识别这些移除操作的检查可能会遗漏某些命令。

覆盖范围取决于条目的形式：像 Read 或 mcp__github__get_issue 这样的裸名称会自动批准对该工具的每个调用，上述例外和从网络路径读取除外，而像 Bash(npm test *) 这样的限定规则仅自动批准匹配的调用，其他需要批准的 Bash 调用仍然会进入回调。对于必须在每个工具调用上运行的检查，使用 PreToolUse hook：hook 在每个其他步骤之前运行，hook 拒绝即使在 bypassPermissions 模式中也适用。

对于锁定的代理，将 allowedTools 与 permissionMode: "dontAsk" 配对：

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

列出的工具被批准，任何模式都不自动批准的操作和从网络路径读取除外。每个其他会提示的调用则会被拒绝，不过您安装的 mod 仍然可以批准其中的部分调用。

在 default 模式中不需要批准的调用会运行，无论您是否列出它们。其中包括只读 Bash 命令、不在运行前询问的 Agent 等工具，以及工作目录内的文件读取。要将工具从请求中完全移除，请将其裸名称添加到 disallowedTools。

[!WARNING]

allowed_tools 不限制 bypassPermissions。 allowed_tools 预批准你列出的工具。其他未列出的工具不匹配任何允许规则，会进入权限模式，其中 bypassPermissions 批准它们。将 allowed_tools=["Read"] 与 permission_mode="bypassPermissions" 一起设置仍然会批准每个工具，包括 Bash、Write 和 Edit。如果你需要 bypassPermissions 但想要阻止特定工具，请使用 disallowed_tools。

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

权限模式

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

在 Claude Code v2.1.302 或更高版本中，您的应用会以 default 模式启动，除非您设置了权限模式，或者应用从其设置文件中的 permissions.defaultMode 获取权限模式。在 default 模式下，Claude Code 会拒绝任何需要批准的工具调用，除非您通过允许规则、hook、canUseTool 回调或权限提示工具批准它。如果工具调用被拒绝，请参阅在 claude -p 和 Agent SDK 运行中工具调用被拒绝。

可用模式

SDK 支持以下权限模式：

模式 描述 工具行为
default 标准权限行为 无基于模式的自动批准；需要批准且不匹配任何允许规则的调用会触发您的 canUseTool 回调
dontAsk 拒绝而不是提示 任何原本会提示的调用都会被拒绝，且不调用 canUseTool，不过您安装的 mod 仍可以批准其中部分调用。由 allowed_tools 或 settings.json 允许规则批准的调用会运行，default 模式下不需要批准的调用也会运行。某些调用，例如来自网络路径的读取，即使 allowed_tools 或允许规则与之匹配也会被拒绝。有关完整列表，请参阅不要询问模式
acceptEdits 自动接受文件编辑 文件编辑和文件系统操作（mkdir、rm、mv 等）会自动批准
bypassPermissions 绕过权限检查 工具运行时无需权限提示，除了任何模式都不自动批准的操作。请谨慎使用
plan 规划模式 Claude 在不编辑您的源文件的情况下探索和规划；文件编辑永远不会自动批准，而是通过您的 canUseTool 回调提示
auto 模型分类批准 模型分类器审查 shell 命令和网络请求等操作，允许或阻止它审查的每一个操作。有关可用性和决策顺序，请参阅自动模式

[!WARNING]

子代理继承： 子代理在父会话的权限模式下运行，除非您在其AgentDefinition上设置 permissionMode，且父会话处于 default、dontAsk 或 plan 模式。即使这样，Claude Code 也永远不会应用 "bypassPermissions" 值，并且仅当该子代理可以使用自动模式时才会应用 "auto" 值。子代理仅在父会话本身处于 bypassPermissions 模式时才在该模式下运行。 bypassPermissions 异常需要 Claude Code v2.1.267 或更高版本。

子代理可能具有不同的系统提示和比主代理更少受限的行为，因此继承 bypassPermissions 会授予它们完整的自主系统访问权限。任何模式都不自动批准的操作仍然适用。

设置权限模式

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

在查询时

在创建查询时传递 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",  # Set the mode here
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const message of query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Set the mode here
    }
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

在流式传输期间

调用 set_permission_mode()（Python）或 setPermissionMode()（TypeScript）以在会话中途更改模式。新模式立即对所有后续工具请求生效。这让您可以从限制性开始，随着信任建立而放宽权限，例如在审查 Claude 的初始方法后切换到 acceptEdits。

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    async with ClaudeSDKClient(
        options=ClaudeAgentOptions(
            permission_mode="default",  # Start in default mode
        )
    ) as client:
        await client.query("Help me refactor this code")

        # Change mode dynamically mid-session
        await client.set_permission_mode("acceptEdits")

        # Process messages with the new permission mode
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  const q = query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Start in default mode
    }
  });

  // Change mode dynamically mid-session
  await q.setPermissionMode("acceptEdits");

  // Process messages with the new permission mode
  for await (const message of q) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

模式详情

接受编辑模式（acceptEdits）

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

自动批准的操作：

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

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

  • 在该范围之外的路径上工作
  • 写入受保护的路径
  • 使用 rm 或 rmdir 删除 Claude Code 识别为关键路径的路径

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

不要询问模式（dontAsk）

将任何权限提示转换为拒绝，而不调用 canUseTool，不过您安装的 mod 仍可以批准其中部分调用。由 allowed_tools、settings.json 允许规则或 hook 预先批准的工具会正常运行。default 模式下不需要批准的调用也会运行，例如在您的工作目录内的文件读取和对 Agent 的调用。

您的组织设置为 ask 的连接器工具、需要用户交互的工具、来自网络路径的读取，以及已识别的关键路径删除即使允许规则匹配也会被拒绝。PreToolUse hook 允许也不会放行已识别的关键路径删除或来自网络路径的读取。识别这些删除操作的检查可能会遗漏某些命令。

使用场景： 您希望为无头代理提供固定的、明确的工具表面，并且更喜欢硬拒绝而不是依赖 canUseTool 不存在的无声依赖。

绕过权限模式（bypassPermissions）

自动批准工具使用而无需提示，除了下面警告中列出的情况。钩子仍会执行，如果需要可以阻止操作。在 Linux 和 macOS 上，Claude Code 拒绝在此模式下以 root 身份或在已识别的沙箱外的 sudo 下启动，查询在第一轮之前失败。

[!WARNING]

请极其谨慎使用。Claude 在此模式下具有完整的系统访问权限。仅在您信任所有可能操作的受控环境中使用。

allowed_tools 不会限制此模式。每个工具都被批准，而不仅仅是您列出的工具。这些控制仍然适用：

规划模式（plan）

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

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

在 TypeScript SDK 中，如果您在 permissionMode: 'plan' 旁边设置 allowDangerouslySkipPermissions: true，文件编辑和修改文件的 shell 命令仍然会到达您的 canUseTool 回调。该选项让您稍后可以使用 setPermissionMode() 切换到 bypassPermissions。

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

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

自动模式（auto）

分类器模型会在 shell 命令和网络请求等操作运行之前对其进行审查，并允许或阻止它审查的每一个操作。有关自动模式所需的模型和提供商以及它评估操作的顺序，请参阅使用自动模式消除权限提示。

如果您使用 set_model()、setModel() 或 applyFlagSettings() 将处于自动模式的会话切换到自动模式不支持的模型，会话将更改为 default 模式：

  • 您会看到的内容：一条子类型为 status、permissionMode 设置为 "default" 的 system 消息，TypeScript SDK 将其类型定义为 SDKStatusMessage。此后，需要批准且不匹配任何允许规则的调用会到达您的 canUseTool 回调。
  • 返回自动模式：切换到受支持的模型，然后调用 set_permission_mode("auto") 或 setPermissionMode("auto")。如果您切换回原模型但未进行该调用，会话将保持在 default 模式。当不受支持的模型处于活动状态时，该调用会失败并显示 Cannot set permission mode to auto: auto mode unavailable for this model。

在调用 set_model()、setModel() 或 applyFlagSettings() 之后更改为 default 模式需要 Claude Code v2.1.299 或更高版本。

相关资源

有关权限评估流程中的其他步骤：