@sema-agent/client-core 0.51.0 → 0.53.0

package/dist/classifierVerdictWire.js

@@ -94,6 +94,117 @@ export function classifierDenyFromToolEnd(ev) {
     const reason = tail.startsWith(': ') ? tail.slice(2).trim() : undefined;
     return { message, ...(reason !== undefined && reason.length > 0 ? { reason } : {}) };
 }
+// ── L-69⑨(0.52.0):被拒行的**行文案判定**(三端同形)────────────────────────────────────────
+/**
+ * {@link classifierDenyDisplay} 的返回上界(字符数,含末尾省略号)。
+ *
+ * 🔴 为什么必须有界:入参 `args` 是**模型产出**的工具入参(UNTRUSTED),`Bash.command` 与
+ *    `Write.file_path` 都可以是任意长度的串。呈现面(cli 的 /permissions Recent Denials 是一行、
+ *    `wrap="truncate"`)自己也会截,但**库不许交出一个没有上限的串** —— 端把它塞进别的容器
+ *    (通知行、日志、剪贴板)时那道呈现截断就不在了。
+ * 🔴 **本上界量的是「交出去的原文长度」,不是端渲出来那一行的最终宽度**(异源对抗复审 R1
+ *    finding③ 采纳的措辞订正):控制符 / 双向符 / 换行的可见化是**展示消毒**,归端
+ *    (cli `cleanUntrustedForDisplay`),而消毒会**变长** —— 200 个 ESC 在这里长度是 200,端把它们
+ *    逐个转成 `\u001B` 之后是 1200。⇒ **端在自己消毒之后必须再按自己的行宽兜一次底**,别把本常量
+ *    读成「拿到手就一定不超过 200 个显示格」。
+ * 🔴 那为什么库不干脆先消毒再截(那样最终宽度就守得住)?因为消毒的字符集只能有**一份**:库里消
+ *    一遍、端再消一遍,两份字符集必然漂([machine-readable-signal-not-visual-anchor] 同族),而
+ *    端那一份还要管别的载体(hook 名 / fleet 行标签)。分工是刻意的:库守「原文不无限长」,
+ *    端守「渲出来那一行不超宽」。
+ */
+export const CLASSIFIER_DENY_DISPLAY_MAX = 200;
+/**
+ * 每只工具「拿哪个入参当行文案」的表(逐字锚 CC/sema 的工具入参键名,实测直证 sema-cli
+ * `src/tools/*`:`BashTool` = `command`、`FileReadTool`/`FileWriteTool`/`FileEditTool` = `file_path`、
+ * `NotebookEditTool` = **`notebook_path`**)。
+ *
+ * 🔴 `NotebookEdit` 的键**不是** `file_path`(它是 `notebook_path`)—— 写成 `file_path` 不会报错,
+ *    只会让这只工具**永远**落回工具名兜底,而那正好和「没实现」长得一模一样(静默无效)。
+ * 🔴 键名归一按 `toolNameKey`(去空白/下划线/连字符 + 小写),与本仓 `toolNameIsFsWrite` /
+ *    `toolNameIsShellExec` 的归一姿势逐字同款 —— 引擎侧工具名的书写形不由本包决定。
+ * 🔴 表**外**的工具一律回落工具名:这是一张**识别表**,不是「合法工具只有这些」
+ *    (`engineErrorCodes` 的开集纪律同族)。
+ */
+const DISPLAY_ARG_KEY_BY_TOOL = new Map([
+    ['bash', 'command'],
+    ['read', 'file_path'],
+    ['fileread', 'file_path'],
+    ['write', 'file_path'],
+    ['filewrite', 'file_path'],
+    ['edit', 'file_path'],
+    ['fileedit', 'file_path'],
+    ['multiedit', 'file_path'],
+    ['notebookedit', 'notebook_path'],
+]);
+/** 工具名归一(与 `hitl/toolApprovalWire.ts` 的两个谓词逐字同款)。 */
+function toolNameKey(name) {
+    return name.replace(/[\s_-]+/g, '').toLowerCase();
+}
+/**
+ * 一条分类器拒绝行的**显示名**:三端同形的「这一行说的是哪条命令 / 哪个文件」判定。
+ *
+ * 为什么在库里(而不是各端自己拼):端要渲的是同一件事(Recent Denials 行 / 通知行 / retry 提示),
+ * 判据(读哪个入参键、什么算「在场」、上界多少)三端各写一遍必然各错一遍;而这是**纯判定**、零 IO、
+ * 零展示——正合本包的归层。
+ *
+ * 判据(逐条):
+ *   · `Bash` ⇒ `args.command`;`Read`/`Write`/`Edit`/`MultiEdit` ⇒ `args.file_path`;
+ *     `NotebookEdit` ⇒ `args.notebook_path`(见 {@link DISPLAY_ARG_KEY_BY_TOOL});表外工具 ⇒ 工具名;
+ *   · 取到的值**必须是非空串**(trim 后非空)——非串 / 缺席 / 空串 / 纯空白一律回落工具名。
+ *     🔴 回落**不是**「渲一个空行」:一个空的显示名会让那一行看起来像坏了,而工具名至少是真的;
+ *   · 工具名自身为空 ⇒ `'tool'`(与同文件 {@link classifierDenyNoticeText} 的兜底逐字同款);
+ *   · 结果长度上界 {@link CLASSIFIER_DENY_DISPLAY_MAX}(超出 ⇒ 截到上界、末位换 `…`)。
+ *
+ * 🔴 **绝不**在这里做展示消毒(控制符/双向符/换行)——那是端的事,理由见
+ *    {@link CLASSIFIER_DENY_DISPLAY_MAX} 头注。返回值仍然是 **UNTRUSTED-for-display**。
+ * 🔴 本函数**不**回答 retry 粒度:重试哪一只调用、按什么规则铸,是端侧规则面的事
+ *    (身份锚 = `ClassifierDenyContext.toolCallId`)。
+ */
+export function classifierDenyDisplay(toolName, args) {
+    const fallback = toolName.length > 0 ? toolName : 'tool';
+    const key = DISPLAY_ARG_KEY_BY_TOOL.get(toolNameKey(toolName));
+    if (key === undefined)
+        return bounded(fallback);
+    if (args === null || typeof args !== 'object')
+        return bounded(fallback);
+    const raw = args[key];
+    if (typeof raw !== 'string' || raw.trim().length === 0)
+        return bounded(fallback);
+    return bounded(raw);
+}
+/**
+ * 上界裁剪(超限 ⇒ 截到上界、末位换 `…`;与 {@link classifierDenyNoticeText} 的截法同形)。
+ *
+ * 🔴 **本函数守的是「截断不制造畸形」,不是「输出一定 well-formed」**(措辞由异源对抗复审 R2
+ *    finding 订正 —— 上一版写成「绝不交出孤代理项」是**过度声称**)。两件事必须分开:
+ *      · **截断制造的**孤高代理项 = 本函数的责任。`slice` 按 UTF-16 码元切,边界正好落在一个 emoji /
+ *        星平面字符的**代理对中间**时,交出去的是一个本来不存在的畸形串 —— 那是本层自己弄坏的,
+ *        必须自己不弄坏(少切一个码元、结果短一格)。
+ *      · **输入里本来就有的**孤代理项(高或低)= **原样透出**,与本文件其余 UNTRUSTED 位一个待遇。
+ *        `JSON.parse('"\ud800"')` 完全合法,所以这种入参是真实存在的;而把它「修好」就是**展示消毒**
+ *        —— 那一份在本包里已有唯一真源:{@link escapeDisplayControlChars}(`fleetTaskDesc.ts`,公面导出),
+ *        它的头注逐字点名这一族:「孤代理项:上游可能本来就送半只,或被列宽截断劈开」。在这里再消一遍
+ *        = 第二份字符集,正是那条单源纪律要防的事。
+ * 🔴 因此只回退**末位的高代理项**这一形:那是本函数唯一可能自己造出来的畸形(切的永远是前缀,
+ *    所以断口只在尾部)。末位是低代理项 ⇒ 要么它的高位还在串里(配对完整),要么它在输入里本来就是
+ *    孤的(上一条,原样透出)。
+ * 🔴 组合记号 / 变体选择符 / ZWJ 序列被切开只是「显示成两个字」,仍是合法 Unicode —— 本函数不做
+ *    字素簇分段(那要一整份 grapheme 表,且属于**渲染**面,与本文件的分工线一致)。
+ */
+function bounded(s) {
+    if (s.length <= CLASSIFIER_DENY_DISPLAY_MAX)
+        return s;
+    const keep = CLASSIFIER_DENY_DISPLAY_MAX - 1;
+    let cut = s.slice(0, keep);
+    const last = cut.charCodeAt(cut.length - 1);
+    // 🔴 只有「末位是高代理项 **且** 原串紧接着的那个码元是低代理项」才是被截断劈开的合法代理对(本层
+    //    自己造的畸形,少切一格);末位高代理项后面跟的不是低代理项 ⇒ 它在输入里本来就是孤的 ⇒ 原样透出
+    //    (对抗复审 r3 [medium]:无条件回退会静默删掉输入自带的孤高代理项,违反上面的分工线)。
+    const next = s.charCodeAt(keep);
+    if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff)
+        cut = cut.slice(0, -1);
+    return `${cut}\u2026`;
+}
 /** 通知行文案(exported for tests;CC 207 三段 text 化)。 */
 export function classifierDenyNoticeText(toolName, reason) {
     let r = reason ?? '';

package/dist/hitl/frameRouter.js

@@ -378,7 +378,16 @@ const TOOL_END_ARMS = [
                 return undefined;
             led.markEnded(callId);
             led.dropHeld(callId);
-            surfaceForCurrentSession()?.surfaceClassifierDeny(typeof ev.toolName === 'string' ? ev.toolName : 'tool', verdict);
+            // L-69⑨(0.52.0):把**这一只 call 的现场**一并交给宿主 —— 修前只给 `toolName`,于是端的
+            // Recent Denials 三行同名(三条被拒的 Bash 一个样)、retry 粒度只能落到「整个工具」。
+            // 🔴 args 是 **UNTRUSTED** wire 值:本层原样搬运(不渲不截不消毒),展示消毒归端。
+            // 🔴 args 取自**在飞表**(`noteStart`,每张 tool_start 都记、有界、收口即删)——`gatedStartArgs`
+            //    在这里读不到:分类器 deny 的工具通常**没被 gate**(引擎侧分类器直接 block,一张
+            //    tool_approval 帧都不出),那张表里根本没有它。
+            // 🔴 缺席不铸键(`exactOptionalPropertyTypes`):台账里没有 ⇒ `ctx` 只带 `toolCallId`,
+            //    端读到的是诚实缺席,不是「args 是 undefined」。
+            const startArgs = led.startArgs().get(callId);
+            surfaceForCurrentSession()?.surfaceClassifierDeny(typeof ev.toolName === 'string' ? ev.toolName : 'tool', verdict, { toolCallId: callId, ...(startArgs !== undefined ? { args: startArgs } : {}) });
             hostLog('debug', `liveHitlAskWire: classifier deny verdict on ${callId} (${String(ev.toolName)}) — labeled render + notice`);
             return { kind: 'yield', events: [{ ...ev, output: verdict.message, structured: undefined }] };
         },
@@ -528,6 +537,15 @@ async function routeToolApprovalFrame(ev, ctx) {
     return { kind: 'skip' };
 }
 function routeToolStart(ev, callId, led) {
+    // L-69⑨(0.52.0):**所有** tool_start 都留一份 args 快照(有界在飞表,收口即删)。
+    // 🔴 与下面那张 gated 表刻意**不合表**:「表里有」绝不等于「被 gate 过」——两张表的成员关系、
+    //    生命周期、容量纪律都不同(逐条理由见 `gateLedger.ts` 的 `noteStart` 头注)。
+    //    这一份服务的是分类器 deny 这类**没走 gate**的收口现场(gated 表里根本没有它们)。
+    // 🔴 **必须排在 `markStarted` 闸之前**(异源对抗复审 R1 finding② 采纳):那道闸是**渲染**去重
+    //    (durable 重放的已渲 call 不再上屏),而记账不是渲染。排在闸之后 ⇒ 重放帧一律早退 ⇒
+    //    `noteStart` 的「先删再写」刷新在**生产路径上永远走不到**,只有直调台账的测试碰得着;
+    //    而重放恰恰是被有界表淘汰过的那些 call 唯一一次把快照拿回来的机会。
+    led.noteStart(callId, ev);
     if (!led.markStarted(callId))
         return { kind: 'skip' }; // durable 重放的已渲 call
     if (isGatedToolName(ev.toolName)) {
@@ -545,13 +563,24 @@ function routeToolStart(ev, callId, led) {
     return { kind: 'yield', events: [ev] };
 }
 function routeToolEnd(ev, callId, led) {
-    if (led.isEnded(callId))
+    if (led.isEnded(callId)) {
+        // L-69⑨(0.52.0):已收口的 call **无论走哪条路**都不该留在在飞表里。这一行是上面
+        // 「noteStart 排在渲染去重闸之前」的对偶:durable 重放会把 start 再送一遍(于是快照被重新
+        // 加回来),而重放的 end 在这里早退 ⇒ 少了这一行,那一条就要一直挂到被容量淘汰为止。
+        led.dropStartArgs(callId);
         return { kind: 'skip' }; // durable 重放/park 复写的已收口 call
+    }
     led.dropFsCall(callId);
     for (const arm of TOOL_END_ARMS) {
         const action = arm.run(ev, callId, led);
-        if (action)
+        if (action) {
+            // L-69⑨(0.52.0):在飞窗到此为止 —— 收口帧已经判完(臂**在这一行之前**跑,分类器 deny 臂
+            // 因此还读得到 args),这一条快照从此没有消费者。
+            // 🔴 释放点必须在**臂之后**:挪到循环之前 ⇒ deny 臂拿到的恒是缺席(修前形);挪到 `return`
+            //    的调用方 ⇒ 五条臂各自 return,释放就要抄五遍(而漏抄的那条就是泄漏点)。
+            led.dropStartArgs(callId);
             return action;
+        }
     }
     // 不可达:兜底臂 generic-close 无条件命中。真走到这里 = 有人给它加了早退条件,
     // 那样 tool_end 会被整帧静默丢弃(用户看不到任何收口),必须当场喊出来而不是 `skip`。

package/dist/hitl/gateLedger.d.ts

@@ -61,6 +61,29 @@ export interface GateLedger {
      *  审批 payload,且台账持帧延长了整帧生命周期。载荷仍是 UNTRUSTED unknown,台账只搬运不解释。 */
     noteGatedStart(callId: string, ev: AgentEvent): void;
     gatedStartArgs(): ReadonlyMap<string, unknown>;
+    /**
+     * 每一张 `tool_start` 的 `args` 快照,**不论这只工具有没有被 gate**。
+     *
+     * 🔴 为什么必须与 {@link gatedStartArgs} **分成两张表**(而不是「合表 + 用有没有 args 判 gated」):
+     *    「被 gate 过」是**另一个集合**,两者的成员关系没有任何蕴含 —— 分类器 deny 的工具通常
+     *    **没有**被 gate(引擎侧分类器直接 block,一张 `tool_approval` 帧都不出),而 gate 过的工具
+     *    也可能整场没有 args。把「表里有这一条」读成「它被 gate 过」,等于拿一个搬运位当身份位
+     *    ([provenance-needs-wire-fact-not-inference] 同族);合表之后总有人会这么读,所以不合。
+     *    两表的**生命周期**也刻意不同,见下:
+     *      · {@link gatedStartArgs}:审批 payload 的一手源,**整个 turn 不删**(park / durable 重放
+     *        之后卡面还要读它),条目数被「真被 gate 的工具数」天然约束;
+     *      · 本表:每一张 tool_start 都进,所以**必须有界**(见 {@link START_ARGS_MAX_ENTRIES}),
+     *        且 `tool_end` 收口当拍就删(见 {@link dropStartArgs})—— 它只服务「这只 call 还没收口」
+     *        那段窗口内的消费者(今天唯一一个:分类器 deny 臂给宿主的 `ctx.args`)。
+     *
+     * 🔴 存的是 **tool_start 当拍的 `args` 快照**而非帧引用,理由与 {@link noteGatedStart} 逐字同款。
+     *    载荷是 **UNTRUSTED** wire 值:台账只搬运,不解释、不渲染、不截断。
+     */
+    noteStart(callId: string, ev: AgentEvent): void;
+    /** 本 call 的 tool_start args 快照;没记过 / 已收口 / 已被有界淘汰 ⇒ 表里读不到。 */
+    startArgs(): ReadonlyMap<string, unknown>;
+    /** `tool_end` 收口当拍释放这一条(在飞窗结束)。不在表里 ⇒ no-op。 */
+    dropStartArgs(callId: string): void;
     isEnded(callId: string): boolean;
     markEnded(callId: string): void;
     /**
@@ -237,5 +260,36 @@ export interface GateLedger {
     /** 判据链上出现了真进展(park 真被决断 / 重探把新坐标的卡呈出去了)⇒ 连续计数归零。 */
     resetAlreadyResolvedGate(): void;
 }
+/**
+ * {@link GateLedger.noteStart} 那张在飞表的**容量上限**(L-69⑨,0.52.0)。
+ *
+ * 🔴 为什么必须有界:本表的写口是**每一张** `tool_start`,而它的删口(`tool_end` 收口)在两种真实
+ *    形态下不会来 —— ①一个 turn 里 `tool_end` 先于本连接开始(durable re-attach 只消费 `runs.events`
+ *    的一段);②run 被中止 / 连接断掉,在飞 call 的收口帧永远不到。无界表在长流多工具的 turn 上
+ *    条目数会一直涨。
+ *
+ * 🔴 **上限量的是条目数(= 保留的引用数),不是字节数**(异源对抗复审 R1 finding① 采纳的措辞订正)。
+ *    本表存的是 `ev.args` 的**引用**,不是拷贝 —— 而同一个 `ev` 在这一拍**照常 yield 下去**
+ *    (`frameRouter.routeToolStart` 返回 `{kind:'yield', events:[ev]}`),投影成 `SDKMessage` 之后
+ *    那份入参在端的转录面上本来就活着。所以本表对**驻留字节**的增量是「一个指针 × 条目数」,
+ *    它不复制载荷、也不是这条链上第一个持有它的容器:同文件的 {@link GateLedger.noteGatedStart}
+ *    从本批之前就持着同一形的引用,而且**整个 turn 不删、连条目数都不设上限**。
+ *    ⚠️ 仍然如实说清**没有**守住的那一格:单条载荷本身**没有**字节预算(一次 `Write` 的
+ *    `content` 有多大,这里就跟着多引用多大一份多久)。真要按字节记账得先定义「多大算大」并同批给出
+ *    超限时的降级形(截断 = 交出一份假入参,不许;整条不留 = 那只 call 的 deny 现场退回诚实缺席),
+ *    属独立一件;本批**不做单边近似**,如实登记在此。
+ * 🔴 为什么是 **256** 而不是更小:上限守的是「条目数无界增长」,而它必须**远大于**同一时刻真正在飞的
+ *    call 数,否则淘汰会打到还没收口的 call 身上(那正是本表要服务的对象)。引擎侧同一 turn 的并发
+ *    工具批今天是个位数量级,单批 `tool_start` 连发也在两位数以内;256 给出的是两个数量级的余量。
+ * 🔴 淘汰**按 FIFO 丢最早**(`Map` 的插入序):最早入表的那一条是**最久没有收口**的,它要么已经因为
+ *    上面两种形态永远不会收口,要么它的消费窗(收口当拍)早就过去了 —— 丢它的代价最小。绝不按
+ *    「随便丢一个」或整表清空(整表清空会把同批在飞的兄弟一起打掉)。
+ * 🔴 **淘汰打到仍在飞的 call 时会怎样(成文的取舍,不是漏)**:那只 call 后来被分类器拒绝的话,
+ *    宿主拿到的 `ctx` 只有 `toolCallId`、没有 `args` —— 即**诚实缺席**,端按可选处理照常降级渲
+ *    (契约见 `docs/INTEGRATION-CLIENTS.md` §15c 第 3 条)。这条路上唯一的替代品是「不淘汰」,
+ *    而那就是无界表。durable 重放会把 `tool_start` 再送一遍,那是被淘汰项**拿回快照**的机会 ——
+ *    所以 `frameRouter.routeToolStart` 把本动词排在渲染去重闸**之前**(见该站点注)。
+ */
+export declare const START_ARGS_MAX_ENTRIES = 256;
 /** 造一份 turn 级 gate 台账(**不是单例**,见文件头注)。 */
 export declare function createGateLedger(): GateLedger;

package/dist/hitl/gateLedger.js

@@ -9,6 +9,37 @@
  *    additive 键保留兼容(裁定原文)。
  */
 export const SEMA_COLLATERAL_ABORT_KEY = '_sema_collateral_abort';
+/**
+ * {@link GateLedger.noteStart} 那张在飞表的**容量上限**(L-69⑨,0.52.0)。
+ *
+ * 🔴 为什么必须有界:本表的写口是**每一张** `tool_start`,而它的删口(`tool_end` 收口)在两种真实
+ *    形态下不会来 —— ①一个 turn 里 `tool_end` 先于本连接开始(durable re-attach 只消费 `runs.events`
+ *    的一段);②run 被中止 / 连接断掉,在飞 call 的收口帧永远不到。无界表在长流多工具的 turn 上
+ *    条目数会一直涨。
+ *
+ * 🔴 **上限量的是条目数(= 保留的引用数),不是字节数**(异源对抗复审 R1 finding① 采纳的措辞订正)。
+ *    本表存的是 `ev.args` 的**引用**,不是拷贝 —— 而同一个 `ev` 在这一拍**照常 yield 下去**
+ *    (`frameRouter.routeToolStart` 返回 `{kind:'yield', events:[ev]}`),投影成 `SDKMessage` 之后
+ *    那份入参在端的转录面上本来就活着。所以本表对**驻留字节**的增量是「一个指针 × 条目数」,
+ *    它不复制载荷、也不是这条链上第一个持有它的容器:同文件的 {@link GateLedger.noteGatedStart}
+ *    从本批之前就持着同一形的引用,而且**整个 turn 不删、连条目数都不设上限**。
+ *    ⚠️ 仍然如实说清**没有**守住的那一格:单条载荷本身**没有**字节预算(一次 `Write` 的
+ *    `content` 有多大,这里就跟着多引用多大一份多久)。真要按字节记账得先定义「多大算大」并同批给出
+ *    超限时的降级形(截断 = 交出一份假入参,不许;整条不留 = 那只 call 的 deny 现场退回诚实缺席),
+ *    属独立一件;本批**不做单边近似**,如实登记在此。
+ * 🔴 为什么是 **256** 而不是更小:上限守的是「条目数无界增长」,而它必须**远大于**同一时刻真正在飞的
+ *    call 数,否则淘汰会打到还没收口的 call 身上(那正是本表要服务的对象)。引擎侧同一 turn 的并发
+ *    工具批今天是个位数量级,单批 `tool_start` 连发也在两位数以内;256 给出的是两个数量级的余量。
+ * 🔴 淘汰**按 FIFO 丢最早**(`Map` 的插入序):最早入表的那一条是**最久没有收口**的,它要么已经因为
+ *    上面两种形态永远不会收口,要么它的消费窗(收口当拍)早就过去了 —— 丢它的代价最小。绝不按
+ *    「随便丢一个」或整表清空(整表清空会把同批在飞的兄弟一起打掉)。
+ * 🔴 **淘汰打到仍在飞的 call 时会怎样(成文的取舍,不是漏)**:那只 call 后来被分类器拒绝的话,
+ *    宿主拿到的 `ctx` 只有 `toolCallId`、没有 `args` —— 即**诚实缺席**,端按可选处理照常降级渲
+ *    (契约见 `docs/INTEGRATION-CLIENTS.md` §15c 第 3 条)。这条路上唯一的替代品是「不淘汰」,
+ *    而那就是无界表。durable 重放会把 `tool_start` 再送一遍,那是被淘汰项**拿回快照**的机会 ——
+ *    所以 `frameRouter.routeToolStart` 把本动词排在渲染去重闸**之前**(见该站点注)。
+ */
+export const START_ARGS_MAX_ENTRIES = 256;
 /** 造一份 turn 级 gate 台账(**不是单例**,见文件头注)。 */
 export function createGateLedger() {
     const startedCalls = new Set();
@@ -16,6 +47,8 @@ export function createGateLedger() {
     /** 只存帧:出身不在入表当拍冻结(那一拍 gate 身份还没到),改在 `flushHeld` 当拍求值。 */
     const heldAskEnds = new Map();
     const gatedStartArgsByCall = new Map();
+    /** 每一张 tool_start 的 args 快照(在飞窗;有界 FIFO,见 {@link START_ARGS_MAX_ENTRIES})。 */
+    const startArgsByCall = new Map();
     const deniedCalls = new Set();
     const pendingFsCalls = [];
     const resolvedAnswers = new Map();
@@ -140,6 +173,27 @@ export function createGateLedger() {
         gatedStartArgs() {
             return gatedStartArgsByCall;
         },
+        noteStart(callId, ev) {
+            // 🔴 **先删再写**:同一 callId 重放(durable 重放的 tool_start 在别的入口被 markStarted 挡掉,
+            //    但本动词不依赖那道闸)必须刷新它在 FIFO 里的位置,否则「覆盖」会让它保持旧的插入序、
+            //    在还活着的时候被当成最老的一条淘汰掉。`Map.set` 对已有键**不**改插入序,这一行是承重的。
+            startArgsByCall.delete(callId);
+            startArgsByCall.set(callId, ev.args);
+            // 有界:超容量丢**最早**入表的那一条(`Map` 迭代序 = 插入序)。while 而不是 if —— 上限被
+            // 调小时(或将来某次批量写入)一次要淘汰多条,if 会让表永久停在超限状态。
+            while (startArgsByCall.size > START_ARGS_MAX_ENTRIES) {
+                const oldest = startArgsByCall.keys().next();
+                if (oldest.done === true)
+                    break;
+                startArgsByCall.delete(oldest.value);
+            }
+        },
+        startArgs() {
+            return startArgsByCall;
+        },
+        dropStartArgs(callId) {
+            startArgsByCall.delete(callId);
+        },
         isEnded(callId) {
             return endedCalls.has(callId);
         },

package/dist/hitl/hitlHostSurface.d.ts

@@ -7,14 +7,41 @@ export interface HitlNotice {
     priority: 'immediate';
     timeoutMs: number;
 }
+/**
+ * 分类器 deny 裁决的**这一只 call 的现场**(L-69⑨,0.52.0;{@link HitlHostSurface.surfaceClassifierDeny}
+ * 的 **additive 可选**第三参)。
+ *
+ * 🔴 为什么要有它:修前宿主只拿到 `toolName`,于是端的 Recent Denials 面板三行同名(三条被拒的
+ *    `Bash` 长一个样),而端要做的两件事 —— **行文案**(这一行说的是哪条命令 / 哪个文件)与
+ *    **retry 粒度**(重试这一只调用,而不是「整个 Bash 工具」)—— 都需要这一只 call 的身份与入参。
+ * 🔴 `args` 是 **UNTRUSTED** wire 值(模型产出的工具入参):本包**原样**交给宿主,不渲染、不截断、
+ *    不消毒 —— 展示消毒是端的事(cli 有 `cleanUntrustedForDisplay`)。要拿它铸**行文案**请用
+ *    `classifierDenyDisplay(toolName, args)`(`src/classifierVerdictWire.ts`,三端同形的判定)。
+ * 🔴 `args` **可缺席**:分类器拒绝的工具通常没被 gate,而在飞 args 表是**有界**的(见
+ *    `gateLedger.START_ARGS_MAX_ENTRIES`),长流上早期 call 的快照可能已被淘汰。缺席 = 诚实缺席,
+ *    端按「只有工具名」降级渲,**绝不**据此编一个空 args 出来。
+ */
+export interface ClassifierDenyContext {
+    /** 这一只被拒调用的 wire `toolCallId`(retry 粒度的锚;帧上取,恒在场)。 */
+    toolCallId: string;
+    /** 这一只调用的 `tool_start` 入参快照;**UNTRUSTED**,缺席 = 台账里没有(见上)。 */
+    args?: unknown;
+}
 /** HITL 的宿主副作用面 —— 通知上屏 + 分类器 deny 的端侧记账。 */
 export interface HitlHostSurface {
     /** 立即顶到 current(壳:`notifications.current = notice`,queue 不动)。 */
     showNotice(notice: HitlNotice): void;
     /** **仅当** current 仍是这个 key 时清掉(壳原文的 if-still-mine 语义 —— 否则会误清别人的通知)。 */
     clearNoticeIfCurrent(key: string): void;
-    /** 分类器 deny 裁决的宿主副作用:footer 通知 + /permissions Recent Denials 记账(壳资产)。 */
-    surfaceClassifierDeny(toolName: string, verdict: ClassifierDenyVerdict): void;
+    /**
+     * 分类器 deny 裁决的宿主副作用:footer 通知 + /permissions Recent Denials 记账(壳资产)。
+     *
+     * 🔴 `ctx` 是 **additive 可选**第三参(0.52.0,L-69⑨):老宿主的两参实现**零改动照跑**
+     *    —— JS 里多传一个实参不影响两参函数,TS 里「参数少的函数可赋给参数多的签名」是语言规则
+     *    (函数参数双变/协变),desktop/web 现有 `surfaceClassifierDeny(t, v)` 实现不需要跟车。
+     *    ⚠️ 反过来**不成立**:端一旦读了 `ctx`,就必须按可选处理(库对老路径/缺席场景不承诺在场)。
+     */
+    surfaceClassifierDeny(toolName: string, verdict: ClassifierDenyVerdict, ctx?: ClassifierDenyContext): void;
 }
 /** 装 HITL 宿主面(传 null 卸)。返回还原函数。 */
 export declare function installHitlHostSurface(surface: HitlHostSurface | null): () => void;

package/dist/hooksWireCaps.js

@@ -45,7 +45,24 @@
  *  - workspace trust: interactive sessions with the trust dialog unaccepted ship NO hooks
  *    (shouldSkipHookDueToTrust — the rc.36 "hooks 全被 trust 门禁" invariant, engine leg included);
  *  - `disableAllHooks` (managed/policy settings): ships NO hooks;
- *  - `allowManagedHooksOnly`: ONLY the policy-settings hooks ship; user/project/local are blocked.
+ *  - `allowManagedHooksOnly`: ONLY the policy-settings hooks ship; user/project/local are blocked;
+ *  - `strictPluginOnlyCustomization` covering the "hooks" surface (L-67④, 0.52.0): same disposition as
+ *    `allowManagedHooksOnly` — ONLY the policy-settings hooks ship. Verbatim parity with the local
+ *    executor's `isRestrictedToPluginOnly('hooks')` is argued clause-by-clause on
+ *    {@link hooksLockedToPluginOnly}.
+ *
+ * 🔴 **在册缺口(同形族扫所得,本批刻意未修 —— 别把它读成「已经守住了」)**:cli 本地执行器
+ *    (`src/utils/hooks/hooksConfigSnapshot.ts:getHooksFromAllowedSources`)还有**第四条**腿 ——
+ *    `disableAllHooks` 出现在**非** managed 的来源(user/project/local)时,按 CC 语义降级成
+ *    「只跑 managed hooks」(非 managed 设置不能禁掉 managed hooks,但能禁掉自己)。本文件今天
+ *    **只读 `policySettings.disableAllHooks`** ⇒ 这一形在引擎腿上不成立(用户把自己的 hooks 关了,
+ *    引擎照投照跑)。**为什么本批不修**:cli 那条腿读的是**合并后**的标量
+ *    (`getSettings_DEPRECATED().disableAllHooks`,四源按 policy→user→project→local 后写覆盖前写),
+ *    而本包的 `SettingsPort` 只有 per-source 读口 —— 拿「任一来源为 true」去近似合并结果会在
+ *    「user 写 true、local 写 false」这一形上判反(cli 那边是**不**限制)。忠实复刻需要给
+ *    `SettingsPort` 加一个合并读口 = **公面改动**,属另一批(端要跟车实现)。
+ *    ⇒ 登记在此,不做单边近似([honest-absence-not-fabricated-zero]:守不住就说守不住,
+ *    别用一个会判反的近似冒充守住了)。
  *
  * Projection semantics (CC settings merge, verbatim shapes):
  *  - Sources: policy → user → project → local settings files, per-event arrays CONCATENATED in that
@@ -72,6 +89,41 @@ import { MAX_HOOK_NOTICE_TEXT_CHARS } from './notifications.js';
 import { goalStopHookMatcher, __resetGoalStopHookForTests } from './goalStopHook.js';
 export { GOAL_STOP_HOOK_WIRE_ENV, CC_STOP_SEMANTICS_MIN_SERVER, ccStopSemanticsFromVersion, engineCcStopSemantics, isGoalStopHookWireArmed, setWireSessionStopHook, getWireSessionStopHook, getWireSessionStopHookCcSemantics, buildGoalStopHookPrompt, } from './goalStopHook.js';
 const EDITABLE_HOOK_SOURCES = ['userSettings', 'projectSettings', 'localSettings'];
+/**
+ * managed `strictPluginOnlyCustomization` 对 **hooks 面**的锁判定(L-67④,0.52.0)。
+ *
+ * 🔴 病(修前):`hooksForWire()` 过了 `disableAllHooks` / `allowManagedHooksOnly` 两道 managed 治理门,
+ *    **没过**这一道 —— 而本文件头注自己写着「the wire must honor the SAME gates the local executor
+ *    honors, or a fleet-managed policy is silently bypassed by the engine leg」。后果:管理侧把 hooks
+ *    面锁成 plugin-only 之后,壳的**本地执行器**不再跑 user/project/local 的 hooks,而**引擎腿**照投
+ *    照跑 —— 禁令只在一半的执行面上成立,而这一半恰好是工具真正执行的那一半。
+ *
+ * 🔴 与 cli 本地执行器 `src/utils/settings/pluginOnlyPolicy.ts:isRestrictedToPluginOnly('hooks')`
+ *    **逐条对照,差异为零**:
+ *      · `=== true`(布尔真)⇒ 锁(cli 原文 `if (policy === true) return true`:`true` 锁**全部四个面**,
+ *        hooks 在内)。⚠️ 本条是必须实现的一形 —— 只认数组形会把「一个字就锁全部」的管理写法整个放过,
+ *        而那正是本件要堵的洞;
+ *      · 数组且含 `'hooks'` ⇒ 锁;数组不含 ⇒ **不锁**(锁的是别的面:skills/agents/mcp,与 hooks 无关);
+ *      · 其余一切值形(缺席 / `false` / 串 / 对象 / 数字)⇒ **不锁**(当未设),**不** fail-closed 整条腿。
+ *
+ * 🔴 「非数组非 true ⇒ 当未设」为什么与 cli 差异为零(而不是本包自己另立一条宽口):cli 侧读到这个字段
+ *    之前先过 `SettingsSchema`,该字段的 `.preprocess(...).catch(undefined)`(cli `settings/types.ts`
+ *    逐字注释:「Non-array invalid values ("skills" string, {object}) … .catch drops the field to
+ *    undefined instead. Degrades to unlocked-for-this-field, never to everything-broken.」)已经把脏值形
+ *    丢成 `undefined` ⇒ 到达 `isRestrictedToPluginOnly` 的值形只有 boolean / 字符串数组两种,本函数对这
+ *    两种与 cli **逐条同判**;而对**没过 schema** 的脏值形(别的宿主可能把盘上原文直接交上来),本函数
+ *    的处置方向与 cli 那条 schema 腿**同向**(degrade to unlocked-for-this-field)。
+ * 🔴 与相邻两道门的 fail-closed 纪律**不矛盾**:那两条 fail-closed 守的是「读取**抛出**」(治理策略
+ *    读不出来 = 当作有限制);本条守的是「读到了、但值是个坏形」—— 值在手里,方向由字段属主(schema)
+ *    定,不是未知态。两件事别混。
+ */
+function hooksLockedToPluginOnly(policyValue) {
+    if (policyValue === true)
+        return true;
+    if (Array.isArray(policyValue))
+        return policyValue.includes('hooks');
+    return false;
+}
 /**
  * REF-CC-155(midband-03,fix-outright):此前这里是静默 `catch { return null }` —— 零 hostLog、零
  * 注释说明「为什么这次失败可以死」。settings 读取失败(格式损坏 / 端内部错误)会被悄悄当成
@@ -136,7 +188,19 @@ export function hooksForWire() {
         hostLog('debug', 'hooksWireCaps: disableAllHooks (managed) — no hooks projected to the engine');
         return undefined;
     }
-    const managedOnly = policy?.allowManagedHooksOnly === true;
+    // L-67④(0.52.0):第三道 managed 治理门 —— `strictPluginOnlyCustomization` 含 hooks 面。
+    // 🔴 **顺序与 `allowManagedHooksOnly` 无关**(两者同时在场时无论谁先判,结论都是同一个
+    //    `['policySettings']`,处置逐字相同 —— 它们是**同一个动作**的两个理由,不是两级策略);
+    //    真正有顺序的只有 `disableAllHooks`:它在上面**先**判且**恒赢**(连 policy 自己的都不投),
+    //    本门只在它没命中时才有机会求值。
+    const pluginOnlyHooks = hooksLockedToPluginOnly(policy?.strictPluginOnlyCustomization);
+    if (pluginOnlyHooks) {
+        hostLog('debug', 'hooksWireCaps: strictPluginOnlyCustomization locks the hooks surface (managed) — only policySettings hooks projected to the engine');
+    }
+    // 🔴 `managedOnly` 这个名字下面还被 `/goal` overlay 的分道复用(用户态 goal 钩子必须与
+    //    EDITABLE_HOOK_SOURCES 同进退)——所以本门**合流进同一个量**,而不是只改 `sources`:
+    //    只改 sources 会让 plugin-only 锁下 user 态的 goal 钩子照投,那是同一个洞换了个入口。
+    const managedOnly = policy?.allowManagedHooksOnly === true || pluginOnlyHooks;
     const sources = managedOnly
         ? ['policySettings']
         : ['policySettings', ...EDITABLE_HOOK_SOURCES];