@sema-agent/sdk 6.12.0 → 6.14.0

package/dist/resources/tool-approvals.d.ts

@@ -68,7 +68,57 @@ export type ToolApprovalDecision = "allow" | "allow_session" | "deny";
  *  (client-core 自持同名闭集 copy)做机器对账用——照 registry-core 值拷贝+同源锚先例。下游测试断言
  *  自己的 copy 键集 ⊇/== 本清单,SDK 每次 additive 增键(如 1.307 的 `toolCallId`)对方当天红,
  *  不再靠人肉追平。**新增帧字段必须同步进本清单**(有测试钉)。 */
-export declare const TOOL_APPROVAL_FRAME_KEYS: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "delegation", "outcome"];
+export declare const TOOL_APPROVAL_FRAME_KEYS: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "delegation", "outcome"];
+/** #154 车二(core 5.18.0 design/179):**引擎铸的**一条规则候选 —— 一格「不再询问」按下去会持久化的东西。
+ *
+ *  🔴 文本由 ENGINE 铸,不由壳拼:`rule` 是 server 从被裁决命令的原字节交给引擎算出来的规范文本,回决时
+ *  客户端只能把**其中一条原样报回去**({@link ToolApprovalsResource.respond} 的 `persistRule.rule`)。
+ *  报一条不在候选里的文本 ⇒ server 拒(`ruleRefusal: "rule_not_offered"`),不猜 —— 于是「点一次某条无害
+ *  命令换来一条别的规则」在这条路上结构性不可拼写。
+ *
+ *  `match`:`exact` = 只放行这一条命令(`Bash(git status)`);`prefix` = 词界前缀放行(`Bash(git status:*)`)。
+ *  `command` = 规则里的命令模式,给不想再解析一遍规则文本的壳直接渲染用。 */
+export interface RuleSuggestion {
+    /** 兑付时要原样报回的规范规则文本(server `MAX_RULE_TEXT_CHARS` = 512 字符上限)。 */
+    rule: string;
+    /** 闭词表两值 —— 精确 / 词界前缀。未知值 ⇒ 这条候选不是本包描述的形,别渲成可兑的选项。 */
+    match: "exact" | "prefix";
+    /** 规则里的命令模式(渲染用;不必再解析 `rule`)。 */
+    command: string;
+}
+/**
+ * #154 车二:回决回执上 `ruleRefusal` 的**闭词表**——「不再询问」这次为什么没存上
+ * (server `src/tool-approval.ts` 的 `RuleRefusalReason` 逐字)。
+ *
+ * 🔴 **没有一个成员能用来判断整台部署**:最容易被误读的是 `rule_lane_unavailable` —— 它是四件事**任一**
+ * 不成立时的同一个答案(逐条见下),其中两件是**这只 ask 自己**的局限。据它去关掉整个规则面是错的。
+ *
+ * 🔴 为什么是闭集而不是 `string`:壳要据它分「这次不能存,换下一次」(`rule_input_edited`)与「这张卡上
+ * 就没有可兑的东西」(`rule_lane_unavailable`)。两族命名风格不同**不是笔误**:连字符四个派生自同意车道的
+ * `CardRulePersisted["reason"]`(车道加员这里自动跟),下划线四个是 server 自铸的门。原样保留 = 与 server
+ * 词表逐字同形,消费端 `switch` 得到穷举。
+ *
+ * 逐条:
+ *  · `no-candidates` —— 引擎对这条命令铸不出任何候选(复合/重定向/替换等不可匹配形);
+ *  · `unknown-candidate` —— 报回的文本在记录的候选表里定位不到;
+ *  · `confirm-refused` / `redeem-refused` —— 同意协议的确认/兑付步被拒(记录状态不对、CAS 输、店拒写);
+ *  · `rule_lane_unavailable` —— **四种成因共用一格**(亲读 `persistRuleAfterDecision` 的合取项):①本部署
+ *    没接规则店;②引擎对这条命令没铸出候选;③命令原字节读不出;④这只 ask 没有已验明的属主。②③是
+ *    **这张卡**的局限,不是部署形态 ⇒ 🔴 **禁**据它判断「这台部署不供规则」(帧上 `ruleSuggestions` 缺席
+ *    时同理,见 {@link ToolApprovalFrame.ruleSuggestions});
+ *  · `rule_input_edited` —— 回决同时带了 `updatedInput`(ctrl+g 编辑放行):生效的是编辑后那份,而候选是
+ *    引擎从**原始**命令铸的 ⇒ v1 拒绝这次持久化(否则「把危险命令改安全 + 勾上不再询问」会给原始那条
+ *    危险命令装上常驻放行规则);
+ *  · `rule_not_offered` —— 报回的文本不在这只 ask 的候选里(旧卡残留 / 有人在试着自铸规则);
+ *  · `rule_store_error` —— 规则店抖动。裁决**照常生效**,只是没存上;
+ *  · `rule_governance_forced`(server ≥7.12.0,#204)—— 这只 ask 的门来自部署的**运维治理层**
+ *    (`governanceForced`),所以它压根没进规则车道。🔴 **与 `rule_lane_unavailable` 刻意分词**:后者是
+ *    「规则店/候选/命令字节/属主」四缺其一(其中两件是本卡局限),这个是「车道好好的,只是**这一只**
+ *    ask 归 operator 管」。⚠️ **两个词都是 per-ask 结局,谁都不是部署级判据** —— 上一格已经写死了
+ *    `rule_lane_unavailable` 禁据以判部署,这一格同理。要判「这台部署供不供规则」只有一个正确来源:
+ *    `capabilities.permissionRules`。处置 = 这一只不渲「不再询问」,**下一只照常渲**。
+ */
+export type RuleRefusalReason = "no-candidates" | "unknown-candidate" | "confirm-refused" | "redeem-refused" | "rule_lane_unavailable" | "rule_input_edited" | "rule_not_offered" | "rule_store_error" | "rule_governance_forced";
 export interface ToolApprovalFrame {
     type: "tool_approval" | "tool_approval_complete";
     /** The id to echo back to {@link ToolApprovalsResource.respond}. */
@@ -122,6 +172,36 @@ export interface ToolApprovalFrame {
      * 分辨 —— server 选择让键缺席而不是猜)。所以缺席**不得**渲染成「这门可以用表态绕开」。
      */
     governanceForced?: true;
+    /**
+     * "tool_approval" only, ADDITIVE (server #154 车二 / core 5.18.0 design/179): the rule candidates the ENGINE
+     * minted for this ask — render them as the "don't ask again" options and echo the chosen one back as
+     * {@link ToolApprovalsResource.respond}'s `persistRule.rule`.
+     *
+     * 📏 HOW MANY, TODAY: core 5.22.0's miner (`suggestRulesForCommand`) emits AT MOST ONE candidate, always
+     * `match: "exact"` — no shipped producer mints the broader prefix option. `prefix` stays in the closed
+     * vocabulary because the wire validator accepts it and a later miner may emit it; render whatever arrives,
+     * but do NOT build a UI that assumes a narrow/broad PAIR is on offer.
+     *
+     * 🔴 **PRESENCE IS THE PROMISE**: the key is present ONLY on a deployment that actually has a permission-rule
+     * store wired (the same object the engine's `permissionRules.storeWired` manifest bit reports). A deployment
+     * without one omits it rather than offering an option that has nowhere to redeem.
+     * 🔴 The CONVERSE does not hold: ABSENT means "THIS CARD has no redeemable candidate" — three causes produce
+     * it (no rule store wired, the engine minted no candidate for this command — compound / redirect /
+     * substitution — or the command bytes were unreadable), and one frame cannot tell them apart. Never diagnose
+     * the deployment's rule lane from a single absence, and never synthesize a candidate to fill the gap.
+     * 🔴 The values are the engine's VERBATIM (closed `match` vocabulary + engine-minted text); the server neither
+     * re-mints nor re-orders them, and neither should you — a hand-built rule string is refused
+     * (`ruleRefusal: "rule_not_offered"`), by construction.
+     *
+     * ⚠️ REDEMPTION SCOPE (stated honestly): this key also rides the durable card replay, but its only redemption
+     * channel is the LIVE respond leg keyed by the frame's `approvalId` — an in-process map that lives on ONE
+     * replica. Same-replica reconnect ⇒ redeemable; after a restart / on another replica that `approvalId` is a
+     * 404 and the person must use the durable decide leg
+     * ({@link ToolApprovalsResource.decideAsk}), which carries NO rule field in v1 (its body is strict — an extra
+     * `persistRule` is a loud 400, not a silent drop). This is the same availability envelope `approvalId` itself
+     * has; do not read a replayed suggestion as a promise that it is still redeemable.
+     */
+    ruleSuggestions?: RuleSuggestion[];
     /** "tool_approval" only (server ≥ core 5.9.0 W1, [2535]): the ask's DELEGATION provenance chain —
      *  `{parentToolCallId, depth, agentName?}` (the innermost grandchild frame wins). Present on the same door as
      *  {@link fromSubagent} (child asks only). Read-only display enrichment (the approval card can show where the
@@ -197,6 +277,11 @@ export interface ApprovalCard {
      *  判据边界逐字见 {@link ToolApprovalFrame.governanceForced}。放在卡的顶层而不是 {@link risk} 里:
      *  `risk` 讲引擎对这次操作的风险判定,本键讲**门是谁下的**,两件事。 */
     governanceForced?: true;
+    /** ADDITIVE(#154 车二 / core 5.18.0 design/179):引擎为这次 ask 铸的规则候选 —— 呈卡面据它渲
+     *  「不再询问」,回决时用 `persistRule.rule` 报出选中的那一条。
+     *  语义、**「在场性即承诺」**(只在规则店真装配时在场)与兑付面的射程逐字见
+     *  {@link ToolApprovalFrame.ruleSuggestions} —— live 帧 / `card_json` / 重放帧三面**同一份素材**。 */
+    ruleSuggestions?: RuleSuggestion[];
     /** 在场 ⇔ 本 ask 来自**委派子代**(显式判别位,worker 不可伪造)。恒 `true` 或缺席。 */
     fromSubagent?: true;
     /** 子代的 core session id —— 行 join 值 + 对早于 `fromSubagent` 的 server 的回落判别位。 */
@@ -211,7 +296,7 @@ export interface ApprovalCard {
  *  **新增帧字段必须同步进本清单**(有测试钉)。 */
 export declare const APPROVAL_REQUEST_FRAME_KEYS: readonly ["type", "schemaVersion", "askId", "taskId", "kind", "card", "expiresInMs", "expiresAtMs", "serverNowMs", "approvalId"];
 /** {@link ApprovalCard} 的字段名清单(同上,卡是嵌套结构,单独一份)。 */
-export declare const APPROVAL_CARD_KEYS: readonly ["toolName", "message", "args", "argsOmitted", "toolCallId", "risk", "governanceForced", "fromSubagent", "sourceTaskId", "sourceAgentName", "delegation"];
+export declare const APPROVAL_CARD_KEYS: readonly ["toolName", "message", "args", "argsOmitted", "toolCallId", "risk", "governanceForced", "ruleSuggestions", "fromSubagent", "sourceTaskId", "sourceAgentName", "delegation"];
 /** 流内审批呈卡帧(SSE,`type` 即事件名;design/172 §3.1 + 车3 §4.1)。**两腿两形**:live 腿上它与
  *  `tool_approval`/`question`/`elicitation` 同一条 out-of-band 通道、在 token 流上交织,**不是**
  *  `AgentEvent` 臂(按 SSE `event:` 名分派);durable 腿上 server 会 append 它,于是同一帧在
@@ -387,6 +472,20 @@ export interface ToolApprovalRespondAck {
      *  引擎(是否被消费取决于 core OnAsk 对象臂是否到位——诚实措辞:forwarded≠applied)。deny/未带编辑/
      *  旧 server=字段省略(tolerate-absent)。 */
     updatedInputForwarded?: boolean;
+    /**
+     * #154 车二,ADDITIVE:这次回决携带的 `persistRule` 到底有没有落进规则店。
+     *
+     * 🔴 **规则没存上从不翻转裁决**:人的「允许这次」已经生效并交给引擎了,把整个回决改判成 4xx 会让一次
+     * 真实的放行凭空消失。所以失败的诚实形恒是 **200 + `rulePersisted: false` + {@link ruleRefusal}**,壳据
+     * 此告诉人「这次放行了,但『不再询问』没存上」——**不要**把它渲成整次审批失败。
+     * 未带 `persistRule` 的回决 / 旧 server ⇒ 字段省略(tolerate-absent);缺席 ≠ `false`。
+     */
+    rulePersisted?: boolean;
+    /** #154 车二,ADDITIVE:`rulePersisted: false` 时的**机读**理由(闭词表,见 {@link RuleRefusalReason})。
+     *  `rulePersisted: true` 时恒缺席。壳按它分「换下一次再存」(`rule_input_edited`)与「这张卡上没有可兑的
+     *  东西」(`rule_lane_unavailable`)。🔴 后者**四种成因共用一格、两种是本卡局限** ⇒ 禁据它判断整台部署,
+     *  逐条见 {@link RuleRefusalReason}。 */
+    ruleRefusal?: RuleRefusalReason;
 }
 export declare class ToolApprovalsResource {
     private readonly t;
@@ -408,6 +507,22 @@ export declare class ToolApprovalsResource {
          *  非 patch)。deny 上 server 静默忽略;旧 server 同样忽略未知键(前向兼容)。透传与否看 ack 的
          *  `updatedInputForwarded`。 */
         updatedInput?: unknown;
+        /**
+         * #154 车二,ADDITIVE —— 人勾了「不再询问」:把 {@link ToolApprovalFrame.ruleSuggestions} 里**选中那条
+         * 的 `rule` 文本原样**报回来。allow 族才有意义(deny 上 server 宽收后忽略,同 `updatedInput` 姿势)。
+         *
+         * 🔴 **只能是候选之一,不是自由规则**:server 拿这段文本在引擎铸的候选表里定位下标,对不上就拒
+         * (`ruleRefusal: "rule_not_offered"`)。所以别拼、别改大小写、别自己加 `:*` —— 原样取自帧。
+         * 🔴 与 `updatedInput` **同时**在场 ⇒ server 拒绝这次持久化(`rule_input_edited`):生效的调用是编辑后
+         * 那份,而候选是引擎从原始命令铸的,给原始那条装规则是真扩权。裁决本身照常生效。
+         * ⚠️ 帧上没有 `ruleSuggestions` 时**别发这一键**:**这张卡**没有可兑的东西,发了拿回的必定是
+         * `rulePersisted:false` + **`rule_lane_unavailable`**(素材缺席在候选比对**之前**就短路了,所以不会是
+         * `rule_not_offered`)。缺席有**三个**可能成因 —— 没接规则店 / 引擎对这条命令铸不出候选(复合、重定向、
+         * 替换)/ 命令原字节读不出 —— 所以**别**据一帧、也别据这一个拒绝理由去判断整台部署的规则车道在不在。
+         */
+        persistRule?: {
+            rule: string;
+        };
     }, opts?: {
         signal?: AbortSignal;
     }): Promise<ToolApprovalRespondAck>;

