claude-code/docs/tool-system.md

工具系统分析

架构概述

工具系统是 Claude Code 的核心能力层，定义了 Agent 可以执行的所有操作。每个工具是一个自包含模块，包含输入 Schema、权限模型和执行逻辑。

classDiagram
    class Tool {
        +string name
        +string description
        +ToolInputJSONSchema inputSchema
        +isEnabled() boolean
        +getDescription() string
        +getPrompt() string
        +execute(input, context) ToolResult
        +validateInput(input) ValidationResult
    }

    class BashTool {
        +name = "Bash"
        +execute() 运行 Shell 命令
        +沙盒支持
        +安全验证
    }

    class FileReadTool {
        +name = "Read"
        +支持图片/PDF/Notebook
        +行号范围读取
    }

    class FileWriteTool {
        +name = "Write"
        +完整文件写入
        +读取前置检查
    }

    class FileEditTool {
        +name = "Edit"
        +字符串替换编辑
        +replace_all 模式
    }

    class GlobTool {
        +name = "Glob"
        +文件模式匹配
        +基于 ripgrep
    }

    class GrepTool {
        +name = "Grep"
        +内容正则搜索
        +ripgrep 集成
    }

    class AgentTool {
        +name = "Agent"
        +子代理生成
        +worktree 隔离
        +代理类型选择
    }

    class MCPTool {
        +MCP 服务器工具调用
    }

    class LSPTool {
        +LSP 操作
        +goToDefinition 等
    }

    class WebFetchTool {
        +URL 内容获取
    }

    class WebSearchTool {
        +Web 搜索
    }

    Tool <|-- BashTool
    Tool <|-- FileReadTool
    Tool <|-- FileWriteTool
    Tool <|-- FileEditTool
    Tool <|-- GlobTool
    Tool <|-- GrepTool
    Tool <|-- AgentTool
    Tool <|-- MCPTool
    Tool <|-- LSPTool
    Tool <|-- WebFetchTool
    Tool <|-- WebSearchTool

工具注册机制

工具注册在 src/tools.ts 中，通过 getAllBaseTools() 函数集中管理：

flowchart TD
    A[getAllBaseTools] --> B{环境判断}
    B -->|默认| C[核心工具集]
    B -->|USER_TYPE=ant| D[内部工具集]
    B -->|feature flag| E[特性开关工具]

    C --> F[AgentTool, BashTool, FileReadTool, FileEditTool, FileWriteTool, GlobTool, GrepTool, NotebookEditTool, WebFetchTool, WebSearchTool, AskUserQuestionTool, SkillTool, BriefTool, TaskStopTool, TodoWriteTool, ExitPlanModeV2Tool, ListMcpResourcesTool, ReadMcpResourceTool]

    D --> G[ConfigTool, TungstenTool, REPLTool, SuggestBackgroundPRTool]

    E --> H[SleepTool PROACTIVE/KAIROS]
    E --> I[CronCreateTool/CronDeleteTool/CronListTool AGENT_TRIGGERS]
    E --> J[RemoteTriggerTool AGENT_TRIGGERS_REMOTE]
    E --> K[EnterWorktreeTool/ExitWorktreeTool]
    E --> L[TeamCreateTool/TeamDeleteTool]
    E --> M[SendMessageTool]
    E --> N[ToolSearchTool]
    E --> O[WorkflowTool WORKFLOW_SCRIPTS]
    E --> P[WebBrowserTool WEB_BROWSER_TOOL]
    E --> Q[MonitorTool MONITOR_TOOL]
    E --> R[PowerShellTool]

工具分类

文件操作类

工具	名称	功能
FileReadTool	Read	读取文件（支持图片、PDF、Jupyter Notebook）
FileWriteTool	Write	创建或覆盖文件
FileEditTool	Edit	部分文件修改（字符串替换）
GlobTool	Glob	文件模式匹配搜索
GrepTool	Grep	基于 ripgrep 的内容搜索
NotebookEditTool	NotebookEdit	Jupyter Notebook 编辑

执行类

工具	名称	功能
BashTool	Bash	Shell 命令执行（含沙盒）
PowerShellTool	PowerShell	Windows PowerShell 命令

网络类

工具	名称	功能
WebFetchTool	WebFetch	获取 URL 内容
WebSearchTool	WebSearch	Web 搜索

