# Claude Code 工具参考

> Claude Code 内置工具、权限规则、Hooks matcher、Bash/Edit/Grep/Agent 等工具行为,以及如何通过 MCP 扩展工具。

URL: https://docs.passion8.cc/docs/claude-code/tools
Language: zh-CN
Publisher: Passion8

Claude Code 的工具名会直接出现在 `permissions`、Hooks matcher、[子代理](https://docs.passion8.cc/docs/claude-code/subagents) `tools`、Skill `allowed-tools` 和 CLI flags 里。理解工具名,才能写出可靠的权限和自动化规则。

## 常见内置工具

| 工具 | 用途 | 通常是否需要权限 |
| --- | --- | --- |
| `Read` | 读取文件 | 受 Read deny/allow 影响 |
| `Edit` | 精确替换文件内容 | 是 |
| `Write` | 新建或覆盖文件 | 是 |
| `Bash` | 运行 shell 命令 | 是 |
| `PowerShell` | 在 Windows 或启用后运行 PowerShell | 是 |
| `Glob` | 按文件名查找 | 否 |
| `Grep` | 用 ripgrep 搜索内容 | 否,但受 Read 路径规则影响 |
| `LSP` | 跳定义、查引用、类型诊断 | 否 |
| `Agent` | 启动子代理 | 否,子代理内部工具仍按权限判断 |
| `Monitor` | 后台监控命令、日志、WebSocket | 是 |
| `WebFetch` | 读取网页 | 是 |
| `WebSearch` | 搜索网页 | 是 |
| `Skill` | 调用 skill | 依赖 skill 和规则 |
| `Workflow` | 运行动态 workflow | 是 |

MCP 工具名形如 `mcp__server__tool`。如果要一次性禁用 MCP,可以用 `mcp__*` 规则。

## 权限规则格式

| 格式 | 适用工具 | 例子 |
| --- | --- | --- |
| `Bash(pattern)` | `Bash`、`Monitor` | `Bash(npm run *)` |
| `PowerShell(pattern)` | `PowerShell` | `PowerShell(Get-ChildItem *)` |
| `Read(path)` | `Read`、`Grep`、`Glob`、`LSP` | `Read(./docs/**)` |
| `Edit(path)` | `Edit`、`Write`、`NotebookEdit` | `Edit(./src/**)` |
| `Skill(name *)` | `Skill` | `Skill(deploy *)` |
| `Agent(name)` | `Agent` | `Agent(Explore)` |
| `WebFetch(domain:host)` | `WebFetch` | `WebFetch(domain:docs.example.com)` |
| `WebSearch` | `WebSearch` | `WebSearch` |

`Edit(...)` allow 通常也授予同路径读取权限。Hook matcher 使用裸工具名,例如 `Edit|Write|Bash`,不是 `Edit(./src/**)` 这种权限格式。

## Bash 行为

| 规则 | 说明 |
| --- | --- |
| 每次 Bash 是单独进程 | `export` 的变量不会自动传到下一条命令 |
| `cd` 可在主会话延续 | 只要仍在项目目录或额外授权目录内 |
| 子代理不继承 Bash cwd | 子代理每条命令按自己的工作目录执行 |
| 默认超时约 2 分钟 | Claude 可请求更长,环境变量可调 |
| 长输出会截断 | 完整输出可能保存到 session 文件,Claude 可再读 |
| 长任务可后台运行 | 用 `/tasks` 查看或停止 |

想让环境变量长期存在,启动 Claude Code 前先配置 shell,或用 `CLAUDE_ENV_FILE` / `SessionStart` hook。

## Edit 行为

`Edit` 是精确字符串替换,不是模糊 patch。它要通过三个检查:

| 检查 | 含义 |
| --- | --- |
| Read-before-edit | 当前会话里必须读过文件,且读后文件没被外部改过 |
| Match | `old_string` 必须和文件内容完全一致 |
| Uniqueness | 默认必须只匹配一次,否则需要更长上下文或 replace_all |

用 Bash 看文件不一定算“读过”。简单的 `cat`、`sed -n`、`head`、`tail` 可能被识别,但带管道、重定向或脚本读取通常不算。稳妥做法是让 Claude 使用 Read。

## Grep / Glob / LSP

| 工具 | 注意点 |
| --- | --- |
| `Glob` | 找文件名,结果按修改时间排序,默认可能包含 gitignored 文件 |
| `Grep` | 基于 ripgrep,默认尊重 `.gitignore`,正则按 rg 语法 |
| `LSP` | 需要安装语言对应的 code intelligence plugin |

大仓库里优先用 `Grep` 和 `LSP` 定位,再读少量关键文件。这样对上下文和缓存都更友好。

## Agent 工具

`Agent` 启动 [子代理](https://docs.passion8.cc/docs/claude-code/subagents)。子代理有自己的上下文窗口和缓存,完成后只把最终结果回传给主会话。

| 场景 | 建议 |
| --- | --- |
| 大范围调研 | 用子代理隔离文件读取 |
| 必须实时依赖结果 | 前台子代理 |
| 可并行后台跑 | 后台子代理或 `/batch` |
| 高风险工具 | 在 subagent frontmatter 里限制 `tools` 或 `disallowedTools` |

子代理启动本身通常不弹权限,但它内部调用 Bash/Edit/Write 时仍按权限规则判断。需要把文件改动隔离到独立目录时,配合 [Worktrees 并行工作区](https://docs.passion8.cc/docs/claude-code/worktrees)。

## 用 MCP 扩展工具

内置工具解决代码编辑和本地执行。外部系统接入用 MCP:

| 需求 | 方式 |
| --- | --- |
| 读数据库、Sentry、Linear、GitHub | 接 MCP server |
| 工具很多 | 开启 tool search 或拆 server |
| 想限制某个 MCP 工具 | `deny: ["mcp__server__tool"]` |
| 想观察调用 | Hook matcher 用 `mcp__server__tool` |

详见 [MCP 工具接入](https://docs.passion8.cc/docs/claude-code/mcp)。

## 官方参考

- [Tools reference](https://code.claude.com/docs/en/tools-reference.md)
- [Configure permissions](https://code.claude.com/docs/en/permissions.md)
- [Hooks reference](https://code.claude.com/docs/en/hooks.md)