@zooique/memora 3.0.1 → 5.0.0

package/dist/agent/toolExecutor.js

@@ -1,13 +1,17 @@
+import { requireConfirmingEntry } from '../security/confirmEntries.js';
 import { toolError, configError, MemoraError, ToolErrorCode } from '../utils/errors.js';
 import { toError } from '../utils/toError.js';
 import { logger } from '../logging/logger.js';
 import { truncate } from '../utils/strings.js';
-import { ALL_BUILTIN_TOOL_DEFS, BUILTIN_TOOLS, WEB_SEARCH_TOOL, WEB_FETCH_TOOL, WEB_FETCH_CONTENT_MAX_LEN, WEB_FETCH_CONTENT_DEFAULT_LEN, RUN_CODE_TOOL, SEARCH_PROJECT_TOOL, } from '../agent/builtinTools.js';
+import { ALL_BUILTIN_TOOL_DEFS, BUILTIN_TOOLS, WEB_SEARCH_TOOL, WEB_FETCH_TOOL, WEB_FETCH_CONTENT_MAX_LEN, WEB_FETCH_CONTENT_DEFAULT_LEN, RUN_CODE_TOOL, buildRunCodeTool, SEARCH_PROJECT_TOOL, } from '../agent/builtinTools.js';
+import { sanitizeExternalText, stripControlChars } from '../agent/textSanitize.js';
+import { okOutcome, failedOutcome, failedOutcomeWithCode, blockedOutcome, } from '../agent/managers/toolCallHelpers.js';
 import { BuiltinToolHandlers } from '../agent/builtinToolHandlers.js';
 import { safeSearch } from '../web-search/webSearchProvider.js';
 import { safeFetch } from '../web-fetch/webFetchProvider.js';
+import { isLoginWallPage } from '../web-fetch/loginWall.js';
 import { safeExecuteCode } from '../code-exec/codeExecutionProvider.js';
-import { formatExecutionResult, formatScriptResult, runSkillScript, } from '../skill/skillScriptRunner.js';
+import { formatExecutionResult, formatScriptResult, formatCommandResult, formatKilledCommandOutput, resolveCommandTimeoutMs, runShellCommand, runSkillScript, } from '../skill/skillScriptRunner.js';
 import { resolveSafePath, inferRuntimeFromExt } from '../utils/scanner.js';
 import { safeSearchProjectFiles, safeSearchProjectText, } from '../project-search/projectSearchProvider.js';
 import { buildSearchTerms } from '../project-search/terms.js';
@@ -17,6 +21,13 @@ export { BUILTIN_TOOLS, BUILTIN_TOOL_IDEMPOTENCY } from '../agent/builtinTools.j
 const WEB_SEARCH_QUERY_MAX_LEN = 200;
 /** web_search 单条结果字段最大长度（防长上下文注入） */
 const WEB_SEARCH_RESULT_MAX_LEN = 500;
+/**
+ * web_search 观测留痕的最大标题条数（证据面小帽）
+ *
+ * 留痕目的是归因取样（「搜到了什么」），不是全量镜像——全量计数由 count 承载，
+ * 标题只留前 N 条样本。与结果字段上限同族：证据落盘体积有界。
+ */
+const WEB_SEARCH_EVIDENCE_MAX_TITLES = 5;
 // ─── web_fetch / run_code 注入防御常量 ─────────────────
 /** web_fetch 的 url 最大长度（防超长/恶意 URL 滥用） */
 const WEB_FETCH_URL_MAX_LEN = 2000;
@@ -44,9 +55,33 @@ function normalizeScriptRuntime(language) {
         return 'shell';
     return 'node';
 }
-// ─── run_skill_script 注入防御常量 ─────────────────
-/** run_skill_script 单次结果最大长度（防脚本刷屏撑爆上下文；对齐 run_code 的 RUN_CODE_RESULT_MAX_LEN） */
+// ─── run_skill_script / run_command 注入防御常量 ─────────────────
+/**
+ * 脚本 / 命令单次结果最大长度（防刷屏撑爆上下文；对齐 run_code 的 RUN_CODE_RESULT_MAX_LEN）
+ *
+ * ⚠️ 这是**上下文层**的字符上限，与收集侧的**内存护栏**不是一回事：
+ * `skillScriptRunner.MAX_COLLECTED_OUTPUT_BYTES`（字节量纲，防 Node 进程内存膨胀）。
+ * 两者量纲不同（字符 / 字节 / token 三层各司其职），**禁止互相对齐或合并**——
+ * 合并会让「内存护栏」退化成「上下文截断」，或让后者在 CJK 下实际越界。
+ */
 const RUN_SCRIPT_RESULT_MAX_LEN = 20_000;
+/**
+ * run_command 单条命令最大长度（防超长命令滥用）
+ *
+ * 对齐 `RUN_CODE_CODE_MAX_LEN`（50_000）的注入防御口径：LLM 可能吐出整份文件内容当命令传，
+ * 而命令原文会**四处扩散**——裁决链正则、确认卡 UI 展示、审计事件、turn 终态脱管报告
+ * （脱管报告把每条命令原文写进 system 消息）。不限长 = 一个超长命令污染整条链路。
+ */
+const RUN_COMMAND_MAX_LEN = 50_000;
+/**
+ * 脚本 / 代码长输出的**尾部保留**字符数（缺口 D）
+ *
+ * 只服务「关键信息常在尾部」的长输出（构建失败原因、堆栈末尾、FAIL 汇总行）。
+ * 网页正文 / 技能文档 / 资源文件等**头部即要点**的内容**不传**此参数（默认 0，
+ * 保持纯头截断——尾部对它们是页脚噪声）。
+ * 是否保留尾部由**调用点显式声明**，不在函数内按内容猜测（猜测 = 隐式分支 + 不可预测）。
+ */
+const SCRIPT_RESULT_TAIL_CHARS = 4_000;
 // ─── search_project 注入防御常量 ─────────────────
 /** search_project 的 query 最大长度（防超长 glob/关键词滥用） */
 const PROJECT_SEARCH_QUERY_MAX_LEN = 500;
@@ -188,36 +223,15 @@ const SKILL_CONTENT_MAX_LEN = 50_000;
 /** read_resource 资源正文单次返回最大长度（防超长资源注入上下文；与 read_skill 同标准） */
 const RESOURCE_CONTENT_MAX_LEN = 50_000;
 /**
- * 去 ANSI 转义序列与不可打印控制字符（**不限长**）
+ * 外部文本净化（转发 re-export，保持既有 import 面不破）
  *
- * 净化规则的单一真理源。外部不可信内容（web_search / 子进程输出 / 文件正文）注入 LLM 上下文前
- * 须剥掉控制字符，防转义/终端注入。
- *
- * @param text 原始文本
- * @returns 净化后的文本
+ * 实现真源已迁至 `textSanitize.ts`：净化是**跨模块**的最后一道闸（工具返回 / 脚本与资源正文 /
+ * 命令结果三处消费），住在本文件有两个后果——① `builtinToolHandlers` 反向 import 本模块
+ * 形成循环依赖；② 命令结果的定长上限成了本模块的**私有常量**，第二个消费面
+ * （后台完成回流）看不到它 ⇒ 回流路径无长度上限。
+ * 本处只做转发，既有调用点无需改动；新代码直接 import `textSanitize.js`。
  */
