@kiturone/kapibala 0.0.5 → 0.0.6

package/dist/index.js

@@ -119,12 +119,25 @@ var KapibalaError = class extends Error {
   code;
   retryPolicy;
   safeMessage;
+  dispatchOutcome;
   constructor(message, options) {
     super(message);
     this.name = "KapibalaError";
     this.code = options?.code ?? "INTERNAL_ERROR";
     this.retryPolicy = options?.retryPolicy ?? "never";
     this.safeMessage = options?.safeMessage ?? "Operation failed";
+    this.dispatchOutcome = options?.dispatchOutcome;
+  }
+};
+var PreDispatchError = class extends KapibalaError {
+  constructor(message, options) {
+    super(message, {
+      code: options?.code ?? "PRE_DISPATCH_FAILED",
+      retryPolicy: options?.retryPolicy ?? "never",
+      safeMessage: options?.safeMessage ?? "Tool execution was aborted before dispatch",
+      dispatchOutcome: "not_sent"
+    });
+    this.name = "PreDispatchError";
   }
 };
 var ModelError = class extends KapibalaError {
@@ -309,6 +322,16 @@ function validateProtocolContent(content) {
         invalidState();
       }
     }
+    if (block.type === "tool_result" && "execution" in block && block.execution !== void 0) {
+      const ex = block.execution;
+      if (!ex || typeof ex !== "object" || ex.version !== 1 || !["not_sent", "succeeded", "failed", "unknown"].includes(ex.dispatchOutcome) || ex.hostError !== void 0 && (!ex.hostError || typeof ex.hostError !== "object" || !["validation", "projection", "hook", "audit"].includes(ex.hostError.phase) || typeof ex.hostError.code !== "string" || !ex.hostError.code))
+        invalidState();
+    }
+    if (block.type === "text" && "promptSource" in block && block.promptSource !== void 0) {
+      const ps = block.promptSource;
+      if (!ps || typeof ps !== "object" || ps.version !== 1 || typeof ps.server !== "string" || !ps.server || typeof ps.name !== "string" || !ps.name || ps.scope !== void 0 && typeof ps.scope !== "string" || ps.contentDigest !== void 0 && typeof ps.contentDigest !== "string" || ps.configIdentity !== void 0 && typeof ps.configIdentity !== "string")
+        invalidState();
+    }
     validatedBlocks.set(block, true);
   }
   validatedContents.set(content, true);
