// 基于 Claude Code 2.1.88 反混淆源码 (本地 D:/1ForCode/CCSourceCode), src/query.ts

export async function* query(          // 对外入口是个薄壳:真循环在内部的 queryLoop()
  params: QueryParams,                 // messages/systemPrompt/tools/canUseTool/maxTurns/fallbackModel...
): AsyncGenerator<StreamEvent | RequestStartEvent | Message | TombstoneMessage | ToolUseSummaryMessage, Terminal>
// 返回值是 Terminal:{ reason: 'completed' | 'blocking_limit' | 'max_turns' | 'aborted_tools' | ... }
// 用生成器是因为 agent 输出天然是流:上层 for await 边到边渲染,类似一条惰性 Stream;
// 中断 = 停止迭代 + AbortController.abort(),协作式,和 Thread.interrupt 一个思路

// queryLoop 内部:显式状态机,不是递归。跨迭代的可变状态收进一个 State 对象
type State = {
  messages: Message[]                  // 会话消息,每轮结尾整体替换
  toolUseContext: ToolUseContext       // 工具执行上下文(权限模式/abort 信号/readFileState...)
  // ... 另有 turnCount、压缩追踪、恢复计数等 7 个字段
  transition: Continue | undefined     // 上一轮为什么 continue(next_turn/reactive_compact_retry...),测试靠它断言恢复路径
}

  while (true) {
    // ① 上下文瘦身流水线,从便宜到贵依次跑:
    //    applyToolResultBudget(限单条工具结果尺寸) → snip(剪旧历史) → deps.microcompact
    //    → contextCollapse(折叠旧片段为摘要,可逆) → deps.autocompact(全量摘要,大锤)
    //    全试完还超硬阻塞线 → yield PROMPT_TOO_LONG_ERROR_MESSAGE, return { reason: 'blocking_limit' }

    // ② 流式调模型。deps.callModel 生产实现 = services/api/claude.ts 的 queryModelWithStreaming
    const toolUseBlocks: ToolUseBlock[] = []
    let needsFollowUp = false          // 唯一的循环出口信号。不信 API 的 stop_reason === 'tool_use',源码注释明说它 unreliable
    for await (const message of deps.callModel({
      // messages + systemPrompt + tools + thinking 配置 + fallback + MCP 工具 + task_budget...
    })) {
      // 边流边 yield 给上层;遇到 tool_use 块:
      //   toolUseBlocks.push(...msgToolUseBlocks); needsFollowUp = true
      // 流式 fallback:主模型断流切备用模型时,已吐出的半截消息逐条 yield tombstone 撤回。
      // 半截 thinking 块带着主模型签名,原样回灌会被 API 以 "thinking blocks cannot be modified" 拒掉
    }

    if (!needsFollowUp) {
      // 模型只说话不要工具。但先别急着结束:
      // - 流里被 withhold(暂扣未 yield)的可恢复错误在这处理:prompt-too-long 先试
      //   contextCollapse.recoverFromOverflow(便宜,保细粒度),再试 reactiveCompact.tryReactiveCompact(全量摘要),
      //   成功就 continue 原地重试;max_output_tokens 则把上限 8k 提到 64k 重发同一请求
      // - API 错误消息直接 return,跳过 stop hooks:否则 错误→hook拦截→重试→错误 死亡螺旋
      // - handleStopHooks(src/query/stopHooks.ts):hook 可以 block 掉"结束",注入错误消息逼模型继续
      return { reason: 'completed' }
    }

    // ③ 跑工具(见下一个代码块)
    const toolUpdates = streamingToolExecutor
      ? streamingToolExecutor.getRemainingResults()      // 灰度路径:边流边跑,模型还在说话工具已开跑
      : runTools(toolUseBlocks, assistantMessages, canUseTool, toolUseContext)
    // 逐条消费:yield 工具结果给 UI,同时 normalizeMessagesForAPI 过滤出 user 消息存进 toolResults

    // ④ 结果回灌:工具结果 + attachments(排队的用户消息/memory 预取/skill 发现)一起拼进下一轮
    const next: State = {
      messages: [...messagesForQuery, ...assistantMessages, ...toolResults],
      // ... turnCount + 1,超 maxTurns 则 return { reason: 'max_turns' }
      transition: { reason: 'next_turn' },
    }
    state = next                       // 整体换态后 continue。循环前的 checkpoint 至今叫 'query_recursive_call',是递归时代的化石
  }

// 基于 Claude Code 2.1.88, src/services/tools/toolOrchestration.ts

export async function* runTools(
  toolUseMessages: ToolUseBlock[],
  // ... assistantMessages, canUseTool, toolUseContext
)
// 先 partitionToolCalls 分批:连续的 concurrency-safe 工具(纯读,见 [01-Tool 抽象](/articles/sourcecode/claude-code/01-tool-抽象))
// 合并成一批并行跑;非安全工具(写文件/命令)每个自成一批串行跑
    if (isConcurrencySafe && acc[acc.length - 1]?.isConcurrencySafe) {
      acc[acc.length - 1]!.blocks.push(toolUse)    // 只合并「连续」的安全工具:穿插一个写操作就切批,保住模型下发的顺序语义
    }
// isConcurrencySafe(input) 抛异常(如 shell-quote 解析失败)按不安全处理,保守兜底

async function* runToolsConcurrently(  // 并行批,并发上限:
    parseInt(process.env.CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY || '', 10) || 10
)

// 单个工具的执行在 src/services/tools/toolExecution.ts:
export async function* runToolUse(/* toolUse, assistantMessage, canUseTool, toolUseContext */)  // 查找工具(含废弃别名回退) → 权限与执行:
async function checkPermissionsAndCallTool(/* ... */)
// 内部顺序:zod 校验输入(源码原话:模型生成合法输入的能力 surprisingly 不行) →
// 权限检查(见 [04-权限系统](/articles/sourcecode/claude-code/04-权限系统)) → PreToolUse hooks → tool.call() → PostToolUse hooks

// 基于 Claude Code 2.1.88, src/QueryEngine.ts

export class QueryEngine {
  private mutableMessages: Message[]         // 会话消息,query() 每轮的产出写回这里
  private abortController: AbortController
  // ...
  private totalUsage: NonNullableUsage       // 跨轮累计 token 用量
  private readFileState: FileStateCache      // 读过的文件缓存:Edit 前必须 Read 的校验就靠它

  async *submitMessage(                      // 驱动入口:一次用户输入 → 组装 QueryParams → yield* query()
    prompt: string | ContentBlockParam[],
    options?: { uuid?: string; isMeta?: boolean },
  ) { /* ... */ }

  interrupt(): void {
    this.abortController.abort()             // 中断只是 abort 信号,循环内各 await 点自己检查并善后
  }
  setModel(model: string): void {
    this.config.userSpecifiedModel = model   // 改配置即可,下一轮 callModel 自然用新模型
  }
}

export async function* ask({                 // 一次性便捷包装:new QueryEngine + submitMessage,print 模式(claude -p)走这里
  // ...
}) {}