Markdown驱动的轻量级AI Agent：BigQuery自然语言查询实战
2026/6/5 7:49:35
代码解析
Claude Code Tool System 与 Permission 机制深度解析
0. 背景与定位
Claude Code 是一个运行在终端的 Agentic 编码工具，其核心能力来自工具系统（Tool System）——AI 通过调用工具与文件系统、Shell、网络、子 Agent 交互。而**权限系统（Permission System）**则是这套能力的安全护城河，决定哪些工具调用可以自动执行、哪些需要用户确认、哪些被永久拒绝。
理解这两个系统，是在企业内安全部署 Claude Code、或基于 SDK 构建自定义 AI Agent 的前提。 1
1. 核心概念速览
| 概念 | 说明 |
|---|---|
| Tool | AI Agent 可调用的能力单元，如BashTool、FileReadTool |
| ToolRegistry | 工具注册表，管理所有可用工具的生命周期 |
| PermissionChecker | 权限检查器，每次工具调用前执行 |
| Permission Mode | 全局权限模式：default/acceptEdits/auto/bypassPermissions |
| Hook | 工具执行前后的生命周期钩子，可拦截、修改、阻断 |
| Sandbox | 针对BashTool的沙箱隔离层，控制网络与文件系统访问 |
| Settings Hierarchy | 配置优先级链：managed-settings.json>settings.json>settings.local.json |
2. 工具系统架构
2.1 工具分类总览
Claude Code 内置以下核心工具类： 2
| 分类 | 工具 | 核心能力 |
|---|---|---|
| 文件操作 | FileReadTool | 读取文件，支持 token 感知截断 |
FileWriteTool | 创建/覆盖文件，含路径安全校验 | |
FileEditTool | 行级 diff 编辑，含符号链接检查 | |
| Shell 执行 | BashTool | 执行 Shell 命令，支持沙箱模式 |
PowerShellTool | Windows 环境专用 Shell | |
| 网络 | WebFetchTool | 抓取 URL 内容 |
WebSearchTool | 执行网络搜索 | |
| Agent 编排 | TaskTool | 派生子 Agent（支持 Worktree 隔离） |
EnterWorktree | 切换 Claude 管理的 Git Worktree | |
| 交互 | AskUserQuestion | 向用户提问 |
| 扩展 | MCP Tools | 通过 Model Context Protocol 接入外部工具 |
注意：
sandbox属性仅作用于BashTool，不影响 Read、Write、WebFetch、MCP 等其他工具。
2.2 工具执行全链路流程
3. 权限系统深度解析
3.1 权限判断链路（Settings Hierarchy）
权限规则按以下优先级从高到低依次检查，高优先级规则可覆盖低优先级：
3.2 三种权限规则类型
// settings.json 示例{"permissions":{"allow":["Bash(git log:*)","Bash(npm test)","Read(**)"],"ask":["Bash"],"deny":["WebSearch","WebFetch"]}}| 规则类型 | 行为 | 典型场景 |
|---|---|---|
allow | 自动批准，无需确认 | 只读命令、安全的 git 操作 |
ask | 每次都弹出确认 | 高风险工具如Bash |
deny | 永久拒绝，不可绕过 | 禁止网络访问、禁止特定工具 |
通配符语法示例：
Bash(npm *)— 匹配所有 npm 子命令Bash(git * main)— 匹配操作 main 分支的 git 命令Read(**)— 匹配所有文件读取Edit(/src/**)— 仅允许编辑 src 目录
3.3 四种全局权限模式
安全提示：
bypassPermissions模式可通过disableBypassPermissionsMode: "disable"在企业策略中永久禁用。 10
4. Hook 系统：工具执行的生命周期拦截
Hook 是权限系统的重要扩展点，允许在工具执行的各个阶段注入自定义逻辑。
4.1 Hook 生命周期全景
渲染错误:Mermaid 渲染失败: Parse error on line 28: ...最终响应```[11](#0-10) ### 4.2 Hook 事件类型速 ----------------------^ Expecting '()', 'SOLID_OPEN_ARROW', 'DOTTED_OPEN_ARROW', 'SOLID_ARROW', 'SOLID_ARROW_TOP', 'SOLID_ARROW_BOTTOM', 'STICK_ARROW_TOP', 'STICK_ARROW_BOTTOM', 'SOLID_ARROW_TOP_DOTTED', 'SOLID_ARROW_BOTTOM_DOTTED', 'STICK_ARROW_TOP_DOTTED', 'STICK_ARROW_BOTTOM_DOTTED', 'SOLID_ARROW_TOP_REVERSE', 'SOLID_ARROW_BOTTOM_REVERSE', 'STICK_ARROW_TOP_REVERSE', 'STICK_ARROW_BOTTOM_REVERSE', 'SOLID_ARROW_TOP_REVERSE_DOTTED', 'SOLID_ARROW_BOTTOM_REVERSE_DOTTED', 'STICK_ARROW_TOP_REVERSE_DOTTED', 'STICK_ARROW_BOTTOM_REVERSE_DOTTED', 'BIDIRECTIONAL_SOLID_ARROW', 'DOTTED_ARROW', 'BIDIRECTIONAL_DOTTED_ARROW', 'SOLID_CROSS', 'DOTTED_CROSS', 'SOLID_POINT', 'DOTTED_POINT', got 'NEWLINE'
6. 企业部署配置参考
6.1 三种典型配置对比15
| 配置项 | settings-lax.json | settings-strict.json | settings-bash-sandbox.json |
|---|---|---|---|
禁用--dangerously-skip-permissions | ✅ | ✅ | |
| 屏蔽插件市场 | ✅ | ✅ | |
| 禁止用户自定义权限规则 | ✅ | ✅ | |
| 禁止用户自定义 Hook | ✅ | ||
| 拒绝 WebFetch/WebSearch | ✅ | ||
| Bash 工具需要审批 | ✅ | ||
| Bash 工具必须在沙箱内运行 | ✅ |
6.2 安全加固关键配置
// managed-settings.json (企业 MDM 下发){"permissions":{"disableBypassPermissionsMode":"disable","deny":["WebSearch","WebFetch"],"ask":["Bash"]},"allowManagedPermissionRulesOnly":true,"allowManagedHooksOnly":true,"sandbox":{"enabled":true,"network":{"allowedDomains":["registry.npmjs.org","api.github.com"]}}}7. 架构设计建议
7.1 安全性维度
- 永远不要在 CI/CD 中使用
--dangerously-skip-permissions，除非在完全隔离的沙箱容器内 - 使用
allowManagedPermissionRulesOnly: true防止项目级配置绕过企业策略 PreToolUseHook 可作为命令注入的最后防线
7.2 可扩展性维度
- MCP 工具：通过 Model Context Protocol 接入内部系统（数据库、CI、监控），无需修改 Claude Code 核心
- Hook 中间件：
PreToolUse返回updatedInput可实现工具输入的透明改写（如自动注入项目前缀） - PermissionRequest Hook：可实现自定义审批逻辑（如 Slack 审批流） 17
7.3 企业部署维度
managed-settings.json通过 MDM 统一下发，开发者无法覆盖settings.json提交到 Git，团队共享项目级规则settings.local.json加入.gitignore，允许开发者本地个性化
8. 总结
Claude Code 的 Tool System 与 Permission 机制构成了一套分层、可扩展、企业就绪的安全执行框架：
用户意图 ↓ Agent 推理 → 选择工具 ↓ Hook (PreToolUse) → 自定义拦截/改写 ↓ PermissionChecker → managed > user > local 规则链 ↓ Sandbox → 网络/文件系统隔离 (仅 BashTool) ↓ 系统执行 ↓ Hook (PostToolUse) → 结果处理/日志对于 AI Agent 前端架构师而言，核心落地路径是：
- 用
managed-settings.json锁定安全基线（企业场景） - 用
PreToolUseHook 实现业务级命令校验 - 用 MCP 扩展工具边界，而非直接暴露 Bash
- 用
auto模式 + 精细allow规则平衡效率与安全 19 20