当前位置：首页 > news >正文

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

news 2026/5/31 0:17:55

代码解析

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`
禁用`--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. 架构设计建议

用户意图 ↓ Agent 推理 → 选择工具 ↓ Hook (PreToolUse) → 自定义拦截/改写 ↓ PermissionChecker → managed > user > local 规则链 ↓ Sandbox → 网络/文件系统隔离 (仅 BashTool) ↓ 系统执行 ↓ Hook (PostToolUse) → 结果处理/日志

对于 AI Agent 前端架构师而言，核心落地路径是：