@sema-agent/client-core 0.40.0 → 0.42.0

package/dist/hitl/toolApprovalWire.d.ts

@@ -130,8 +130,27 @@ export interface ApprovalCardAllowDecision {
     allowSession: boolean;
     updatedInput?: unknown;
     /** #225 件1:卡上选中的持久规则候选**原文**({@link ApprovalCardRequest.ruleSuggestions} 之一);
-     *  缺席/空串 = 本次不兑付。表外文本会在编排层被丢键留痕(server 亦拒 rule_not_offered)。 */
+     *  缺席/空串 = 本次不兑付。表外文本会在编排层被丢键留痕(server 亦拒 rule_not_offered)。
+     *  ⚠️ 0.42.0 起本位有一个**兄弟位** {@link persistRuleEdited} —— 带上它就是「这段文本是人手改的
+     *  自由文本」,此时本位**不再**要求是候选之一(见该位注)。本位自身的类型与字节一字未动。 */
     persistRule?: string;
+    /**
+     * #225 编辑臂(0.42.0;server #340 `respondFreeFormRules`,[5071] wire 形):{@link persistRule}
+     * 里那段文本是**人在卡上手打/改过的自由文本**,不是帧候选表里的原文。
+     *
+     * 🔴 **缺席 ≠ false**:缺席 = 既有候选臂(表内核对照旧、语义与 0.41.0 逐字节相同);
+     *    `true` = 编辑臂。刻意只收 `true` 一个值(机读位是二值的,「在场但不是 true」没有语义)。
+     * 🔴 **它不是放行凭据**,是**出身声明**:带上它只会让编排层放弃「必须是候选之一」那道表核
+     *    (见 {@link surfaceToolApprovalFrameAndRespond} 的兑付段),真正的判官仍在引擎侧
+     *    (core `confirmRuleApproval` 同函数体)。客户端**绝不**在这里替引擎预判文本合不合法 ——
+     *    在边界复读解析器就是装第二个更严的判官,`Bash(adb *)` 这类肌肉记忆形会被当场误杀
+     *    ([5071] 定界②,core [5075] 复核确认)。要「边打字边校验」请用
+     *    {@link import('./editedRuleTextPrecheck.js').precheckEditedRuleText} 的注入口 —— 那是**引擎
+     *    自己那只**判官,不是第二份。
+     * 🔴 **能力位在场才发**:`true` 而 {@link ToolApprovalFrameLaneOpts.respondFreeFormRulesCapable}
+     *    未确认 ⇒ 编排层**整条丢 persistRule**(决断照送),见该位注。
+     */
+    persistRuleEdited?: true;
 }
 /**
  * deny 决断臂(命名形,typeshape B4 口径;0.28.0 因 `reason` 位抽名,与 0.26.0
@@ -344,7 +363,21 @@ export declare function surfaceApprovalCard(req: ApprovalCardRequest): Promise<A
  *
  * @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>;
+export declare function surfaceFsApprovalAndDecide(deps: FsApprovalWireDeps, taskId: string, argsByCall: Map<string, unknown>, signal?: AbortSignal, 
+/**
+ * 这张 park 的**待批 call 身份**(server ≥7.41.0 的 `done{suspended}.result.toolCallId` /
+ * durable `suspended` 事件同键;供给见 `frameRouter.parkGatedCallId`,缺席是常态)。
+ *
+ * 🔴 它必须从**取件**这一步就起作用,不能只拿去删扣留帧(0.41.0 件④ 的异源复审 finding①):
+ * 取件按 taskId + 族谓词选**第一行**,同 task 同族多行排队时那可能是旁观者 —— 只用身份删帧就成了
+ * split-brain(决断绑的是旁观者行、删掉的是主角帧):用户其实在批准/拒绝**另一个**工具调用,
+ * 而真 park 原地不动、反复重挂。
+ * 🔴 **不 fail-closed**:身份在场但队列里没有对应行时**照旧回落**既有两条腿(taskId + 族谓词)。
+ * 这个 join(checkpoint 的 `pendingAction.toolCallId` ↔ `/v1/approvals` 行的 `toolCallId`/
+ * `boundCallId`)本仓没有对真 server 的实证,而 fail-closed 的失效面是**每一次审批都决断不了**;
+ * 回落的失效面则与本键出现之前逐字节相同。方向按代价不对称取:宁可退回原状,不赌一个没实证的键。
+ */
+parkGatedCallId?: string): Promise<FsApprovalOutcome>;
 /** server 包 src/tool-approval.ts 头注的帧契约(redactDeep + 16KiB 帽;超帽 argsOmitted 仍出帧)。 */
 export interface ToolApprovalFrame {
     type: 'tool_approval' | 'tool_approval_complete';
@@ -584,8 +617,22 @@ export type ToolApprovalRespondDecision = 'allow' | 'allow_session' | 'deny';
 export interface RespondToolApprovalOpts {
     signal?: AbortSignal;
     updatedInput?: unknown;
-    /** #225 件1:兑付键 —— 帧候选之一的**原文**(编排层已做表内核对与 deny 剥除)。 */
+    /** #225 件1:兑付键 —— 帧候选之一的**原文**(编排层已做表内核对与 deny 剥除)。
+     *  ⚠️ 带 {@link persistRuleEdited} 时表核已让位,本位是人手改的自由文本(类型不变)。 */
     persistRule?: string;
+    /**
+     * #225 编辑臂(0.42.0;server #340,[5071]):{@link persistRule} 是**自由文本**而非候选原文。
+     *
+     * 🔴 **注入面的映射义务**(本包只到这一格,wire 体由宿主/SDK 铸):server 的 respond 体形是
+     *    `persistRule: { rule, edited: true }`。本包刻意保持**扁平兄弟位**(`persistRule: string`
+     *    字节不变 + 一个可选布尔),由注入面把两位合成那个嵌套形:
+     *      `persistRule !== undefined ? { rule: persistRule, ...(persistRuleEdited === true ? { edited: true } : {}) } : undefined`
+     *    改成嵌套形会是既有 `persistRule: string` 消费者的 BREAKING,而这一批的纲领是 additive。
+     * 🔴 **缺席 = 候选臂**(server 侧 `rule_not_offered` 语义一字不变);老 server 收到带 `edited`
+     *    的体会诚实降级为 `rule_not_offered`,这正是 [5071] 选这个键名而不是顶层新键的理由
+     *    (顶层新键在老 server 上是静默 200 什么都不落,坏于诚实降级)。
+     */
+    persistRuleEdited?: true;
     /** #229(server ≥7.15.0):回决备注 —— 与 durable 腿 `AskDecisionBody.note` **同词同源同一列**
      *  (`decision_note`,≤2048)。任何 decision 都可带(deny 的「为什么拒」正是审计面上最值钱的
      *  一条);真落行与否看 ack 的 {@link surfaceToolApprovalFrameAndRespond} 消费的 `noteRecorded`。
@@ -615,7 +662,79 @@ export interface ToolApprovalFrameOutcome {
     decision: ToolApprovalRespondDecision | 'unresolved';
     /** server 的 200 ack。**缺席 = 未知**(注入面回 void / 旧 server / respond 失败),绝不当成 false。 */
     ack?: ToolApprovalRespondAck;
+    /**
+     * #225 件5(0.42.0):respond **抛错**那一支的原文交还位。
+     *
+     * 🔴 修的是一条真断链:此前本函数的 catch 只写一行 `debug` 然后返 `{decision:'unresolved'}`,
+     *    于是 server 的响亮 400(`persistRule.rule` 空/超长、`edited` 非布尔、顶层 `scope`、
+     *    `edit-rejected` 的拒句 …… [5071] G4/G5/G6)在**包边界上被吞掉** —— 宿主的错误反馈面
+     *    无论怎么写都拿不到那句话,人在卡上改了规则被拒,屏上什么都不会说。
+     * 🔴 **不改 `decision` 的语义**:`'unresolved'` 仍是 `'unresolved'`(respond 没落定 = 引擎按
+     *    TTL/abort 自决,这一位的含义一字未动);本位是**附加**的诊断面,不是新的决断态。
+     * 🔴 **缺席 = 没有拒绝原文可交**(respond 成功 / 抛的东西上**三位皆读不出**),绝不造一句。
+     *    在场时**三位都可能缺席其二** —— 有 `status` 没文本(应答体为空)、有文本没 `status`
+     *    (传输层失败)都是真实形。
+     */
+    respondRefusal?: ToolApprovalRespondRefusal;
+}
+/**
+ * #225 件5:respond 抛错的**结构化原文**(不是新的决断态,见
+ * {@link ToolApprovalFrameOutcome.respondRefusal})。
+ *
+ * 三位**各自独立**防御读、各自缺席不铸:`status` 只认有限数、`errorCode` 只认非空串、
+ * `message` 只认真读得出来的文本(取值序与 try 保护见 {@link readToolApprovalRespondRefusal})。
+ * 🔴 **三位皆缺席时整只不铸**(异源复审 [medium] 采纳,0.42.0):此前 `message` 是必填、读不出时
+ *    无条件退 `String(err)`,于是 `throw {}` 会得到一句 `"[object Object]"` —— 那不是 server 说的话,
+ *    是本层编的([honest-absence-not-fabricated-zero])。
+ * 🔴 **原样交还,零加工**:不 trim、不截断、不改写、不按识别表过滤。server 的拒句是给人看的
+ *    指路文本([5071] 三条 400 拒句各自成文),包边界任何一次改写都会让宿主呈的不再是引擎说的那句;
+ *    长度夹取与呈现归端(与 `message`/`approver` 同族口径)。
+ * 🔴 **UNTRUSTED-for-display**:它是 HTTP 应答体上的文本,只渲染,绝不回喂模型/工具入参。
+ */
+interface ToolApprovalRespondRefusalFields {
+    /** HTTP 状态(在场 = 引擎真应答了;缺席 = 传输层失败/注入面自抛,不许反推成 0)。 */
+    status?: number;
+    /** 机读码(开集,原样;缺席 = 应答没带码)。 */
+    errorCode?: string;
+    /**
+     * 拒句原文(server 的响亮拒文案)。
+     * 🔴 **缺席 = 这个抛出物上读不出任何可用文本**(异源复审 [medium] 采纳,0.42.0)——
+     *    此前本位是必填、读不出时无条件铸 `String(err)`,于是 `throw {}` 会得到一句
+     *    `"[object Object]"`、`throw null` 得到 `"null"`:那**不是** server 说的话,是本层编的,
+     *    与本形头注承诺的「读不出原文就缺席」直接冲突([honest-absence-not-fabricated-zero])。
+     */
+    message?: string;
 }
+/**
+ * 🔴 **「在场即至少有一位」写进类型**(异源复审 [medium] 采纳,0.42.0):三位全 optional 的
+ * interface 在类型上允许 `{}`,而实现明确承诺「三位皆缺席时整只返 `undefined`」——
+ * 消费端于是既不能依赖「对象在场 = 至少有一条诊断信息」,也没法穷举安全渲染。
+ * 用**三选一联合**把那条运行期不变量抬到编译期:`{}` 从此不可赋值。
+ */
+export type ToolApprovalRespondRefusal = (ToolApprovalRespondRefusalFields & {
+    status: number;
+}) | (ToolApprovalRespondRefusalFields & {
+    errorCode: string;
+}) | (ToolApprovalRespondRefusalFields & {
+    message: string;
+});
+/**
+ * 从 respond 抛出来的东西上读 {@link ToolApprovalRespondRefusal}。**永不抛、永不造**。
+ *
+ * 键位口径与 {@link import('../wireErrorTriage.js').classifyTurnWireError} 同源([2055] 死键
+ * 纪律:只认活键 `errorCode`,退役的 `code` 槽不做兼容)。
+ *
+ * @returns 三位**全缺席**时返回 `undefined` —— 一个三位皆空的 refusal 对象是「有拒句」的假象。
+ *
+ * 🔴 **文本取值序**(异源复审 [medium] 修):`err.message` 非空串 > 抛出物本身是非空串 >
+ *    受保护的 `String(err)`,且**只接受**真有内容的结果 —— `[object Object]` / `null` /
+ *    `undefined` 三种占位串一律当作「读不出」。
+ * 🔴 **`String(err)` 用 try 包住**:抛出物可以自带 `Symbol.toPrimitive` / `toString` 钩子并在里面
+ *    抛错。本函数的唯一调用点在 `surfaceToolApprovalFrameAndRespond` 的 catch 里,那里的契约是
+ *    「respond 失败 ⇒ 返回 unresolved」;让一个不可信的转换钩子把这条收敛路径变成 reject,
+ *    等于给注入面开了一个「让整次审批消费抛出去」的口。
+ */
+export declare function readToolApprovalRespondRefusal(err: unknown): ToolApprovalRespondRefusal | undefined;
 /** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名)。
  *  ⚠️ 口径更正(2026-08-08):此处原写「非 AgentEvent arm」—— SDK #185a 起这两个帧**是**
  *  `AgentEvent` 的臂了(durable 腿也回放),所以结构识别与 union 收窄两条路都成立;本函数仍按
@@ -630,6 +749,16 @@ export interface ToolApprovalFrameLaneOpts {
      * 缺席/false ⇒ 不发(fail-closed 到「不发」侧;决断本身照常送达,现状字节不变)。
      */
     approvalDecisionNoteCapable?: boolean;
+    /**
+     * server 能力位 `capabilities.respondFreeFormRules` 的读数(宿主从自己的 caps 缓存供给;
+     * server ≥7.44,#340 [5071] 恒真版本位)。
+     * 🔴 形与判据**逐字照** {@link approvalDecisionNoteCapable} 既有形(同一条 SDK 6.16 成文纪律:
+     *    **位缺席就别发**)—— 老 server 对未知请求键静默忽略且照回 200,「这台不认识自由文本臂」与
+     *    「记上了」在响应上不可分,发了只造「规则已存」的错觉。
+     * 缺席/false ⇒ 编辑臂的 `persistRule` **整条不发**(fail-closed 到「不发」侧;决断本身照常送达,
+     * 现状字节不变,老引擎零受迫)。候选臂**不受本位影响**(它是 0.25.0 起就有的既有通道)。
+     */
+    respondFreeFormRulesCapable?: boolean;
     /**
      * 这条帧是不是**当下**从 live 流上收到的(异源对抗复审 P1 采纳;壳孪生帧族同名闸的
      * 本包席位 —— 壳 `approvalStreamWire` 头注逐字:「账本重放的历史帧带的是铸帧时刻的旧余量,
@@ -642,3 +771,4 @@ export interface ToolApprovalFrameLaneOpts {
     windowIsCurrent?: boolean;
 }
 export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts): Promise<ToolApprovalFrameOutcome>;
+export {};

package/dist/hitl/toolApprovalWire.js

@@ -221,7 +221,21 @@ function cardPortMissReason() {
  *
  * @param argsByCall tool_start.args(toolCallId → args)——题干/diff 的一手源;缺则 pending.input。
  */
-export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signal) {
+export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signal, 
+/**
+ * 这张 park 的**待批 call 身份**(server ≥7.41.0 的 `done{suspended}.result.toolCallId` /
+ * durable `suspended` 事件同键;供给见 `frameRouter.parkGatedCallId`,缺席是常态)。
+ *
+ * 🔴 它必须从**取件**这一步就起作用,不能只拿去删扣留帧(0.41.0 件④ 的异源复审 finding①):
+ * 取件按 taskId + 族谓词选**第一行**,同 task 同族多行排队时那可能是旁观者 —— 只用身份删帧就成了
+ * split-brain(决断绑的是旁观者行、删掉的是主角帧):用户其实在批准/拒绝**另一个**工具调用,
+ * 而真 park 原地不动、反复重挂。
+ * 🔴 **不 fail-closed**:身份在场但队列里没有对应行时**照旧回落**既有两条腿(taskId + 族谓词)。
+ * 这个 join(checkpoint 的 `pendingAction.toolCallId` ↔ `/v1/approvals` 行的 `toolCallId`/
+ * `boundCallId`)本仓没有对真 server 的实证,而 fail-closed 的失效面是**每一次审批都决断不了**;
+ * 回落的失效面则与本键出现之前逐字节相同。方向按代价不对称取:宁可退回原状,不赌一个没实证的键。
+ */
+parkGatedCallId) {
     // REF-CC-031(2026-08-02):卡口缺席判据不在此前置重复一遍 —— `surfaceApprovalCard`(下方调用)
     // 已经计 miss + 出 typed `{kind:'failed', reason:...}`,card.kind==='failed' 走既有汇流分支
     // (下面 switch 的 'failed' 臂);两处各写一份文案会在 SEMA_DEBUG 里出现两种措辞,取决于走的是
@@ -232,7 +246,11 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
     // 二次 list(),消掉 hitl2-01/hitl2-08 的 TOCTOU 窗。
     // 🔴 常驻判据不是「看得见 pending 这个实参」,是 pure 门那四条「approvals.list 全程恰好 1 次」——
     // 漏传一条腿,形状断言全绿而计数当场翻红(回炉车前的实况:只有 aborted 臂传了)。
-    const found = await findPendingForTask(deps.client, taskId, (toolName) => toolName !== undefined && (toolNameIsFsWrite(toolName) || toolNameIsShellExec(toolName)), signal ? { signal } : undefined);
+    const found = await findPendingForTask(deps.client, taskId, (toolName) => toolName !== undefined && (toolNameIsFsWrite(toolName) || toolNameIsShellExec(toolName)), signal ? { signal } : undefined, parkGatedCallId, // 见本参数头注:身份在场 ⇒ 逐字命中优先于「同族第一行」;缺席/不命中 ⇒ 原两腿
+    // 身份腿的族闸走**整行**判据:本腿的族是 `isToolApprovalGate` 的**两条腿**(一等 kind 放行任意
+    // toolName + fs/shell 名字腿),而上面那个 `matches` 只有名字腿那半 —— 拿它当身份闸会把合法的
+    // kind-only 行判出局(五审 finding①)。gateKind = 行上的扁平投影,与 gate.kind 同一权威。
+    (row) => isToolApprovalGate({ kind: row.gateKind, toolName: row.toolName }));
     if (!found.ok)
         return { kind: 'failed', reason: found.reason };
     const { pending, gatedCallId } = found;
@@ -279,7 +297,9 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         case 'failed':
             return { kind: 'failed', gatedCallId, reason: card.reason };
         case 'aborted':
-            // turn 被中断(Esc/Ctrl+C):cancel-by-deny(contract/04 §2.4)。REF-CC-023(2026-08-02):
+            // turn 被中断(Esc/Ctrl+C):把挂着的 ask 用一次 **TOOL 级 deny** 结算掉(server
+            // `ASSISTANT-WIRE-CONTRACT.md` §4a;0.42.0 撤稿 —— 原文写的是「cancel-by-deny(contract/04
+            // §2.4)」,两条前提均已作废,逐条见 `parkResolver.ts` 同臂的撤稿段)。REF-CC-023(2026-08-02):
             // 有界观察(observeCancelByDeny)取代裸 `.catch(()=>{})` 全吞 —— 与 askGateWire.ts 同款
             // reason 文案,同一次事故(件3,中断事故修复批 G,2026-07-15)的两条腿现在共用同一个观察器。
             observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: 'Interrupted by user' }, gatedCallId, undefined, pending), taskId);
