@sema-agent/client-core 0.8.0 → 0.9.0

package/dist/hitl/askGateWire.js

@@ -0,0 +1,530 @@
+import { HitlBridge } from './hitlBridge.js';
+import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
+import { hostLog } from '../host.js';
+import { isFsApprovalGate, toolNameIsFsWrite, surfaceFsApprovalAndDecide, isToolApprovalFrame, isFromSubagent, surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
+import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
+let hostSurface = null;
+let hostSurfaceMisses = 0;
+/** 装 HITL 宿主面(传 null 卸)。返回还原函数。 */
+export function installHitlHostSurface(surface) {
+    const prev = hostSurface;
+    hostSurface = surface;
+    return () => {
+        hostSurface = prev;
+    };
+}
+/** 🔴 宿主自检:恒应为 0。非 0 = 有 HITL 副作用发生时口不在,那一行 warn / 那条记账丢了。 */
+export function hitlHostSurfaceMisses() {
+    return hostSurfaceMisses;
+}
+/** 测试钩:卸口 + 清计数。 */
+export function _resetHitlHostSurfaceForTest() {
+    hostSurface = null;
+    hostSurfaceMisses = 0;
+}
+function surface() {
+    if (hostSurface === null)
+        hostSurfaceMisses++;
+    return hostSurface;
+}
+/**
+ * CC `utils/messages.ts` 的 `REJECT_MESSAGE` **逐字**(搬迁差分 2)。deny 后重放 tool_end 的
+ * render 面 stamp 用 —— vendored `renderToolUseRejectedMessage` 渲 `User rejected <op> to <path>`。
+ * 🔴 与壳树那份的 byte-identity 由 pure 门 B7 段锁住(壳树缺席 ⇒ DEGRADED,不假绿)。
+ */
+export const HITL_REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
+function rejectMessageForRender() {
+    return HITL_REJECT_MESSAGE;
+}
+/** 一 turn 内最多循环这么多次 park(防御:引擎/模型病态连环提问时不无限 attach)。 */
+const MAX_GATE_HOPS = 24;
+function isAskTool(name) {
+    return typeof name === 'string' && name.replace(/[\s_-]+/g, '').toLowerCase() === 'askuserquestion';
+}
+/** done 帧的 AskUserQuestion park 形状(结构性读;别的终态一律 false)。 */
+function isAskGatePark(result) {
+    const r = result;
+    return (!!r &&
+        r.status === 'suspended' &&
+        isAskTool(r.checkpointGate?.toolName) &&
+        typeof r.taskId === 'string' &&
+        r.taskId.length > 0);
+}
+/** done 帧的 fs 写权限 park 形状([816] 放宽腿):status suspended + checkpointGate 指 fs 写工具
+ *  (Write/Edit/NotebookEdit)或一等 kind==='tool_approval'。Ask gate 恒先判(问答 overlay 原路)。 */
+function isFsApprovalPark(result) {
+    const r = result;
+    return (!!r &&
+        r.status === 'suspended' &&
+        typeof r.taskId === 'string' &&
+        r.taskId.length > 0 &&
+        !isAskTool(r.checkpointGate?.toolName) &&
+        isFsApprovalGate(r.checkpointGate));
+}
+/** 把 wire 答案({answers:[{header,selected,note?}]})折回 CC 卡片的 Record<question,string> 形状
+ *  (multiSelect 与对话框同款 ", " lossy join;note → annotations.notes)。 */
+export function toAnsweredOutput(questions, answer) {
+    const answers = {};
+    const annotations = {};
+    for (const entry of answer.answers ?? []) {
+        const q = questions.find(qq => qq.header === entry.header);
+        const key = typeof q?.question === 'string' ? q.question : entry.header;
+        answers[key] = (entry.selected ?? []).join(', ');
+        if (entry.note)
+            annotations[key] = { notes: entry.note };
+    }
+    return {
+        type: 'ask-user-question',
+        questions,
+        answers,
+        ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+    };
+}
+// ── 件3(中断事故修复批 G,2026-07-15)—— 中断 deny 的有界观察 ─────────────────────────────────
+/** cancel-by-deny 的后台 settle 预算。decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测
+ *  4-5s+),但 DENY-abort 语义上引擎收到即终结 run;2s 内连收都没收到 ⇒ 按丢失警示(晚到成功
+ *  只是多一行良性 warn,比锁死无线索诚实)。 */
+export const CANCEL_DENY_BUDGET_MS = 2000;
+/** warn 行文案(测试锁字面)。 */
+export const CANCEL_DENY_WARN_TEXT = 'could not cancel the pending question — the session may stay locked; the run may need engine-side recovery';
+const CANCEL_DENY_WARN_KEY = 'hitl-cancel-deny-warn';
+const CANCEL_DENY_WARN_TIMEOUT_MS = 10_000;
+/** 失败 warn 上屏:借 footer notifications 通道。壳原文经 `appStateRef` 直写 store
+ *  (immediate 语义:立即顶到 current + 到点自清「仅当仍是本 warn 时」);本包把那两次
+ *  setState 拆成宿主口的两个动词,**时序纪律(2s 预算 / 10s 自清)留在库内**——
+ *  [paired-mechanisms-must-share-premise]:只给「显示」不给「清」,端各写各的清法必然漂。
+ *  无口(print/headless 没屏可上)⇒ 静默,与壳原文 `if (!store) return` 同语义。 */
+function surfaceCancelDenyWarn() {
+    try {
+        const s = surface();
+        if (!s)
+            return;
+        s.showNotice({
+            key: CANCEL_DENY_WARN_KEY,
+            text: CANCEL_DENY_WARN_TEXT,
+            color: 'warning',
+            priority: 'immediate',
+            timeoutMs: CANCEL_DENY_WARN_TIMEOUT_MS,
+        });
+        const timer = setTimeout(() => {
+            try {
+                s.clearNoticeIfCurrent(CANCEL_DENY_WARN_KEY);
+            }
+            catch {
+                /* fail-soft */
+            }
+        }, CANCEL_DENY_WARN_TIMEOUT_MS);
+        timer.unref?.();
+    }
+    catch {
+        /* fail-soft:上屏失败绝不再伤害 abort 流 */
+    }
+}
+/**
+ * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面)。
+ * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:
+ *   - 2s 内 settle 成功 ⇒ 零上屏(SEMA_DEBUG 记成功);
+ *   - 失败/超时 ⇒ 上屏一行 warn + SEMA_DEBUG 记原因(deny 丢失 = run 卡 suspended,下一条消息
+ *     撞 409;配合件2b 的专属文案,用户知道现场 + 出路);
+ *   - HitlSafetyError code==='no_pending' ⇒ 良性静默(pending 已被别处消解/过期 —— run 没锁;
+ *     hitlBridge decideTool 的同款语义,那里的静默维持不动)。
+ */
+export function observeCancelByDeny(settle, taskId) {
+    let timer;
+    const budget = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`cancel-by-deny did not settle within ${CANCEL_DENY_BUDGET_MS}ms`)), CANCEL_DENY_BUDGET_MS);
+        timer.unref?.();
+    });
+    void Promise.race([settle, budget])
+        .then(() => {
+        hostLog('debug', `[hitl-ask] cancel-by-deny settled for run ${taskId} (session unlocked)`);
+    })
+        .catch((e) => {
+        if (e?.code === 'no_pending') {
+            hostLog('debug', `[hitl-ask] cancel-by-deny no_pending for run ${taskId} (benign — already resolved)`);
+            return;
+        }
+        hostLog('error', `[hitl-ask] cancel-by-deny FAILED for run ${taskId}: ${String(e)}`);
+        surfaceCancelDenyWarn();
+    })
+        .finally(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+    // 超时后原 promise 迟到 reject 不得变成 unhandledRejection。
+    void settle.catch(() => { });
+}
+/**
+ * 弹既有 AskUserQuestion overlay → 等作答 → 经 HitlBridge decide(答案/拒答)。
+ * decide 成功即引擎已把 run 驱到下一状态(sync);调用方随后 attach runs.events 续流。
+ */
+async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal) {
+    if (!hasQuestionOverlay()) {
+        return { kind: 'failed', reason: 'no question overlay mounted (print/non-REPL mode)' };
+    }
+    // pending 行 = 问题 payload 的权威源 + D-1 绑定的唯一 surface(PendingCheckpoint.input)。
+    let pending;
+    try {
+        const rows = await deps.client.approvals.list(signal ? { signal } : undefined);
+        pending =
+            rows.find(r => r.taskId === taskId && isAskTool(r.toolName ?? undefined)) ??
+                rows.find(r => r.taskId === taskId);
+    }
+    catch (e) {
+        return { kind: 'failed', reason: `approvals.list failed: ${String(e)}` };
+    }
+    if (!pending)
+        return { kind: 'failed', reason: 'no pending checkpoint for this run (resolved/expired?)' };
+    const gatedCallId = pending.toolCallId ?? pending.boundCallId ?? undefined;
+    // 问题 payload:优先流上 tool_start.args(零额外语义),缺则 pending.input(service 已 redact + 限长)。
+    const fromArgs = gatedCallId
+        ? askArgsByCall.get(gatedCallId)?.questions
+        : undefined;
+    const fromPending = pending.input?.questions;
+    const questions = Array.isArray(fromArgs) && fromArgs.length > 0 ? fromArgs : fromPending;
+    if (!Array.isArray(questions) || questions.length === 0) {
+        // [1543]②:input 超引擎入参帽(MAX_TOOL_INPUT_CHARS,preview 富文本题易中)时 server 降级为
+        // {truncated:true} ——无题可渲不是引擎代差,是 payload 被截。分形出诚实理由(fail-soft 链
+        // 会把 reason 记入 SEMA_DEBUG,别再误导成 pre-CHANNEL[56] 老引擎)。
+        const truncated = pending.input?.truncated === true;
+        return {
+            kind: 'failed',
+            gatedCallId,
+            reason: truncated
+                ? 'question payload exceeded the engine input cap (input={truncated:true}) — dialog cannot be re-rendered; run stays suspended for out-of-band decide'
+                : 'gate has no question payload (pre-CHANNEL[56] engine?)',
+        };
+    }
+    // overlay 往返:合成 frame(id 独占命名空间 hitl-ask:)→ local responder 一次性收答。
+    const questionId = `hitl-ask:${gatedCallId ?? taskId}`;
+    const answer = await new Promise(resolve => {
+        const unregister = registerLocalQuestionResponder(questionId, async (_id, a) => {
+            cleanup();
+            resolve(a);
+            return { ok: true };
+        });
+        const onAbort = () => {
+            cleanup();
+            // 撤下还开着的对话框(question_complete = overlay 的既有 dismiss 语义)
+            publishQuestionFrame({ type: 'question_complete', questionId });
+            resolve(null);
+        };
+        const cleanup = () => {
+            unregister();
+            signal?.removeEventListener('abort', onAbort);
+        };
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        publishQuestionFrame({ type: 'question', questionId, questions });
+    });
+    const bridge = new HitlBridge(deps.client, taskId);
+    if (answer === null) {
+        // turn 被中断(Esc/Ctrl+C):cancel-by-deny(contract/04 §2.4 —— suspended run 不 runs.cancel)。
+        // 件3(中断事故修复批 G,2026-07-15,症状1 壳侧配套):此前 .catch(()=>{}) 全吞 = deny 丢失时
+        // run 永卡 suspended,session 锁死,用户下一条消息撞 409「active run」还全无线索。改为有界观察
+        // (observeCancelByDeny,2s 预算):abort 仍立即返回用户控制(不 await,交互时序不变),后台
+        // settle 失败/超时上屏一行 warn + SEMA_DEBUG 记失败原因。引擎侧解锁腿([866] server:cancel
+        // suspended 改语义 + reapSuspended TTL)到货前,这是壳能做的最诚实半场。
+        observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: 'Interrupted by user' }, gatedCallId), taskId);
+        return { kind: 'aborted', gatedCallId };
+    }
+    try {
+        const entries = (answer.answers ?? []);
+        const hasContent = entries.some(a => (a.selected?.length ?? 0) > 0 || (a.note?.length ?? 0) > 0);
+        if (hasContent) {
+            await bridge.answerQuestion(entries, gatedCallId, signal ? { signal } : undefined);
+            return { kind: 'decided', gatedCallId, answered: toAnsweredOutput(questions, answer) };
+        }
+        else {
+            // 用户拒答(overlay reject/dismiss 送空 answers)= 诚实 deny;模型收 denied 结果自续。
+            await bridge.decideTool({ decision: 'deny', reason: 'User declined to answer' }, gatedCallId, signal ? { signal } : undefined);
+        }
+        return { kind: 'decided', gatedCallId };
+    }
+    catch (e) {
+        return { kind: 'failed', gatedCallId, reason: `decide failed: ${String(e)}` };
+    }
+}
+/**
+ * 包一层 AgentEvent 流:把 AskUserQuestion 的 suspended park 变成「对话框 → decide → 续流」闭环。
+ * 其它事件原样透传;非 AskUserQuestion 的 gate 保持现状。fail-soft:任何桥内失败回退为
+ * 「flush 毒化 tool_end + 原样终帧」(= 修复前行为)。
+ *
+ * @param source 上游 AgentEvent 流(tasks.stream 或 runs.events,已过 demuxQuestionFrames)。
+ * @param opts.taskId runs.events 消费时已知的 run handle(sync leg 从 suspended done 捕获)。
+ */
+export async function* bridgeAskUserQuestionGates(source, deps, opts) {
+    const startedCalls = new Set();
+    const endedCalls = new Set();
+    /** park 毒化的 gated tool_end(isError:true "Operation aborted")——HOLD 到 gate 定性
+     *  (AskUserQuestion + [816] 放宽后的 fs 写工具)。 */
+    const heldAskEnds = new Map();
+    /** gated 工具的 tool_start.args(toolCallId → args)= 对话框/三选卡 payload 的一手源。 */
+    const askArgsByCall = new Map();
+    /** 三选卡 deny 过的 call:重放 tool_end 的 render 面 stamp REJECT_MESSAGE(vendored
+     *  renderToolUseRejectedMessage 渲 `User rejected <op> to <path>`,CC 逐字)。 */
+    const deniedCalls = new Set();
+    /** started-未-ended 的 fs 写 call(顺序保留)——同步 tool_approval 帧的 callId 关联面
+     *  (帧契约不带 toolCallId;引擎阻塞在帧上,最后一张未收口 fs 写 call 即被 gate 的 call)。 */
+    const pendingFsCalls = [];
+    /** 同步帧腿 deny 但 callId 关联不上(引擎在 tool_start 前出帧的形状):stamp 下一张 fs 写报错帧。 */
+    let denyStampNextFsEnd = false;
+    /** 已作答的 gate(toolCallId → CC 卡片形状的真实答案)——续流重放的解答 tool_end 无 output,
+     *  不补就会渲成结果不可用;这里 stamp `structured` 让卡片渲真实选择。 */
+    const resolvedAnswers = new Map();
+    let lastSeq;
+    let realTaskId = opts?.taskId;
+    let stream = source;
+    let hops = 0;
+    function* flushHeld() {
+        for (const [callId, held] of heldAskEnds) {
+            endedCalls.add(callId);
+            yield held;
+        }
+        heldAskEnds.clear();
+    }
+    while (true) {
+        /** park 请求:遇 AskUserQuestion / fs 写权限 gate 时置位后 break 内环。 */
+        let park = null;
+        for await (const ev of stream) {
+            const seq = ev.id;
+            if (typeof seq === 'string' && seq.length > 0)
+                lastSeq = seq;
+            // ── server 1.191 同步帧腿([830]①):`tool_approval` 帧 → 三选卡 → respond ────────────────
+            // 引擎此刻同步阻塞在帧上(fail-closed:无 respond/TTL 5min/abort ⇒ deny),await 卡决断安全。
+            // 帧是 HITL 词汇非 AgentEvent arm——两种帧都不外泄到渲染管道。
+            if (isToolApprovalFrame(ev)) {
+                // #51: `ToolApprovalFrame` frames are documented as NOT part of the
+                // `AgentEvent` union (a separate SSE wire vocabulary riding the same
+                // stream) — intersecting the type-predicate's asserted type with the
+                // unrelated `AgentEvent` union collapses every arm to `never`. Local
+                // rebind restores the real (already-checked) shape.
+                const frame = ev;
+                if (frame.type === 'tool_approval_complete')
+                    continue; // 收口帧:卡已由决断路径撤下,吞掉
+                if (!deps.respondToolApproval) {
+                    hostLog('debug', `liveHitlAskWire: tool_approval frame ${frame.approvalId} but no respond wire — engine self-settles (TTL deny)`);
+                    continue;
+                }
+                // 补验批 askq 案定谳(2026-07-23,黑板 [1534],引擎 dist 逐坐标读定):core 的 durable
+                // question policy 对 AskUserQuestion 出 action:"ask",本意让 durable gate park(suspended
+                // → 本函数下方 bridge 弹卡收答);但 core suspendAsk 的退位条件(safety 缺席 + onAsk 在场)
+                // 把问题门也抢进了同步审批帧腿(壳为 fs 写权限三选卡开的 TOOL_APPROVAL_ENABLED)——同步帧
+                // 二值 respond 装不下「答案」,链路死锁:deny=模型误信问题已展示原地等;allow=执行工具
+                // 本体炸 durable 装配的 onQuestion 占位(QUESTION_AWAITS_RESUME)。此处取两害之轻恒 allow:
+                // 模型收到明确错误后退化成正文提问,用户尚可下一条消息作答(deny 形连这条退化路都没有)。
+                // 承重域收敛史([1543]§一 cli 注意):core 1.375 修 question gate 恒 park(健康路),
+                // 1.376 又断了降级路(checkpoint pre-commit/put 失败 fallback 改 typed refusal)与继承链
+                // 两臂——1.376+ 下 ask 工具在任何路径都不再出 tool_approval 帧,本分支唯一剩余承重
+                // = 旧引擎(<1.375)兼容,askq pty fence @1.375+ 已四门全绿实证([1542])。
+                if (isAskTool(ev.toolName)) {
+                    try {
+                        await deps.respondToolApproval(frame.approvalId, 'allow', {
+                            ...(opts?.signal && !opts.signal.aborted ? { signal: opts.signal } : {}),
+                        });
+                        hostLog('debug', `liveHitlAskWire: ask-tool approval frame ${frame.approvalId} → allow(问题门放行,候 park 弹卡)`);
+                    }
+                    catch (e) {
+                        hostLog('debug', `liveHitlAskWire: ask-tool approval allow failed for ${frame.approvalId}: ${String(e)} — engine self-settles (TTL)`);
+                    }
+                    continue;
+                }
+                // [1535]/server 1.258:子代的审批帧(broker 腿浮到宿主流,判别=fromSubagent 显式键
+                // core 1.378 优先/sourceTaskId 在场性兜底)——子代的 tool_start 不在宿主行流上,绝不把
+                // 宿主自己的 pending fs call 关联给它(args 会错配成宿主的 diff、deny 会误标宿主 call 的
+                // REJECT 收口)。args 从帧上取,deny 收口归子代 lane 自理。
+                const fromSubagent = isFromSubagent(ev);
+                hostLog('debug', `liveHitlAskWire: tool_approval frame ${frame.approvalId} tool=${String(ev.toolName)}${fromSubagent ? ` from-subagent=${String(ev.sourceTaskId ?? ev.sourceAgentName ?? 'explicit')}` : ''}`);
+                const gatedCallId = !fromSubagent && pendingFsCalls.length > 0 ? pendingFsCalls[pendingFsCalls.length - 1] : undefined;
+                const decision = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, gatedCallId !== undefined ? askArgsByCall.get(gatedCallId) : undefined, opts?.signal);
+                if (decision === 'deny' && !fromSubagent) {
+                    // 该 call 的报错收口帧 stamp REJECT 文案(vendored `User rejected <op> to <path>` 卡)。
+                    if (gatedCallId !== undefined)
+                        deniedCalls.add(gatedCallId);
+                    else
+                        denyStampNextFsEnd = true;
+                }
+                continue;
+            }
+            if (ev.type === 'tool_start' && typeof ev.toolCallId === 'string') {
+                if (startedCalls.has(ev.toolCallId))
+                    continue; // durable 重放的已渲 call
+                startedCalls.add(ev.toolCallId);
+                if (isAskTool(ev.toolName) || (typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName))) {
+                    askArgsByCall.set(ev.toolCallId, ev.args);
+                    if (typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName)) {
+                        pendingFsCalls.push(ev.toolCallId);
+                    }
+                }
+                yield ev;
+                continue;
+            }
+            if (ev.type === 'tool_end' && typeof ev.toolCallId === 'string') {
+                if (endedCalls.has(ev.toolCallId))
+                    continue; // durable 重放/park 复写的已收口 call
+                {
+                    const pi = pendingFsCalls.indexOf(ev.toolCallId);
+                    if (pi !== -1)
+                        pendingFsCalls.splice(pi, 1);
+                }
+                // ── 分类器批3([907]):auto-mode 分类器 deny 裁决帧 —— 结构性识别(core 机器签名)优先于
+                // fs HOLD/REJECT 分支(签名比"fs 写报错"更特定;分类器 deny 从不产 tool_approval 帧,
+                // deniedCalls/denyStampNextFsEnd 与之互斥)。副作用 = CC 207 通知行 + Recent Denials 记账;
+                // render 面 stamp 去 system-reminder 包裹渲裁决原文(render-only,模型面原文不动)。
+                if (ev.isError === true && !deniedCalls.has(ev.toolCallId)) {
+                    const verdict = classifierDenyFromToolEnd(ev);
+                    if (verdict) {
+                        endedCalls.add(ev.toolCallId);
+                        heldAskEnds.delete(ev.toolCallId);
+                        surface()?.surfaceClassifierDeny(typeof ev.toolName === 'string' ? ev.toolName : 'tool', verdict);
+                        hostLog('debug', `liveHitlAskWire: classifier deny verdict on ${ev.toolCallId} (${String(ev.toolName)}) — labeled render + notice`);
+                        yield { ...ev, output: verdict.message, structured: undefined };
+                        continue;
+                    }
+                }
+                if (ev.isError === true &&
+                    typeof ev.toolName === 'string' &&
+                    toolNameIsFsWrite(ev.toolName) &&
+                    denyStampNextFsEnd &&
+                    !deniedCalls.has(ev.toolCallId)) {
+                    // 同步帧腿 deny 且 callId 没关联上:下一张 fs 写报错帧即该 gate 的收口帧,stamp REJECT 文案。
+                    denyStampNextFsEnd = false;
+                    endedCalls.add(ev.toolCallId);
+                    heldAskEnds.delete(ev.toolCallId);
+                    yield { ...ev, output: rejectMessageForRender(), structured: undefined };
+                    continue;
+                }
+                if (ev.isError === true &&
+                    (isAskTool(ev.toolName) || (typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName)))) {
+                    if (deniedCalls.has(ev.toolCallId)) {
+                        // 三选卡 No:重放的报错帧 stamp REJECT 文案 → vendored 卡渲 `User rejected <op> to <path>`。
+                        deniedCalls.delete(ev.toolCallId);
+                        endedCalls.add(ev.toolCallId);
+                        heldAskEnds.delete(ev.toolCallId);
+                        yield { ...ev, output: rejectMessageForRender(), structured: undefined };
+                        continue;
+                    }
+                    heldAskEnds.set(ev.toolCallId, ev); // park 毒化帧,先 HOLD(gate 定性前不渲 Error 卡)
+                    continue;
+                }
+                endedCalls.add(ev.toolCallId);
+                heldAskEnds.delete(ev.toolCallId); // 正常收口(重放的 isError:false 解答帧)赢
+                const answered = resolvedAnswers.get(ev.toolCallId);
+                if (answered &&
+                    ev.isError !== true &&
+                    ev.structured === undefined) {
+                    resolvedAnswers.delete(ev.toolCallId);
+                    yield { ...ev, structured: answered }; // 真实答案卡(见 resolvedAnswers 注)
+                }
+                else {
+                    yield ev;
+                }
+                continue;
+            }
+            if (ev.type === 'suspended') {
+                // durable leg 的 park arm(续流中模型再次提问/再次撞写权限)。gate 只带 kind/toolName,
+                // payload 走 approvals。
+                if (ev.gate && isAskTool(ev.gate.toolName) && realTaskId) {
+                    park = { gate: 'ask' };
+                    break;
+                }
+                if (ev.gate && isFsApprovalGate(ev.gate) && realTaskId) {
+                    park = { gate: 'fs' };
+                    break;
+                }
+                yield ev; // 其余 gate:透传(现状,eventToSdkMessage 出 null)
+                continue;
+            }
+            if (ev.type === 'done') {
+                if (isAskGatePark(ev.result)) {
+                    realTaskId = realTaskId ?? ev.result.taskId;
+                    park = { pendingDone: ev, gate: 'ask' };
+                    break;
+                }
+                if (isFsApprovalPark(ev.result)) {
+                    realTaskId = realTaskId ?? ev.result.taskId;
+                    park = { pendingDone: ev, gate: 'fs' };
+                    break;
+                }
+                yield* flushHeld(); // 真错(非 gate)的 Ask tool_end 此刻诚实渲染
+                // durable 终帧的 result.taskId === sessionId(引擎 durable quirk)会让 captureSessionId 跳过
+                // rewind 绑定 —— 用 sync leg 捕的真 handle 修正回去。
+                const r = ev.result;
+                if (realTaskId && r && r.taskId === r.sessionId && r.taskId !== realTaskId) {
+                    yield { ...ev, result: { ...ev.result, taskId: realTaskId } };
+                }
+                else {
+                    yield ev;
+                }
+                return;
+            }
+            if (ev.type === 'failed') {
+                yield* flushHeld();
+                yield ev;
+                return;
+            }
+            yield ev;
+        }
+        if (!park) {
+            // 源流走完没终帧(disconnect/abort)——flush 后结束,与现状一致。
+            yield* flushHeld();
+            return;
+        }
+        hops++;
+        let outcome;
+        if (hops > MAX_GATE_HOPS) {
+            outcome = { kind: 'failed', reason: `gate hop limit (${MAX_GATE_HOPS}) exceeded` };
+        }
+        else if (park.gate === 'fs') {
+            // [816] 放宽腿:fs 写权限 gate → CC 三选卡(vendored PermissionRequest)→ decide。
+            outcome = await surfaceFsApprovalAndDecide({ client: deps.client }, realTaskId, askArgsByCall, opts?.signal);
+            // #51: `outcome`'s declared type is the wider `GateOutcome |
+            // FsApprovalOutcome`; both unions share a 'decided' kind with
+            // different optional fields (`answered` vs `denied`), so a plain
+            // `.denied` access doesn't hold for every 'decided' member even
+            // though this branch only ever assigns the FsApprovalOutcome shape.
+            // 'in' narrowing sidesteps it.
+            const outcomeDenied = 'denied' in outcome ? outcome.denied : undefined;
+            if (outcome.kind === 'decided' && outcomeDenied === true && outcome.gatedCallId) {
+                deniedCalls.add(outcome.gatedCallId); // 重放的报错帧渲 `User rejected …`(见 tool_end 手柄)
+            }
+        }
+        else {
+            outcome = await surfaceGateAndDecide(deps, realTaskId, askArgsByCall, opts?.signal);
+        }
+        if (outcome.kind !== 'decided') {
+            hostLog('debug', `liveHitlAskWire: gate not decided (${outcome.kind}${'reason' in outcome ? `: ${outcome.reason}` : ''}) — fail-soft to suspended terminal`);
+            yield* flushHeld(); // 回退:毒化帧照旧渲染(= 修复前的诚实红)
+            if (park.pendingDone) {
+                yield park.pendingDone;
+            }
+            else if (outcome.kind === 'failed') {
+                // 记案(#87 评审② minor,不修):durable re-attach 的第二问(park.pendingDone 无)走 `aborted`
+                // 时(仅用户主动 Esc/Ctrl+C 中断触发)不吐终帧——下游正在拆流,合成终帧也没人渲;flushHeld
+                // 已把毒化帧诚实吐出。真正的 failed 才合成下面的可见终帧。
+                // durable-leg park 无 done 可回吐 —— 合成 failed 让用户看得见为什么停了
+                yield {
+                    type: 'failed',
+                    errorCode: 'hitl_unanswered',
+                    errorMessage: `${park.gate === 'fs' ? 'Tool approval' : 'AskUserQuestion'} gate could not be answered: ${outcome.reason}`,
+                };
+            }
+            return;
+        }
+        // decide 成功:丢弃该 call 的毒化 HOLD(续流重放会带 isError:false 的解答帧收口卡片),
+        // 并记下真实答案供该解答帧 stamp `structured`(否则卡片渲成结果不可用)。
+        if (outcome.gatedCallId) {
+            heldAskEnds.delete(outcome.gatedCallId);
+            if ('answered' in outcome && outcome.answered)
+                resolvedAnswers.set(outcome.gatedCallId, outcome.answered);
+        }
+        hostLog('debug', `liveHitlAskWire: gate decided (call ${outcome.gatedCallId ?? '?'}) — attaching runs.events(${realTaskId})${lastSeq ? ` from seq ${lastSeq}` : ''}`);
+        stream = deps.runsEvents(realTaskId, {
+            ...(lastSeq !== undefined ? { lastEventId: lastSeq } : {}),
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+        });
+    }
+}