-export function stripControlChars(text) {
-    // 去 ANSI 转义序列（CSI：ESC [ 参数 + 终结符；子进程经 env 继承可能拿到
-    // FORCE_COLOR 输出色码，单剥 ESC 会留 `[33m` 残渣——整个序列须剥净）
-    const withoutAnsi = text.replace(/\u001B\[[0-9;?]*[a-zA-Z]/g, '');
-    // 去控制字符：保留可打印字符（含 \t 制表符），其余控制字符移除
-    return withoutAnsi.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '');
-}
-/**
- * 外部工具返回净化：去控制字符 + 长度上限
- *
- * 净化规则本身抽为 `stripControlChars`（**单一真理源**），供需要「净化但不限长」的调用方复用——
- * 例如 `read_file`：它的长度由 **token 预算分段**（`sliceFileByLineBudget`）收口，不走字符上限，
- * 但仍须剥掉 ANSI/控制字符。否则它只能传一个假的上限（如 MAX_SAFE_INTEGER）来迁就本函数签名。
- *
- * @param text 外部原始文本
- * @param maxLen 最大长度
- * @returns 净化后的文本
- */
-export function sanitizeExternalText(text, maxLen) {
-    const cleaned = stripControlChars(text);
-    return cleaned.length > maxLen ? `${cleaned.slice(0, maxLen)}…` : cleaned;
-}
+export { stripControlChars, sanitizeExternalText } from '../agent/textSanitize.js';
 /**
  * 解析 task_table_update 的 plan_item_id 为真实任务项 uuid（唯一解析点）。
  *
@@ -313,6 +327,12 @@ export const DEFAULT_EXPOSED_TOOLS = new Set([
     'list_skills',
     // 项目内既有脚本执行（判据 A+B：仓库已沉淀）；search_project 走宿主注入例外，不在此集
     'run_project_script',
+    // 命令执行（§11.5 拍板：常驻开放 + deny/ask/allow 三层护栏）——
+    // 不做角色包能力门：命令执行是通用脚手架（构建/测试/git 查询），按需声明会让
+    // 「宿主已注入确认闸、内核已恒拦黑名单」的双层防护退化为「角色包没声明就不能用」。
+    // 危险度由裁决链（deny 黑名单恒拦 / alwaysAsk 恒确认 / guest 恒确认）承担，不由暴露面承担。
+    'run_command',
+    'kill_command',
 ]);
 /**
  * 工具执行器
@@ -360,6 +380,14 @@ export class ToolExecutor {
     projectSearchProvider;
     /** node 可执行文件路径（可选）：run_project_script 的 node runtime 分支注入真实 node 路径 */
     scriptNodePath;
