// 基于 Claude Code 2.1.88 反混淆源码, src/Tool.ts（闭源，只引签名级片段）
export type Tool<
  Input extends AnyObject = AnyObject,  // AnyObject = z.ZodType<{[key: string]: unknown}>，入参必须是 zod 对象 schema
  Output = unknown,
// ...（第三个泛型 P 是进度事件类型，如 BashProgress / AgentToolProgress）
> = {
  readonly name: string
  readonly inputSchema: Input  // 一份 zod schema 三用：运行期 safeParse 校验、zodToJsonSchema 转给 API、z.infer<Input> 推静态类型
// ...

// ---- 真正干活 ----
  call(
    args: z.infer<Input>,
    context: ToolUseContext,  // 工具与整个会话的接口：messages、AppState 读写、abortController、文件读取缓存……
// ...（还有 canUseTool、parentMessage、onProgress? 共 5 个参数）
  ): Promise<ToolResult<Output>>

// ---- 安全闸门：外层调度与权限系统据此决策 ----
  isConcurrencySafe(input: z.infer<Input>): boolean  // 决定能否与相邻工具并发；按输入粒度判断，Bash 会解析具体命令
  isReadOnly(input: z.infer<Input>): boolean  // 注意：并发由上面那个决定，这个主要给权限 UI（只读展示轻量确认）和记忆提取用
  isDestructive?(input: z.infer<Input>): boolean  // 不可逆操作（删除/覆盖/发送）
  interruptBehavior?(): 'cancel' | 'block'  // 用户中途发新消息：砍掉工具，还是跑完让新消息等着（默认 block）
  validateInput?(
// ...语义校验（如 Edit 要求文件先 Read 过），失败文本直接回给模型自纠
  ): Promise<ValidationResult>
  checkPermissions(
// ...工具特有的权限逻辑（如 Bash 按子命令匹配规则）；通用裁决在 utils/permissions/permissions.ts，见下
  ): Promise<PermissionResult>

// ---- 给模型看的文字：prompt() 生成 API 请求 tools 数组里的 description 字段（utils/api.ts），
// ---- description() 是给权限弹窗等 UI 用的一句话说明（hooks/useCanUseTool.tsx）——两者容易搞反
  prompt(options: {
// ...
  }): Promise<string>
  searchHint?: string  // 配合延迟加载（shouldDefer）：schema 不随首轮请求下发，模型先用 ToolSearch 关键词搜到再加载
  maxResultSizeChars: number  // 结果超限就落盘、只回传路径+预览；Read 设为 Infinity——否则"读文件→落盘→再读"套娃
  toAutoClassifierInput(input: z.infer<Input>): unknown  // 压缩成一句摘要喂 auto 模式安全分类器；返回 '' 表示跳过

// ---- 渲染也长在接口上：终端 UI 是 React（Ink 渲染到 TTY），每个工具自带渲染方法 ----
  renderToolUseMessage(
// ...还有 renderToolResultMessage? / renderToolUseProgressMessage? 等 8 个 render* 成员，外加 getActivityDescription? / userFacingNameBackgroundColor? 等 UI 辅助成员
  ): React.ReactNode
}

// 同上 src/Tool.ts
export type ToolResult<T> = {
  data: T
  newMessages?: (  // 工具可以往对话追加消息（如 Task 把子代理产出注入主线）
// ...
  )[]
  contextModifier?: (context: ToolUseContext) => ToolUseContext  // 工具还能改写后续工具的执行上下文
// ...
}

const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: (_input?: unknown) => false,  // 拿不准就当不可并发
// ...
  isReadOnly: (_input?: unknown) => false,  // 拿不准就当有副作用——fail-closed，忘了声明的工具被保守对待而不是放松
  toAutoClassifierInput: (_input?: unknown) => '',  // 唯一往"松"倒的默认：跳过分类器，安全相关工具必须显式覆盖
// ...
}
export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
// ...
  return {
    ...TOOL_DEFAULTS,
    userFacingName: () => def.name,
// ...（最后 ...def 展开：def 自己写了的成员一律覆盖默认值。所有工具都走这里导出，默认策略只写一份）
  } as BuiltTool<D>
}

// 基于 Claude Code 2.1.88 反混淆源码, src/services/tools/toolOrchestration.ts
export async function* runTools(
  // ...
): AsyncGenerator<MessageUpdate, void>  // 整条管线是 AsyncGenerator：边执行边 yield 消息，UI 实时渲染
// ...partitionToolCalls 按 isConcurrencySafe 切批：
    if (isConcurrencySafe && acc[acc.length - 1]?.isConcurrencySafe) {
      acc[acc.length - 1]!.blocks.push(toolUse)  // 只合并"相邻"的安全调用成一批，不做全局重排
    }  // else 分支另起一批（略）
// ...并发批走 all(generators, N)，N 来自：
    parseInt(process.env.CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY || '', 10) || 10
// ...谓词抛异常按 false 处理（Bash 判断要 shell-quote 解析命令，解析不了就当不安全）

// ---- src/services/tools/toolExecution.ts：单个调用的完整生命周期 ----
export async function* runToolUse(
  // ...
): AsyncGenerator<MessageUpdateLazy, void>
// ...findToolByName 找不到（模型幻觉/旧别名）不抛异常，yield 一条 is_error 的 <tool_use_error> tool_result 回给模型
  // Validate input types with zod (surprisingly, the model is not great at generating valid input)
  const parsedInput = tool.inputSchema.safeParse(input)  // 官方注释原话：模型生成合法参数的能力"出人意料地"不行
// ...类型过了才轮到语义校验：
  const isValidCall = await tool.validateInput?.(parsedInput.data, context)
// ...再跑 PreToolUse hooks，然后进权限裁决（utils/permissions/permissions.ts 的 hasPermissionsToUseToolInner）：
  const denyRule = getDenyRuleForTool(appState.toolPermissionContext, tool)  // 1a: deny 规则最先看，谁也压不过
// ...1b 整工具 ask 规则 → 1c 才问工具自己：
    toolPermissionResult = await tool.checkPermissions(parsedInput, context)
// ...1g: .git/、.claude/、shell 配置等路径的 safetyCheck 连 bypassPermissions 模式都拦。全绿后：
    const result = await tool.call(/* args, context, canUseTool, parentMessage, onProgress */)
// ...结果序列化成 API 格式（超过 maxResultSizeChars 的落盘换成路径+预览）：
    const mappedToolResultBlock = tool.mapToolResultToToolResultBlockParam(
      // ...
    )