@@ -426,7 +449,11 @@ function normalizeHistory(input) {
         content: "Tool execution was interrupted or crashed in previous session",
         isError: true,
         errorCode: "OUTCOME_UNKNOWN",
-        retryPolicy: "after_user_action"
+        retryPolicy: "after_user_action",
+        execution: {
+          version: 1,
+          dispatchOutcome: "unknown"
+        }
       };
       content.push(repair);
       result.repairs.push({
@@ -4710,7 +4737,8 @@ var CAPABILITIES = /* @__PURE__ */ new Set([
   "exec",
   "net:outbound",
   "env:read",
-  "agent:spawn"
+  "agent:spawn",
+  "external:call"
 ]);
 function validatePermissionRules(rules) {
   for (const [index2, rule] of rules.entries()) {
@@ -4823,7 +4851,8 @@ var SessionApprovalCache = class {
         [...request.capabilities].sort(),
         request.input,
         request.rootDir,
-        request.shell ?? null
+        request.shell ?? null,
+        request.executionIdentity ?? null
       ])
     ).digest("hex");
   }
@@ -4841,9 +4870,14 @@ var ToolRegistry = class {
   toolSources = /* @__PURE__ */ new Map();
   // toolName -> source
   conflictPolicy;
+  version = 0;
   constructor(options) {
     this.conflictPolicy = options?.conflictPolicy ?? "error";
   }
+  /** 获取当前注册表版本号；每次有效变更（注册、替换、注销）单调自增。 */
+  get currentVersion() {
+    return this.version;
+  }
   register(tool, opts) {
     const source = opts?.source ?? tool.metadata?.source ?? "builtin";
     const existing = this.tools.get(tool.name);
@@ -4859,27 +4893,93 @@ var ToolRegistry = class {
     }
     this.tools.set(tool.name, tool);
     this.toolSources.set(tool.name, source);
+    this.version++;
   }
-  registerSource(source, tools) {
+  /**
+   * 原子替换指定来源的全部工具：
+   * 1. 预检候选批内自身重名：若候选批次内包含同名工具，整批拒绝；
+   * 2. 预检跨来源冲突：若候选工具被其它来源占用且策略不允许覆盖，整批拒绝；
+   * 3. 同步原子提交：预检全部通过后一次性清理该来源旧工具并写入新工具；失败时完全保持旧状态不变。
+   */
+  replaceSource(source, tools) {
+    const batchNames = /* @__PURE__ */ new Set();
+    for (const tool of tools) {
+      if (batchNames.has(tool.name)) {
+        throw new Error(
+          `Invalid candidate tools: duplicate tool name '${tool.name}' within source batch '${source}'`
+        );
+      }
+      batchNames.add(tool.name);
+    }
     for (const tool of tools) {
-      this.register(tool, { source });
+      const existing = this.tools.get(tool.name);
+      const existingSource = this.toolSources.get(tool.name);
+      if (existing && existingSource !== source) {
+        if (this.conflictPolicy === "error") {
+          throw new Error(
+            `Tool name conflict: candidate '${tool.name}' from '${source}' conflicts with existing tool registered by '${existingSource}'`
+          );
+        }
+        if (this.conflictPolicy === "prefer-builtin" && existingSource === "builtin") {
+          throw new Error(
+            `Tool name conflict: candidate '${tool.name}' from '${source}' cannot override builtin tool`
+          );
+        }
+      }
     }
+    for (const [name, s] of this.toolSources.entries()) {
+      if (s === source) {
+        this.tools.delete(name);
+        this.toolSources.delete(name);
+      }
+    }
+    for (const tool of tools) {
+      this.tools.set(tool.name, tool);
+      this.toolSources.set(tool.name, source);
+    }
+    this.version++;
+  }
+  /**
+   * 注册指定来源的工具集。
+   *
+   * 语义与约束：
+   * 1. 委托给 `replaceSource` 实现整源原子替换（新集合未包含的该来源旧工具将被注销移除，非增量累加）；
+   * 2. 默认禁止跨来源名称冲突（抛出 KapibalaError TOOL_CONFLICT）；若 options 配置了 conflictPolicy: 'prefer-last' 则允许覆盖旧来源同名工具；
+   * 3. 预检阶段发现批内同名重复时整批拒绝，绝不破坏注册表原子状态。
+   */
+  registerSource(source, tools) {
+    this.replaceSource(source, tools);
   }
   unregisterSource(source) {
+    let changed = false;
     for (const [name, s] of this.toolSources.entries()) {
       if (s === source) {
         this.tools.delete(name);
         this.toolSources.delete(name);
+        changed = true;
       }
     }
+    if (changed) {
+      this.version++;
+    }
   }
   get(name) {
     return this.tools.get(name);
   }
+  has(name) {
+    return this.tools.has(name);
+  }
+  /** 获取工具对应的来源标记。 */
+  sourceOf(name) {
+    return this.toolSources.get(name);
+  }
   /** 注销指定名称及来源记录；调用方须核对实例身份，不能移除同名替代工具。 */
   unregister(name) {
-    this.tools.delete(name);
-    this.toolSources.delete(name);
+    if (this.tools.has(name)) {
+      this.tools.delete(name);
+      this.toolSources.delete(name);
+      this.version++;
+    }
   }
   /** 未命中时抛 ToolNotFound，并携带当前全部可用名称辅助模型自纠。 */
   resolve(name) {
@@ -4895,6 +4995,30 @@ var ToolRegistry = class {
   definitions() {
     return this.list().map(toToolDefinition);
   }
+  /**
+   * 捕获当前注册表的不可变只读快照。
+   * 注册表后续的增删改绝不改变该快照的定义列表、工具执行实例与来源版本。
+   */
+  snapshot() {
+    const snapshotTools = new Map(this.tools);
+    const snapshotSources = new Map(this.toolSources);
+    const snapshotVersion = this.version;
+    return {
+      version: snapshotVersion,
+      get: (name) => snapshotTools.get(name),
+      has: (name) => snapshotTools.has(name),
+      resolve: (name) => {
+        const tool = snapshotTools.get(name);
+        if (!tool) {
+          throw new ToolNotFound(name, Array.from(snapshotTools.keys()));
+        }
+        return tool;
+      },
+      list: () => Array.from(snapshotTools.values()),
+      definitions: () => Array.from(snapshotTools.values()).map(toToolDefinition),
+      sourceOf: (name) => snapshotSources.get(name)
+    };
+  }
 };
 
 // src/capabilities/tools/builtin/fs.ts
@@ -5370,14 +5494,18 @@ var ToolExecutor = class {
     call.executionRoot = path15.resolve(this.rootDir);
     const startedAt = Date.now();
     const operationId = createLogId();
-    const failure = (message, errorCode, retryPolicy = "never") => ({
+    const failure = (message, errorCode, retryPolicy = "never", execution) => ({
       type: "tool_result",
       toolUseId: call.id,
       content: JSON.stringify({ code: errorCode, retryPolicy, message }),
       isError: true,
       errorCode,
       retryPolicy,
-      durationMs: Math.max(0, Date.now() - startedAt)
+      durationMs: Math.max(0, Date.now() - startedAt),
+      execution: execution ?? {
+        version: 1,
+        dispatchOutcome: "not_sent"
+      }
     });
     const audit = async (event, fields = {}) => {
       if (!this.eventLogger || !this.sessionId) return;
@@ -5397,7 +5525,12 @@ var ToolExecutor = class {
       return failure(
         "Audit unavailable; tool was not started",
         "AUDIT_UNAVAILABLE",
-        "after_user_action"
+        "after_user_action",
+        {
+          version: 1,
+          dispatchOutcome: "not_sent",
+          hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+        }
       );
     }
     if (forcedDeny) {
@@ -5408,7 +5541,12 @@ var ToolExecutor = class {
         return failure(
           "Audit unavailable; tool was not started",
           "AUDIT_UNAVAILABLE",
-          "after_user_action"
+          "after_user_action",
+          {
+            version: 1,
+            dispatchOutcome: "not_sent",
+            hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+          }
         );
       }
       return failure(
@@ -5431,7 +5569,11 @@ var ToolExecutor = class {
             toolUseId: call.id,
             content: decision.result,
             isError: decision.isError ?? false,
-            durationMs: Math.max(0, Date.now() - startedAt)
+            durationMs: Math.max(0, Date.now() - startedAt),
+            execution: {
+              version: 1,
+              dispatchOutcome: "not_sent"
+            }
           };
         }
       }
@@ -5441,8 +5583,23 @@ var ToolExecutor = class {
         await audit("tool.finished", { status: "failed" });
       } catch {
       }
-      return failure("Tool preparation failed", "HOOK_ERROR");
+      return failure("Tool preparation failed", "HOOK_ERROR", "never", {
+        version: 1,
+        dispatchOutcome: "not_sent",
+        hostError: { phase: "hook", code: "HOOK_ERROR" }
+      });
     }
+    function deepFreeze(obj) {
+      if (obj === null || typeof obj !== "object" || Object.isFrozen(obj)) {
+        return obj;
+      }
+      Object.freeze(obj);
+      for (const key of Object.keys(obj)) {
+        deepFreeze(obj[key]);
+      }
+      return obj;
+    }
+    const finalInput = deepFreeze(structuredClone(currentInput));
     let tool;
     try {
       tool = this.tools.resolve(call.name);
@@ -5455,13 +5612,50 @@ var ToolExecutor = class {
       }
       return failure(
         known?.safeMessage ?? "Requested tool is unavailable",
-        known?.code ?? "TOOL_NOT_FOUND"
+        known?.code ?? "TOOL_NOT_FOUND",
+        "never",
+        {
+          version: 1,
+          dispatchOutcome: "not_sent"
+        }
       );
     }
+    try {
+      const validation = tool.validateInput?.(finalInput);
+      if (validation && !validation.valid) {
+        try {
+          await audit("tool.decided", { decision: "deny", decisionSource: "validation" });
+          await audit("tool.finished", { status: "failed", errorCode: "INVALID_INPUT" });
+        } catch {
+        }
+        return failure(
+          validation.message || "Tool input validation failed",
+          "INVALID_INPUT",
+          "never",
+          {
+            version: 1,
+            dispatchOutcome: "not_sent",
+            hostError: { phase: "validation", code: "INVALID_INPUT" }
+          }
+        );
+      }
+    } catch (err) {
+      try {
+        await audit("tool.decided", { decision: "deny", decisionSource: "validation" });
+        await audit("tool.finished", { status: "failed", errorCode: "INVALID_INPUT" });
+      } catch {
+      }
+      const msg = err instanceof Error ? err.message : "Tool input validation error";
+      return failure(msg || "Tool input validation error", "INVALID_INPUT", "never", {
+        version: 1,
+        dispatchOutcome: "not_sent",
+        hostError: { phase: "validation", code: "INVALID_INPUT" }
+      });
+    }
     try {
       return await this.executeResolved(
         call,
-        currentInput,
+        finalInput,
         tool,
         startedAt,
         audit,
@@ -5477,14 +5671,18 @@ var ToolExecutor = class {
       return failure(
         "Tool outcome is unknown after an executor failure",
         "OUTCOME_UNKNOWN",
-        "after_user_action"
+        "after_user_action",
+        {
+          version: 1,
+          dispatchOutcome: "unknown"
+        }
       );
     }
   }
-  async executeResolved(call, currentInput, tool, startedAt, audit, failure, hookCtx, onProgress) {
+  async executeResolved(call, finalInput, tool, startedAt, audit, failure, hookCtx, onProgress) {
     let shell;
     try {
-      shell = tool.approvalScope?.(currentInput, this.rootDir);
+      shell = tool.approvalScope?.(finalInput, this.rootDir);
     } catch {
       try {
         await audit("tool.decided", { decision: "deny", decisionSource: "invalid_target" });
@@ -5493,19 +5691,32 @@ var ToolExecutor = class {
       }
       return failure("Invalid tool execution target", "INVALID_TARGET");
     }
+    let executionIdentity;
+    try {
+      executionIdentity = tool.executionIdentity?.(finalInput, this.rootDir);
+    } catch {
+      try {
+        await audit("tool.decided", { decision: "deny", decisionSource: "invalid_identity" });
+        await audit("tool.finished", { status: "failed", errorCode: "INVALID_TARGET" });
+      } catch {
+      }
+      return failure("Invalid tool execution identity", "INVALID_TARGET");
+    }
     let auditFields = {};
     for (let attempt = 0; attempt < 2; attempt++) {
       const request = {
         toolName: call.name,
         capabilities: tool.metadata?.permissions ?? [],
-        input: currentInput,
+        input: finalInput,
         rootDir: this.rootDir,
         ...shell ? { shell } : {},
+        ...executionIdentity ? { executionIdentity } : {},
         // 解释器内建查询与内容已绑定摘要的工作区直引脚本可确认不受外部脚本变更影响，
         // 允许会话级批准；其余 shell 命令仅允许单次批准。
+        // 非 shell 工具（含深度绑定 executionIdentity 的外部工具）允许会话级批准。
         sessionAllowed: !shell || /^(?:pwd|get-location)$/i.test(shell.command.trim()) || shell.scriptDigest !== void 0
       };
-      const repeatKey = createHash11("sha256").update(stableJsonStringify([call.name, currentInput])).digest("hex");
+      const repeatKey = createHash11("sha256").update(stableJsonStringify([call.name, finalInput])).digest("hex");
       if (this.neverFailures.has(repeatKey)) {
         try {
           await audit("tool.decided", { decision: "deny", decisionSource: "repeat_block" });
@@ -5514,7 +5725,12 @@ var ToolExecutor = class {
           return failure(
             "Audit unavailable; tool was not started",
             "AUDIT_UNAVAILABLE",
-            "after_user_action"
+            "after_user_action",
+            {
+              version: 1,
+              dispatchOutcome: "not_sent",
+              hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+            }
           );
         }
         return failure(
@@ -5522,7 +5738,7 @@ var ToolExecutor = class {
           "REPEAT_BLOCKED"
         );
       }
-      const hardDenied = this.hardDenial?.(tool, currentInput);
+      const hardDenied = this.hardDenial?.(tool, finalInput);
       const cached = this.approvalCache.get(request);
       const decision = this.policy.decide({
         hardDenied: hardDenied !== void 0,
@@ -5558,6 +5774,11 @@ var ToolExecutor = class {
         executableDigest: shell.executableDigest,
         executionFingerprint: shell.executionFingerprint,
         ...commandAuditSummary(shell.command)
+      } : executionIdentity ? {
+        serverIdentity: executionIdentity.serverIdentity,
+        connectionGeneration: executionIdentity.connectionGeneration,
+        catalogEpoch: executionIdentity.catalogEpoch,
+        toolDigest: executionIdentity.toolDigest
       } : {};
       try {
         await audit("tool.decided", {
@@ -5571,7 +5792,12 @@ var ToolExecutor = class {
         return failure(
           "Audit unavailable; tool was not started",
           "AUDIT_UNAVAILABLE",
-          "after_user_action"
+          "after_user_action",
+          {
+            version: 1,
+            dispatchOutcome: "not_sent",
+            hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+          }
         );
       }
       if (!permitted || this.signal?.aborted) {
@@ -5579,7 +5805,11 @@ var ToolExecutor = class {
         try {
           await audit("tool.finished", { status: "denied", errorCode: code });
         } catch {
-          return failure("Audit result unavailable", "AUDIT_UNAVAILABLE", "after_user_action");
+          return failure("Audit result unavailable", "AUDIT_UNAVAILABLE", "after_user_action", {
+            version: 1,
+            dispatchOutcome: "not_sent",
+            hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+          });
         }
         return failure(
           this.signal?.aborted ? "Operation cancelled" : hardDenied?.message ?? "Tool permission denied",
@@ -5589,7 +5819,7 @@ var ToolExecutor = class {
       }
       if (shell) {
         try {
-          const next = tool.approvalScope?.(currentInput, this.rootDir);
+          const next = tool.approvalScope?.(finalInput, this.rootDir);
           if (next?.executionFingerprint !== shell.executionFingerprint) {
             if (attempt === 0 && next) {
               try {
@@ -5598,7 +5828,12 @@ var ToolExecutor = class {
                 return failure(
                   "Audit unavailable; tool was not started",
                   "AUDIT_UNAVAILABLE",
-                  "after_user_action"
+                  "after_user_action",
+                  {
+                    version: 1,
+                    dispatchOutcome: "not_sent",
+                    hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+                  }
                 );
               }
               shell = next;
@@ -5619,6 +5854,37 @@ var ToolExecutor = class {
           );
         }
       }
+      if (executionIdentity) {
+        try {
+          const nextIdentity = tool.executionIdentity?.(finalInput, this.rootDir);
+          if (!nextIdentity || nextIdentity.serverIdentity !== executionIdentity.serverIdentity || nextIdentity.connectionGeneration !== executionIdentity.connectionGeneration || nextIdentity.catalogEpoch !== executionIdentity.catalogEpoch || nextIdentity.toolDigest !== executionIdentity.toolDigest) {
+            await audit("tool.finished", {
+              status: "identity_changed",
+              errorCode: "MCP_TOOL_CHANGED"
+            });
+            return failure(
+              "Tool execution identity changed after approval",
+              "MCP_TOOL_CHANGED",
+              "after_user_action",
+              {
+                version: 1,
+                dispatchOutcome: "not_sent",
+                hostError: { phase: "validation", code: "MCP_TOOL_CHANGED" }
+              }
+            );
+          }
+        } catch {
+          return failure(
+            "Tool execution identity check failed after approval",
+            "MCP_TOOL_CHANGED",
+            "after_user_action",
+            {
+              version: 1,
+              dispatchOutcome: "not_sent"
+            }
+          );
+        }
+      }
       break;
     }
     try {
@@ -5627,13 +5893,19 @@ var ToolExecutor = class {
       return failure(
         "Audit unavailable; tool was not started",
         "AUDIT_UNAVAILABLE",
-        "after_user_action"
+        "after_user_action",
+        {
+          version: 1,
+          dispatchOutcome: "not_sent",
+          hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+        }
       );
     }
     let outputStr;
     let isError = false;
     let errorCode;
     let retryPolicy;
+    let execution;
     try {
       const executionController = new AbortController();
       const abortFromSession = () => executionController.abort();
@@ -5652,16 +5924,52 @@ var ToolExecutor = class {
         } : {}
       };
       try {
-        const rawResult = tool.metadata?.managesTimeout ? await tool.execute(currentInput, toolCtx) : await this.withTimeout(
-          tool.execute(currentInput, toolCtx),
+        const rawResult = tool.metadata?.managesTimeout ? await tool.execute(finalInput, toolCtx) : await this.withTimeout(
+          tool.execute(finalInput, toolCtx),
           call.name,
           executionController
         );
-        outputStr = typeof rawResult === "string" ? rawResult : JSON.stringify(rawResult, null, 2);
-        if (call.name === "run_command" && typeof rawResult === "object" && rawResult !== null && "exitCode" in rawResult && rawResult.exitCode !== 0) {
-          isError = true;
-          errorCode = "COMMAND_EXIT_NONZERO";
-          retryPolicy = "never";
+        if (typeof tool.toExecutionResult === "function") {
+          try {
+            const converted = tool.toExecutionResult(rawResult);
+            outputStr = converted.content;
+            isError = converted.isError ?? false;
+            errorCode = converted.errorCode;
+            retryPolicy = converted.retryPolicy;
+            execution = converted.execution ?? {
+              version: 1,
+              dispatchOutcome: isError ? "failed" : "succeeded"
+            };
+          } catch (convErr) {
+            isError = true;
+            errorCode = "MCP_RESULT_INVALID";
+            retryPolicy = "after_user_action";
+            outputStr = convErr instanceof Error ? convErr.message : "Tool result projection failed";
+            execution = {
+              version: 1,
+              dispatchOutcome: "succeeded",
+              hostError: {
+                phase: "projection",
+                code: "MCP_RESULT_INVALID"
+              }
+            };
+          }
+        } else {
+          outputStr = typeof rawResult === "string" ? rawResult : JSON.stringify(rawResult, null, 2);
+          if (call.name === "run_command" && typeof rawResult === "object" && rawResult !== null && "exitCode" in rawResult && rawResult.exitCode !== 0) {
+            isError = true;
+            errorCode = "COMMAND_EXIT_NONZERO";
+            retryPolicy = "never";
+            execution = {
+              version: 1,
+              dispatchOutcome: "failed"
+            };
+          } else {
+            execution = {
+              version: 1,
+              dispatchOutcome: "succeeded"
+            };
+          }
         }
       } finally {
         this.signal?.removeEventListener("abort", abortFromSession);
@@ -5672,13 +5980,19 @@ var ToolExecutor = class {
       outputStr = known?.safeMessage ?? "Tool execution failed";
       errorCode = known?.code ?? "TOOL_FAILED";
       retryPolicy = known?.retryPolicy ?? "never";
+      const outcome = known?.dispatchOutcome ?? (errorCode === "OUTCOME_UNKNOWN" || known && known.retryPolicy === "after_user_action" ? "unknown" : "failed");
+      execution = {
+        version: 1,
+        dispatchOutcome: outcome
+      };
     }
     const resultBlock = {
       type: "tool_result",
       toolUseId: call.id,
       content: outputStr,
       isError,
-      ...errorCode ? { errorCode, retryPolicy } : {}
+      ...errorCode ? { errorCode, retryPolicy } : {},
+      execution
     };
     if (resultBlock.isError && resultBlock.errorCode) {
       resultBlock.content = JSON.stringify({
@@ -5691,7 +6005,7 @@ var ToolExecutor = class {
       for (const hook of this.hooks.get("tool:after")) {
         await hook(
           hookCtx,
-          { id: call.id, name: call.name, input: currentInput },
+          { id: call.id, name: call.name, input: finalInput },
           { output: outputStr, isError }
         );
       }
@@ -5704,11 +6018,19 @@ var ToolExecutor = class {
       resultBlock.isError = true;
       resultBlock.errorCode = "HOOK_ERROR";
       resultBlock.retryPolicy = "after_user_action";
+      resultBlock.execution = {
+        version: 1,
+        dispatchOutcome: resultBlock.execution?.dispatchOutcome ?? "failed",
+        hostError: {
+          phase: "hook",
+          code: "HOOK_ERROR"
+        }
+      };
     }
     resultBlock.durationMs = Math.max(0, Date.now() - startedAt);
     if (resultBlock.isError && resultBlock.retryPolicy === "never") {
       this.neverFailures.add(
-        createHash11("sha256").update(stableJsonStringify([call.name, currentInput])).digest("hex")
+        createHash11("sha256").update(stableJsonStringify([call.name, finalInput])).digest("hex")
       );
     }
     try {
@@ -5718,13 +6040,25 @@ var ToolExecutor = class {
         durationMs: resultBlock.durationMs
       });
     } catch {
-      return failure(
-        "Tool outcome is unknown because the audit result could not be written",
-        "OUTCOME_UNKNOWN",
-        "after_user_action"
-      );
+      resultBlock.isError = true;
+      resultBlock.errorCode = "OUTCOME_UNKNOWN";
+      resultBlock.retryPolicy = "after_user_action";
+      resultBlock.content = JSON.stringify({
+        code: "OUTCOME_UNKNOWN",
+        retryPolicy: "after_user_action",
+        message: "Tool outcome is unknown because the audit result could not be written"
+      });
+      resultBlock.execution = {
+        version: 1,
+        dispatchOutcome: resultBlock.execution?.dispatchOutcome ?? "succeeded",
+        hostError: {
+          phase: "audit",
+          code: "AUDIT_UNAVAILABLE"
+        }
+      };
+      return resultBlock;
     }
-    await this.onToolResult?.(tool, currentInput, resultBlock);
+    await this.onToolResult?.(tool, finalInput, resultBlock);
     return resultBlock;
   }
   /**
@@ -7499,6 +7833,7 @@ var AgentLoop = class {
     let consecutiveErrors = 0;
     let completed = false;
     let overflowRetried = false;
+    const toolSnapshot = "snapshot" in this.tools ? this.tools.snapshot() : this.tools;
     while (step < this.maxSteps) {
       step++;
       const turnStartTime = Date.now();
@@ -7509,7 +7844,7 @@ var AgentLoop = class {
       let request = {
         systemPrompt: this.systemPrompt,
         messages: structuredClone(this.projectHistory?.(history) ?? history),
-        tools: visibleTools(this.tools.list(), this.getMode(), this.permissionRules).map(
+        tools: visibleTools(toolSnapshot.list(), this.getMode(), this.permissionRules).map(
           toToolDefinition
         ),
         signal: this.signal,
@@ -7518,7 +7853,30 @@ var AgentLoop = class {
       const beforeModelHooks = this.hooks.get("model:before");
       const hookCtx = { signal: this.signal };
       for (const hook of beforeModelHooks) {
-        request = await hook(hookCtx, request);
+        const modified = await hook(hookCtx, request);
+        if (modified) {
+          request = modified;
+        }
+      }
+      if (request.tools) {
+        for (const t of request.tools) {
+          const original = toolSnapshot.get(t.name);
+          if (!original) {
+            throw new ModelError(`Hook injected tool '${t.name}' not present in snapshot`, {
+              stage: "request",
+              retryable: false
+            });
+          }
+          if (t.description !== original.description || JSON.stringify(t.parameters) !== JSON.stringify(original.parameters)) {
+            throw new ModelError(
+              `Hook mutated tool definition for '${t.name}' (description or parameters drifted from snapshot)`,
+              {
+                stage: "request",
+                retryable: false
+              }
+            );
+          }
+        }
       }
       if (this.prepareRequest) request = yield* this.prepareRequest(request, history);
       yield {
@@ -8258,6 +8616,14 @@ var AgentSession = class {
     });
     this.plugins.push(plugin);
   }
+  /**
+   * 获取当前会话已成功挂载的扩展插件只读列表。
+   *
+   * 保证返回当前状态的独立切片，外部修改不污染内部挂载表。
+   */
+  getPlugins() {
+    return [...this.plugins];
+  }
   /**
    * 空闲时原子替换角色的模型绑定；本方法不改变当前角色或工具权限。
    * @param profile 模型协议、请求目标和输出预算。
@@ -8324,6 +8690,10 @@ var AgentSession = class {
   getMode() {
     return this.mode;
   }
+  /** 获取当前会话生效的权限规则列表。 */
+  getPermissionRules() {
+    return this.permissionRules;
+  }
   /** 返回最近一次成功装载的来源路径，不暴露指令正文。 */
   getInstructionSources() {
     return this.instructionSnapshot?.sources.map((source) => source.path) ?? [];
@@ -8452,8 +8822,23 @@ var AgentSession = class {
       options?.signal
     );
   }
+  /**
+   * 受控任务准备入口：在同一运行锁内异步准备文本块/来源，预算和存储成功后才进入模型。
+   *
+   * @param task 用户显式任务正文（或命令描述）。
+   * @param prepare 异步任务准备函数；在锁内执行，若准备失败或取消则释放锁且零 append。
+   * @param options 可选中止信号与显式主任务角色。
+   * @returns 结构化事件的异步流。
+   * @throws {SessionBusyError} 当前会话忙碌时抛出。
+   */
+  runPreparedTask(task, prepare, options) {
+    return cancellableGenerator(
+      (signal) => this.runOperation(task, { signal, role: options?.role }, void 0, prepare),
+      options?.signal
+    );
+  }
   /** 单次任务执行主体；调用方 return 的中止与 finally 清理由外层统一协调。 */
-  async *runOperation(userInput, options, skillName) {
+  async *runOperation(userInput, options, skillName, prepare) {
     this.assertIdle("start another run");
     const role = options?.role ?? this.primaryRole;
     const { profile, provider } = this.resolvePrimaryBinding(role);
@@ -8537,12 +8922,22 @@ var AgentSession = class {
         profile.contextWindow,
         profile.maxOutputTokens
       ).inputBudget;
+      const toolSnapshot = this.tools.snapshot();
+      let prepared;
+      if (prepare) {
+        prepared = await prepare({ signal: options?.signal, runId, tools: toolSnapshot });
+        if (options?.signal?.aborted) throw new AbortError();
+        if (prepared.skillName) skillName = prepared.skillName;
+      }
       await this.skillRegistry?.refresh(options?.signal);
       this.skillRuntime?.syncTools();
+      const extraPreparedTokens = prepared?.content ? typeof prepared.content === "string" ? estimateSkillTokens(prepared.content) : prepared.content.filter(isTextBlock).reduce((sum, b) => sum + estimateSkillTokens(b.text), 0) : 0;
       const promptAssembler = this.createPromptAssembler(
         profile,
         this.context.project(this.history),
-        32 + estimateSkillTokens(userInput)
+        32 + estimateSkillTokens(userInput) + extraPreparedTokens,
+        toolSnapshot.list(),
+        toolSnapshot
       );
       this.skillRuntime?.begin(
         runId,
@@ -8551,7 +8946,7 @@ var AgentSession = class {
           const current = {
             ...previousRequest ?? { systemPrompt: promptAssembler.assemble() },
             messages: [...this.context.project(this.history), ...budgetToolMessages],
-            tools: previousRequest?.tools ?? visibleTools(this.tools.list(), this.mode, this.permissionRules).map((tool) => ({
+            tools: previousRequest?.tools ?? visibleTools(toolSnapshot.list(), this.mode, this.permissionRules).map((tool) => ({
               name: tool.name,
               description: tool.description,
               parameters: tool.parameters
@@ -8559,7 +8954,7 @@ var AgentSession = class {
           };
           return Math.max(
             0,
-            inputBudget - (this.estimator ?? new UnicodeTokenEstimator()).estimate(current).total - (previousRequest ? 0 : estimateSkillTokens(userInput) + 32)
+            inputBudget - (this.estimator ?? new UnicodeTokenEstimator()).estimate(current).total - (previousRequest ? 0 : estimateSkillTokens(userInput) + extraPreparedTokens + 32)
           );
         },
         () => previousRequest?.messages ?? this.context.project(this.history)
@@ -8571,6 +8966,51 @@ var AgentSession = class {
         await this.authorizeSkill(skillName, runId, options?.signal);
         preparedSkill = await this.skillRuntime.prepare(skillName, "user", options?.signal);
       }
+      if (prepared?.verifyIdentity) {
+        const valid = await prepared.verifyIdentity();
+        if (!valid) {
+          throw new KapibalaError("Task preparation identity changed before commit", {
+            code: "MCP_PROMPT_CHANGED",
+            retryPolicy: "never"
+          });
+        }
+      }
+      const userContent = [{ type: "text", text: userInput }];
+      if (preparedSkill)
+        userContent.push({
+          type: "text",
+          text: preparedSkill.text,
+          skillSource: preparedSkill.source
+        });
+      if (prepared?.content) {
+        if (typeof prepared.content === "string") {
+          userContent.push({
+            type: "text",
+            text: prepared.content,
+            ...prepared.promptSource ? { promptSource: prepared.promptSource } : {}
+          });
+        } else {
+          userContent.push(...prepared.content);
+        }
+      }
+      const userMessage = {
+        id: createMessageId(),
+        interactionId: runId,
+        state: "completed",
+        role: "user",
+        content: userContent,
+        timestamp: Date.now()
+      };
+      const taskBudgetCheck = (this.estimator ?? new UnicodeTokenEstimator()).estimate({
+        systemPrompt: promptAssembler.assemble(),
+        messages: [userMessage]
+      }).total;
+      if (taskBudgetCheck > inputBudget) {
+        throw new ContextOverflowError(400, {
+          message: "Prepared task content exceeds context input budget",
+          stage: "request"
+        });
+      }
       this.totalTurns++;
       if (this.store && supportsSessionState(this.store)) {
         const currentProject = resolveSessionProject(this.cwd);
@@ -8584,24 +9024,39 @@ var AgentSession = class {
         });
       }
       runStarted = true;
-      const userMessage = {
-        id: createMessageId(),
-        interactionId: runId,
-        state: "completed",
-        role: "user",
-        content: [{ type: "text", text: userInput }],
-        timestamp: Date.now()
-      };
-      if (preparedSkill)
-        userMessage.content.push({
-          type: "text",
-          text: preparedSkill.text,
-          skillSource: preparedSkill.source
-        });
       if (this.store) {
         await this.store.append(userMessage);
       }
       this.history.push(userMessage);
+      if (prepared?.promptSource) {
+        const persistence = this.store ? "disk" : "memory";
+        yield {
+          type: "mcp_prompt_loaded",
+          server: prepared.promptSource.server,
+          name: prepared.promptSource.name,
+          persistence,
+          promptSource: prepared.promptSource,
+          runId
+        };
+        try {
+          await this.eventLogger.recordAudit({
+            level: "info",
+            event: "mcp.prompt_loaded",
+            sessionId: this.sessionId,
+            runId,
+            fields: {
+              server: prepared.promptSource.server,
+              promptName: prepared.promptSource.name,
+              contentDigest: prepared.promptSource.contentDigest,
+              persistence
+            }
+          });
+        } catch (auditErr) {
+          const msg = `MCP prompt audit recording failed: ${auditErr instanceof Error ? auditErr.message : String(auditErr)}`;
+          this.logger?.(msg);
+          this.onDiagnostic?.(msg);
+        }
+      }
       if (preparedSkill && this.skillRuntime) {
         this.skillRuntime.acceptUser(preparedSkill);
         for (const event of await this.commitSkills(runId)) yield event;
@@ -8612,7 +9067,7 @@ var AgentSession = class {
       const executor = new ToolExecutor({
         hardDenial: (tool) => this.skillRuntime?.denial(tool),
         onToolResult: (tool, _input, result) => this.skillRuntime?.acceptResult(tool, result),
-        tools: this.tools,
+        tools: toolSnapshot,
         hooks: this.hooks,
         rootDir: this.rootDir,
         signal: options?.signal,
@@ -8734,12 +9189,12 @@ var AgentSession = class {
           const skills = this.skillRuntime;
           const preparation = context.prepare(history, candidate, profile, runId, reason, !frozen);
           return (async function* () {
-            const prepared = yield* preparation;
-            skills?.assertProjection(prepared.messages);
-            previousRequest = structuredClone({ ...prepared, signal: void 0 });
+            const prepared2 = yield* preparation;
+            skills?.assertProjection(prepared2.messages);
+            previousRequest = structuredClone({ ...prepared2, signal: void 0 });
             lastPromptTokens = void 0;
             lastEstimatedPromptTokens = context.getSnapshot()?.estimate.total;
-            return prepared;
+            return prepared2;
           })();
         },
         onUsage: async (request, usage, attemptId) => {
@@ -8758,7 +9213,7 @@ var AgentSession = class {
         },
         provider,
         executor,
-        tools: this.tools,
+        tools: toolSnapshot,
         hooks: this.hooks,
         systemPrompt: assembledSystemPrompt,
         maxSteps: this.maxSteps,
@@ -8964,11 +9419,12 @@ var AgentSession = class {
     if (this.activeRun) throw new SessionBusyError(operation);
   }
   /** 实际请求、静态统计和手动压缩共用目录空间推导；先计正文、工具和非目录提示，再预算整段目录。 */
-  createPromptAssembler(profile, messages, extraTokens = 0) {
-    const tools = visibleTools(this.tools.list(), this.mode, this.permissionRules);
+  createPromptAssembler(profile, messages, extraTokens = 0, toolList, toolRegistry) {
+    const registry = toolRegistry ?? this.tools;
+    const tools = visibleTools(toolList ?? registry.list(), this.mode, this.permissionRules);
     const options = {
       skills: this.skillRegistry,
-      tools: this.tools,
+      tools: registry,
       rootDir: this.rootDir,
       customInstructions: this.customSystemPrompt,
       instructionSources: this.instructionSnapshot?.sources,
@@ -9268,6 +9724,7 @@ export {
   OpenAIResponsesProvider,
   PathSandbox,
   PermissionPolicy,
+  PreDispatchError,
   PromptAssembler,
   SESSION_SCHEMA_VERSION,
   SKILL_LIMITS,