@sema-agent/client-core 0.19.0 → 0.20.1

package/dist/hitl/hitlBridge.js

@@ -8,6 +8,9 @@ export class HitlSafetyError extends Error {
     constructor(message, 
     /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
      *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
+    /** 🔴 闭集(FIX② 2026-08-07 加 `empty_answer`,第 5 员)。加员必须**同批**改齐
+     *  `parkResolver.GATE_FAILURE_CODES` 白名单 —— 那道白名单把不认得的码降成 `undefined`,
+     *  一边加一边不改另一边 = 新码在消费端被静默吞掉(比不加还坏:本地拦住了,判词却丢了)。 */
     code) {
         super(message);
         this.code = code;
@@ -185,11 +188,25 @@ export class HitlBridge {
      * permission gate, but the answer rides `ApprovalDecision.answer` as the worker-validated
      * `{ answers: [{ header, selected, note? }] }` shape. The D-1 binding STILL binds (it is still a
      * checkpoint). Each answer's `header` MUST match a question header (the worker 400s on mismatch).
+     *
+     * 🔴 FIX②(2026-08-07)—— **本地 fail-loud**:此前本方法对 `answers: []` 与「某条 `selected: []`」
+     * 零校验,一条注定 400 的请求照样出门。这不是「多一次往返」而已 ——
+     *   · 用户面只看到「作答失败」,而失败的原因(空作答)在壳侧一个字都没说;
+     *   · `ToolPermissionDecision.answer` 的头注自己写着「a silently emptied answer is the user's
+     *     choice being thrown away without anyone noticing」—— 那条纪律此前只写在类型注释里,
+     *     没有任何一层真的执行它;
+     *   · `{answers:[]}` 在 wire 上另有确切含义(question 域 **deny** 的 NO_HUMAN 形),把它当成一次
+     *     approve 发出去 = 拿 deny 的载荷冒充 approve。
+     * 三形一律抛 `HitlSafetyError('empty_answer')`,一次 decide 都不发:空 `answers[]` /
+     * 任一条 `selected[]` 为空 / 任一条 `header` 为空串。
      */
     async answerQuestion(answers, toolUseID, opts, 
     /** REF-CC-029(2026-08-02):see `decideTool`'s same-named param — the pending row the caller already
      *  fetched via `findPendingForTask`. */
     preResolvedPending) {
+        // 🔴 校验在 findPending **之前**:入参坏了跟 pending 行在不在场无关,而先 list 再拒会把
+        //    「你的作答是空的」这条真判词换成「no_pending」那条假判词(行恰好过期时)。
+        assertAnswersSendable(answers);
         const pending = preResolvedPending ?? (await this.findPending(toolUseID, opts));
         if (!pending) {
             throw new HitlSafetyError('no pending AskUserQuestion checkpoint to answer — refetch + re-present', 'no_pending');
@@ -304,6 +321,26 @@ export function makeHitlCanUseTool(bridge, prompt) {
     };
 }
 // ── helpers ───────────────────────────────────────────────────────────────────
+/**
+ * FIX②(2026-08-07):作答**出门前**的本地闭集校验(fail-closed;详见 `answerQuestion` 头注)。
+ * 只判「这批作答在 wire 上有没有意义」,不判 header 与题面对不对得上 —— 后者的真源在 worker
+ * (它持有题面),壳侧猜一份题面副本只会造出第二个真源。
+ */
+function assertAnswersSendable(answers) {
+    if (!Array.isArray(answers) || answers.length === 0) {
+        throw new HitlSafetyError('refusing to send an EMPTY AskUserQuestion answer set — `{answers:[]}` is the wire\'s DENY/NO_HUMAN form, ' +
+            'sending it as an approve would throw the human\'s choice away and 400 the worker', 'empty_answer');
+    }
+    for (const a of answers) {
+        if (typeof a?.header !== 'string' || a.header.length === 0) {
+            throw new HitlSafetyError('refusing to send an answer with an EMPTY `header` — the worker matches answers to questions BY header (400)', 'empty_answer');
+        }
+        if (!Array.isArray(a.selected) || a.selected.length === 0) {
+            throw new HitlSafetyError(`refusing to send an answer with an EMPTY \`selected\` for header "${a.header}" — ` +
+                'an emptied selection is the human\'s choice silently discarded (the worker 400s on it)', 'empty_answer');
+        }
+    }
+}
 /** Marshal one answer into the worker-validated wire entry (contract/04 §4.1). Drops undefined `note`.
  *  REF-CC-038(2026-08-02):return 类型是 `AskAnswer` 本身(唯一源),不再是一份重写的内联匿名形。 */
 function marshalAnswer(a) {

package/dist/hitl/hitlHostSurface.d.ts

@@ -37,6 +37,33 @@ export declare function surfaceForCurrentSession(): HitlHostSurface | null;
 export declare const CANCEL_DENY_BUDGET_MS = 2000;
 /** warn 行文案(测试锁字面)。 */
 export declare const CANCEL_DENY_WARN_TEXT = "could not cancel the pending question \u2014 the session may stay locked; the run may need engine-side recovery";
+/** 文案(测试锁字面)。措辞刻意描述**后果**而不是内部机制:用户要知道的是「下次还会问」。 */
+export declare const REMEMBER_NOT_APPLIED_WARN_TEXT = "this session-wide allow was not remembered by the worker \u2014 you will be asked again for this tool";
+/** 文案(测试锁字面)。"original" 是判据词:用户必须读到「跑的是原来那份」。 */
+export declare const EDIT_NOT_FORWARDED_WARN_TEXT = "your edited tool input was NOT forwarded \u2014 the tool is running with the ORIGINAL input you saw before editing";
+/**
+ * `allow_session` 决断的 ack 回报 `rememberApplied:false`(server 1.239 起诚实回显 —— 典型成因
+ * 是这条 run 没有 sessionId,grant 无处可落)。
+ *
+ * 🔴 为什么这必须上屏而不是只记 debug:三选卡第 2 项在用户心里签的是「本会话这个工具不再问我」。
+ * 记没落店而界面照渲「全放行」,就是**把一个没有发生的授权渲成发生了** —— 下一次弹卡时用户会以为
+ * 是 bug,更坏的是他可能因此养成「一路回车」的习惯。缺席(旧 server 不出这个位)= 未知,
+ * 按 [honest-absence-not-fabricated-zero] 一律不发通知,绝不把未知渲成失败。
+ * 无宿主口(print/headless 没屏)⇒ 静默,与 {@link surfaceCancelDenyWarn} 同语义。
+ */
+export declare function surfaceRememberNotApplied(): void;
+/**
+ * 「编辑并批准」带了 `updatedInput`,而 ack 回报 `updatedInputForwarded:false`(server 1.241 起
+ * 诚实回显)—— 引擎拿到的是**原始**入参。
+ *
+ * 🔴 这一条比 remember 那条严重一个量级,它是本批 codex 复审判的 [high]:用户在卡上把
+ * `rm -rf /tmp/x` 改成 `rm -rf /tmp/x/build` 然后按了批准,而真正执行的是他改之前那条。
+ * **事后没有 fail-closed 的余地**(allow 已经送达,工具已经在跑),所以唯一诚实的处置就是立刻
+ * 响亮地说出来 —— 静默(此前只写 debug 日志)等于让用户以为自己的编辑生效了。
+ * 上游的正位是让 server 在「带了 updatedInput 却转发不了」时 fail-closed 拒批;那属跨仓,
+ * 已记进 docs/refactor/README.md 的宿主/上游工单表,本层不做旁路补偿(只做如实告知)。
+ */
+export declare function surfaceEditNotForwarded(): void;
 /**
  * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面;REF-CC-023 起两条决断腿共用)。
  * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:

package/dist/hitl/hitlHostSurface.js

@@ -75,31 +75,71 @@ const CANCEL_DENY_WARN_TIMEOUT_MS = 10_000;
  *  [paired-mechanisms-must-share-premise]:只给「显示」不给「清」,端各写各的清法必然漂。
  *  无口(print/headless 没屏可上)⇒ 静默,与壳原文 `if (!store) return` 同语义。 */
 function surfaceCancelDenyWarn() {
+    surfaceSelfClearingWarn(CANCEL_DENY_WARN_KEY, CANCEL_DENY_WARN_TEXT, CANCEL_DENY_WARN_TIMEOUT_MS);
+}
+/**
+ * 「上屏一行 warning + 到点自清(仅当仍是本 key)」的**唯一**实现(FIX① 收编:此前只有
+ * cancel-by-deny 一处,新增 remember-not-applied 时若各写一遍,两处的自清时序必然漂 ——
+ * [paired-mechanisms-must-share-premise];顺带保住 TIMER③ 的裸定时器创建点基线不上涨)。
+ * 无宿主口 ⇒ 静默(print/headless 没屏可上,与壳原文 `if (!store) return` 同语义)。
+ */
+function surfaceSelfClearingWarn(key, text, timeoutMs) {
     try {
         const s = surfaceForCurrentSession();
         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,
-        });
+        s.showNotice({ key, text, color: 'warning', priority: 'immediate', timeoutMs });
         const timer = setTimeout(() => {
             try {
-                s.clearNoticeIfCurrent(CANCEL_DENY_WARN_KEY);
+                s.clearNoticeIfCurrent(key);
             }
             catch {
                 /* fail-soft */
             }
-        }, CANCEL_DENY_WARN_TIMEOUT_MS);
+        }, timeoutMs);
         unrefTimer(timer);
     }
     catch {
-        /* fail-soft:上屏失败绝不再伤害 abort 流 */
+        /* fail-soft:上屏失败绝不再伤害它所依附的那条流 */
     }
 }
+// ── FIX① (2026-08-07) —— allow_session 的「记住了没有」诚实回执 ────────────────────────────────
+/** 文案(测试锁字面)。措辞刻意描述**后果**而不是内部机制:用户要知道的是「下次还会问」。 */
+export const REMEMBER_NOT_APPLIED_WARN_TEXT = 'this session-wide allow was not remembered by the worker — you will be asked again for this tool';
+const REMEMBER_NOT_APPLIED_KEY = 'hitl-remember-not-applied';
+const REMEMBER_NOT_APPLIED_TIMEOUT_MS = 10_000;
+/** 文案(测试锁字面)。"original" 是判据词:用户必须读到「跑的是原来那份」。 */
+export const EDIT_NOT_FORWARDED_WARN_TEXT = 'your edited tool input was NOT forwarded — the tool is running with the ORIGINAL input you saw before editing';
+const EDIT_NOT_FORWARDED_KEY = 'hitl-edit-not-forwarded';
+/** 比 remember 那条久:它说的是「正在跑的东西和你批的不是同一份」,值得多留一会儿。 */
+const EDIT_NOT_FORWARDED_TIMEOUT_MS = 20_000;
+/**
+ * `allow_session` 决断的 ack 回报 `rememberApplied:false`(server 1.239 起诚实回显 —— 典型成因
+ * 是这条 run 没有 sessionId,grant 无处可落)。
+ *
+ * 🔴 为什么这必须上屏而不是只记 debug:三选卡第 2 项在用户心里签的是「本会话这个工具不再问我」。
+ * 记没落店而界面照渲「全放行」,就是**把一个没有发生的授权渲成发生了** —— 下一次弹卡时用户会以为
+ * 是 bug,更坏的是他可能因此养成「一路回车」的习惯。缺席(旧 server 不出这个位)= 未知,
+ * 按 [honest-absence-not-fabricated-zero] 一律不发通知,绝不把未知渲成失败。
+ * 无宿主口(print/headless 没屏)⇒ 静默,与 {@link surfaceCancelDenyWarn} 同语义。
+ */
+export function surfaceRememberNotApplied() {
+    surfaceSelfClearingWarn(REMEMBER_NOT_APPLIED_KEY, REMEMBER_NOT_APPLIED_WARN_TEXT, REMEMBER_NOT_APPLIED_TIMEOUT_MS);
+}
+/**
+ * 「编辑并批准」带了 `updatedInput`,而 ack 回报 `updatedInputForwarded:false`(server 1.241 起
+ * 诚实回显)—— 引擎拿到的是**原始**入参。
+ *
+ * 🔴 这一条比 remember 那条严重一个量级,它是本批 codex 复审判的 [high]:用户在卡上把
+ * `rm -rf /tmp/x` 改成 `rm -rf /tmp/x/build` 然后按了批准,而真正执行的是他改之前那条。
+ * **事后没有 fail-closed 的余地**(allow 已经送达,工具已经在跑),所以唯一诚实的处置就是立刻
+ * 响亮地说出来 —— 静默(此前只写 debug 日志)等于让用户以为自己的编辑生效了。
+ * 上游的正位是让 server 在「带了 updatedInput 却转发不了」时 fail-closed 拒批;那属跨仓,
+ * 已记进 docs/refactor/README.md 的宿主/上游工单表,本层不做旁路补偿(只做如实告知)。
+ */
+export function surfaceEditNotForwarded() {
+    surfaceSelfClearingWarn(EDIT_NOT_FORWARDED_KEY, EDIT_NOT_FORWARDED_WARN_TEXT, EDIT_NOT_FORWARDED_TIMEOUT_MS);
+}
 /**
  * cancel-by-deny 的「良性 no_pending」判据。**结构化 `.code` 为主,`instanceof` 只作加强,绝不替代**:
  *  - `.code` 是 client-core 自家 `HitlSafetyError` 的契约属性(hitlBridge.ts,REF-CC-036 起是闭集

package/dist/hitl/parkResolver.d.ts

@@ -25,7 +25,14 @@ import { type AskGateWireDeps, type GatePark } from './frameRouter.js';
  * 开集腐蚀这个新判别位)。消费点只认 `'no_pending'` 为「已解决」,其余码(binding_mismatch 等)
  * 是真需要重新呈现给人的失败,不能走「继续读流」这条路。
  */
-export type GateFailureCode = 'no_pending' | 'binding_mismatch' | 'wrong_gate' | 'bad_plan_edit';
+/**
+ * 白名单的**运行期真源**(FIX② 2026-08-07 由三处散落的 `===` 收成一份元组)。
+ * 🔴 与 `hitlBridge.HitlSafetyError.code` 的联合是**同一个闭集的两半**:下方 `_gateFailureCodePins`
+ * 双向钉住,任何一边加员而另一边不跟 ⇒ 编译红。此前两边靠人肉同步,而不同步的可观测后果是
+ * 「新码被 `isGateFailureCode` 降成 undefined 后静默走文案兜底臂」—— 门里长得跟正常一模一样。
+ */
+export declare const GATE_FAILURE_CODES: readonly ["no_pending", "binding_mismatch", "wrong_gate", "bad_plan_edit", "empty_answer"];
+export type GateFailureCode = (typeof GATE_FAILURE_CODES)[number];
 export type GateOutcome = {
     kind: 'decided';
     gatedCallId?: string | undefined;

package/dist/hitl/parkResolver.js

@@ -6,8 +6,33 @@ import { observeCancelByDeny } from './hitlHostSurface.js';
 import { isAskTool } from './frameRouter.js';
 /** 一 turn 内最多循环这么多次 park(防御:引擎/模型病态连环提问时不无限 attach)。 */
 const MAX_GATE_HOPS = 24;
+/**
+ * REF-CC-033:`GateOutcome` 的 `failed` 分支闭集判别码。来源两处:①本文件自己的
+ * 「pending 行取不到」早退(`surfaceGateAndDecide` 里 `!pending` 那条);②`HitlBridge` 抛出的
+ * `HitlSafetyError.code`(hitlBridge.ts 契约:`binding_mismatch|no_pending|wrong_gate|bad_plan_edit`
+ * ——该属性今天仍是开集 `string`,TYPESHAPE-07/REF-CC-036 候后续车锁死;这里落地前用
+ * `isGateFailureCode` 按闭集白名单过滤,不认得的值一律降级成 `undefined`,退回文案兜底,不让
+ * 开集腐蚀这个新判别位)。消费点只认 `'no_pending'` 为「已解决」,其余码(binding_mismatch 等)
+ * 是真需要重新呈现给人的失败,不能走「继续读流」这条路。
+ */
+/**
+ * 白名单的**运行期真源**(FIX② 2026-08-07 由三处散落的 `===` 收成一份元组)。
+ * 🔴 与 `hitlBridge.HitlSafetyError.code` 的联合是**同一个闭集的两半**:下方 `_gateFailureCodePins`
+ * 双向钉住,任何一边加员而另一边不跟 ⇒ 编译红。此前两边靠人肉同步,而不同步的可观测后果是
+ * 「新码被 `isGateFailureCode` 降成 undefined 后静默走文案兜底臂」—— 门里长得跟正常一模一样。
+ */
+export const GATE_FAILURE_CODES = [
+    'no_pending',
+    'binding_mismatch',
+    'wrong_gate',
+    'bad_plan_edit',
+    /** FIX②:空作答被本地拦下(空 answers[] / 空 selected[] / 空 header)。 */
+    'empty_answer',
+];
+const _gateFailureCodePins = [true, true];
+void _gateFailureCodePins;
 function isGateFailureCode(v) {
-    return v === 'no_pending' || v === 'binding_mismatch' || v === 'wrong_gate' || v === 'bad_plan_edit';
+    return typeof v === 'string' && GATE_FAILURE_CODES.includes(v);
 }
 /**
  * decide 的 `failed` 原因是不是「这个 gate 早就被解决了」(#110 缺陷② c 的判据)。

package/dist/hitl/toolApprovalWire.d.ts

@@ -62,6 +62,7 @@
  * 🔴 UNTRUSTED:gate args 为模型作文(service 已 redact),只渲染绝不回喂;决断只带 decision 枚举。
  */
 import { type HitlClientLike } from './hitlBridge.js';
+import type { ToolApprovalRespondAck } from '@sema-agent/sdk';
 /** fs 写权限 gate 判定:未来的一等 kind(tool_approval)或按 toolName(server 桥首批=fs 写三件,
  *  [820] 表)。AskUserQuestion 永不进这里(ask 桥先判)。 */
 export declare function isFsApprovalGate(gate: {
@@ -127,6 +128,16 @@ export interface ApprovalCardRequest {
     /** wire 层降级说明(卡 content 上方 dim 行,ToolUseConfirm.wireNote 超集位)——argsOmitted 等
      *  不可注入 args 的提示走这里([1543]③ 记账的 note 位,2026-07-23 落位)。 */
     wireNote?: string;
+    /**
+     * 治理强制位(server ≥7.5.0,2026-08-08 补透传)——原样来自
+     * {@link ToolApprovalFrame.governanceForced}。**缺席 ≠ false**:只在为真时在场,缺席 = 无治理来源
+     * 的证据。壳应据此把门呈成**表态掀不掉**(而不是引导用户去改 `permissionMode`);呈现形是壳半场,
+     * 本包只保证这一位到得了卡口 —— 此前它在帧类型上就不存在,于是宿主无论怎么写都读不到。
+     */
+    governanceForced?: true;
+    /** 委派出处链(core 5.9.0 W1)——原样来自 {@link ToolApprovalFrame.delegation};只读展示增强,
+     *  `agentName` UNTRUSTED-for-display。子代 ask 才在场。 */
+    delegation?: ToolApprovalDelegation;
 }
 /**
  * 🔴 **拆缝口** —— 弹「三选卡」并等人的决断。壳 = vendored CC `PermissionRequest`;
@@ -189,24 +200,91 @@ export interface ToolApprovalFrame {
     fromSubagent?: boolean;
     /** core 1.378 RB-39②:展示身份(UNTRUSTED-for-display,server redact 后上帧)——徽章名一手源。 */
     sourceAgentName?: string;
+    /**
+     * server ≥7.5.0([2942]/[2943],ADDITIVE;≤7.4.0 恒缺席)——**治理强制**位:此门来自运维治理层
+     * (部署侧 `AUTONOMY` / `commandPolicy` / `MANUAL_MODE_SHELL_GATE` / `SENSITIVE_WRITE_PATTERNS`),
+     * 不是模型默认门、也不是本次请求的客户端表态。它回答「我都开了 `bypassPermissions` 为什么还在问」。
+     *
+     * 🔴 **缺席 ≠ `false`**(与风险两轴同族纪律):本键**只在为真时在场**。缺席 = 「没有治理来源的
+     * 证据」,它既覆盖真的非治理 ask,也覆盖 server 侧判据够不着的形(治理 shell 门停在 `classify`
+     * 档时,一次 shell ask 出自分类器还是别的门无从分辨——server 选择让键缺席而不是猜)。所以缺席
+     * **不得**被渲染成「这门可以用表态绕开」。
+     *
+     * 分工:本包只做**透传**(帧 → {@link ApprovalCardRequest.governanceForced}),徽标呈现是壳半场。
+     */
+    governanceForced?: true;
+    /**
+     * core 5.9.0 W1([2535],ADDITIVE):ask 的**委派出处链**(最内层孙代帧胜出)。与
+     * {@link fromSubagent} 同门在场(只有子代 ask 带)。只读展示增强 —— 卡可以说清这只 ask 是从哪
+     * 一层浮上来的。`agentName` 与 {@link sourceAgentName} 同属 UNTRUSTED-for-display。
+     */
+    delegation?: ToolApprovalDelegation;
+}
+/** {@link ToolApprovalFrame.delegation} 的形(命名形,不用内联匿名 —— typeshape 门 B4 棘轮口径)。 */
+export interface ToolApprovalDelegation {
+    /** 宿主侧那次委派调用的 tool-call id —— 卡的归属锚。 */
+    parentToolCallId: string;
+    /** 委派深度(宿主直接子代 = 1)。 */
+    depth: number;
+    /** 子代 agent 名。**UNTRUSTED**:spawning model 的自由文本(server 已脱敏+限长)。 */
+    agentName?: string;
 }
 /**
  * 本地值拷贝的**运行时键集镜像**([1950]② 建议形):对账测试拿它与 SDK 0.1.6+ 的同源锚
  * `TOOL_APPROVAL_FRAME_KEYS` 比对——SDK additive 增键时对账当天红,不再人肉追平。
  * 下面两个类型钉保证镜像与 interface 本身不可能漂移(少键/多键都是编译错)。
  */
-export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "outcome"];
+export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "delegation", "outcome"];
 /** 子代帧判别:显式键 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)。 */
+/**
+ * POST /v1/tool-approvals/:id/respond 的注入面。
+ *
+ * 🔴 FIX①(2026-08-07):**SDK 6.3.0 起这是一等资源** `client.toolApprovals.respond`,返回
+ * `ToolApprovalRespondAck`(`{approvalId, delivery:"applied", decision, rememberApplied?,
+ * updatedInputForwarded?}`)。此前本位钉死 `Promise<void>` —— 于是 ack 上那两个**诚实位**在类型层
+ * 就不可能被读到:
+ *   · `rememberApplied:false`(server 1.239)= allow_session 的 grant **没落店**(典型:无 sessionId)
+ *     ⇒ 壳照渲「本会话全放行」就是把一个没发生的授权渲成发生了;
+ *   · `updatedInputForwarded`(server 1.241)= 编辑后的 args 是否真被透传给引擎(措辞诚实:
+ *     forwarded ≠ applied)。
+ * 返回型放宽成 `ack | void` 而不是硬钉 ack:**注入面的实现方**(旧 liveClient / mock / 测试桩)
+ * 回 void 仍然合法(assignable),消费端按 {@link readToolApprovalRespondAck} 结构化读,缺席=未知。
+ */
 export type RespondToolApprovalFn = (approvalId: string, decision: ToolApprovalRespondDecision, opts?: {
     signal?: AbortSignal;
     updatedInput?: unknown;
-}) => Promise<void>;
-/** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名;非 AgentEvent arm)。 */
+}) => Promise<ToolApprovalRespondAck | void>;
+/**
+ * respond 回执的**结构化读口**(wire 是 JSON:注入面可能是旧 liveClient 的 raw fetch,也可能是
+ * 比本包新一版的 SDK)。坏形一律降 `undefined` —— 与 `controlRouter.errCodes` 同族纪律:
+ * 「拿到一个不好用的值」不如「诚实地什么都没有」。两个可选布尔位非布尔时**单独**降缺席
+ * (它们直接决定要不要渲「本会话全放行」,透传一个 `'yes'` 字符串会让 `!== false` 这类读法说反话)。
+ *
+ * 🔴 `decision` 判到 **wire 三词闭集**而不是「是不是串」(codex 复审二轮):ack 上那两个布尔位会
+ * 触发**高危安全声明**(「工具正在用原始入参跑」),所以一个 `decision:'garbage'` 的回执绝不许被
+ * 当成合规 ack 放行。**相关性**(「这个 ack 是不是**这一次**审批的回执」)不在本函数判 —— 本函数
+ * 只认形,对不对得上由 {@link surfaceToolApprovalFrameAndRespond} 拿着 frame 与刚发出的 decision 核。
+ */
+export declare function readToolApprovalRespondAck(v: unknown): ToolApprovalRespondAck | undefined;
+/**
+ * 一张 `tool_approval` 帧消费完的产物(FIX①,2026-08-07 **BREAKING**:此前是裸的
+ * `ToolApprovalRespondDecision | 'unresolved'` 字符串)。
+ * 迁移判据一句话:`const out = await surfaceToolApprovalFrameAndRespond(…); out.decision === 'deny'`。
+ */
+export interface ToolApprovalFrameOutcome {
+    /** 用户(或 fail-closed)落定的决断;`'unresolved'` = respond 没送达(引擎按 TTL 自决)。 */
+    decision: ToolApprovalRespondDecision | 'unresolved';
+    /** server 的 200 ack。**缺席 = 未知**(注入面回 void / 旧 server / respond 失败),绝不当成 false。 */
+    ack?: ToolApprovalRespondAck;
+}
+/** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名)。
+ *  ⚠️ 口径更正(2026-08-08):此处原写「非 AgentEvent arm」—— SDK #185a 起这两个帧**是**
+ *  `AgentEvent` 的臂了(durable 腿也回放),所以结构识别与 union 收窄两条路都成立;本函数仍按
+ *  结构读(不依赖类型收窄),因为它同时服务 raw SSE 与 durable 回放两条入口。 */
 export declare function isToolApprovalFrame(ev: unknown): ev is ToolApprovalFrame;
 /**
  * 消费一张 `tool_approval` 帧:弹三选卡 → respond。引擎此刻同步阻塞在本帧上(fail-closed 全腿:
@@ -215,6 +293,6 @@ export declare function isToolApprovalFrame(ev: unknown): ev is ToolApprovalFram
  * fail-closed:卡面不可用(print 模式无卡口/enqueue 失败)⇒ 立刻 respond deny,不让引擎
  * 干等 TTL。respond 自身失败(404=已过期/settled)⇒ 'unresolved'(诚实放行后续帧,引擎已自决)。
  *
- * @returns 用户(或 fail-closed)落定的决断;'unresolved' = respond 没送达。
+ * @returns {@link ToolApprovalFrameOutcome} —— 决断 + server ack(ack 缺席 = 未知,不是 false)。
  */