+    /**
+     * 后台任务注册表（可选，run_command background=true / kill_command 的唯一数据源）
+     *
+     * 由 agent 装配时注入（实例非单例，多会话互不可见——见 backgroundTasks 模块头注释）。
+     * 未注入时两个工具返回 NOT_AVAILABLE：工具面仍暴露（能力缺失要如实说，不静默假装能跑），
+     * 而非把工具从暴露面摘掉（那会让 LLM 以为自己看错了工具清单）。
+     */
+    backgroundTasks;
     /**
      * 剩余对话预算提供者（可选，预算联动）
      *
@@ -373,6 +401,29 @@ export class ToolExecutor {
     setBudgetProvider(provider) {
         this.budgetProvider = provider;
     }
+    /**
+     * web_search 执行事实观察者（可选，观测留痕）
+     *
+     * 由 agent 装配时注入（loop.recordWebSearchEvidence，「搜不准」归因取证）：
+     * 每次 web_search **实际执行后**（safeSearch 返回即发射，零结果/降级页同样发射——
+     * 「没搜到」与「搜到了但不对」同为归因现场，失败按原样记录 = 诚实镜像 LLM 实际所得）。
+     * 护栏硬拦的搜索不走此路（未执行即无结果面；拦截事实已在 tool 消息可见）。
+     * undefined = 未注入静默跳过（纯 ToolExecutor 单测场景）。
+     */
+    searchResultObserver;
+    /** 注入 web_search 执行事实观察者（装配时由 loop 创建后注入，见 assembler） */
+    setSearchResultObserver(observer) {
+        this.searchResultObserver = observer;
+    }
+    /**
+     * 注入后台任务注册表（装配层接线，run_command background / kill_command 数据源）
+     *
+     * 与 toolExec 构造解耦（注册表在 toolExec 之后创建，见 assembler），故用 setter。
+     * 注入的是**实例**——多会话各自一张任务表，kill_command 够不着别的会话的进程。
+     */
+    setBackgroundTasks(registry) {
+        this.backgroundTasks = registry;
+    }
     /** 任务表管理回调（由 agent 装配时注入，处理 task_table_write/update） */
     planManager;
     /**
@@ -397,6 +448,10 @@ export class ToolExecutor {
      *
      * 渐进披露 L3：执行技能的 scripts/ 目录下的可执行脚本。
      * 脚本源码不进入 LLM 上下文，仅执行结果返回。
+     *
+     * B2-a 契约加宽：返回**结构化执行事实**而非已格式化字符串——格式化与 outcome
+     * 派生都在 ToolExecutor 单点完成（与 run_project_script 同源），
+     * 消除「exitCode/timedOut 在装配边界被压成文本」的事实丢失。
      */
     runSkillScript;
     /**
@@ -469,7 +524,8 @@ export class ToolExecutor {
      * 转发给 builtinHandlers：search_memories 命中记忆时触发，为全库**唯一** memoryRecalled
      * 发射位（无 warmRecall 等其他发射路径）。
      *
-     * @param callback 命中回调（count 命中条数 / query 检索词），缺省注入则工具静默（无宿主 no-op）
+     * @param callback 命中回调（载荷类型 = AgentEventMap['memoryRecalled'] 单一真源：count 命中条数 /
+     *   query 检索词 / hits 命中明细 / toolCallId 本次调用配对键），缺省注入则工具静默（无宿主 no-op）
      */
     setOnMemoryRecalled(callback) {
         this.builtinHandlers.setOnMemoryRecalled(callback);
@@ -484,6 +540,15 @@ export class ToolExecutor {
     setExclusionRoundIdsProvider(provider) {
         this.builtinHandlers.setExclusionRoundIdsProvider(provider);
     }
+    /**
+     * 注入后台任务槽位调度器，转发给 builtinHandlers：search_memories 命中 touch 走实例级限流。
+     * 与 SeedDeps 的调度器同一实例（装配期 wiring），纳入 Agent.close() 单点等待。
+     *
+     * @param scheduler Agent 实例级后台任务调度器
+     */
+    setBackgroundTaskScheduler(scheduler) {
+        this.builtinHandlers.setBackgroundTaskScheduler(scheduler);
+    }
     /**
      * 注册自定义工具
      *
@@ -604,8 +669,10 @@ export class ToolExecutor {
             baseTools = [...baseTools, WEB_SEARCH_TOOL];
         if (this.fetchProvider)
             baseTools = [...baseTools, WEB_FETCH_TOOL];
+        // run_code 定义按宿主执行器声明生成（命令执行能力方案 §10.4-①(b)）：声明 supportedLanguages →
+        // 描述列举「支持：a、b、c」；未声明 → buildRunCodeTool 缺省形态（去承诺文案，不列举）
         if (this.codeExecutionProvider)
-            baseTools = [...baseTools, RUN_CODE_TOOL];
+            baseTools = [...baseTools, buildRunCodeTool(this.codeExecutionProvider.supportedLanguages)];
         // 常驻豁免集无条件暴露（LLM 工具面不因角色包能力声明收窄本地能力）
         const exposed = baseTools.filter((t) => DEFAULT_EXPOSED_TOOLS.has(t.name));
         // 特权工具按白名单过滤（toolWhitelist=null 全暴露；否则只在名单内）
@@ -634,6 +701,24 @@ export class ToolExecutor {
     get builtinDefinitions() {
         return [...ALL_BUILTIN_TOOL_DEFS];
     }
+    /**
+     * 按登记表把执行面路由到对应确认入口（CMD-1-BYPASS 2026-10-03）
+     *
+     * 入口由 `security/confirmEntries.ts` 的 `CONFIRM_ENTRY_BY_TOOL` 唯一指定，
+     * 不在各 case 分支里隐式选方法 ⇒ 新增执行面漏登记会在守卫测试处即红。
+     *
+     * @param entry 确认入口（来自登记表，类型已排除 `none`——非确认面不可能被路由进来）
+     * @param target 确认对象（命令原文 / 脚本路径 / 内联代码标识）
+     * @param tool 工具名
+     * @param description 面向用户的描述
+     * @returns 是否获确认放行
+     */
+    async confirmByEntry(entry, target, tool, description) {
+        if (entry === 'command') {
+            return this.security.confirmCommandRun(target, tool, description);
+        }
+        return this.security.confirmScriptRun(target, tool, description);
+    }
     /**
      * 执行工具调用
      *
@@ -645,9 +730,15 @@ export class ToolExecutor {
      * @param name 工具名称
      * @param argsJson 参数 JSON 字符串
      * @param extensions 写入扩展（可选，用于 diff 确认等）
-     * @returns 工具结果的字符串描述
+     * @param emitOutcome 原生结构化结果回调（可选 · SCRIPT-2 outcome 通道）：
+     *   已切族工具在**返回字符串的同点**按执行事实产出 `ToolOutcome`（status 不读文本前缀）；
+     *   未切族不调用 ⇒ ToolRunner 回落文本判据。每调用独立回调，无并发相关性问题。
+     * @param toolCallId 本次工具调用的唯一 ID（可选 · 证据配对通道）：web_search 执行时随
+     *   观测留痕一并携带，使宿主渲染能把证据唯一配对回工具行（不再按 query 文本猜）。
+     *   非 web_search 工具忽略此参；缺省 = 证据不带 ID，宿主回退 query 启发式（保不带伤）。
+     * @returns 工具结果的字符串描述（渲染面，逐字保持）
      */
-    async execute(name, argsJson, extensions) {
+    async execute(name, argsJson, extensions, emitOutcome, toolCallId) {
         let args;
         try {
             args = JSON.parse(argsJson);
@@ -681,7 +772,9 @@ export class ToolExecutor {
             case 'list_dir':
                 return this.builtinHandlers.listDir(strArg('path', '.'), strArg('recursive', 'false'), strArg('maxDepth', '2'));
             case 'search_memories':
-                return this.builtinHandlers.searchMemories(strArg('query'), strArg('limit', '10'), strArg('mode', 'match'));
+                // toolCallId 透传给处理器：命中明细随 memoryRecalled 携带配对键，宿主据此挂回工具行
+                // （与 web_search 证据配对同源通道；缺省 undefined 时处理器不带该字段，宿主走兜底落位）。
+                return this.builtinHandlers.searchMemories(strArg('query'), strArg('limit', '10'), strArg('mode', 'match'), toolCallId);
             case 'trace_summary':
                 return this.builtinHandlers.traceSummary(strArg('sessionId'), strArg('roundId') || undefined, strArg('limit', '5'));
             case 'list_sessions':
@@ -690,7 +783,11 @@ export class ToolExecutor {
                 // web_search 由 ToolExecutor 直接处理，不经过 BuiltinToolHandlers（文件系统导向）
                 // 使用注入的 webSearchProvider 执行网络搜索，带超时保护
                 if (!this.webSearchProvider) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] 错误：网络搜索功能未配置，请先注入 IWebSearchProvider';
+                    // 未注入提供方 = 工具能力缺失（执行失败事实，非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', '错误：网络搜索功能未配置，请先注入 IWebSearchProvider');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const query = strArg('query');
                 if (!query) {
@@ -702,12 +799,27 @@ export class ToolExecutor {
                 }
                 const limit = Math.min(Number.parseInt(strArg('limit', '5'), 10) || 5, 20);
                 const results = await safeSearch(this.webSearchProvider, query, { limit });
+                // 搜索来源（降级透出 + 观测留痕同源）：同批次结果来自同一后端，取首条 endpoint
+                const endpoint = results[0]?.endpoint;
+                // 观测留痕（SEARCH-QUALITY-1 P1-1）：执行事实镜像给 loop 落裁决证据轨。
+                // 在空结果分支**之前**发射——零结果（count=0）是「没搜到」的归因现场，不静默跳过；
+                // safeSearch 降级页按原样记录（title 即「网络搜索暂不可用」）= 诚实镜像 LLM 实际所得。
+                // query 与 titles 同净化标准（stripControlChars 剥控制字符——落盘证据面不进原始
+                // 控制字符；长度已由 WEB_SEARCH_QUERY_MAX_LEN 校验管，不重复钳制）
+                this.searchResultObserver?.({
+                    toolCallId,
+                    query: stripControlChars(query),
+                    endpoint,
+                    count: results.length,
+                    titles: results
+                        .slice(0, WEB_SEARCH_EVIDENCE_MAX_TITLES)
+                        .map((r) => sanitizeExternalText(r.title, WEB_SEARCH_RESULT_MAX_LEN)),
+                });
                 if (results.length === 0) {
                     return `（未找到与 "${query}" 相关的搜索结果）`;
                 }
                 // 搜索来源透出：同批次结果来自同一后端，取首条 endpoint 告知用户实际使用的搜索源
                 // （降级到 DuckDuckGo 时即透出「搜索来源：DuckDuckGo」），提升 in-flow 信任；宿主渲染工具结果文本即可见。
-                const endpoint = results[0]?.endpoint;
                 const sourceLine = endpoint ? `（搜索来源：${endpoint}）` : '';
                 // 返回净化：外部内容去控制字符 + 长度上限，防长上下文注入
                 const body = results
@@ -724,7 +836,11 @@ export class ToolExecutor {
                 // web_fetch 由 ToolExecutor 直接处理（与 web_search 同侧，均为外部信息获取）
                 // 使用注入的 fetchProvider 抓取网页正文，带超时保护；失败由 safeFetch 降级
                 if (!this.fetchProvider) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] 错误：网页抓取功能未配置，请先注入 IFetchProvider';
+                    // 未注入提供方 = 工具能力缺失（执行失败事实，非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', '错误：网页抓取功能未配置，请先注入 IFetchProvider');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const url = strArg('url');
                 if (!url) {
@@ -745,6 +861,18 @@ export class ToolExecutor {
                 if (!page.content) {
                     return `（未能从 "${url}" 提取到正文内容）`;
                 }
+                // 登录墙识别（SEARCH-QUALITY-1 P2-1）：HTTP 200 的登录页洗成正文 = 「抓到了一堵墙」，
+                // 明示不可读并引导换源——不把表单碎片当页面内容交付（LLM 会当正文啃）。
+                // 判据是保守启发式（漏判=现状，误判=藏可读页，见 loginWall.ts 文件头）；
+                // finalUrl 取重定向后实际地址 page.url（带登录态参数的原始 URL 常常正是要抓的页面）。
+                // 两条边界排除（落地自审 D-2/D-3）：
+                // · fetchFailed 降级页不判墙——「抓取失败」不得谎报成「可能需登录」（失败语义不改写）；
+                // · contentCap 传 maxChars——截断上限 < 弱信号阈值时「短正文」是截断假象，弱信号禁用。
+                if (!page.fetchFailed &&
+                    isLoginWallPage(page.url || url, page.title, page.content, maxChars)) {
+                    return (`（该页面（${page.url || url}）可能需要登录才能查看，本次只获取到登录表单而非正文。` +
+                        `请改用其他来源，或请用户提供可访问的链接。）`);
+                }
                 // 返回净化：外部内容去控制字符 + 长度上限，防长上下文注入
                 const title = sanitizeExternalText(page.title, 500);
                 const content = sanitizeExternalText(page.content, WEB_FETCH_CONTENT_MAX_LEN);
@@ -758,7 +886,11 @@ export class ToolExecutor {
                 // run_code 由 ToolExecutor 直接处理（通用计算/数据处理/验证底座）
                 // 使用注入的 codeExecutionProvider 执行代码，带超时保护；失败由 safeExecuteCode 降级
                 if (!this.codeExecutionProvider) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] 错误：代码执行功能未配置，请先注入 ICodeExecutionProvider';
+                    // 未注入执行器 = 工具能力缺失（旧口径 [ERR 开头亦判失败），显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', '错误：代码执行功能未配置，请先注入 ICodeExecutionProvider');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const language = strArg('language');
                 const code = strArg('code');
@@ -770,10 +902,11 @@ export class ToolExecutor {
                 // 统一执行入参：脚本源码 / 代码字符串 + 语言 + 工作目录
                 let execCode;
                 let execLanguage;
-                // 临时脚本模式 cwd=项目根（脚本可 require 项目本地依赖、读取项目数据）；code 模式不指定由执行器决定
-                const execOptions = scriptPath
-                    ? { cwd: this.builtinHandlers.projectPath }
-                    : undefined;
+                // cwd 恒=项目根（两模式同源供给，SKILL-CWD-1 审查实锤的 code 模式缺口，2026-10-14 补）：
+                // 此前 code 模式不传 → 执行器 spawn 无 cwd → 子进程继承宿主进程 cwd（VS Code 启动目录，
+                // 不可控）→ 内联代码相对路径写文件可逃出项目根 / 读项目数据 ENOENT。
+                // 四执行面（run_command / run_project_script / run_skill_script / run_code）cwd 判据至此对称。
+                const execOptions = { cwd: this.builtinHandlers.projectPath };
                 if (scriptPath) {
                     // 读取脚本文件原样执行（路径白名单 + 长度上限由 readScriptFile 负责，截断会破坏语法）
                     execCode = await this.builtinHandlers.readScriptFile(scriptPath);
@@ -802,24 +935,35 @@ export class ToolExecutor {
                 }
                 // 执行确认：guest 模式或 confirmScripts 时询问（run_code 由宿主沙箱执行，此处为权限层确认；
                 // owner+confirmScripts=false 自动批准，走审计。code 无落盘路径，target 用描述型标识）
-                const execConfirmed = await this.security.confirmScriptRun(scriptPath ? `run_code:script:${scriptPath}` : 'run_code:inline', 'run_code', scriptPath
+                const execConfirmed = await this.confirmByEntry(requireConfirmingEntry('run_code'), scriptPath ? `run_code:script:${scriptPath}` : 'run_code:inline', 'run_code', scriptPath
                     ? `运行脚本 ${scriptPath}（宿主沙箱）`
                     : `执行内联代码（${execLanguage}，${execCode.length} 字符，宿主沙箱）`);
                 if (!execConfirmed) {
-                    return '[ERR:SCRIPT_DECLINE] 代码执行未获确认（用户拒绝或未注入确认回调，fail-closed）';
+                    // 用户/系统拒绝执行 = 主动挡下（permission_denied），非执行失败
+                    const declineText = '[ERR:SCRIPT_DECLINE] 代码执行未获确认（用户拒绝或未注入确认回调，fail-closed）';
+                    emitOutcome?.(blockedOutcome('permission_denied', declineText));
+                    return declineText;
                 }
                 const result = await safeExecuteCode(this.codeExecutionProvider, execCode, execLanguage, execOptions);
                 // 结果净化：stdout/stderr 当外部内容去控制字符 + 长度上限，防长上下文注入
-                const stdout = sanitizeExternalText(result.stdout, RUN_CODE_RESULT_MAX_LEN);
-                const stderr = sanitizeExternalText(result.stderr, RUN_CODE_RESULT_MAX_LEN);
+                const stdout = sanitizeExternalText(result.stdout, RUN_CODE_RESULT_MAX_LEN, SCRIPT_RESULT_TAIL_CHARS);
+                const stderr = sanitizeExternalText(result.stderr, RUN_CODE_RESULT_MAX_LEN, SCRIPT_RESULT_TAIL_CHARS);
                 // 格式化：与 run_skill_script 共用 formatExecutionResult（同一真理源，改格式契约须两链路同步）
-                return formatExecutionResult({ stdout, stderr, exitCode: result.exitCode, timedOut: result.timedOut }, { kind: 'CODE', timeoutDetail: '代码执行超时', errorDetail: '代码执行失败' });
+                const codeText = formatExecutionResult({ stdout, stderr, exitCode: result.exitCode, timedOut: result.timedOut }, { kind: 'CODE', timeoutDetail: '代码执行超时', errorDetail: '代码执行失败' });
+                // status 直接读执行事实（B2-a：不扫文本前缀）：超时或退出码非 0 = failed，其余 = ok
+                const codeFailed = result.timedOut || result.exitCode !== 0;
+                emitOutcome?.(codeFailed ? failedOutcome(codeText) : okOutcome(codeText));
+                return codeText;
             }
             case 'search_project': {
                 // search_project 由 ToolExecutor 直接处理（与 web_search/run_code 同侧，均为宿主注入能力）
                 // 使用注入的 projectSearchProvider 执行项目内搜索，带超时保护；失败由 safe* 降级
                 if (!this.projectSearchProvider) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] 错误：项目搜索功能未配置，请先注入 IProjectSearchProvider';
+                    // 未注入提供方 = 工具能力缺失（执行失败事实，非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', '错误：项目搜索功能未配置，请先注入 IProjectSearchProvider');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const query = strArg('query');
                 const mode = strArg('mode', 'name');
@@ -834,11 +978,17 @@ export class ToolExecutor {
                     throw toolError('search_project exclude 参数过长', `exclude 超过 ${PROJECT_SEARCH_GLOB_MAX_LEN} 字符上限`, ['缩短 exclude 模式'], undefined, ToolErrorCode.ARGUMENT_ERROR);
                 }
                 if (mode !== 'name' && mode !== 'content') {
-                    return `[ERR:INVALID_ARG] 不支持的搜索模式 "${mode}"，仅支持 name/content`;
+                    // 非法参数 = 执行失败事实（方案明文 INVALID_ARG=failed）→ 显式 emit failed
+                    const invalidModeText = `[ERR:INVALID_ARG] 不支持的搜索模式 "${mode}"，仅支持 name/content`;
+                    emitOutcome?.(failedOutcome(invalidModeText));
+                    return invalidModeText;
                 }
                 if (mode === 'content') {
                     if (!query) {
-                        return '[ERR:INVALID_ARG] content 模式需要 query 内容关键词';
+                        // 非法参数 = 执行失败事实（方案明文 INVALID_ARG=failed）→ 显式 emit failed
+                        const missingQueryText = '[ERR:INVALID_ARG] content 模式需要 query 内容关键词';
+                        emitOutcome?.(failedOutcome(missingQueryText));
+                        return missingQueryText;
                     }
                     // 放宽词表（精确优先 + 零命中回退）：剔除与整串等价的词——否则宿主会做一轮与
                     // 精确轮逐字相同的徒劳扫描，并回报一个名不副实的 relaxed
@@ -872,12 +1022,19 @@ export class ToolExecutor {
             case 'task_table_write': {
                 // 写入任务表（overwrite / append / replace）；items 每项可选 rolePack（会议表层装配角色）
                 if (!this.planManager) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] 任务表功能未就绪';
+                    // 任务表能力未装配 = 执行失败事实（非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', '任务表功能未就绪');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 // mode 为 required（validateAndCoerceArgs 强制校验），不设缺省——设缺省即与 required 契约矛盾
                 const writeMode = strArg('mode');
                 if (writeMode !== 'overwrite' && writeMode !== 'append' && writeMode !== 'replace') {
-                    return `[ERR:INVALID_ARG] 不支持的写入模式 "${writeMode}"，仅支持 overwrite/append/replace`;
+                    // 非法参数 = 执行失败事实（方案明文 INVALID_ARG=failed）→ 显式 emit failed
+                    const invalidModeText = `[ERR:INVALID_ARG] 不支持的写入模式 "${writeMode}"，仅支持 overwrite/append/replace`;
+                    emitOutcome?.(failedOutcome(invalidModeText));
+                    return invalidModeText;
                 }
                 const itemsRaw = args.items;
                 const items = Array.isArray(itemsRaw)
@@ -888,18 +1045,28 @@ export class ToolExecutor {
                     }))
                     : [];
                 if (items.length === 0 || items.some((s) => s.description.trim() === '')) {
-                    return '[ERR:INVALID_ARG] items 参数不能为空，且每项须含非空 description';
+                    // 非法参数 = 执行失败事实（方案明文 INVALID_ARG=failed）→ 显式 emit failed
+                    const invalidItemsText = '[ERR:INVALID_ARG] items 参数不能为空，且每项须含非空 description';
+                    emitOutcome?.(failedOutcome(invalidItemsText));
+                    return invalidItemsText;
                 }
                 return this.planManager.writePlan(writeMode, items);
             }
             case 'task_table_update': {
                 // 更新任务状态
                 if (!this.planManager) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] 任务表功能未就绪';
+                    // 任务表能力未装配 = 执行失败事实（非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', '任务表功能未就绪');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const planItemId = strArg('plan_item_id');
                 if (!planItemId) {
-                    return '[ERR:INVALID_ARG] plan_item_id 不能为空';
+                    // 非法参数 = 执行失败事实（方案明文 INVALID_ARG=failed）→ 显式 emit failed
+                    const missingIdText = '[ERR:INVALID_ARG] plan_item_id 不能为空';
+                    emitOutcome?.(failedOutcome(missingIdText));
+                    return missingIdText;
                 }
                 // 寻址统一解析（见 resolvePlanItemId）：renderer 只向 LLM 展示行首序号（1-based），
                 // task_table_write 返回 uuid 前 8 位短 id，planItemLog 展示完整 uuid——三种来源全部归一为真实 uuid 后
@@ -907,12 +1074,17 @@ export class ToolExecutor {
                 const plan = this.planManager.getPlan?.() ?? [];
                 const resolved = resolvePlanItemId(planItemId, plan);
                 if (!resolved.ok) {
+                    // 寻址失败（PLAN_ITEM_NOT_FOUND）= 执行失败事实 → 显式 emit failed
+                    emitOutcome?.(failedOutcome(resolved.error));
                     return resolved.error;
                 }
                 // status 为 required（validateAndCoerceArgs 强制校验），不设缺省
                 const planItemStatus = strArg('status');
                 if (planItemStatus !== 'done' && planItemStatus !== 'blocked') {
-                    return `[ERR:INVALID_ARG] 不支持的状态 "${planItemStatus}"，仅支持 done/blocked`;
+                    // 非法参数 = 执行失败事实（方案明文 INVALID_ARG=failed）→ 显式 emit failed
+                    const invalidStatusText = `[ERR:INVALID_ARG] 不支持的状态 "${planItemStatus}"，仅支持 done/blocked`;
+                    emitOutcome?.(failedOutcome(invalidStatusText));
+                    return invalidStatusText;
                 }
                 return this.planManager.updatePlanItem(resolved.id, planItemStatus);
             }
@@ -920,11 +1092,18 @@ export class ToolExecutor {
                 // 渐进披露 L2：读取激活角色包内嵌技能正文（readSkill 回调由 agent 装配注入）
                 // name 为必填参数，已由 validateAndCoerceArgs 校验，此处直接用
                 if (!this.readSkill) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] read_skill 不可用：未装配角色包技能读取回调';
+                    // 能力未装配 = 执行失败事实（非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', 'read_skill 不可用：未装配角色包技能读取回调');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const content = await this.readSkill(strArg('name'));
                 if (content === null) {
-                    return `[ERR:SKILL_NOT_FOUND] 未找到技能 "${strArg('name')}"（角色包 skills/ 与全局技能池均无此名，或技能正文读取失败）`;
+                    // 技能未找到 = 执行失败事实 → 显式 emit failed
+                    const notFoundText = `[ERR:SKILL_NOT_FOUND] 未找到技能 "${strArg('name')}"（角色包 skills/ 与全局技能池均无此名，或技能正文读取失败）`;
+                    emitOutcome?.(failedOutcome(notFoundText));
+                    return notFoundText;
                 }
                 // 返回净化：技能正文当外部内容去控制字符 + 长度上限（防超长技能正文撑爆上下文）
                 return sanitizeExternalText(content, SKILL_CONTENT_MAX_LEN);
@@ -932,13 +1111,20 @@ export class ToolExecutor {
             case 'read_resource': {
                 // 渐进披露 L3：读取技能的参考资源文件
                 if (!this.readResource) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] read_resource 不可用：未装配 L3 资源读取回调';
+                    // 能力未装配 = 执行失败事实（非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', 'read_resource 不可用：未装配 L3 资源读取回调');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const skillName = strArg('skill_name');
                 const resourcePath = strArg('resource_path');
                 const resourceContent = await this.readResource(skillName, resourcePath);
                 if (resourceContent === null) {
-                    return `[ERR:RESOURCE_NOT_FOUND] 未找到资源 "${resourcePath}"（技能 "${skillName}" 无此资源，或资源读取失败）`;
+                    // 资源未找到 = 执行失败事实 → 显式 emit failed
+                    const notFoundText = `[ERR:RESOURCE_NOT_FOUND] 未找到资源 "${resourcePath}"（技能 "${skillName}" 无此资源，或资源读取失败）`;
+                    emitOutcome?.(failedOutcome(notFoundText));
+                    return notFoundText;
                 }
                 // 返回净化：资源正文当外部内容去控制字符 + 长度上限（防超长资源撑爆上下文）
                 return sanitizeExternalText(resourceContent, RESOURCE_CONTENT_MAX_LEN);
@@ -946,7 +1132,11 @@ export class ToolExecutor {
             case 'run_skill_script': {
                 // 渐进披露 L3：执行技能的可执行脚本（脚本源码不进上下文，仅结果返回）
                 if (!this.runSkillScript) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] run_skill_script 不可用：未装配 L3 脚本执行回调';
+                    // 未装配回调 = 工具能力缺失（旧口径 [ERR 开头亦判失败），显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', 'run_skill_script 不可用：未装配 L3 脚本执行回调');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const skillName = strArg('skill_name');
                 const scriptPath = strArg('script_path');
@@ -957,16 +1147,26 @@ export class ToolExecutor {
                 // confirmScripts=true 时 owner 亦确认（开关语义 = "脚本执行二次确认"，对全部脚本生效）。
                 // 无 OS 级沙箱（子进程直跑 + env 继承用户环境），故不能以 Codex workspace-write 的
                 // "边界内自动"前提豁免 guest。target 用技能名:脚本路径标识（无落盘绝对路径）。
-                const execConfirmed = await this.security.confirmScriptRun(`skill:${skillName}:${scriptPath ?? ''}`, 'run_skill_script', `执行技能 ${skillName} 的脚本 ${scriptPath ?? ''}`);
+                const execConfirmed = await this.confirmByEntry(requireConfirmingEntry('run_skill_script'), `skill:${skillName}:${scriptPath ?? ''}`, 'run_skill_script', `执行技能 ${skillName} 的脚本 ${scriptPath ?? ''}`);
                 if (!execConfirmed) {
-                    return '[ERR:SCRIPT_DECLINE] 技能脚本执行未获确认（用户拒绝或未注入确认回调，fail-closed）';
+                    // 用户/系统拒绝执行 = 主动挡下（permission_denied），非执行失败
+                    const declineText = '[ERR:SCRIPT_DECLINE] 技能脚本执行未获确认（用户拒绝或未注入确认回调，fail-closed）';
+                    emitOutcome?.(blockedOutcome('permission_denied', declineText));
+                    return declineText;
                 }
                 const result = await this.runSkillScript(skillName, scriptPath, scriptArgs);
                 if (result === null) {
-                    return `[ERR:SCRIPT_NOT_FOUND] 未找到脚本 "${scriptPath}"（技能 "${skillName}" 无此脚本，或执行失败）`;
+                    // 脚本不存在/无法执行 = 执行事实失败（区别于权限拒绝）
+                    const notFoundText = `[ERR:SCRIPT_NOT_FOUND] 未找到脚本 "${scriptPath}"（技能 "${skillName}" 无此脚本，或执行失败）`;
+                    emitOutcome?.(failedOutcome(notFoundText));
+                    return notFoundText;
                 }
-                // 返回净化：脚本输出当外部内容去控制字符 + 长度上限（8-1 对齐 run_code 的防护），防刷屏撑爆上下文
-                return sanitizeExternalText(result, RUN_SCRIPT_RESULT_MAX_LEN);
+                // 格式化在本点单点收口（B2-a：回调只返结构化事实）；再经净化防刷屏撑爆上下文
+                const formattedText = sanitizeExternalText(formatScriptResult(result), RUN_SCRIPT_RESULT_MAX_LEN, SCRIPT_RESULT_TAIL_CHARS);
+                // status 直接读执行事实：超时或退出码非 0 = failed，其余 = ok（不扫文本前缀）
+                const scriptFailed = result.timedOut || result.exitCode !== 0;
+                emitOutcome?.(scriptFailed ? failedOutcome(formattedText) : okOutcome(formattedText));
+                return formattedText;
             }
             case 'run_project_script': {
                 // 项目内已有脚本执行（默认开放，判据 A+B）：内核子进程执行，脚本源码不进上下文
@@ -979,12 +1179,18 @@ export class ToolExecutor {
                 // ① 路径白名单：相对项目根解析，防穿越返回 null → 拒绝（越界不协商）
                 const fullPath = resolveSafePath(this.builtinHandlers.projectPath, scriptPath);
                 if (!fullPath) {
-                    return `[ERR:PATH_DENIED] 脚本路径越界（超出项目根）："${scriptPath}"`;
+                    // 安全白名单拦截 = 主动挡下（B2-a 拍板：归 permission_denied，不新增枚举值）
+                    const pathDeniedText = `[ERR:PATH_DENIED] 脚本路径越界（超出项目根）："${scriptPath}"`;
+                    emitOutcome?.(blockedOutcome('permission_denied', pathDeniedText));
+                    return pathDeniedText;
                 }
                 // ② 执行确认：guest 模式或 confirmScripts 时询问（owner 默认自动批准，走审计）
-                const confirmed = await this.security.confirmScriptRun(fullPath, 'run_project_script', `运行项目脚本 ${scriptPath}`);
+                const confirmed = await this.confirmByEntry(requireConfirmingEntry('run_project_script'), fullPath, 'run_project_script', `运行项目脚本 ${scriptPath}`);
                 if (!confirmed) {
-                    return '[ERR:SCRIPT_DECLINE] 脚本运行未获确认（用户拒绝或未注入确认回调，fail-closed）';
+                    // 用户/系统拒绝执行 = 主动挡下（permission_denied），非执行失败
+                    const declineText = '[ERR:SCRIPT_DECLINE] 脚本运行未获确认（用户拒绝或未注入确认回调，fail-closed）';
+                    emitOutcome?.(blockedOutcome('permission_denied', declineText));
+                    return declineText;
                 }
                 // ③ 运行时白名单：扩展名推断并收敛到 node/python/shell 三档（推断即可信，不规则兜底 node）
                 const ext = scriptPath.slice(scriptPath.lastIndexOf('.')).toLowerCase();
@@ -1001,12 +1207,157 @@ export class ToolExecutor {
                 this.scriptNodePath);
                 // 返回净化：脚本输出当外部内容去控制字符 + 长度上限（防刷屏撑爆上下文，对齐 run_skill_script）
                 // 超时文案按本次实际超时生成（未传 timeout_ms → 内核默认 60s，见上），不恒报上限 600s
-                return sanitizeExternalText(formatScriptResult(result, timeoutMs), RUN_SCRIPT_RESULT_MAX_LEN);
+                const projectScriptText = sanitizeExternalText(formatScriptResult(result, timeoutMs), RUN_SCRIPT_RESULT_MAX_LEN, SCRIPT_RESULT_TAIL_CHARS);
+                // status 直接读执行事实（B2-a：不扫文本前缀）：超时或退出码非 0 = failed，其余 = ok
+                const projectScriptFailed = result.timedOut || result.exitCode !== 0;
+                emitOutcome?.(projectScriptFailed ? failedOutcome(projectScriptText) : okOutcome(projectScriptText));
+                return projectScriptText;
+            }
+            case 'run_command': {
+                // 裸命令执行（§13.2 裁决链 → 执行）：三道闸顺序不可颠倒——
+                //   ① 参数校验（空命令 / 越界 cwd）② 命令裁决（deny 恒拦 / alwaysAsk 恒确认）
+                //   ③ 执行（同步等退出码 / 后台注册表立即返回 taskId）
+                // 裁决链判据在 SecurityGuard.confirmCommandRun（与 confirmScriptRun 共用 confirmGate 单点）。
+                const command = strArg('command');
+                if (!command.trim()) {
+                    throw toolError('run_command 缺少 command 参数', '命令为空', ['传要执行的 shell 命令，如 "npm test"'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+                }
+                if (command.length > RUN_COMMAND_MAX_LEN) {
+                    // 截半条命令 = 语义破坏（执行的不是用户/模型写的那条），故整条拒收
+                    throw toolError('run_command 命令过长', `命令长度 ${command.length} 字符，超过上限 ${RUN_COMMAND_MAX_LEN}`, ['把命令拆成多条执行，或改用脚本文件 + run_project_script'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+                }
+                // cwd 缺省 = 项目根；显式传入时按项目根解析，越界拒绝（与 run_project_script 同判据）
+                let cwd = this.builtinHandlers.projectPath;
+                const rawCwd = strArg('cwd');
+                if (rawCwd) {
+                    const resolved = resolveSafePath(this.builtinHandlers.projectPath, rawCwd);
+                    if (!resolved) {
+                        const pathDeniedText = `[ERR:PATH_DENIED] 工作目录越界（超出项目根）："${rawCwd}"`;
+                        // 原生 outcome：越界拒绝 = 主动挡下 ⇒ blocked（对齐 run_project_script 同判据先例；
+                        // B4 口径：blocked 不再计入 toolFailureCount，见方案 §六决策二）
+                        emitOutcome?.(blockedOutcome('permission_denied', pathDeniedText));
+                        return pathDeniedText;
+                    }
+                    cwd = resolved;
+                }
+                // ② 命令裁决：deny 恒拦（不入确认流程）/ alwaysAsk 恒确认 / 其余同脚本判据
+                const confirmed = await this.confirmByEntry(requireConfirmingEntry('run_command'), command, 'run_command', `在工作区执行命令：${command}`);
+                if (!confirmed) {
+                    const declineText = '[ERR:COMMAND_DECLINE] 命令未获执行许可（命中恒拦黑名单 / 用户拒绝 / 未注入确认回调 fail-closed）。' +
+                        '未执行任何命令；如确需执行，请改用等效手段或请用户调整审批设置。';
+                    // 语义是「主动挡下」⇒ blocked（permission_denied），不是 failed。
+                    // ⚠️ 注释订正：原写「编排层仍按本前缀文本算 failed（已知口径分歧）」——**已不成立**，
+                    // 失败计数唯一判据面是 `outcome.status`（见 `loop._processToolResults`），内核无
+                    // 任何生产代码按文本算 failed，勿再去找那处并不存在的判据。
+                    // 本前缀只是**渲染面**（LLM 自愈看的证据类别），与判据面解耦，保留是有意的。
+                    emitOutcome?.(blockedOutcome('permission_denied', declineText));
+                    return declineText;
+                }
+                // ③ 执行：background=true 立即返回 taskId（不等进程结束）
+                // `=== 1` 兜底：validateAndCoerceArgs 已把字符串 'true'/'1' 归一为布尔，
+                // 裸数字 1 仍会漏过——若不认，模型要的后台会退化成同步阻塞（正是本能力要消除的形态）
+                if (args['background'] === true || args['background'] === 1) {
+                    if (!this.backgroundTasks) {
+                        // 能力缺失如实说（B1 缺口补齐：补 emit，对齐 run_code/run_skill_script NOT_AVAILABLE 先例）
+                        // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                        const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', 'run_command 后台模式不可用：未装配后台任务注册表');
+                        emitOutcome?.(naOutcome);
+                        return naOutcome.text;
+                    }
+                    const rawTimeout = args['timeoutMs'];
+                    const taskId = this.backgroundTasks.start(command, cwd, typeof rawTimeout === 'number' && Number.isFinite(rawTimeout) ? rawTimeout : undefined);
+                    return (`[BACKGROUND_STARTED] taskId=${taskId}（命令已在本轮之外继续运行，本轮对话结束不会终止它）。` +
+                        '**结果不会自动进入上下文**：它不会自己跳进来，你需要时用 kill_command 传入该 taskId，' +
+                        '取回截至当时的输出并终止它；若不取，它会一直跑到自己结束（未传 timeoutMs 时没有超时上限）。' +
+                        '寿命边界：正常退出 VS Code 时随扩展一并终止（扩展崩溃或被强制结束时不保证清理）。' +
+                        '命令：' +
+                        command);
+                }
+                // 同步路径：超时钳制与文案同源（resolveCommandTimeoutMs 单一真源，见 命令执行能力方案 §13.6-C）
+                const effectiveTimeoutMs = resolveCommandTimeoutMs(typeof args['timeoutMs'] === 'number' ? args['timeoutMs'] : undefined);
+                const result = await runShellCommand(command, cwd, effectiveTimeoutMs);
+                // 定长与净化由 formatCommandResult 自带（真源在格式化层，回流面共用同一上限）
+                const text = formatCommandResult(result, effectiveTimeoutMs);
+                // 原生 status 直接读**执行事实**（不扫文本前缀）：超时或退出码非 0 = failed，其余 = ok。
+                // status 与 text 同源产出，编排层/计数层只读 status（B4 判据切换，无文本交叉核对）。
+                const commandFailed = result.timedOut || result.exitCode !== 0;
+                emitOutcome?.(commandFailed ? failedOutcome(text) : okOutcome(text));
+                return text;
+            }
+            case 'kill_command': {
+                // 后台任务终止（§14.1 免裁决链：只可杀本 agent 起的自家任务，taskId 寻址非任意 pid）
+                if (!this.backgroundTasks) {
+                    // 能力缺失 = 执行失败事实（非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', 'kill_command 不可用：未装配后台任务注册表');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
+                }
+                const taskId = strArg('taskId');
+                if (!taskId) {
+                    throw toolError('kill_command 缺少 taskId 参数', '未传 taskId', ['传 run_command 后台执行返回的 taskId（如 "bg-1"）'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+                }
+                const outcome = this.backgroundTasks.kill(taskId);
+                // 不静默成功：不存在与已终态是两种语义，必须让 LLM 知道（命令执行能力方案 §13.6 未决二定案）
+                if (!outcome) {
+                    const notFoundText = `[ERR:TASK_NOT_FOUND] 未找到后台任务 "${taskId}"。` +
+                        '任务跨轮保留、可在后续轮次 kill；该 id 可能本就有误，或来自扩展重启前的会话' +
+                        '（注册表不跨重启保留）——本轮不会终止任何进程。';
+                    emitOutcome?.(failedOutcome(notFoundText));
+                    return notFoundText;
+                }
+                const task = this.backgroundTasks.get(taskId);
+                if (!outcome.result) {
+                    const settledBareText = `[TASK_ALREADY_SETTLED] taskId=${taskId} 已是终态（status=${outcome.status}，无需终止；该任务无已捕获输出）`;
+                    // 终止动作本身完成（无事可终止）→ ok；底层任务若有失败已由完成点单点结算（B3）
+                    emitOutcome?.(okOutcome(settledBareText));
+                    return settledBareText;
+                }
+                // 结果体的净化与定长由 formatCommandResult / formatKilledCommandOutput 自带
+                // （定长真源在格式化层，两条消费面共用）——此处不再套一层，避免两个 policy。
+                if (outcome.status === 'killed') {
+                    // 被主动终止 ≠ 执行失败：走专用格式化，不谎报退出码（见 formatKilledCommandOutput）
+                    const killedText = `[KILLED] taskId=${taskId}（已终止；以下为截至终止时的输出）\n命令：${task?.command ?? '(未知)'}\n${formatKilledCommandOutput(outcome.result)}`;
+                    // 终止动作成功 → ok（强杀无退出码，文本不谎报失败，status 同样不谎）
+                    emitOutcome?.(okOutcome(killedText));
+                    return killedText;
+                }
+                const settledNote = `[TASK_ALREADY_SETTLED] taskId=${taskId} 已是终态（status=${outcome.status}，无需终止）`;
+                // 行首归属判据改读**结构化执行事实**（B4 判据切换，不再扫文本前缀）：
+                // 「已是终态」是控制流事实、「退出码非零/超时」是执行结局事实，两者抢同一行首。
+                // 原写法把 [TASK_ALREADY_SETTLED] 放行首 ⇒ 已终态的失败任务被判成功
+                // （SCRIPT-1 同形状漏计，2026-10-06 实测）。
+                // 修法：失败/超时终态把结果体提到行首（结局可判），「已终态」说明降为末尾附注。
+                // ⚠️ 引导语必须**随结果体一起走**（不能钉在 settledNote 上）：它在原文案里是
+                // **前置引导**（结果在下方）。若失败路径把同一句放在结果体**之后**，「以下」就变成
+                // 指向上方 —— 对 LLM 是指代错乱的谎。两条路径各自带对位置的引导语。
+                const commandLine = `命令：${task?.command ?? '(未知)'}`;
+                const body = formatCommandResult(outcome.result);
+                // 失败终态判定（timedOut / exitCode 非零）仍写入文本（诚实呈现），
+                // 但 **status 恒 ok**：底层任务的失败已在完成点单点结算（B3 setBackgroundTasks 回调），
+                // kill 回传只是「取回输出快照」这一动作的成功 —— 若此处再判 failed，同一失败计 2 次
+                // （双计伤：B3 完成点 × B4-c 行首 [COMMAND_ERROR] 桥判，2026-10-06 实测）。
+                // 文本层的 [COMMAND_ERROR] 保留给 LLM 看结局，计数层只认 status（单点结算）。
+                const settledWithFailure = outcome.result.timedOut || outcome.result.exitCode !== 0;
+                if (settledWithFailure) {
+                    // 附注在结果**之后** ⇒ 用回指语（「其结果为」），不用「以下」。
+                    const settledFailedText = `${body}\n${commandLine}\n${settledNote}；其结果为上述内容`;
+                    emitOutcome?.(okOutcome(settledFailedText));
+                    return settledFailedText;
+                }
+                // 成功路径：附注在前、结果在后 ⇒ 沿用原文案的前置引导语，逐字不变。
+                const settledOkText = `${settledNote}；以下为其结果\n${commandLine}\n${body}`;
+                emitOutcome?.(okOutcome(settledOkText));
+                return settledOkText;
             }
             case 'list_resources': {
                 // 渐进披露 L3：列出技能的资源清单
                 if (!this.listResources) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] list_resources 不可用';
+                    // 能力未装配 = 执行失败事实（非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', 'list_resources 不可用');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const skillName = strArg('skill_name');
                 return await this.listResources(skillName);
@@ -1014,26 +1365,41 @@ export class ToolExecutor {
             case 'list_skills': {
                 // 渐进披露 L1 补充：列出所有技能清单（>50 技能时使用）
                 if (!this.listSkills) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] list_skills 不可用';
+                    // 能力未装配 = 执行失败事实（非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', 'list_skills 不可用');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 return await this.listSkills();
             }
             case 'register_work': {
                 // 作品投影登记（registerWork 回调由 agent 装配注入；用户主动触发写索引卡片）
                 if (!this.registerWork) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] register_work 不可用：未装配作品投影登记回调';
+                    // 能力未装配 = 执行失败事实（非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', 'register_work 不可用：未装配作品投影登记回调');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const path = strArg('path');
                 const description = strArg('description');
                 if (!path || !description) {
-                    return '[ERR:INVALID_ARG] register_work 需要 path（相对项目根）与 description（一句话说明）参数';
+                    // 非法参数 = 执行失败事实（方案明文 INVALID_ARG=failed）→ 显式 emit failed
+                    const invalidArgText = '[ERR:INVALID_ARG] register_work 需要 path（相对项目根）与 description（一句话说明）参数';
+                    emitOutcome?.(failedOutcome(invalidArgText));
+                    return invalidArgText;
                 }
                 return await this.registerWork(path, description);
             }
             case 'run_team_meeting': {
                 // 评估/评审型小组会议（runTeamMeeting 回调由 agent 装配注入；工具内嵌一次 LLM 调用）
                 if (!this.runTeamMeeting) {
-                    return '[ERR:TOOL:NOT_AVAILABLE] run_team_meeting 不可用：未装配小组会议回调';
+                    // 能力未装配 = 执行失败事实（非主动拦截）→ 显式 emit failed
+                    // 错误码与文本前缀经 failedOutcomeWithCode 同源产出（NOT_AVAILABLE 不可重试）
+                    const naOutcome = failedOutcomeWithCode('NOT_AVAILABLE', 'run_team_meeting 不可用：未装配小组会议回调');
+                    emitOutcome?.(naOutcome);
+                    return naOutcome.text;
                 }
                 const group = strArg('group');
                 const topic = strArg('topic');