package/dist/resources/tool-approvals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-approvals.d.ts","sourceRoot":"","sources":["../../src/resources/tool-approvals.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-approvals.d.ts","sourceRoot":"","sources":["../../src/resources/tool-approvals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kGAmDkG;AAClG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;yBAIyB;AACzB,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,eAAe,GAAG,MAAM,CAAC;AAEtE;;;;;;kEAMkE;AAClE;;;uCAGuC;AACvC,eAAO,MAAM,wBAAwB,gNAe3B,CAAC;AAEX;;;;;;;;gDAQgD;AAChD,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,iBAAiB,GACzB,eAAe,GACf,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,GAChB,uBAAuB,GACvB,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,GAClB,wBAAwB,CAAC;AAE7B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,GAAG,wBAAwB,CAAC;IACjD,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;qGAMiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;+DAK2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;oCAIgC;IAChC,YAAY,CAAC,EAAE,IAAI,CAAC;IACpB;;;qCAGiC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8GAA8G;IAC9G,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,EAAE,IAAI,CAAC;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC;;;6GAGyG;IACzG,UAAU,CAAC,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7E;;;;;sEAKkE;IAClE,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAeD;sEACsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,MAAM,CAAC;AAErD;;;;;;;wDAOwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,0CAA0C;AAC1C,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;yBAUyB;AACzB,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,oEAAoE;IACpE,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,IAAI,EAAE,gBAAgB,CAAC;IACvB;;;iDAG6C;IAC7C,gBAAgB,CAAC,EAAE,IAAI,CAAC;IACxB;;;8FAG0F;IAC1F,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,IAAI,CAAC;IACpB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,UAAU,CAAC,EAAE,sBAAsB,CAAC;CACrC;AAED;;+BAE+B;AAC/B,eAAO,MAAM,2BAA2B,kIAW9B,CAAC;AAEX,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,uLAarB,CAAC;AAEX;;;;;;;;;;;;;;;;;;wCAkBwC;AACxC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,wEAAwE;IACxE,aAAa,EAAE,CAAC,CAAC;IACjB;;;8CAG0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf;wEACoE;IACpE,IAAI,EAAE,YAAY,CAAC;IACnB,eAAe;IACf,IAAI,EAAE,YAAY,CAAC;IACnB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB;8DAC0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,kDAAkD;AAClD,eAAO,MAAM,0BAA0B,kFAAmF,CAAC;AAE3H;;;;;;sEAMsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,4DAA4D;IAC5D,aAAa,EAAE,CAAC,CAAC;IACjB,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;yCAGqC;IACrC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;;;;;;;gEASgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC7D,4BAA4B;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAkDD;;;;;mDAKmD;AACnD,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,oBAAoB,CAO9E;AAED;yEACyE;AACzE,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,mBAAmB,CAM5E;AAED;;;;;;;;;;;;;mFAamF;AACnF,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;8DAE0D;IAC1D,GAAG,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CAC5B;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B;;sEAEkE;IAClE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;uFACmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;oEACgE;IAChE,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3B;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB;;mEAE+D;IAC/D,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;;mDAI+C;IAC/C,qBAAqB,CAAC,EAAE,IAAI,CAAC;CAC9B;AAED;2EAC2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;yCAEqC;IACrC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;0CAEsC;IACtC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;yCAGqC;IACrC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED,qBAAa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;;;;;;;;;uGAUmG;IAC7F,OAAO,CACX,EAAE,EAAE,MAAM,EACV,IAAI,EAAE;QACJ,QAAQ,EAAE,oBAAoB,CAAC;QAC/B;;uCAE+B;QAC/B,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB;;;;;;;;;;;;WAYG;QACH,WAAW,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KAChC,EACD,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC9B,OAAO,CAAC,sBAAsB,CAAC;IASlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iEAkC6D;IACvD,SAAS,CACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,eAAe,EACrB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC9B,OAAO,CAAC,cAAc,CAAC;CAQ3B"}

