第8章：工具系统 —— 47 个成员的接口与延迟加载

readonly name: string
aliases?: string[]              // 改名后的向后兼容
readonly inputSchema: Input     // Zod
readonly inputJSONSchema?: ToolInputJSONSchema   // MCP 工具直接给 JSON Schema
outputSchema?: z.ZodType<unknown>

// If not found, check if it's a deprecated tool being called by alias
// (e.g., old transcripts calling "KillShell" which is now an alias for "TaskStop")

isEnabled(): boolean
isReadOnly(input): boolean
isConcurrencySafe(input): boolean
isDestructive?(input): boolean          // 「只在真正不可逆时设」
isOpenWorld?(input): boolean
isMcp?: boolean
isLsp?: boolean
requiresUserInteraction?(): boolean

/** Defaults to false. Only set when the tool performs irreversible operations
 *  (delete, overwrite, send). */

call(args, context, canUseTool, parentMessage, onProgress?): Promise<ToolResult<Output>>
validateInput?(input, context): Promise<ValidationResult>
checkPermissions(input, context): Promise<PermissionResult>
getPath?(input): string

/**
 * What should happen when the user submits a new message while this tool is running.
 * - `'cancel'` — stop the tool and discard its result
 * - `'block'`  — keep running; the new message waits
 * Defaults to `'block'` when not implemented.
 */
interruptBehavior?(): 'cancel' | 'block'
inputsEquivalent?(a, b): boolean

maxResultSizeChars: number          // 第 7 章讲过
readonly shouldDefer?: boolean      // 本章 §3
readonly alwaysLoad?: boolean       // 本章 §3
searchHint?: string                 // 本章 §3

/**
 * Called on copies of tool_use input before observers see it (SDK stream,
 * transcript, canUseTool, PreToolUse/PostToolUse hooks). Mutate in place
 * to add legacy/derived fields. Must be idempotent. The original API-bound
 * input is never mutated (preserves prompt cache). Not re-applied when a
 * hook/permission returns a fresh updatedInput — those own their shape.
 */
backfillObservableInput?(input: Record<string, unknown>): void

// Backfill legacy/derived fields on a shallow clone so hooks/canUseTool see
// them without affecting tool.call(). SendMessageTool adds fields; file
// tools overwrite file_path with expandPath — that mutation must not reach
// call() because tool results embed the input path verbatim (e.g. "File
// created successfully at: {path}"), and changing it alters the serialized
// transcript and VCR fixture hashes.

if (backfilledClone && processedInput !== callInput
    && 'file_path' in processedInput && 'file_path' in callInput
    && processedInput.file_path === backfilledClone.file_path) {
  callInput = { ...processedInput, file_path: callInput.file_path }   // 换回原值
} else if (processedInput !== backfilledClone) {
  callInput = processedInput
}

description(input, options): Promise<string>
prompt(options): Promise<string>
userFacingName(input): string
userFacingNameBackgroundColor?(input): keyof Theme | undefined
renderToolUseMessage(...)
renderToolResultMessage?(...)
renderToolUseProgressMessage?(...)
renderToolUseQueuedMessage?(): React.ReactNode
renderToolUseRejectedMessage?(...)
renderToolUseErrorMessage?(...)
renderToolUseTag?(input): React.ReactNode
isSearchOrReadCommand?(input): { isSearch, isRead, isList? }
…

/**
 * Returns information about whether this tool use is a search or read operation
 * that should be collapsed into a condensed display in the UI.
 */

/**
 * Prepare a matcher for hook `if` conditions (permission-rule patterns like
 * "git *" from "Bash(git *)"). Called once per hook-input pair; any
 * expensive parsing happens here. Returns a closure that is called per
 * hook pattern.
 */
preparePermissionMatcher?(input): Promise<(pattern: string) => boolean>
readonly strict?: boolean

export function isDeferredTool(tool: Tool): boolean {
  // Explicit opt-out via _meta['anthropic/alwaysLoad'] — tool appears in the
  // initial prompt with full schema. Checked first so MCP tools can opt out.
  if (tool.alwaysLoad === true) return false

  // MCP tools are always deferred (workflow-specific)
  if (tool.isMcp === true) return true

  // Never defer ToolSearch itself — the model needs it to load everything else
  if (tool.name === TOOL_SEARCH_TOOL_NAME) return false

  // Fork-first experiment: Agent must be available turn 1, not behind ToolSearch.
  if (feature('FORK_SUBAGENT') && tool.name === AGENT_TOOL_NAME) {
    if (isForkSubagentEnabled()) return false
  }
  …
}

/**
 * Tool search mode:
 *   - 'tst': Tool Search Tool — deferred tools discovered via ToolSearchTool (always enabled)
 *   - 'tst-auto': auto — tools deferred only when they exceed threshold
 *   - 'standard': tool search disabled — all tools exposed inline
 *
 *   ENABLE_TOOL_SEARCH    Mode
 *   auto / auto:1-99      tst-auto
 *   true / auto:0         tst
 *   false / auto:100      standard
 *   (unset)               tst (default: always defer MCP and shouldDefer tools)
 */

