@xyagent/cli 0.0.1

package/src-ext/runtime/claude/handleRequest.mjs

@@ -0,0 +1,1418 @@
+/**
+ * handleRequest.mjs — claude runtime D-C2.3
+ *
+ * 把 claude handleRequest 逻辑提取为独立模块，以便单元测试。
+ *
+ * createClaudeHandleRequest({ cwd, log, usage, dispatchHandlerOptions })
+ *   → async (request, ctx) => void
+ *
+ * 路由：
+ *   1. request.__kind == "agent.run.dispatch" → unifiedDispatchHandler（返回 true）→ 结束
+ *   2. 否则 → 原有 spawn 旧路径（含 usage.addCost）
+ *
+ * dispatchHandlerOptions:
+ *   relayUrl          string         relay 服务地址
+ *   bridgeToken       string         bridge 鉴权 token
+ *   producerFactory?  Function       注入 producer（测试用）
+ *   openclawInvoke?   Function       注入 openclawInvoke（测试用；若未注入则使用默认）
+ *   _spawnFactory?    Function       注入 spawnClaude（测试用，覆盖旧路径）
+ */
+
+import { spawnClaude, writeUserMessage, writeToolResult } from "./launcher.mjs";
+import { collectCustomCommands as _defaultCollectCustomCommands } from "./customCommandsCollector.mjs";
+import { probeClaudeSystemInit } from "../_shared/cliExec.mjs";
+import { normalizeClaudeLine, createLineStreamParser } from "./stdoutParser.mjs";
+import { createUnifiedDispatchHandler } from "../../core/unifiedDispatchHandler.mjs";
+import { scanWorkspacesByRuntime } from "../../core/scanWorkspaces.mjs";
+import { expandHome } from "../../core/pathExpand.mjs";
+import { ensureDefaultWorkspace, defaultWorkspacePath } from "../../core/defaultWorkspace.mjs";
+import { createWorkspace as _defaultCreateWorkspace } from "../../core/createWorkspace.mjs";
+import { createClaudeTodoTranslator } from "./todoTranslator.mjs";
+import { createAskUserQuestionTranslator, aggregateAnswers, buildOptionMaps } from "./askUserQuestionTranslator.mjs";
+import {
+  classifySlashCommand,
+  emitAssistantText,
+} from "../_shared/slashCommandRouter.mjs";
+import { createInterruptGateway } from "../../core/interruptGateway.mjs";
+import { createActiveRunRegistry } from "../../core/activeRuns.mjs";
+import { BoundedMap } from "../../core/boundedMap.mjs";
+import { waitForRunResumed } from "../../core/interruptRunListener.mjs";
+import { listSessionsForRuntime, buildSessionLabel, buildSessionSubtitle } from "../_shared/sessionPicker.mjs";
+import {
+  buildRunStarted,
+  buildRunCompleted,
+  buildRunPaused,
+  buildBlockStarted,
+  buildBlockCompleted,
+  newBlockId,
+  newRunId,
+  translateOpenClawChunkToEnvelope,
+  newBlockState,
+} from "../../../src-shared/envelope_builder.mjs";
+import { createPermissionPromptServer as _defaultPermissionPromptServerFactory } from "./permissionPromptServer.mjs";
+import { writeMcpConfig as _defaultWriteMcpConfig, deleteMcpConfig as _defaultDeleteMcpConfig } from "./mcpConfigWriter.mjs";
+import { buildPermissionInterruptBlock } from "./permissionInterruptBlock.mjs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PERMISSION_PROMPT_WORKER_SCRIPT = path.join(__dirname, "permissionPromptServerWorker.mjs");
+
+/**
+ * 把已解析的 normalizedEvent（来自 stdoutParser.mjs）翻译为 onChunk 期望格式。
+ * 翻译规则:
+ *   assistant_text (非 _marker)      → response.output_text.delta
+ *   assistant_text with stop_reason  → response.completed  (message_stop 信号)
+ *   thinking                         → response.reasoning_summary_text.delta
+ *   tool_use                         → response.tool_use.start  + response.tool_use.completed (input already complete from claude stream-json)
+ *   tool_use_end                     → response.tool_result
+ *   error                            → response.failed
+ *   其他                             → null (忽略)
+ *
+ * **subagent**: claude stdoutParser 在 assistant_text / tool_use / tool_use_end
+ * 的 payload 上携带 parent_tool_use_id（非 null 表示子 agent 输出）；翻译时
+ * 透传该字段到 chunk，envelope_builder 把它放到 envelope.extensions。
+ *
+ * 返回单个 chunk 或一组 chunk 数组——为支持 tool_use 一次产 start+completed
+ * 两个事件，签名兼容数组返回。调用方需 for-of 而非直接 await。
+ */
+export function translateClaudeEventToChunk(ev) {
+  if (!ev) return null;
+  const parentRef = ev.payload?.parent_tool_use_id || null;
+  const withParent = (chunk) => parentRef ? { ...chunk, parent_tool_use_id: parentRef } : chunk;
+  switch (ev.kind) {
+    case "assistant_text": {
+      if (ev.payload?._marker === "turn_end" || ev.payload?.stop_reason) {
+        return { event: "response.completed" };
+      }
+      const text = ev.payload?.text || "";
+      if (!text) return null;
+      return withParent({ event: "response.output_text.delta", delta: text });
+    }
+    case "thinking": {
+      const text = String(ev.payload?.text || "");
+      if (!text) return null;
+      return withParent({ event: "response.reasoning_summary_text.delta", delta: text });
+    }
+    case "tool_use": {
+      // claude stream-json 一次性 emit 完整 tool_use block（含 input），所以
+      // 我们 emit start + completed 一对，input_complete=true。
+      const callId = String(ev.payload?.tool_id || ev.payload?.id || "");
+      const name = String(ev.payload?.name || "unknown");
+      const input = ev.payload?.input && typeof ev.payload.input === "object"
+        ? ev.payload.input : {};
+      return [
+        withParent({ event: "response.tool_use.start", call_id: callId, name, input }),
+        withParent({ event: "response.tool_use.completed", call_id: callId, name, input }),
+      ];
+    }
+    case "tool_use_end": {
+      // claude stream-json 的 tool_result 块挂在 user 消息上, stdoutParser
+      // 已经把 block.content 提取为 `result` 文本 (见 stdoutParser.mjs:70)。
+      const callId = String(ev.payload?.tool_id || "");
+      // stdoutParser uses `result` (string); fallback to `content` for forward-compat.
+      const resultText = typeof ev.payload?.result === "string"
+        ? ev.payload.result
+        : (typeof ev.payload?.content === "string" ? ev.payload.content : "");
+      const isError = !!ev.payload?.is_error;
+      const output = resultText
+        ? [{ type: "text", format: "plain", text: resultText }]
+        : [];
+      return withParent({
+        event: "response.tool_result",
+        call_id: callId,
+        output,
+        is_error: isError,
+      });
+    }
+    case "error":
+      return {
+        event: "response.failed",
+        error: { message: String(ev.payload?.err || ev.payload?.message || "claude error") },
+      };
+    default:
+      return null;
+  }
+}
+
+/**
+ * 构造 --resume 注入时的答案文本（传给 claude 的 user message）。
+ *
+ * 规格（spec design.md §2.3）：
+ *   - 单问：`[你提问了：{question}]\n我的选择是：{answer}`
+ *   - 多问：`[你提问了以下问题，以下是我的回答：]\n1. {Q1}：{A1}\n2. {Q2}：{A2}...`
+ *
+ * answer 格式化：
+ *   - free_text_response → 直接使用
+ *   - selected_ids / selected_option_ids → 反查 label，顿号拼接
+ *   - option_id → 反查 label（fallback 到 option_id 本身）
+ *
+ * @param {Array<{question: string, options?: Array<{label: string}>}>} questions
+ * @param {Array<object>} resumeValues  每个 block 的 resume value，与 questions 一一对应
+ * @param {Array<Record<string, string>>} optionMaps  每题的 option_id→label 映射
+ * @returns {string}
+ */
+export function buildAnswerInjectionText(questions, resumeValues, optionMaps) {
+  const formatAnswer = (value, map) => {
+    const v = value ?? {};
+    // free_text_response 优先
+    if (typeof v.free_text_response === "string" && v.free_text_response.trim()) {
+      return v.free_text_response.trim();
+    }
+    // 多选
+    if (Array.isArray(v.selected_ids) && v.selected_ids.length > 0) {
+      return v.selected_ids.map((id) => (map?.[id] ?? id)).join("、");
+    }
+    if (Array.isArray(v.selected_option_ids) && v.selected_option_ids.length > 0) {
+      return v.selected_option_ids.map((id) => (map?.[id] ?? id)).join("、");
+    }
+    // 单选
+    if (typeof v.option_id === "string" && v.option_id) {
+      return map?.[v.option_id] ?? v.option_id;
+    }
+    return "";
+  };
+
+  if (questions.length === 1) {
+    const q = questions[0].question ?? "";
+    const a = formatAnswer(resumeValues[0], optionMaps?.[0] ?? {});
+    return `[你提问了：${q}]\n我的选择是：${a}`;
+  }
+
+  // 多问场景
+  const lines = ["[你提问了以下问题，以下是我的回答：]"];
+  for (let i = 0; i < questions.length; i++) {
+    const q = questions[i].question ?? "";
+    const a = formatAnswer(resumeValues[i], optionMaps?.[i] ?? {});
+    lines.push(`${i + 1}. ${q}：${a}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * @param {{
+ *   cwd: string,
+ *   log: { info, warn, error, child? },
+ *   usage: { addCost },
+ *   dispatchHandlerOptions: {
+ *     relayUrl: string,
+ *     bridgeToken: string,
+ *     producerFactory?: Function,
+ *     openclawInvoke?: Function,
+ *     _spawnFactory?: Function,  // 仅测试用
+ *   },
+ * }} opts
+ * @returns {(request: any, ctx: any) => Promise<void>}
+ */
+export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatchHandlerOptions, scanner, _createWorkspace, _collectCustomCommands }) {
+  const {
+    relayUrl,
+    bridgeToken,
+    producerFactory,
+    openclawInvoke: injectedOpenclawInvoke,
+    _spawnFactory,
+    // approval 模式注入点（测试用）
+    approvalGateway: injectedApprovalGateway,
+    permissionMode: injectedPermissionMode,
+    _permissionPromptServerFactory,
+    _writeMcpConfig,
+    _deleteMcpConfig,
+    // waitForRunResumed 注入点（测试用；生产走顶层 import）
+    _waitForRunResumed: injectedWaitForRunResumed,
+  } = dispatchHandlerOptions ?? {};
+
+  // waitForRunResumed 可注入（测试用），生产走 module-level import
+  const mkWaitForRunResumed = injectedWaitForRunResumed ?? waitForRunResumed;
+
+  // approval 功能依赖注入（允许测试注入，生产走默认）
+  const mkPermissionPromptServer = _permissionPromptServerFactory ?? _defaultPermissionPromptServerFactory;
+  const doWriteMcpConfig = _writeMcpConfig ?? _defaultWriteMcpConfig;
+  const doDeleteMcpConfig = _deleteMcpConfig ?? _defaultDeleteMcpConfig;
+  // bridge 状态(claude CLI 版本 / gw_id / model), 供 slash 路由器在 bridge-synth
+  // 分支(/help /status /model 等 CLI 不支持的)合成响应文本时引用。
+  const claudeCliVersion = bridgeCtx?.version || null;
+  const claudeGwId = bridgeCtx?.gwId || null;
+  const claudeModel = bridgeCtx?.model || null;
+
+  // spawn 工厂（可被测试注入）
+  const mkSpawn = _spawnFactory ?? ((opts) => spawnClaude(opts));
+
+  // thread_id → 上次 claude 给的 session_id 缓存。每条 dispatch 用 thread_id
+  // 查 map，命中就 `claude --resume <sid>` 续上下文，没命中就开新 session
+  // 并在 session_ready 事件里捕获 session_id 回写。
+  // 进程级 in-memory 即可——bridge 重启会丢，但前端再发一条会自然 reseed；
+  // 持久化方案待后续与 nacos / 本地 ~/.agentlink/sessions.json 整合。
+  // audit 修复：thread 数随用户/会话增长，进程级 Map 改 LRU+TTL
+  //（7 天未访问的 thread 续接缓存丢弃——丢了也只是开新 session，可接受）。
+  const threadSessionMap = new BoundedMap({ maxSize: 5_000, ttlMs: 7 * 24 * 60 * 60 * 1000 });
+  // thread_id → 选中历史会话的项目 cwd。claude session 按项目目录隔离，
+  // /resume 选中的会话属于其原始项目；下次 spawn 必须在该 cwd 下才能 --resume 成功。
+  const threadSessionCwdMap = new BoundedMap({ maxSize: 5_000, ttlMs: 7 * 24 * 60 * 60 * 1000 });
+
+  // interrupt 闸门 — 跨请求共享，用于 /resume picker 挂起/恢复。
+  const interruptGateway = createInterruptGateway({ log });
+
+  // 活跃 run 登记表 — App 停止按钮 (sessions.abort RPC) 据此 kill 子进程。
+  const activeRuns = createActiveRunRegistry({ log });
+
+  // 默认 openclawInvoke：spawn claude --print 子进程，解析 stdout，翻译事件
+  // Task 3.5: 加入 blocks 参数（来自 dispatch payload），透传给 writeUserMessage 以支持多模态
+  // workspace-aware cwd: 若 workspace_path 非空且目录存在，spawn 用它作 cwd；
+  // 否则 fallback 到 defaultWorkspace（不再用工厂 cwd，修 service 模式 "/" bug）。
+  const defaultOpenclawInvoke = async ({ thread_id, run_id, input, blocks = [], workspace_path: reqWorkspacePath, session_key = null, onChunk: _rawOnChunk }) => {
+    // per-request cwd 解析（align-runtime-default-workspace）:
+    //   1. workspace_path 非空 → expandHome + existsSync → 用它
+    //   2. workspace_path 给定但不存在 → fallback 到 defaultWorkspace，emit cwd_fallback 可观测
+    //   3. workspace_path 未给 → 直接用 defaultWorkspace
+    //   注：factory cwd 不再作为兜底（保留作显式 --cwd 入口）
+    let spawnCwd;
+    let cwdFallback = null;
+
+    const { existsSync } = await import("node:fs");
+
+    if (reqWorkspacePath && typeof reqWorkspacePath === "string" && reqWorkspacePath.trim()) {
+      const resolved = expandHome(reqWorkspacePath.trim());
+      if (existsSync(resolved)) {
+        spawnCwd = resolved;
+        log.info?.("claude.spawn.cwd.workspace", "using workspace_path as cwd", {
+          cwd: resolved, source: "workspace_path",
+        });
+      } else {
+        // workspace_path 给定但不存在 → fallback 到默认工作区，fallback 可观测
+        spawnCwd = await ensureDefaultWorkspace("claude");
+        cwdFallback = {
+          actual_cwd: spawnCwd,
+          requested_cwd: reqWorkspacePath,
+          reason: `workspace_path '${reqWorkspacePath}' does not exist after expand, falling back to default workspace`,
+        };
+        log.warn?.("claude.spawn.cwd.not_found", "workspace_path does not exist, falling back to default workspace", {
+          workspace_path: reqWorkspacePath, fallback_cwd: spawnCwd,
+        });
+      }
+    } else {
+      // 未给 workspace_path → 用默认工作区（lazy ensure，兜底 service 模式 "/" bug）
+      spawnCwd = await ensureDefaultWorkspace("claude");
+      log.info?.("claude.spawn.cwd.default", "no workspace_path, using default workspace", {
+        cwd: spawnCwd, source: "default_workspace",
+      });
+    }
+    // /resume picker 选中的历史会话属于其原始项目目录；claude session 按 cwd 隔离，
+    // 必须在该会话的项目 cwd 下才能 `--resume <id>` 命中。覆盖 spawnCwd。
+    if (thread_id && threadSessionCwdMap.has(thread_id)) {
+      const sessCwd = threadSessionCwdMap.get(thread_id);
+      if (sessCwd && typeof sessCwd === "string") {
+        if (existsSync(sessCwd)) {
+          spawnCwd = sessCwd;
+          log.info?.("claude.spawn.cwd.resume_session",
+            "using picked session project cwd for --resume", { cwd: sessCwd });
+        }
+      }
+    }
+    // 自动 attach 扫描器: 拦 response.output_text.delta 喂 accumulator, fire-and-forget
+    // 不阻塞流式输出。scanner 由工厂注入(bootstrapAgentlinkTools.scanner)。
+    const _acc = scanner?.createTurnAccumulator({ requestId: run_id });
+    const onChunk = _acc
+      ? async (event) => {
+          if (event && event.event === "response.output_text.delta" && typeof event.delta === "string") {
+            try { _acc.append(event.delta); } catch { /* swallow */ }
+          }
+          return _rawOnChunk(event);
+        }
+      : _rawOnChunk;
+
+    // fallback 可观测：workspace_path 给定但不存在时，emit run.started 含 cwd_fallback
+    if (cwdFallback) {
+      await onChunk({
+        event: "__envelopes",
+        envelopes: [buildRunStarted(run_id, { options: { cwd_fallback: cwdFallback } })],
+      });
+    }
+
+    // approval 模式资源（在 try 块外声明，以便 finally 块访问）
+    let _approvalPermServer = null;
+    let _approvalMcpConfigPath = null;
+
+    try {
+    // ── Slash command 拦截（bridge 层）─────────────────────────────────────
+    // 设计原则（2026-05-20 重写）:
+    //   claude CLI 在 `--print --input-format stream-json` 模式下对 slash 命令
+    //   有两类反应:
+    //     A) CLI 真支持(/cost /usage /context /init /review 等): 发 synthetic
+    //        assistant 消息(model="<synthetic>"), 内容是真实结果。stdoutParser
+    //        的 isSyntheticSlashResponse 分支会把文本 emit 给 bridge。
+    //     B) CLI 不支持(/help /status /model /agents /skills /memory 等):
+    //        同样发 synthetic 消息但内容是 "<cmd> isn't available in this
+    //        environment.", 给用户看一句"不支持"对远程会话体验不友好。
+    //
+    //   所以 bridge 端策略:
+    //     - /clear → client-reset(必须清 thread→session map)
+    //     - /compact → passthrough(CLI 真跑 compaction)
+    //     - B 类(CLI 拒绝响应的)→ bridge-synth, 用已有 bridge 状态合成等价输出
+    //     - 其它(/cost /usage /context ...) → not-slash, 让 CLI 自己说话
+    const slash = await classifySlashCommand(input, "claude", {
+      version: claudeCliVersion,
+      // 必须用本次请求解析出的 spawnCwd（工作区目录），不能用 factory cwd：
+      // init 探活的 slash_commands 清单含工作区级自定义命令(.claude/commands/)，
+      // 用错目录会把非默认工作区的自定义命令全部误判「不支持」(P0#25)。
+      cwd: spawnCwd,
+      gwId: claudeGwId,
+      threadId: thread_id || null,
+      sessionId: thread_id ? threadSessionMap.get(thread_id) || null : null,
+      model: claudeModel,
+    });
+    if (slash.kind === "client-reset") {
+      if (thread_id) {
+        threadSessionMap.delete(thread_id);
+        threadSessionCwdMap.delete(thread_id);
+        log.info?.("claude.slash.clear",
+          "client-reset slash command, dropped thread→session mapping",
+          { thread_id, command: slash.command });
+      }
+      await emitAssistantText(onChunk, slash.ackText);
+      return;
+    }
+    if (slash.kind === "bridge-synth") {
+      log.info?.("claude.slash.synth",
+        "bridge-synthesized slash response (CLI rejects in --print mode)",
+        { thread_id, command: slash.command });
+      await emitAssistantText(onChunk, slash.responseText);
+      return;
+    }
+
+    // ── /resume interrupt session picker ────────────────────────────────────
+    if (slash.kind === "interrupt-session-pick") {
+      log.info?.("claude.slash.resume_picker", "/resume: starting interrupt session picker", { thread_id, run_id });
+
+      // 默认只列「当前工作区」(spawnCwd) 下的历史会话；跨项目会话不再混入。
+      const sessions = await listSessionsForRuntime("claude", { filterCwd: spawnCwd });
+
+      if (sessions.length === 0) {
+        // 本工作区无可恢复会话 → 文本提示 + run.completed（无 run.paused）
+        log.info?.("claude.slash.resume_picker.empty", "/resume: no sessions in current workspace, sending text fallback", { thread_id, cwd: spawnCwd });
+        await emitAssistantText(onChunk, "本工作区暂无历史会话，直接开始新对话吧");
+        return;
+      }
+
+      // 构造 interrupt block options
+      const blockId = newBlockId();
+      const options = sessions.map((s) => ({
+        id: s.session_id,
+        label: buildSessionLabel(s),
+        description: buildSessionSubtitle(s),
+      }));
+
+      // 发 run.started → content_block.started(interrupt) → run.paused
+      await onChunk({
+        event: "__envelopes",
+        envelopes: [
+          buildRunStarted(run_id),
+          buildBlockStarted(run_id, {
+            id: blockId,
+            type: "interrupt",
+            subtype: "question",
+            prompt: "选择要续接的历史会话",
+            options,
+            selection_mode: "single",
+          }),
+          buildRunPaused(run_id, [blockId]),
+        ],
+      });
+
+      // 非阻塞：发完 interrupt + run.paused 后**立即返回**释放 long-poll worker，
+      // 否则单 worker 会卡在 await 上，导致其它会话的 /resume 全部排队 hang。
+      // resume 由 relay stream 监听器异步处理：收到 run.resumed → 发收尾 + 记 session。
+      if (relayUrl && bridgeToken && thread_id) {
+        waitForRunResumed({
+          relayUrl,
+          bridgeToken,
+          threadId: thread_id,
+          runId: run_id,
+          interruptId: blockId,
+          log,
+        }).then(async ({ value }) => {
+          const decisionValue = value;
+          // 发 content_block.completed + run.completed（收尾，独立 POST /events）
+          await onChunk({
+            event: "__envelopes",
+            envelopes: [
+              buildBlockCompleted(run_id, {
+                id: blockId,
+                type: "interrupt",
+                // schema 要求 interrupt 块带 type/subtype/prompt（completed 也校验），
+                // 否则 oneOf 退化到 text 分支报 missing format/text。
+                subtype: "question",
+                prompt: "选择要续接的历史会话",
+                status: "completed",
+                value: decisionValue,
+              }),
+              // stop_reason 必须是协议枚举值；控制型 run 正常结束用 end_turn。
+              buildRunCompleted(run_id, "end_turn"),
+            ],
+          });
+          // 写入 threadSessionMap（下次消息走 --resume <session_id>）+ 记下该会话项目 cwd
+          const selectedSessionId = decisionValue?.option_id ?? null;
+          if (selectedSessionId) {
+            threadSessionMap.set(thread_id, selectedSessionId);
+            const picked = sessions.find((s) => s.session_id === selectedSessionId);
+            if (picked?.cwd) {
+              threadSessionCwdMap.set(thread_id, picked.cwd);
+            }
+            log.info?.("claude.slash.resume_picker.done", "session selected for next run", {
+              thread_id, session_id: selectedSessionId, session_cwd: picked?.cwd || null,
+            });
+          }
+        }).catch((err) => {
+          log.warn?.("claude.slash.resume_picker.listener_err", "run.resumed listener error", {
+            run_id, err: err?.message || String(err),
+          });
+        });
+      } else {
+        log.warn?.("claude.slash.resume_picker.no_listener",
+          "missing relay/token/thread; cannot await resume", { run_id });
+      }
+      return;
+    }
+
+    // not-slash / passthrough(/compact): 继续走 spawn, claude CLI 自己应答
+    const isPassthroughSlash = slash.kind === "passthrough" || slash.kind === "prompt-rewrite";
+    // prompt-rewrite(P1#22): /diff /recap 等 TUI 命令改写成等效自然语言真跑
+    const effectiveInput = slash.kind === "prompt-rewrite" ? slash.rewrittenInput : input;
+    if (slash.kind === "prompt-rewrite") {
+      log.info?.("claude.slash.rewrite", "slash rewritten to natural-language prompt",
+        { thread_id, command: slash.command });
+    }
+
+    // ── approval 模式 ─────────────────────────────────────────────────────────
+    // 读取权限模式：injectedPermissionMode（测试注入）> env var > bypass 默认
+    const effectivePermissionMode = injectedPermissionMode
+      || process.env.AGENTLINK_CLAUDE_PERMISSION_MODE
+      || "bypassPermissions";
+    const isApprovalMode = effectivePermissionMode === "approval" || effectivePermissionMode === "default";
+
+    if (isApprovalMode && injectedApprovalGateway) {
+      // 写 MCP config 文件
+      try {
+        _approvalMcpConfigPath = await doWriteMcpConfig({
+          runId: run_id,
+          serverScriptPath: PERMISSION_PROMPT_WORKER_SCRIPT,
+        });
+        log.info?.("claude.approval.mcp_config_written", "MCP config written", {
+          run_id, path: _approvalMcpConfigPath,
+        });
+      } catch (err) {
+        log.warn?.("claude.approval.mcp_config_failed", "failed to write MCP config, falling back to bypass", {
+          err: err?.message || String(err),
+        });
+        _approvalMcpConfigPath = null;
+      }
+
+      if (_approvalMcpConfigPath) {
+        try {
+          _approvalPermServer = mkPermissionPromptServer({ approvalGateway: injectedApprovalGateway, log });
+          await _approvalPermServer.start();
+          log.info?.("claude.approval.perm_server_started", "permission prompt server started", { run_id });
+
+          // pull 模式：监听 approvalGateway 上的 openRequest，发 interrupt block + run.paused
+          // 通过轮询 getLastRequestId 并监听 promise 来实现 pull
+          // 注：实际上 approvalGateway.openRequest 是同步注册的；permServer 的 IPC 消息
+          // 会触发 approvalGateway.openRequest，然后由 permServer 内部管理 promise。
+          // handleRequest 通过 onRequest 监听器（间隔轮询 lastRequestId）来发 interrupt block。
+
+          // 启动 approval 监听器（fire-and-forget，直到 run 结束）
+          const approvalListener = (async () => {
+            let lastSeenId = null;
+            // 轮询直到 permServer 被 stop（child=null）或 run 结束
+            while (_approvalPermServer) {
+              const currentId = _approvalPermServer.getLastRequestId();
+              if (currentId && currentId !== lastSeenId) {
+                lastSeenId = currentId;
+                // 找到新的 openRequest，发 interrupt block
+                try {
+                  // 从 approvalGateway 内部取 meta（tool_name, tool_input）
+                  // approvalGateway 没有直接暴露 meta，但 permServer 的 worker 已经把
+                  // meta 传给 approvalGateway.openRequest；我们通过 approvalGateway.openRequest
+                  // 调用时传入的 meta 来构造 block。
+                  // 为了取到 meta，我们在 permServer IPC 收到 openRequest 时也通知 handleRequest。
+                  // 简单方案：permServer 额外暴露 getLastMeta()。
+                  const meta = _approvalPermServer.getLastMeta ? _approvalPermServer.getLastMeta() : {};
+                  const blockId = newBlockId();
+                  const block = buildPermissionInterruptBlock({
+                    toolName: meta.tool_name || "unknown",
+                    toolInput: meta.tool_input || {},
+                    blockId,
+                    runId: run_id,
+                  });
+
+                  // 发 content_block.started + run.paused
+                  await onChunk({
+                    event: "__envelopes",
+                    envelopes: [
+                      buildBlockStarted(run_id, block),
+                      buildRunPaused(run_id, [blockId]),
+                    ],
+                  });
+
+                  log.info?.("claude.approval.interrupt_sent", "approval interrupt block sent", {
+                    run_id, block_id: blockId, tool: meta.tool_name || "",
+                  });
+
+                  // waitForRunResumed：等待用户决策
+                  if (relayUrl && bridgeToken && thread_id) {
+                    waitForRunResumed({
+                      relayUrl,
+                      bridgeToken,
+                      threadId: thread_id,
+                      runId: run_id,
+                      interruptId: blockId,
+                      log,
+                    }).then(({ value }) => {
+                      const behavior = value?.behavior || "deny";
+                      const decision = behavior === "allow" ? "approve" : "reject";
+                      injectedApprovalGateway.settle(currentId, decision, `user-${behavior}`);
+                      log.info?.("claude.approval.settled", "approval settled from run.resumed", {
+                        run_id, request_id: currentId, decision,
+                      });
+                    }).catch((err) => {
+                      log.warn?.("claude.approval.listener_err", "waitForRunResumed error, auto-reject", {
+                        run_id, err: err?.message || String(err),
+                      });
+                      injectedApprovalGateway.settle(currentId, "reject", "listener-error");
+                    });
+                  }
+                } catch (err) {
+                  log.warn?.("claude.approval.block_err", "failed to send approval interrupt block", {
+                    err: err?.message || String(err),
+                  });
+                }
+              }
+              await new Promise((r) => setTimeout(r, 30));
+            }
+          })();
+          // 不 await，fire-and-forget
+        } catch (err) {
+          log.warn?.("claude.approval.perm_server_failed", "permission prompt server failed to start, falling back", {
+            err: err?.message || String(err),
+          });
+          _approvalPermServer = null;
+          await doDeleteMcpConfig(_approvalMcpConfigPath).catch(() => {});
+          _approvalMcpConfigPath = null;
+        }
+      }
+    }
+
+    // 包成 attemptOnce，便于 --resume 失败时清缓存后重试一次无 resume 路径
+    async function attemptOnce({ resumeSessionId, isRetry }) {
+      let handle;
+      try {
+        const cwdSource = spawnCwd !== cwd ? "workspace_path" : "default";
+        // approval 模式：注入 extraArgs
+        const approvalExtraArgs = (isApprovalMode && _approvalMcpConfigPath) ? [
+          "--permission-mode", "default",
+          "--permission-prompt-tool", "mcp__agentlink-permission__agentlink_permission_prompt",
+          "--setting-sources", "project",
+          "--mcp-config", _approvalMcpConfigPath,
+        ] : [];
+        handle = mkSpawn({ cwd: spawnCwd, log, resumeSessionId: resumeSessionId || undefined, cwdSource, extraArgs: approvalExtraArgs });
+      } catch (err) {
+        const msg = err?.message || String(err);
+        log.error?.("child.spawn.failed", "spawn claude failed", { err: msg, isRetry: !!isRetry });
+        return { spawnError: msg };
+      }
+      // P0 停止按钮：登记活跃 run，App 的 sessions.abort RPC 据此 kill 子进程
+      let abortedByRpc = false;
+      const unregister = activeRuns.register({
+        sessionKey: session_key,
+        threadId: thread_id,
+        runId: run_id,
+        kill: (reason) => {
+          abortedByRpc = true;
+          try { handle.kill(reason); } catch { /* already dead */ }
+        },
+      });
+      if (resumeSessionId) {
+        log.info?.("claude.session.resume", "resuming claude session for thread", {
+          thread_id, session_id: resumeSessionId,
+        });
+      }
+
+      // 写 user 消息进 stdin（含 multimodal blocks）
+      try {
+        await writeUserMessage(handle.child, effectiveInput, blocks);
+      } catch (err) {
+        const msg = err?.message || String(err);
+        log.error?.("child.stdin.failed", "write user message failed", { err: msg });
+        try { handle.kill("stdin-failed"); } catch {}
+        unregister();
+        return { stdinError: msg };
+      }
+      // 关 stdin 发 EOF —— claude --print --input-format stream-json 在没收到
+      // EOF 时会等下一条 user 消息，导致响应憋着不退、App 端永远 loading。
+      try { handle.child.stdin.end(); } catch {}
+
+      // 跟踪本轮:assistant 是否产出过 chunk + 抓到的 session_id（还没决定要不要
+      // 落 threadSessionMap，因为 slash 命令 / 失败情况下 claude 没写 jsonl 文件，
+      // 落了下一轮 --resume 必败）。
+      let sawAssistantOutput = false;
+      let sawNonSyntheticOutput = false; // 区分 synthetic slash 响应 vs 真 LLM turn
+      let pendingSessionId = null;
+
+      const todoTranslator = createClaudeTodoTranslator(run_id);
+      const askTranslator = createAskUserQuestionTranslator({ log, runId: run_id });
+      // 未决 AskUserQuestion 批次登记。真 CLI headless 下 AskUserQuestion 由
+      // CLI 自答 is_error tool_result 自取消、turn 直接结束（实测 2.1.173，
+      // 即使 stdin 保持打开也不等外部回填）——child 退出时必须 reconcile，
+      // 否则 run 永远停在 paused：relay 行卡 running、App 转圈不复位。
+      const pendingAskBatches = [];
+      let sawResponseCompleted = false;
+      let childExited = false;
+      let askTerminalEmitted = false;
+      // run 因 ask 暂停后的终态兜底：dispatcher 在 paused 时跳过合成收尾，
+      // 这里补一条 response.completed 让它闭合文本块 + 发 run.completed。
+      // sawResponseCompleted / askTerminalEmitted 双闸防止双终态。
+      const ensureAskTerminal = async () => {
+        if (askTerminalEmitted || sawResponseCompleted) return;
+        askTerminalEmitted = true;
+        try { await onChunk({ event: "response.completed" }); } catch { /* ignore */ }
+      };
+      const parser = createLineStreamParser({
+        onObject: async (obj) => {
+          const events = normalizeClaudeLine(obj);
+          for (const ev of events) {
+            if (ev.kind === "session_ready" && thread_id) {
+              const sid = ev.payload?.session_id;
+              if (typeof sid === "string" && sid) {
+                // 不直接写 map；等 exit code=0 且 sawNonSyntheticOutput=true 才确认
+                pendingSessionId = sid;
+              }
+              continue;
+            }
+            // 标记真有 assistant 内容（include text/thinking/tool_use；不算
+            // response.completed 这种生命周期事件）
+            if (ev.kind === "assistant_text" && !ev.payload?._marker && (ev.payload?.text || "").length > 0) {
+              sawAssistantOutput = true;
+              // synthetic slash 响应不算"真 LLM turn"——claude 没写 jsonl,
+              // session_id 不能续 resume。
+              if (!ev.payload?.synthetic) {
+                sawNonSyntheticOutput = true;
+              }
+            } else if (ev.kind === "thinking" || ev.kind === "tool_use" || ev.kind === "tool_use_end") {
+              sawAssistantOutput = true;
+              sawNonSyntheticOutput = true;
+            }
+
+            // ── AskUserQuestion 拦截（todoTranslator 之后） ─────────────────
+            const askResult = askTranslator.intercept(ev);
+            if (askResult !== null) {
+              if (askResult.consumed) {
+                // tool_use_end 被吞噬，跳过
+                continue;
+              }
+              // AskUserQuestion 被拦截：发 N 个 block.started + run.paused，异步等待
+              const { toolId, questions, batchGroupId, blocks } = askResult;
+              const batchBlockIds = blocks.map((b) => b.id);
+              const optionMaps = buildOptionMaps(blocks);
+              const askBatch = {
+                toolId,
+                blocks,
+                finalized: false,
+                abortCtrl: new AbortController(),
+              };
+              pendingAskBatches.push(askBatch);
+
+              // 发 N 个 buildBlockStarted(interrupt, awaiting) + 1 个 buildRunPaused
+              const envelopes = [
+                ...blocks.map((b) => buildBlockStarted(run_id, b)),
+                buildRunPaused(run_id, batchBlockIds),
+              ];
+              try {
+                await onChunk({ event: "__envelopes", envelopes });
+              } catch { /* ignore */ }
+
+              // 非阻塞等待：发完 run.paused 后立即继续，等待在 .then() 里
+              if (relayUrl && bridgeToken && thread_id) {
+                // Promise.all：集齐全部 block 的 resume 后聚合
+                const waitPromises = batchBlockIds.map((blockId, idx) =>
+                  mkWaitForRunResumed({
+                    relayUrl,
+                    bridgeToken,
+                    threadId: thread_id,
+                    runId: run_id,
+                    interruptId: blockId,
+                    signal: askBatch.abortCtrl.signal,
+                    log,
+                  }).then(({ value }) => ({ blockId, idx, value, ok: true }))
+                    .catch((err) => ({ blockId, idx, value: null, ok: false, err })),
+                );
+
+                Promise.all(waitPromises).then(async (results) => {
+                  // child-exit reconcile 已收尾 → 本批次作废，避免双终态
+                  if (askBatch.finalized) return;
+                  askBatch.finalized = true;
+                  // 检查是否有取消（reject/cancel_run 或超时）
+                  const hasCanceled = results.some((r) => {
+                    if (!r.ok) return true; // 超时或监听失败
+                    const v = r.value ?? {};
+                    return v.decision === "reject" || v.decision === "cancel_run";
+                  });
+
+                  if (hasCanceled) {
+                    // 取消语义：全部 block 发 canceled，不写 stdin（claude 进程已退出）
+                    const canceledEnvelopes = blocks.map((b) =>
+                      buildBlockCompleted(run_id, {
+                        id: b.id,
+                        type: "interrupt",
+                        subtype: b.subtype,
+                        prompt: b.prompt,
+                        status: "canceled",
+                      }),
+                    );
+                    try { await onChunk({ event: "__envelopes", envelopes: canceledEnvelopes }); } catch {}
+                    // child 已死（headless AskUserQuestion 场景），原 run 终态由
+                    // reconcileAskOnExit 或本路径的 ensureAskTerminal 保证。
+                    if (childExited) await ensureAskTerminal();
+                    return;
+                  }
+
+                  // 全部答案收集完毕 ── --resume 注入路径
+                  const resumeValues = results.map((r) => r.value ?? {});
+                  const retainedSid = askBatch.retainedSessionId ?? null;
+
+                  if (!retainedSid) {
+                    // 降级路径：session_id 不可用，无法续接
+                    log?.warn?.("claude.ask_user_question.no_session_id_for_resume",
+                      "decision arrived but retainedSessionId is null; falling back to cancel",
+                      { run_id });
+                    const canceledEnvelopes = blocks.map((b) =>
+                      buildBlockCompleted(run_id, {
+                        id: b.id,
+                        type: "interrupt",
+                        subtype: b.subtype,
+                        prompt: b.prompt,
+                        status: "canceled",
+                      }),
+                    );
+                    try { await onChunk({ event: "__envelopes", envelopes: canceledEnvelopes }); } catch {}
+                    // 补一条友好提示（新 run 信封）——本地 translate 保证 run_id 正确
+                    const fallbackRunId = newRunId();
+                    try {
+                      await onChunk({
+                        event: "__envelopes",
+                        envelopes: [buildRunStarted(fallbackRunId)],
+                      });
+                    } catch {}
+                    {
+                      let fbState = newBlockState();
+                      const fbDelta = translateOpenClawChunkToEnvelope(
+                        { event: "response.output_text.delta", delta: "暂无可续接的会话，请重新提问。" },
+                        fallbackRunId, fbState,
+                      );
+                      fbState = fbDelta.blockState;
+                      if (fbDelta.envelopes.length > 0) {
+                        try { await onChunk({ event: "__envelopes", envelopes: fbDelta.envelopes }); } catch {}
+                      }
+                      const fbCompleted = translateOpenClawChunkToEnvelope(
+                        { event: "response.completed" },
+                        fallbackRunId, fbState,
+                      );
+                      if (fbCompleted.envelopes.length > 0) {
+                        try { await onChunk({ event: "__envelopes", envelopes: fbCompleted.envelopes }); } catch {}
+                      }
+                    }
+                    return;
+                  }
+
+                  // § spec 2.4 时序：
+                  // 1. 发原 batch 所有 block 的 blockCompleted(status=completed)
+                  // 2. 生成新 run_id_resume
+                  // 3. 构造 answerText
+                  // 4. 起新 child（--resume <session_id>，answerText 经 stdin 写 user message）
+                  // 5. 流式透传，新 session_id → threadSessionMap
+                  // 6. run.completed(R2)
+
+                  // Step 1: block completed（原 run R1 信封下）
+                  const completedEnvelopes = results.map((r) =>
+                    buildBlockCompleted(run_id, {
+                      id: r.blockId,
+                      type: "interrupt",
+                      subtype: blocks[r.idx].subtype,
+                      prompt: blocks[r.idx].prompt,
+                      status: "completed",
+                      value: r.value,
+                    }),
+                  );
+                  try { await onChunk({ event: "__envelopes", envelopes: completedEnvelopes }); } catch {}
+
+                  // Step 2 & 3
+                  const runIdResume = newRunId();
+                  const answerText = buildAnswerInjectionText(questions, resumeValues, optionMaps);
+
+                  log?.info?.("claude.ask_user_question.resume_inject",
+                    "starting --resume child for AskUserQuestion answer injection",
+                    { run_id, run_id_resume: runIdResume, session_id: retainedSid });
+
+                  // Step 4: 起新 child（独立 run 信封）。dispatcher 的 translate 只认
+                  // 原 R1 run_id，所以 R2 的全部信封都在本地铸（translate + 本地
+                  // blockState），经 __envelopes 直通下发，run_id 天然是 runIdResume。
+
+                  // emit run.started(R2)
+                  try {
+                    await onChunk({
+                      event: "__envelopes",
+                      envelopes: [buildRunStarted(runIdResume)],
+                    });
+                  } catch {}
+
+                  // Step 5: spawn --resume child
+                  let resumeHandle;
+                  try {
+                    resumeHandle = mkSpawn({
+                      cwd: spawnCwd,
+                      log,
+                      resumeSessionId: retainedSid,
+                      cwdSource: "ask_resume",
+                    });
+                  } catch (spawnErr) {
+                    log?.warn?.("claude.ask_user_question.resume_spawn_failed",
+                      "failed to spawn --resume child",
+                      { run_id_resume: runIdResume, err: spawnErr?.message });
+                    {
+                      let spawnFbState = newBlockState();
+                      const spawnFbDelta = translateOpenClawChunkToEnvelope(
+                        { event: "response.output_text.delta", delta: "续接会话失败，请重新提问。" },
+                        runIdResume, spawnFbState,
+                      );
+                      spawnFbState = spawnFbDelta.blockState;
+                      if (spawnFbDelta.envelopes.length > 0) {
+                        try { await onChunk({ event: "__envelopes", envelopes: spawnFbDelta.envelopes }); } catch {}
+                      }
+                      const spawnFbCompleted = translateOpenClawChunkToEnvelope(
+                        { event: "response.completed" },
+                        runIdResume, spawnFbState,
+                      );
+                      if (spawnFbCompleted.envelopes.length > 0) {
+                        try { await onChunk({ event: "__envelopes", envelopes: spawnFbCompleted.envelopes }); } catch {}
+                      }
+                    }
+                    return;
+                  }
+
+                  // 写 user message（答案注入文本）
+                  try {
+                    await writeUserMessage(resumeHandle.child, answerText, []);
+                  } catch (stdinErr) {
+                    log?.warn?.("claude.ask_user_question.resume_stdin_failed",
+                      "failed to write answer to --resume child stdin",
+                      { err: stdinErr?.message });
+                    try { resumeHandle.kill("stdin-failed"); } catch {}
+                    {
+                      let stdinFbState = newBlockState();
+                      const stdinFbDelta = translateOpenClawChunkToEnvelope(
+                        { event: "response.output_text.delta", delta: "续接会话失败，请重新提问。" },
+                        runIdResume, stdinFbState,
+                      );
+                      stdinFbState = stdinFbDelta.blockState;
+                      if (stdinFbDelta.envelopes.length > 0) {
+                        try { await onChunk({ event: "__envelopes", envelopes: stdinFbDelta.envelopes }); } catch {}
+                      }
+                      const stdinFbCompleted = translateOpenClawChunkToEnvelope(
+                        { event: "response.completed" },
+                        runIdResume, stdinFbState,
+                      );
+                      if (stdinFbCompleted.envelopes.length > 0) {
+                        try { await onChunk({ event: "__envelopes", envelopes: stdinFbCompleted.envelopes }); } catch {}
+                      }
+                    }
+                    return;
+                  }
+                  try { resumeHandle.child.stdin.end(); } catch {}
+
+                  // 流式透传 R2 输出
+                  // 本地持有 blockState，对每个 chunk 调用 translateOpenClawChunkToEnvelope，
+                  // 产出的 envelopes 以 __envelopes 直通发出，run_id 天然等于 runIdResume。
+                  let resumePendingSessionId = null;
+                  let resumeSawNonSynthetic = false;
+                  let resumeBlockState = newBlockState();
+                  let resumeSawResponseCompleted = false;
+                  const resumeParser = createLineStreamParser({
+                    onObject: async (obj) => {
+                      const events = normalizeClaudeLine(obj);
+                      for (const ev of events) {
+                        if (ev.kind === "session_ready") {
+                          const sid = ev.payload?.session_id;
+                          if (typeof sid === "string" && sid) {
+                            resumePendingSessionId = sid;
+                          }
+                          continue;
+                        }
+                        if (ev.kind === "assistant_text" && !ev.payload?._marker && (ev.payload?.text || "").length > 0) {
+                          if (!ev.payload?.synthetic) resumeSawNonSynthetic = true;
+                        } else if (ev.kind === "thinking" || ev.kind === "tool_use" || ev.kind === "tool_use_end") {
+                          resumeSawNonSynthetic = true;
+                        }
+                        const chunk = translateClaudeEventToChunk(ev);
+                        if (!chunk) continue;
+                        const chunks = Array.isArray(chunk) ? chunk : [chunk];
+                        for (const c of chunks) {
+                          const cEvent = c.event || c.type;
+                          if (cEvent === "response.completed" || cEvent === "response.failed" || cEvent === "end") {
+                            resumeSawResponseCompleted = true;
+                          }
+                          const result = translateOpenClawChunkToEnvelope(c, runIdResume, resumeBlockState);
+                          resumeBlockState = result.blockState;
+                          if (result.envelopes.length > 0) {
+                            try { await onChunk({ event: "__envelopes", envelopes: result.envelopes }); } catch {}
+                          }
+                        }
+                      }
+                    },
+                    onInvalid: () => {},
+                    log,
+                  });
+                  resumeHandle.child.stdout.on("data", (buf) => resumeParser.push(buf));
+
+                  const resumeCode = await new Promise((resolve) => {
+                    resumeHandle.child.once("exit", (c) => {
+                      resumeParser.flush();
+                      resolve(c == null ? -1 : c);
+                    });
+                    resumeHandle.child.once("error", () => resolve(-1));
+                  });
+
+                  // 新 session_id 写入 threadSessionMap
+                  if (resumeCode === 0 && resumeSawNonSynthetic && resumePendingSessionId && thread_id) {
+                    threadSessionMap.set(thread_id, resumePendingSessionId);
+                    log?.info?.("claude.ask_user_question.resume_session_updated",
+                      "threadSessionMap updated after --resume child",
+                      { thread_id, new_session_id: resumePendingSessionId });
+                  }
+
+                  // 若 child 未自发 response.completed，本地合成一次以关闭未闭合块并产出 run.completed(R2)。
+                  // 若已发过（resumeSawResponseCompleted=true），translate 已产出 run.completed，不重复发。
+                  if (!resumeSawResponseCompleted) {
+                    const syntheticResult = translateOpenClawChunkToEnvelope(
+                      { event: "response.completed" },
+                      runIdResume, resumeBlockState,
+                    );
+                    if (syntheticResult.envelopes.length > 0) {
+                      try { await onChunk({ event: "__envelopes", envelopes: syntheticResult.envelopes }); } catch {}
+                    }
+                  }
+                }).catch((err) => {
+                  log?.warn?.("claude.ask_user_question.batch_wait_error",
+                    "batch wait Promise.all error", { err: err?.message || String(err) });
+                });
+              } else {
+                log?.warn?.("claude.ask_user_question.no_listener",
+                  "missing relay/token/thread; cannot await AskUserQuestion resume", { run_id });
+              }
+              continue; // ev 已被消费，不走 todoTranslator
+            }
+
+            const intercepted = todoTranslator.intercept(ev);
+            if (intercepted.length === 0) continue;
+            if (intercepted !== null && intercepted[0] !== ev) {
+              try { await onChunk({ event: "__envelopes", envelopes: intercepted }); } catch { /* ignore */ }
+              continue;
+            }
+            const chunk = translateClaudeEventToChunk(ev);
+            if (!chunk) continue;
+            const chunks = Array.isArray(chunk) ? chunk : [chunk];
+            for (const c of chunks) {
+              if (c?.event === "response.completed") sawResponseCompleted = true;
+              try { await onChunk(c); } catch { /* ignore */ }
+            }
+          }
+        },
+        onInvalid: () => {},
+        log,
+      });
+
+      handle.child.stdout.on("data", (buf) => parser.push(buf));
+
+      const code = await new Promise((resolve) => {
+        handle.child.once("exit", (c) => {
+          parser.flush();
+          resolve(c == null ? -1 : c);
+        });
+        handle.child.once("error", () => resolve(-1));
+      });
+      childExited = true;
+      unregister();
+
+      const stderrTail = handle.getStderrTail ? handle.getStderrTail() : "";
+      return {
+        code, stderrTail, sawAssistantOutput, sawNonSyntheticOutput,
+        pendingSessionId, abortedByRpc,
+        pendingAskBatches, ensureAskTerminal,
+      };
+    }
+
+    // 第一次尝试：用现有 session_id（如果有）
+    let resumeSessionId = thread_id ? threadSessionMap.get(thread_id) : null;
+    let result = await attemptOnce({ resumeSessionId, isRetry: false });
+
+    // 兜底 1：spawn 失败直接报。
+    if (result.spawnError) {
+      await onChunk({ event: "response.failed", error: { message: `spawn failed: ${result.spawnError}` } });
+      return;
+    }
+    if (result.stdinError) {
+      await onChunk({ event: "response.failed", error: { message: `stdin write failed: ${result.stdinError}` } });
+      return;
+    }
+
+    // Bug-B 修复：--resume <id> 失败 + stderr 含 "No conversation found"
+    // → 清掉 map 里那条幻影 session_id，retry 一次无 resume 路径。
+    if (
+      result.code === 1 &&
+      resumeSessionId &&
+      typeof result.stderrTail === "string" &&
+      /no conversation found/i.test(result.stderrTail)
+    ) {
+      log.warn?.("claude.session.invalid",
+        "claude --resume rejected (session not found); clearing cache and retrying without resume",
+        { thread_id, stale_session_id: resumeSessionId });
+      if (thread_id) threadSessionMap.delete(thread_id);
+      result = await attemptOnce({ resumeSessionId: null, isRetry: true });
+      if (result.spawnError) {
+        await onChunk({ event: "response.failed", error: { message: `spawn failed (retry): ${result.spawnError}` } });
+        return;
+      }
+      if (result.stdinError) {
+        await onChunk({ event: "response.failed", error: { message: `stdin write failed (retry): ${result.stdinError}` } });
+        return;
+      }
+    }
+
+    // Session-id 写入策略：只有当 claude 本轮真的跑了 LLM turn(产出过非
+    // synthetic 的 assistant 内容)时才信任这个 session_id —— 说明会话 jsonl
+    // 已写盘。synthetic slash 响应(/help /status /cost 等)和"无任何 assistant
+    // 内容"都不能信, 否则下一轮 --resume <sid> 报 "No conversation found"。
+    //
+    // 覆盖的场景:
+    //   - 普通对话:sawNonSyntheticOutput=true → 落盘 ✓
+    //   - /compact passthrough(claude 真跑 LLM compaction):sawNonSyntheticOutput=true → 落盘 ✓
+    //   - /help /status 等被 claude 以 synthetic 应答:sawNonSyntheticOutput=false → 丢
+    //   - claude 异常无 assistant:sawAssistantOutput=false → 丢
+    if (
+      thread_id &&
+      result.code === 0 &&
+      result.sawNonSyntheticOutput &&
+      result.pendingSessionId
+    ) {
+      threadSessionMap.set(thread_id, result.pendingSessionId);
+    } else if (
+      thread_id &&
+      result.pendingSessionId &&
+      !result.sawNonSyntheticOutput
+    ) {
+      log.info?.("claude.session.discarded",
+        "claude emitted session_id but no real LLM turn (synthetic slash response or no output); discarding to avoid stale resume",
+        { thread_id, discarded_session_id: result.pendingSessionId,
+          is_passthrough_slash: isPassthroughSlash,
+          saw_synthetic_only: result.sawAssistantOutput && !result.sawNonSyntheticOutput,
+          exit_code: result.code });
+    }
+
+    // child 已退出但 AskUserQuestion 还挂着 → reconcile。
+    //
+    // fix-claude-ask-resume-injection 新行为：
+    //   - session_id 可用（exit_code=0 && sawNonSyntheticOutput && pendingSessionId）：
+    //     不发 blockCompleted(canceled)；让 interrupt block 保持 awaiting；
+    //     锁定 retainedSessionId 供后续异步等待链起 --resume child。
+    //   - session_id 不可用：退化为原止血路径（cancel + log warn）。
+    //
+    // 无论哪条路径，补 run.completed 让 dispatcher 正常收尾（dispatch 层因
+    // run.paused 跳过合成收尾，必须这里收）。
+    const reconcileAskOnExit = async ({ emitTerminal }) => {
+      const all = result.pendingAskBatches || [];
+      if (all.length === 0) return;
+      const stale = all.filter((b) => !b.finalized);
+
+      // 判断是否有可用 session_id
+      const hasRetainableSession = (
+        result.code === 0 &&
+        result.sawNonSyntheticOutput &&
+        result.pendingSessionId != null
+      );
+
+      for (const b of stale) {
+        if (hasRetainableSession) {
+          // 留存路径：不 finalize（让异步 waitPromises.then() 继续处理），
+          // 锁定 session_id，不发 canceled。
+          // 注意：不设 b.finalized = true，让 waitPromises.then() 可以继续执行。
+          b.retainedSessionId = result.pendingSessionId;
+          log?.info?.("claude.ask_user_question.session_retained",
+            "session_id retained for --resume injection; interrupt block stays awaiting",
+            { run_id, session_id: result.pendingSessionId });
+        } else {
+          // 止血路径：cancel + warn
+          b.finalized = true;
+          try { b.abortCtrl.abort(); } catch { /* ignore */ }
+          log?.warn?.("claude.ask_user_question.no_session_id_for_resume",
+            "child exited without usable session_id; falling back to cancel interrupt blocks",
+            { run_id, exit_code: result.code,
+              saw_non_synthetic: result.sawNonSyntheticOutput,
+              pending_session_id: result.pendingSessionId });
+          const canceledEnvelopes = b.blocks.map((blk) =>
+            buildBlockCompleted(run_id, {
+              id: blk.id,
+              type: "interrupt",
+              subtype: blk.subtype,
+              prompt: blk.prompt,
+              status: "canceled",
+            }),
+          );
+          try { await onChunk({ event: "__envelopes", envelopes: canceledEnvelopes }); } catch { /* ignore */ }
+        }
+      }
+      const staleCanceled = stale.filter((b) => b.finalized);
+      if (staleCanceled.length > 0) {
+        log.info?.("claude.ask_user_question.reconciled_on_exit",
+          "claude exited with AskUserQuestion pending; canceled interrupt blocks (no session_id)",
+          { run_id, batch_count: staleCanceled.length });
+      }
+      if (emitTerminal && typeof result.ensureAskTerminal === "function") {
+        await result.ensureAskTerminal();
+      }
+    };
+
+    // 用户主动停止（sessions.abort RPC kill）→ 优雅收尾，不报失败
+    if (result.abortedByRpc) {
+      log.info?.("claude.run.aborted", "run killed by sessions.abort rpc",
+        { thread_id, run_id, code: result.code });
+      await emitAssistantText(onChunk, "已停止本次回复。");
+      await reconcileAskOnExit({ emitTerminal: true });
+      return;
+    }
+
+    if (result.code !== 0) {
+      log.warn?.("child.nonzero_exit", "claude exited non-zero",
+        { code: result.code, stderrTail: result.stderrTail });
+      // 卡片先置 canceled；终态交给下面的 response.failed（run.failed）
+      await reconcileAskOnExit({ emitTerminal: false });
+      await onChunk({
+        event: "response.failed",
+        error: { message: `claude exited code=${result.code} stderr=${(result.stderrTail || "").slice(-200)}` },
+      });
+      return;
+    }
+
+    // 兜底 2：slash 命令短路退出，0 assistant chunk —— 给一句"命令已发往
+    // Claude Code,无可显示输出"提示,免得 App 看起来卡住。
+    if (isPassthroughSlash && !result.sawAssistantOutput) {
+      await emitAssistantText(
+        onChunk,
+        `「${slash.command}」已发给 Claude Code 处理，但 CLI 在远程模式下无可显示输出。\n` +
+        `如果是 /compact，可以在下一条消息观察上下文是否变短。`,
+      );
+    }
+    // 正常退出且 ask 还挂着 → 卡片 canceled + 补终态（dispatch 层因
+    // run.paused 不会自动追加 run.completed，必须这里收）。
+    await reconcileAskOnExit({ emitTerminal: true });
+    // 若 stdout 没有 message_stop（response.completed），unifiedDispatchHandler 会自动追加 run.completed
+    } finally {
+      try { _acc?.flush(); } catch { /* swallow */ }
+      // approval 模式清理：stop permServer + 删 MCP config 临时文件
+      if (_approvalPermServer) {
+        try { await _approvalPermServer.stop(); } catch { /* swallow */ }
+        _approvalPermServer = null;
+      }
+      if (_approvalMcpConfigPath) {
+        try { await doDeleteMcpConfig(_approvalMcpConfigPath); } catch { /* swallow */ }
+        _approvalMcpConfigPath = null;
+      }
+    }
+  };
+
+  // 注册 unifiedDispatchHandler
+  const unifiedHandler = createUnifiedDispatchHandler({
+    relayUrl,
+    bridgeToken,
+    log,
+    producerFactory,
+    openclawInvoke: injectedOpenclawInvoke ?? defaultOpenclawInvoke,
+    gatewayId: claudeGwId, // 正文 agentlink-cos:// 图片引用解析（sign-get）
+  });
+
+  // workspaces.create 实现（可注入用于测试）
+  const createWorkspaceImpl = _createWorkspace ?? _defaultCreateWorkspace;
+  // 自定义命令收集器（可注入用于测试）
+  const collectCustomCommandsImpl = _collectCustomCommands ?? _defaultCollectCustomCommands;
+
+  return async function handleRequest(request, ctx) {
+    // 步骤 0（最优先）：relay-rpc 分支。
+    if (request?.request?.__relayKind === "rpc") {
+      const method = request.request.method;
+      const params = request.request.params ?? {};
+      let result;
+      try {
+        if (method === "__runtime.customCommands") {
+          // 获取当前工作区的自定义命令清单。
+          // workspacePath 由 App 传入；probe claude system/init 获取活体 slash_commands。
+          const workspacePath = typeof params.workspacePath === "string" && params.workspacePath.trim()
+            ? params.workspacePath.trim()
+            : cwd;
+          let init = null;
+          try {
+            init = await probeClaudeSystemInit({ cwd: workspacePath, timeoutMs: 8000 });
+          } catch {
+            log.warn?.("claude.rpc.customCommands.probe_failed", "probeClaudeSystemInit failed", { workspacePath });
+          }
+          const commands = await collectCustomCommandsImpl({ init, cwd: workspacePath });
+          result = { commands };
+        } else if (method === "workspaces.scan") {
+          // workspaces.scan 走通用 scanWorkspacesByRuntime（claude runtime 读
+          // ~/.claude.json projects trust list）。
+          result = await scanWorkspacesByRuntime({
+            runtimeKind: "claude",
+            gatewayId: claudeGwId,
+            params,
+          });
+        } else if (method === "workspaces.create") {
+          result = await createWorkspaceImpl({
+            runtime: "claude",
+            name: params.name,
+          });
+        } else if (method === "sessions.abort" || method === "chat.abort") {
+          // P0 停止按钮：杀掉匹配的活跃 claude 子进程
+          const { aborted, matched } = activeRuns.abort({
+            key: params.key ?? params.sessionKey ?? "",
+            runId: params.runId ?? "",
+          });
+          log.info?.("claude.rpc.abort", "sessions.abort handled", {
+            requestId: ctx.requestId, key: params.key || "", runId: params.runId || "",
+            aborted, matched,
+          });
+          result = { ok: true, aborted, matched };
+        } else {
+          result = { ok: false, error: `unknown rpc method: ${method}` };
+        }
+      } catch (err) {
+        result = { ok: false, error: err?.message ?? String(err) };
+      }
+      await ctx.publishEvent({
+        event: "response",
+        statusCode: 200,
+        contentType: "application/json; charset=utf-8",
+        body: JSON.stringify(result),
+      });
+      await ctx.publishEvent({ event: "end" });
+      return;
+    }
+
+    // 步骤 1：优先走 unified dispatch
+    const handled = await unifiedHandler(request, ctx);
+    if (handled) return;
+
+    // 步骤 2：旧路径 — 与 index.mjs 原有逻辑一致
+    const userText = extractUserText(request);
+    if (!userText) {
+      log.warn?.("turn.skip", "no user text in request", { requestId: ctx.requestId });
+      await ctx.publishEvent({ event: "error", error: "empty user input" });
+      await ctx.publishEvent({ event: "end" });
+      return;
+    }
+
+    await ctx.publishEvent({ event: "start" });
+
+    let handle;
+    try {
+      handle = mkSpawn({ cwd, log });
+    } catch (err) {
+      const msg = err?.message || String(err);
+      log.error?.("child.spawn.failed", "spawn claude failed", { err: msg });
+      await ctx.publishEvent({ event: "error", error: `spawn failed: ${msg}` });
+      await ctx.publishEvent({ event: "end" });
+      return;
+    }
+
+    // 写 user 消息进 stdin
+    try {
+      await writeUserMessage(handle.child, userText);
+    } catch (err) {
+      const msg = err?.message || String(err);
+      log.error?.("child.stdin.failed", "write user message failed", { err: msg });
+      await ctx.publishEvent({ event: "error", error: `stdin write failed: ${msg}` });
+      await ctx.publishEvent({ event: "end" });
+      try { handle.kill("stdin-failed"); } catch {}
+      return;
+    }
+
+    // 透传 stdout 行 — claude adapter 直接吃 native stream-json，逐行 chunk 即可。
+    let stdoutBuf = "";
+    handle.child.stdout.on("data", (buf) => {
+      stdoutBuf += buf.toString("utf8");
+      let nl;
+      while ((nl = stdoutBuf.indexOf("\n")) >= 0) {
+        const line = stdoutBuf.slice(0, nl).trim();
+        stdoutBuf = stdoutBuf.slice(nl + 1);
+        if (!line) continue;
+        void ctx.publishEvent({ event: "chunk", data: line });
+      }
+    });
+
+    // 等子进程退出
+    const code = await new Promise((resolve) => {
+      handle.child.once("exit", (c) => resolve(c == null ? -1 : c));
+      handle.child.once("error", () => resolve(-1));
+    });
+
+    // 处理 stdout 残余
+    const tail = stdoutBuf.trim();
+    stdoutBuf = "";
+    if (tail) {
+      await ctx.publishEvent({ event: "chunk", data: tail });
+    }
+
+    if (code !== 0) {
+      const stderrTail = handle.getStderrTail ? handle.getStderrTail() : "";
+      log.warn?.("child.nonzero_exit", "claude exited non-zero", { code, stderrTail });
+      await ctx.publishEvent({
+        event: "error",
+        error: `claude exited code=${code} stderr=${(stderrTail || "").slice(-400)}`,
+      });
+    }
+    await ctx.publishEvent({ event: "end" });
+
+    usage.addCost({ turns: 1 });
+  };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function extractUserText(request) {
+  const input = request?.request?.input;
+  if (typeof input === "string") return input.trim();
+  if (Array.isArray(input)) return collectTextFromItems(input).trim();
+  if (input && typeof input === "object") {
+    if (typeof input.text === "string") return input.text.trim();
+    if (input.content !== undefined) return collectTextFromAny(input.content).trim();
+  }
+  if (typeof request?.clientPreviewText === "string") {
+    return request.clientPreviewText.trim();
+  }
+  return "";
+}
+
+function collectTextFromAny(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return collectTextFromItems(value);
+  if (value && typeof value === "object" && typeof value.text === "string") return value.text;
+  return "";
+}
+
+function collectTextFromItems(items) {
+  const parts = [];
+  for (const item of items) {
+    if (typeof item === "string") { parts.push(item); continue; }
+    if (!item || typeof item !== "object") continue;
+    if (item.role && String(item.role).toLowerCase() !== "user") continue;
+    if (typeof item.text === "string") { parts.push(item.text); continue; }
+    if (item.content !== undefined) {
+      const t = collectTextFromAny(item.content);
+      if (t) parts.push(t);
+    }
+  }
+  return parts.join("\n\n");
+}