package/dist/resources/tool-approvals.js

@@ -21,6 +21,7 @@ export const TOOL_APPROVAL_FRAME_KEYS = [
     "args",
     "argsOmitted",
     "governanceForced",
+    "ruleSuggestions",
     "delegation",
     "outcome",
 ];
@@ -48,6 +49,7 @@ export const APPROVAL_CARD_KEYS = [
     "toolCallId",
     "risk",
     "governanceForced",
+    "ruleSuggestions",
     "fromSubagent",
     "sourceTaskId",
     "sourceAgentName",
@@ -78,6 +80,15 @@ function isApprovalCardDelegationV1(v) {
     const d = v;
     return isStr(d.parentToolCallId) && isNum(d.depth) && optIs(d.agentName, isStr);
 }
+/** 一条候选的逐键判据。**`match` 必须是闭词表内的值**:一条 `match: "regex"` 的「候选」若被窄化成可信形,
+ *  壳会渲出一格按下去必被 server 拒(`rule_not_offered`/`unknown-candidate`)的「不再询问」—— 而人已经
+ *  以为自己存下了一条规则。这正是可选键判据必须覆盖**在场形**的那条纪律。 */
+function isRuleSuggestionV1(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const s = v;
+    return isStr(s.rule) && isStr(s.command) && (s.match === "exact" || s.match === "prefix");
+}
 function isApprovalCardV1(v) {
     if (typeof v !== "object" || v === null)
         return false;
@@ -87,6 +98,7 @@ function isApprovalCardV1(v) {
     // `args` 是 `unknown` —— 任何 JSON 值都合法,没有可校验的形(帽/洗涤是 server 的责任)。
     return (optTrue(c.argsOmitted) &&
         optIs(c.toolCallId, isStr) &&
+        optIs(c.ruleSuggestions, (x) => Array.isArray(x) && x.every(isRuleSuggestionV1)) &&
         optTrue(c.fromSubagent) &&
         optIs(c.sourceTaskId, isStr) &&
         optIs(c.sourceAgentName, isStr) &&

package/dist/resources/tool-approvals.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-approvals.js","sourceRoot":"","sources":["../../src/resources/tool-approvals.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-approvals.js","sourceRoot":"","sources":["../../src/resources/tool-approvals.ts"],"names":[],"mappings":"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"}

package/dist/resources/trace.d.ts

@@ -2,7 +2,7 @@
  *  timeline; artifacts (diff/files/git-push) = the deliverable. Needs a SESSION_BACKEND=tidb worker.
  *  A web workspace view is built ENTIRELY from this — keep it the SHARED model for all doors. */
 import type { Transport } from "../transport.js";
-import type { Artifact, TaskSummary, TraceStreamEvent, TraceTurn } from "../types.js";
+import type { Artifact, TaskSummary, ToolResultSlice, TraceStreamEvent, TraceTurn } from "../types.js";
 export declare class TraceResource {
     private readonly t;
     constructor(t: Transport);
@@ -64,6 +64,35 @@ export declare class TraceResource {
     }): Promise<{
         artifacts: Artifact[];
     }>;
+    /** GET /v1/tasks/:id/tool-results/:ref[?offset=&limit=] — page an OFFLOADED (large) tool result back.
+     *
+     *  When a tool returns more text than the worker's offload threshold, the conversation keeps a preview plus a
+     *  `ref` (`<persisted-output ref="tr_…">`) and the full text moves into the deployment's durable tool-result
+     *  store. This reads a slice of it — the same data the model itself pages through — so a workspace can show
+     *  the whole output instead of the preview. Pass the `ref` VERBATIM as it appeared; never re-derive it (it is
+     *  minted by the engine from sessionId+toolCallId with its own escaping, and this SDK does not mirror that).
+     *
+     *  Paging: `totalChars` is the FULL length, `offset` echoes the slice start; read until
+     *  `offset + content.length === totalChars` and concatenate — the pieces join byte-exactly.
+     *
+     *  SCOPE: ask on the task whose trace showed the ref. The worker binds the ref to THAT task's own durable
+     *  event log (it re-derives the ref from the log's tool-call ids) — trace and this face read the same log, so
+     *  "visible in the task's trace ⇒ readable here" holds, while a ref carried over from a DIFFERENT task of the
+     *  same session is a 404: ask for it under that task's id. Refs the engine mints from SYNTHETIC ids
+     *  (background-agent output spills, Monitor stream segments, compaction offloads) are not attested by the log
+     *  and answer the same 404 — this out-of-band face refuses what it cannot prove ownership of.
+     *
+     *  🔴 The 404 is UNIFORM by design (`not_found.tool_result`): a ref the task's log does not attest (unknown /
+     *  another session's / another task's), a worker with no durable tool-result store, and an attested ref whose
+     *  content was already reaped are byte-identical responses — a distinguishable arm would be an existence /
+     *  deployment-shape oracle. So do NOT branch on them, and do not expect a 501 for "feature not configured":
+     *  treat any 404 as "this output is not available to you here", the same way the model's own page-back
+     *  degrades. Out-of-range `limit` (>262144) / `offset` (>2147483646) are 400s, never a silent clamp. */
+    toolResult(taskId: string, ref: string, opts?: {
+        offset?: number;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<ToolResultSlice>;
     /** GET /v1/tasks/:id/stream — the workspace LIVE timeline (`streamTaskTrace` + `mapTraceEvent`, server.ts).
      *  RESUMABLE SSE with a DISTINCT vocabulary from `runs.events`/AgentEvent: the durable log is BLOCK-grained,
      *  so each frame is a `block-content-delta` / `block-thinking-delta` / `tool-call` / `tool-result` / `turn` /

package/dist/resources/trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/resources/trace.ts"],"names":[],"mappings":"AAAA;;iGAEiG;AACjG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGtF,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;4DAEwD;IAClD,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAYtM;;;;;;;8EAO0E;IAGpE,aAAa,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAOxK;;;;;;;yFAOqF;IAC/E,KAAK,CACT,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC/D,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAQ9E;2HACuH;IACjH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;IASpG;;;;;;;;;;kFAU8E;IACvE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC,gBAAgB,CAAC;CA6BvH"}
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/resources/trace.ts"],"names":[],"mappings":"AAAA;;iGAEiG;AACjG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGvG,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;4DAEwD;IAClD,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAYtM;;;;;;;8EAO0E;IAGpE,aAAa,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAOxK;;;;;;;yFAOqF;IAC/E,KAAK,CACT,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC/D,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAQ9E;2HACuH;IACjH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;IASpG;;;;;;;;;;;;;;;;;;;;;;;4GAuBwG;IAClG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC/D,OAAO,CAAC,eAAe,CAAC;IAa3B;;;;;;;;;;kFAU8E;IACvE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC,gBAAgB,CAAC;CA6BvH"}

package/dist/resources/trace.js

@@ -67,6 +67,44 @@ export class TraceResource {
             signal: opts?.signal,
         });
     }
+    /** GET /v1/tasks/:id/tool-results/:ref[?offset=&limit=] — page an OFFLOADED (large) tool result back.
+     *
+     *  When a tool returns more text than the worker's offload threshold, the conversation keeps a preview plus a
+     *  `ref` (`<persisted-output ref="tr_…">`) and the full text moves into the deployment's durable tool-result
+     *  store. This reads a slice of it — the same data the model itself pages through — so a workspace can show
+     *  the whole output instead of the preview. Pass the `ref` VERBATIM as it appeared; never re-derive it (it is
+     *  minted by the engine from sessionId+toolCallId with its own escaping, and this SDK does not mirror that).
+     *
+     *  Paging: `totalChars` is the FULL length, `offset` echoes the slice start; read until
+     *  `offset + content.length === totalChars` and concatenate — the pieces join byte-exactly.
+     *
+     *  SCOPE: ask on the task whose trace showed the ref. The worker binds the ref to THAT task's own durable
+     *  event log (it re-derives the ref from the log's tool-call ids) — trace and this face read the same log, so
+     *  "visible in the task's trace ⇒ readable here" holds, while a ref carried over from a DIFFERENT task of the
+     *  same session is a 404: ask for it under that task's id. Refs the engine mints from SYNTHETIC ids
+     *  (background-agent output spills, Monitor stream segments, compaction offloads) are not attested by the log
+     *  and answer the same 404 — this out-of-band face refuses what it cannot prove ownership of.
+     *
+     *  🔴 The 404 is UNIFORM by design (`not_found.tool_result`): a ref the task's log does not attest (unknown /
+     *  another session's / another task's), a worker with no durable tool-result store, and an attested ref whose
+     *  content was already reaped are byte-identical responses — a distinguishable arm would be an existence /
+     *  deployment-shape oracle. So do NOT branch on them, and do not expect a 501 for "feature not configured":
+     *  treat any 404 as "this output is not available to you here", the same way the model's own page-back
+     *  degrades. Out-of-range `limit` (>262144) / `offset` (>2147483646) are 400s, never a silent clamp. */
+    async toolResult(taskId, ref, opts) {
+        const q = new URLSearchParams();
+        // `!== undefined`,不是真值判断:`offset: 0` / `limit: 0` 是合法请求(sourceSummary 的 falsy-drop 前科同族)。
+        if (opts?.offset !== undefined)
+            q.set("offset", String(opts.offset));
+        if (opts?.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString();
+        return this.t.request({
+            method: "GET",
+            path: `/v1/tasks/${encodeURIComponent(taskId)}/tool-results/${encodeURIComponent(ref)}${qs ? `?${qs}` : ""}`,
+            signal: opts?.signal,
+        });
+    }
     /** GET /v1/tasks/:id/stream — the workspace LIVE timeline (`streamTaskTrace` + `mapTraceEvent`, server.ts).
      *  RESUMABLE SSE with a DISTINCT vocabulary from `runs.events`/AgentEvent: the durable log is BLOCK-grained,
      *  so each frame is a `block-content-delta` / `block-thinking-delta` / `tool-call` / `tool-result` / `turn` /

package/dist/resources/trace.js.map

@@ -1 +1 @@
-{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/resources/trace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/resources/trace.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -454,6 +454,31 @@ export interface TaskRequest {
      *  deployment supports them). Probe `capabilities.interactiveTools` (server hardcodes true — the `interactiveTools` bit in `routes/capabilities.ts`)
      *  before sending to OLDER servers — an unknown-field deployment on the strict lane would 400. */
     interactiveTools?: boolean;
+    /**
+     * 🔴 ONE-SHOT SUBMISSION declaration (core ≥5.23.0 `TaskSpec.oneShot`, server ≥7.12.0 —
+     * `src/http/wire-types.ts` 的请求形;非 boolean = fail-loud 400 `request.field_invalid`
+     * "oneShot must be a boolean",不是静默强转).
+     *
+     * `true` = **这次提交**是一次性的:不存在一个后续回合能接住异步的后台通知。原型就是 headless `sema -p`
+     * ——回合一结束进程就退了。
+     *
+     * 🔴 **它什么权限都不给,也什么都不保证** —— core 只把它当**给模型的指引**用:`RunWorkflow` / 委派回执
+     * 里那句话从「结束回合,到时会通知你」(有下一回合时才对)改成「用 `TaskOutput({block:true})` 主动
+     * 阻塞等」。**不发**,headless 调用方会丢后台结果 —— 这是这个键存在的理由;但**发了也只是尽力而为**,
+     * 不是完成契约(codex 对抗复审 [medium]):模型可以不听那句话、也可能预算先耗尽,而且有的腿根本没有
+     * 轮询路径。真需要拿到结果的调用方,自己那步等待/对账**不能省**。没有租户门,因为没有可 gate 的能力。
+     *
+     * 🔴 **发它之前先探 {@link Capabilities.oneShot}**(codex 对抗复审 R2 [medium] 提出,上游采纳后
+     * server 7.12.0 加位):提交体是**开集**(server 不拒未知键),所以一台还没接这个键的 worker 收下
+     * `oneShot: true`、回 200、然后照旧告诉模型「结束回合等通知」—— 没有 400、没有警告。**能力位缺席就是
+     * 那台 worker** ⇒ 键正被忽略,自己那步等待/对账不能省。
+     * ⚠️ 位**在场**也不解除那步:它证明的是「键被消费」,不是「结果一定收得到」(见上一段:指引 ≠ 契约)。
+     *
+     * **按请求走**是刻意的:「这次提交期不期待被继续」是**提交**的属性,不是它到达的那条连接的属性。
+     * 与 {@link interactiveTools}(同一个 `-p` 姿态)是姊妹键,透传方式逐字相同:布尔才上路,**缺席 ⇒ 键
+     * 被省略**、core 的默认(交互态)生效。会随持久化的 body 骑到 resume 腿上。
+     */
+    oneShot?: boolean;
     /** 🔴 Retain background processes past the turn (server `src/http/wire-types.ts:179` 的请求形 — STRICT boolean, else 400).
      *  `true` = backgrounded Bash tasks (b*) survive the run's turn end instead of being reaped (long dev servers,
      *  watch builds). HONORED only on a single-user deployment (`capabilities.retainBackgroundProcesses` =
@@ -1115,6 +1140,20 @@ export interface Artifact {
     deletions?: number;
     [k: string]: unknown;
 }
+/** One slice of an offloaded (large) tool result — `GET /v1/tasks/:taskId/tool-results/:ref`, the wire form
+ *  of the engine's `ToolResultSlice`. CLOSED shape (three keys, no index signature): the server's mint point
+ *  projects exactly these.
+ *
+ *  Paging: `offset` echoes where the slice starts and `totalChars` is the FULL stored length (never the
+ *  slice's), so the loop is `while (offset + content.length < totalChars) read(offset + content.length)` and
+ *  the concatenation is byte-exact. */
+export interface ToolResultSlice {
+    content: string;
+    /** Char offset this slice starts at. */
+    offset: number;
+    /** Total chars of the FULL stored content (independent of this slice). */
+    totalChars: number;
+}
 /** The `suspended` event's gate payload (core checkpoint-store). Tool args / question text
  *  are NOT here — join the same task's trace tool-call block via approvals' toolCallId.
  *
@@ -1689,6 +1728,49 @@ export interface Capabilities {
      *  SDK 1.0.0 已删)。⚠️ 与 {@link TaskRequest.memoryWrite}(per-run 记忆引擎写 PAUSE 开关,live 且不受本位
      *  gate)不是一回事 —— 同名不同物。 */
     memoryWrite?: boolean;
+    /** design/177 org 共享记忆库只读面(`GET /v1/shared-memory/*`)已挂载。server 侧判据与路由域的挂载合取式
+     *  **逐字相同**(SQL 供给面在场 ∧ principal→org 成员折叠面在场),true ⟺ 面真能打通——只有 store 没有
+     *  成员性判据的部署刻意报 false(且不挂载路由)。probe before use,勿 trial-by-501。 */
+    sharedMemory?: boolean;
+    /** design/183 form b 收编面(`POST /v1/adoption` + `GET /v1/adoption/:id`,operator lane)已挂供给。
+     *  server 谓词与 handleAdoption 的 501 同源(SQL backend 的 adoptionLog 工厂在场;local 后端诚实缺席)。
+     *  probe before use,勿 trial-by-501。 */
+    adoption?: boolean;
+    /** #154 + design/203 §2 规则车道(`/v1/rules/cc-import/*` 两口 + `GET`/`DELETE /v1/rules` 撤销面两口 +
+     *  respond `persistRule` 兑付口)可用。server 谓词=`PERMISSION_RULES_ENABLED ∧ 规则店 wired`
+     *  (🔴 旋钮默认**分两段**:≤7.11.0 默认 `false`,7.12.0 起默认 `true` ⇒ 别按「默认关」推断这一位),
+     *  与这台 server **所有**规则口的 501 **同一条**谓词 ⇒ 说 yes ⟺ 它有的那些口**全都**活(不是「有一口活」)。
+     *  ⚠️ 面的条数随 server 版本长:≤7.11.0 是导入两口 + 兑付口,7.12.0 起再加撤销面两口 —— 本位说的是
+     *  「车道在不在」,不是「有几条口」,所以别拿它反推 server 版本。 */
+    permissionRules?: boolean;
+    /** design/203 §2(server ≥7.12.0):撤销面两口(`GET`/`DELETE /v1/rules`)在这台 worker 上**已被路由**。
+     *  deps 谓词与 {@link permissionRules} **同源**,真正带信息的是这一位的**在场性本身**。
+     *  🔴 这正是它必须是**第二个位**而不是把第一个位改严的理由:≤7.11.0 的 worker 上 `permissionRules`
+     *  已经报 true 而这两口 404(位早于路由),那个位因此分不出「车道没开」与「这份二进制比撤销面老」,
+     *  而它已发布的成文语义(「四口都活」)在那些包上本来就是谎 —— **只能加位,不能追改位**。
+     *  **缺席 ⇒ 老 worker**:`rules.list` / `rules.revoke` 会拿到 404 `not_found.route`,治理入口该藏起来;
+     *  **在场 ⇒ 路由在**(它接着答不答,照旧看 {@link permissionRules})。 */
+    permissionRulesRevoke?: boolean;
+    /** server ≥7.12.0:这台 worker **真的消费** {@link TaskRequest.oneShot}(布尔才投影进 TaskSpec、缺席不写
+     *  键、非布尔 400)。恒 true —— 消费不依赖任何可选设施。
+     *  🔴 **用那个字段之前先探这一位**:提交体是**开集**,不消费这个键的 worker 照样收下并回 200 ——
+     *  一个 headless 调用方会以为自己声明了一次性形,却拿不到 core 的 block-wait 指引,后台结果就这么丢了,
+     *  而 wire 上没有任何迹象。**缺席 ⇒ 键正被忽略**,自己那步等待/对账不能省。
+     *  (⚠️ 这一位**在场**也不解除那步:该字段是给模型的指引,不是完成契约。) */
+    oneShot?: boolean;
+    /** design/201 §3(server ≥7.12.0):这份二进制里**有没有** `permissionMode` → `spec.shellGate` 的翻译表
+     *  (bypassPermissions ⇒ off;auto/default/acceptEdits/plan ⇒ classify;表态缺席 ⇒ 不写键)。
+     *  **恒 true 且与翻译表同一个 commit** —— 这一位说的不是「配置在不在」而是「这份二进制里有没有那张表」,
+     *  所以「says yes ⟺ 翻译真在」是结构性的,没有任何 deps 缺席能让它变假。
+     *  🔴 **判据必须是「所连 server 广告本位」,绝不是壳自身版本**:壳据它撤掉对 `MANUAL_MODE_SHELL_GATE`
+     *  的无条件 env 注入,而按壳版本判会在三种真部署下开天窗(新壳连老 server / 副本回滚到旧二进制 / 混版
+     *  fleet)—— 那正是「翻译还没到货但壳已经撤注」的放宽窗。缺席/false ⇒ 继续注。 */
+    modeShellGateTranslation?: boolean;
+    /** design/73 §7.2(server ≥7.12.0):`GET /v1/outcomes` 机械信号只读聚合面可用。server 谓词逐项对着该
+     *  路由的拒绝臂:①可查询的账面在场(`outcomeSink.summary` —— File sink 只写 JSONL、没有查询面 ⇒ 501);
+     *  ②多租户下 operator 名单非空(单用户形无此门 —— 唯一的用户就是 operator)。
+     *  补这一位是因为该面此前**有 501 拒而无能力位**,消费端只能 trial-by-501 —— 而那正是能力面存在的目的。 */
+    outcomeLedger?: boolean;
     /** 2c session-sync (P1d) — the `/v1/sessions/:id/sync/*` peer routes resolve. The server predicate is a
      *  **FOUR-way** conjunction (`src/http/routes/capabilities.ts`): durable backend ∧ `exportEntries` ∧
      *  `beginImportStaging` ∧ a file-snapshot store. 🔴 The fourth conjunct is the correction: this doc used to