/**
 * Default percentage of context window at which to auto-enable tool search.
 * When MCP tool descriptions exceed this percentage (in tokens), tool search is enabled.
 */
const DEFAULT_AUTO_TOOL_SEARCH_PERCENTAGE = 10 // 10%

function getAutoToolSearchTokenThreshold(model: string): number {
  const contextWindow = getContextWindowForModel(model, getMergedBetas(model))
  return Math.floor(contextWindow * (getAutoToolSearchPercentage() / 100))
}

/** Approximate chars per token for MCP tool definitions (name + description + input schema). */
const CHARS_PER_TOKEN = 2.5

memoize(async (…) => {…}, (tools: Tools) =>
  tools.filter(t => isDeferredTool(t)).map(t => t.name).join(','))

/**
 * One-line capability phrase used by ToolSearch for keyword matching.
 * Helps the model find this tool via keyword search when it's deferred.
 * 3–10 words, no trailing period.
 * Prefer terms not already in the tool name (e.g. 'jupyter' for NotebookEdit).
 */
searchHint?: string

/**
 * Appended to Zod errors when a deferred tool wasn't in the discovered-tool
 * set — re-runs the claude.ts schema-filter scan dispatch-time to detect the
 * mismatch. The raw Zod error ("expected array, got string") doesn't tell the
 * model to re-load the tool; this hint does.
 */
export function buildSchemaNotSentHint(tool, messages, tools): string | null {
  if (!isToolSearchEnabledOptimistic()) return null
  if (!isToolSearchToolAvailable(tools)) return null
  if (!isDeferredTool(tool)) return null
  const discovered = extractDiscoveredToolNames(messages)
  if (discovered.has(tool.name)) return null
  return (
    `\n\nThis tool's schema was not sent to the API — it was not in the discovered-tool set derived from message history. ` +
    `Without the schema in your prompt, typed parameters (arrays, numbers, booleans) get emitted as strings and the client-side parser rejects them. ` +
    `Load the tool first: call ${TOOL_SEARCH_TOOL_NAME} with query "select:${tool.name}", then retry this call.`
  )
}

for (const { isConcurrencySafe, blocks } of partitionToolCalls(toolUseMessages, currentContext)) {
  if (isConcurrencySafe) {
    // 并发跑这一批
    yield* runToolsConcurrently(blocks, …)
    // 批跑完后，统一应用所有 contextModifier
  } else {
    // 串行跑
    yield* runToolsSerially(blocks, …)
  }
}

/**
 * Partition tool calls into batches where each batch is either:
 * 1. A single non-read-only tool, or
 * 2. Multiple consecutive read-only tools
 */

function getMaxToolUseConcurrency(): number {
  return parseInt(process.env.CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY || '', 10) || 10
}

const isConcurrencySafe = parsedInput?.success
  ? (() => {
      try {
        return Boolean(tool?.isConcurrencySafe(parsedInput.data))
      } catch {
        // If isConcurrencySafe throws (e.g., due to shell-quote parse failure),
        // treat as not concurrency-safe to be conservative
        return false
      }
    })()
  : false

const queuedContextModifiers: Record<string, ((context) => ToolUseContext)[]> = {}
for await (const update of runToolsConcurrently(…)) {
  if (update.contextModifier) {
    queuedContextModifiers[toolUseID] ??= []
    queuedContextModifiers[toolUseID].push(modifyContext)
  }
  yield { message: update.message, newContext: currentContext }   // ← 还是旧的
}
// 批全部跑完之后，按 block 顺序统一应用
for (const block of blocks) {
  for (const modifier of queuedContextModifiers[block.id] ?? []) {
    currentContext = modifier(currentContext)
  }
}

if (update.contextModifier) {
  currentContext = update.contextModifier.modifyContext(currentContext)
}

description(input, options): Promise<string>    // 针对这一次调用的描述（UI / 权限对话框）
prompt(options): Promise<string>                // 工具的 schema description（发给模型）

prompt(options: {
  getToolPermissionContext: () => Promise<ToolPermissionContext>
  tools: Tools
  agents: AgentDefinition[]
  allowedAgentTypes?: string[]
}): Promise<string>

cd claude-code-deep-dive/extracted-source

# 1. Tool 类型全文（300 行，建议整读）
sed -n '362,680p' src/Tool.ts

# 2. 并发分区与上限
cat src/services/tools/toolOrchestration.ts

# 3. 延迟加载判定
sed -n '55,120p' src/tools/ToolSearchTool/prompt.ts

# 4. 三种模式与 10% 阈值
sed -n '43,175p' src/utils/toolSearch.ts

# 5. 「schema 没发」诊断提示
grep -n -B12 -A20 'buildSchemaNotSentHint' src/services/tools/toolExecution.ts

# 6. 两份输入（可观测 vs API 绑定）
grep -n -B8 -A20 'backfillObservableInput' src/Tool.ts src/services/tools/toolExecution.ts

# 7. 42 个工具目录
ls -d src/tools/*/

# 本会话里的 ToolSearch 提示（在 Claude Code 里翻上下文即可看到）
# 形如：The following deferred tools are now available via ToolSearch…

# 关掉延迟加载对比
ENABLE_TOOL_SEARCH=false claude