代理和协调类

工具	名称	功能
AgentTool	Agent	生成子代理（支持 worktree 隔离）
SendMessageTool	SendMessage	代理间消息传递
TeamCreateTool	TeamCreate	创建代理团队
TeamDeleteTool	TeamDelete	删除代理团队
TaskCreateTool	TaskCreate	创建任务
TaskGetTool	TaskGet	获取任务详情
TaskUpdateTool	TaskUpdate	更新任务状态
TaskListTool	TaskList	列出所有任务
TaskOutputTool	TaskOutput	获取后台任务输出
TaskStopTool	TaskStop	停止后台任务

交互类

工具	名称	功能
AskUserQuestionTool	AskUserQuestion	向用户提问获取输入
EnterPlanModeTool	EnterPlanMode	进入计划模式
ExitPlanModeV2Tool	ExitPlanMode	退出计划模式
EnterWorktreeTool	EnterWorktree	进入 Git Worktree
ExitWorktreeTool	ExitWorktree	退出 Git Worktree

集成类

工具	名称	功能
MCPTool	(动态)	MCP 服务器工具调用
ListMcpResourcesTool	ListMcpResources	列出 MCP 资源
ReadMcpResourceTool	ReadMcpResource	读取 MCP 资源
LSPTool	LSP	Language Server Protocol 集成
SkillTool	Skill	技能执行

特殊类

工具	名称	功能
BriefTool	Brief	附件处理和上传
ConfigTool	Config	设置管理（仅内部）
ToolSearchTool	ToolSearch	延迟工具发现
TodoWriteTool	TodoWrite	待办事项管理
SleepTool	Sleep	主动模式等待
SyntheticOutputTool	SyntheticOutput	结构化输出生成
ScheduleCronTool	CronCreate/CronDelete/CronList	定时任务
RemoteTriggerTool	RemoteTrigger	远程触发
REPLTool	REPL	REPL 模式（仅内部）
WorkflowTool	Workflow	工作流脚本执行
WebBrowserTool	WebBrowser	Web 浏览器自动化

权限模型

flowchart TD
    A[工具调用请求] --> B{权限检查}
    B -->|auto 模式| C[自动允许]
    B -->|default 模式| D{规则匹配}
    B -->|plan 模式| E[只读操作允许]
    B -->|bypassPermissions| C

    D -->|允许规则| F[执行工具]
    D -->|拒绝规则| G[拒绝执行]
    D -->|无规则| H[提示用户]

    H -->|用户允许| F
    H -->|用户拒绝| G
    H -->|用户允许本次| I[临时允许并执行]

    G --> J[getDenyRuleForTool 过滤]
    J --> K[从工具列表中移除]

AgentTool 子代理架构

flowchart TD
    A[AgentTool] --> B[子代理类型选择]
    B --> C[general-purpose<br/>通用代理]
    B --> D[Explore<br/>代码探索]
    B --> E[Plan<br/>架构规划]
    B --> F[claude-code-guide<br/>使用指南]

    C --> G[可用工具: 全部]
    D --> H[可用工具: 只读<br/>Glob, Grep, Read, Agent]
    E --> I[可用工具: 只读<br/>同 Explore]

    A --> J{隔离模式}
    J -->|worktree| K[Git Worktree 隔离]
    J -->|默认| L[同目录执行]

    A --> M[代理能力]
    M --> N[并行代理启动]
    M --> O[后台运行]
    M --> P[消息传递]
    M --> Q[内存管理]

BashTool 安全机制

flowchart TD
    A[BashTool 命令执行] --> B{安全检查}
    B --> C[路径验证<br/>pathValidation.ts]
    B --> D[只读验证<br/>readOnlyValidation.ts]
    B --> E[破坏性命令警告<br/>destructiveCommandWarning.ts]
    B --> F[沙盒检查<br/>shouldUseSandbox.ts]
    B --> G[sed 命令验证<br/>sedValidation.ts]

    C --> H{在工作目录内?}
    H -->|是| I[允许执行]
    H -->|否| J[路径限制警告]

    E --> K{破坏性命令?}
    K -->|rm, git reset --hard| L[额外确认]
    K -->|其他| I

    F --> M{沙盒可用?}
    M -->|是| N[沙盒执行]
    M -->|否| I