@zooique/memora 3.0.1 → 5.0.0

package/dist/agent/toolLedger.js.map

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

package/dist/agent/toolResultCache.js

@@ -5,7 +5,7 @@
  * 同一参数重复调用既浪费 token 又无增量价值（文件未变 / 同 query 网络结果近似）。
  * 本缓存以「闭环内去重」为粒度——闭环结束即清空，跨闭环不复用。
  *
- * 拦截语义与 loop 已有的 web_search MAX_WEB_SEARCH_CALLS / ask_user askLimit 同级：
+ * 拦截语义与 loop 已有的 web_search 搜索上限护栏 / ask_user askLimit 同级：
  * 检测到重复 → blocked=true（不算工具失败）→ 返回 [ALREADY_READ] 拒绝文案。
  *
  * **去重主体是结构化的**（`DedupSubject`），不是预先拼好的字符串 key：

package/dist/agent/toolResultOffload.d.ts

@@ -44,6 +44,14 @@ export interface ToolResultOffloadOptions {
     thresholdTokens?: number;
     /** 预览字符数（默认 1,000） */
     previewChars?: number;
+    /**
+     * 尾部预览字符数（默认 0 = 只留头部）。
+     *
+     * >0 时从**总预览预算内**划出尾部份额（头 = previewChars − 尾），**不扩大预算**——
+     * 预算扩大会让替换文本逼近单条上限，破坏「替换后不二次落盘」的结构性保证。
+     * 用途同 `SCRIPT_RESULT_TAIL_CHARS`：长输出的关键信息常在尾部（见缺口 D）。
+     */
+    tailPreviewChars?: number;
 }
 /**
  * 单条工具结果超阈 → 落盘 + 生成替换文本；否则原样返回。

package/dist/agent/toolResultOffload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolResultOffload.d.ts","sourceRoot":"","sources":["../../src/agent/toolResultOffload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAYH,oCAAoC;AACpC,MAAM,WAAW,wBAAwB;IACvC,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,WAAW;AACX,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,wBAAwB,GAC7B,wBAAwB,CA+B1B"}
+{"version":3,"file":"toolResultOffload.d.ts","sourceRoot":"","sources":["../../src/agent/toolResultOffload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAYH,oCAAoC;AACpC,MAAM,WAAW,wBAAwB;IACvC,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,WAAW;AACX,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,wBAAwB,GAC7B,wBAAwB,CA0C1B"}

package/dist/agent/toolResultOffload.js

@@ -57,11 +57,18 @@ export function offloadLargeToolResult(content, opts) {
         logger.warn({ err, filePath, tokens }, '工具结果卸载失败，已降级为原文入上下文（未产生引用）');
         return { content, offloaded: false };
     }
-    const preview = content.slice(0, previewChars);
-    const omitted = Math.max(0, content.length - previewChars);
+    // 头（+可选尾）份额均在 previewChars 预算内划分，不扩大总预览量
+    const tailChars = Math.min(Math.max(opts.tailPreviewChars ?? 0, 0), Math.max(previewChars - 1, 0));
+    const headChars = previewChars - tailChars;
+    const head = content.slice(0, headChars);
+    const tail = tailChars > 0 ? content.slice(content.length - tailChars) : '';
+    const omitted = Math.max(0, content.length - headChars - tailChars);
+    const previewBlock = tailChars > 0
+        ? `[预览（头 ${headChars} + 尾 ${tailChars} 字符）]\n${head}\n…[省略 ${omitted} 字符]…\n${tail}`
+        : `[预览（前 ${previewChars} 字符）]\n${head}…`;
     return {
         content: `[工具结果已卸载至磁盘] 原文 ${content.length} 字符（≈${tokens} tokens）写入：${filePath}\n` +
-            `[预览（前 ${previewChars} 字符）]\n${preview}…\n` +
+            `${previewBlock}\n` +
             `[省略 ${omitted} 字符。需要完整内容请用 read_file 读取上述路径，大文件可配合 offset/limit 分段读取]`,
         offloaded: true,
         filePath,

package/dist/agent/toolResultOffload.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolResultOffload.js","sourceRoot":"","sources":["../../src/agent/toolResultOffload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,wCAAwC;AACxC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AA4BpC;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAe,EACf,IAA8B;IAE9B,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,IAAI,cAAc,CAAC,6BAA6B,CAAC;IACvF,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAChE,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAEtD,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sCAAsC;QACtC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,4BAA4B,CAAC,CAAC;QACrE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC;IAE3D,OAAO;QACL,OAAO,EACL,mBAAmB,OAAO,CAAC,MAAM,QAAQ,MAAM,cAAc,QAAQ,IAAI;YACzE,SAAS,YAAY,UAAU,OAAO,KAAK;YAC3C,OAAO,OAAO,yDAAyD;QACzE,SAAS,EAAE,IAAI;QACf,QAAQ;KACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"toolResultOffload.js","sourceRoot":"","sources":["../../src/agent/toolResultOffload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,wCAAwC;AACxC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAoCpC;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAe,EACf,IAA8B;IAE9B,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,IAAI,cAAc,CAAC,6BAA6B,CAAC;IACvF,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAChE,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAEtD,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sCAAsC;QACtC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,4BAA4B,CAAC,CAAC;QACrE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvC,CAAC;IAED,yCAAyC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CACxB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,gBAAgB,IAAI,CAAC,EAAE,CAAC,CAAC,EACvC,IAAI,CAAC,GAAG,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC,CAAC,CAC9B,CAAC;IACF,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC;IACpE,MAAM,YAAY,GAChB,SAAS,GAAG,CAAC;QACX,CAAC,CAAC,SAAS,SAAS,QAAQ,SAAS,UAAU,IAAI,UAAU,OAAO,UAAU,IAAI,EAAE;QACpF,CAAC,CAAC,SAAS,YAAY,UAAU,IAAI,GAAG,CAAC;IAE7C,OAAO;QACL,OAAO,EACL,mBAAmB,OAAO,CAAC,MAAM,QAAQ,MAAM,cAAc,QAAQ,IAAI;YACzE,GAAG,YAAY,IAAI;YACnB,OAAO,OAAO,yDAAyD;QACzE,SAAS,EAAE,IAAI;QACf,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/agent/toolRunner.d.ts

@@ -2,8 +2,9 @@
  * 工具执行器（ToolRunner）— 从 AgentLoop 抽出的「单工具执行」独立单元
  *
  * 承载一个工具的完整生命周期：执行前检查（三重闸门）→ 并发/中断竞争执行 → 异常转结构化错误串。
- * 状态独立（不触碰 loop 工作记忆 / 指标 / 自主步标志），输入工具调用元素、输出结果串并触发
- * onToolExecuted，故可独立单测。loop 的 executeToolCalls 只做批量编排，逐工具委托本执行器。
+ * 状态独立（不触碰 loop 工作记忆 / 指标 / 自主步标志），输入工具调用元素、输出结构化
+ * ToolOutcome（status 为判据面真源）并触发 onToolExecuted，故可独立单测。
+ * loop 的 executeToolCalls 只做批量编排，逐工具委托本执行器。
  *
  * 依赖经 deps 注入（execute / preExecutionCheck / onToolExecuted / getStrategy / tracer），
  * 其中 getStrategy 每次执行读最新策略——setStrategy 的动态更新在此依然生效。
@@ -12,14 +13,17 @@ import type { PreExecutionResult } from '../agent/types.js';
 import type { ToolDefinition } from '../agent/toolExecutor.js';
 import type { L2RuntimeStrategy } from '../role-pack/types.js';
 import type { ITracer } from '../agent/tracer.js';
+import { type ToolOutcome } from '../agent/managers/toolCallHelpers.js';
 /** 工具调用元素契约（OpenAI 协议结构）——单一真源 llm/types.ToolCall（Message.toolCalls 同源） */
 import type { ToolCall } from '../llm/types.js';
 /** 一次工具调用（LLM 输出的工具调用元素）——SSOT：形状真源在 llm/types.ToolCall（协议契约单一实现；re-export 保留本文件测试判据点） */
 export type { ToolCall };
