@sema-agent/sdk 21.1.0 → 22.0.1

package/dist/types.d.ts

@@ -604,11 +604,12 @@ export interface TaskRequest {
      *  · **ABSENT(两个载体都不带模式)= `default`**(不再是「无门」):非只读 shell 命令与每一次写先问;有审批席 / durable park 的腿上是卡,无人应答的
      *    腿上 headless 拒(拒句点名 `permissionMode:"acceptEdits"` / 接审批席)。要旧的「不问」就显式发 `acceptEdits`(工作区内写不问)或
      *    `bypassPermissions`(托管部署 422 `request.host_posture_refused`)。
-     *  · `bypassPermissions` **放行并披露**可放的十类 ask(写保护、根外读探针、MCP / A2A 工具标记、transcript 写、规则店读不出〔安全轴 fail-open,单列〕、
-     *    他人共享 artifact 读、模式自己的问、没人表态的服务器工具调用〔`unstated`,server ≥7.115.0〕、普通 / 形状层的问)—— 逐调用记在 `tool_end.gate.disposition.released`({@link ModeRelease}),每 (模式, 类)
+     *  · `bypassPermissions` **放行并披露**可放的类(server ≥7.127.0 每一面九类:写保护、根外读探针、MCP / A2A 工具标记、transcript 写、
+     *    他人共享 artifact 读、模式自己的问、没人表态的服务器工具调用〔`unstated`,server ≥7.115.0〕、普通 / 形状层的问;server 7.122.0–7.126.x 另放「规则店读不出」〔安全轴 fail-open,单列〕⇒ 十类,
+     *    core 7.50.0 / server ≥7.127.0 起这一类 bypass 也问)—— 逐调用记在 `tool_end.gate.disposition.released`({@link ModeRelease}),每 (模式, 类)
      *    每 run 一帧 `engine_notice` `permission.ask_released_by_mode`;免疫类(部署出身 `operator_forced`、ask / org 规则、hook、祖先、问答 …)照问。
-     *    判不出保护目标的写在文件工具上仍拒(`deniedBy:"mode"`);server ≥7.122.0 / core 7.47.0 起在**壳面**(线名恰为 `Bash` / `Monitor`、且声明了写路径目标的调用方工具)
-     *    **放行**——第十一类 `write_protection_unresolved`,披露在 {@link ModeRelease.reason}。
+     *    写目标落点读不出的写在文件工具上仍拒(`deniedBy:"mode"`);server ≥7.122.0 / core 7.47.0 起在**壳面**(线名恰为 `Bash` / `Monitor`、且声明了写路径目标的调用方工具)
+     *    **放行**——壳面多放的那一类 `target_unresolved`(server ≥7.126.0 的拼法;7.122.0–7.125.x 是旧拼法,见 README 22.0.0 迁移表),披露在 {@link ModeRelease.reason}。
      *  · `plan`(server ≥7.122.0)= 引擎的 plan 模式,服务端不另加任何东西:工具表与 `default` 同面、引擎挂交计划工具,写与非只读调用在**调用时**由引擎的 plan 门问(有人可答 ⇒ 一张卡)/ 拒(无人可答);
      *    委派子代以 plan 为天花板。≤7.121.x 服务端另把 plan 翻成只读手、剥掉委派工具并拒 `Workflow`。
      *  · `auto` 武装 ⟺ `permissionMode === "auto"` ∧ 部署挂了分类器席 ∧ `caps.autoMode !== false`(单极;答旧极性的那一位 server 7.107.0 起删,
@@ -1048,6 +1049,10 @@ export interface PendingGateMaterial {
  */
 export type TerminalCause = {
     kind: "completed";
+    /** server ≥7.126.0(core 7.49.0 `TerminalCompletedDetail`,逐字转发):完成**旁**的一份机读账 —— 只有一形:最后一轮的服务商用一个
+     *  本引擎不读的流结束词收了尾(`finish_reason_unknown`;那一轮按模型留下的样子保留,run 另发过一帧 `route.finish_reason_unknown`)。
+     *  **在场 ⇔ 最后一条 assistant 消息带着那个位、且 run 就在那一轮完成**;其余每种完成都缺席。见 {@link TerminalCompletedDetail}。 */
+    detail?: TerminalCompletedDetail;
 } | {
     kind: "failed";
     /** 这次失败带的**机器码**——退役的平面 `errorCode` 那一席,现在**结构上**只属于失败臂
@@ -1095,6 +1100,16 @@ export type TerminalCause = {
  * 同一事实在会话读面的 assistant 消息上另有两键(`apiErrorRoute` / `modelOutputInvalid`,`GET /v1/sessions/:id` 的 `messages[]` 逐字转发,本包不为引擎消息型建联合)。
  */
 export type TerminalFailureDetail = TerminalProviderRejectedDetail | TerminalCodedDetail | TerminalModelOutputInvalidDetail;
+/**
+ * `completed` 因由可能带的机读账(server ≥7.126.0;core 7.49.0 `dist/core/terminal-cause.d.ts` 的同名接口,键逐键同)。`kind` 闭集、一员:
+ * `finish_reason_unknown` —— 最后一轮的服务商用一个引擎不读的流结束词收尾;`finishReasonUnknown` = 那个词,按服务商回声形(形外的字节换成 `?`),server 逐字过境。
+ * 这是「完成了,但可能不完整」唯一的一形:读它的消费端提示「最后一段回答可能被截」,别当失败。
+ */
+export interface TerminalCompletedDetail {
+    kind: "finish_reason_unknown";
+    /** 服务商的流结束词(服务商回声形;不是引擎词表里的词)。 */
+    finishReasonUnknown: string;
+}
 /** `provider_rejected` 臂(契约 §5.0a):**只在模型服务商用 4xx 拒绝了这次请求、且这次拒绝就是这条结果的原因时在场**;5xx、建连 / 流式中断、200 体里的带内错误、锁冲突、请求构建守卫、一切非服务商的失败 ⇒ 缺席(缺席不是「旧版本」的信号)。 */
 export interface TerminalProviderRejectedDetail {
     kind: "provider_rejected";
@@ -2668,7 +2683,7 @@ export interface TraceTurn {
  *    server 真会发它 ⇒ 留在闭集里(同 `fileHistoryCapture` 的 `on-always` 先例),登记 `test/_keyset-divergence.ts` `DENIED_BY_RETIRED_WORDS`,
  *    删除条件 = 支持地板抬过 7.106.0;
  *  · `mode` —— **权限模式自己的拒**(server ≥7.106.0 / core 7.34.0):`dontAsk` 把一只无人在场可答的问变成拒、`bypassPermissions` 拒一次
- *    判不出保护目标的写(`write_protection_unresolved`)。同臂必带 `mode` / `askClass` / `classes`(core 不变量 I8,见 {@link GateDisposition});
+ *    写目标落点读不出的写(`target_unresolved`;7.122.0–7.125.x 是旧拼法)。同臂必带 `mode` / `askClass` / `classes`(core 不变量 I8,见 {@link GateDisposition});
  *  · `compliance` —— 合规的调用期锁;
  *  · `write_protection` —— 一次被批准的编辑被限制链改写到了**没有任何审批覆盖**的写保护路径上;
  *  · `ask_resolution` —— 这次 ask 的**结算本身**就是拒(有人说了不 / 窗到期 / 没人可问……),细节在
@@ -2720,19 +2735,21 @@ export type DeniedBy = "policy" | "hook" | "org" | "persisted_rule" | "classifie
  */
 export type PermissionMode = "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | "dontAsk";
 /**
- * 一只问**属于哪一类**(core `ASK_CLASSES`:7.34.0 铸二十词,core 7.39.0 起 `shell_floor` 入册 ⇒ 二十一词,core 7.40.0 起 `unstated` 入册 ⇒ 二十二词,core 7.41.0 起 `requires_user_interaction` 入册 ⇒ 二十三词,core 7.43.0 起 `classifier_no_ruling` 入册 ⇒ 二十四词,core 7.45.0 起 `dangerous_delete` 入册 ⇒ **二十五词**;模式 × 类仲裁表的列)。K-32 扩项 / server ≥7.106.0 起出现在
+ * 一只问**属于哪一类**(core `ASK_CLASSES`:7.34.0 铸二十词,core 7.39.0 起 `shell_floor` 入册 ⇒ 二十一词,core 7.40.0 起 `unstated` 入册 ⇒ 二十二词,core 7.41.0 起 `requires_user_interaction` 入册 ⇒ 二十三词,core 7.43.0 起 `classifier_no_ruling` 入册 ⇒ 二十四词,core 7.45.0 起 `dangerous_delete` 入册 ⇒ 二十五词,core 7.49.0 起 `unverifiable_shell_text` 入册 ⇒ **二十六词**(同版写目标落点读不出那一类改拼 `target_unresolved`,旧拼法见 README 22.0.0 迁移表);模式 × 类仲裁表的列)。K-32 扩项 / server ≥7.106.0 起出现在
  * {@link ModeRelease.askClass} / `.classes` 与 deny 臂的 `askClass` / `classes` 上,以及通告 `permission.ask_released_by_mode` 的 detail 里;
  * K-37 扩项 / server ≥7.109.0(S-934 ②)起也在审批面:活卡帧 / 卡面 / 运维队列行 / `/stream` `pending` 帧的 `askClass` / `classes`
  * (同样经 core `isAskClass` 筛,读不出整对不投;见 {@link import("./resources/tool-approvals.js").ToolApprovalFrame.askClass})。
- * 🔴 **门记录这一面是真闭集**(server 按 core `isAskClass` 筛,出集整条不上帧)。`bypassPermissions` 只放行其中**可放**的十类
- * (每一面都可放:`transcript_write` / `rule_unreadable` / `probe` / `write_protection` / `tool_marks_mcp` / `tool_marks_a2a` /
- * `artifact_shared_read` / `mode` / `unstated` / `ordinary`)—— 另加:core 7.47.0 / server ≥7.122.0 起,**壳面**(线名恰为 `Bash` / `Monitor`、声明了写路径目标的调用方工具)
- * 还放第十一类 `write_protection_unresolved`(core `releasableAskClassesFor(face)`:壳面 11、其余面 10;≤7.121.x 的 `RELEASABLE_ASK_CLASSES` 常量在 core 7.47.0 已删;
- * 文件工具上这一类照拒);其余(`operator_forced` 部署出身、`ask_rule` / `org_rule`、`hook`、`ancestor`、`content_question`、
- * `dangerous_delete`(core 7.45.0)、`unverifiable_delete`、`governance_unavailable`、`policy_rra`、`requires_user_interaction` …)任何模式下都照问。
+ * 🔴 **门记录这一面是真闭集**(server 按 core `isAskClass` 筛,出集整条不上帧)。`bypassPermissions` 只放行其中**可放**的类(core `releasableAskClassesFor(face)`):
+ *  · **server ≥7.127.0(core 7.50.0)**:每一面都可放九类 —— `transcript_write` / `probe` / `write_protection` / `tool_marks_mcp` / `tool_marks_a2a` /
+ *    `artifact_shared_read` / `mode` / `unstated` / `ordinary`;**壳面**(线名恰为 `Bash` / `Monitor`、声明了写路径目标的调用方工具)另放第十类 `target_unresolved`
+ *    (壳面 10、其余面 9;文件工具上这一类照拒,`deniedBy: "mode"`)。`rule_unreadable` 不再被任何模式放行(规则读不出 ⇒ bypass 也问,run 一条 `permission.rule_store_unavailable` 通告)。
+ *  · server 7.122.0–7.126.x(core 7.47.0–7.49.x):每一面另放 `rule_unreadable` ⇒ 十类、壳面第十一类(壳面 11、其余面 10;7.122.0–7.125.x 壳面多放的那一类是旧拼法)。
+ *  · ≤7.121.x:`RELEASABLE_ASK_CLASSES` 常量(在 core 7.47.0 已删)十类、不分面。
+ * 其余(`operator_forced` 部署出身、`ask_rule` / `org_rule`、`hook`、`ancestor`、`content_question`、`dangerous_delete`(core 7.45.0)、`unverifiable_delete`、
+ * `unverifiable_shell_text`(core 7.49.0)、`governance_unavailable`、`policy_rra`、`requires_user_interaction` …)任何模式下都照问。
  *
  * 🔴 **`requires_user_interaction`(core 7.41.0;server ≥7.116.0 提货)= 服务器声明「这只工具每次都要用户在场」**:MCP 服务器在工具申报里声明
- * `_meta["anthropic/requiresUserInteraction"] === true`(只认布尔 `true`)⇒ 这只工具的**每一次**调用都问人 —— **每种模式含 `bypassPermissions`** 都问(**不在**可放十类里),
+ * `_meta["anthropic/requiresUserInteraction"] === true`(只认布尔 `true`)⇒ 这只工具的**每一次**调用都问人 —— **每种模式含 `bypassPermissions`** 都问(**不在**可放类里),
  * 且**只有人的答**清得掉:请求 `settings.permissions.allow`、运维 `APPROVAL_GRANT`、技能清单 + `userInvokedSkills`、PreToolUse hook 的显式 allow 都清不掉它;
  * 无审批席 ⇒ 拒(服务器侧零收到)、无人值守腿不答这一类;帧上同带 `requiresRealApproval:true` / `mandated:true`(`origin:"safety_tighten"`),卡上没有「不再询问」规则。
  * 按 `askClass` 穷举渲卡的客户端要加这一个词;本型是闭集(server 对 `askClass` / `classes` 按 core `isAskClass` 筛,出集整对不投)。
@@ -2744,18 +2761,28 @@ export type PermissionMode = "default" | "acceptEdits" | "plan" | "auto" | "bypa
  * `plan` 模式下只有**只读**的服务器工具出这张卡。本类说的是「**没人说**」,不是 `ask_rule` / `org_rule` 那种「有人说了问」。
  */
 export type AskClass = "content_question" | "hook" | "ancestor"
-/** core 7.45.0 / server ≥7.119.0:**受保护位置的删除**(`rm` / `rmdir` 的目标是文件系统根、顶层目录、家目录、任务根 / 工作目录 / 附加工作目录或它们的祖先 —— 含 `rm -rf *` 在任务根、`rm -rf ~/*` ——
- *  或 shell 拿到的是运行时才拼出的脚本〔`bash -c "$CMD"` / `eval "$(…)"`〕)。**只有人的答清得掉**:任何模式(含 `bypassPermissions`)、任何 allow(请求 `settings.permissions.allow`、运维 `APPROVAL_GRANT`、
- *  存下的 allow 行、技能清单、hook 的 allow)、`auto` 的分类器都清不掉;帧上同带 `requiresRealApproval:true`;没人答就不执行(无人值守腿拒)。**免疫 bypass**(不在可放十类里)。 */
- | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "org_rule" | "governance_unavailable" | "rule_unreadable" | "ask_rule" | "denial_limit_fallback"
+/** core 7.45.0 / server ≥7.119.0:**受保护位置的删除**(`rm` / `rmdir` 的目标是文件系统根、顶层目录、家目录、任务根 / 工作目录 / 附加工作目录或它们的祖先 —— 含 `rm -rf *` 在任务根、`rm -rf ~/*`)。
+ *  **只有人的答清得掉**:任何模式(含 `bypassPermissions`)、任何 allow(请求 `settings.permissions.allow`、运维 `APPROVAL_GRANT`、
+ *  存下的 allow 行、技能清单、hook 的 allow)、`auto` 的分类器都清不掉;帧上同带 `requiresRealApproval:true`;没人答就不执行(无人值守腿拒)。**免疫 bypass**(不在可放类里)。
+ *  ⚠️ server 7.119.0–7.125.x 这一类还盖「shell 拿到的是运行时才拼出的脚本」(`bash -c "$CMD"` / `eval "$(…)"`);core 7.49.0 / server ≥7.126.0 起那一形归 {@link unverifiable_shell_text}。 */
+ | "dangerous_delete" | "unverifiable_delete"
+/** core 7.49.0(#1505)/ server ≥7.126.0:**引擎读不出这只 shell 要执行的文本** —— shell 拿到的不是命令里写着的字:程序的输出、命令替换、文件内容、由流填的 argv
+ *  (`bash -c "$CMD"` / `eval "$(…)"` / `xargs sh -c` 一类;解析失败或嵌套过深的 shell 文本也归这一类)。仲裁行与 `unverifiable_delete` 同、只差分类器一列:
+ *  **免疫 bypass**(不在可放类里)、allow 规则清不掉、`auto` 的分类器不被问、`dontAsk` 拒;只有人的答清得掉。卡上不带 `mandate` 词(它的理由是「文本读不出」这扇门,不是表上的词)。
+ *  server 7.125.x 及以前这一形落 `dangerous_delete`。 */
+ | "unverifiable_shell_text" | "transcript_write" | "org_rule" | "governance_unavailable" | "rule_unreadable" | "ask_rule" | "denial_limit_fallback"
 /** core 7.43.0 #1353 / server ≥7.118.0:auto 模式的分类器**没判出来**(它跑不了 —— `error` / `timeout`,或答了却没有判词 —— `parse_error`),于是交给人:
  *  denial-limit 回落那一行(只有人的答清得掉;**免疫 bypass**,allow 规则清不掉,分类器不再被问)。活卡帧 / 收件箱行另带成因 {@link import("./resources/tool-approvals.js").ToolApprovalFrame.classifierNoRuling}。 */
  | "classifier_no_ruling"
-/** core 7.41.0 / server ≥7.116.0:服务器工具申报声明「每次调用都要用户在场」(见本型顶注)—— **不在** `bypassPermissions` 可放的十类里,只有人的答清得掉。 */
+/** core 7.41.0 / server ≥7.116.0:服务器工具申报声明「每次调用都要用户在场」(见本型顶注)—— **不在** `bypassPermissions` 可放的类里,只有人的答清得掉。 */
  | "requires_user_interaction" | "operator_forced"
 /** core 7.39.0(#1260;server ≥7.113.0 提货):运维旋钮 `shellGate: "always"` 在**跑 shell 的席位**上的地板 —— `operator_always` 授权词所披露的那一问,
- *  自己成一类,免得持有另一种强制问的类集把它藏掉。与 `operator_forced` 同样**免疫 bypass**(不在 `bypassPermissions` 可放的十类里)。 */
- | "shell_floor" | "write_protection_unresolved" | "probe" | "write_protection" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "mode"
+ *  自己成一类,免得持有另一种强制问的类集把它藏掉。与 `operator_forced` 同样**免疫 bypass**(不在 `bypassPermissions` 可放的类里)。 */
+ | "shell_floor"
+/** core 7.49.0(#955)/ server ≥7.126.0 起的拼法(7.122.0–7.125.x 是旧拼法,零别名,见 README 22.0.0 迁移表):**写目标的落点读不出** —— 这次写的目标在盘上通向哪里说不出
+ *  (路上有一个链接查不了,或执行环境解不出目标),于是它落不落在受保护的路径上(写保护表、敏感路径表)是未知。文件工具上它是拒(`deniedBy: "mode"` / 安全层);
+ *  **壳面**(线名恰为 `Bash` / `Monitor`、声明了写路径目标的调用方工具)上 `bypassPermissions` 放行并披露在 {@link ModeRelease.reason}。同名词也是 {@link import("./resources/tool-approvals.js").PersistedRuleMandate} 的一员。 */
+ | "target_unresolved" | "probe" | "write_protection" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "mode"
 /** core 7.40.0 / server ≥7.115.0:**没人表态**的服务器工具 / A2A 技能调用(见本型顶注)—— 可放类(bypass / allow 规则 / 分类器都清得掉它),不在免疫类里。 */
  | "unstated" | "ordinary";
 /**
@@ -2777,14 +2804,16 @@ export interface ModeRelease {
     mandate?: PersistedRuleMandate;
     /**
      * 🔴 放行**越过了什么**:一个词,取 core `MODE_RELEASE_REASONS` 数组序里这只 ask 的类集持有的**第一位**;类集不持有任何成员 ⇒ 缺席。
-     * 🔴 **闭集**(server 按 core `isModeReleaseReason` 筛,出集整条 `gate` 不上帧;core 加词本筛随之放行,所以按词分派的消费端要认新词):
-     *  · `"rule_unreadable"` —— 放行越过了一条**这次调用读不出**的规则(规则店读不出 —— 安全轴 fail-open 方向,server 单列披露);
-     *  · `"write_protection_unresolved"`(server ≥7.122.0 / core 7.47.0 起上 wire)—— 放行越过了一次**写保护判官解不出目标**的写(它落不落在受保护表上是未知)。
-     *    只在**壳面**放:线名恰为 `Bash` / `Monitor`、且声明了写路径目标的**调用方工具**,在 `bypassPermissions` 下;文件工具上同一类问照拒(`deniedBy: "mode"`)。
-     *    引擎自带的 `Bash` / `Monitor` 铸不出这一类,server 自己也不挂这样的工具 —— 它出自调用方(嵌入方)自带的同名工具。
-     * 7.122.0 / core 7.47.0 之前这里只有 `"rule_unreadable"` 一个词。
+     * 🔴 **闭集、一员**(server 按 core `isModeReleaseReason` 筛,出集整条 `gate` 不上帧):
+     *  · `"target_unresolved"` —— 放行越过了一次**写目标落点读不出**的写(落点的读法说不出它在盘上通向哪里 —— 路上有一个链接查不了,或执行环境解不出目标 ——
+     *    于是它落不落在受保护的路径上是未知)。只在**壳面**放:线名恰为 `Bash` / `Monitor`、且声明了写路径目标的**调用方工具**,在 `bypassPermissions` 下;
+     *    文件工具上同一类问照拒(`deniedBy: "mode"`)。引擎自带的 `Bash` / `Monitor` 铸不出这一类,server 自己也不挂这样的工具 —— 它出自调用方(嵌入方)自带的同名工具。
+     * ⚠️ 版本史(本包 22.0.0 起型面只认上面一员;老 server 发的别的词读作集外,不改写 —— 与 21.0.0 删 `contentKind` 同一纪律):
+     *  server 7.122.0–7.125.x 这一员是旧拼法(core 7.47.0–7.48.x;README 22.0.0 迁移表);server ≤7.126.x 另有一员 `"rule_unreadable"`(放行越过了一条这次调用读不出的规则)——
+     *  core 7.50.0 / server ≥7.127.0 起规则读不出不再被任何模式放行(bypass 也问,run 一条 `permission.rule_store_unavailable` 通告),这一员退出;`rule_unreadable` 作为 {@link AskClass} 的一类**仍在**。
+     *  7.122.0 之前这里只有 `"rule_unreadable"` 一个词。
      */
-    reason?: "rule_unreadable" | "write_protection_unresolved";
+    reason?: "target_unresolved";
 }
 /**
  * 这一次分类的**模型归属**(core 7.18.0 #742 `AutoModeClassifierRound`,server ≥7.78.0)——「这次 auto 模式
@@ -3109,6 +3138,10 @@ export type WiringManifestHookEntry = {
 /**
  * 一条腿的 **LSP 代码智能接缝**(core 7.18.0 #789,server ≥7.78.0;**租户可见**)。
  *
+ * 🔴 **车道射程(server ≥7.127.0 / core 7.50.0)**:LSP 只挂在能把读**绑到对象**的车道上(引擎 7.50.0 起 LSP 会话只读执行环境 `openBound` 持有的对象)——
+ *   今天只有 **host** 车道;e2b / k8s(以及 ssh / adb / device / local-docker / in-process)上本段**恒缺席**(名册里也没有 LSP 工具),
+ *   开着 `LSP_ENABLED` 的部署起服打一行 `lsp_not_mounted` 说明原因。绑定读在某条车道实现之日 LSP 随之回来;本型不变。
+ *
  * 🔴 **在场 iff 解析出了 manager 席**(`spec.lspManager ?? deps.lspManager`);没接的部署一个字节都不报
  *   ⇒ 整键缺席 = 这台没接 LSP,**不是**「接了但没挂上」。
  * 🔴 **两位互相独立,禁合读**(core 逐字):{@link mounted} 是**名册**事实(接了 manager 但 `LSP` 工具被
@@ -3208,6 +3241,54 @@ export type ContextUsageSection = {
     /** 语义槽(manifest 条目没带槽时缺席)。**缺席不是「没有语义」**,是「那个条目没声明槽」。 */
     kind?: string;
 };
+/**
+ * `tool_end.output` 的**两形**之一 —— 块数组里的一块(core 7.50.0 `tool_end` 臂 `output` 注的块形;一处定义,三处引用:活帧 {@link import("./events.js").AgentEvent} 的
+ * `tool_end.output`、turns 面 {@link TraceBlock} 的 `tool-result.output`、trace 流 {@link TraceStreamEvent} 的 `tool-result.data.output`)。另一形是串(见 {@link ToolOutput})。
+ * **两形都处理**:工具回串就是串(超 core 文本上限被截、末尾带 `…[+N chars truncated]` 标记);回块数组就是块数组,每块守自己的槽位。
+ *
+ * 四臂(闭集,core 工具契约 `(TextContent | ImageContent | DocumentContent)[]` 加引擎 / 服务端的两种降级形):
+ *  · {@link ToolOutputTextBlock} `{ type: "text", text }` —— 文本;整条文本流过 core 文本上限时在超限那一块原位截断(该块末尾带标记,其后的文本块离场);
+ *  · {@link ToolOutputMediaBlock} `{ type: "image" | "document", data, mimeType }` —— 已准入的图像 / 文档,`data` 是字节的 base64(不过文本脱敏:脱敏一段 base64 拦不住什么,只会把图改坏);
+ *  · {@link ToolOutputMediaDescriptor} `{ type: "image" | "document", mimeType?, bytes, truncated: true }` —— 同一块**没随这一面送达**:`bytes` = 解码字节数,`mimeType` 超 255 字符不回声;
+ *  · {@link ToolOutputOmittedBlock} `{ type: "omitted", blocks, bytes, truncated: true }` —— 连描述符都放不下时,它与之后的每个媒体块折成**一块**汇总(core 7.50.0,引擎侧)。
+ * 媒体块与描述符同 `type`,按有没有 `data` 区分(`"data" in b`)。
+ *
+ * 🔴 **哪一面见哪一形**(server ≥7.127.0):
+ *  · **活面**(SSE `tool_end`:同步流、子代 tail 流)—— 媒体块整块逐字(那就是模型看到的那张图);core 在腿的媒体预算用尽时已在源头把块降成描述符 / 汇总块。
+ *    唯一的服务端例外 = **连接积压**:本帧媒体字节 + 这条连接还没送出去的字节 > 64 MiB ⇒ 本帧媒体降成描述符(跟得上的读者永远拿到整图)。
+ *  · **账本面与回放**(`GET /v1/runs/:id/events`、turns 面、trace 流)—— 带 `data` 的媒体块**恒**换成描述符,帧级 `truncated: true`;纯文本与串形 `output` 一个字节不变。
+ *    回放面只见「这里有一张多大的什么图、没随账本落下」—— 对无 `data` 且 `truncated: true` 的块按 `mimeType` / `bytes` 渲染「未送达」;要看图走实时流。
+ * ⚠️ 只说 core 工具契约之内的形:第三方工具交回契约外的内容(非串非数组的体、契约外的块)不在这只型里 —— 那是工具的违约,不是 wire 的第三形。
+ * 🔴 UNTRUSTED RAW + 只供观测:server 已脱敏文本并限长,消费端**永不**把它回喂模型(模型手里有完整结果)。
+ */
+export type ToolOutputBlock = ToolOutputTextBlock | ToolOutputMediaBlock | ToolOutputMediaDescriptor | ToolOutputOmittedBlock;
+/** {@link ToolOutputBlock} 的文本臂(core `TextContent`)。 */
+export interface ToolOutputTextBlock {
+    type: "text";
+    text: string;
+}
+/** {@link ToolOutputBlock} 的媒体臂(core `ImageContent` / `DocumentContent`):`data` = base64 字节。只在活面上出现(账本面恒为 {@link ToolOutputMediaDescriptor})。 */
+export interface ToolOutputMediaBlock {
+    type: "image" | "document";
+    data: string;
+    mimeType: string;
+}
+/** {@link ToolOutputBlock} 的描述符臂:同一媒体块没随这一面送达(core 预算降级 / 服务端账本面 / 活面连接积压)。`bytes` = 解码字节数;`mimeType` 超 255 字符不回声。 */
+export interface ToolOutputMediaDescriptor {
+    type: "image" | "document";
+    mimeType?: string;
+    bytes: number;
+    truncated: true;
+}
+/** {@link ToolOutputBlock} 的汇总臂(core 7.50.0):连描述符都放不下时,它与之后的每个媒体块折成的那一块 —— `blocks` 块、共 `bytes` 解码字节。 */
+export interface ToolOutputOmittedBlock {
+    type: "omitted";
+    blocks: number;
+    bytes: number;
+    truncated: true;
+}
+/** `tool_end.output` 的两形:串 或 {@link ToolOutputBlock} 数组(三面同一只型,见 {@link ToolOutputBlock})。 */
+export type ToolOutput = string | ToolOutputBlock[];
 /** Open set — render unknown types generically, never crash.
  *
  *  design/99 §E1/§E2 (SHIPPED, service `TraceBlock`/`projectEvents` project.ts:69-73,160-165): the action-card
@@ -3263,7 +3344,7 @@ export type TraceBlock = {
     type: "tool-result";
     callId: string;
     label?: string;
-    output?: unknown;
+    output?: ToolOutput;
     isError?: boolean;
     truncated?: boolean;
     totalChars?: number;
@@ -3367,7 +3448,7 @@ export type TraceStreamEvent = {
         callId: string;
         label?: string;
         isError: boolean;
-        output?: unknown;
+        output?: ToolOutput;
         truncated?: boolean;
         totalChars?: number;
         structured?: unknown;
@@ -4841,6 +4922,46 @@ export interface ScenarioDetail {
  *    - **无 `checkpointToken`**（§4a:server-INTERNAL,NOT surfaced 在 /v1/approvals 记录上;合规 client 只回传
  *      boundCallId+boundInputHash 两件套 —— `ApprovalDecision` 上那个可选 checkpointToken 字段已于 SDK 1.0.0 删除）。
  *  这是 boundCallId/boundInputHash decide 绑定的唯一 surface 处。契约说"可选字段缺则 OMIT 不是 null"。 */
+/**
+ * `GET /v1/approvals` 的**信封**(`client.approvals.list()` 的返回,wire 体原样)—— server `src/http/routes/approvals-assistant.ts` 的 `approvals-list` 臂一次 `sendJson` 铸四键:
+ *  · `pending` —— 耐久停驻行(决议走 `POST /v1/approvals/:sessionId/decide`);恒在场;
+ *  · `serverNowMs` —— **本响应铸造时刻**的服务器钟(server ≥7.57.0;同版本恒在场)。壳渲倒计时用 `deadline − serverNowMs`,别减本机钟(钟差会让「还剩 4 分钟」的卡其实早过期);
+ *    ≤7.56.x 的 server 不带它(本包支持地板 3.0.0 之内,所以型上可选);
+ *  · `livePending?` —— 流内窗里的活 ask(server ≥7.43;决议走 `POST /v1/tool-approvals/:approvalId/respond`)。**缺席 = 本部署没有活审批面**,`[]` = 有面、此刻无待批;
+ *  · `crashConverged?` —— 启动时收敛掉的**审计行**(server ≥7.55.0;只在 local 车道审计店在场时在场,`[]` = 有面且无崩溃残账)。行不是队列行:无决议路由、不复活 run。
+ * 三族行形与决议路由各不相同,**分数组不混编**(数组名即路由判据)。
+ */
+export interface PendingList {
+    pending: PendingCheckpoint[];
+    serverNowMs?: number;
+    livePending?: LivePendingRow[];
+    crashConverged?: CrashConvergedRow[];
+}
+/**
+ * `GET /v1/approvals` `crashConverged[]` 的一行(server ≥7.55.0;server `src/approval-ask-audit-store.ts` 的 `CrashConvergedRow`,键逐键同)——
+ * 上一个进程留下的、承载这一问的腿没了的审批:启动时收敛成**不可再决**。args / 卡体不上列表(与 `livePending` 行同一条纪律)。
+ */
+export interface CrashConvergedRow {
+    approvalId: string;
+    toolName: string;
+    taskId: string;
+    sessionId?: string;
+    /** 铸造时刻(ms epoch;键名照 `livePending[].ts`)。 */
+    ts: number;
+    expiresAtMs: number;
+    /** 判别常量:这张卡**已不可再决**。 */
+    decision: "denied";
+    /** 成因(决断口 410 `gone.ask` 体的 `cause` 是同一个词):`crashed_before_park` = 进程崩了;`shutdown_before_park`(server ≥7.108.0)= 腿被有序关停截断。 */
+    cause: Extract<import("./errors.js").AskRowEndingCause, "crashed_before_park" | "shutdown_before_park">;
+    /** `pending` = 工具零执行可机械证明;`decided` = 人当时已答、可能有半截副作用。 */
+    orphanState: "pending" | "decided";
+    /** decided 臂:人当时批的是 approve。 */
+    originalDecision?: "approve";
+    decidedAtMs?: number;
+    convergedAtMs: number;
+    /** pending 臂 = 续跑(引擎的 resume 补偿腿)安全,壳可默认自动续;decided 臂 = 留人工确认。 */
+    resumeSafe: boolean;
+}
 /** #315(server ≥7.43)—— `GET /v1/approvals` 信封第二顶层键 `livePending` 的行:streamApproval 窗内的
  *  **流内 ask**(此前对轮询消费端结构性不可见)。🔴 决议口=`POST /v1/tool-approvals/{approvalId}/respond`,
  *  **不是** /decide(那是 durable 行的门)——数组名即路由判据,两数组不混编。可选旗标 only-if-true