@sema-agent/client-core 0.8.0 → 0.9.0

package/dist/hitl/planReviewWire.js

@@ -0,0 +1,142 @@
+/**
+ * ⇄ B7 批搬迁(2026-07-27,设计稿 §3 B7):cli `src/sema/planReviewWire.ts`(142 行)**整条进包**。
+ *
+ * 🔴 **`wireConfig()` 第七份收编闭合**:B6 的 `engineWireTarget.ts` 头注记着「本批搬入的是前六份;
+ *    第七份 `planReviewWire` 不在 B6 范围,仍留壳内 —— 它是下一批的收编候选,别以为已经收干净了」。
+ *    本批就是那一批:这里改用 `engineWireTarget()`,壳树 `grep -rn 'function wireConfig' src/sema/`
+ *    的七份手抄至此**归零**(pure 门 B7 段有断言:壳树在场时命中数 = 0;缺席 ⇒ DEGRADED)。
+ *
+ * 🔴 其余搬迁差分(零行为变化):
+ *   1. `logForDebugging` → `hostLog`。
+ *   2. `await import('../utils/messageQueueManager.js').enqueuePendingNotification({...})`
+ *      → `NotificationQueuePort.enqueueMetaPrompt`(B7 新增的**可选**方法 —— 既有宿主实现不破)。
+ *      🔴 缺席后果不是「少个装饰」:模型永远不知道 plan 被批准/驳回后引擎跑出了什么结果,
+ *      于是它在 approve 之后**原地不动**。所以缺席计 miss(`notificationQueuePortMisses()`),
+ *      并保留壳原文的 try/catch fail-soft(投递失败绝不炸流)。
+ *   3. `registerLocalQuestionResponder`/`publishQuestionFrame` → 包内 `liveQuestionStore`
+ *      (B1 已搬,**同一个 module 台账**;两份实例 ⇒ 卡弹出来没人收答)。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * planReviewWire — plan_review park 的壳侧审批闭环(core [508]③ 形状拍板 + [511]② 实证)。
+ *
+ * WIRE 全链(server 1.138 × core 1.257.4 探针逐字实证,probe-plan-final-frame.mjs):
+ *   1. plan-mode turn 里模型调 ExitPlanMode → 引擎 park:done 帧 `status:"needs_review"` +
+ *      `checkpointGate:{kind:"plan_review",reason:"ExitPlanMode"}` + `errorCode:"review.pending"`;
+ *      plan 文本已由 ExitPlanMode tool_end 渲染在转录(fence 块),checkpoint 落 FileCheckpointStore。
+ *   2. 壳(本模块,runStream done 分支调用)合成一个 QuestionFrame 借 AskUserQuestion overlay 弹
+ *      审批卡(core 拍板:不新造 live question 帧,壳自绘)——合成 id `plan-review:<taskId>` 经
+ *      liveQuestionStore 的 LOCAL responder 拦截,绝不会打到引擎的 /v1/questions(那里 404)。
+ *   3. 决断 → POST /v1/assistant/tasks/:taskId/plan_review `{decision:"approve"|"reject"}`——
+ *      resume 是 SYNC 驱动到终态的(实证 200 `{taskId,sessionId,status:"completed"}`,可能分钟级),
+ *      所以 fire 后卡片即关,完成后经 enqueuePendingNotification 入队一个 isMeta turn:模型收到
+ *      resume 终态,自然接续汇报(approve 后"继续干活"的 CC 体验由引擎侧 resume 已完成,这里是
+ *      结果呈现)。reject 同构(引擎丢 plan 保持 plan 语境)。
+ *
+ * 挂账(诚实边界):approve 后壳本地的 plan-mode footer 徽章不自动退(CC 会退)——退 mode 的
+ * app-state seam 不在本模块可达面,记 rc.47 接 REPL 层;engine 侧 handsReadOnly 已由 resume 处理。
+ */
+import { publishQuestionFrame, registerLocalQuestionResponder, } from '../liveQuestionStore.js';
+import { hostLog } from '../host.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireTarget } from '../engineWireTarget.js';
+import { enqueuePlanReviewOutcome } from '../notifications.js';
+/** resume 是 SYNC 驱动到终态的(可能分钟级)——原 raw fetch 无超时;SDK Transport 恒有每请求
+ *  超时,取 6h 宽上界(诚实预算:超过它基本是引擎僵死,超时文案与网络失败同走 outcome 通知)。 */
+const PLAN_REVIEW_RESUME_TIMEOUT_MS = 6 * 60 * 60_000;
+const APPROVE_LABEL = 'Yes, approve and run the plan';
+const REJECT_LABEL = 'No, reject it (keep planning)';
+/** done 帧的 plan_review park 形状(结构性读,别的终态一律 false)。 */
+export function isPlanReviewPark(result) {
+    const r = result;
+    return (!!r &&
+        r.status === 'needs_review' &&
+        r.checkpointGate?.kind === 'plan_review' &&
+        typeof r.taskId === 'string' &&
+        r.taskId.length > 0);
+}
+/**
+ * Arm the approval card for a parked plan_review (call with the RAW done.result). Returns true when
+ * armed (live path + shape matched); false = caller renders the terminal as usual. Fail-soft: any
+ * error inside must never break the stream drain.
+ */
+export function armPlanReviewApproval(result) {
+    try {
+        if (!isPlanReviewPark(result))
+            return false;
+        if (!engineWireTarget())
+            return false;
+        const { taskId } = result;
+        const questionId = `plan-review:${taskId}`;
+        registerLocalQuestionResponder(questionId, async (_id, answer) => {
+            const selected = answer?.answers?.[0]?.selected?.[0];
+            const decision = selected === APPROVE_LABEL ? 'approve' : 'reject';
+            // fire-and-forget:resume 同步驱动到终态可能分钟级,不能挂住 overlay;结果经 queue 通知回来
+            void decidePlanReview(taskId, decision);
+            return { ok: true };
+        });
+        publishQuestionFrame({
+            type: 'question',
+            questionId,
+            questions: [
+                {
+                    header: 'Plan review',
+                    question: 'The plan is ready for review. Approve it and start the implementation?',
+                    options: [
+                        { label: APPROVE_LABEL, description: 'Resume the task now and execute the plan (runs to completion engine-side)' },
+                        { label: REJECT_LABEL, description: 'Discard this plan and stay in plan mode to refine it' },
+                    ],
+                    multiSelect: false,
+                },
+            ],
+        });
+        hostLog('debug', `planReviewWire: approval card armed for parked plan (task ${taskId})`);
+        return true;
+    }
+    catch (e) {
+        hostLog('debug', `planReviewWire: arm failed (fail-soft): ${String(e)}`);
+        return false;
+    }
+}
+/** POST the decision; on settle enqueue an isMeta turn so the model reports the resume outcome.
+ *  SDK 宪法迁移批:SDK 0.0.52 assistant.planReview verb(同 wire `POST /v1/assistant/tasks/:id/
+ *  plan_review` 同 body {decision})——raw fetch 退役。错误模型:非 2xx 抛 APIError(message =
+ *  server body.error 原文)→ 同款「HTTP <status> <error>」outcome 文案;网络失败走原「could not
+ *  reach the engine」臂。 */
+export async function decidePlanReview(taskId, decision) {
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return;
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+        timeoutMs: PLAN_REVIEW_RESUME_TIMEOUT_MS,
+    });
+    if (!client)
+        return;
+    let outcome = '';
+    try {
+        const body = await client.assistant.planReview(taskId, { decision });
+        hostLog('debug', `planReviewWire: ${decision} → ok ${JSON.stringify(body).slice(0, 200)}`);
+        outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${body?.status ?? 'unknown'}.`;
+    }
+    catch (e) {
+        // APIError 判型走 status duck-check(sseIdleTriage 同款纪律:双包时 instanceof 会分叉)。
+        const status = e?.status;
+        if (typeof status === 'number') {
+            const msg = e instanceof Error ? e.message : String(e);
+            hostLog('debug', `planReviewWire: ${decision} → ${status} ${msg.slice(0, 200)}`);
+            outcome = `The plan_review decision failed: HTTP ${status} ${msg}`.trim();
+        }
+        else {
+            outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
+        }
+    }
+    try {
+        enqueuePlanReviewOutcome(`<plan-review-outcome>\n${outcome}${decision === 'approve' ? `\nUse TaskOutput("${taskId}") if you need the resumed task's full output, then give the user a brief report of what was done.` : '\nBriefly acknowledge to the user that the plan was rejected and continue planning.'}\n</plan-review-outcome>`);
+    }
+    catch (e) {
+        hostLog('debug', `planReviewWire: outcome enqueue failed: ${String(e)}`);
+    }
+}

package/dist/hitl/toolApprovalWire.d.ts

@@ -0,0 +1,126 @@
+import { type HitlClientLike } from './hitlBridge.js';
+/** fs 写权限 gate 判定:未来的一等 kind(tool_approval)或按 toolName(server 桥首批=fs 写三件,
+ *  [820] 表)。AskUserQuestion 永不进这里(ask 桥先判)。 */
+export declare function isFsApprovalGate(gate: {
+    kind?: unknown;
+    toolName?: unknown;
+} | undefined | null): boolean;
+export declare function toolNameIsFsWrite(name: string): boolean;
+export type FsApprovalOutcome = {
+    kind: 'decided';
+    gatedCallId?: string;
+    denied?: boolean;
+} | {
+    kind: 'aborted';
+    gatedCallId?: string;
+} | {
+    kind: 'failed';
+    gatedCallId?: string;
+    reason: string;
+};
+/** 本桥消费的 wire 面(liveHitlAskWire 的 AskGateWireDeps 同形切片,mock 可注入)。 */
+export interface FsApprovalWireDeps {
+    client: HitlClientLike;
+}
+/** 结构等值(键序无关深比较)——updatedInput「真编辑过」判定用。zod parse 会产新引用与重排,
+ *  引用比较/JSON.stringify 串比较都会假报「编辑过」。 */
+export declare function structurallyEqual(a: unknown, b: unknown): boolean;
+/** 三选卡的原始决断(vendor 卡的三个选项 + abort + 表面失败)。allow_session=第 2 项
+ *  (vendor 产出非空 permissionUpdates:setMode acceptEdits / cwd 外 addDirectories)。 */
+export type ApprovalCardDecision = {
+    kind: 'allow';
+    allowSession: boolean;
+    updatedInput?: unknown;
+} | {
+    kind: 'deny';
+} | {
+    kind: 'aborted';
+} | {
+    kind: 'failed';
+    reason: string;
+};
+/** 卡口的入参 —— cli `surfaceApprovalCard` 的 `req` 逐字。 */
+export interface ApprovalCardRequest {
+    toolName: string;
+    args: object;
+    callKey: string;
+    signal?: AbortSignal;
+    /** 后台子代 ask 的归属徽章(卡头 `· @name`,CC swarm workerBadge 原生位;宿主 ask 恒缺席)。 */
+    workerBadge?: {
+        name: string;
+        color: string;
+    };
+    /** wire 层降级说明(卡 content 上方 dim 行,ToolUseConfirm.wireNote 超集位)——argsOmitted 等
+     *  不可注入 args 的提示走这里([1543]③ 记账的 note 位,2026-07-23 落位)。 */
+    wireNote?: string;
+}
+/**
+ * 🔴 **拆缝口** —— 弹「三选卡」并等人的决断。壳 = vendored CC `PermissionRequest`;
+ * 桌面/web = 各自的模态。缺席 ⇒ 两条决断腿都 `failed`(= 壳原文 print/non-REPL 的同一条路)。
+ */
+export type ApprovalCardPort = (req: ApprovalCardRequest) => Promise<ApprovalCardDecision>;
+/** 装卡口(传 null 卸)。返回还原函数。 */
+export declare function installApprovalCardPort(port: ApprovalCardPort | null): () => void;
+/** 🔴 宿主自检:恒应为 0。非 0 = 有 gate 到达时卡口不在,那次审批走了 fail-closed 路径。 */
+export declare function approvalCardPortMisses(): number;
+/** 卡口在不在(壳原文 `getLeaderToolUseConfirmQueue()` 那个存在性判据的等价物)。 */
+export declare function hasApprovalCardPort(): boolean;
+/** 测试钩:卸口 + 清计数(只卸口不清计数会让「未装配时 misses 为 0」的断言恒假 —— host.ts 同款教训)。 */
+export declare function _resetApprovalCardPortForTest(): void;
+/**
+ * 共享卡面:弹 vendored CC 三选卡(PermissionRequest)→ 等用户决断。两条腿共用:
+ *  - 旧 durable park 腿(surfaceFsApprovalAndDecide → HitlBridge.decideTool)
+ *  - 新同步帧腿(server 1.191 `tool_approval` 帧 → POST /v1/tool-approvals/:id/respond)
+ * 决断落地(decide/respond)由调用方做;卡的渲染/键行为/本地 permissionUpdates
+ * (accept-session 升 intent,[816] 壳侧承诺② —— 与决断通道无关,两腿都要)由**宿主卡口**做。
+ */
+export declare function surfaceApprovalCard(req: ApprovalCardRequest): Promise<ApprovalCardDecision>;
+/**
+ * 弹 CC 三选卡 → 等决断 → 经 HitlBridge decide(durable park 腿,server 桥前的 checkpointGate 面;
+ * 合成单测/旧引擎兜底保留)。decide 成功即引擎驱到下一状态(sync);调用方随后 attach runs.events
+ * 续流(与 ask 桥完全同 loop)。
+ *
+ * @param argsByCall tool_start.args(toolCallId → args)——题干/diff 的一手源;缺则 pending.input。
+ */
+export declare function surfaceFsApprovalAndDecide(deps: FsApprovalWireDeps, taskId: string, argsByCall: Map<string, unknown>, signal?: AbortSignal): Promise<FsApprovalOutcome>;
+/** server 包 src/tool-approval.ts 头注的帧契约(redactDeep + 16KiB 帽;超帽 argsOmitted 仍出帧)。 */
+export interface ToolApprovalFrame {
+    type: 'tool_approval' | 'tool_approval_complete';
+    approvalId: string;
+    toolName?: string;
+    message?: string;
+    args?: unknown;
+    argsOmitted?: boolean;
+    outcome?: 'allowed' | 'denied' | 'expired';
+    /** server 1.258([1535] 审批链,[1549]①3 判别式定谳):**在场即子代**——server 只对后台子代
+     *  lane 的 ask 出此键(宿主自身 ask 的 sourceTaskId=sessionId 已在 server 侧收口不上帧)。
+     *  ⚠️ 值=子代 sessionId 非 a… handle(fence 实测 2026-07-23)——不是 fleet 台账键。 */
+    sourceTaskId?: string;
+    /** core 1.378 RB-39②([1550]):Runner 填充的只读显式判别键——委派子代 gate 的 ask 恒带,
+     *  受信 internals 事实不可伪造。在场即子代(优先于 sourceTaskId 权宜式);候 server 帧透传班车。 */
+    fromSubagent?: boolean;
+    /** core 1.378 RB-39②:展示身份(UNTRUSTED-for-display,server redact 后上帧)——徽章名一手源。 */
+    sourceAgentName?: string;
+}
+/** 子代帧判别:显式键 fromSubagent(core 1.378 RB-39②)优先;缺席退 sourceTaskId 在场性权宜式
+ *  (server 1.258 [1549]①3,旧代际兼容)。 */
+export declare function isFromSubagent(frame: ToolApprovalFrame): boolean;
+/** 三选卡决断 → respond 端点的 wire 枚举(server parseToolApprovalDecision)。 */
+export type ToolApprovalRespondDecision = 'allow' | 'allow_session' | 'deny';
+/** POST /v1/tool-approvals/:id/respond 的注入面(liveClient 提供;SDK 0.0.46 无此资源,raw fetch)。 */
+export type RespondToolApprovalFn = (approvalId: string, decision: ToolApprovalRespondDecision, opts?: {
+    signal?: AbortSignal;
+    updatedInput?: unknown;
+}) => Promise<void>;
+/** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名;非 AgentEvent arm)。 */
+export declare function isToolApprovalFrame(ev: unknown): ev is ToolApprovalFrame;
+/**
+ * 消费一张 `tool_approval` 帧:弹三选卡 → respond。引擎此刻同步阻塞在本帧上(fail-closed 全腿:
+ * TTL 5min/abort/emit 失败⇒deny),所以本函数 await 卡决断是安全的(流上不会再来别的内容帧)。
+ *
+ * fail-closed:卡面不可用(print 模式无卡口/enqueue 失败)⇒ 立刻 respond deny,不让引擎
+ * 干等 TTL。respond 自身失败(404=已过期/settled)⇒ 'unresolved'(诚实放行后续帧,引擎已自决)。
+ *
+ * @returns 用户(或 fail-closed)落定的决断;'unresolved' = respond 没送达。
+ */
+export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal): Promise<ToolApprovalRespondDecision | 'unresolved'>;

package/dist/hitl/toolApprovalWire.js

@@ -0,0 +1,263 @@
+import { HitlBridge } from './hitlBridge.js';
+import { hostLog } from '../host.js';
+import { readEngineActiveBgTasks } from '../fleet/fleetLedger.js';
+/** fs 写权限 gate 判定:未来的一等 kind(tool_approval)或按 toolName(server 桥首批=fs 写三件,
+ *  [820] 表)。AskUserQuestion 永不进这里(ask 桥先判)。 */
+export function isFsApprovalGate(gate) {
+    if (!gate)
+        return false;
+    if (gate.kind === 'tool_approval')
+        return true;
+    return typeof gate.toolName === 'string' && toolNameIsFsWrite(gate.toolName);
+}
+export function toolNameIsFsWrite(name) {
+    const n = name.replace(/[\s_-]+/g, '').toLowerCase();
+    return (n === 'write' || n === 'filewrite' || n === 'edit' || n === 'fileedit' || n === 'multiedit' || n === 'notebookedit');
+}
+/** 结构等值(键序无关深比较)——updatedInput「真编辑过」判定用。zod parse 会产新引用与重排,
+ *  引用比较/JSON.stringify 串比较都会假报「编辑过」。 */
+export function structurallyEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null || typeof a !== 'object')
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => structurallyEqual(v, b[i]));
+    }
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length)
+        return false;
+    return ka.every(k => structurallyEqual(a[k], b[k]));
+}
+let cardPort = null;
+let cardPortMisses = 0;
+/** 装卡口(传 null 卸)。返回还原函数。 */
+export function installApprovalCardPort(port) {
+    const prev = cardPort;
+    cardPort = port;
+    return () => {
+        cardPort = prev;
+    };
+}
+/** 🔴 宿主自检:恒应为 0。非 0 = 有 gate 到达时卡口不在,那次审批走了 fail-closed 路径。 */
+export function approvalCardPortMisses() {
+    return cardPortMisses;
+}
+/** 卡口在不在(壳原文 `getLeaderToolUseConfirmQueue()` 那个存在性判据的等价物)。 */
+export function hasApprovalCardPort() {
+    return cardPort !== null;
+}
+/** 测试钩:卸口 + 清计数(只卸口不清计数会让「未装配时 misses 为 0」的断言恒假 —— host.ts 同款教训)。 */
+export function _resetApprovalCardPortForTest() {
+    cardPort = null;
+    cardPortMisses = 0;
+}
+/**
+ * 共享卡面:弹 vendored CC 三选卡(PermissionRequest)→ 等用户决断。两条腿共用:
+ *  - 旧 durable park 腿(surfaceFsApprovalAndDecide → HitlBridge.decideTool)
+ *  - 新同步帧腿(server 1.191 `tool_approval` 帧 → POST /v1/tool-approvals/:id/respond)
+ * 决断落地(decide/respond)由调用方做;卡的渲染/键行为/本地 permissionUpdates
+ * (accept-session 升 intent,[816] 壳侧承诺② —— 与决断通道无关,两腿都要)由**宿主卡口**做。
+ */
+export function surfaceApprovalCard(req) {
+    if (cardPort === null) {
+        cardPortMisses++;
+        return Promise.resolve({
+            kind: 'failed',
+            reason: 'no approval card port installed (print/non-REPL mode, or host forgot installApprovalCardPort)',
+        });
+    }
+    return cardPort(req);
+}
+/**
+ * 弹 CC 三选卡 → 等决断 → 经 HitlBridge decide(durable park 腿,server 桥前的 checkpointGate 面;
+ * 合成单测/旧引擎兜底保留)。decide 成功即引擎驱到下一状态(sync);调用方随后 attach runs.events
+ * 续流(与 ask 桥完全同 loop)。
+ *
+ * @param argsByCall tool_start.args(toolCallId → args)——题干/diff 的一手源;缺则 pending.input。
+ */
+export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signal) {
+    if (!hasApprovalCardPort()) {
+        cardPortMisses++;
+        return { kind: 'failed', reason: 'no approval card port installed (print/non-REPL mode)' };
+    }
+    // pending 行 = gate 的权威源 + D-1 绑定 surface(与 ask 桥同姿势)。
+    let pending;
+    try {
+        const rows = await deps.client.approvals.list(signal ? { signal } : undefined);
+        pending =
+            rows.find(r => r.taskId === taskId && typeof r.toolName === 'string' && toolNameIsFsWrite(r.toolName)) ??
+                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;
+    const toolName = typeof pending.toolName === 'string' ? pending.toolName : '';
+    // 工具入参:优先流上 tool_start.args(完整、零额外语义);缺则 pending.input(service 已 redact+限长
+    // ——大 Write 的 content 可能被截,对话框 diff 退化但仍可决断)。
+    const args = (gatedCallId !== undefined ? argsByCall.get(gatedCallId) : undefined) ??
+        pending.input ??
+        {};
+    if (typeof args !== 'object' || args === null) {
+        return { kind: 'failed', gatedCallId, reason: 'gate has no tool input payload' };
+    }
+    const bridge = new HitlBridge(deps.client, taskId);
+    const callKey = gatedCallId ?? taskId;
+    const card = await surfaceApprovalCard({
+        toolName,
+        args,
+        callKey,
+        ...(signal ? { signal } : {}),
+    });
+    switch (card.kind) {
+        case 'failed':
+            return { kind: 'failed', gatedCallId, reason: card.reason };
+        case 'aborted':
+            // turn 被中断(Esc/Ctrl+C):cancel-by-deny(contract/04 §2.4),best-effort fire-and-forget。
+            void bridge.decideTool({ decision: 'deny', reason: 'Interrupted by user' }, gatedCallId).catch(() => { });
+            return { kind: 'aborted', gatedCallId };
+        case 'allow':
+            try {
+                // accept-session(三选第 2 项)在 durable-park 腿的引擎侧半场:decide 带 remember:"session"
+                // (server 1.191 approvalExemptionStore.grant)→ 同 session 该工具后续 ask 免 park 免卡
+                // (frame 腿的 allow_session 对偶)。老 server 不识别 remember ⇒ 400 —— 回退纯 approve
+                // (本地 acceptEdits intent 已升,下一 turn 起 permissionMode 就位,同 turn 内可能再弹卡=
+                // 修复前行为,fail-soft 不更糟)。
+                if (card.allowSession) {
+                    try {
+                        await bridge.decideTool({ decision: 'approve', remember: 'session', ...(card.updatedInput !== undefined ? { updatedInput: card.updatedInput } : {}) }, gatedCallId, signal ? { signal } : undefined);
+                        return { kind: 'decided', gatedCallId };
+                    }
+                    catch (e) {
+                        hostLog('debug', `liveToolApprovalWire: decide(approve+remember) failed (${String(e)}) — falling back to plain approve`);
+                    }
+                }
+                await bridge.decideTool({ decision: 'approve', ...(card.updatedInput !== undefined ? { updatedInput: card.updatedInput } : {}) }, gatedCallId, signal ? { signal } : undefined);
+                return { kind: 'decided', gatedCallId };
+            }
+            catch (e) {
+                return { kind: 'failed', gatedCallId, reason: `decide(approve) failed: ${String(e)}` };
+            }
+        case 'deny':
+            try {
+                await bridge.decideTool({ decision: 'deny', reason: 'The user rejected this tool use' }, gatedCallId, signal ? { signal } : undefined);
+                return { kind: 'decided', gatedCallId, denied: true };
+            }
+            catch (e) {
+                return { kind: 'failed', gatedCallId, reason: `decide(deny) failed: ${String(e)}` };
+            }
+    }
+}
+/** 子代帧判别:显式键 fromSubagent(core 1.378 RB-39②)优先;缺席退 sourceTaskId 在场性权宜式
+ *  (server 1.258 [1549]①3,旧代际兼容)。 */
+export function isFromSubagent(frame) {
+    if (frame.fromSubagent === true)
+        return true;
+    return typeof frame.sourceTaskId === 'string' && frame.sourceTaskId.length > 0;
+}
+/** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名;非 AgentEvent arm)。 */
+export function isToolApprovalFrame(ev) {
+    const e = ev;
+    return (!!e &&
+        (e.type === 'tool_approval' || e.type === 'tool_approval_complete') &&
+        typeof e.approvalId === 'string' &&
+        e.approvalId.length > 0);
+}
+/** 从 gate 的 ask 文案(core fs-write-gate-policy `approve write to "<path>"?`)兜出 path——argsOmitted
+ *  且流上无 tool_start.args 时的最后退化(卡仍可弹,diff 退化为空写)。 */
+function pathFromGateMessage(message) {
+    const m = typeof message === 'string' ? /"([^"]+)"/.exec(message) : null;
+    return m?.[1];
+}
+/** 子代审批帧的归属徽章([1535] cli 半场):名一手源=帧上 sourceAgentName(core 1.378 RB-39②
+ *  显式展示身份,server redact 后透传,候 server 班车到货即亮);缺席退 fleet 在飞台账行名
+ *  (`${agentType}: ${description}` 合成形;⚠️ sourceTaskId 实测=子代 sessionId 非 a… handle,
+ *  台账按 handle 键常 miss);再退 sourceTaskId 短形——徽章永在场,归属永不静默。截 32c 防破行。
+ *  🔴 搬迁差分:cli 用延迟 require 拉 `fleetClient.js`(理由=纯 wire 模块不背 fleet 图冷启动);
+ *  在包内 fleet 台账就是同一个包的模块,改静态 import。try/catch 保留(台账不可用的兜底那一支)。 */
+function subagentBadgeFor(frame) {
+    let name = typeof frame.sourceAgentName === 'string' && frame.sourceAgentName.length > 0 ? frame.sourceAgentName : '';
+    if (!name && typeof frame.sourceTaskId === 'string' && frame.sourceTaskId.length > 0) {
+        name = frame.sourceTaskId;
+        try {
+            const row = readEngineActiveBgTasks().tasks.find(t => t.id === frame.sourceTaskId);
+            if (typeof row?.name === 'string' && row.name.length > 0)
+                name = row.name;
+        }
+        catch {
+            /* 台账不可用 → taskId 短形兜底 */
+        }
+    }
+    if (!name)
+        name = 'background agent';
+    if (name.length > 32)
+        name = `${name.slice(0, 31)}…`;
+    return { name, color: 'cyan' };
+}
+/**
+ * 消费一张 `tool_approval` 帧:弹三选卡 → respond。引擎此刻同步阻塞在本帧上(fail-closed 全腿:
+ * TTL 5min/abort/emit 失败⇒deny),所以本函数 await 卡决断是安全的(流上不会再来别的内容帧)。
+ *
+ * fail-closed:卡面不可用(print 模式无卡口/enqueue 失败)⇒ 立刻 respond deny,不让引擎
+ * 干等 TTL。respond 自身失败(404=已过期/settled)⇒ 'unresolved'(诚实放行后续帧,引擎已自决)。
+ *
+ * @returns 用户(或 fail-closed)落定的决断;'unresolved' = respond 没送达。
+ */
+export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamArgs, signal) {
+    const toolName = typeof frame.toolName === 'string' ? frame.toolName : 'Write';
+    // 工具入参:流上 tool_start.args(完整一手源)> 帧 args(redacted+16KiB 帽)> message 兜 path。
+    let args = streamArgs !== undefined && streamArgs !== null
+        ? streamArgs
+        : frame.args !== undefined && frame.args !== null
+            ? frame.args
+            : undefined;
+    let wireNote;
+    if (typeof args !== 'object' || args === null) {
+        // [1543]③:args>16KiB 超帽时 server 出帧带 argsOmitted:true 而无 args。卡面提示走
+        // ToolUseConfirm.wireNote 超集位(2026-07-23 落位,清 [1543]③ 记账)——dim 行不进 args,
+        // 不会随「编辑并批准」的 updatedInput 转发污染工具入参。
+        if (frame.argsOmitted === true) {
+            wireNote = 'tool arguments exceeded the wire cap and were omitted — the diff below is reconstructed from the gate message, not the full payload';
+            hostLog('debug', `liveToolApprovalWire: frame ${frame.approvalId} args omitted (>16KiB wire cap) — card falls back to message-derived path`);
+        }
+        const p = pathFromGateMessage(frame.message);
+        args = p !== undefined ? { file_path: p } : {};
+    }
+    // [1535]:子代的写审批浮到宿主卡(server 1.258 broker 腿)——卡头渲归属徽章(`· @name`),
+    // 用户知道在替谁批。判别=fromSubagent 显式键(core 1.378)优先、sourceTaskId 在场性权宜式兜底;
+    // 宿主自身 ask 两键恒缺席=徽章缺席,卡形不变。
+    const card = await surfaceApprovalCard({
+        toolName,
+        args: args,
+        callKey: `hitl-frame:${frame.approvalId}`,
+        ...(signal ? { signal } : {}),
+        ...(isFromSubagent(frame) ? { workerBadge: subagentBadgeFor(frame) } : {}),
+        ...(wireNote !== undefined ? { wireNote } : {}),
+    });
+    const decision = card.kind === 'allow' ? (card.allowSession ? 'allow_session' : 'allow') : 'deny';
+    if (card.kind === 'failed') {
+        hostLog('debug', `liveToolApprovalWire: approval card unavailable (${card.reason}) — fail-closed deny for ${frame.approvalId}`);
+    }
+    try {
+        // abort 后的 deny 仍要送达(引擎侧同款 cancel-by-deny)——不带已 aborted 的 signal。
+        await respond(frame.approvalId, decision, {
+            ...(signal && !signal.aborted ? { signal } : {}),
+            ...(card.kind === 'allow' && card.updatedInput !== undefined ? { updatedInput: card.updatedInput } : {}),
+        });
+        return decision;
+    }
+    catch (e) {
+        hostLog('debug', `liveToolApprovalWire: respond(${decision}) failed for ${frame.approvalId}: ${String(e)} — engine self-settles (TTL/abort)`);
+        return 'unresolved';
+    }
+}

package/dist/index.d.ts

@@ -5,6 +5,20 @@
  * 沿革:@sema-agent/wire-cc-adapter 0.1.0 = seam 类型 + id 确定性派生 + 首批踩坑纯函数;
  * 0.1.2(#52a)= adapt() 管线首批(纯投影臂全落 + 壳态耦合臂投影成 ChromeEvent + 差分守卫);
  * 0.2.0 = 迁入 sema-client-core 独立仓并改名(旧 npm 名 deprecate 指本包);
+ * 0.9.0 = **B7 批**(设计稿 §3 B7「完成事件单一权威 + HITL」):
+ *   ① **HITL 族四件**(新目录 `hitl/`):`hitlBridge`(整搬,🔴 **D-1 两元组 verbatim 回显**
+ *      与「409 绝不自动重试」两段**逐字节**搬,pure 门 B7 段用冻结字面量 + 壳树双向对拍 +
+ *      毒化行为口径三重钉)· `toolApprovalWire`(**拆**:判定/编排进包,三选卡本体经
+ *      `ApprovalCardPort` 留端)· `askGateWire`(整搬;footer 通知与 Recent Denials 记账经
+ *      `HitlHostSurface` 留端)· `planReviewWire`(整搬,**第七份 `wireConfig()` 收编闭合**)。
+ *   ② **完成事件族 T2/T3**:`taskNotificationDedupKeyFromWire`(裸 wire 载荷键形)+
+ *      `parseTranscriptNotificationSeeds` / `seedTaskNotificationDedupFromTranscript`
+ *      (#63 resume 回植的 XML 反解)搬入 `notifications.ts`。**P1-3 未到货 ⇒ 只搬不删**,
+ *      四道去重原样;退役条件登记进 `compensations.ts`(T1/T2/T3/T25/T53 五条)。
+ *   ③ **`approvals.stream()` 换轮询**(census G20):`hitl/approvalsFeed.ts` —— SDK 原生推送优先、
+ *      断流/无端点**回落轮询**的韧性臂保留;两条腿都收敛到「非 heartbeat 事件 ⇒ 重取权威
+ *      `list()`」(SDK 自述 payload 是 FORWARD-DRAFT,绝不信未确认的 delta 形)。
+ *   🆕 队列口新增**可选**动词 `enqueueMetaPrompt`(plan_review 结局回植;既有宿主不破)。
  * 0.8.0 = **B6 批**(设计稿 §3 B6,分两轮落):
  *   ——【前半,fleet/子代身份族】fleetClient 沿 §2.5 拆两半(帧体归库、连接归端):
  *   `fleet/fleetProjection` + `fleet/fleetLedger` · 子代 wire 族六件(`subagent/*`)·
@@ -80,6 +94,12 @@
  *     · liveInitToolFace.ts(`cached`)—— 两份只是多探一次 `/v1/capabilities/scenarios/:name`,
  *       **不是**静默失效;仍登记,免得下次读表的人以为它没状态。
  *     · model/providerPresets.ts(`presetIndexCache`)—— 由不可变 JSON 派生的纯 memo,两份只费内存。
+ *   —— B7 新增(两条都是**装在一份、读另一份 = 面直接不工作**,比台账分裂更响):
+ *     · **hitl/toolApprovalWire.ts**(`cardPort` + `cardPortMisses`)—— 写方 = 宿主启动装配
+ *       `installApprovalCardPort()`,读方 = 两条决断腿。两份 ⇒ `hasApprovalCardPort()` 恒 false ⇒
+ *       **每一张写权限 gate 都走 fail-closed deny(卡根本不弹)**,而宿主那边"我装了啊"。
+ *     · **hitl/askGateWire.ts**(`hostSurface` + `hostSurfaceMisses`)—— 写方 = 宿主装配,
+ *       读方 = cancel-deny warn 与分类器 deny 记账。两份 ⇒ 那一行 warn 与 Recent Denials 全丢。
  * 🔴 **宿主装配**——B4 起总入口是 `installHost({log,probe,queue,timers,settings,fs,session})`
  *   (`installNotificationQueuePort()` 仍是队列的真源出口,`installHost({queue})` 直通它,两者不分裂);
  *   自检口 `hostPortMisses()` 恒应为空对象,非空 = 有口漏装、对应的面已在静默失效。
@@ -174,4 +194,9 @@ export * from './workflowClient.js';
 export * from './hooksWireCaps.js';
 export * from './liveInitToolFace.js';
 export * from './model/providerPresets.js';
+export * from './hitl/hitlBridge.js';
+export * from './hitl/toolApprovalWire.js';
+export * from './hitl/askGateWire.js';
+export * from './hitl/planReviewWire.js';
+export * from './hitl/approvalsFeed.js';
 export * from './compensations.js';

package/dist/index.js

@@ -5,6 +5,20 @@
  * 沿革:@sema-agent/wire-cc-adapter 0.1.0 = seam 类型 + id 确定性派生 + 首批踩坑纯函数;
  * 0.1.2(#52a)= adapt() 管线首批(纯投影臂全落 + 壳态耦合臂投影成 ChromeEvent + 差分守卫);
  * 0.2.0 = 迁入 sema-client-core 独立仓并改名(旧 npm 名 deprecate 指本包);
+ * 0.9.0 = **B7 批**(设计稿 §3 B7「完成事件单一权威 + HITL」):
+ *   ① **HITL 族四件**(新目录 `hitl/`):`hitlBridge`(整搬,🔴 **D-1 两元组 verbatim 回显**
+ *      与「409 绝不自动重试」两段**逐字节**搬,pure 门 B7 段用冻结字面量 + 壳树双向对拍 +
+ *      毒化行为口径三重钉)· `toolApprovalWire`(**拆**:判定/编排进包,三选卡本体经
+ *      `ApprovalCardPort` 留端)· `askGateWire`(整搬;footer 通知与 Recent Denials 记账经
+ *      `HitlHostSurface` 留端)· `planReviewWire`(整搬,**第七份 `wireConfig()` 收编闭合**)。
+ *   ② **完成事件族 T2/T3**:`taskNotificationDedupKeyFromWire`(裸 wire 载荷键形)+
+ *      `parseTranscriptNotificationSeeds` / `seedTaskNotificationDedupFromTranscript`
+ *      (#63 resume 回植的 XML 反解)搬入 `notifications.ts`。**P1-3 未到货 ⇒ 只搬不删**,
+ *      四道去重原样;退役条件登记进 `compensations.ts`(T1/T2/T3/T25/T53 五条)。
+ *   ③ **`approvals.stream()` 换轮询**(census G20):`hitl/approvalsFeed.ts` —— SDK 原生推送优先、
+ *      断流/无端点**回落轮询**的韧性臂保留;两条腿都收敛到「非 heartbeat 事件 ⇒ 重取权威
+ *      `list()`」(SDK 自述 payload 是 FORWARD-DRAFT,绝不信未确认的 delta 形)。
+ *   🆕 队列口新增**可选**动词 `enqueueMetaPrompt`(plan_review 结局回植;既有宿主不破)。
  * 0.8.0 = **B6 批**(设计稿 §3 B6,分两轮落):
  *   ——【前半,fleet/子代身份族】fleetClient 沿 §2.5 拆两半(帧体归库、连接归端):
  *   `fleet/fleetProjection` + `fleet/fleetLedger` · 子代 wire 族六件(`subagent/*`)·
@@ -80,6 +94,12 @@
  *     · liveInitToolFace.ts(`cached`)—— 两份只是多探一次 `/v1/capabilities/scenarios/:name`,
  *       **不是**静默失效;仍登记,免得下次读表的人以为它没状态。
  *     · model/providerPresets.ts(`presetIndexCache`)—— 由不可变 JSON 派生的纯 memo,两份只费内存。
+ *   —— B7 新增(两条都是**装在一份、读另一份 = 面直接不工作**,比台账分裂更响):
+ *     · **hitl/toolApprovalWire.ts**(`cardPort` + `cardPortMisses`)—— 写方 = 宿主启动装配
+ *       `installApprovalCardPort()`,读方 = 两条决断腿。两份 ⇒ `hasApprovalCardPort()` 恒 false ⇒
+ *       **每一张写权限 gate 都走 fail-closed deny(卡根本不弹)**,而宿主那边"我装了啊"。
+ *     · **hitl/askGateWire.ts**(`hostSurface` + `hostSurfaceMisses`)—— 写方 = 宿主装配,
+ *       读方 = cancel-deny warn 与分类器 deny 记账。两份 ⇒ 那一行 warn 与 Recent Denials 全丢。
  * 🔴 **宿主装配**——B4 起总入口是 `installHost({log,probe,queue,timers,settings,fs,session})`
  *   (`installNotificationQueuePort()` 仍是队列的真源出口,`installHost({queue})` 直通它,两者不分裂);
  *   自检口 `hostPortMisses()` 恒应为空对象,非空 = 有口漏装、对应的面已在静默失效。
@@ -217,6 +237,22 @@ export * from './liveInitToolFace.js';
 //    来源。表不在包里,那条中央规则在 web/桌面上恒拿不到 cap ⇒ 对 deepseek-chat(8192)这类模型
 //    超发 ⇒ 网关 400。搬迁期与壳树两份 JSON 由 pure 门的 byte-identity 断言锁住。
 export * from './model/providerPresets.js';
+// ── B7 批:HITL 族(2026-07-27,设计稿 §3 B7)────────────────────────────────────────────────
+// 🔴 `hitl/hitlBridge.ts` 里的 **D-1 两元组 verbatim 回显**是安全不变量(`bindingOf` 绝不重算
+//    hash;409 ⇒ `HitlSafetyError('binding_mismatch')` 绝不自动重试)—— pure 门 B7 段做**字节级**
+//    断言,改一个字符就红。
+// 🔴 两个新拆缝口(缺席都计 miss,宿主自检恒应为 0):
+//    · `installApprovalCardPort` —— 三选卡本体(vendored CC `PermissionRequest` / 桌面模态);
+//    · `installHitlHostSurface` —— footer 通知与 /permissions Recent Denials 记账(端状态形状)。
+// 🔴 单实例:`toolApprovalWire` 的卡口槽 + `askGateWire` 的宿主面槽是 module 级变量;两份实例 ⇒
+//    装在一份、读另一份 = 每张 gate 都走 fail-closed deny(卡根本不弹)。
+export * from './hitl/hitlBridge.js';
+export * from './hitl/toolApprovalWire.js';
+export * from './hitl/askGateWire.js';
+export * from './hitl/planReviewWire.js';
+// B7 ③(census G20,**行为改动**不是搬迁):pending-approvals 推送 feed(stream 优先 / 断流回落
+// 轮询 / 定期再试)。🔴 它**不替换** D-1 的取件 —— 那三处必须继续走权威 `list()`(见文件头)。
+export * from './hitl/approvalsFeed.js';
 // ── B6 余项③(P5):补偿层登记表 —— 把「哪条补偿拆了、拆缝对面是谁、什么时候能退休」做成数据。
 // 🔴 它**不是** `ADAPTER_DIVERGENCES`(那张表说的是 adapt 与 cli 行为不同的地方;本表里的东西
 //    两侧行为相同)。自检口 `compensationSplitViolations()` 恒应为空。