@@ -497,6 +517,88 @@ export function readToolApprovalRespondAck(v) {
         ...(typeof o.noteRecorded === 'boolean' ? { noteRecorded: o.noteRecorded } : {}),
     };
 }
+/**
+ * 从 respond 抛出来的东西上读 {@link ToolApprovalRespondRefusal}。**永不抛、永不造**。
+ *
+ * 键位口径与 {@link import('../wireErrorTriage.js').classifyTurnWireError} 同源([2055] 死键
+ * 纪律:只认活键 `errorCode`,退役的 `code` 槽不做兼容)。
+ *
+ * @returns 三位**全缺席**时返回 `undefined` —— 一个三位皆空的 refusal 对象是「有拒句」的假象。
+ *
+ * 🔴 **文本取值序**(异源复审 [medium] 修):`err.message` 非空串 > 抛出物本身是非空串 >
+ *    受保护的 `String(err)`,且**只接受**真有内容的结果 —— `[object Object]` / `null` /
+ *    `undefined` 三种占位串一律当作「读不出」。
+ * 🔴 **`String(err)` 用 try 包住**:抛出物可以自带 `Symbol.toPrimitive` / `toString` 钩子并在里面
+ *    抛错。本函数的唯一调用点在 `surfaceToolApprovalFrameAndRespond` 的 catch 里,那里的契约是
+ *    「respond 失败 ⇒ 返回 unresolved」;让一个不可信的转换钩子把这条收敛路径变成 reject,
+ *    等于给注入面开了一个「让整次审批消费抛出去」的口。
+ */
+export function readToolApprovalRespondRefusal(err) {
+    // 🔴 **取属性本身就可能抛**(异源复审 [medium] 的形比它自己说的还宽一档,施工时实撞):
+    //    抛出物可以是一个带 `get message() { throw }` 的对象 —— 连 `typeof e.message` 这一步都会炸,
+    //    根本走不到下面的转换。所以逐位读**各自**包 try,读不动就当那一位缺席。
+    const pick = (key) => {
+        try {
+            return err?.[key];
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const rawStatus = pick('status');
+    const rawCode = pick('errorCode');
+    const status = typeof rawStatus === 'number' && Number.isFinite(rawStatus) ? rawStatus : undefined;
+    const errorCode = typeof rawCode === 'string' && rawCode.length > 0 ? rawCode : undefined;
+    const message = refusalTextOf(err, pick('message'));
+    if (status === undefined && errorCode === undefined && message === undefined)
+        return undefined;
+    const rest = {
+        ...(status !== undefined ? { status } : {}),
+        ...(errorCode !== undefined ? { errorCode } : {}),
+        ...(message !== undefined ? { message } : {}),
+    };
+    // 三选一联合的**构造侧证明**:哪一位在场就从哪一位收窄(与上面的 early-return 合起来,
+    // 「至少有一位」在编译期与运行期是同一条不变量,不是两份各自维护的承诺)。
+    if (status !== undefined)
+        return { ...rest, status };
+    if (errorCode !== undefined)
+        return { ...rest, errorCode };
+    return { ...rest, message: message };
+}
+/** 无信息量的占位串:`String()` 对这几类抛出物的产物,它们不是「拒句」。 */
+const USELESS_REFUSAL_TEXTS = new Set(['[object Object]', 'null', 'undefined', '']);
+/** 见 {@link readToolApprovalRespondRefusal} 的取值序与 try 保护。读不出 ⇒ `undefined`。 */
+function refusalTextOf(err, message) {
+    if (typeof message === 'string' && message.length > 0)
+        return message;
+    if (typeof err === 'string' && err.length > 0)
+        return err;
+    let coerced;
+    try {
+        coerced = String(err);
+    }
+    catch {
+        // 不可信的 toString/Symbol.toPrimitive 钩子抛了 —— 诚实缺席,绝不让它逃出 catch。
+        return undefined;
+    }
+    return USELESS_REFUSAL_TEXTS.has(coerced) ? undefined : coerced;
+}
+/**
+ * 机读码的**日志安全形**(异源复审 [medium] 采纳,0.42.0):`errorCode` 来自 UNTRUSTED 应答体且
+ * 无长度/控制字符/换行约束,把它原样插进宿主日志 = 可伪造日志行、可注入终端控制序列、还能把一段
+ * 服务端正文当「码」漏进 sink。
+ *
+ * 🔴 **只有形合的才照写**(真机读码的字符集):`[A-Za-z0-9._:-]{1,64}`。形不合 ⇒ 只报**长度**,
+ *    正文一个字节都不进日志(与本文件 note 那条「留痕只写元数据」逐字同纪律)。
+ * 🔴 这**不影响**交还调用方的那一份:{@link ToolApprovalRespondRefusal.errorCode} 仍是**原样**
+ *    ——净化的是日志这条外溢面,不是契约。
+ */
+const MACHINE_CODE_SHAPE = /^[A-Za-z0-9._:-]{1,64}$/;
+function logSafeErrorCode(code) {
+    if (code === undefined)
+        return 'none';
+    return MACHINE_CODE_SHAPE.test(code) ? code : `<unprintable len=${code.length}>`;
+}
 /** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名)。
  *  ⚠️ 口径更正(2026-08-08):此处原写「非 AgentEvent arm」—— SDK #185a 起这两个帧**是**
  *  `AgentEvent` 的臂了(durable 腿也回放),所以结构识别与 union 收窄两条路都成立;本函数仍按
@@ -732,9 +834,33 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         // 按表拒(rule_not_offered),这道核对把坏卡口实现挡在包边界并留痕(丢键不丢决断:人的
         // allow/deny 已经落定,一条对不上的规则文本不该反过来污染整次回决)。deny 恒不带(server
         // 宽收后忽略,发了只留「像是记住了」的错觉)。
+        //
+        // ── #225 编辑臂(0.42.0,[5071] wire 形):自由文本时**表核让位**,但能力位缺席就别发 ────────
+        // 🔴 让位的判据锚在**出身声明** `card.persistRuleEdited === true`,不锚「文本恰好不在表里」——
+        //    后者会让一个坏卡口实现(拼错了候选原文)自动升级成「自由文本臂」,把这道核对彻底架空。
+        // 🔴 让位的**理由**:表核的全部意义是「绝不把没被 offer 过的文本送进规则店」,而编辑臂的定义
+        //    就是人自己打的文本 —— 对它做表核,等于把这条 wire 上刚开出来的能力在包边界原样关掉
+        //    ([5111] 探针实测的闭集三处之②:自由文本恒丢键)。真判官在引擎侧同一函数体
+        //    (core `confirmRuleApproval`),不在这里。
+        // 🔴 能力位闸(`lane.respondFreeFormRulesCapable`)与 note 那条**同一条纪律**:位缺席就别发。
+        //    编辑臂在老 server 上会诚实降级 `rule_not_offered`(不是静默 200),但那仍然是一次
+        //    「人以为存上了、其实拿回一个拒绝」的往返 —— 能提前知道这台不供,就别把人的编辑送出去。
         let persistRule;
+        let persistRuleEdited;
         if (card.kind === 'allow' && typeof card.persistRule === 'string' && card.persistRule !== '' && decision !== 'deny') {
-            if (ruleSuggestions?.some(sug => sug.rule === card.persistRule) === true) {
+            const edited = card.persistRuleEdited === true;
+            if (edited) {
+                if (lane?.respondFreeFormRulesCapable === true) {
+                    persistRule = card.persistRule;
+                    persistRuleEdited = true;
+                }
+                else {
+                    hostLog('debug', `liveToolApprovalWire: DROPPING edited persistRule for ${frame.approvalId} (len=${card.persistRule.length}) — the ` +
+                        'respondFreeFormRules capability is not confirmed for this engine, so the free-form arm is not sent at all ' +
+                        '(the decision itself still goes through unchanged)');
+                }
+            }
+            else if (ruleSuggestions?.some(sug => sug.rule === card.persistRule) === true) {
                 persistRule = card.persistRule;
             }
             else {
@@ -745,6 +871,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
             ...(signal && !signal.aborted ? { signal } : {}),
             ...(card.kind === 'allow' && card.updatedInput !== undefined ? { updatedInput: card.updatedInput } : {}),
             ...(persistRule !== undefined ? { persistRule } : {}),
+            ...(persistRuleEdited !== undefined ? { persistRuleEdited } : {}),
             ...(note !== undefined ? { note } : {}),
         });
         // 🔴 相关性门(对抗复审二轮):ack 必须是**这一次**审批的回执 —— id 与决断词都要对上。
@@ -783,7 +910,17 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         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 { decision: 'unresolved' };
+        // #225 件5(0.42.0):**原文交还调用方**,不再只留一行 debug 就把它吞掉。
+        // 🔴 `decision:'unresolved'` 逐字保留(respond 没落定这件事没变);新增的只是 `respondRefusal`
+        //    这一格诊断面 —— 宿主拿它去渲「你的规则被拒了,引擎说:…」,而不是把一次响亮 400 呈成
+        //    「什么也没发生」([5111] 探针实测的闭集三处之③)。
+        // 🔴 留痕仍只写**元数据**(状态码 + 码 + 长度),正文不进日志:它是 UNTRUSTED 的应答体文本,
+        //    回喂宿主 sink 零诊断增量、还是外溢面(与 note 那条同一条纪律)。
+        const respondRefusal = readToolApprovalRespondRefusal(e);
+        hostLog('debug', `liveToolApprovalWire: respond(${decision}) failed for ${frame.approvalId} ` +
+            `(status=${respondRefusal?.status ?? 'none'} errorCode=${logSafeErrorCode(respondRefusal?.errorCode)} ` +
+            `messageLen=${respondRefusal?.message?.length ?? 0}) — engine self-settles (TTL/abort); ` +
+            'the refusal text is handed back on outcome.respondRefusal for the host to surface');
+        return respondRefusal !== undefined ? { decision: 'unresolved', respondRefusal } : { decision: 'unresolved' };
     }
 }

package/dist/index.d.ts

@@ -224,6 +224,7 @@ export { toolEndOutputText, ENGINE_ABORT_TOOL_RESULT } from './hitl/frameRouter.
 export { isAskTool } from './hitl/frameRouter.js';
 export * from './hitl/hitlHostSurface.js';
 export * from './hitl/toolApprovalWire.js';
+export * from './hitl/editedRuleTextPrecheck.js';
 export * from './hitl/askGateWire.js';
 export * from './hitl/planReviewWire.js';
 export * from './hitl/gateIdentity.js';

package/dist/index.js

@@ -326,6 +326,13 @@ export { toolEndOutputText, ENGINE_ABORT_TOOL_RESULT } from './hitl/frameRouter.
 export { isAskTool } from './hitl/frameRouter.js';
 export * from './hitl/hitlHostSurface.js';
 export * from './hitl/toolApprovalWire.js';
+// ── #225 编辑臂预检的转出口([5076] 自领件,0.42.0)————————————————————————————————————
+// core 5.57.0 导出了 `precheckEditedRuleText`(与 `confirmRuleApproval` **同一函数体**的 text×command
+// 三步门)。本包**不能**做 value 级 re-export —— `@sema-agent/core` 的 barrel 值级拉 `node:crypto`/
+// `node:fs`/`node:path`,而 portability 门的 `EXPECTED_PACKAGES_INDEX` 是等值门 + ③ 段拿 esbuild
+// `--platform=browser` 真打包,一条这样的边会把整台引擎焊进 web/desktop 的产物。
+// ⇒ 转出口取「类型面 + 注入口 + 诚实缺席读口」三件(逐条理由见模块头注)。
+export * from './hitl/editedRuleTextPrecheck.js';
 export * from './hitl/askGateWire.js';
 export * from './hitl/planReviewWire.js';
 // ── A-028.2/.3(#244 族A,2026-08-12):决断卡链的键词汇/呈现台账/归属判据三件 ————————————

package/dist/model/catalogLoader.js

@@ -234,10 +234,41 @@ export async function loadCatalogWithSources(opts) {
     const timeoutMs = opts?.timeoutMs ?? DEFAULT_CATALOG_TIMEOUT_MS;
     const attempts = [];
     const warnings = [];
-    let hit = null;
     let lastDialed;
+    // ── 委托:载荷判决 / 三层合并 / 来源标注全在 resolveModelCatalog ──────────────────────────
+    // 传给它的 `fetchJson` 只是「把已经拿到的这一份交出去」的闭包 —— 候选链与传输门是本文件的活,
+    // 校验与合并是它的活,两边不重叠也不互相重写。
+    const resolveWith = async (p) => {
+        const onlineUrl = p?.url ?? lastDialed ?? sources[0];
+        const resolveOpts = {
+            ...(onlineUrl !== undefined ? { onlineUrl } : {}),
+            fetchJson: async () => {
+                if (p === null)
+                    throw new Error(`all ${sources.length} catalog source(s) failed; see attempts[]`);
+                return p.doc;
+            },
+            ...(opts?.overrides !== undefined ? { overrides: opts.overrides } : {}),
+            ...(opts?.nowMs !== undefined ? { nowMs: opts.nowMs } : {}),
+        };
+        return resolveModelCatalog(resolveOpts);
+    };
+    // ══ 🔴 [4982] 候选② 的**同形存量**(0.42.0 异源复审 [high] 采纳)══════════════════════════
+    //
+    // 病根与「缓存腿从没被问过」是**同一条**:候选链的停止判据锚在**传输层**(`hit !== null`)而不是
+    // **内容判决**。后果比缓存那一格更重 —— 首源发得下来但内容不合格时,`break` 让**后续健康源
+    // 永远不会被请求**:一次坏发布、或一个 CDN 的半更新窗,就能把整条后备链压掉。
+    // ⇒ 停止判据换成 `accepted !== null`(内容判决),逐源「传输 → 旁签 → **内容校验**」,
+    //   只有真被接受的那一份才停链。
+    //
+    // 🔴 `rejected` 是**诚实兜底**不是备选源:全链都被拒时,拿**第一份被拒的**去出结果,
+    //    这样 `online.reason` 说的是真话(`schema-version-unsupported`),而不是退成
+    //    「一个源都没连上」(`fetch-failed`)—— 那会把「内容坏了」谎报成「网络坏了」。
+    //    它**绝不**参与「用哪份目录」的竞争:被拒就是被拒,`online.ok === false` 时合并结果本就
+    //    回落内置表。
+    let accepted = null;
+    let rejected = null;
     for (const src of sources) {
-        if (hit !== null)
+        if (accepted !== null)
             break;
         const got = await guardedGet(src, allowedHosts, fetchImpl, timeoutMs);
         if (got.outcome !== 'insecure-url' && got.outcome !== 'host-not-allowed')
@@ -289,7 +320,17 @@ export async function loadCatalogWithSources(opts) {
             warnings.push(`catalog sha256 sidecar unavailable for ${finalUrl} (${shaGot.outcome}) — payload accepted without the checksum`);
         }
         attempts.push({ url: src, outcome: 'ok', ...(got.status !== undefined ? { status: got.status } : {}), shaChecked });
-        hit = { url: finalUrl, doc, raw: got.text, shaChecked };
+        const candidate = { url: finalUrl, doc, raw: got.text, shaChecked };
+        // 内容判决就在这里做 —— 传输成功**不等于**这份目录能用。
+        const verdict = await resolveWith(candidate);
+        if (verdict.online.ok) {
+            accepted = { hit: candidate, base: verdict };
+            continue;
+        }
+        if (rejected === null)
+            rejected = { hit: candidate, base: verdict };
+        warnings.push(`catalog source ${finalUrl} was fetched but REJECTED by content validation ` +
+            `(${verdict.online.reason ?? 'unknown'}) — trying the next source`);
     }
     // ── 缓存腿(口缺席 ⇒ 整条不启用,cacheHit 键缺席)────────────────────────────────────────
     const cache = opts?.cache;
@@ -297,7 +338,15 @@ export async function loadCatalogWithSources(opts) {
     let cacheHit = cache !== undefined ? false : undefined;
     let cacheStale;
     let cachedSourceUrl;
-    if (hit === null && cache !== undefined && cachePath !== undefined) {
+    /**
+     * 读一次缓存信封 → `SourceHit`(+ 陈旧判)。**永不抛**;坏形/缺件记 warn 返 null。
+     * 🔴 [4982] 候选②(0.42.0)提出来的:此前这段是内联的,只有「传输全败」那一条路走得到它。
+     *    现在有**两个**调用点(传输全败 / 传输 ok 但内容被拒),提成一处才不会有两份读法。
+     *    `alreadyWarned` = 第二次调用时不重复堆同一批 warn(同一份坏缓存说两遍是噪音)。
+     */
+    const readCachedHit = async (alreadyWarned) => {
+        if (cache === undefined || cachePath === undefined)
+            return null;
         let text = null;
         let readError;
         try {
@@ -306,52 +355,109 @@ export async function loadCatalogWithSources(opts) {
         catch (e) {
             readError = shortError(e);
         }
-        if (readError !== undefined)
+        if (readError !== undefined && !alreadyWarned)
             warnings.push(`catalog cache read failed: ${readError}`);
-        if (typeof text === 'string' && text.length > 0) {
-            let env;
-            let envError;
-            try {
-                env = JSON.parse(text);
-            }
-            catch (e) {
-                envError = shortError(e);
-            }
-            if (envError !== undefined)
+        if (typeof text !== 'string' || text.length === 0)
+            return null;
+        let env;
+        let envError;
+        try {
+            env = JSON.parse(text);
+        }
+        catch (e) {
+            envError = shortError(e);
+        }
+        if (envError !== undefined) {
+            if (!alreadyWarned)
                 warnings.push(`catalog cache is not parsable JSON (ignored): ${envError}`);
-            const doc = env?.catalog;
-            const url = env?.sourceUrl;
-            if (doc !== undefined && typeof url === 'string' && url.length > 0) {
-                // 缓存里那份**就是**当初的线上载荷 —— 照样过 validateOnlineCatalog(下面同一条路),
-                // 不给它开后门:一份当年合法、今天已超区间的文档必须照样被拒。
-                hit = { url, doc, raw: text, shaChecked: false };
-                cacheHit = true;
-                cachedSourceUrl = url;
-                if (opts?.nowMs !== undefined && typeof env?.fetchedAt === 'number') {
-                    cacheStale = opts.nowMs - env.fetchedAt > CATALOG_CACHE_STALE_MS;
-                }
-            }
-            else if (envError === undefined) {
+            return null;
+        }
+        const doc = env?.catalog;
+        const url = env?.sourceUrl;
+        if (doc === undefined || typeof url !== 'string' || url.length === 0) {
+            if (!alreadyWarned)
                 warnings.push('catalog cache envelope missing sourceUrl/catalog (ignored)');
-            }
+            return null;
         }
-    }
-    // ── 委托:载荷判决 / 三层合并 / 来源标注全在 resolveModelCatalog ──────────────────────────
-    // 传给它的 `fetchJson` 只是「把已经拿到的这一份交出去」的闭包 —— 候选链与传输门是本文件的活,
-    // 校验与合并是它的活,两边不重叠也不互相重写。
-    const payload = hit;
-    const onlineUrl = payload?.url ?? lastDialed ?? sources[0];
-    const resolveOpts = {
-        ...(onlineUrl !== undefined ? { onlineUrl } : {}),
-        fetchJson: async () => {
-            if (payload === null)
-                throw new Error(`all ${sources.length} catalog source(s) failed; see attempts[]`);
-            return payload.doc;
-        },
-        ...(opts?.overrides !== undefined ? { overrides: opts.overrides } : {}),
-        ...(opts?.nowMs !== undefined ? { nowMs: opts.nowMs } : {}),
+        // 缓存里那份**就是**当初的线上载荷 —— 照样过 validateOnlineCatalog(下面同一条路),
+        // 不给它开后门:一份当年合法、今天已超区间的文档必须照样被拒。
+        const stale = opts?.nowMs !== undefined && typeof env?.fetchedAt === 'number'
+            ? opts.nowMs - env.fetchedAt > CATALOG_CACHE_STALE_MS
+            : undefined;
+        return {
+            hit: { url, doc, raw: text, shaChecked: false },
+            ...(stale !== undefined ? { stale } : {}),
+        };
     };
-    const base = await resolveModelCatalog(resolveOpts);
+    // ══ 缓存腿:**内容判决**缺席时才问它(传输全败 与 内容被拒 两条路共用这一格)═══════════════
+    //
+    // 🔴 [4982] 候选②(P0-KPI,0.42.0):此前这条腿的门槛是 `hit === null`,而 `hit` 只记录**传输层**
+    //    结果(200 + 旁签过就算 hit)。于是「线上目录发得下来、但内容被 validateOnlineCatalog 拒」
+    //    这条缝里,loader 认为「有 hit」⇒ **永不查缓存**(即便缓存里躺着一份上次真正被接受过的
+    //    合法目录),用户只拿到内置精简表;而 `cacheHit:false` 这个**诚实位反过来说谎** —— 它读起来
+    //    是「没有缓存」,真相是「有缓存,但从头到尾没人问过它」。
+    //    判据锚在**真正决定结果的量**上:决定「用不用得上目录」的是**内容判决**(`accepted`),
+    //    不是传输判决(`hit !== null`)。异源复审 [high] 之后,候选链的停止判据也换成了同一个量
+    //    (见上方 `accepted` 头注)—— 两处同根同治,不留同形存量。
+    // 🔴 缓存那份**不开后门**:它照样过同一个 `resolveModelCatalog`。也被拒时**不拿它顶替**
+    //    (一份同样不合格的文档顶替不了什么),`cacheHit` 诚实留在 `false` —— 本位的语义是
+    //    「这次的目录**是从缓存来的**」,不是「问过缓存」;抬成 true 会让「缓存救场了」与
+    //    「缓存也坏了」在读数上不可分。「问过但没用上」那件事由 warning 说。
+    /**
+     * 线上腿的**归因汇总**(异源复审 [medium] 采纳,0.42.0)。
+     *
+     * 🔴 修的是一句会指错方向的话:此前只要**任一**源产生 `rejected`,回落 warning 就写
+     *    「every online catalog source was fetched but REJECTED」。而其余源完全可能是网络失败、
+     *    畸形 JSON、sha 不匹配、或被域白名单挡下 —— 把一次 CDN/网络事故说成「目录发布损坏」,
+     *    运维会照着错误方向查,恢复时间平白变长。
+     * ⇒ 按 `attempts` 的**真实计数**分两类措辞:全部进过内容校验且全被拒 ⇒ 说 "every … REJECTED";
+     *   混合故障 ⇒ 逐类报数,并保留内容拒绝的 reason。
+     */
+    const onlineLegSummary = () => {
+        const contentRejected = attempts.filter((a) => a.outcome === 'ok').length;
+        const otherFailures = attempts.length - contentRejected;
+        const reason = rejected?.base.online.reason ?? 'unknown';
+        if (otherFailures === 0 && contentRejected > 0) {
+            return `every online catalog source (${contentRejected}) was fetched but REJECTED by content validation (${reason})`;
+        }
+        return (`the online catalog leg failed in more than one way: ${contentRejected} source(s) were fetched but ` +
+            `REJECTED by content validation (${reason}), ${otherFailures} source(s) failed before content ` +
+            'validation (transport / integrity / policy — see attempts[])');
+    };
+    let cached = null;
+    if (accepted === null)
+        cached = await readCachedHit(false);
+    let payload;
+    let base;
+    if (accepted !== null) {
+        payload = accepted.hit;
+        base = accepted.base;
+    }
+    else if (cached !== null) {
+        const fromCache = await resolveWith(cached.hit);
+        if (fromCache.online.ok) {
+            payload = cached.hit;
+            base = fromCache;
+            cacheHit = true;
+            cachedSourceUrl = cached.hit.url;
+            if (cached.stale !== undefined)
+                cacheStale = cached.stale;
+            if (rejected !== null)
+                warnings.push(`${onlineLegSummary()} — fell back to the cached catalog (${cached.hit.url})`);
+        }
+        else {
+            // 缓存那份也不合格 ⇒ 诚实回落:`online` 报的仍是**线上腿自己**的判词(有被拒的那一份就用
+            // 它的,一个都没连上就是 fetch-failed),绝不拿缓存的判词冒充线上的。
+            payload = rejected?.hit ?? null;
+            base = rejected?.base ?? (await resolveWith(null));
+            warnings.push(`${onlineLegSummary()}, and the cached catalog was rejected by content validation too — ` +
+                'falling back to the built-in table');
+        }
+    }
+    else {
+        payload = rejected?.hit ?? null;
+        base = rejected?.base ?? (await resolveWith(null));
+    }
     // 线上腿真的被接受了才写缓存(被 validateOnlineCatalog 拒掉的载荷绝不进缓存 ——
     // 否则下一次断网时我们会把一份已知不合格的文档当兜底)。
     if (base.online.ok && payload !== null && cacheHit !== true && cache !== undefined && cachePath !== undefined) {