代码解析

Claude Code Tool System 与 Permission 机制深度解析

0. 背景与定位

Claude Code 是一个运行在终端的 Agentic 编码工具，其核心能力来自工具系统（Tool System）——AI 通过调用工具与文件系统、Shell、网络、子 Agent 交互。而**权限系统（Permission System）**则是这套能力的安全护城河，决定哪些工具调用可以自动执行、哪些需要用户确认、哪些被永久拒绝。

理解这两个系统，是在企业内安全部署 Claude Code、或基于 SDK 构建自定义 AI Agent 的前提。 1

1. 核心概念速览

2. 工具系统架构

2.1 工具分类总览

Claude Code 内置以下核心工具类： 2

注意： 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"
    ]
  }
}

通配符语法示例：

• Bash(npm *) — 匹配所有 npm 子命令
• Bash(git * main) — 匹配操作 main 分支的 git 命令
• Read(**) — 匹配所有文件读取
• Edit(/src/**) — 仅允许编辑 src 目录

3.3 四种全局权限模式

安全提示： bypassPermissions 模式可通过 disableBypassPermissionsMode: "disable" 在企业策略中永久禁用。 10

4. Hook 系统：工具执行的生命周期拦截

Hook 是权限系统的重要扩展点，允许在工具执行的各个阶段注入自定义逻辑。

4.1 Hook 生命周期全景

6. 企业部署配置参考

6.1 三种典型配置对比 15

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 防止项目级配置绕过企业策略
• PreToolUse Hook 可作为命令注入的最后防线

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 前端架构师而言，核心落地路径是：

1. 用 managed-settings.json 锁定安全基线（企业场景）
2. 用 PreToolUse Hook 实现业务级命令校验
3. 用 MCP 扩展工具边界，而非直接暴露 Bash
4. 用 auto 模式 + 精细 allow 规则平衡效率与安全 19 20