代码解析Claude Code Tool System 与 Permission 机制深度解析0. 背景与定位Claude Code 是一个运行在终端的 Agentic 编码工具其核心能力来自工具系统Tool System——AI 通过调用工具与文件系统、Shell、网络、子 Agent 交互。而**权限系统Permission System**则是这套能力的安全护城河决定哪些工具调用可以自动执行、哪些需要用户确认、哪些被永久拒绝。理解这两个系统是在企业内安全部署 Claude Code、或基于 SDK 构建自定义 AI Agent 的前提。 11. 核心概念速览概念说明ToolAI Agent 可调用的能力单元如BashTool、FileReadToolToolRegistry工具注册表管理所有可用工具的生命周期PermissionChecker权限检查器每次工具调用前执行Permission Mode全局权限模式default/acceptEdits/auto/bypassPermissionsHook工具执行前后的生命周期钩子可拦截、修改、阻断Sandbox针对BashTool的沙箱隔离层控制网络与文件系统访问Settings Hierarchy配置优先级链managed-settings.jsonsettings.jsonsettings.local.json2. 工具系统架构2.1 工具分类总览Claude Code 内置以下核心工具类 2分类工具核心能力文件操作FileReadTool读取文件支持 token 感知截断FileWriteTool创建/覆盖文件含路径安全校验FileEditTool行级 diff 编辑含符号链接检查Shell 执行BashTool执行 Shell 命令支持沙箱模式PowerShellToolWindows 环境专用 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权限规则按以下优先级从高到低依次检查高优先级规则可覆盖低优先级交互式确认选项DenyAllow无匹配allowManagedPermissionRulesOnly: true命中 deny命中 allow命中 ask无匹配命中规则无匹配工具调用请求① 检查 managed-settings.json企业 MDM 下发的托管策略执行被阻断 ❌直接执行 ✅② 检查 settings.json用户/项目级配置交互式确认③ 检查 settings.local.json本地覆盖配置仅此一次允许始终允许(持久化到 settings.json)拒绝3.2 三种权限规则类型// settings.json 示例{permissions:{allow:[Bash(git log:*),Bash(npm test),Read(**)],ask:[Bash],deny:[WebSearch,WebFetch]}}规则类型行为典型场景allow自动批准无需确认只读命令、安全的 git 操作ask每次都弹出确认高风险工具如Bashdeny永久拒绝不可绕过禁止网络访问、禁止特定工具通配符语法示例Bash(npm *)— 匹配所有 npm 子命令Bash(git * main)— 匹配操作 main 分支的 git 命令Read(**)— 匹配所有文件读取Edit(/src/**)— 仅允许编辑 src 目录3.3 四种全局权限模式权限模式 (ShiftTab 循环切换)ShiftTabShiftTabShiftTabShiftTabdefault默认模式每次工具调用均需确认acceptEdits接受编辑模式文件操作自动批准Bash 仍需确认auto自动模式内置分类器自动判断危险操作仍会拦截bypassPermissions跳过权限模式⚠️ 危险跳过所有检查安全提示bypassPermissions模式可通过disableBypassPermissionsMode: disable在企业策略中永久禁用。 104. 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 NEWLINE6. 企业部署配置参考6.1 三种典型配置对比15配置项settings-lax.jsonsettings-strict.jsonsettings-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 安全性维度防御纵深managed-settings 锁定基线PreToolUse Hook 二次校验Sandbox 网络隔离最小权限原则默认 deny 所有网络工具按需 allow 特定域名Bash 工具默认 ask仅 allow 只读命令永远不要在 CI/CD 中使用--dangerously-skip-permissions除非在完全隔离的沙箱容器内使用allowManagedPermissionRulesOnly: true防止项目级配置绕过企业策略PreToolUseHook 可作为命令注入的最后防线7.2 可扩展性维度MCP 工具通过 Model Context Protocol 接入内部系统数据库、CI、监控无需修改 Claude Code 核心Hook 中间件PreToolUse返回updatedInput可实现工具输入的透明改写如自动注入项目前缀PermissionRequest Hook可实现自定义审批逻辑如 Slack 审批流 177.3 企业部署维度下发最高优先级提交次高优先级本地调整最低优先级MDM 系统(Jamf/Intune/Kandji)managed-settings.json/Library/Application Support/Claude/Claude Code 实例项目管理员.claude/settings.json项目级配置开发者.claude/settings.local.json本地覆盖 (gitignore)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