Claude Code Tool System 架构分析

// src/Tool.ts:362-366
export type Tool<
  Input extends AnyObject = AnyObject,
  Output = unknown,
  P extends ToolProgressData = ToolProgressData,
> = {
  readonly name: string
  aliases?: string[]             // 重命名兼容
  searchHint?: string            // ToolSearch 关键词匹配

  // --- 核心方法 ---
  call(args, context, canUseTool, parentMessage, onProgress): Promise<ToolResult<Output>>
  description(input, options): Promise<string>
  prompt(options): Promise<string>

  // --- Schema ---
  readonly inputSchema: Input                    // Zod schema
  readonly inputJSONSchema?: ToolInputJSONSchema // MCP JSON Schema
  outputSchema?: z.ZodType<unknown>

  // --- 能力标志 ---
  isConcurrencySafe(input): boolean    // 默认 false
  isEnabled(): boolean                 // 默认 true
  isReadOnly(input): boolean           // 默认 false
  isDestructive?(input): boolean       // 不可逆操作标记

  // --- 权限 ---
  validateInput?(input, context): Promise<ValidationResult>
  checkPermissions(input, context): Promise<PermissionResult>

  // --- UI 渲染 ---
  renderToolUseMessage(input, options): React.ReactNode
  renderToolResultMessage(content, progressMessages, options): React.ReactNode
  renderToolUseProgressMessage?(progressMessages, options): React.ReactNode
  renderToolUseErrorMessage?(result, options): React.ReactNode
  renderToolUseRejectedMessage?(input, options): React.ReactNode

  // --- 结果映射 ---
  mapToolResultToToolResultBlockParam(content, toolUseID): ToolResultBlockParam
  extractSearchText?(out: Output): string
}

// src/Tool.ts:721-726
type DefaultableToolKeys =
  | 'isEnabled' | 'isConcurrencySafe' | 'isReadOnly'
  | 'isDestructive' | 'checkPermissions' | 'toAutoClassifierInput'
  | 'userFacingName'

export type ToolDef<Input, Output, P> =
  Omit<Tool<Input, Output, P>, DefaultableToolKeys> &
  Partial<Pick<Tool<Input, Output, P>, DefaultableToolKeys>>

// src/Tool.ts:757-769 — 安全默认值
const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: (_input?: unknown) => false,  // 默认非并发安全
  isReadOnly: (_input?: unknown) => false,         // 默认假设写入
  isDestructive: (_input?: unknown) => false,
  checkPermissions: (input, _ctx) =>
    Promise.resolve({ behavior: 'allow', updatedInput: input }),
  toAutoClassifierInput: (_input?: unknown) => '',
  userFacingName: (_input?: unknown) => '',
}

// src/Tool.ts:783-792
export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return {
    ...TOOL_DEFAULTS,
    userFacingName: () => def.name,
    ...def,
  } as BuiltTool<D>
}

export type ToolResult<T> = {
  data: T
  newMessages?: (UserMessage | AssistantMessage | AttachmentMessage | SystemMessage)[]
  contextModifier?: (context: ToolUseContext) => ToolUseContext
  mcpMeta?: { _meta?: Record<string, unknown>; structuredContent?: Record<string, unknown> }
}

// src/tools.ts:193-251
export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]), // 条件注册
    ExitPlanModeV2Tool,
    FileReadTool, FileEditTool, FileWriteTool,
    NotebookEditTool, WebFetchTool, TodoWriteTool,
    WebSearchTool, TaskStopTool, AskUserQuestionTool,
    SkillTool, EnterPlanModeTool,
    // ... 更多条件工具
    ...(process.env.NODE_ENV === 'test' ? [TestingPermissionTool] : []),
  ]
}

// src/tools.ts:271-327
export const getTools = (permissionContext: ToolPermissionContext): Tools => {
  if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) { /* 只返回 Bash/Read/Edit */ }
  const tools = getAllBaseTools().filter(tool => !specialTools.has(tool.name))
  let allowedTools = filterToolsByDenyRules(tools, permissionContext)
  if (isReplModeEnabled()) { /* 过滤 REPL_ONLY_TOOLS */ }
  const isEnabled = allowedTools.map(_ => _.isEnabled())
  return allowedTools.filter((_, i) => isEnabled[i])
}