-/** ToolRunner 依赖注入（loop 稳定的窄面；策略动态经 getStrategy 读取） */
+/** 工具执行器依赖注入（loop 稳定的窄面；策略动态经 getStrategy 读取） */
 export interface ToolRunnerDeps {
-    /** 执行单个工具（loop 的 opts.toolExecutor） */
-    execute: (name: string, args: string) => Promise<string>;
+    /** 执行单个工具（loop 的 opts.toolExecutor）。
+     *  第 3 参 emitOutcome：执行器按调用独立产出原生 outcome 的通道（见 toolExecutor.execute）
+     *  第 4 参 toolCallId：本次工具调用唯一 ID（web_search 证据配对通道，透传至 toolExecutor.execute） */
+    execute: (name: string, args: string, emitOutcome?: (outcome: ToolOutcome) => void, toolCallId?: string) => Promise<string>;
     /** 内置工具定义（只读闸查 readonly 标记） */
     builtinTools?: ToolDefinition[];
     /** 宿主执行前检查（拒绝 / 跳过 / 改写参数） */
@@ -41,9 +45,10 @@ export declare class ToolRunner {
      * 执行单个工具（并行独立执行单元，无共享状态，可安全并发）。
      * @param tc 工具调用元素
      * @param signal 中止信号（与工具执行 race，signal 先 abort 返回 ABORTED 错误串）
-     * @returns 执行结果串（成功文本或 [ERR:TOOL:code] 错误串）
+     * @returns 结构化结果（`status` 为判据面唯一真源，`text` 为渲染面——B4 判据切换后
+     *   编排层全部决策读 `status`，文本只喂 LLM / 渲染，不再参与成败判定）
      */
-    runOne(tc: ToolCall, signal?: AbortSignal): Promise<string>;
+    runOne(tc: ToolCall, signal?: AbortSignal): Promise<ToolOutcome>;
     /**
      * 执行前检查：按顺序叠加两层闸门——只读 → 宿主 preExecutionCheck，任一命中提前返回。
      * （内核不提供"审批"闸门：无"需审批"标签与回调，审批决策统一归宿主 preExecutionCheck。）
@@ -53,6 +58,10 @@ export declare class ToolRunner {
      * 工具执行与 signal abort 竞争包裹。toolExecutor 签名不接受 signal，无法真正中断；
      * 用 Promise.race 竞争，signal 先 abort 则返回 [ERR:TOOL:ABORTED]（而非抛 AbortError，
      * 避免破坏"工具失败回传 LLM"契约；ABORTED 不入错误码体系，不触发 Reflection）
+     *
+     * @param emitOutcome 原生 outcome 回调（透传给 execute；abort 出口也经它显式 emit failed，
+     *   保证 runOne 兜底（nativeOutcome ?? ok）读到中断事实而非误判 ok）
+     * @param toolCallId 工具调用唯一 ID（透传给 execute，web_search 证据配对通道）
      */
     private raceToolWithSignal;
 }

package/dist/agent/toolRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolRunner.d.ts","sourceRoot":"","sources":["../../src/agent/toolRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAMjD,2EAA2E;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,0FAA0F;AAC1F,YAAY,EAAE,QAAQ,EAAE,CAAC;AAQzB,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,+BAA+B;IAC/B,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,kBAAkB,CAAC;IACvE,iCAAiC;IACjC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC;IACnF,iDAAiD;IACjD,WAAW,EAAE,MAAM,iBAAiB,CAAC;IACrC,kBAAkB;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,cAAc;IAEjD;;;;;OAKG;IACG,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA6DjE;;;OAGG;IACH,OAAO,CAAC,cAAc;IAuCtB;;;;OAIG;YACW,kBAAkB;CA4BjC"}
+{"version":3,"file":"toolRunner.d.ts","sourceRoot":"","sources":["../../src/agent/toolRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAKjD,OAAO,EAKL,KAAK,WAAW,EAEjB,MAAM,qCAAqC,CAAC;AAE7C,2EAA2E;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,0FAA0F;AAC1F,YAAY,EAAE,QAAQ,EAAE,CAAC;AASzB,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B;;mFAE+E;IAC/E,OAAO,EAAE,CACP,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,EAC5C,UAAU,CAAC,EAAE,MAAM,KAChB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,kBAAkB,CAAC;IACvE,iCAAiC;IACjC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC;IACnF,iDAAiD;IACjD,WAAW,EAAE,MAAM,iBAAiB,CAAC;IACrC,kBAAkB;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,cAAc;IAEjD;;;;;;OAMG;IACG,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAyFtE;;;OAGG;IACH,OAAO,CAAC,cAAc;IAoDtB;;;;;;;;OAQG;YACW,kBAAkB;CAyCjC"}

package/dist/agent/toolRunner.js

@@ -2,16 +2,18 @@
  * 工具执行器（ToolRunner）— 从 AgentLoop 抽出的「单工具执行」独立单元
  *
  * 承载一个工具的完整生命周期：执行前检查（三重闸门）→ 并发/中断竞争执行 → 异常转结构化错误串。
- * 状态独立（不触碰 loop 工作记忆 / 指标 / 自主步标志），输入工具调用元素、输出结果串并触发
- * onToolExecuted，故可独立单测。loop 的 executeToolCalls 只做批量编排，逐工具委托本执行器。
+ * 状态独立（不触碰 loop 工作记忆 / 指标 / 自主步标志），输入工具调用元素、输出结构化
+ * ToolOutcome（status 为判据面真源）并触发 onToolExecuted，故可独立单测。
+ * loop 的 executeToolCalls 只做批量编排，逐工具委托本执行器。
  *
  * 依赖经 deps 注入（execute / preExecutionCheck / onToolExecuted / getStrategy / tracer），
  * 其中 getStrategy 每次执行读最新策略——setStrategy 的动态更新在此依然生效。
  */
 import { TRACE_SPANS } from '../agent/tracer.js';
-import { MemoraError } from '../utils/errors.js';
+import { MemoraError, ToolErrorCode } from '../utils/errors.js';
 import { toError } from '../utils/toError.js';
 import { logger } from '../logging/logger.js';
+import { failedOutcome, failedOutcomeWithCode, okOutcome, blockedOutcome, } from '../agent/managers/toolCallHelpers.js';
 /**
  * 工具执行器：单工具执行单元（异常捕获转结构化错误串回传 LLM，不中断对话）。
  */
@@ -24,7 +26,8 @@ export class ToolRunner {
      * 执行单个工具（并行独立执行单元，无共享状态，可安全并发）。
      * @param tc 工具调用元素
      * @param signal 中止信号（与工具执行 race，signal 先 abort 返回 ABORTED 错误串）
-     * @returns 执行结果串（成功文本或 [ERR:TOOL:code] 错误串）
+     * @returns 结构化结果（`status` 为判据面唯一真源，`text` 为渲染面——B4 判据切换后
+     *   编排层全部决策读 `status`，文本只喂 LLM / 渲染，不再参与成败判定）
      */
     async runOne(tc, signal) {
         // 工具执行 Span（并发时多个 span 时间重叠，tracer 可观测并发度）
@@ -38,21 +41,33 @@ export class ToolRunner {
             const decision = this.applyPrechecks(tc);
             if (decision.kind === 'denied') {
                 span.setAttribute('denied', true);
-                return decision.result;
+                // denied = 主动挡下（只读拒绝 / 宿主审批拒绝）⇒ blocked，原因随该闸门事实带出
+                return blockedOutcome(decision.reason, decision.result);
             }
             if (decision.kind === 'skip') {
                 span.setAttribute('skipped', true);
-                return decision.result;
+                // skip = outbox 幂等跳过（主动挡下）⇒ blocked（idempotent_skip）
+                return blockedOutcome(decision.reason, decision.result);
             }
+            // 每调用独立的原生 outcome 捕获器：执行器在返回字符串的同点按事实产出。
+            let nativeOutcome;
             // raceToolWithSignal 兼容 signal 中断（每个调用独立 race，监听器无并发副作用）
-            const result = await this.raceToolWithSignal(tc.function.name, decision.args, signal);
-            // 通知上层工具执行完成（供 outbox 幂等模式记录是否已执行）
-            const ok = !result.startsWith('[ERR');
-            this.deps.onToolExecuted?.(tc.function.name, decision.args, result, ok);
+            const result = await this.raceToolWithSignal(tc.function.name, decision.args, signal, (native) => {
+                nativeOutcome = native;
+            }, 
+            // 工具调用唯一 ID 透传：web_search 执行时随证据一并留痕，供宿主唯一配对渲染
+            tc.id);
+            // SCRIPT-2 B5 后无文本判据：失败事实一律由执行器在同点显式 emit（结构化产出，
+            // status 与 text 同源）；未 emit = 工具正常完成（裸文本含软降级说明与成功输出），
+            // runOne 统一兜底 ok——兜底不再扫文本前缀。
+            const outcome = nativeOutcome ?? okOutcome(result);
+            // 通知上层工具执行完成（供 outbox 幂等模式记录是否已执行）；
+            // ok 判据单点 = outcome.status（与文本派生/native 产出同源，无第二次独立判断）
+            this.deps.onToolExecuted?.(tc.function.name, decision.args, outcome.text, outcome.status === 'ok');
             // 记录工具执行结果摘要到 Span（可观测性增强：宿主可追踪每次工具调用的结果）
-            span.setAttribute('result', result.slice(0, 200));
-            span.setAttribute('ok', ok);
-            return result;
+            span.setAttribute('result', outcome.text.slice(0, 200));
+            span.setAttribute('ok', outcome.status === 'ok');
+            return outcome;
         }
         catch (err) {
             // 捕获异常转为结构化错误串回传 LLM 自行调整策略，避免传播中断对话
@@ -64,17 +79,21 @@ export class ToolRunner {
                 // 若建议只在 `error.format()` 给宿主 UI、LLM 只收 title+detail——首击失败后
                 // LLM 收不到「使用 list_dir 查看目录结构」这类确切指令，只能凭证据自己悟（多绕一次）。
                 // 证据（siblingDirHint 清单）在 detail 内，本拼接补上命令式建议，双管齐下。
-                const result = `[ERR:TOOL:${code}] 错误：${err.title}${err.detail ? ` — ${err.detail}` : ''}` +
-                    (err.suggestions.length > 0 ? ` 建议：${err.suggestions.join('；')}` : '');
+                // 错误码与文本前缀经 failedOutcomeWithCode **同源产出一次**：
+                // 此前 `code` 算了却只拼进文本、结构化面被丢弃 ⇒ 重试分类（isRetryableToolError）
+                // 只能回头解析前缀，正是 ToolOutcome 自述文档痛批的「判据与渲染耦合」反模式。
+                const failed = failedOutcomeWithCode(code, `错误：${err.title}${err.detail ? ` — ${err.detail}` : ''}` +
+                    (err.suggestions.length > 0 ? ` 建议：${err.suggestions.join('；')}` : ''));
                 logger.warn({ tool: tc.function.name, errorCode: code, title: err.title }, '工具执行失败，错误已回传给 LLM');
-                this.deps.onToolExecuted?.(tc.function.name, tc.function.arguments, result, false);
-                return result;
+                this.deps.onToolExecuted?.(tc.function.name, tc.function.arguments, failed.text, false);
+                return failed;
             }
             else {
-                const result = `[ERR:TOOL:UNKNOWN] 错误：工具执行异常 — ${e.message}`;
+                // 非 MemoraError 归入 UNKNOWN；同样经带码构造器产出，前缀不手抄
+                const failed = failedOutcomeWithCode('UNKNOWN', `错误：工具执行异常 — ${e.message}`);
                 logger.error({ tool: tc.function.name, err }, '工具执行异常');
-                this.deps.onToolExecuted?.(tc.function.name, tc.function.arguments, result, false);
-                return result;
+                this.deps.onToolExecuted?.(tc.function.name, tc.function.arguments, failed.text, false);
+                return failed;
             }
         }
         finally {
@@ -94,9 +113,12 @@ export class ToolRunner {
             const toolDef = this.deps.builtinTools?.find((t) => t.name === name);
             if (toolDef && !toolDef.readonly) {
                 logger.warn({ tool: name }, '工具只读模式：阻止写入工具执行');
+                // 只读拦截前缀 [ERR:TOOL:READONLY_DENIED] 是独立登记标签（非 ToolErrorCode 枚举成员，
+                // 见 toolFailurePrefixGuard TOOL_RESULT_TAGS）；denied 通道机器维度用 reason（readonly_denied）。
                 return {
                     kind: 'denied',
                     result: `[ERR:TOOL:READONLY_DENIED] 工具 "${name}" 是写入操作，在只读模式下不可用`,
+                    reason: 'readonly_denied',
                 };
             }
         }
@@ -105,13 +127,23 @@ export class ToolRunner {
         if (preCheck?.denied) {
             const reason = preCheck.reason ?? '工具调用被拒绝';
             logger.warn({ tool: name, reason }, '工具调用被拒绝（执行前检查）');
-            // PERMISSION_DENIED 不可重试，LLM 见后会调整策略而非重试
-            return { kind: 'denied', result: `[ERR:TOOL:PERMISSION_DENIED] ${reason}` };
+            // 前缀经 failedOutcomeWithCode 由错误码派生（SSOT 单源出口），与 builtinToolHandlers 同口径；
+            // PERMISSION_DENIED 不可重试，LLM 见后会调整策略而非重试。denied 通道机器维度仍用 reason。
+            return {
+                kind: 'denied',
+                result: failedOutcomeWithCode(ToolErrorCode.PERMISSION_DENIED, reason).text,
+                reason: 'permission_denied',
+            };
         }
         if (preCheck?.skip) {
             const result = preCheck.previousResult ?? '[SKIP:TOOL:IDEMPOTENT] 工具已执行（outbox 模式跳过）';
             logger.debug({ tool: name, argsSignature: args.slice(0, 80) }, '工具已执行，跳过（仅一次语义）');
-            return { kind: 'skip', result };
+            return {
+                kind: 'skip',
+                result,
+                // outbox 幂等跳过：idempotent_skip
+                reason: 'idempotent_skip',
+            };
         }
         // 放行：有改写参数则用改写后的执行（审计/参数改写）
         return { kind: 'execute', args: preCheck?.overrideArgs ?? args };
@@ -120,25 +152,38 @@ export class ToolRunner {
      * 工具执行与 signal abort 竞争包裹。toolExecutor 签名不接受 signal，无法真正中断；
      * 用 Promise.race 竞争，signal 先 abort 则返回 [ERR:TOOL:ABORTED]（而非抛 AbortError，
      * 避免破坏"工具失败回传 LLM"契约；ABORTED 不入错误码体系，不触发 Reflection）
+     *
+     * @param emitOutcome 原生 outcome 回调（透传给 execute；abort 出口也经它显式 emit failed，
+     *   保证 runOne 兜底（nativeOutcome ?? ok）读到中断事实而非误判 ok）
+     * @param toolCallId 工具调用唯一 ID（透传给 execute，web_search 证据配对通道）
      */
-    async raceToolWithSignal(name, args, signal) {
+    async raceToolWithSignal(name, args, signal, emitOutcome, toolCallId) {
         const { execute } = this.deps;
         // 无 signal 时直接执行工具（保持原行为，测试场景常用）
         if (!signal) {
-            return execute(name, args);
+            return execute(name, args, emitOutcome, toolCallId);
         }
         // signal 已 abort：直接返回中断错误，不发起工具调用
         if (signal.aborted) {
-            return '[ERR:TOOL:ABORTED] 错误：工具执行被中断';
+            const abortedText = '[ERR:TOOL:ABORTED] 错误：工具执行被中断';
+            // 中断 = 失败事实（执行被夺走），显式 emit 防兜底误判 ok
+            emitOutcome(failedOutcome(abortedText));
+            return abortedText;
         }
         // abort 监听 Promise（signal abort 时 resolve 错误串）；onAbort 提外层便于 race 后清理
         let onAbort = null;
         const abortPromise = new Promise((resolve) => {
-            onAbort = () => resolve('[ERR:TOOL:ABORTED] 错误：工具执行被中断');
+            onAbort = () => {
+                const abortedText = '[ERR:TOOL:ABORTED] 错误：工具执行被中断';
+                // 中断胜出 = 失败事实（execute 仍在后台跑但结果丢弃），显式 emit 防兜底误判 ok
+                emitOutcome(failedOutcome(abortedText));
+                resolve(abortedText);
+            };
             signal.addEventListener('abort', onAbort, { once: true });
         });
-        // race 结束清理监听器，避免并发工具调用累积残留监听器（{ once: true } 不保证未触发时被移除）
-        return Promise.race([execute(name, args), abortPromise]).finally(() => {
+        // race 结束清理监听器，避免并发工具调用累积残留监听器（{ once: true } 不保证未触发时被移除）。
+        // ⚠️ 注意：execute 胜出时已完成（含可能的 emitOutcome）；abort 胜出时执行仍在后台跑但结果丢弃。
+        return Promise.race([execute(name, args, emitOutcome, toolCallId), abortPromise]).finally(() => {
             if (onAbort)
                 signal.removeEventListener('abort', onAbort);
         });

package/dist/agent/toolRunner.js.map

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

package/dist/agent/tracer.d.ts

@@ -90,7 +90,11 @@ export interface AgentMetrics {
     tools: {
         /** 工具调用总次数 */
         callCount: number;
-        /** 失败次数（结果以 [ERR 开头） */
+        /**
+         * 失败次数（判据 = `ToolOutcome.status === 'failed'`，SCRIPT-2 B4 判据切换）。
+         * **口径变更（Breaking）**：执行层闸门（宿主审批拒绝 / 只读拒绝 / 幂等跳过）归
+         * `blocked`、不再计入本值 ⇒ 数字较双轨期下降且历史不可比；主动挡下看 `toolBlockedCount`。
+         */
         failureCount: number;
         /**
          * 未解析工具意图数（文本骨架 <tool_call>/<function=> 但无常原生 toolCalls）。
@@ -107,6 +111,14 @@ export interface AgentMetrics {
         /** read_dedup 护栏硬拦命中（同主体重复获取且结果仍在上下文）次数。
          *  与 ledgerStubEchoCount 互补：本计数 = L2 精确判重（模型乒乓信号，撞墙升级文案的量化基线）。 */
         readDedupBlockCount: number;
+        /**
+         * 主动挡下总数（SCRIPT-2）：loop 护栏 + 旁路拒绝 + 台账替身 + 执行层闸门
+         * （宿主审批拒绝 / 只读拒绝 / 幂等跳过）。B4 起本计数从 `failureCount` 剥离
+         * 独立承载「主动挡下」语义 ⇒ `failureCount` 下降且历史不可比（CHANGELOG 登记）。
+         */
+        toolBlockedCount: number;
+        /** 挡下中藏真失败的次数（`read_failed` 子集；独立于 failureCount） */
+        toolBlockedWithFailureCount: number;
     };
     /** 上下文管理指标 */
     context: {

package/dist/agent/tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/agent/tracer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAIzE,iBAAiB;AACjB,KAAK,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAIpD,mBAAmB;AACnB,MAAM,WAAW,KAAK;IACpB,yBAAyB;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC3D,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,4BAA4B;IAC5B,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrC;AAID,8BAA8B;AAC9B,MAAM,WAAW,OAAO;IACtB,+DAA+D;IAC/D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,KAAK,CAAC;CACjF;AA4BD,oCAAoC;AACpC,eAAO,MAAM,WAAW,EAAE,OAA0B,CAAC;AAIrD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW;IACtB,iBAAiB;;IAEjB,WAAW;;IAEX,aAAa;;IAEb,wEAAwE;;IAExE,4EAA4E;;IAE5E,sDAAsD;;IAEtD,uDAAuD;;CAE/C,CAAC;AAIX;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe;IACf,GAAG,EAAE;QACH,sCAAsC;QACtC,SAAS,EAAE,MAAM,CAAC;QAClB,oCAAoC;QACpC,gBAAgB,EAAE,MAAM,CAAC;QACzB,oCAAoC;QACpC,iBAAiB,EAAE,MAAM,CAAC;QAC1B,6DAA6D;QAC7D,iBAAiB,EAAE,MAAM,CAAC;QAC1B,6DAA6D;QAC7D,kBAAkB,EAAE,MAAM,CAAC;QAC3B;;;WAGG;QACH,kBAAkB,EAAE,MAAM,CAAC;QAC3B;;;;;WAKG;QACH,uBAAuB,EAAE,MAAM,CAAC;QAChC;;;;;WAKG;QACH,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,aAAa;IACb,KAAK,EAAE;QACL,cAAc;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,wBAAwB;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB;;;WAGG;QACH,uBAAuB,EAAE,MAAM,CAAC;QAChC;;;;;WAKG;QACH,mBAAmB,EAAE,MAAM,CAAC;QAC5B;0EACkE;QAClE,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,cAAc;IACd,OAAO,EAAE;QACP,gDAAgD;QAChD,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,mCAAmC;QACnC,eAAe,EAAE,MAAM,CAAC;QACxB,mDAAmD;QACnD,MAAM,CAAC,EAAE,aAAa,CAAC;QACvB,0CAA0C;QAC1C,SAAS,CAAC,EAAE,gBAAgB,CAAC;QAC7B;;;;WAIG;QACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,gCAAgC;IAChC,KAAK,EAAE;QACL,uCAAuC;QACvC,UAAU,EAAE,MAAM,CAAC;QACnB,+BAA+B;QAC/B,YAAY,EAAE,MAAM,CAAC;QACrB,2BAA2B;QAC3B,YAAY,EAAE,MAAM,CAAC;QACrB,qCAAqC;QACrC,WAAW,EAAE,MAAM,CAAC;QACpB,0BAA0B;QAC1B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,yDAAyD;IACzD,IAAI,EAAE;QACJ,mDAAmD;QACnD,mBAAmB,EAAE,MAAM,CAAC;QAC5B,0DAA0D;QAC1D,qBAAqB,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH"}
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/agent/tracer.ts"],"names":[],"mappings":"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"}

package/dist/agent/types.d.ts

@@ -43,9 +43,10 @@ export type AgentChunk = ({
     ok: boolean;
     summary?: string;
     /**
-     * 策略拦截标记：工具被内核确定性拒绝（如 web_search 达硬上限），
-     * 未实际执行。ok=false + blocked=true：区别于「执行失败」，UI 显示「已拦截」，
-     * 不计成功数亦不计失败数；LLM 收到的是拒绝文案而非真实结果。
+     * 主动挡下标记（B4 口径）：工具被**我们**拦下未实际执行——loop 护栏（搜索上限等）、
+     * 执行层闸门（宿主审批拒绝 / 只读拒绝 / 幂等跳过）、旁路拒绝均归此。
+     * ok=false + blocked=true：区别于「执行失败」，UI 显示「已拦截」，不计成功数亦不计失败数；
+     * LLM 收到的是拒绝文案而非真实结果。
      */
     blocked?: boolean;
 }
@@ -128,7 +129,12 @@ export type AgentChunk = ({
     maxRetries: number;
     delayMs: number;
     error: string;
-} | {
+}
+/** 挂起（step 边界暂停 / ask_user 提问挂起共用）。
+ *  来源与原因**不由此事件承载**——唯一真源是 SessionStateMachine 的 pendingPause：
+ *  提问挂起同样经 assembler 的 onPendingQuestion → requestPause(reason, 'agent') 注册，
+ *  与用户暂停同一入口、同一套判据。事件带来源会造出第二个真源（并列即漂移）。 */
+ | {
     type: 'paused';
 }
 /**
@@ -173,6 +179,29 @@ export type AgentChunk = ({
  */
  | {
     type: 'step_boundary';
+}
+/**
+ * 任务表收尾快照：turn 收尾清空运行时任务表（clearPlanOnTurnEnd）**之前**拍的全量终态。
+ * 宿主桥接为 ProcessEvent `plan_snapshot` 落盘（重放恢复任务项完成态的唯一真源）；
+ * 中断轮同样经过收尾兜底产出；暂停/ask 挂起轮 pauseMeta guard 保留 plan → 不拍。
+ */
+ | {
+    type: 'plan_snapshot';
+    items: {
+        planItemId: string;
+        status: PlanItem['status'];
+    }[];
+}
+/**
+ * 后台任务收尾报告：turn 终态对存活后台进程**脱管**（不杀，跨轮存活）后 emit
+ * （定案锚：ADR-036；无存活进程则不产，纯问答常态零块）。
+ * 与 `plan_snapshot` 同型（turn 收尾瞬态信号）：宿主上屏收尾条并桥接为 ProcessEvent 落盘
+ * （重放可见）；中断硬关闭（generator.return()）路径下 yield 被丢弃不上屏，但 LLM 历史
+ * 的 system 消息已由内核写入（脱管报告双通道：chunk 上屏 + system 消息进史，不双写渲染）。
+ */
+ | {
+    type: 'background_report';
+    content: string;
 } | {
     type: 'done';
 }) & RoundTagged;
@@ -237,13 +266,13 @@ export interface UIMessages {
     emptyResponseFallbackTruncated?: (attempts: number) => string;
 }
 /**
- * 归档模式二态：'full'（默认，content 在会话切换前自动归档）/'manual'（全部手动触发，
- * postProcess 跳过所有自动归档分支）。
+ * 归档模式二态：'full'（默认，content 在会话切走/分叉离场/暂停超时时自动归档）/'manual'
+ * （全部手动触发，自动触发传 autoTriggered 时被跳过）。
  */
 export type ArchiveMode = 'full' | 'manual';
 /** 会话状态（三态状态机） */
 export type SessionStatus = 'running' | 'paused' | 'error';
-/** 计划中单个任务项，用于目标漂移检测（文本相似度）和进度追踪 */
+/** 计划中单个任务项，用于任务表进度追踪（task_table 工具读写、暂停检查点随内存携带） */
 export interface PlanItem {
     /** 任务项唯一标识 */
     id: string;
@@ -338,15 +367,6 @@ export interface SessionCheckpoint {
         /** 是否已恢复（ERROR→RUNNING 前须为 true） */
         recovered: boolean;
     };
-    /** 原始目标（防漂移锚点，不随迭代改变） */
-    mainGoal: string;
-    /** 当前迭代目标（可随 plan 推进更新） */
-    currentGoal: string;
-    /**
-     * 目标变更事件序号（每次 currentGoal 变更递增，goalDriftDetected 事件载荷）。
-     * 仅作事件序号，不承担版本一致性校验——漂移碰撞由文本相似度完成，勿误用为版本校验。
-     */
-    goalChangeSeq: number;
     /** 执行计划任务项列表 */
     plan: PlanItem[];
     /**
@@ -409,11 +429,6 @@ import type { IProjectSearchProvider } from '../project-search/types.js';
 import type { ProviderRouter } from '../llm/types.js';
 import type { BehaviorStrategy } from '../role-pack/types.js';
 import type { RolePackTeam } from '../role-pack/types.js';
-/**
- * 文件层前置条件断言回调：注入时 deleteRule/deleteSkill/updateRule 入口先校验宿主是否已完成
- * 文件操作。expected='absent'/'exists' 分别校验已删/已写。id 格式 `rule:NAME` 或 `skill:NAME`。
- */
-export type FileConsistencyCheck = (id: string, expected: 'exists' | 'absent') => boolean;
 /**
  * 工具执行前检查的三态结果（所有工具调用统一入口，由 preExecutionCheck 做执行前检查）：
  * - 放行（skip=false）：允许执行，可选 overrideArgs 改写参数（审计/参数改写）
@@ -469,6 +484,35 @@ export interface DuplicateCheckContext {
     /** 当前阈值（默认 3） */
     readonly threshold: number;
 }
+/**
+ * 宿主环境事实快照（命令执行能力方案 §10.4-②，IEnvironmentProvider 的上报载荷）
+ *
+ * 全字段可选：宿主只上报它知道的事实，未探测/未知的字段省略，内核不补猜。
+ * 内核对快照**零解释转发**（仅格式化为 system prompt 段落）——环境事实不得
+ * 升级为内核判据（命令执行能力方案 §10.5 刻意不做：内核内置探测 = 派生判定律违规）。
+ */
+export interface HostEnvironmentInfo {
+    /** 操作系统描述（如 "win32 10.0.22631"；宿主自行决定详细程度） */
+    os?: string;
+    /** 默认 shell（如 "PowerShell"、"/bin/zsh"；供模型避免跨平台命令误用） */
+    shell?: string;
+    /**
+     * 可用运行时清单（每项一行，如 "node v22.10.0"、"python 3.12.1"）：
+     * 宿主探测结果（探测失败/不存在的运行时不上报），模型据此决定用什么语言写脚本。
+     */
+    runtimes?: string[];
+}
+/**
+ * 宿主环境提供者接口：宿主实现并注入 AgentOptions.environmentProvider。
+ *
+ * getEnvironment 为**同步**返回快照——探测节奏（异步 spawn / 启动期缓存）由宿主自理，
+ * 内核装配与前缀刷新路径同步读取，零等待、零解释。
+ * 返回 null / undefined = 本轮无环境信息（system prompt 不注入该段，非错误）。
+ */
+export interface IEnvironmentProvider {
+    /** 返回环境事实快照；null = 无环境信息（不注入 prompt 段） */
+    getEnvironment(): HostEnvironmentInfo | null;
+}
 /** Agent 构造选项 */
 export interface AgentOptions {
     /** 项目路径（必须） */
@@ -506,13 +550,7 @@ export interface AgentOptions {
      * 是宿主的产品决策，内核不置喙，也不假设其下的文件形态。
      */
     dataDir: string;
-    /**
-     * 项目注册表目录（可选，缺省随 dataDir）。注册表存在的意义是**跨项目按名解析**，
-     * 故只有多项目共用同一 dataDir（或显式指定共同的 registryDir）时才真正兑现；
-     * 若 dataDir 是项目级目录，注册表随之落进各项目内、只含项目自身条目，按名切换不成立。
-     */
-    registryDir?: string;
-    /** 最大上下文 token 数（默认 120000） */
+    /** 最大上下文 token 数（缺省 = AGENT_CONSTANTS.DEFAULT_MAX_CONTEXT_TOKENS，数字以该常量为真源、不在此落账） */
     maxContextTokens?: number;
     /**
      * per-LLM 输出预算默认值（token，可选）：宿主 per-LLM 配置（配置面板「输出上限」）透传，
@@ -557,6 +595,14 @@ export interface AgentOptions {
     codeExecutionProvider?: ICodeExecutionProvider;
     /** 项目搜索提供者（可选，不配则不启用 search_project；等价 IDE 全局搜索，由宿主实现） */
     projectSearchProvider?: IProjectSearchProvider;
+    /**
+     * 宿主环境提供者（可选，不配则 system prompt 不注入环境段）：宿主上报运行环境事实
+     * （OS / shell / 可用运行时），内核经 buildEnvironmentContextBlock 注入 system prompt。
+     * 命令执行能力方案 §10.4-②：探测环境 → 把事实告诉模型 → 由模型自己决定（对齐 Cline System
+     * Information 支柱与 Claude Code 每轮环境注入）。内核不裁决平台差异——环境事实
+     * 只有宿主知道，内核零解释转发（宿主内部事实不得提升为内核判据，命令执行能力方案 §10.5）。
+     */
+    environmentProvider?: IEnvironmentProvider;
     /**
      * node 可执行文件路径（可选）：宿主注入真实 node 路径
      * （如 IDE 内置 node / 用户配置的 node）给 L3 脚本执行器（run_skill_script /
@@ -571,8 +617,6 @@ export interface AgentOptions {
      * 缺省空 = 全量技能可用（向后兼容）。
      */
     disabledSkills?: string[];
-    /** 文件层前置条件断言回调（可选，未注入则完全降级为现状） */
-    fileConsistencyCheck?: FileConsistencyCheck;
     /**
      * 工具执行前检查回调（宿主审批/审计/参数改写通道）：装配时与内部幂等检查组合为单点入口。
      *