-export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal): Promise<ToolApprovalRespondDecision | 'unresolved'>;
+export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal): Promise<ToolApprovalFrameOutcome>;

package/dist/hitl/toolApprovalWire.js

@@ -65,7 +65,7 @@ import { HitlBridge, HitlSafetyError, findPendingForTask } from './hitlBridge.js
 import { hostLog } from '../host.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { readEngineActiveBgTasks } from '../fleet/fleetLedger.js';
-import { observeCancelByDeny } from './hitlHostSurface.js';
+import { observeCancelByDeny, surfaceRememberNotApplied, surfaceEditNotForwarded } from './hitlHostSurface.js';
 /** fs 写权限 gate 判定:未来的一等 kind(tool_approval)或按 toolName(server 桥首批=fs 写三件,
  *  [820] 表)。AskUserQuestion 永不进这里(ask 桥先判)。 */
 export function isFsApprovalGate(gate) {
@@ -301,10 +301,39 @@ export const TOOL_APPROVAL_FRAME_KEYS_MIRROR = [
     'message',
     'args',
     'argsOmitted',
+    // sdk 6.9.0 追平(2026-08-08,#3004 跟修批):server 7.5.0 起真发 `governanceForced`,core 5.9.0 W1
+    // 起真发 `delegation` —— 镜像滞后了两代,于是这两键在包内**零消费面**(治理徽标端到端不可达,
+    // [1947] 那次 `toolCallId` 滞后的同款形)。本门(run-approval-frame-keys-test.mjs)对 SDK 运行期
+    // 锚逐元素相等,所以这次滞后是被门抓到的,不是人肉发现的。
+    'governanceForced',
+    'delegation',
     'outcome',
 ];
 const _mirrorPin = [true, true];
 void _mirrorPin;
+/**
+ * `delegation` 的结构读(wire 是 JSON:注入面/旧 server/比本包新一版的 server 都可能给别的形)。
+ * 坏形一律降**缺席** —— 与 `readToolApprovalRespondAck` 同族纪律:「拿到一个不好用的值」不如
+ * 「诚实地什么都没有」。`parentToolCallId` 是卡的归属锚、`depth` 决定「第几层」的措辞,两者任一
+ * 不成形就整体不透传(半个链比没有链更容易被渲成错话);`agentName` 非串时单独降缺席。
+ *
+ * **不导出**(2026-08-08 收货修):它是本模块的边界窄化器,唯一消费点就在下面那个卡口调用;导出会
+ * 给公面加一个 `unknown` 入参签名(typeshape 门的 unknown-出境棘轮 +1),而它的行为在 pure 门里由
+ * `surfaceToolApprovalFrameAndRespond` 的坏形/正形素材端到端覆盖 —— 真消费路径比直调守卫更强。
+ */
+function isToolApprovalDelegation(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const d = v;
+    // 归属锚:必须是**非空白**串(`'  '` 当 tool-call id 用会让卡按一个空锚归属)。
+    if (typeof d.parentToolCallId !== 'string' || d.parentToolCallId.trim().length === 0)
+        return false;
+    // 深度:上游语义是「宿主直接子代 = 1」⇒ **正安全整数**。0 / 负数 / 小数都不是可渲染的层数,
+    // 而 `Number.isFinite` 会把它们全放过(codex 复审命中:`depth: 0` / `-1` / `1.5` 曾一律判真)。
+    if (typeof d.depth !== 'number' || !Number.isSafeInteger(d.depth) || d.depth < 1)
+        return false;
+    return d.agentName === undefined || typeof d.agentName === 'string';
+}
 /** 子代帧判别:显式键 fromSubagent(core 1.378 RB-39②)优先;缺席退 sourceTaskId 在场性权宜式
  *  (server 1.258 [1549]①3,旧代际兼容)。 */
 export function isFromSubagent(frame) {
@@ -312,7 +341,46 @@ export function isFromSubagent(frame) {
         return true;
     return typeof frame.sourceTaskId === 'string' && frame.sourceTaskId.length > 0;
 }
-/** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名;非 AgentEvent arm)。 */
+/** 上面那个闭集的运行期真源(ack 判形要用;词表与类型由下方 `Covers` 双向钉住)。 */
+const RESPOND_DECISIONS = ['allow', 'allow_session', 'deny'];
+const _respondDecisionPins = [true, true];
+void _respondDecisionPins;
+function isRespondDecision(v) {
+    return typeof v === 'string' && RESPOND_DECISIONS.includes(v);
+}
+/**
+ * respond 回执的**结构化读口**(wire 是 JSON:注入面可能是旧 liveClient 的 raw fetch,也可能是
+ * 比本包新一版的 SDK)。坏形一律降 `undefined` —— 与 `controlRouter.errCodes` 同族纪律:
+ * 「拿到一个不好用的值」不如「诚实地什么都没有」。两个可选布尔位非布尔时**单独**降缺席
+ * (它们直接决定要不要渲「本会话全放行」,透传一个 `'yes'` 字符串会让 `!== false` 这类读法说反话)。
+ *
+ * 🔴 `decision` 判到 **wire 三词闭集**而不是「是不是串」(codex 复审二轮):ack 上那两个布尔位会
+ * 触发**高危安全声明**(「工具正在用原始入参跑」),所以一个 `decision:'garbage'` 的回执绝不许被
+ * 当成合规 ack 放行。**相关性**(「这个 ack 是不是**这一次**审批的回执」)不在本函数判 —— 本函数
+ * 只认形,对不对得上由 {@link surfaceToolApprovalFrameAndRespond} 拿着 frame 与刚发出的 decision 核。
+ */
+export function readToolApprovalRespondAck(v) {
+    if (v === null || typeof v !== 'object')
+        return undefined;
+    const o = v;
+    if (o.delivery !== 'applied')
+        return undefined;
+    if (typeof o.approvalId !== 'string' || o.approvalId.length === 0)
+        return undefined;
+    if (!isRespondDecision(o.decision))
+        return undefined;
+    return {
+        approvalId: o.approvalId,
+        delivery: 'applied',
+        decision: o.decision,
+        ...(typeof o.rememberApplied === 'boolean' ? { rememberApplied: o.rememberApplied } : {}),
+        ...(typeof o.updatedInputForwarded === 'boolean' ? { updatedInputForwarded: o.updatedInputForwarded } : {}),
+    };
+}
+/** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名)。
+ *  ⚠️ 口径更正(2026-08-08):此处原写「非 AgentEvent arm」—— SDK #185a 起这两个帧**是**
+ *  `AgentEvent` 的臂了(durable 腿也回放),所以结构识别与 union 收窄两条路都成立;本函数仍按
+ *  结构读(不依赖类型收窄),因为它同时服务 raw SSE 与 durable 回放两条入口。 */
 export function isToolApprovalFrame(ev) {
     const e = ev;
     return (!!e &&
@@ -365,7 +433,7 @@ function subagentBadgeFor(frame) {
  * fail-closed:卡面不可用(print 模式无卡口/enqueue 失败)⇒ 立刻 respond deny,不让引擎
  * 干等 TTL。respond 自身失败(404=已过期/settled)⇒ 'unresolved'(诚实放行后续帧,引擎已自决)。
  *
- * @returns 用户(或 fail-closed)落定的决断;'unresolved' = respond 没送达。
+ * @returns {@link ToolApprovalFrameOutcome} —— 决断 + server ack(ack 缺席 = 未知,不是 false)。
  */
 export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamArgs, signal) {
     const toolName = typeof frame.toolName === 'string' ? frame.toolName : 'Write';
@@ -390,6 +458,9 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
     // [1535]:子代的写审批浮到宿主卡(server 1.258 broker 腿)——卡头渲归属徽章(`· @name`),
     // 用户知道在替谁批。判别=fromSubagent 显式键(core 1.378)优先、sourceTaskId 在场性权宜式兜底;
     // 宿主自身 ask 两键恒缺席=徽章缺席,卡形不变。
+    // 🔴 治理位与委派链透传(2026-08-08):两键在帧上**只在为真/在场时**出现,所以这里也按在场性
+    //    条件 stamp —— 绝不 `governanceForced: frame.governanceForced === true`(那会把「缺席」折成
+    //    显式 `false`,而缺席的语义是「没有治理来源的证据」,不是「这门可以被表态掀掉」)。
     const card = await surfaceApprovalCard({
         toolName,
         args: args,
@@ -397,6 +468,15 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         ...(signal ? { signal } : {}),
         ...(isFromSubagent(frame) ? { workerBadge: subagentBadgeFor(frame) } : {}),
         ...(wireNote !== undefined ? { wireNote } : {}),
+        ...(frame.governanceForced === true ? { governanceForced: true } : {}),
+        // 🔴 跨字段不变量(codex 复审命中):`delegation` 只在**子代 ask** 的门上在场(SDK 头注:
+        //    "Present on the same door as fromSubagent (child asks only)")。只校对象形不校这一条 ⇒
+        //    一个**宿主自己**的破坏性工具审批也能带着 delegation 到卡口,被呈成「某层子代发起的」——
+        //    把归属这件安全展示位渲错,正是本键存在的反面。`isToolApprovalFrame` 只验 type/approvalId,
+        //    所以 raw SSE / durable 回放里的坏形到得了这里,必须在本层挡住。
+        ...(isFromSubagent(frame) && isToolApprovalDelegation(frame.delegation)
+            ? { delegation: frame.delegation }
+            : {}),
     });
     const decision = card.kind === 'allow' ? (card.allowSession ? 'allow_session' : 'allow') : 'deny';
     if (card.kind === 'failed') {
@@ -404,14 +484,40 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
     }
     try {
         // abort 后的 deny 仍要送达(引擎侧同款 cancel-by-deny)——不带已 aborted 的 signal。
-        await respond(frame.approvalId, decision, {
+        const raw = await respond(frame.approvalId, decision, {
             ...(signal && !signal.aborted ? { signal } : {}),
             ...(card.kind === 'allow' && card.updatedInput !== undefined ? { updatedInput: card.updatedInput } : {}),
         });
-        return decision;
+        // 🔴 相关性门(codex 复审二轮):ack 必须是**这一次**审批的回执 —— id 与决断词都要对上。
+        //    对不上的 ack(注入面串了别人的响应 / 坏 mock / raw-fetch 包装器复用了连接)如果照样被
+        //    消费,一次普通审批就能弹出「你的编辑没生效、工具正在用原始入参跑」这种强安全声明。
+        //    不匹配 ⇒ 整个 ack 丢弃(降成「未知」)+ 响亮留痕,绝不据此触发任何用户告警。
+        const parsed = readToolApprovalRespondAck(raw);
+        let ack = parsed;
+        if (parsed !== undefined && (parsed.approvalId !== frame.approvalId || parsed.decision !== decision)) {
+            hostLog('error', `liveToolApprovalWire: DISCARDING respond ack for ${frame.approvalId} — it does not correlate ` +
+                `(ack.approvalId=${parsed.approvalId} ack.decision=${parsed.decision}, sent decision=${decision}); ` +
+                'treating as "no ack" (unknown) — never surfacing a safety notice off an unrelated receipt');
+            ack = undefined;
+        }
+        // 🔴 FIX①:三选卡第 2 项在用户心里签的是「本会话这个工具不再问我」。server 说没记住时,
+        //    界面必须收敛那个承诺 —— 这里只发一条诚实通知(渲不渲「全放行」徽标由宿主按 ack 决定,
+        //    ack 也随本函数返回值一起交出去)。ack 缺席(旧 server / void 注入面)= 未知,不发。
+        if (decision === 'allow_session' && ack?.rememberApplied === false) {
+            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} allow_session ack rememberApplied=false — grant not stored, surfacing honest notice`);
+            surfaceRememberNotApplied();
+        }
+        // 🔴 [high] 同族但更重的一位:用户**编辑过**入参并批准,而 server 说编辑没转发 ⇒ 引擎按
+        //    原始入参跑。批的那份 ≠ 跑的那份,对 Write/Edit/Bash 就是破坏性操作的入口。
+        //    allow 已送达,事后无法 fail-closed ⇒ 唯一诚实的处置是立刻响亮告知(不是 debug 日志)。
+        if (card.kind === 'allow' && card.updatedInput !== undefined && ack?.updatedInputForwarded === false) {
+            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} edited args were NOT forwarded (ack.updatedInputForwarded=false) — the tool runs on the ORIGINAL input`);
+            surfaceEditNotForwarded();
+        }
+        return ack !== undefined ? { decision, ack } : { decision };
     }
     catch (e) {
         hostLog('debug', `liveToolApprovalWire: respond(${decision}) failed for ${frame.approvalId}: ${String(e)} — engine self-settles (TTL/abort)`);
-        return 'unresolved';
+        return { decision: 'unresolved' };
     }
 }

package/dist/retryStatus.d.ts

@@ -6,16 +6,46 @@
  *   retrying     → error    → '✻ API error · Retrying in Ns'(非终态;187 硬编码 'API error')
  *   rate_limited → error    → '✻ Usage limit reached · Retrying in Ns'(rateLimits 真 ⇒ 终态)
  *   circuit_open → error    → '✻ <detail|Service temporarily unavailable> · Retrying in Ns'
- * 绝不捏造 attempt 计数——只用引擎真给的 phase/detail/retryInSec。
+ *   recovered    → null     → 覆盖层摘掉(重试**成功**,不是错误 —— 见下)
+ *   gave_up      → error+terminal → '✻ <detail>'(重试用尽的终态;与 recovered 反向。**打 terminal 位**,
+ *                                    渲染面据此不得再接「· Retrying in Ns」——已经没有下一次了)
+ * 绝不捏造 attempt 计数——只用引擎真给的 phase / detail / retryInSec / retryInMs / attempt / maxRetries。
+ *
+ * 🔴 员数与字段补全(2026-08-08,#3004 跟修批)。此前本文件只列 4 相 + 3 字段,而引擎侧
+ * (core `BrainStatusPhase` / `BrainStatus`,dist/core/types.d.ts)是 **6 相 + 6 字段**,server 两腿的
+ * `brainStatusEventData`(dist/trace/project.js)把 attempt/maxRetries/retryInMs 全发。两处后果:
+ *   · `recovered`(引擎重试**成功**的终态)落 `default:` 臂 ⇒ 被渲成 `kind:'error'`,即
+ *     「刚刚恢复」被渲成「API error · Retrying」—— 方向完全相反的谎报;
+ *   · attempt/maxRetries/retryInMs 在本层被剥掉 ⇒ `RetryStatus` 上早就留好的 attempt/maxRetries
+ *     两位恒缺席。这不是「不许编造」(那条纪律没错),是**供给方给了却没接**。
+ * 反漂移腿:`scripts/run-engine-vocab-floor-test.mjs` G2-b/G2-c 拿下面两张运行期镜像对**实装
+ * @sema-agent/core** 的 `BrainStatusPhase` / `BrainStatus` 逐词逐键对账 —— 引擎再加相/加键,那边先红。
  */
-export type RetryStatus = {
+export type RetryStatus = 
+/** 等 API 响应(`reconnecting`)。**计数两位在场**:实装 core 的 reconnecting 帧与 retrying/
+ *  rate_limited 同形,六字段全发(`stream-engine.js` 三处 `sleepAnnouncingRetry` 逐处实测)——
+ *  丢掉它们正好是在「用户最需要看重连进度」的那一刻把进度藏起来(2026-08-08 codex 复审命中)。 */
+{
     kind: 'stalled';
     deadline: number;
+    attempt?: number;
+    maxRetries?: number;
 } | {
     kind: 'error';
     deadline: number;
     attempt?: number;
     maxRetries?: number;
+    /**
+     * 🔴 **终态位**(2026-08-08 codex 复审命中):`true` ⇔ 引擎**不会再重试了**(`gave_up` 相)。
+     * 缺席 = 仍在重试循环里(retrying / rate_limited / circuit_open)。
+     *
+     * 为什么必须有这一位:`deadline` 的语义是「距下次重试」,而 gave_up 根本没有下次 —— 实装 core
+     * 的 finally 只发 `{phase:'gave_up', detail:'retries exhausted'}`(**不带** attempt/maxRetries,
+     * 所以消费方也无法靠「3/3」推出耗尽)。没有这一位,187 那套「<detail> · Retrying in Ns」句式
+     * 会把一次**已经放弃**渲成「正在重试,还剩 0 秒」——终帧稍有延迟,这句谎就一直挂着。
+     * 渲染措辞是壳半场(本包不渲染),本位只保证那个事实到得了壳。
+     */
+    terminal?: true;
     error: {
         formatted: string;
         isNetworkDown?: boolean;
@@ -28,9 +58,38 @@ export type RetryStatus = {
         } | null;
     };
 };
+/**
+ * core `BrainStatusPhase` 的**运行期值拷贝**(engine-vocab 门 G2-b 拿它对实装 core 对账)。
+ * 引擎侧是闭集,**读时按开集处理** —— 一个部署可以在自己的通道上冒出别的相,认得的分支照走,
+ * 认不得的落 `default:` 兜底(见 {@link mapBrainStatusToRetry} 末臂)。
+ */
+export declare const BRAIN_STATUS_PHASES: readonly ["rate_limited", "retrying", "reconnecting", "circuit_open", "recovered", "gave_up"];
+export type BrainStatusPhase = (typeof BRAIN_STATUS_PHASES)[number];
+/** wire 上 `status` 臂的载荷(= core `BrainStatus`;server 两腿白名单原样转发这 6 键)。 */
 export interface BrainStatusPayload {
-    phase: string;
+    /** 闭集 + `(string & {})`:未知相仍可携带(开集读),不必先改类型再解析。 */
+    phase: BrainStatusPhase | (string & {});
+    /** 中性人话提示(无 provider/HTTP 细节;server 已脱敏 + 限 300 字)。 */
     detail?: string;
+    /** 距下次重试的秒数(= `ceil(retryInMs/1000)`,core circuit-breaker 与 ms 位同发)。 */
     retryInSec?: number;
+    /** 距下次重试的毫秒数 —— **更精的同一个量**,在场时优先于 `retryInSec`。 */
+    retryInMs?: number;
+    /** 引擎真实的第几次尝试(1-based)。缺席 = 引擎没给,绝不折成 0。 */
+    attempt?: number;
+    /** 引擎这一轮的重试上限。与 `attempt` 一起才能渲「2/5」。 */
+    maxRetries?: number;
 }
-export declare function mapBrainStatusToRetry(p: BrainStatusPayload, nowMs: number): RetryStatus;
+/**
+ * 上面那个 interface 的**运行期键镜像**(照 `TOOL_APPROVAL_FRAME_KEYS_MIRROR` 先例):
+ * engine-vocab 门 G2-c 拿它与 core `BrainStatus` 的键集逐元素比 ⇒ 引擎 additive 增键当天红。
+ * 下面两个类型钉保证镜像与 interface 之间不可能漂移(少键/多键都是编译错)。
+ */
+export declare const BRAIN_STATUS_PAYLOAD_KEYS: readonly ["phase", "detail", "retryInSec", "retryInMs", "attempt", "maxRetries"];
+/**
+ * BrainStatus 载荷 → spinner 行状态。
+ *
+ * 返回 **`null` = 没有覆盖层**(不是「不知道」):今天只有 `recovered` 走这条 —— 引擎明说这次重试
+ * 已经成功,行就该摘掉。此前本函数返回型钉死非空,于是 `recovered` 只能被塞进 error 臂。
+ */
+export declare function mapBrainStatusToRetry(p: BrainStatusPayload, nowMs: number): RetryStatus | null;