export function assembleToolPool(permissionContext, mcpTools): Tools {
  const builtInTools = getTools(permissionContext)
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)
  // 内置工具在前（优先级更高），MCP 工具在后，各自按名称排序保证缓存稳定性
  const byName = (a, b) => a.name.localeCompare(b.name)
  return uniqBy(
    [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),
    'name',
  )
}

// 权限行为：三方决策
type PermissionBehavior = 'allow' | 'deny' | 'ask'

// 权限模式：控制整体策略
type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions'
                    | 'dontAsk' | 'plan' | 'auto' | 'bubble'

// 权限规则
type PermissionRule = {
  source: PermissionRuleSource       // userSettings, projectSettings, localSettings, ...
  ruleBehavior: PermissionBehavior
  ruleValue: { toolName: string; ruleContent?: string }
}

type ValidationResult =
  | { result: true }
  | { result: false; message: string; errorCode: number }

// src/Tool.ts:500-503
checkPermissions(input: z.infer<Input>, context: ToolUseContext): Promise<PermissionResult>

z.strictObject({
  command: z.string(),
  description: z.string().optional(),
  timeout: z.number().optional(),
  run_in_background: z.boolean().optional(),
})

z.strictObject({
  file_path: z.string(),
  offset: z.number().int().nonnegative().optional(),
  limit: z.number().int().positive().optional(),
  pages: z.string().optional(),     // PDF 页码范围
})

// 基础
z.object({
  description: z.string(),
  prompt: z.string(),
  subagent_type: z.string().optional(),
  model: z.enum(['sonnet', 'opus', 'haiku']).optional(),
  run_in_background: z.boolean().optional(),
})
// 扩展（feature-gated）
+ { name, team_name, mode, isolation, cwd }

// src/tools/MCPTool/MCPTool.ts:27-77
export const MCPTool = buildTool({
  isMcp: true,          // MCP 标记
  name: 'mcp',          // 占位名 — 被 mcpClient.ts 覆盖
  maxResultSizeChars: 100_000,
  // 以下方法全部被覆盖
  async call() { return { data: '' } },
  async checkPermissions() { return { behavior: 'passthrough', ... } },
  inputSchema: z.object({}).passthrough(),  // 接受任意输入
})

z.strictObject({
  pattern: z.string(),
  path: z.string().optional(),
  glob: z.string().optional(),
  output_mode: z.enum(['content', 'files_with_matches', 'count']).optional(),
  '-B', '-A', '-C', context: z.number().optional(),  // 上下文行
  '-n': z.boolean().optional(),   // 行号
  '-i': z.boolean().optional(),   // 大小写不敏感
  type: z.string().optional(),    // 文件类型
  head_limit: z.number().optional(),
  offset: z.number().optional(),
  multiline: z.boolean().optional(),
})

// src/tools/WebFetchTool/WebFetchTool.ts:104-180
async checkPermissions(input, context): Promise<PermissionDecision> {
  // 1. 预批准主机 → allow
  if (isPreapprovedHost(hostname, pathname)) return { behavior: 'allow', ... }
  // 2. deny 规则 → deny
  // 3. ask 规则 → ask
  // 4. allow 规则 → allow
  // 5. 无规则 → ask (默认)
  return { behavior: 'ask', suggestions: buildSuggestions(ruleContent) }
}

const inputSchema = lazySchema(() => z.strictObject({ ... }))
type InputSchema = ReturnType<typeof inputSchema>

// 在 ToolDef 中：
get inputSchema(): InputSchema { return inputSchema() }

// 只读工具声明并发安全
isConcurrencySafe() { return true }
isReadOnly() { return true }

// 写入工具默认非并发安全（TOOL_DEFAULTS 中 isConcurrencySafe = false）
// BashTool 动态判断
isConcurrencySafe(input) { return this.isReadOnly(input) }

// BashTool
toAutoClassifierInput(input) { return input.command }
// FileReadTool
toAutoClassifierInput(input) { return input.file_path }
// 无安全相关性的工具可省略（默认 ''）

// BashTool (src/tools/BashTool/BashTool.tsx:445-467)
async preparePermissionMatcher({ command }) {
  const parsed = await parseForSecurity(command)
  if (parsed.kind !== 'simple') return () => true  // fail-safe
  const subcommands = parsed.commands.map(c => c.argv.join(' '))
  return pattern => { /* 匹配逻辑 */ }
}

// src/tools.ts:16-18
const REPLTool = process.env.USER_TYPE === 'ant'
  ? require('./tools/REPLTool/REPLTool.js').REPLTool
  : null