deny 数组。
要添加自定义工具，请连接一个 MCP server。要使用可重用的基于提示的工作流扩展 Claude，请编写一个 skill，它通过现有的 Skill 工具运行，而不是添加新的工具条目。
Permission required 列显示该工具在默认权限模式下是否对工作目录内的路径进行提示。标记为”否”的文件访问工具，包括 Read、Grep 和 Glob，仍然会对工作目录和其他目录之外的路径进行提示。Bash 标记为”是”，但运行一组内置的只读命令而无需提示。
使用权限规则和 hooks 配置工具
在大多数情况下，Claude 决定何时使用这些工具，您在与 Claude 交互时不需要自己命名它们。当定义权限和其他配置时，您直接引用工具名称：- 在设置中的
permissions.allow和permissions.deny，以及/permissions界面 - 在 CLI 标志中的
--allowedTools和--disallowedTools - 在 Agent SDK 的
allowedTools和disallowedTools选项中 - 在 subagent 的
tools或disallowedToolsfrontmatter 中 - 在 skill 的
allowed-toolsfrontmatter 中 - 在 hook 的
if条件中
ToolName(specifier)。specifier 取决于工具，几个工具共享一种格式：
此处未列出的工具，例如
ExitPlanMode 或 ShareOnboardingGuide，仅接受不带 specifier 的裸工具名称。
Edit(...) 允许规则也授予对相同路径的读取访问权限，因此您不需要匹配的 Read(...) 规则。Read(...) 拒绝规则也会阻止 Edit 工具在相同路径上的使用，包括在该处创建新文件，因为编辑需要读取结果。Edit 上的 Read 拒绝检查需要 Claude Code v2.1.208 或更高版本。
Hook matcher 字段使用裸工具名称，而不是带括号的规则格式。请参阅匹配器模式了解匹配规则。对于每个工具在 hooks 中传递给 tool_input 的字段名称，请参阅 PreToolUse 输入参考。
Agent 工具行为
Agent 工具在单独的 context window 中生成一个 subagent。subagent 自主地完成其任务，然后向父对话返回单个文本结果。父对话看不到 subagent 的中间工具调用或输出，只看到最终结果。 要限制 subagent 运行的轮数，请在 subagent 定义中设置maxTurns。
同一个 Agent 工具也在启用 fork 模式时启动分叉 subagents。fork 继承完整的父对话，而不是从头开始，始终在后台运行，并且仍然在您的终端中显示权限提示。本节的其余部分描述命名的 subagents。
命名的 subagent 可以使用哪些工具取决于 subagent 定义中的 tools 和 disallowedTools 字段：
- 两个字段都未设置：subagent 继承父对话可用的每个工具。
- 仅设置
tools：subagent 仅获得列出的工具。 - 仅设置
disallowedTools：subagent 获得除列出的工具外的每个父工具。 - 两个都设置：
disallowedTools优先。同时列在两个中的工具会被移除。
tools 列表最终没有任何工具时，例如因为每个条目都拼写错误或命名了一个对 subagents 不可用的工具，Agent 工具会返回一个错误，列出这些条目，而不是启动 subagent。在 v2.1.208 之前，subagent 会以无工具的方式启动，可能返回空结果或令人困惑的结果。
启动 subagent 本身不会提示权限。Claude Code 在运行时根据您的权限规则检查 subagent 自己的工具调用。
从 v2.1.198 起，subagents 默认在后台运行；当 Claude 需要结果后才继续时，它会在前台运行一个。
- 前台 subagents 显示您在主对话中会看到的相同权限提示，在每个工具调用发生时。
- 后台 subagents 从 v2.1.186 起在您的主会话中显示权限提示。提示会指出是哪个 subagent 在请求，按 Esc 会拒绝该工具调用而不停止 subagent。在 v2.1.186 之前，后台 subagents 会自动拒绝任何会提示的工具调用并继续运行而不使用该工具。
tools 字段，将 Bash 排除在列表之外，或在设置中设置拒绝规则，如控制 subagent 功能中所述。有关选择前台或后台的更多信息，请参阅在前台或后台运行 subagents。
Bash 工具行为
Bash 工具在单独的进程中运行每个命令，具有以下持久性行为：- 当 Claude 在主会话中运行
cd时，只要它保持在项目目录内或您使用--add-dir、/add-dir或设置中的additionalDirectories添加的额外工作目录内，新的工作目录就会延续到后续的 Bash 命令。Subagent 会话永远不会延续工作目录更改。- 如果
cd落在这些目录之外，Claude Code 会重置为项目目录，并将Shell cwd was reset to <dir>附加到工具结果。 - 要禁用此延续，使每个 Bash 命令都在项目目录中启动，请设置
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1。
- 如果
- 环境变量不持久。一个命令中的
export在下一个命令中将不可用。 - 在您的 shell 启动文件中定义的别名和 shell 函数可用。在会话启动时，Claude Code 会根据您的 shell 来源
~/.zshrc、~/.bashrc或~/.profile，捕获生成的别名、函数和 shell 选项，并将它们应用于每个 Bash 命令。
CLAUDE_ENV_FILE 设置为 shell 脚本，或使用 SessionStart hook 动态填充它。
两个限制限制每个命令：
- 超时：默认为两分钟。Claude 可以使用
timeout参数请求每个命令最多 10 分钟。使用BASH_DEFAULT_TIMEOUT_MS和BASH_MAX_TIMEOUT_MS覆盖默认值和上限。 - 输出长度：默认为 30,000 个字符。当命令产生超过该数量的输出时，Claude Code 将完整输出保存到会话目录中的文件，并给 Claude 文件路径加上开头的简短预览。Claude 在需要其余部分时读取或搜索该文件。使用
BASH_MAX_OUTPUT_LENGTH提高限制，最高为 150,000 个字符的硬上限。
run_in_background: true 以将命令作为后台任务启动并在其运行时继续工作。使用 /tasks 列出和停止后台任务。在使用 -p 标志的非交互模式下，后台任务在运行的最终结果后不久结束。
Edit 工具行为
Edit 工具执行精确的字符串替换。它接受old_string 和 new_string 并用后者替换前者。它不使用正则表达式或模糊匹配。
三个检查必须通过才能应用编辑。在任何检查之前，与 Read 拒绝规则匹配的路径会被拒绝，包括在那里创建新文件。此拒绝需要 Claude Code v2.1.208 或更高版本。
- 编辑前读取：Claude 在当前对话中读取文件后才能编辑它，并且以
PARTIAL view通知中断的读取不计数。Claude Opus 4.6、Claude Haiku 4.5 和更早的模型始终需要读取。较新的模型可以在读取不需要权限提示且 Read 工具可用时编辑未读文件。 - 匹配：
old_string必须在文件中完全按照编写的方式出现。单个空格或缩进差异足以导致不匹配。 - 唯一性：
old_string必须恰好出现一次。当它出现多次时，Claude 要么提供一个更长的字符串，其中包含足够的周围上下文来确定一个出现，要么设置replace_all: true来替换所有出现。
old_string 与当前内容完全且明确匹配，并且 Claude Code 可以读取文件而无需提示时。针对文件的当前内容进行匹配可以保持安全，结果会注明该文件包含其他更改，以便 Claude 在依赖周围内容的编辑之前重新读取它。在任何其他情况下，例如过时的 old_string 或与多个出现匹配而没有 replace_all 的情况，Claude 在编辑前重新读取文件。未读和已更改文件的宽松处理需要 Claude Code v2.1.208 或更高版本；在此之前，Claude Code 拒绝对它在对话中未读过或在读取后在磁盘上更改的任何文件进行编辑。
使用 Bash 查看文件也满足编辑前读取要求，当命令是 cat、head、tail、sed -n 'X,Yp'、grep、egrep 或 fgrep 在单个文件上，没有管道或重定向时。管道输出和其他 Bash 命令不计入编辑前读取检查。
这仅影响编辑资格，不影响权限。Read 和 Edit 拒绝规则也适用于 Claude Code 在 Bash 中识别的文件命令，例如 cat、head、tail、sed 和 grep，但不适用于间接读取或写入文件的任意子进程，例如自己打开文件的 Python 或 Node 脚本。对于编辑前读取，识别的命令集与上面的拒绝规则列表不同：例如，egrep 和 fgrep 计入编辑前读取但不针对 Read 拒绝规则进行检查。对于覆盖每个进程的操作系统级别强制，请启用沙箱。
Glob 工具行为
Glob 工具按名称模式查找文件。它支持标准 glob 语法，包括** 用于递归目录匹配：
**/*.js匹配任何深度的所有.js文件src/**/*.ts匹配src/下的所有.ts文件*.{json,yaml}匹配当前目录中的.json和.yaml文件
.gitignore，因此它找到被 gitignore 的文件以及跟踪的文件。这与 Grep 不同，后者跳过被 gitignore 的文件。要使 Glob 尊重 .gitignore，请在启动 Claude Code 之前设置 CLAUDE_CODE_GLOB_NO_IGNORE=false。
包含空字节的 pattern 或 path 值会返回错误，要求 Claude 将其删除。
Grep 工具行为
Grep 工具在文件内容中搜索模式。Glob 按名称查找文件，Grep 在文件内查找行。 Grep 基于 ripgrep 并使用 ripgrep 的正则表达式语法，而不是 POSIX grep。包含正则表达式元字符的模式需要转义。例如，在 Go 代码中查找interface{} 需要模式 interface\{\}。
一个 ripgrep 拒绝的模式、glob 或文件类型会返回一个包含 ripgrep 诊断信息的错误，这样 Claude 可以更正输入并再次搜索。在 v2.1.208 之前，Claude Code 将被拒绝的输入报告为 No files found，而不是错误，即使搜索的文本存在于目标文件中。
三种输出模式控制返回的内容：
files_with_matches：仅文件路径，无行内容。这是默认值。content：匹配的行及其文件和行号。count：每个文件的匹配计数，后跟所有匹配文件的总计数。总计覆盖每一个匹配，即使工具的head_limit或offset参数截断了列出的每个文件条目。在 v2.1.208 之前，总计仅对列出的条目求和。
glob 参数（例如 **/*.tsx）按文件范围结果，或使用 type 参数（例如 py 或 rust）按语言范围结果。默认情况下，模式在单行内匹配。Claude 可以设置 multiline: true 以跨行边界匹配。
Grep 尊重 .gitignore，因此被 gitignore 的文件会被跳过。要搜索被 gitignore 的文件，Claude 直接传递其路径。
LSP 工具行为
LSP 工具为 Claude 提供来自运行中的语言服务器的代码智能。在每次文件编辑后，它会自动报告类型错误和警告，以便 Claude 可以在没有单独构建步骤的情况下修复问题。Claude 还可以直接调用它来导航代码：- 跳转到符号的定义
- 查找对符号的所有引用
- 获取位置处的类型信息
- 列出文件中的符号
- 按名称在工作区中搜索符号
- 查找接口的实现
- 追踪调用层次结构
Monitor 工具
Monitor 工具让 Claude 在后台监视某些内容，并在其更改时做出反应，而无需暂停对话。要求 Claude：- 跟踪日志文件并在错误出现时标记它们
- 轮询 PR 或 CI 作业并在其状态更改时报告
- 监视目录以查找文件更改
- 跟踪您指向的任何长时间运行脚本的输出
- 连接到 WebSocket 源并在每条消息到达时报告
allow 和 deny 模式也适用于此处。WebSocket 源有其自己的批准提示。
该工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。当设置了 DISABLE_TELEMETRY 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 时，它也不可用。
插件可以声明在插件处于活动状态时自动启动的监视，而不是要求 Claude 启动它们。请参阅 plugin monitors。
WebSocket 源
WebSocket 源需要 Claude Code v2.1.195 或更高版本。
- 文本消息：每条消息都成为一个事件，即使消息跨越多行。
- 二进制消息：不通过。Claude 接收一个占位符行，例如
[binary frame, 512 bytes]。 - 大于 1 MiB 的消息：监视结束，因此请订阅存在的过滤源。
- 套接字关闭：监视结束，Claude 接收关闭代码。
ws 输入代替 command，单个 Monitor 调用不能将两者结合。ws 输入有两个字段：
timeout_ms 和 persistent 输入的行为与它们对命令的行为相同：监视在截止时间结束，除非设置了 persistent，TaskStop 会提前取消它。
打开 WebSocket 会提示批准，提示不提供跳过同一主机的未来提示的选项。
Claude Code 拒绝指向私有、链接本地或云元数据地址的 URL，包括解析为这些地址的主机名。它还拒绝 sandbox.network.deniedDomains 中的主机，以及当在托管设置中设置了 allowManagedDomainsOnly 时，任何在托管允许列表之外的主机。
NotebookEdit 工具行为
NotebookEdit 一次修改一个 Jupyter notebook 单元格，按其cell_id 定位单元格。它不像 Edit 在纯文本文件上那样在整个 notebook 中执行字符串替换。
三种编辑模式控制目标单元格发生的情况：
replace：覆盖单元格的源。这是默认值。insert：在目标后添加新单元格。没有cell_id时，新单元格位于 notebook 的开始。需要cell_type设置为code或markdown。delete：删除目标单元格。
Edit(...) 路径格式。像 Edit(notebooks/**) 这样的规则涵盖该目录中的 NotebookEdit 调用。
PowerShell 工具
PowerShell 工具让 Claude 本地运行 PowerShell 命令。在 Windows 上，这意味着命令在 PowerShell 中运行，而不是通过 Git Bash 路由。该工具的可用方式取决于您的平台：- 没有 Git Bash 的 Windows：该工具会自动启用。
- 安装了 Git Bash 的 Windows：该工具正在逐步推出。
- Linux、macOS 和 WSL：该工具是选择加入的。
启用 PowerShell 工具
在您的环境或settings.json 中设置 CLAUDE_CODE_USE_POWERSHELL_TOOL=1：
0 以选择退出推出。在 Linux、macOS 和 WSL 上，该工具需要 PowerShell 7 或更高版本：安装 pwsh 并确保它在您的 PATH 中。
在 Windows 上，Claude Code 自动检测 pwsh.exe（PowerShell 7+），回退到 powershell.exe（PowerShell 5.1）。启用该工具后，Claude 将 PowerShell 视为主 shell。当安装了 Git Bash 时，Bash 工具仍可用于 POSIX 脚本。
Claude Code 使用 -ExecutionPolicy Bypass 在进程范围内生成 PowerShell，因此 .ps1 脚本和模块导入可以在默认 Windows 安装上工作，无需更改计算机的策略。进程范围绕过不会覆盖组策略 MachinePolicy 或 UserPolicy，因此企业策略仍然适用。要改为遵守计算机的有效执行策略，请设置 CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1。
设置、hooks 和 skills 中的 shell 选择
三个额外的设置控制 PowerShell 的使用位置：settings.json中的"defaultShell": "powershell"：通过 PowerShell 路由交互式!命令。需要启用 PowerShell 工具。- 单个 command hooks 上的
"shell": "powershell"：在 PowerShell 中运行该 hook。Hooks 直接生成 PowerShell，因此无论CLAUDE_CODE_USE_POWERSHELL_TOOL如何，这都有效。 - skill frontmatter 中的
shell: powershell：在 PowerShell 中运行!`command`块。需要启用 PowerShell 工具。
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR 环境变量。
从 v2.1.196 开始，PowerShell 工具与 Bash 工具的搜索和 diff 退出代码处理方式相匹配。来自 grep、egrep、fgrep 和 git grep 的退出代码 1 表示没有匹配项，来自 git diff 的退出代码 1 表示存在差异，因此这些结果不会作为命令失败报告给 Claude。
预览限制
PowerShell 工具在预览期间有以下已知限制：- PowerShell 配置文件未加载
- 在 Windows 上，不支持 sandboxing
Read 工具行为
Read 工具接受文件路径并返回带有行号的内容。Claude 被指示始终传递绝对路径。 默认情况下，Read 从开始返回文件。当整个文件读取超过令牌限制时，Read 返回第一页，并显示PARTIAL view 通知，告诉 Claude 它收到了多少文件内容以及如何使用 offset 和 limit 读取更多内容。传递显式 offset 或 limit 的读取仍然超过令牌限制时会返回错误。
使用显式 limit 的读取会在选定的行超过令牌限制可能容纳的内容时立即停止，并返回错误而不加载范围的其余部分。该错误告诉 Claude 使用较小的 limit，或者当单行非常大时，改为使用 Grep 搜索特定内容。在 v2.1.208 之前，Claude Code 在拒绝前会将整个范围加载到内存中，因此具有极长单行的文件可能会耗尽内存。
读取空文件会返回一个通知，说明文件存在但其内容为空，而超过最后一行的 offset 会返回一个给出文件行数的通知。在 v2.1.208 之前，读取空文件会返回过去末尾的通知。
Read 处理纯文本之外的几种文件类型：
- 图像：PNG、JPG 和其他图像格式作为 Claude 可以看到的视觉内容返回，而不是原始字节。Claude Code 在发送前调整大小并重新压缩大图像以适应模型的图像大小限制，因此 Claude 可能会看到大截图的缩小版本。从 v2.1.196 开始，调整大小后仍然大于 500KB 的图像会以降低质量的 JPEG 格式重新编码，其像素尺寸保持不变。如果 Claude 在大图像中遗漏了细微的像素级细节，请要求它首先裁剪感兴趣的区域，例如使用 ImageMagick 通过 Bash。
- PDFs：Claude 完整读取短
.pdf文件。对于超过 10 页的 PDFs，它使用pages参数（例如"1-5"）按范围读取，一次最多 20 页。 - Jupyter notebooks：
.ipynb文件返回所有单元格及其输出，包括代码、markdown 和可视化。
ls 列出目录内容。
WebFetch 工具行为
WebFetch 接受 URL 和描述要提取内容的提示。它获取页面，当服务器返回 HTML 时将响应转换为 Markdown，并使用小型快速模型针对内容运行提示。对于大多数获取，Claude 接收该模型的答案，而不是原始页面。转换步骤不可配置。 这使 WebFetch 在设计上是有损的。提取提示确定到达 Claude 的内容，因此说页面不提及某内容的结果可能只意味着提示没有询问它。要求 Claude 使用更具体的提示再次获取，或通过 Bash 使用curl 获取未处理的页面。
几种行为塑造 Claude 接收的响应：
- HTTP URLs 自动升级到 HTTPS。
- 大页面在处理前被截断到固定字符限制。
- 响应缓存 15 分钟，因此相同 URL 的重复获取快速返回。
- 当 URL 重定向到不同的主机时，WebFetch 返回一个文本结果，命名原始 URL 和重定向目标，而不是跟随它。Claude 然后使用第二个 WebFetch 调用获取新 URL。
acceptEdits 权限模式中，WebFetch 在首次到达新域时提示，除了一组内置的预批准文档域可以无需提示地获取。要提前允许另一个域而不提示，请添加像 WebFetch(domain:example.com) 这样的权限规则。auto 和 bypassPermissions 权限模式完全跳过提示。
deny、ask 或 allow 中的显式 WebFetch(domain:...) 规则优先于预批准集合，因此您可以阻止预批准域或要求对其进行提示。
WebFetch 设置以 Claude-User 开头的 User-Agent 标头，以及优先 Markdown 而不是 HTML 的 Accept 标头，以便支持内容协商的服务器可以直接返回 Markdown。Sandbox 网络规则单独配置，因此您希望沙箱进程到达的域仍然需要显式沙箱权限规则。
WebSearch 工具行为
WebSearch 针对 Anthropic 的网络搜索后端运行查询，并返回结果标题和 URLs。它不获取结果页面。要读取 Claude 在搜索结果中找到的页面，它使用 WebFetch 进行后续操作。 该工具可能在返回结果之前发出最多八个后端搜索，在内部优化搜索。Claude 可以使用allowed_domains 范围结果以仅包含某些主机，或使用 blocked_domains 排除它们。这两个列表不能在单个调用中组合。
搜索后端不可配置。要使用不同的提供商进行搜索，请添加一个 MCP server，公开搜索工具。
WebSearch 权限规则不接受 specifier。allow 或 deny 中的裸 WebSearch 条目是唯一的形式。
WebSearch 在 Claude API、Claude Platform on AWS 和 Microsoft Foundry 上可用。在 Google Cloud 的 Agent Platform 上，它适用于 Claude 4 及更高版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公开服务器端网络搜索工具。
Write 工具行为
Write 工具创建新文件或用提供的完整内容覆盖现有文件。它不追加或合并。 如果目标路径已存在，Claude 必须在当前对话中至少读取过该文件一次才能覆盖它。对未读现有文件的 Write 失败并出现错误。此约束不适用于新文件。 使用 Bash 查看文件也满足此要求，如 Edit 工具行为中所述。 对于现有文件的部分更改，Claude 使用 Edit 而不是 Write。检查哪些工具可用
您的确切工具集取决于您的提供商、平台和设置。要检查在运行中的会话中加载了什么，请直接询问 Claude：/mcp。
advisor tool 是一个 server tool，由 API 运行，而不是 Claude Code 实现的工具。它没有您可以在权限规则或 hook 匹配器中引用的名称。
另请参阅
- MCP servers：通过连接外部服务器添加自定义工具
- 权限：权限系统、规则语法和工具特定模式
- Subagents：为 subagents 配置工具访问
- Hooks：在工具执行前后运行自定义命令