aws-runtime-bridge 1.9.33 → 1.9.41

package/package/acode/dist/runtime.js

@@ -1,15 +1,23 @@
 import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { createBuiltInFileTools, } from "./built-in-file-tools.js";
+import { ASK_USER_QUESTION_TOOL_NAME, createAskUserQuestionTool, } from "./ask-user-question-tool.js";
+import { createSkillTool } from "./skill-tool.js";
+import { createTodoWriteTool, createTodoReadTool } from "./todo-tool.js";
+import { createSubAgentTools } from "./sub-agent-tools.js";
 import { cleanupAcodeCmdDist } from "./builtins/commandArtifacts.js";
 import { loadAcodeCommands } from "./commands/commandLoader.js";
 import { ACodeCommandRegistry } from "./commands/commandRegistry.js";
-import { loadAcodeConfig, loadAcodeSkills } from "./config.js";
+import { calculateCompactionThreshold, COMPACTION_LLM_PROMPT_TEMPLATE, conversationSizeKB, estimateConversationTokens, performCompaction, pruneToolOutputs, summarizeConversation, } from "./compaction.js";
+import { loadAcodeConfig, loadAcodeSkillGroup } from "./config.js";
 import { ACodeHookBus, findDeniedHookResult } from "./hooks/hookBus.js";
-import { isMcpPollingToolName } from "./mcpToolNames.js";
+import { isMcpPollingToolName, getSemanticToolName } from "./mcpToolNames.js";
 function cloneChatContentPart(part) {
     if (part.type === "text") {
         return { type: "text", text: part.text };
@@ -58,19 +66,94 @@ function normalizeText(value) {
     return text || undefined;
 }
 const DEFAULT_PROVIDER_REQUEST_TIMEOUT_MS = 60_000;
+/**
+ * 单次 provider 请求的总时长上限（毫秒）。默认 10 分钟。
+ * 超过该总预算即终止整个请求（含流式读取），不论是否仍在持续接收 chunk。
+ * 与 requestTimeoutMs（流式空闲超时 / 非流式分段超时）配合：只要每个 chunk 间隔不超过 60s，
+ * 但整体跑满 10min 仍会断开，避免长流式请求无限挂起。
+ * 0 = 不设总时长上限（仅靠 requestTimeoutMs 保护）。
+ */
+const DEFAULT_PROVIDER_REQUEST_TOTAL_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_PROVIDER_REQUEST_RETRY_COUNT = 2;
+/**
+ * 无限重试哨兵值：配置 requestRetryCount 为 -1 时，
+ * provider 请求在遇到可重试错误（超时/网络错误等）时无限重试，
+ * 直到请求成功、用户中止或会话终止。
+ * 启用后同时禁用总时长上限（requestTotalTimeoutMs 无效），
+ * 仅依靠单次请求超时（requestTimeoutMs）保护。
+ */
+const INFINITE_RETRY_SENTINEL = -1;
 const DEFAULT_PROVIDER_REQUEST_RETRY_DELAY_MS = 1000;
 const DEFAULT_MCP_TOOL_CALL_TIMEOUT_MS = 60_000;
 const DEFAULT_MCP_POLLING_TOOL_CALL_TIMEOUT_MS = 0;
 const MCP_SDK_MAX_SAFE_TIMEOUT_MS = 2_147_483_647;
+/**
+ * 子 agent 通过共享 MCP 连接允许调用的工具白名单。
+ * 与 aws-client-agent-mcp 的 MEMORY_TOOL_NAMES 保持一致，
+ * 防止子 agent 调用 poll_message/send_group 等与父 agent 冲突的工具。
+ */
+const SUB_AGENT_ALLOWED_MCP_TOOLS = new Set([
+    "create_memory",
+    "read_memory",
+    "update_memory",
+    "delete_memory",
+    "search_memory",
+    "list_memories",
+    "get_memory_stats",
+    "list_memories_by_file",
+    // Memory 过期回忆工具：memory_expiration 委托子 agent 需调用以整理过期记忆
+    "memory_recurrence",
+    "memory_recurrence_complete",
+]);
 const DEFAULT_BASH_BUILT_IN_TOOL_TIMEOUT_MS = 10 * 60_000 + 2000;
 const DEFAULT_RUNTIME_SHUTDOWN_TIMEOUT_MS = 10_000;
+/**
+ * 当 poll_message 返回的全部消息被 memory 自动委托处理后，重新 poll 前的等待间隔。
+ * 防止紧密循环：MCP doPollMessage 对 updating memory 每次都返回通知，
+ * 而 processMemoryAutoDelegates 因 URI 已在处理中而返回 null，
+ * 导致 while(true) 无延迟重 poll，引发状态快速跳动（思考→MCP→跳过）最终连接丢失。
+ */
+const DELEGATE_REPOLL_DELAY_MS = 5_000;
 const MAX_INLINE_IMAGE_BYTES = 10 * 1024 * 1024;
 const MAX_REQUEST_BODY_BYTES = 800 * 1024;
-const CONTEXT_COMPACTION_RECENT_MESSAGE_COUNT = 12;
-const CONTEXT_COMPACTION_MAX_SUMMARY_CHARS = 6000;
-const CONTEXT_COMPACTION_MAX_PREVIEW_CHARS = 500;
-const CONTEXT_COMPACTION_SUMMARY_PREFIX = "ACode context compaction summary:";
+/**
+ * 上下文压缩调试日志开关：仅当设置环境变量 ACODE_COMPACTION_DEBUG=1 时启用。
+ * 默认关闭，避免生产环境同步写盘阻塞事件循环。
+ */
+const COMPACTION_DEBUG_ENABLED = process.env.ACODE_COMPACTION_DEBUG === "1";
+const COMPACTION_DEBUG_LOG = COMPACTION_DEBUG_ENABLED
+    ? path.join(os.tmpdir(), "acode-compaction-debug.log")
+    : "";
+/**
+ * Runtime 调试日志：受 ACODE_COMPACTION_DEBUG=1 开关控制。
+ * 默认关闭以避免生产环境同步写盘阻塞事件循环、泄漏用户消息内容。
+ * 文件中所有原 `console.log` 调用均改为走此 helper。
+ */
+function runtimeDebugLog(...args) {
+    if (!COMPACTION_DEBUG_ENABLED)
+        return;
+    console.log(...args);
+}
+/** 当 provider 未配置 contextLimit 时使用的默认值 */
+const FALLBACK_CONTEXT_LIMIT = 64_000;
+/**
+ * 解析 provider 的压缩配置，返回实际用于触发压缩的 contextLimit/maxOutput/inputLimit/threshold。
+ * 供 session_started 事件、startCompactionDebugLog、requestChatCompletion 共用，
+ * 确保前端显示的压缩点与后端实际触发阈值完全一致（消除前端自算公式的脱节）。
+ */
+function resolveCompactionConfig(provider) {
+    const contextLimit = (provider.contextLimit && provider.contextLimit > 0)
+        ? provider.contextLimit
+        : FALLBACK_CONTEXT_LIMIT;
+    const maxOutput = (provider.maxOutput && provider.maxOutput > 0)
+        ? provider.maxOutput
+        : 8_192;
+    const inputLimit = (provider.inputLimit && provider.inputLimit > 0)
+        ? provider.inputLimit
+        : undefined;
+    const threshold = calculateCompactionThreshold(contextLimit, maxOutput, inputLimit);
+    return { contextLimit, maxOutput, inputLimit, threshold };
+}
 async function withTimeout(operation, timeoutMs, label, onTimeout) {
     if (timeoutMs <= 0) {
         return await operation;
@@ -104,6 +187,10 @@ function normalizeNonNegativeInteger(value, fallback) {
         return 0;
     }
     const numeric = typeof value === "number" ? value : Number(value);
+    // -1 是无限重试哨兵值，直接透传
+    if (numeric === INFINITE_RETRY_SENTINEL) {
+        return INFINITE_RETRY_SENTINEL;
+    }
     return Number.isFinite(numeric) && numeric > 0
         ? Math.floor(numeric)
         : fallback;
@@ -145,6 +232,18 @@ function estimateContextTokens(systemPrompt, exposedTools) {
     }
     return Math.ceil(charCount / ESTIMATED_CHARS_PER_TOKEN);
 }
+/**
+ * 估算 exposedTools 定义的 token 开销。
+ * tools 的 JSON schema（函数名、描述、参数定义）会被序列化进请求体，
+ * 占用可观 token 数（十几个工具可达数千 tokens），必须计入上下文估算。
+ * 否则 estimateConversationTokens 系统性偏低，导致主动压缩阈值无法触达。
+ */
+function estimateToolsTokens(exposedTools) {
+    if (exposedTools.length === 0)
+        return 0;
+    const toolsJson = JSON.stringify(toOpenAiTools(exposedTools));
+    return estimateTokensFromText(toolsJson);
+}
 async function delay(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -172,6 +271,36 @@ function modelSupportsImageInput(model, defaultProvider, providerOptions) {
  * 解析 ACode 当前会话模型：优先显式启动参数，其次兼容 cc-switch 写入的
  * OpenCode-style `provider.default.model`，最后回落到旧版 top-level model。
  */
+/**
+ * 按优先级从 provider 配置中查找字段值：
+ *   1. options.*（通用配置）
+ *   2. models.<currentModel>.*（当前模型专属配置，面板初始化写入的位置）
+ *   3. provider.*（provider 级别兜底）
+ *
+ * @param optionsValue  providerOptions 上的值（已取出）
+ * @param defaultProvider  provider.default 对象
+ * @param currentModel  当前使用的模型名
+ * @param fieldName     要查找的字段名（如 "contextLimit"）
+ */
+function resolveProviderConfigValue(optionsValue, defaultProvider, currentModel, fieldName) {
+    // 1. options 级别优先
+    if (optionsValue !== undefined)
+        return optionsValue;
+    if (!defaultProvider)
+        return undefined;
+    // 2. models.<modelName>.<fieldName>
+    const models = defaultProvider.models;
+    if (isRecord(models)) {
+        const modelConfig = models[currentModel];
+        if (isRecord(modelConfig)) {
+            const modelValue = modelConfig[fieldName];
+            if (modelValue !== undefined)
+                return modelValue;
+        }
+    }
+    // 3. provider 级别兜底
+    return defaultProvider[fieldName];
+}
 function resolveProviderConfig(config, acodeConfig) {
     const defaultProvider = acodeConfig.provider?.default;
     const providerOptions = defaultProvider?.options;
@@ -179,17 +308,36 @@ function resolveProviderConfig(config, acodeConfig) {
         defaultProvider?.model ||
         acodeConfig.model ||
         "acode-default";
+    // effort 优先级：runtime config (per-session/per-instance) > provider options (acode.json) > provider default
+    const effort = normalizeText(config.effort) ||
+        normalizeText(providerOptions?.effort) ||
+        normalizeText(defaultProvider?.effort) ||
+        undefined;
     return {
         model,
         baseURL: normalizeText(providerOptions?.baseURL || providerOptions?.baseUrl),
         apiKey: normalizeText(providerOptions?.apiKey),
+        effort,
         systemPrompt: config.systemPrompt || acodeConfig.systemPrompt,
         stream: providerOptions?.stream !== false,
-        requestTimeoutMs: normalizeNonNegativeInteger(providerOptions?.requestTimeoutMs ?? providerOptions?.timeoutMs, DEFAULT_PROVIDER_REQUEST_TIMEOUT_MS),
+        // ★ 安全修复：使用 normalizePositiveInteger 禁止设为 0，
+        //   0 会导致 withTimeout 直接返回 operation（禁用超时），
+        //   fetch 挂起时请求永久不返回，agent 死锁。
+        requestTimeoutMs: normalizePositiveInteger(providerOptions?.requestTimeoutMs ?? providerOptions?.timeoutMs, DEFAULT_PROVIDER_REQUEST_TIMEOUT_MS),
+        requestTotalTimeoutMs: normalizePositiveInteger(providerOptions?.requestTotalTimeoutMs, DEFAULT_PROVIDER_REQUEST_TOTAL_TIMEOUT_MS),
         requestRetryCount: normalizeNonNegativeInteger(providerOptions?.requestRetryCount, DEFAULT_PROVIDER_REQUEST_RETRY_COUNT),
         mcpToolTimeoutMs: normalizePositiveInteger(providerOptions?.mcpToolTimeoutMs, DEFAULT_MCP_TOOL_CALL_TIMEOUT_MS),
         mcpPollingToolTimeoutMs: normalizeNonNegativeInteger(providerOptions?.mcpPollingToolTimeoutMs, DEFAULT_MCP_POLLING_TOOL_CALL_TIMEOUT_MS),
         supportsImageInput: modelSupportsImageInput(model, defaultProvider, providerOptions),
+        // ★ 从 provider 配置中读取 contextLimit/inputLimit/maxOutput，
+        //    requestChatCompletion 和 startCompactionDebugLog 使用这些值计算压缩触发阈值。
+        //    按优先级查找三个位置：
+        //      1. provider.default.options.*（options 级别，通用配置）
+        //      2. provider.default.models.<modelName>.*（模型级别，面板初始化写入的位置）
+        //      3. provider.default.*（provider 级别兜底）
+        contextLimit: normalizeNonNegativeInteger(resolveProviderConfigValue(providerOptions?.contextLimit, defaultProvider, model, "contextLimit"), 0) || undefined,
+        inputLimit: normalizeNonNegativeInteger(resolveProviderConfigValue(providerOptions?.inputLimit, defaultProvider, model, "inputLimit"), 0) || undefined,
+        maxOutput: normalizeNonNegativeInteger(resolveProviderConfigValue(providerOptions?.maxOutput, defaultProvider, model, "maxOutput"), 0) || undefined,
     };
 }
 function appendTextPart(parts, text) {
@@ -393,38 +541,6 @@ function contentPreview(content) {
         .join(" ")
         .trim();
 }
-function truncateText(value, maxChars) {
-    if (value.length <= maxChars) {
-        return value;
-    }
-    return `${value.slice(0, maxChars)}…`;
-}
-function summarizeToolCalls(toolCalls) {
-    if (!toolCalls || toolCalls.length === 0) {
-        return "";
-    }
-    return toolCalls
-        .map((toolCall) => {
-        const args = truncateText(toolCall.function.arguments.replace(/\s+/g, " ").trim(), 160);
-        return `${toolCall.function.name}(${args})`;
-    })
-        .join(", ");
-}
-function summarizeConversationMessage(message, index) {
-    const preview = truncateText(contentPreview(message.content).replace(/\s+/g, " ").trim(), CONTEXT_COMPACTION_MAX_PREVIEW_CHARS);
-    const toolCalls = summarizeToolCalls(message.tool_calls);
-    const parts = [`${index + 1}. ${message.role}`];
-    if (toolCalls) {
-        parts.push(`tool_calls=${toolCalls}`);
-    }
-    if (message.tool_call_id) {
-        parts.push(`tool_call_id=${message.tool_call_id}`);
-    }
-    if (preview) {
-        parts.push(`content=${preview}`);
-    }
-    return parts.join(" | ");
-}
 /**
  * 解析 ACode 工具权限配置。
  * 主流程：运行时配置优先 -> `.acode/config.json` 次之 -> 兼容旧式 allowedTools/deniedTools 字段。
@@ -530,6 +646,16 @@ function coerceArguments(rawArguments) {
     }
 }
 function getBuiltInToolTimeoutMs(tool, args, fallbackTimeoutMs) {
+    // 阻塞等待型工具不受超时限制：
+    // - ask_user_question: 阻塞等待用户回答
+    // - await_sub_agents: 永久阻塞等待指定子 agent 数组到达终态
+    const BLOCKING_BUILT_IN_TOOL_NAMES = new Set([
+        ASK_USER_QUESTION_TOOL_NAME,
+        "await_sub_agents",
+    ]);
+    if (BLOCKING_BUILT_IN_TOOL_NAMES.has(tool.toolName)) {
+        return 0;
+    }
     if (tool.toolName !== "Bash") {
         return fallbackTimeoutMs;
     }
@@ -594,12 +720,16 @@ function estimateMessageSizeBytes(message) {
     }
     return size;
 }
-function isContextCompactionSummaryMessage(message) {
-    return (message.role === "system" &&
-        typeof message.content === "string" &&
-        message.content.startsWith(CONTEXT_COMPACTION_SUMMARY_PREFIX));
-}
-function truncateConversationIfNeeded(conversation, maxBytes) {
+/**
+ * 按字节大小截断对话，防止 HTTP 请求体过大。
+ * 这是与 token 压缩不同的关注点：即使 token 在上下文窗口内，
+ * HTTP 请求体也可能因 base64 图片等内容超过网关限制。
+ * 使用 compaction 模块的 performCompaction 进行压缩。
+ *
+ * ★ 支持 LLM 摘要器（与 performCompaction 一致）：
+ *   若提供 llmSummarizer，则 summarize 阶段使用 LLM 生成语义化摘要。
+ */
+async function truncateConversationIfNeeded(conversation, maxBytes, contextLimit, maxOutput, llmSummarizer) {
     let totalBytes = 0;
     for (const message of conversation) {
         totalBytes += estimateMessageSizeBytes(message);
@@ -607,52 +737,14 @@ function truncateConversationIfNeeded(conversation, maxBytes) {
     if (totalBytes <= maxBytes) {
         return 0;
     }
-    return compactConversationForRequestLimit(conversation, maxBytes);
-}
-function compactConversationForRequestLimit(conversation, maxBytes) {
-    const baseSystemMessages = conversation.filter((m) => m.role === "system" && !isContextCompactionSummaryMessage(m));
-    const compactableMessages = conversation.filter((m) => m.role !== "system" || isContextCompactionSummaryMessage(m));
-    const keptMessages = [];
-    let keptBytes = baseSystemMessages.reduce((sum, m) => sum + estimateMessageSizeBytes(m), 0);
-    for (let i = compactableMessages.length - 1; i >= 0; i--) {
-        const messageSize = estimateMessageSizeBytes(compactableMessages[i]);
-        if (keptBytes + messageSize > maxBytes && keptMessages.length > 0) {
-            break;
-        }
-        keptBytes += messageSize;
-        keptMessages.unshift(compactableMessages[i]);
-    }
-    return compactConversationWithSummary(conversation, compactableMessages.length - keptMessages.length);
-}
-function compactConversationForContextOverflow(conversation) {
-    const compactableMessages = conversation.filter((m) => m.role !== "system" || isContextCompactionSummaryMessage(m));
-    const removableCount = Math.max(0, compactableMessages.length - CONTEXT_COMPACTION_RECENT_MESSAGE_COUNT);
-    return compactConversationWithSummary(conversation, removableCount);
-}
-function compactConversationWithSummary(conversation, requestedRemovedCount) {
-    const baseSystemMessages = conversation.filter((m) => m.role === "system" && !isContextCompactionSummaryMessage(m));
-    const compactableMessages = conversation.filter((m) => m.role !== "system" || isContextCompactionSummaryMessage(m));
-    const removedCount = Math.max(0, Math.min(requestedRemovedCount, compactableMessages.length));
-    if (removedCount === 0) {
-        return 0;
-    }
-    const removedMessages = compactableMessages.slice(0, removedCount);
-    const keptMessages = compactableMessages.slice(removedCount);
-    const summaryLines = removedMessages.map((message, index) => summarizeConversationMessage(message, index));
-    const summary = truncateText(summaryLines.join("\n"), CONTEXT_COMPACTION_MAX_SUMMARY_CHARS);
-    conversation.length = 0;
-    conversation.push(...baseSystemMessages);
-    conversation.push({
-        role: "system",
-        content: [
-            CONTEXT_COMPACTION_SUMMARY_PREFIX,
-            `${removedCount} earlier compactable conversation messages were summarized to keep the provider request within context limits.`,
-            "Preserve the user's goal, decisions, tool results, file paths, errors, and unresolved tasks from this summary. Recent messages below remain authoritative.",
-            summary,
-        ].join("\n"),
+    const result = await performCompaction(conversation, contextLimit, maxOutput, {
+        llmSummarizer,
     });
-    conversation.push(...keptMessages);
-    return removedCount;
+    if (result.strategy !== "none") {
+        return result.prunedToolMessages + result.summarizedMessages;
+    }
+    // performCompaction 未生效时，强制 summarize
+    return summarizeConversation(conversation, { llmSummarizer, contextLimit });
 }
 function isContextOverflowProviderRequestError(error) {
     const message = getErrorMessage(error).toLowerCase();
@@ -742,10 +834,10 @@ function buildSkillPrompt(skills) {
         return "";
     }
     return [
-        "Available skills:",
-        ...skills.map((skill) => `- ${skill.name}${skill.description ? `: ${skill.description}` : ""}`),
-        "Use these skills as guidance when they match the user task.",
-    ].join("\n");
+        "Skills are available for this session.",
+        "Use the `skill` tool to load specialized skill instructions when a user task matches one of the available skills listed in the tool description.",
+        "Do not attempt to follow skill instructions from memory — always invoke the `skill` tool first to load the full content.",
+    ].join(" ");
 }
 function buildCommandPrompt(commands) {
     if (commands.length === 0) {
@@ -757,6 +849,49 @@ function buildCommandPrompt(commands) {
         "When the user invokes a slash command, ACode expands it before model execution.",
     ].join("\n");
 }
+/**
+ * 格式化 profile 信息为文本，供 rolePrompt 拼接使用。
+ * 主流程：提取关键字段并格式化为可读文本，返回空字符串当 profile 为空。
+ */
+function buildProfilePrompt(profile) {
+    if (!profile || typeof profile !== "object") {
+        return "";
+    }
+    const p = profile;
+    const parts = [];
+    const displayName = p.displayName;
+    const roleName = p.roleName;
+    const instanceName = p.instanceName;
+    const projectName = p.projectName;
+    const workspacePath = p.workspacePath;
+    const runtimeMode = p.runtimeMode;
+    const describe = p.describe;
+    if (typeof displayName === "string" && displayName.trim()) {
+        parts.push(`Display Name: ${displayName.trim()}`);
+    }
+    if (typeof roleName === "string" && roleName.trim()) {
+        parts.push(`Role: ${roleName.trim()}`);
+    }
+    if (typeof instanceName === "string" && instanceName.trim()) {
+        parts.push(`Instance: ${instanceName.trim()}`);
+    }
+    if (typeof projectName === "string" && projectName.trim()) {
+        parts.push(`Project: ${projectName.trim()}`);
+    }
+    if (typeof workspacePath === "string" && workspacePath.trim()) {
+        parts.push(`Workspace: ${workspacePath.trim()}`);
+    }
+    if (typeof runtimeMode === "string" && runtimeMode.trim()) {
+        parts.push(`Runtime Mode: ${runtimeMode.trim()}`);
+    }
+    if (typeof describe === "string" && describe.trim()) {
+        parts.push(`Description: ${describe.trim()}`);
+    }
+    if (parts.length === 0) {
+        return "";
+    }
+    return ["[User Profile]", ...parts].join("\n");
+}
 function toOpenAiTools(tools) {
     return tools.map((tool) => ({
         type: "function",
@@ -843,6 +978,7 @@ export class ACodeRuntime extends EventEmitter {
                 model: "acode-default",
                 stream: false,
                 requestTimeoutMs: DEFAULT_PROVIDER_REQUEST_TIMEOUT_MS,
+                requestTotalTimeoutMs: DEFAULT_PROVIDER_REQUEST_TOTAL_TIMEOUT_MS,
                 requestRetryCount: DEFAULT_PROVIDER_REQUEST_RETRY_COUNT,
                 mcpToolTimeoutMs: DEFAULT_MCP_TOOL_CALL_TIMEOUT_MS,
                 mcpPollingToolTimeoutMs: DEFAULT_MCP_POLLING_TOOL_CALL_TIMEOUT_MS,
@@ -850,18 +986,41 @@ export class ACodeRuntime extends EventEmitter {
             },
             permissions: { mode: "default", allow: [], deny: [] },
             mcpConnections: [],
+            ownsMcpConnections: true,
             exposedTools: [],
             commands: [],
             commandRegistry: new ACodeCommandRegistry([]),
             conversation: [],
+            accumulatedInputTokens: 0,
+            accumulatedOutputTokens: 0,
         };
         this.abortController = null;
+        /**
+         * 正在处理中的 memory 子 agent 跟踪表。
+         * key = memory URI，value = subId（用于防止同一 memory 被重复委托）。
+         * 子 agent 完成后通过 SubAgentManager 事件回调移除对应 URI。
+         */
+        this.pendingMemorySubAgents = new Map();
         this.submitQueue = Promise.resolve();
         this.activeTurn = false;
         this.abortRequested = false;
         this.sessionCompleteEmitted = false;
         this.contextVersion = 0;
         this.stopWaiters = new Set();
+        /** 上下文压缩调试定时器（每 5 秒输出一次） */
+        this.compactionDebugTimer = null;
+        /** 可动态刷新的 SkillTool 引用（含 refresh 方法），运行中变更时调用其 refresh */
+        this.skillTool = null;
+        /** 监听 skills 目录变更的 FSWatcher 列表 */
+        this.skillWatchers = [];
+        /** skill 目录变更后的防抖定时器，避免短时间多次触发重扫 */
+        this.skillRefreshTimer = null;
+        /**
+         * ask_user_question 工具的挂起等待队列。
+         * key: toolCallId；value: resolve/reject 回调 + 创建时的 contextVersion。
+         * submitQuestionAnswer() 调用时 resolve；abort/stop/supersede 时 reject。
+         */
+        this.questionWaiters = new Map();
         this.hookBus = new ACodeHookBus({
             sessionId: config.sessionId,
             onError: (event, error) => {
@@ -874,6 +1033,10 @@ export class ACodeRuntime extends EventEmitter {
             this.hookBus.register(handler);
         }
     }
+    /** 获取当前已暴露的工具名称列表（供 SubAgentManager 记录） */
+    getAvailableTools() {
+        return this.state.exposedTools.map((tool) => tool.exposedName);
+    }
     emitAcodeEvent(type, data) {
         const event = {
             type,
@@ -883,6 +1046,44 @@ export class ACodeRuntime extends EventEmitter {
         };
         this.emit("event", event);
     }
+    /**
+     * 发射压缩子事件（phase 事件）到面板时间线。
+     * 子事件通过 parentId 关联到父压缩事件，在前端以嵌套子元素形式展示。
+     *
+     * @param compactionId 父压缩事件 ID
+     * @param phase 阶段标识（detect/prune/prune_done/summarize/summarize_done）
+     * @param phaseLabel 阶段显示标签（如"阶段1: 裁剪工具输出"）
+     * @param phaseDetail 阶段详情（如"裁剪了 5 条工具输出"）
+     */
+    emitCompactionPhase(compactionId, phase, phaseLabel, phaseDetail) {
+        this.emitAcodeEvent("context_compaction", {
+            action: "phase",
+            compactionId,
+            parentId: compactionId,
+            phase,
+            phaseLabel,
+            phaseDetail,
+        });
+    }
+    /**
+     * performCompaction 的 onPhase 回调处理：将 CompactionPhaseEvent 转换为面板子事件。
+     */
+    handleCompactionPhase(compactionId, event) {
+        switch (event.phase) {
+            case "prune_start":
+                this.emitCompactionPhase(compactionId, "prune", "阶段1: 裁剪工具输出", `正在裁剪 ${event.messageCount ?? 0} 条消息中的工具输出...`);
+                break;
+            case "prune_end":
+                this.emitCompactionPhase(compactionId, "prune_done", "阶段1: 裁剪工具输出", `裁剪了 ${event.prunedCount ?? 0} 条工具输出, 释放 ${event.freedTokens ?? 0} tokens`);
+                break;
+            case "summarize_start":
+                this.emitCompactionPhase(compactionId, "summarize", "阶段2: 摘要化对话", `正在摘要 ${event.messageCount ?? 0} 条早期对话...`);
+                break;
+            case "summarize_end":
+                this.emitCompactionPhase(compactionId, "summarize_done", "阶段2: 摘要化对话", `摘要化了 ${event.summarizedCount ?? 0} 条消息${event.usedLLM ? " (LLM 摘要)" : " (规则摘要)"}`);
+                break;
+        }
+    }
     /**
      * 启动 ACode headless 会话。
      * 主流程：加载 `.acode/config.json` 与 skills 目录 -> 发出 MCP/Skill 状态 ->
@@ -890,20 +1091,48 @@ export class ACodeRuntime extends EventEmitter {
      */
     async start() {
         const acodeConfig = await loadAcodeConfig(this.config.configPath);
-        const skills = await loadAcodeSkills(this.config.skillsDir);
+        // Skills 来源（按优先级，后加载的覆盖先加载的同名 skill）：
+        //   1. 全局目录（~/.acode/skills，由 config.skillsDir 指定）
+        //   2. 项目目录（<workingDirectory>/.acode/skills）
+        //   3. 项目目录（<workingDirectory>/.agentswork/skills）
+        // 各目录的 skills 合并后供 SkillTool / prompt 使用；分组信息供前端按目录展示。
+        // 即使目录不存在也会作为空节点返回，前端按目录展示。
+        const { skills, skillGroups, watchedDirs } = await this.loadAllSkills();
         const provider = resolveProviderConfig(this.config, acodeConfig);
         // [DEBUG] ACode Runtime 最终解析的 provider 配置（写入 stdout，bridge 会捕获）
-        console.log(`[ACodeRuntime] ★★★ DEBUG ★★★ resolveProviderConfig 结果: config.model=${this.config.model ?? "(undefined)"}, ` +
+        runtimeDebugLog(`[ACodeRuntime] ★★★ DEBUG ★★★ resolveProviderConfig 结果: config.model=${this.config.model ?? "(undefined)"}, ` +
             `resolvedModel=${provider.model}, baseURL=${provider.baseURL ?? "(none)"}, apiKey=${provider.apiKey ? "[set]" : "(none)"}, ` +
             `configPath=${this.config.configPath ?? "(none)"}`);
         const permissions = resolvePermissionConfig(this.config, acodeConfig);
-        const mcpConnections = await this.connectMcpServers(acodeConfig.mcpServers ?? {}, provider.mcpToolTimeoutMs);
+        // 子 agent 复用父 agent 的 MCP 连接，避免启动新 MCP server 进程后 401
+        // 共享连接时只暴露 memory 工具，防止子 agent 调用 poll_message/send_group 等
+        // 与父 agent 冲突的工具（原设计通过 AWS_SUB_AGENT=true 限制，共享连接绕过了该机制）
+        const mcpConnections = this.config.sharedMcpConnections
+            ? this.filterSharedMcpConnectionsForSubAgent(this.config.sharedMcpConnections)
+            : await this.connectMcpServers(acodeConfig.mcpServers ?? {}, provider.mcpToolTimeoutMs);
+        const ownsMcpConnections = !this.config.sharedMcpConnections;
+        // 获取用户 profile 信息并拼接在 rolePrompt 下方
+        const profilePrompt = await this.fetchProfilePrompt(mcpConnections);
         const agentId = this.config.agentId || "unknown";
         // 重启时清理旧 spillover 输出
         void cleanupAcodeCmdDist(agentId);
         const builtInTools = createBuiltInFileTools(this.config.workingDirectory, agentId);
+        const askUserQuestionTool = createAskUserQuestionTool(this.buildAskUserQuestionDeps(), () => this.contextVersion);
+        const skillTool = createSkillTool(skills);
+        this.skillTool = skillTool;
+        const todoWriteTool = createTodoWriteTool(agentId);
+        const todoReadTool = createTodoReadTool(agentId);
+        // 注册 sub-agent 工具集（仅当注入了 subAgentManager）
+        const subAgentTools = this.config.subAgentManager
+            ? createSubAgentTools(this.buildSubAgentToolDeps(this.config.subAgentManager))
+            : [];
         const exposedTools = [
             ...builtInTools,
+            askUserQuestionTool,
+            skillTool,
+            todoWriteTool,
+            todoReadTool,
+            ...subAgentTools,
             ...mcpConnections.flatMap((connection) => connection.tools),
         ];
         const commandDirs = this.resolveCommandDirs(acodeConfig);
@@ -922,9 +1151,14 @@ export class ACodeRuntime extends EventEmitter {
             .join("\n\n");
         // 辅助函数：将非空文本构造为 system role 消息，消除重复的 spread+ternary 模式
         const makeSystem = (content) => content?.trim() ? [{ role: 'system', content: content.trim() }] : [];
+        // 将 rolePrompt 与 profilePrompt 合并为第二条 system 消息
+        const roleWithProfile = [this.config.rolePrompt, profilePrompt]
+            .map((item) => item?.trim())
+            .filter((item) => Boolean(item))
+            .join("\n\n");
         const initialConversation = [
             ...makeSystem(this.config.globalPrompt),
-            ...makeSystem(this.config.rolePrompt),
+            ...makeSystem(roleWithProfile),
             ...makeSystem(this.config.memory),
             ...(runtimePrompt ? [{ role: 'system', content: runtimePrompt }] : []),
         ];
@@ -941,21 +1175,35 @@ export class ACodeRuntime extends EventEmitter {
             provider,
             permissions,
             mcpConnections,
+            ownsMcpConnections,
             exposedTools,
             commands,
             commandRegistry,
             conversation: cloneChatConversation(initialConversation),
+            accumulatedInputTokens: 0,
+            accumulatedOutputTokens: 0,
         };
         await this.hookBus.dispatch("SessionStart", {
             workingDirectory: this.config.workingDirectory,
             model: provider.model,
             commandCount: commands.length,
         });
+        // ★ emit 实际用于触发压缩的配置，前端 AgentContextPanel 直接显示此阈值，
+        //   消除前端自算公式与后端实际触发阈值（min(动态比例, hardLimit-reserved)）的脱节。
+        //   注意：此处的 contextLimit/maxOutput/inputLimit 来自 resolveProviderConfig（读 provider.default.* 三级），
+        //   与 adapter 的 totalUsage.contextLimit（读顶层+查表）可能不同源——前端应以这里 emit 的值为准。
+        const compactionConfig = resolveCompactionConfig(provider);
         this.emitAcodeEvent("session_started", {
             workingDirectory: this.config.workingDirectory,
             model: provider.model,
             commandCount: commands.length,
             estimatedContextTokens: estimateContextTokens(systemMessagesPlainText, exposedTools),
+            contextLimit: compactionConfig.contextLimit,
+            maxOutput: compactionConfig.maxOutput,
+            ...(compactionConfig.inputLimit !== undefined
+                ? { inputLimit: compactionConfig.inputLimit }
+                : {}),
+            compactionThreshold: compactionConfig.threshold,
         });
         this.emitAcodeEvent("mcp_status", {
             configPath: this.config.configPath,
@@ -972,6 +1220,7 @@ export class ACodeRuntime extends EventEmitter {
                 source: tool.kind === "mcp"
                     ? `${tool.serverName}.${tool.toolName}`
                     : `builtin.${tool.toolName}`,
+                description: tool.description || "",
             })),
         });
         this.emitAcodeEvent("skill_status", {
@@ -980,6 +1229,16 @@ export class ACodeRuntime extends EventEmitter {
             skills: skills.map((skill) => ({
                 name: skill.name,
                 description: skill.description,
+                directory: skill.directory,
+            })),
+            skillGroups: skillGroups.map((group) => ({
+                dir: group.dir,
+                exists: group.exists,
+                skills: group.skills.map((skill) => ({
+                    name: skill.name,
+                    description: skill.description,
+                    directory: skill.directory,
+                })),
             })),
         });
         this.emitAcodeEvent("command_status", {
@@ -994,6 +1253,226 @@ export class ACodeRuntime extends EventEmitter {
         if (this.config.initialPrompt) {
             await this.submit(this.config.initialPrompt);
         }
+        // 启动上下文压缩调试日志（仅当 ACODE_COMPACTION_DEBUG=1 时启用）
+        this.startCompactionDebugLog();
+        // 启动 skills 目录监听，运行中变更会触发重扫并刷新 SkillTool + 重发 skill_status
+        this.startSkillWatchers(watchedDirs);
+    }
+    /**
+     * 加载所有 skills 来源目录并合并。
+     *
+     * 三个来源（按优先级，后加载的覆盖先加载的同名 skill）：
+     *   1. 全局目录（~/.acode/skills，由 config.skillsDir 指定）
+     *   2. 项目目录（<workingDirectory>/.acode/skills）
+     *   3. 项目目录（<workingDirectory>/.agentswork/skills）
+     *
+     * 返回合并后的 skills 列表、按目录分组的 skillGroups，以及需要监听的目录列表
+     * （已去重、规范化）。watchedDirs 用于启动 fs.watch 监听运行时变更。
+     */
+    async loadAllSkills() {
+        const globalSkillsDir = this.config.skillsDir ?? "";
+        const projectAcodeSkillsDir = path.join(this.config.workingDirectory, ".acode", "skills");
+        const projectAgentsworkSkillsDir = path.join(this.config.workingDirectory, ".agentswork", "skills");
+        // 按规范化路径去重，避免全局目录与项目目录路径相同时重复加载
+        const seenDirs = new Set();
+        const skillGroups = [];
+        const watchedDirs = [];
+        for (const dir of [globalSkillsDir, projectAcodeSkillsDir, projectAgentsworkSkillsDir]) {
+            if (!dir)
+                continue;
+            const normalized = path.resolve(dir);
+            if (seenDirs.has(normalized))
+                continue;
+            seenDirs.add(normalized);
+            skillGroups.push(await loadAcodeSkillGroup(dir));
+            // 即使目录不存在也加入监听列表：fs.watch 会失败但被静默忽略，
+            // 这样用户后续创建该目录时（如果父目录存在）能通过其他途径感知。
+            // 实际上 fs.watch 不存在的路径会抛错，所以这里只加入存在的目录。
+            try {
+                await fs.promises.access(normalized);
+                watchedDirs.push(normalized);
+            }
+            catch {
+                // 目录不存在，跳过监听
+            }
+        }
+        // 合并各目录 skills，按 name 去重（项目优先覆盖全局）
+        const skillsByName = new Map();
+        for (const group of skillGroups) {
+            for (const skill of group.skills) {
+                skillsByName.set(skill.name, skill);
+            }
+        }
+        const skills = [...skillsByName.values()];
+        return { skills, skillGroups, watchedDirs };
+    }
+    /**
+     * 启动 fs.watch 监听 skills 目录变更。
+     *
+     * 使用 recursive: true（Windows/macOS 原生支持，Linux 在 Node 19+ 支持）。
+     * Linux 旧版本不支持时会抛 ERR_FEATURE_UNAVAILABLE，fallback 到非 recursive
+     * 监听顶层目录（只能感知 skill 子目录的新增/删除，无法感知 SKILL.md 内容修改）。
+     *
+     * 变更事件经防抖后触发 refreshSkills()，重新扫描目录、刷新 SkillTool、重发 skill_status。
+     */
+    startSkillWatchers(dirs) {
+        for (const dir of dirs) {
+            let watcher = null;
+            try {
+                watcher = fs.watch(dir, { recursive: true }, () => {
+                    this.scheduleSkillRefresh();
+                });
+            }
+            catch {
+                // recursive 在当前平台不支持（如 Linux 旧版本），fallback 到非 recursive
+                try {
+                    watcher = fs.watch(dir, () => {
+                        this.scheduleSkillRefresh();
+                    });
+                }
+                catch {
+                    // 监听失败（如权限问题），跳过该目录
+                    continue;
+                }
+            }
+            if (watcher) {
+                watcher.on("error", () => {
+                    // 静默处理 watcher 错误（如目录被删除），避免未捕获异常
+                });
+                this.skillWatchers.push(watcher);
+            }
+        }
+    }
+    /**
+     * 防抖调度 skill 重扫。短时间内多次变更事件只触发一次重扫。
+     */
+    scheduleSkillRefresh() {
+        if (this.skillRefreshTimer) {
+            clearTimeout(this.skillRefreshTimer);
+        }
+        this.skillRefreshTimer = setTimeout(() => {
+            this.skillRefreshTimer = null;
+            void this.refreshSkills();
+        }, ACodeRuntime.SKILL_REFRESH_DEBOUNCE_MS);
+    }
+    /**
+     * 重新扫描 skills 目录并刷新 SkillTool 与 state。
+     *
+     * 调用时机：fs.watch 监听到目录变更后（经防抖）。
+     * 副作用：
+     *   - 更新 this.skillTool 的内部 Map 与工具描述（让下一轮 turn 的 LLM 感知新 skill）
+     *   - 更新 this.state.skills（影响 fallback 响应等）
+     *   - 重发 skill_status 事件（让 DevTools 面板刷新"能力"标签页）
+     */
+    async refreshSkills() {
+        if (!this.state.started || this.state.terminated)
+            return;
+        try {
+            const { skills, skillGroups } = await this.loadAllSkills();
+            if (this.skillTool) {
+                this.skillTool.refresh(skills);
+            }
+            this.state.skills = skills;
+            this.emitAcodeEvent("skill_status", {
+                skillsDir: this.config.skillsDir,
+                installedCount: skills.length,
+                skills: skills.map((skill) => ({
+                    name: skill.name,
+                    description: skill.description,
+                    directory: skill.directory,
+                })),
+                skillGroups: skillGroups.map((group) => ({
+                    dir: group.dir,
+                    exists: group.exists,
+                    skills: group.skills.map((skill) => ({
+                        name: skill.name,
+                        description: skill.description,
+                        directory: skill.directory,
+                    })),
+                })),
+            });
+            runtimeDebugLog(`[skill-watch] Skills refreshed: ${skills.length} skills ` +
+                `(${skills.map((s) => s.name).join(", ") || "none"})`, { sessionId: this.config.sessionId });
+        }
+        catch (error) {
+            console.error(`[skill-watch] Failed to refresh skills:`, error instanceof Error ? error.message : error);
+        }
+    }
+    /**
+     * 关闭所有 skills 目录监听器与防抖定时器。在 stop() 中调用。
+     */
+    stopSkillWatchers() {
+        if (this.skillRefreshTimer) {
+            clearTimeout(this.skillRefreshTimer);
+            this.skillRefreshTimer = null;
+        }
+        for (const watcher of this.skillWatchers) {
+            try {
+                watcher.close();
+            }
+            catch {
+                // 忽略关闭错误
+            }
+        }
+        this.skillWatchers = [];
+    }
+    /**
+     * 启动上下文压缩调试日志，每 5 秒写入系统临时目录下的 acode-compaction-debug.log。
+     * 仅当环境变量 ACODE_COMPACTION_DEBUG=1 时启用，使用异步写入避免阻塞事件循环。
+     */
+    startCompactionDebugLog() {
+        if (!COMPACTION_DEBUG_ENABLED)
+            return;
+        if (this.compactionDebugTimer)
+            return;
+        const provider = this.state.provider;
+        const { contextLimit, maxOutput, inputLimit, threshold: triggerThreshold } = resolveCompactionConfig(provider);
+        this.compactionDebugTimer = setInterval(() => {
+            try {
+                const actualUsed = this.state.accumulatedInputTokens + this.state.accumulatedOutputTokens;
+                const estimatedUsed = estimateConversationTokens(this.state.conversation)
+                    + estimateToolsTokens(this.state.exposedTools);
+                const effectiveUsed = Math.max(actualUsed, estimatedUsed);
+                const sizeKB = conversationSizeKB(this.state.conversation);
+                const isRunning = this.state.started && !this.state.terminated;
+                const lines = [
+                    `[${new Date().toISOString()}]`,
+                    `started=${this.state.started}`,
+                    `terminated=${this.state.terminated}`,
+                    `activeTurn=${this.activeTurn}`,
+                    `conversationSize=${this.state.conversation.length}msgs`,
+                    `sizeKB=${sizeKB}KB`,
+                    `estimation=${estimatedUsed} tokens`,
+                    `actualInput=${this.state.accumulatedInputTokens}`,
+                    `actualOutput=${this.state.accumulatedOutputTokens}`,
+                    `actualUsed=${actualUsed}`,
+                    `contextLimit=${contextLimit}`,
+                    `inputLimit=${inputLimit ?? "n/a"}`,
+                    `maxOutput=${maxOutput}`,
+                    `triggerThreshold=${triggerThreshold}`,
+                    `remainingToTrigger=${Math.max(0, triggerThreshold - actualUsed)}`,
+                    `isRunning=${isRunning}`,
+                    `shouldCompact=${isRunning ? effectiveUsed >= triggerThreshold : false}`,
+                    `---`,
+                ].join(" | ");
+                // 异步写入，避免阻塞事件循环
+                fs.promises.appendFile(COMPACTION_DEBUG_LOG, lines + "\n", "utf-8").catch(() => {
+                    // 忽略日志写入错误
+                });
+            }
+            catch {
+                // 忽略日志写入错误
+            }
+        }, 5000);
+    }
+    /**
+     * 停止上下文压缩调试日志。
+     */
+    stopCompactionDebugLog() {
+        if (this.compactionDebugTimer) {
+            clearInterval(this.compactionDebugTimer);
+            this.compactionDebugTimer = null;
+        }
     }
     /**
      * 处理一轮用户输入。
@@ -1002,8 +1481,17 @@ export class ACodeRuntime extends EventEmitter {
      */
     async submit(message) {
         const contextVersion = this.contextVersion;
-        const queued = this.submitQueue.then(() => this.executeSubmit(message, contextVersion));
-        this.submitQueue = queued.catch(() => undefined);
+        runtimeDebugLog(`[ACodeRuntime] 📬 submit() queued: contextVersion=${contextVersion}, ` +
+            `activeTurn=${this.activeTurn}, abortRequested=${this.abortRequested}, ` +
+            `terminated=${this.state.terminated}, message.length=${message.length}`);
+        const queued = this.submitQueue.then(() => {
+            runtimeDebugLog(`[ACodeRuntime] ▶️ executeSubmit dequeued: contextVersion=${contextVersion}`);
+            return this.executeSubmit(message, contextVersion);
+        });
+        this.submitQueue = queued.catch(() => {
+            runtimeDebugLog(`[ACodeRuntime] 📬 submit() queued item rejected (catch swallowed)`);
+        });
+        runtimeDebugLog(`[ACodeRuntime] 📬 submit() returning queued promise`);
         return queued;
     }
     /**
@@ -1019,17 +1507,19 @@ export class ACodeRuntime extends EventEmitter {
         this.abortController?.abort();
         this.abortController = null;
         this.state.conversation = cloneChatConversation(this.initialConversation);
+        this.state.accumulatedInputTokens = 0;
+        this.state.accumulatedOutputTokens = 0;
     }
     isTurnSuperseded(contextVersion) {
         return contextVersion !== this.contextVersion;
     }
     async executeSubmit(message, contextVersion) {
         const turnStartTime = Date.now();
-        console.log(`[ACodeRuntime] ══════════════════════════════════════════`);
-        console.log(`[ACodeRuntime] ▶️ executeSubmit STARTED`);
-        console.log(`[ACodeRuntime]  Message: ${message.slice(0, 100)}${message.length > 100 ? '...' : ''}`);
-        console.log(`[ACodeRuntime] 🔢 Context version: ${contextVersion}`);
-        console.log(`[ACodeRuntime] ═══════════════════════════════════════════`);
+        runtimeDebugLog(`[ACodeRuntime] ══════════════════════════════════════════`);
+        runtimeDebugLog(`[ACodeRuntime] ▶️ executeSubmit STARTED`);
+        runtimeDebugLog(`[ACodeRuntime]  Message: <redacted, length=${message.length}>`);
+        runtimeDebugLog(`[ACodeRuntime] 🔢 Context version: ${contextVersion}`);
+        runtimeDebugLog(`[ACodeRuntime] ═══════════════════════════════════════════`);
         if (!this.state.started || this.state.terminated) {
             console.error(`[ACodeRuntime] ❌ Runtime not active (started: ${this.state.started}, terminated: ${this.state.terminated})`);
             throw new Error("ACode runtime is not active");
@@ -1039,14 +1529,14 @@ export class ACodeRuntime extends EventEmitter {
         const originalPrompt = message.trim();
         let turnCompleted = false;
         try {
-            console.log(`[ACodeRuntime] 🔍 Dispatching UserPromptSubmit hook...`);
+            runtimeDebugLog(`[ACodeRuntime] 🔍 Dispatching UserPromptSubmit hook...`);
             const promptHookStartTime = Date.now();
             const promptHookResults = await this.hookBus.dispatch("UserPromptSubmit", { prompt: originalPrompt });
             const promptHookDuration = Date.now() - promptHookStartTime;
-            console.log(`[ACodeRuntime] ✅ UserPromptSubmit hook completed in ${promptHookDuration}ms, ` +
+            runtimeDebugLog(`[ACodeRuntime] ✅ UserPromptSubmit hook completed in ${promptHookDuration}ms, ` +
                 `results: ${promptHookResults.length}`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ⚠️ Turn superseded after hook, aborting`);
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Turn superseded after hook, aborting`);
                 return;
             }
             const promptDeny = findDeniedHookResult(promptHookResults);
@@ -1057,15 +1547,15 @@ export class ACodeRuntime extends EventEmitter {
                 });
                 this.emitAcodeEvent("turn_complete", { failed: true });
                 turnCompleted = true;
-                console.log(`[ACodeRuntime] 📤 Emitted turn_complete (failed=true) due to hook deny`);
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitted turn_complete (failed=true) due to hook deny`);
                 return;
             }
-            console.log(`[ACodeRuntime] 🔍 Expanding command if any...`);
+            runtimeDebugLog(`[ACodeRuntime] 🔍 Expanding command if any...`);
             const expandedCommand = this.state.commandRegistry.expand(originalPrompt);
             const trimmed = expandedCommand?.prompt.trim() || originalPrompt;
             const commandAllowedTools = expandedCommand?.command.allowedTools;
             if (expandedCommand) {
-                console.log(`[ACodeRuntime] 📋 Slash command detected: ${expandedCommand.command.name}`);
+                runtimeDebugLog(`[ACodeRuntime] 📋 Slash command detected: ${expandedCommand.command.name}`);
                 this.emitAcodeEvent("command_status", {
                     action: "slash_command",
                     command: expandedCommand.command.name,
@@ -1074,76 +1564,85 @@ export class ACodeRuntime extends EventEmitter {
                 });
             }
             if (!this.state.provider.baseURL || !this.state.provider.apiKey) {
-                console.log(`[ACodeRuntime] ⚠️ No provider configured, using fallback response`);
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ No provider configured, using fallback response`);
                 const text = createFallbackResponse(trimmed, this.state);
                 this.emitAcodeEvent("assistant_delta", { text });
                 this.emitAcodeEvent("turn_complete", {
                     usage: { inputTokens: trimmed.length, outputTokens: text.length },
                 });
                 turnCompleted = true;
-                console.log(`[ACodeRuntime] 📤 Emitted turn_complete (fallback mode)`);
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitted turn_complete (fallback mode)`);
                 return;
             }
-            console.log(`[ACodeRuntime] 📎 Parsing attachment message...`);
+            runtimeDebugLog(`[ACodeRuntime] 📎 Parsing attachment message...`);
             const parsedContent = parseAttachmentMessage(trimmed);
             if (parsedContent.hasImages && !this.state.provider.supportsImageInput) {
                 console.error(`[ACodeRuntime] ❌ Image input not supported by current provider`);
                 throw new Error("ACode provider/model is not configured for image input. Enable provider.default.models[model].modalities.input including 'image' or options.supportsImageInput=true.");
             }
-            console.log(`[ACodeRuntime] 🖼️ Materializing image content if any...`);
+            runtimeDebugLog(`[ACodeRuntime] 🖼️ Materializing image content if any...`);
             const userContent = await materializeImageContent(parsedContent.content);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ️ Turn superseded after materializing content, aborting`);
+                runtimeDebugLog(`[ACodeRuntime] ️ Turn superseded after materializing content, aborting`);
                 return;
             }
-            console.log(`[ACodeRuntime] 💬 Adding user message to conversation`);
+            runtimeDebugLog(`[ACodeRuntime] 💬 Adding user message to conversation`);
             this.state.conversation.push({ role: "user", content: userContent });
-            console.log(`[ACodeRuntime]  Conversation size: ${this.state.conversation.length} messages`);
-            console.log(`[ACodeRuntime]  Starting runModelTurn...`);
+            runtimeDebugLog(`[ACodeRuntime]  Conversation size: ${this.state.conversation.length} messages`);
+            runtimeDebugLog(`[ACodeRuntime]  Starting runModelTurn...`);
             const modelTurnStartTime = Date.now();
             const result = await this.runModelTurn(commandAllowedTools, contextVersion);
             const modelTurnDuration = Date.now() - modelTurnStartTime;
-            console.log(`[ACodeRuntime] ✅ runModelTurn completed in ${modelTurnDuration}ms`);
-            console.log(`[ACodeRuntime] 📝 Result: text=${result.text ? result.text.slice(0, 80) + (result.text.length > 80 ? '...' : '') : '(empty)'}, ` +
+            runtimeDebugLog(`[ACodeRuntime] ✅ runModelTurn completed in ${modelTurnDuration}ms`);
+            runtimeDebugLog(`[ACodeRuntime] 📝 Result: text=${result.text ? result.text.slice(0, 80) + (result.text.length > 80 ? '...' : '') : '(empty)'}, ` +
                 `finishReason=${result.finishReason || '(none)'}`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ️ Turn superseded after runModelTurn, aborting`);
+                runtimeDebugLog(`[ACodeRuntime] ️ Turn superseded after runModelTurn, aborting`);
                 return;
             }
             if (result.text && !this.state.provider.stream) {
-                console.log(`[ACodeRuntime] 📤 Emitting assistant_delta (non-streaming mode)`);
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitting assistant_delta (non-streaming mode)`);
                 this.emitAcodeEvent("assistant_delta", { text: result.text });
             }
-            console.log(`[ACodeRuntime] 📤 Emitting turn_complete...`);
+            runtimeDebugLog(`[ACodeRuntime] 📤 Emitting turn_complete...`);
             this.emitAcodeEvent("turn_complete", {
+                // ★ 使用 result.totalOutputTextLength 替代 result.text.length，
+                //    result.text 只保留最后一次迭代的文本，导致多轮迭代时 outputTokens 被严重低估
                 usage: result.usage ?? {
                     inputTokens: trimmed.length,
-                    outputTokens: result.text.length,
+                    outputTokens: result.totalOutputTextLength ?? result.text.length,
                 },
                 ...(result.responseBody ? { responseBody: result.responseBody } : {}),
                 ...(result.finishReason ? { finishReason: result.finishReason } : {}),
             });
+            // ★ token 用量已在 runModelTurn 中按迭代更新到 state（非累加），
+            //    此处不再累加，避免 actualUsed 跨轮只增不减导致 shouldCompact 永远为 true。
+            //    finalUsage 用于 turn_complete 事件的 usage 上报（当前迭代的上下文用量，覆盖式）。
+            runtimeDebugLog(`[ACodeRuntime] 💰 Current context usage: ` +
+                `input=${this.state.accumulatedInputTokens}, ` +
+                `output=${this.state.accumulatedOutputTokens}` +
+                (result.usage ? '' : ' (estimated, no provider usage)'));
             turnCompleted = true;
             const totalDuration = Date.now() - turnStartTime;
-            console.log(`[ACodeRuntime] ═══════════════════════════════════════════`);
-            console.log(`[ACodeRuntime] ✅ executeSubmit COMPLETED in ${totalDuration}ms`);
-            console.log(`[ACodeRuntime] ══════════════════════════════════════════`);
+            runtimeDebugLog(`[ACodeRuntime] ═══════════════════════════════════════════`);
+            runtimeDebugLog(`[ACodeRuntime] ✅ executeSubmit COMPLETED in ${totalDuration}ms`);
+            runtimeDebugLog(`[ACodeRuntime] ══════════════════════════════════════════`);
         }
         catch (error) {
             const errorDuration = Date.now() - turnStartTime;
             console.error(`[ACodeRuntime] ❌ executeSubmit FAILED after ${errorDuration}ms:`, error instanceof Error ? error.message : String(error));
             console.error(`[ACodeRuntime] 🔍 Error stack:`, error instanceof Error ? error.stack : '(no stack)');
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ️ Turn superseded in error handler, skipping recovery`);
+                runtimeDebugLog(`[ACodeRuntime] ️ Turn superseded in error handler, skipping recovery`);
                 return;
             }
             if (this.abortRequested) {
-                console.log(`[ACodeRuntime] ⚠️ Abort requested, emitting aborted turn_complete`);
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Abort requested, emitting aborted turn_complete`);
                 this.emitAcodeEvent("turn_complete", { aborted: true });
                 turnCompleted = true;
                 return;
             }
-            console.log(`[ACodeRuntime]  Emitting error and failed turn_complete...`);
+            runtimeDebugLog(`[ACodeRuntime]  Emitting error and failed turn_complete...`);
             this.emitAcodeEvent("error", {
                 message: error instanceof Error ? error.message : String(error),
             });
@@ -1152,30 +1651,186 @@ export class ACodeRuntime extends EventEmitter {
         }
         finally {
             const finallyDuration = Date.now() - turnStartTime;
-            console.log(`[ACodeRuntime] 🔚 executeSubmit finally block entered after ${finallyDuration}ms`);
-            console.log(`[ACodeRuntime] 🔍 turnCompleted=${turnCompleted}, activeTurn=${this.activeTurn}, ` +
-                `abortRequested=${this.abortRequested}`);
+            runtimeDebugLog(`[ACodeRuntime] 🔚 executeSubmit finally block entered after ${finallyDuration}ms`);
+            runtimeDebugLog(`[ACodeRuntime] 🔍 turnCompleted=${turnCompleted}, activeTurn=${this.activeTurn}, ` +
+                `abortRequested=${this.abortRequested}, contextVersion=${contextVersion}, ` +
+                `currentContextVersion=${this.contextVersion}`);
             this.activeTurn = false;
             this.abortRequested = false;
             // 关键修复：如果异常路径没有发射 turn_complete，强制发射一个
             // 这确保 adapter 层的 recoverResolvedTurnWithoutTerminalEvent 能够正确触发
             if (!turnCompleted && !this.isTurnSuperseded(contextVersion)) {
-                console.error(`[ACodeRuntime] 🚨 CRITICAL: executeSubmit finally block reached without turn_complete event!`);
-                console.error(`[ACodeRuntime] 🚨 This indicates a code path that should have emitted turn_complete but didn't.`);
-                console.error(`[ACodeRuntime]  Forcing failed turn_complete to prevent state stuck.`);
+                console.error(`[ACodeRuntime] 🚨 CRITICAL: executeSubmit finally block reached without turn_complete event! ` +
+                    `Duration: ${finallyDuration}ms. ` +
+                    `This indicates a code path that should have emitted turn_complete but didn't. ` +
+                    `Forcing failed turn_complete to prevent state stuck.`);
                 this.emitAcodeEvent("error", {
                     message: "ACode turn completed without proper completion event (internal error)",
                 });
                 this.emitAcodeEvent("turn_complete", { failed: true });
-                console.log(`[ACodeRuntime]  Emergency turn_complete (failed=true) emitted`);
+                runtimeDebugLog(`[ACodeRuntime]  Emergency turn_complete (failed=true) emitted`);
             }
         }
     }
     /** 中止当前轮次；由执行轮次统一发出一个终态事件，避免 aborted/failed 双终态。 */
     async abort() {
+        const hadController = this.abortController !== null;
+        const wasActiveTurn = this.activeTurn;
         this.abortRequested = this.activeTurn;
-        this.abortController?.abort();
+        if (this.abortController) {
+            runtimeDebugLog(`[ACodeRuntime] ⛔ abort() calling abortController.abort() (activeTurn=${wasActiveTurn})`);
+            this.abortController.abort();
+        }
+        else {
+            console.warn(`[ACodeRuntime] ⛔ abort() called but abortController is null! ` +
+                `activeTurn=${wasActiveTurn}, abortRequested will be set to ${wasActiveTurn}. ` +
+                `This means abort() CANNOT cancel any running fetch/stream — ` +
+                `if a built-in tool is executing, it will NOT be interrupted.`);
+        }
         this.abortController = null;
+        // ask_user_question 等待用户回答期间被 abort，需 reject 所有 waiter
+        this.rejectAllQuestionWaiters("aborted");
+    }
+    /**
+     * 构造 ask_user_question 工具的依赖注入。
+     * onQuestion: 发出 question_request 事件，让 adapter 转发到前端。
+     * waitForAnswer: 阻塞等待 submitQuestionAnswer() 调用 resolve，或 abort/stop/supersede 时 reject。
+     */
+    buildAskUserQuestionDeps() {
+        return {
+            onQuestion: (toolCallId, questions) => {
+                this.emitAcodeEvent("question_request", {
+                    toolCallId,
+                    questions: questions,
+                });
+            },
+            waitForAnswer: (toolCallId, contextVersion) => {
+                return new Promise((resolve, reject) => {
+                    this.questionWaiters.set(toolCallId, {
+                        resolve,
+                        reject,
+                        contextVersion,
+                    });
+                });
+            },
+        };
+    }
+    /**
+     * 构造 sub-agent 工具集依赖（注入 SubAgentManager 句柄）。
+     *
+     * 5 个工具的依赖：
+     *   - spawnSubAgent: 创建子 agent（不阻塞，不自动 start）
+     *   - listSubAgents: 列出当前 agent 的所有子 agent
+     *   - getSubAgentStatus: 查询某子 agent 实时状态
+     *   - awaitSubAgents: 阻塞等待指定子 agent 数组完成
+     *   - abortSubAgent: 终止某子 agent
+     */
+    buildSubAgentToolDeps(manager) {
+        const parentAgentId = this.config.agentId ?? "unknown";
+        const parentSessionId = this.config.sessionId;
+        const workingDirectory = this.config.workingDirectory;
+        const parentConfig = this.config;
+        return {
+            // 非阻塞 spawn：创建后不等待，立即返回 subId
+            spawnSubAgent: async (opts) => {
+                const subId = await manager.spawn({
+                    parentAgentId,
+                    parentSessionId,
+                    subagentType: opts.subagentType,
+                    description: opts.description,
+                    prompt: opts.prompt,
+                    workingDirectory,
+                    parentConfig: {
+                        ...parentConfig,
+                        // 注入父 agent 的 MCP 连接，子 agent 复用而非启动新 MCP server 进程
+                        // 避免 launch binding 已被父 agent 消费后子 agent 401
+                        sharedMcpConnections: this.state?.mcpConnections,
+                    },
+                });
+                // 自动 start（非阻塞，立即返回）
+                await manager.start(subId);
+                return { subId };
+            },
+            // 列出当前 agent 的所有子 agent（运行中 + 历史）
+            listSubAgents: async () => {
+                const entries = manager.listByParent(parentAgentId);
+                const running = [];
+                const history = [];
+                for (const entry of entries) {
+                    const info = {
+                        subId: entry.subId,
+                        subagentType: entry.subagentType,
+                        description: entry.description,
+                        status: entry.status,
+                        startedAt: entry.startedAt,
+                        endedAt: entry.endedAt,
+                        durationMs: entry.durationMs,
+                    };
+                    if (entry.status === "pending" || entry.status === "running") {
+                        running.push(info);
+                    }
+                    else {
+                        history.push(info);
+                    }
+                }
+                // history 按 endedAt 倒序
+                history.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
+                return { running, history };
+            },
+            // 查询某子 agent 实时状态
+            getSubAgentStatus: async (subId) => {
+                const entry = manager.getSubAgent(subId);
+                if (!entry)
+                    return null;
+                return {
+                    subId: entry.subId,
+                    subagentType: entry.subagentType,
+                    description: entry.description,
+                    status: entry.status,
+                    startedAt: entry.startedAt,
+                    endedAt: entry.endedAt,
+                    durationMs: entry.durationMs,
+                    prompt: entry.prompt,
+                    result: entry.result,
+                    errorMessage: entry.errorMessage,
+                    contextSnapshot: entry.contextSnapshot,
+                };
+            },
+            // 阻塞等待指定子 agent 数组完成
+            awaitSubAgents: (subIds, timeoutMs) => manager.awaitCompletion(subIds, timeoutMs),
+            // 终止某子 agent
+            abortSubAgent: (subId) => manager.abort(subId),
+        };
+    }
+    /**
+     * 接收用户对 ask_user_question 的回答（由 AcodeSdkAdapter.sendQuestionAnswer 调用）。
+     * 若当前 turn 已被 supersede（contextVersion 变更），返回 false 让 adapter 知晓。
+     */
+    submitQuestionAnswer(toolCallId, answers) {
+        const waiter = this.questionWaiters.get(toolCallId);
+        if (!waiter) {
+            return false;
+        }
+        this.questionWaiters.delete(toolCallId);
+        // 若 turn 已被 supersede，不 resolve（避免过期答案污染新轮次）
+        if (this.isTurnSuperseded(waiter.contextVersion)) {
+            waiter.reject(new Error("turn superseded before user answered"));
+            return false;
+        }
+        waiter.resolve(answers);
+        return true;
+    }
+    /**
+     * 中止所有 ask_user_question 等待，让工具 execute() 抛错走 appendToolFailureResult。
+     * 在 abort()/stop() 中调用，确保用户点停止或会话终止时 execute 不会永久阻塞。
+     */
+    rejectAllQuestionWaiters(reason) {
+        if (this.questionWaiters.size === 0)
+            return;
+        for (const [, waiter] of this.questionWaiters) {
+            waiter.reject(new Error(`ask_user_question ${reason}`));
+        }
+        this.questionWaiters.clear();
     }
     /** 终止 ACode 会话并发出 session_complete。 */
     async stop() {
@@ -1187,6 +1842,8 @@ export class ACodeRuntime extends EventEmitter {
         this.abortRequested = this.activeTurn;
         this.abortController?.abort();
         this.abortController = null;
+        // ask_user_question 等待用户回答期间被 stop，需 reject 所有 waiter
+        this.rejectAllQuestionWaiters("session terminated");
         await runBestEffort("ACode active turn shutdown", this.submitQueue, (message) => {
             this.emitAcodeEvent("error", { message });
         });
@@ -1199,6 +1856,18 @@ export class ACodeRuntime extends EventEmitter {
             this.sessionCompleteEmitted = true;
             this.emitAcodeEvent("session_complete", { exitCode: 0 });
         }
+        this.stopCompactionDebugLog();
+        this.stopSkillWatchers();
+        if (COMPACTION_DEBUG_ENABLED) {
+            try {
+                fs.promises.appendFile(COMPACTION_DEBUG_LOG, `[${new Date().toISOString()}] runtime stopped | ---\n`, "utf-8").catch(() => {
+                    // 忽略
+                });
+            }
+            catch {
+                // 忽略
+            }
+        }
     }
     resolveCommandDirs(acodeConfig) {
         const configured = [
@@ -1215,29 +1884,31 @@ export class ACodeRuntime extends EventEmitter {
         let finalUsage;
         let finalResponseBody;
         let finalFinishReason;
+        let accumulatedAssistantText = ""; // 累加多轮迭代的 output 文本长度
+        let accumulatedPromptTokens = 0; // 累加多轮迭代的 prompt_tokens
         // 日志：开始 runModelTurn
-        console.log(`[ACodeRuntime] ▶️ runModelTurn started (contextVersion: ${contextVersion})`);
+        runtimeDebugLog(`[ACodeRuntime] ▶️ runModelTurn started (contextVersion: ${contextVersion})`);
         // 移除5次限制，添加安全上限防止真正的无限循环
         const SAFETY_LIMIT = 50; // 安全上限，正常情况下不会达到
         for (let step = 0; step < SAFETY_LIMIT; step += 1) {
             // 详细日志：记录每次迭代
-            console.log(`[ACodeRuntime] 🔄 Iteration ${step + 1} starting...`);
+            runtimeDebugLog(`[ACodeRuntime] 🔄 Iteration ${step + 1} starting...`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ⚠️ Turn superseded at iteration ${step + 1}, aborting`);
-                return { text: "" };
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Turn superseded at iteration ${step + 1}, aborting`);
+                return { text: "", totalOutputTextLength: accumulatedAssistantText.length };
             }
             const requestStartTime = Date.now();
             const response = await this.requestChatCompletion(commandAllowedTools);
             const requestDuration = Date.now() - requestStartTime;
             // 日志：AI请求完成
-            console.log(`[ACodeRuntime] 🤖 AI request completed in ${requestDuration}ms, ` +
+            runtimeDebugLog(`[ACodeRuntime] 🤖 AI request completed in ${requestDuration}ms, ` +
                 `choices: ${response.choices?.length || 0}`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ⚠️ Turn superseded after AI response at iteration ${step + 1}`);
-                return { text: "" };
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Turn superseded after AI response at iteration ${step + 1}`);
+                return { text: "", totalOutputTextLength: accumulatedAssistantText.length };
             }
             if (this.state.terminated) {
-                console.log(`[ACodeRuntime]  Runtime terminated at iteration ${step + 1}`);
+                runtimeDebugLog(`[ACodeRuntime]  Runtime terminated at iteration ${step + 1}`);
                 throw new Error("ACode runtime was stopped during the active turn");
             }
             const choice = response.choices?.[0];
@@ -1252,7 +1923,7 @@ export class ACodeRuntime extends EventEmitter {
                 ? message.tool_calls
                 : [];
             // 日志：AI响应详情
-            console.log(`[ACodeRuntime]  AI response: ` +
+            runtimeDebugLog(`[ACodeRuntime]  AI response: ` +
                 `content=${content ? content.slice(0, 100) + (content.length > 100 ? '...' : '') : '(empty)'}, ` +
                 `toolCalls=${toolCalls.length}, ` +
                 `finishReason=${finalFinishReason || '(none)'}`);
@@ -1261,11 +1932,25 @@ export class ACodeRuntime extends EventEmitter {
                 const rtOutputTokens = response.usage.completion_tokens ?? response.usage.output_tokens;
                 if (typeof rtInputTokens === "number" &&
                     typeof rtOutputTokens === "number") {
+                    // ★ finalUsage 记录当前迭代的实际 token 用量（覆盖式，非累加）。
+                    //    prompt_tokens 代表本次请求时 provider 看到的完整上下文大小，
+                    //    若跨迭代累加会得到 N × 上下文大小 的无意义总和，导致 turn_complete
+                    //    上报的 usage 远超真实上下文，前端"上下文"标签会瞬间跳到几 M 再跳回。
+                    //    改为覆盖式，与 state.accumulatedInputTokens 及 AcodeSdkAdapter 的
+                    //    "当前上下文"语义保持一致。
                     finalUsage = {
                         inputTokens: rtInputTokens,
                         outputTokens: rtOutputTokens,
                     };
-                    console.log(`[ACodeRuntime] 💰 Token usage: input=${rtInputTokens}, output=${rtOutputTokens}`);
+                    accumulatedPromptTokens += rtInputTokens;
+                    // ★ 更新 state 为当前迭代的实际 token 用量（非累加）
+                    //    prompt_tokens 代表本次请求时 provider 看到的完整上下文大小，
+                    //    是当前上下文大小的最准确度量。
+                    //    之前用 += 累加导致 actualUsed 只增不减，shouldCompact 永远为 true。
+                    this.state.accumulatedInputTokens = rtInputTokens;
+                    this.state.accumulatedOutputTokens = rtOutputTokens;
+                    runtimeDebugLog(`[ACodeRuntime] 💰 Token usage: input=${rtInputTokens}, output=${rtOutputTokens} ` +
+                        `(turn accumulated cost: input=${accumulatedPromptTokens})`);
                 }
             }
             this.state.conversation.push({
@@ -1275,31 +1960,33 @@ export class ACodeRuntime extends EventEmitter {
             });
             if (content) {
                 finalText = content;
-                console.log(`[ACodeRuntime] ✨ Captured assistant text: ${content.slice(0, 80)}...`);
+                accumulatedAssistantText += content;
+                runtimeDebugLog(`[ACodeRuntime] ✨ Captured assistant text: ${content.slice(0, 80)}...`);
             }
             if (toolCalls.length === 0) {
-                console.log(`[ACodeRuntime] ✅ No tool calls at iteration ${step + 1}, completing turn`);
+                runtimeDebugLog(`[ACodeRuntime] ✅ No tool calls at iteration ${step + 1}, completing turn`);
                 return {
                     text: finalText,
                     usage: finalUsage,
                     responseBody: finalResponseBody,
                     finishReason: finalFinishReason,
+                    totalOutputTextLength: accumulatedAssistantText.length,
                 };
             }
             // 日志：即将执行工具调用
             const toolNames = toolCalls.map(tc => tc.function.name).join(", ");
-            console.log(`[ACodeRuntime] 🔧 Executing ${toolCalls.length} tool(s) at iteration ${step + 1}: ${toolNames}`);
+            runtimeDebugLog(`[ACodeRuntime] 🔧 Executing ${toolCalls.length} tool(s) at iteration ${step + 1}: ${toolNames}`);
             const toolStart = Date.now();
             await this.handleToolCalls(toolCalls, commandAllowedTools, contextVersion);
             const toolDuration = Date.now() - toolStart;
             // 日志：工具执行完成
-            console.log(`[ACodeRuntime] ⚙️ Tool execution completed in ${toolDuration}ms at iteration ${step + 1}`);
+            runtimeDebugLog(`[ACodeRuntime] ⚙️ Tool execution completed in ${toolDuration}ms at iteration ${step + 1}`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ⚠️ Turn superseded after tool execution at iteration ${step + 1}`);
-                return { text: "" };
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Turn superseded after tool execution at iteration ${step + 1}`);
+                return { text: "", totalOutputTextLength: accumulatedAssistantText.length };
             }
             // 日志：准备下一次迭代
-            console.log(`[ACodeRuntime] 🔄 Preparing iteration ${step + 2}...`);
+            runtimeDebugLog(`[ACodeRuntime] 🔄 Preparing iteration ${step + 2}...`);
         }
         // 达到安全上限（理论上不应该发生）
         console.error(`[ACodeRuntime] 🚨 CRITICAL: Reached safety limit of ${SAFETY_LIMIT} iterations! ` +
@@ -1309,19 +1996,163 @@ export class ACodeRuntime extends EventEmitter {
             usage: finalUsage,
             responseBody: finalResponseBody,
             finishReason: finalFinishReason || "safety_iteration_limit_reached",
+            totalOutputTextLength: accumulatedAssistantText.length,
         };
     }
+    /**
+     * LLM 摘要器：调用当前 provider 生成结构化对话摘要。
+     *
+     * 这是把 OpenCode 的 LLM 摘要能力赋能到 ACode 的核心方法：
+     * - OpenCode 在 compaction.process 中调用独立的 compaction agent
+     * - ACode 复用当前 provider 配置，发起一次非流式 chat completion 请求
+     * - 使用 COMPACTION_LLM_PROMPT_TEMPLATE 作为 prompt 模板
+     *
+     * 设计要点：
+     * 1. 非流式调用（不需要流式，简化处理）
+     * 2. 不带 tools（纯文本生成）
+     * 3. 失败时抛出异常，由 summarizeConversation 降级到规则摘要
+     * 4. 独立的 AbortController，避免主请求取消影响摘要
+     * 5. 复用 provider 的 timeout 配置
+     *
+     * @param input 摘要输入（conversationText + messageCount + contextLimit）
+     * @returns LLM 生成的结构化摘要文本
+     */
+    async summarizeConversationWithLLM(input) {
+        const provider = this.state.provider;
+        const baseURL = provider.baseURL;
+        if (!baseURL) {
+            throw new Error("ACode provider baseURL is not configured for LLM summarization");
+        }
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (provider.apiKey) {
+            headers.Authorization = `Bearer ${provider.apiKey}`;
+        }
+        const requestBody = {
+            model: provider.model,
+            stream: false,
+            messages: [
+                {
+                    role: "system",
+                    content: "You are a helpful AI assistant tasked with summarizing conversations. " +
+                        "When asked to summarize, provide a detailed but concise summary of the conversation. " +
+                        "Focus on information that would be helpful for continuing the conversation. " +
+                        "Do not respond to any questions in the conversation, only output the summary.",
+                },
+                {
+                    role: "user",
+                    content: `Below is an earlier conversation (${input.messageCount} messages) that needs to be summarized ` +
+                        `to free context space (current context limit: ${input.contextLimit} tokens).\n\n` +
+                        `--- Conversation Start ---\n${input.conversationText}\n--- Conversation End ---\n\n` +
+                        COMPACTION_LLM_PROMPT_TEMPLATE,
+                },
+            ],
+        };
+        const abortController = new AbortController();
+        this.abortController = abortController;
+        const response = await withTimeout(fetch(normalizeChatCompletionsUrl(baseURL), {
+            method: "POST",
+            headers,
+            body: JSON.stringify(requestBody),
+            signal: abortController.signal,
+        }), provider.requestTimeoutMs, "ACode LLM summarization", () => {
+            abortController.abort();
+        });
+        if (!response.ok) {
+            // ★ 防御修复：用 withTimeout 包裹 response.text()，防止错误响应 body stream 挂起
+            const errorBody = await withTimeout(response.text(), provider.requestTimeoutMs, "ACode LLM summarization error response body", () => {
+                abortController.abort();
+            });
+            const truncatedBody = errorBody.length > 500
+                ? `${errorBody.slice(0, 500)}...(truncated, total ${errorBody.length} chars)`
+                : errorBody;
+            throw new Error(`ACode LLM summarization request failed: ${response.status} ${truncatedBody}`);
+        }
+        const payload = (await response.json());
+        const content = payload.choices?.[0]?.message?.content;
+        if (!content || content.trim().length === 0) {
+            throw new Error("ACode LLM summarization returned empty content");
+        }
+        return content;
+    }
     async requestChatCompletion(commandAllowedTools) {
         const provider = this.state.provider;
         const baseURL = provider.baseURL;
         if (!baseURL) {
             throw new Error("ACode provider baseURL is not configured");
         }
-        const truncatedCount = truncateConversationIfNeeded(this.state.conversation, MAX_REQUEST_BODY_BYTES);
+        // 主动上下文压缩：在发送 AI 请求前检测 token 是否溢出。
+        // ★ 与 session_started 事件 emit 的阈值同源（resolveCompactionConfig），保证前端显示 = 实际触发。
+        const { contextLimit, maxOutput, inputLimit, threshold: compactionThreshold } = resolveCompactionConfig(provider);
+        // 使用 effectiveUsed = max(actualUsed, estimatedUsed)
+        // 因为部分 provider 不返回 usage 数据（actualUsed=0），此时降级到文本估算
+        const actualUsed = this.state.accumulatedInputTokens + this.state.accumulatedOutputTokens;
+        // ★ 估算时加入 tools 定义开销，使估算更接近实际请求 token 数。
+        //   之前只估算 conversation 消息，遗漏了 tools 的 JSON schema（可达数千 tokens），
+        //   导致估算系统性偏低、主动压缩阈值无法触达。
+        const estimatedUsed = estimateConversationTokens(this.state.conversation)
+            + estimateToolsTokens(this.state.exposedTools);
+        const effectiveUsed = Math.max(actualUsed, estimatedUsed);
+        const shouldCompact = effectiveUsed >= compactionThreshold;
+        runtimeDebugLog(`[ACodeRuntime] 🔍 Compaction check: ` +
+            `actualUsed=${actualUsed}, estimation=${estimatedUsed}, ` +
+            `effectiveUsed=${effectiveUsed}, contextLimit=${contextLimit}, ` +
+            `inputLimit=${inputLimit ?? "n/a"}, maxOutput=${maxOutput}, ` +
+            `triggerThreshold=${compactionThreshold}, shouldCompact=${shouldCompact}`);
+        if (shouldCompact) {
+            const sizeBeforeKB = conversationSizeKB(this.state.conversation);
+            const compactionId = `compaction-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            this.emitAcodeEvent("context_compaction", {
+                action: "start",
+                compactionId,
+                sizeKB: sizeBeforeKB,
+                estimatedTokens: estimatedUsed,
+                actualInputTokens: this.state.accumulatedInputTokens,
+                actualOutputTokens: this.state.accumulatedOutputTokens,
+                messageCount: this.state.conversation.length,
+                model: provider.model,
+                trigger: actualUsed >= compactionThreshold ? "actual_usage" : "estimated_overflow",
+            });
+            // ★ 发射压缩子事件（检测到溢出）
+            this.emitCompactionPhase(compactionId, "detect", "检测到上下文溢出", `有效用量: ${effectiveUsed} tokens, 阈值: ${compactionThreshold}, 触发: ${actualUsed >= compactionThreshold ? "实际用量" : "估算溢出"}`);
+            const result = await performCompaction(this.state.conversation, contextLimit, maxOutput, {
+                llmSummarizer: (input) => this.summarizeConversationWithLLM(input),
+                onPhase: (phaseEvent) => this.handleCompactionPhase(compactionId, phaseEvent),
+                // 传入 effectiveUsed 修复文本估算低于实际 token 数时
+                // post-prune isOverflow 误判导致 summarize 被跳过的问题
+                actualUsedTokens: effectiveUsed,
+            });
+            const sizeAfterKB = conversationSizeKB(this.state.conversation);
+            this.emitAcodeEvent("context_compaction", {
+                action: "end",
+                compactionId,
+                sizeBeforeKB,
+                sizeAfterKB,
+                freedKB: Math.round((sizeBeforeKB - sizeAfterKB) * 10) / 10,
+                strategy: result.strategy,
+                freedTokens: result.freedTokens,
+                tokensBefore: result.tokensBefore,
+                tokensAfter: result.tokensAfter,
+                prunedToolMessages: result.prunedToolMessages,
+                summarizedMessages: result.summarizedMessages,
+                messageCountBefore: result.messageCountBefore,
+                messageCountAfter: result.messageCountAfter,
+            });
+            // ★ 压缩后重置累积 token 计数，使下一次请求时 actualUsed 反映压缩后的真实上下文大小。
+            //    若不重置，actualUsed 仍为压缩前的旧值，shouldCompact 会持续为 true 导致无效压缩循环。
+            this.state.accumulatedInputTokens = 0;
+            this.state.accumulatedOutputTokens = 0;
+        }
+        const truncatedCount = await truncateConversationIfNeeded(this.state.conversation, MAX_REQUEST_BODY_BYTES, contextLimit, maxOutput, (input) => this.summarizeConversationWithLLM(input));
         if (truncatedCount > 0) {
             this.emitAcodeEvent("warning", {
                 message: `Conversation truncated: removed ${truncatedCount} older messages to fit within ${MAX_REQUEST_BODY_BYTES} byte request size limit`,
             });
+            // ★ HTTP body 兜底压缩后同样重置累积 token 计数，避免下一轮 actualUsed 仍为
+            //   压缩前旧值导致 shouldCompact 误判（与主动压缩路径行为一致，见上方 shouldCompact 块）。
+            this.state.accumulatedInputTokens = 0;
+            this.state.accumulatedOutputTokens = 0;
         }
         const allowedTools = this.state.exposedTools.filter((tool) => isToolAllowed(tool, this.state.permissions, commandAllowedTools));
         const buildBody = () => {
@@ -1330,6 +2161,16 @@ export class ACodeRuntime extends EventEmitter {
                 messages: this.state.conversation,
                 stream: provider.stream,
             };
+            // ★ 思考强度：写入 reasoning_effort 字段，兼容 OpenAI o-series 及兼容 API。
+            //   未配置 effort 时不写入，由 provider 使用默认值。
+            if (provider.effort) {
+                body.reasoning_effort = provider.effort;
+            }
+            // ★ 流式请求必须设置 stream_options.include_usage，否则 provider 不返回 usage，
+            //   导致 accumulatedInputTokens 永远为 0，主动压缩无法基于实际用量触发。
+            if (provider.stream) {
+                body.stream_options = { include_usage: true };
+            }
             if (allowedTools.length > 0) {
                 body.tools = toOpenAiTools(allowedTools);
                 body.tool_choice = "auto";
@@ -1343,7 +2184,7 @@ export class ACodeRuntime extends EventEmitter {
         const emitAiRequest = (body) => {
             const requestBody = JSON.stringify(body, null, 2);
             // [DEBUG] ACode Runtime 实际发送的模型名称
-            console.log(`[ACodeRuntime] ★★★ DEBUG ★★★ emitAiRequest: 发送请求 model=${provider.model}, endpoint=${requestUrl}, messageCount=${this.state.conversation.length}`);
+            runtimeDebugLog(`[ACodeRuntime] ★★★ DEBUG ★★★ emitAiRequest: 发送请求 model=${provider.model}, endpoint=${requestUrl}, messageCount=${this.state.conversation.length}`);
             this.emitAcodeEvent("ai_request", {
                 model: provider.model,
                 endpoint: requestUrl,
@@ -1360,9 +2201,10 @@ export class ACodeRuntime extends EventEmitter {
         };
         let body = buildBody();
         emitAiRequest(body);
-        const maxAttempts = provider.requestRetryCount + 1;
+        const infiniteRetries = provider.requestRetryCount === INFINITE_RETRY_SENTINEL;
+        const maxAttempts = infiniteRetries ? Infinity : provider.requestRetryCount + 1;
         let contextOverflowCompacted = false;
-        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        for (let attempt = 1; infiniteRetries || attempt <= maxAttempts; attempt += 1) {
             const requestAbortController = new AbortController();
             this.abortController = requestAbortController;
             let timedOut = false;
@@ -1378,7 +2220,20 @@ export class ACodeRuntime extends EventEmitter {
                         requestAbortController.abort();
                     });
                     if (!response.ok) {
-                        throw new Error(`ACode provider request failed: ${response.status} ${await response.text()}`);
+                        // ★ 防御修复：用 withTimeout 包裹 response.text()，
+                        //   防止 502/503 等错误响应的 body stream 挂起导致永久阻塞。
+                        //   外层 withTimeout(requestTotalTimeoutMs, 10min) 兜底太晚，
+                        //   且看门狗可能已被重试 error 事件禁用。
+                        const errorBody = await withTimeout(response.text(), provider.requestTimeoutMs, "ACode provider error response body", () => {
+                            timedOut = true;
+                            requestAbortController.abort();
+                        });
+                        // ★ 截断过长的错误响应体（如 Cloudflare 502 HTML 页面可达数 KB），
+                        //   避免错误消息通过事件链路传播时造成 HTTP POST body 过大或日志膨胀
+                        const truncatedBody = errorBody.length > 500
+                            ? `${errorBody.slice(0, 500)}...(truncated, total ${errorBody.length} chars)`
+                            : errorBody;
+                        throw new Error(`ACode provider request failed: ${response.status} ${truncatedBody}`);
                     }
                     const contentType = response.headers?.get?.("content-type") || "";
                     if (provider.stream &&
@@ -1398,7 +2253,14 @@ export class ACodeRuntime extends EventEmitter {
                         return {};
                     }
                     return payload;
-                })(), 0, "ACode provider request");
+                })(), 
+                // ★ 安全修复：即使无限重试也保留总预算超时兜底，
+                //   防止 provider 持续发送 SSE keep-alive 导致 idle timeout 永不触发、
+                //   请求永久挂起。用户可通过配置更大的 requestTotalTimeoutMs 值来放宽限制。
+                provider.requestTotalTimeoutMs, "ACode provider request total", () => {
+                    // 总预算超时：abort 底层 fetch / stream reader，避免泄漏
+                    requestAbortController.abort();
+                });
             }
             catch (error) {
                 let requestError;
@@ -1415,11 +2277,62 @@ export class ACodeRuntime extends EventEmitter {
                     !this.abortRequested &&
                     !this.state.terminated &&
                     isContextOverflowProviderRequestError(requestError)) {
-                    const compactedCount = compactConversationForContextOverflow(this.state.conversation);
+                    // 响应式上下文压缩：Provider 返回上下文溢出错误时强制执行
+                    // 这里不通过 performCompaction（它会先检查 isOverflow），
+                    // 而是直接调用 summarizeConversation 进行强制摘要化
+                    const sizeBeforeKB = conversationSizeKB(this.state.conversation);
+                    const tokensBeforeOC = estimateConversationTokens(this.state.conversation); // tokensBefore 命名冲突，加 OC 后缀
+                    const msgCountBefore = this.state.conversation.length;
+                    const compactionId = `compaction-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+                    this.emitAcodeEvent("context_compaction", {
+                        action: "start",
+                        compactionId,
+                        sizeKB: sizeBeforeKB,
+                        estimatedTokens: tokensBeforeOC,
+                        messageCount: msgCountBefore,
+                        model: provider.model,
+                        trigger: "provider_overflow_error",
+                    });
+                    // ★ 发射压缩子事件（检测到溢出）
+                    this.emitCompactionPhase(compactionId, "detect", "Provider 返回上下文溢出", `消息: ${msgCountBefore}条, 大小: ${sizeBeforeKB}KB`);
+                    // 先尝试 prune 旧工具输出
+                    this.emitCompactionPhase(compactionId, "prune", "阶段1: 裁剪工具输出", "正在裁剪...");
+                    const pruneResult = pruneToolOutputs(this.state.conversation, contextLimit);
+                    this.emitCompactionPhase(compactionId, "prune_done", "阶段1: 裁剪工具输出", `裁剪了 ${pruneResult.prunedCount} 条工具输出, 释放 ${pruneResult.freedTokens} tokens`);
+                    // 再强制 summarize 早期对话（使用 LLM 摘要器提升摘要质量，失败降级到规则摘要）
+                    this.emitCompactionPhase(compactionId, "summarize", "阶段2: 摘要化对话", "正在摘要...");
+                    const summarizedCount = await summarizeConversation(this.state.conversation, {
+                        llmSummarizer: (input) => this.summarizeConversationWithLLM(input),
+                        contextLimit,
+                    });
+                    this.emitCompactionPhase(compactionId, "summarize_done", "阶段2: 摘要化对话", `摘要化了 ${summarizedCount} 条消息`);
+                    const sizeAfterKB = conversationSizeKB(this.state.conversation);
+                    const tokensAfterOC = estimateConversationTokens(this.state.conversation);
+                    const msgCountAfter = this.state.conversation.length;
                     contextOverflowCompacted = true;
+                    const compactedCount = pruneResult.prunedCount + summarizedCount;
+                    this.emitAcodeEvent("context_compaction", {
+                        action: "end",
+                        compactionId,
+                        sizeBeforeKB,
+                        sizeAfterKB,
+                        freedKB: Math.round((sizeBeforeKB - sizeAfterKB) * 10) / 10,
+                        tokensBefore: tokensBeforeOC,
+                        tokensAfter: tokensAfterOC,
+                        messageCountBefore: msgCountBefore,
+                        messageCountAfter: msgCountAfter,
+                        strategy: summarizedCount > 0 ? "summarize" : "prune",
+                        freedTokens: pruneResult.freedTokens,
+                        prunedToolMessages: pruneResult.prunedCount,
+                        summarizedMessages: summarizedCount,
+                        trigger: "provider_overflow_error",
+                    });
                     if (compactedCount === 0) {
                         throw requestError;
                     }
+                    // ★ 响应式压缩后同样重置累积 token 计数
+                    this.state.accumulatedInputTokens = 0;
+                    this.state.accumulatedOutputTokens = 0;
                     this.emitAcodeEvent("warning", {
                         message: `ACode provider context limit exceeded; summarized ${compactedCount} older messages and rebuilt the request instead of retrying the same oversized payload`,
                     });
@@ -1428,7 +2341,7 @@ export class ACodeRuntime extends EventEmitter {
                     attempt -= 1;
                     continue;
                 }
-                const shouldRetry = attempt < maxAttempts &&
+                const shouldRetry = (infiniteRetries || attempt < maxAttempts) &&
                     !this.abortRequested &&
                     !this.state.terminated &&
                     isRetryableProviderRequestError(requestError);
@@ -1436,7 +2349,11 @@ export class ACodeRuntime extends EventEmitter {
                     throw requestError;
                 }
                 this.emitAcodeEvent("error", {
-                    message: `ACode provider request attempt ${attempt}/${maxAttempts} failed; retrying: ${requestError.message}`,
+                    message: `ACode provider request attempt ${attempt}${infiniteRetries ? '' : `/${maxAttempts}`} failed; retrying: ${requestError.message}`,
+                    // ★ 关键修复：重试中的错误是瞬态的，不是致命错误。
+                    //   如果不标记 nonFatal，适配器会把 status 设为 "error" 并取消看门狗，
+                    //   导致后续重试尝试挂起时看门狗无法检测，agent 永久卡死。
+                    nonFatal: true,
                 });
                 await delay(DEFAULT_PROVIDER_REQUEST_RETRY_DELAY_MS * attempt);
             }
@@ -1457,6 +2374,8 @@ export class ACodeRuntime extends EventEmitter {
         const toolCallAccumulators = new Map();
         let text = "";
         let buffer = "";
+        /** 从 SSE 流最终 chunk 中提取的 usage（OpenAI 格式在最后一个 chunk 的 usage 字段中） */
+        let streamUsage;
         const consumeFrame = (frame) => {
             for (const data of parseSseDataLines(frame)) {
                 if (data === "[DONE]") {
@@ -1466,6 +2385,11 @@ export class ACodeRuntime extends EventEmitter {
                 if (!isRecord(payload)) {
                     continue;
                 }
+                // ★ 提取 SSE chunk 中的 usage（OpenAI 流式 API 在最后一个 chunk 返回完整 usage，此时 choices 为空数组）
+                const chunkUsage = payload.usage;
+                if (chunkUsage) {
+                    streamUsage = chunkUsage;
+                }
                 const choice = payload.choices?.[0];
                 const delta = choice?.delta;
                 const reasoningText = extractReasoningText(delta);
@@ -1510,33 +2434,40 @@ export class ACodeRuntime extends EventEmitter {
                     },
                 },
             ],
+            ...(streamUsage ? { usage: streamUsage } : {}),
         };
     }
     async handleToolCalls(toolCalls, commandAllowedTools, contextVersion = this.contextVersion) {
-        console.log(`[ACodeRuntime]  handleToolCalls started with ${toolCalls.length} tool(s)`);
+        runtimeDebugLog(`[ACodeRuntime]  handleToolCalls started with ${toolCalls.length} tool(s)`);
         for (const toolCall of toolCalls) {
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ️ Turn superseded, skipping remaining tools`);
+                runtimeDebugLog(`[ACodeRuntime] ️ Turn superseded, skipping remaining tools`);
                 return;
             }
             const toolName = toolCall.function.name;
-            console.log(`[ACodeRuntime] 🔍 Looking up tool: ${toolName}`);
-            const tool = this.state.exposedTools.find((item) => item.exposedName === toolCall.function.name);
+            runtimeDebugLog(`[ACodeRuntime] 🔍 Looking up tool: ${toolName}`);
+            let tool = this.state.exposedTools.find((item) => item.exposedName === toolName);
             if (!tool) {
-                console.error(`[ACodeRuntime] ❌ Tool not found: ${toolCall.function.name}, ` +
+                tool = this.state.exposedTools.find((item) => item.toolName === toolName);
+                if (tool) {
+                    runtimeDebugLog(`[ACodeRuntime] ↩️ 裸名回退匹配: ${toolName} -> ${tool.exposedName}`);
+                }
+            }
+            if (!tool) {
+                console.error(`[ACodeRuntime] ❌ Tool not found: ${toolName}, ` +
                     `available tools: ${this.state.exposedTools.map(t => t.exposedName).join(", ")}`);
                 this.state.conversation.push({
                     role: "tool",
                     tool_call_id: toolCall.id,
-                    content: `ACode MCP tool not found: ${toolCall.function.name}`,
+                    content: `ACode MCP tool not found: ${toolName}`,
                 });
                 continue;
             }
-            console.log(`[ACodeRuntime]  Found tool: ${tool.toolName} (kind: ${tool.kind}, source: ${tool.kind === 'mcp' ? tool.serverName : 'builtin'})`);
+            runtimeDebugLog(`[ACodeRuntime]  Found tool: ${tool.toolName} (kind: ${tool.kind}, source: ${tool.kind === 'mcp' ? tool.serverName : 'builtin'})`);
             try {
                 if (tool.kind === "builtin") {
                     const toolArguments = coerceArguments(toolCall.function.arguments);
-                    console.log(`[ACodeRuntime]  Built-in tool arguments: ${JSON.stringify(toolArguments).slice(0, 200)}`);
+                    runtimeDebugLog(`[ACodeRuntime]  Built-in tool arguments: ${JSON.stringify(toolArguments).slice(0, 200)}`);
                     assertToolPermission(tool, this.state.permissions, commandAllowedTools);
                     const preResults = await this.hookBus.dispatch("PreToolUse", {
                         source: "builtin",
@@ -1553,7 +2484,7 @@ export class ACodeRuntime extends EventEmitter {
                         throw new Error(denied.message ||
                             `ACode tool denied by hook: ${tool.exposedName}`);
                     }
-                    console.log(`[ACodeRuntime]  Emitting mcp_status call_tool for ${tool.exposedName}`);
+                    runtimeDebugLog(`[ACodeRuntime]  Emitting mcp_status call_tool for ${tool.exposedName}`);
                     this.emitAcodeEvent("mcp_status", {
                         action: "call_tool",
                         server: "builtin",
@@ -1564,7 +2495,13 @@ export class ACodeRuntime extends EventEmitter {
                         argumentsPreview: summarizeToolArguments(toolArguments),
                     });
                     const toolStart = Date.now();
-                    console.log(`[ACodeRuntime] ▶️ Executing built-in tool: ${tool.exposedName}`);
+                    const toolTimeoutMs = getBuiltInToolTimeoutMs(tool, toolArguments, this.state.provider.mcpToolTimeoutMs);
+                    runtimeDebugLog(`[ACodeRuntime] ▶️ Executing built-in tool: ${tool.exposedName} ` +
+                        `(timeout: ${toolTimeoutMs}ms, abortRequested: ${this.abortRequested})`);
+                    if (toolTimeoutMs <= 0) {
+                        console.warn(`[ACodeRuntime] ⚠️ Built-in tool ${tool.exposedName} has NO timeout (timeoutMs=${toolTimeoutMs})! ` +
+                            `If this tool hangs, executeSubmit will NEVER resolve, blocking the submit queue permanently.`);
+                    }
                     const result = await withTimeout(tool.execute(toolArguments, {
                         onOutput: (outputEvent) => {
                             this.emitAcodeEvent("command_output", {
@@ -1582,9 +2519,10 @@ export class ACodeRuntime extends EventEmitter {
                                     : {}),
                             });
                         },
-                    }), getBuiltInToolTimeoutMs(tool, toolArguments, this.state.provider.mcpToolTimeoutMs), `ACode built-in tool ${tool.toolName}`);
+                        toolCallId: toolCall.id,
+                    }), toolTimeoutMs, `ACode built-in tool ${tool.toolName}`);
                     const toolDuration = Date.now() - toolStart;
-                    console.log(`[ACodeRuntime] ✅ Built-in tool ${tool.exposedName} completed in ${toolDuration}ms`);
+                    runtimeDebugLog(`[ACodeRuntime] ✅ Built-in tool ${tool.exposedName} completed in ${toolDuration}ms`);
                     if (this.isTurnSuperseded(contextVersion)) {
                         return;
                     }
@@ -1598,7 +2536,7 @@ export class ACodeRuntime extends EventEmitter {
                         return;
                     }
                     const resultText = toToolResultText(result);
-                    console.log(`[ACodeRuntime] 📤 Emitting mcp_status tool_result for ${tool.exposedName}, ` +
+                    runtimeDebugLog(`[ACodeRuntime] 📤 Emitting mcp_status tool_result for ${tool.exposedName}, ` +
                         `result length: ${resultText.length} chars`);
                     this.emitAcodeEvent("mcp_status", {
                         action: "tool_result",
@@ -1611,7 +2549,7 @@ export class ACodeRuntime extends EventEmitter {
                         tool_call_id: toolCall.id,
                         content: resultText,
                     });
-                    await this.appendSyntheticMultimodalUserMessage(resultText, contextVersion);
+                    await this.appendSyntheticMultimodalUserMessage(resultText, toolCall.id, contextVersion);
                     continue;
                 }
                 // MCP工具处理
@@ -1627,7 +2565,7 @@ export class ACodeRuntime extends EventEmitter {
                     continue;
                 }
                 const toolArguments = coerceArguments(toolCall.function.arguments);
-                console.log(`[ACodeRuntime]  MCP tool arguments: ${JSON.stringify(toolArguments).slice(0, 200)}`);
+                runtimeDebugLog(`[ACodeRuntime]  MCP tool arguments: ${JSON.stringify(toolArguments).slice(0, 200)}`);
                 assertToolPermission(tool, this.state.permissions, commandAllowedTools);
                 const preResults = await this.hookBus.dispatch("PreToolUse", {
                     source: "mcp",
@@ -1644,7 +2582,7 @@ export class ACodeRuntime extends EventEmitter {
                     console.error(`[ACodeRuntime] ❌ MCP tool denied by hook: ${tool.exposedName}: ${denied.message}`);
                     throw new Error(denied.message || `ACode tool denied by hook: ${tool.exposedName}`);
                 }
-                console.log(`[ACodeRuntime] 📤 Emitting mcp_status call_tool for MCP ${tool.exposedName}`);
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitting mcp_status call_tool for MCP ${tool.exposedName}`);
                 this.emitAcodeEvent("mcp_status", {
                     action: "call_tool",
                     server: tool.serverName,
@@ -1659,11 +2597,15 @@ export class ACodeRuntime extends EventEmitter {
                     ? this.state.provider.mcpPollingToolTimeoutMs
                     : this.state.provider.mcpToolTimeoutMs;
                 const toolStart = Date.now();
-                console.log(`[ACodeRuntime] ▶️ Executing MCP tool: ${tool.exposedName} ` +
+                runtimeDebugLog(`[ACodeRuntime] ▶️ Executing MCP tool: ${tool.exposedName} ` +
                     `(timeout: ${toolTimeoutMs}ms, polling: ${isPollingTool})`);
-                const result = await this.callMcpToolWithTimeout(connection, tool, toolArguments, toolTimeoutMs, isPollingTool);
+                // poll_message 工具需要同时检测子 agent 完成事件（有就返回类型），
+                // 使用 sub-agent race 包装器替代直接 MCP 调用。
+                const result = isPollingTool && getSemanticToolName(tool.toolName) === "poll_message"
+                    ? await this.callPollMessageWithSubAgentRace(connection, tool, toolArguments, toolTimeoutMs)
+                    : await this.callMcpToolWithTimeout(connection, tool, toolArguments, toolTimeoutMs, isPollingTool);
                 const toolDuration = Date.now() - toolStart;
-                console.log(`[ACodeRuntime] ✅ MCP tool ${tool.exposedName} completed in ${toolDuration}ms`);
+                runtimeDebugLog(`[ACodeRuntime] ✅ MCP tool ${tool.exposedName} completed in ${toolDuration}ms`);
                 if (this.isTurnSuperseded(contextVersion)) {
                     return;
                 }
@@ -1678,7 +2620,7 @@ export class ACodeRuntime extends EventEmitter {
                     return;
                 }
                 const resultText = toToolResultText(result);
-                console.log(`[ACodeRuntime] 📤 Emitting mcp_status tool_result for MCP ${tool.exposedName}, ` +
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitting mcp_status tool_result for MCP ${tool.exposedName}, ` +
                     `result length: ${resultText.length} chars`);
                 this.emitAcodeEvent("mcp_status", {
                     action: "tool_result",
@@ -1691,31 +2633,60 @@ export class ACodeRuntime extends EventEmitter {
                     tool_call_id: toolCall.id,
                     content: resultText,
                 });
-                await this.appendSyntheticMultimodalUserMessage(resultText, contextVersion);
+                await this.appendSyntheticMultimodalUserMessage(resultText, toolCall.id, contextVersion);
             }
             catch (error) {
-                console.error(`[ACodeRuntime] ❌ Tool execution failed: ${toolCall.function.name}`, error instanceof Error ? error.message : String(error));
+                const isTimeout = error instanceof Error &&
+                    error.message.includes("timed out after");
+                const isAbortError = error instanceof Error &&
+                    error.name === "AbortError";
+                console.error(`[ACodeRuntime] ❌ Tool execution failed: ${toolCall.function.name}`, `isTimeout=${isTimeout}, isAbortError=${isAbortError}`, error instanceof Error ? error.message : String(error));
                 if (this.isTurnSuperseded(contextVersion)) {
+                    runtimeDebugLog(`[ACodeRuntime] ️ Turn superseded after tool error, skipping`);
                     return;
                 }
                 if (this.abortRequested || this.state.terminated) {
-                    console.log(`[ACodeRuntime] ⚠️ Rethrowing error due to abort/termination`);
+                    // ★ 修复 BUG（时间线永久卡在"编辑文件"）：
+                    //   abort/termination 时原实现直接 rethrow，跳过 appendToolFailureResult
+                    //   (3752 行的 mcp_status tool_result 发射)，导致 adapter 永远收不到 tool_result，
+                    //   tool_use_end 永不发射，前端时间线永久卡在 tool_use_start 创建的工具条目。
+                    //   修复：在 rethrow 前补发一个带 failed=true 的 tool_result，关闭时间线条目。
+                    runtimeDebugLog(`[ACodeRuntime] ⚠️ Rethrowing error due to abort/termination ` +
+                        `(abortRequested=${this.abortRequested}, terminated=${this.state.terminated})`);
+                    runtimeDebugLog(`[ACodeRuntime] 📤 Emitting mcp_status tool_result (failed, aborted) ` +
+                        `for ${tool.exposedName} before rethrow to close timeline entry`);
+                    this.emitAcodeEvent("mcp_status", {
+                        action: "tool_result",
+                        server: tool.kind === "mcp" ? tool.serverName : "builtin",
+                        tool: tool.toolName,
+                        result: `[aborted] ${error instanceof Error ? error.message : String(error)}`,
+                        failed: true,
+                        aborted: true,
+                    });
                     throw error instanceof Error ? error : new Error(String(error));
                 }
+                runtimeDebugLog(`[ACodeRuntime]  Calling appendToolFailureResult for ${tool.exposedName} ` +
+                    `(isTimeout=${isTimeout})`);
                 this.appendToolFailureResult(toolCall, tool, error);
             }
         }
-        console.log(`[ACodeRuntime]  handleToolCalls completed for all ${toolCalls.length} tool(s)`);
+        runtimeDebugLog(`[ACodeRuntime]  handleToolCalls completed for all ${toolCalls.length} tool(s)`);
     }
     async callMcpToolWithTimeout(connection, tool, toolArguments, timeoutMs, retrySdkTimeout) {
         const sdkTimeout = timeoutMs > 0 ? timeoutMs : MCP_SDK_MAX_SAFE_TIMEOUT_MS;
+        // 子 agent 共享父 agent 的 MCP 连接时，注入标记让 MCP server 跳过状态上报
+        // （StatusReporter 绑定父 agentId，子 agent 的事件不应出现在父 agent 时间线上）
+        const isSubAgent = Boolean(this.config.sharedMcpConnections);
+        const finalArguments = isSubAgent
+            ? { ...toolArguments, _aws_sub_agent: true }
+            : toolArguments;
         while (true) {
             const stopWaiter = this.createRuntimeStopWaiter(`ACode MCP tool ${tool.serverName}/${tool.toolName}`);
             try {
                 return await withTimeout(Promise.race([
                     connection.client.callTool({
                         name: tool.toolName,
-                        arguments: toolArguments,
+                        arguments: finalArguments,
                     }, undefined, { timeout: sdkTimeout }),
                     stopWaiter.promise,
                 ]), timeoutMs, `ACode MCP tool ${tool.serverName}/${tool.toolName}`);
@@ -1735,6 +2706,568 @@ export class ACodeRuntime extends EventEmitter {
             }
         }
     }
+    /**
+     * 将子 agent 终态通知转为 poll_message 格式的合成 DirectMessage。
+     * 主流程：构建符合 MCP poll_message 返回格式的 JSON 字符串。
+     */
+    static formatSubAgentCompletionAsPollResult(notifications) {
+        const directMessages = notifications.map((n) => {
+            const summary = n.error
+                ? `Sub-agent ${n.subId} [${n.status}]: ${n.description}\nError: ${n.error}`
+                : `Sub-agent ${n.subId} [${n.status}]: ${n.description}\nOutput: ${n.output.length > 500 ? n.output.slice(0, 500) + "... (truncated)" : n.output}`;
+            return {
+                msgId: `subagent-completion-${n.subId}-${Date.now()}`,
+                senderId: "ACode-Runtime",
+                senderName: "系统",
+                content: summary,
+                requireReply: false,
+                prompt: `Sub-agent ${n.subId} (${n.description}) has reached terminal state: ${n.status}. Review its output and decide next steps.`,
+                timestamp: new Date().toISOString(),
+            };
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        directMessages,
+                        groupMessages: [],
+                        fromBuffer: false,
+                        systemMessages: [],
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    /**
+     * 将子 agent 终态通知合并到已有的 MCP poll_message 返回结果中。
+     * 主流程：解析 MCP 返回的 JSON -> 将通知转为 DirectMessage 插入到 directMessages 前面 -> 重新序列化。
+     */
+    static mergeSubAgentCompletionsIntoMcpResult(mcpResult, notifications) {
+        if (notifications.length === 0)
+            return mcpResult;
+        // 提取 MCP 结果中的文本
+        const resultText = toToolResultText(mcpResult);
+        let parsed;
+        try {
+            parsed = JSON.parse(resultText);
+        }
+        catch {
+            // 如果 MCP 结果不是 JSON（异常情况），直接返回原结果
+            return mcpResult;
+        }
+        const subAgentMessages = notifications.map((n) => {
+            const summary = n.error
+                ? `Sub-agent ${n.subId} [${n.status}]: ${n.description}\nError: ${n.error}`
+                : `Sub-agent ${n.subId} [${n.status}]: ${n.description}\nOutput: ${n.output.length > 500 ? n.output.slice(0, 500) + "... (truncated)" : n.output}`;
+            return {
+                msgId: `subagent-completion-${n.subId}-${Date.now()}`,
+                senderId: "ACode-Runtime",
+                senderName: "系统",
+                content: summary,
+                requireReply: false,
+                prompt: `Sub-agent ${n.subId} (${n.description}) has reached terminal state: ${n.status}. Review its output and decide next steps.`,
+                timestamp: new Date().toISOString(),
+            };
+        });
+        const mergedDirectMessages = [
+            ...subAgentMessages,
+            ...(parsed.directMessages ?? []),
+        ];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ...parsed,
+                        directMessages: mergedDirectMessages,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    /**
+     * Memory 自动委托 sub-agent 完成一轮后的外部重新检查。
+     *
+     * 查询服务端 memory 真实状态（通过 MCP 工具直接调用，非 LLM 自报），
+     * 判断 sub-agent 是否真正完成了处理：
+     * - memory_file_change：检查每条 memory 的 memory_status 是否已回到 normal
+     * - memory_expiration：检查每条 memory 是否已续期（expiresAt 在未来）或已清理（read 返回 null）
+     * - memory_cleanup：检查 get_memory_stats 中对应类型/域是否仍 exceeded
+     *
+     * 若仍有未完成项，返回 { done: false, continueMessage } 包含 "经检查，未完成对xxx的处理，请继续"
+     * 及具体未完成列表，由 SubAgentManager 注入同一 sub-agent 的下一轮 submit。
+     *
+     * recheck 自身出错（MCP 连接不可用、工具调用超时等）时返回 { done: true }，不阻塞 sub-agent 结束。
+     */
+    async recheckMemoryDelegate(type, uris, output, turn) {
+        const connection = this.state.mcpConnections.find((c) => c.serverName === 'aws-client-agent-mcp');
+        if (!connection) {
+            runtimeDebugLog(`[ACodeRuntime] recheckMemoryDelegate: aws-client-agent-mcp connection not found, treating as done`);
+            return { done: true };
+        }
+        try {
+            if (type === 'memory_file_change') {
+                return await this.recheckMemoryFileChange(connection, uris);
+            }
+            if (type === 'memory_expiration') {
+                return await this.recheckMemoryExpiration(connection, uris);
+            }
+            return await this.recheckMemoryCleanup(connection, uris);
+        }
+        catch (err) {
+            runtimeDebugLog(`[ACodeRuntime] recheckMemoryDelegate failed (type=${type}, turn=${turn}): ` +
+                `${err instanceof Error ? err.message : String(err)}, treating as done`);
+            return { done: true };
+        }
+    }
+    /**
+     * 通过 MCP read_memory 工具读取单条 memory 记录。
+     * 注入 _aws_sub_agent=true 避免状态上报污染父 agent 时间线。
+     * 返回 null 表示 memory 不存在或读取失败。
+     */
+    async readMemoryViaMcp(connection, uri) {
+        try {
+            const result = await withTimeout(connection.client.callTool({
+                name: 'read_memory',
+                arguments: { uri, _aws_sub_agent: true },
+            }, undefined, { timeout: 30_000 }), 30_000, `recheck read_memory ${uri}`);
+            const text = toToolResultText(result);
+            const parsed = JSON.parse(text);
+            if (parsed === null || parsed === undefined)
+                return null;
+            if (typeof parsed !== 'object' || Array.isArray(parsed))
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** recheck memory_file_change：检查 memory_status 是否仍为 updating */
+    async recheckMemoryFileChange(connection, uris) {
+        const stillUpdating = [];
+        await Promise.all(uris.map(async (uri) => {
+            const mem = await this.readMemoryViaMcp(connection, uri);
+            if (mem && mem.memory_status === 'updating') {
+                stillUpdating.push(uri);
+            }
+        }));
+        if (stillUpdating.length === 0) {
+            runtimeDebugLog(`[ACodeRuntime] recheck memory_file_change: all ${uris.length} URIs done (memory_status=normal or deleted)`);
+            return { done: true };
+        }
+        const list = stillUpdating.map((u) => `- ${u}`).join('\n');
+        runtimeDebugLog(`[ACodeRuntime] recheck memory_file_change: ${stillUpdating.length}/${uris.length} URIs still updating`);
+        return {
+            done: false,
+            continueMessage: `经检查，未完成对以下 memory 的更新，请继续：\n${list}\n\n` +
+                `这些 memory 的 memory_status 仍为 "updating"。请重新 read_memory 查看内容，` +
+                `查看绑定文件最新内容，并调用 update_memory 完成更新。`,
+        };
+    }
+    /** recheck memory_expiration：检查 expiresAt 是否仍过期 或 memory_status 是否仍为 recalling */
+    async recheckMemoryExpiration(connection, uris) {
+        const stillExpired = [];
+        const now = Date.now();
+        await Promise.all(uris.map(async (uri) => {
+            const mem = await this.readMemoryViaMcp(connection, uri);
+            if (!mem)
+                return; // memory 已删除/不存在 → 视为已处理
+            const expiresAt = mem.expiresAt ?? mem.expires_at;
+            const isRecalling = mem.memory_status === 'recalling';
+            const isExpired = typeof expiresAt === 'string' && new Date(expiresAt).getTime() < now;
+            if (isRecalling || isExpired) {
+                stillExpired.push(uri);
+            }
+        }));
+        if (stillExpired.length === 0) {
+            runtimeDebugLog(`[ACodeRuntime] recheck memory_expiration: all ${uris.length} URIs done (renewed, cleaned, or no longer expired)`);
+            return { done: true };
+        }
+        const list = stillExpired.map((u) => `- ${u}`).join('\n');
+        runtimeDebugLog(`[ACodeRuntime] recheck memory_expiration: ${stillExpired.length}/${uris.length} URIs still expired or recalling`);
+        return {
+            done: false,
+            continueMessage: `经检查，未完成对以下 memory 的处理，请继续：\n${list}\n\n` +
+                `这些 memory 仍处于过期或回忆中状态。请调用 memory_recurrence 获取内容，` +
+                `对需要保留的调用 update_memory 续期，对无价值的调用 memory_recurrence_complete 清理。`,
+        };
+    }
+    /** recheck memory_cleanup：检查 get_memory_stats 中对应类型/域是否仍 exceeded */
+    async recheckMemoryCleanup(connection, uris) {
+        // delegate URIs 格式为 "${memoryType}/${domain}"
+        let stats;
+        try {
+            const result = await withTimeout(connection.client.callTool({
+                name: 'get_memory_stats',
+                arguments: { _aws_sub_agent: true },
+            }, undefined, { timeout: 30_000 }), 30_000, 'recheck get_memory_stats');
+            const text = toToolResultText(result);
+            stats = JSON.parse(text);
+        }
+        catch {
+            // stats 查询失败 → 视为完成
+            return { done: true };
+        }
+        const byType = (stats.by_type ?? {});
+        const stillExceeded = [];
+        for (const uri of uris) {
+            const sepIdx = uri.indexOf('/');
+            if (sepIdx < 0)
+                continue;
+            const memoryType = uri.slice(0, sepIdx);
+            const domain = uri.slice(sepIdx + 1);
+            const typeStats = byType[memoryType];
+            const domainStats = typeStats?.by_domain?.[domain];
+            if (domainStats?.exceeded) {
+                stillExceeded.push(`${memoryType}/${domain} (当前 ${domainStats.count ?? '?'} 条，建议上限 ${domainStats.limit ?? '?'})`);
+            }
+        }
+        if (stillExceeded.length === 0) {
+            runtimeDebugLog(`[ACodeRuntime] recheck memory_cleanup: all ${uris.length} type/domain pairs within limits`);
+            return { done: true };
+        }
+        const list = stillExceeded.map((u) => `- ${u}`).join('\n');
+        runtimeDebugLog(`[ACodeRuntime] recheck memory_cleanup: ${stillExceeded.length}/${uris.length} type/domain pairs still exceeded`);
+        return {
+            done: false,
+            continueMessage: `经检查，以下类型/域尚未整理完成，请继续：\n${list}\n\n` +
+                `请调用 list_memories 查看超限记忆，删除不再需要的 recently_memory 或对 agent_memory 调用 update_memory 续期。`,
+        };
+    }
+    /**
+     * 构造 memory 自动委托子 agent 的 prompt。
+     * 主流程：根据 delegate 类型（过期整理/文件变更更新）生成自包含指令。
+     */
+    buildMemoryDelegatePrompt(delegate) {
+        const urisText = delegate.uris.map(u => `- ${u}`).join('\n');
+        if (delegate.type === 'memory_expiration') {
+            return `你是一条专门处理 memory 过期整理的子 agent。
+
+当前有以下 ${delegate.uris.length} 条即将遗忘的记忆需要整理：
+${urisText}
+
+请执行以下步骤（核心逻辑：处理 → 验证 → 未完成则继续）：
+
+=== 处理阶段 ===
+1. 调用 memory_recurrence(limit=10) 分批获取这些过期记忆的完整内容（最早过期优先）
+2. 逐条分析：这些内容是否仍然有价值？是否需要保留、更新、归档或删除？
+3. 对于需要保留的，调用 update_memory 续期；对于无价值的，调用 memory_recurrence_complete 将其清理到永久记忆或删除
+
+=== 验证阶段（关键，不可跳过） ===
+4. 再次调用 memory_recurrence(limit=5) 检查是否还有未处理的过期记忆
+   - 如果返回结果中有之前处理过的 URI，说明更新/清理未生效
+   - 如果仍有待处理条目，说明部分操作未完成
+5. 仔细检查返回结果：
+   - ❌ 若仍有过期记忆未处理（或处理未成功）：输出 "经检查，未完成对以下 memory 的处理，请继续：" 列出还记忆，然后回到步骤 1 继续处理
+   - ✅ 若全部处理完毕（返回空或无过期条目）：静默结束
+
+注意：你运行在独立的上下文窗口中，不影响主 agent 的主线任务。请高效完成，不要询问用户。
+完成后系统会通过查询服务端真实状态进行二次验证（不依赖你的自报结果）。若验证发现仍有 memory 未处理，会发送 "经检查，未完成对以下 memory 的处理，请继续" 消息让你继续处理。`;
+        }
+        if (delegate.type === 'memory_cleanup') {
+            return `你是一条专门处理 memory 容量整理的子 agent。
+
+以下 memory 类型/域已超过建议容量，需要整理：
+${urisText}
+
+请执行以下步骤（核心逻辑：处理 → 验证 → 未完成则继续）：
+
+=== 处理阶段 ===
+1. 调用 get_memory_stats 查看容量详情
+2. 调用 list_memories 按类型查看超限记忆
+3. 删除不再需要的 recently_memory，或更新 agent_memory 续期
+
+=== 验证阶段（关键，不可跳过） ===
+4. 再次调用 get_memory_stats 检查各类型/域的 count 是否已降到建议上限以下
+5. 仔细检查返回结果：
+   - ❌ 若仍有类型/域超过容量上限：输出 "经检查，以下类型/域尚未整理完成，请继续：" 列出具体类型/域和当前容量，然后回到步骤 1 继续处理
+   - ✅ 若全部在建议上限内：静默结束
+
+注意：你运行在独立的上下文窗口中，不影响主 agent 的主线任务。请高效完成，不要询问用户。
+完成后系统会通过查询服务端真实状态进行二次验证（不依赖你的自报结果）。若验证发现仍有类型/域超过容量上限，会发送 "经检查，以下类型/域尚未整理完成，请继续" 消息让你继续处理。`;
+        }
+        return `你是一条专门处理永久记忆文件变更更新的子 agent。
+
+以下 ${delegate.uris.length} 个永久记忆绑定的文件已发生变更：
+${urisText}
+
+请执行以下步骤（核心逻辑：更新 → 验证 → 未完成则继续）：
+
+=== 更新阶段 ===
+1. 调用 read_memory 读取这些 memory 的当前内容
+2. 查看相关绑定文件的最新内容（bound_files 中列出），理解变更点
+3. 调用 update_memory 更新 memory 内容，确保与文件最新状态同步
+
+=== 验证阶段（关键，不可跳过） ===
+4. 调用 read_memory 重新读取这些 memory，检查 memory_status 字段：
+   - 正常情况：Java 服务端会在 update_memory 后自动将 memory_status 恢复为 normal
+5. 仔细检查每个 memory 的状态：
+   - ❌ 若仍有 memory 的 memory_status 为 "updating"：说明更新未生效，输出 "经检查，未完成对以下 memory 的更新，请继续：" 列出具体 memory URI 和当前状态，然后回到步骤 1 继续处理
+   - ✅ 若全部 memory_status 为 "normal"：静默结束
+
+注意：你运行在独立的上下文窗口中，不影响主 agent 的主线任务。请高效完成，不要询问用户。
+完成后系统会通过查询服务端真实状态进行二次验证（不依赖你的自报结果）。若验证发现仍有 memory 的 memory_status 为 "updating"，会发送 "经检查，未完成对以下 memory 的更新，请继续" 消息让你继续处理。`;
+    }
+    /**
+     * 处理 poll_message 结果中的 memory 自动委托标记 (_acodeAutoDelegate)。
+     * 主流程：解析 MCP 返回 -> 识别标记 -> spawn 子 agent -> 返回简化结果。
+     * 非 ACode 运行时（无 subAgentManager）直接透传原结果，不受影响。
+     * 返回 null 表示全部消息已被委托，调用方应重新 poll_message 继续等待真正的消息。
+     */
+    async processMemoryAutoDelegates(mcpResult) {
+        const manager = this.config.subAgentManager;
+        if (!manager) {
+            return mcpResult;
+        }
+        // 提取 MCP 结果中的 JSON 文本
+        let resultText;
+        try {
+            resultText = toToolResultText(mcpResult);
+        }
+        catch {
+            return mcpResult;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(resultText);
+        }
+        catch {
+            return mcpResult;
+        }
+        const directMessages = parsed.directMessages;
+        if (!Array.isArray(directMessages) || directMessages.length === 0) {
+            return mcpResult;
+        }
+        const remainingMessages = [];
+        let delegateEncountered = 0;
+        for (const msg of directMessages) {
+            const delegate = msg._acodeAutoDelegate;
+            if (delegate && (delegate.type === 'memory_expiration' || delegate.type === 'memory_file_change' || delegate.type === 'memory_cleanup')) {
+                delegateEncountered++;
+                // 过滤掉已在处理中的 URI
+                const newUris = delegate.uris.filter(uri => !this.pendingMemorySubAgents.has(uri));
+                if (newUris.length === 0) {
+                    // 所有 URI 都在处理中，跳过此通知（不委托也不返回给主 agent）
+                    runtimeDebugLog(`[ACodeRuntime] Memory ${delegate.type} skipped: all ${delegate.uris.length} URIs already being processed by sub-agents`);
+                    continue;
+                }
+                // 用过滤后的 URI 构造 prompt
+                const prompt = this.buildMemoryDelegatePrompt({
+                    type: delegate.type,
+                    uris: newUris,
+                });
+                try {
+                    const subId = await manager.spawn({
+                        parentAgentId: this.config.agentId || 'unknown',
+                        parentSessionId: this.config.sessionId,
+                        subagentType: 'general',
+                        description: `Memory ${delegate.type} auto-delegate (${newUris.length} items)`,
+                        prompt,
+                        workingDirectory: this.config.workingDirectory,
+                        parentConfig: {
+                            ...this.config,
+                            // 注入父 agent 的 MCP 连接，子 agent 复用而非启动新 MCP server 进程
+                            sharedMcpConnections: this.state?.mcpConnections,
+                        },
+                        silent: true,
+                    });
+                    // 注册完成回调：子 agent 终态时从跟踪表中移除对应 URI
+                    for (const uri of newUris) {
+                        this.pendingMemorySubAgents.set(uri, subId);
+                    }
+                    const uriSet = new Set(newUris);
+                    manager.subscribe(subId, () => {
+                        const entry = manager.getSubAgent(subId);
+                        if (entry && (entry.status === 'completed' || entry.status === 'failed' || entry.status === 'cancelled')) {
+                            for (const uri of uriSet) {
+                                if (this.pendingMemorySubAgents.get(uri) === subId) {
+                                    this.pendingMemorySubAgents.delete(uri);
+                                }
+                            }
+                        }
+                    });
+                    // 使用带 recheck 循环的启动方式：
+                    // 每轮 submit 完成后，通过 recheckMemoryDelegate 查询服务端真实状态，
+                    // 若 memory 仍未处理好（memory_status=updating / 仍过期 / 容量仍超限），
+                    // 则将 "经检查，未完成对xxx的处理，请继续" 注入同一 sub-agent 的下一轮 submit。
+                    // 最多重试 3 次，提供系统级硬保证（不依赖 LLM 自报结果）。
+                    const delegateType = delegate.type;
+                    const recheckFn = async (output, turn) => {
+                        return this.recheckMemoryDelegate(delegateType, newUris, output, turn);
+                    };
+                    await manager.startWithRecheck(subId, recheckFn, 3);
+                    runtimeDebugLog(`[ACodeRuntime] Auto-delegated memory ${delegate.type} to sub-agent ${subId} (${newUris.length} URIs, ${delegate.uris.length - newUris.length} already in progress)`);
+                }
+                catch (e) {
+                    // 委托失败时不返回给主 agent：memory 通知不应打断主 agent 的主线任务，
+                    // 下次 poll_message 会重新检测并重试委托
+                    runtimeDebugLog(`[ACodeRuntime] Failed to auto-delegate memory ${delegate.type} (suppressed, will retry next poll): ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            else {
+                remainingMessages.push(msg);
+            }
+        }
+        // 未遇到任何 delegate 消息，原样返回（保留原始格式，避免不必要的对象创建）
+        if (delegateEncountered === 0) {
+            return mcpResult;
+        }
+        // 全部 delegate 消息已处理（spawned/skipped/failed），不返回给主 agent
+        if (remainingMessages.length === 0) {
+            return null;
+        }
+        // 有非 delegate 类型的剩余消息，返回简化后的结果
+        const simplified = {
+            ...parsed,
+            directMessages: remainingMessages,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(simplified, null, 2),
+                },
+            ],
+        };
+    }
+    /**
+     * poll_message MCP 工具调用的子 agent 完成事件 race 包装器。
+     *
+     * 主流程：
+     * 1. 先检查 completionQueue 中是否有已完成的子 agent -> 有则直接返回合成结果（不调 MCP）
+     * 2. 启动 MCP poll_message 调用与 waitForAnyCompletion 的 race
+     * 3. 子 agent 先完成 -> 返回合成结果（MCP 调用被放弃但仍在运行，下次 poll_message 会复用 pendingPollMessage）
+     * 4. MCP 先返回 -> 合并新完成的子 agent 事件后返回
+     *
+     * 设计说明：
+     * - MCP server 的 poll_message 内部有 while(true) 永久阻塞，只在有消息时返回
+     * - 子 agent 完成事件由 SubAgentManager 在同进程内产生，通过 completionQueue 传递
+      * - 当子 agent 先完成时，MCP 调用被放弃（Promise 不再被 await），MCP server 侧的
+      *   pendingPollMessage 仍在运行，下次 poll_message 调用会通过 pendingPollMessage 复用
+      */
+    async callPollMessageWithSubAgentRace(connection, tool, toolArguments, timeoutMs) {
+        const manager = this.config.subAgentManager;
+        // 没有 SubAgentManager 时，直接走普通 MCP 调用
+        if (!manager) {
+            return await this.callMcpToolWithTimeout(connection, tool, toolArguments, timeoutMs, true);
+        }
+        // 步骤1: 先检查是否有已完成的子 agent -> 有则直接返回合成结果（不调 MCP）
+        const completedBefore = manager.takeCompletedSubAgents();
+        if (completedBefore.length > 0) {
+            runtimeDebugLog(`[ACodeRuntime] poll_message: ${completedBefore.length} sub-agent(s) already completed, returning synthetic result`);
+            return ACodeRuntime.formatSubAgentCompletionAsPollResult(completedBefore);
+        }
+        // 循环：MCP 返回的 memory 通知被全部委托时，重新 poll 继续等待真正的消息
+        let isDelegateRepoll = false; // 首次正常上报，后续委托循环中抑制状态跳动
+        while (true) {
+            // 步骤2: 启动 MCP poll_message 调用与 waitForAnyCompletion 的 race
+            const subAgentWaiter = manager.waitForAnyCompletion();
+            // 委托等待循环中的后续 poll 注入标记：MCP server 跳过 reportToolUse/reportToolResult，
+            // 只调用 reportThinking 保持"思考中"状态，避免"调用MCP↔思考中"反复跳动
+            const pollArgs = isDelegateRepoll
+                ? { ...toolArguments, _aws_silent_poll: true }
+                : toolArguments;
+            const mcpCallPromise = this.callMcpToolWithTimeout(connection, tool, pollArgs, timeoutMs, true);
+            try {
+                const raceWinner = await Promise.race([
+                    mcpCallPromise.then((result) => ({ type: "mcp", result })),
+                    subAgentWaiter.promise.then((notif) => ({ type: "subagent", notif })),
+                ]);
+                if (raceWinner.type === "subagent") {
+                    // 步骤3: 子 agent 先完成 -> 返回合成结果
+                    // 收集所有已完成的子 agent（race 中 resolve 的 + 队列中可能已积累的）
+                    const notifications = manager.takeCompletedSubAgents();
+                    // raceWinner.notif 可能已从队列中取出（waitForAnyCompletion 内部处理），
+                    // 也可能仍在队列中（如果 takeCompletedSubAgents 先执行）
+                    if (notifications.length === 0) {
+                        notifications.push(raceWinner.notif);
+                    }
+                    runtimeDebugLog(`[ACodeRuntime] poll_message: sub-agent ${raceWinner.notif.subId} completed during race, returning synthetic result (${notifications.length} notification(s))`);
+                    return ACodeRuntime.formatSubAgentCompletionAsPollResult(notifications);
+                }
+                // 步骤4: MCP 先返回 -> 合并新完成的子 agent 事件
+                const completedAfter = manager.takeCompletedSubAgents();
+                if (completedAfter.length > 0) {
+                    runtimeDebugLog(`[ACodeRuntime] poll_message: MCP returned, merging ${completedAfter.length} sub-agent completion(s)`);
+                    const merged = ACodeRuntime.mergeSubAgentCompletionsIntoMcpResult(raceWinner.result, completedAfter);
+                    // 合并后仍需检查 memory 自动委托
+                    const processedMerged = await this.processMemoryAutoDelegates(merged);
+                    if (processedMerged !== null) {
+                        // 校验：结果必须包含实际消息才返回，否则继续 poll
+                        if (this.pollResultHasMessages(processedMerged)) {
+                            return processedMerged;
+                        }
+                    }
+                    // 全部被委托或结果为空，等待后再重新 poll（防止紧密循环）
+                    await this.waitForDelegateRepoll();
+                    isDelegateRepoll = true;
+                    continue;
+                }
+                // 自动委托：识别 memory 过期/更新通知，spawn 子 agent 处理，避免打断主 agent 主线
+                const processedResult = await this.processMemoryAutoDelegates(raceWinner.result);
+                if (processedResult !== null) {
+                    // 校验：结果必须包含实际消息才返回，否则继续 poll
+                    if (this.pollResultHasMessages(processedResult)) {
+                        return processedResult;
+                    }
+                }
+                // 全部被委托或结果为空，等待后再重新 poll（防止紧密循环）
+                await this.waitForDelegateRepoll();
+                isDelegateRepoll = true;
+            }
+            finally {
+                subAgentWaiter.cancel();
+            }
+        }
+    }
+    /**
+     * 检查 poll_message 结果是否包含实际消息（directMessages 或 groupMessages 非空）。
+     * 用于循环中过滤空结果，确保 poll_message 只在有消息时返回。
+     */
+    pollResultHasMessages(result) {
+        try {
+            const text = toToolResultText(result);
+            const parsed = JSON.parse(text);
+            const dm = Array.isArray(parsed.directMessages) ? parsed.directMessages.length : 0;
+            const gm = Array.isArray(parsed.groupMessages) ? parsed.groupMessages.length : 0;
+            return dm > 0 || gm > 0;
+        }
+        catch {
+            return true; // 无法解析时保守返回 true，避免无限循环
+        }
+    }
+    /**
+     * 在 memory 委托消息被全部处理后，等待一段时间再重新 poll_message。
+     *
+     * 背景：MCP doPollMessage 对 updating memory 每次都返回通知（无去重），
+     * 而 processMemoryAutoDelegates 因 URI 已在 pendingMemorySubAgents 中而返回 null，
+     * 导致 while(true) 无延迟重 poll，每轮触发 handleToolCall 的 reportToolUse/reportThinking
+     * 状态上报，引发"思考→MCP→跳过"快速循环，最终连接丢失。
+     *
+     * 等待策略：
+     * 1. 固定延迟 DELEGATE_REPOLL_DELAY_MS（5s），给子 agent 时间完成 memory 更新
+     * 2. 可被 runtime stop 中断（通过 createRuntimeStopWaiter）
+     * 3. 不消费 completionQueue（下一轮 takeCompletedSubAgents 会取到）
+     */
+    async waitForDelegateRepoll() {
+        runtimeDebugLog(`[ACodeRuntime] poll_message: all messages delegated, waiting ${DELEGATE_REPOLL_DELAY_MS}ms before re-poll`);
+        const stopWaiter = this.createRuntimeStopWaiter("delegate re-poll delay");
+        try {
+            await Promise.race([
+                new Promise((resolve) => {
+                    const timer = setTimeout(resolve, DELEGATE_REPOLL_DELAY_MS);
+                    if (timer.unref)
+                        timer.unref();
+                }),
+                stopWaiter.promise,
+            ]);
+        }
+        finally {
+            stopWaiter.cancel();
+        }
+    }
     /**
      * Build a one-shot waiter that rejects long-running MCP calls when the runtime stops.
      * Main flow: register a stop callback -> race it with the SDK call -> remove it after either side settles.
@@ -1776,7 +3309,7 @@ export class ACodeRuntime extends EventEmitter {
             notifyStop();
         }
     }
-    async appendSyntheticMultimodalUserMessage(toolResultText, contextVersion = this.contextVersion) {
+    async appendSyntheticMultimodalUserMessage(toolResultText, toolCallId, contextVersion = this.contextVersion) {
         const parsedContent = parseAttachmentMessage(toolResultText);
         if (!parsedContent.hasImages) {
             return;
@@ -1792,11 +3325,50 @@ export class ACodeRuntime extends EventEmitter {
             return;
         }
         this.state.conversation.push({ role: "user", content });
+        // 去重：将对应 tool 消息中的图片/附件数据替换为占位符，
+        // 避免 conversation 中同时存在原始 tool 结果和解析后的 user 消息导致重复。
+        const toolMsg = this.state.conversation.find((m) => m.role === "tool" && m.tool_call_id === toolCallId);
+        if (toolMsg && typeof toolMsg.content === "string") {
+            let cleaned;
+            // 尝试 JSON 格式：移除 attachments 数组，保留 text 和 messages
+            try {
+                const parsed = JSON.parse(toolMsg.content);
+                if (typeof parsed === "object" && parsed !== null) {
+                    const clone = { ...parsed };
+                    if ("attachments" in clone) {
+                        delete clone.attachments;
+                        cleaned = JSON.stringify(clone);
+                    }
+                }
+            }
+            catch {
+                // 不是 JSON，尝试 marker 格式
+            }
+            if (cleaned === undefined) {
+                const markerCleaned = toolMsg.content
+                    .replace(/\[(图片|文件)\s*:\s*([^\]\n]*?)\s*\]/gi, "")
+                    .trim();
+                if (markerCleaned !== toolMsg.content) {
+                    cleaned = markerCleaned;
+                }
+            }
+            if (cleaned !== undefined && cleaned.length > 0) {
+                toolMsg.content = cleaned;
+            }
+            else if (cleaned !== undefined) {
+                toolMsg.content = "[Tool result contained images; see user message above]";
+            }
+        }
     }
     appendToolFailureResult(toolCall, tool, error) {
         const resultText = toToolErrorResultText(tool, error);
+        runtimeDebugLog(`[ACodeRuntime] 📤 appendToolFailureResult: emitting mcp_status tool_result ` +
+            `(failed: true) for ${tool.exposedName}, result length: ${resultText.length} chars`);
+        // 工具执行失败是正常运行过程的一部分（Agent 会继续处理失败结果）。
+        // 标记 nonFatal=true 让 adapter 不变更运行态为 "error"，避免面板按钮异常。
         this.emitAcodeEvent("error", {
             message: `ACode tool failed: ${tool.exposedName}: ${getErrorMessage(error)}`,
+            nonFatal: true,
         });
         this.emitAcodeEvent("mcp_status", {
             action: "tool_result",
@@ -1811,6 +3383,21 @@ export class ACodeRuntime extends EventEmitter {
             content: resultText,
         });
     }
+    /**
+     * 为子 agent 过滤共享 MCP 连接：只保留 memory 工具。
+     *
+     * 原 MCP server 进程通过 AWS_SUB_AGENT=true 限制子 agent 只能调用 memory 工具，
+     * 共享连接后绕过了该机制。此方法在 ACode runtime 层重新施加限制：
+     *   - 复用同一 client/transport（不创建新连接）
+     *   - 仅暴露 MEMORY_TOOL_NAMES 中的工具
+     *   - 防止子 agent 调用 poll_message（与父 agent 冲突）、send_group 等
+     */
+    filterSharedMcpConnectionsForSubAgent(connections) {
+        return connections.map((conn) => ({
+            ...conn,
+            tools: conn.tools.filter((tool) => SUB_AGENT_ALLOWED_MCP_TOOLS.has(tool.toolName)),
+        }));
+    }
     async connectMcpServers(servers, timeoutMs) {
         const connections = [];
         for (const [serverName, serverSpec] of Object.entries(servers)) {
@@ -1869,7 +3456,70 @@ export class ACodeRuntime extends EventEmitter {
             requestInit,
         });
     }
+    /**
+     * 通过 MCP 连接调用 get_profile 工具获取用户 profile 信息，
+     * 格式化为文本后返回，用于拼接到 rolePrompt 下方。
+     * 主流程：遍历已连接的 MCP -> 找到 get_profile 工具 -> 调用 -> 格式化结果。
+     * 容错：任何步骤失败都返回空字符串，不阻塞启动。
+     */
+    async fetchProfilePrompt(mcpConnections) {
+        for (const connection of mcpConnections) {
+            const profileTool = connection.tools.find((tool) => tool.toolName === "get_profile");
+            if (!profileTool) {
+                continue;
+            }
+            try {
+                const result = await withTimeout(connection.client.callTool({ name: "get_profile", arguments: {} }, undefined, { timeout: DEFAULT_MCP_TOOL_CALL_TIMEOUT_MS }), DEFAULT_MCP_TOOL_CALL_TIMEOUT_MS, "ACode startup get_profile");
+                const profile = this.extractProfileFromToolResult(result);
+                return buildProfilePrompt(profile);
+            }
+            catch (error) {
+                this.emitAcodeEvent("warning", {
+                    message: `ACode failed to fetch profile via ${connection.serverName}/get_profile: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                return "";
+            }
+        }
+        return "";
+    }
+    /**
+     * 从 MCP callTool 返回值中提取 profile 对象。
+     * 主流程：优先取 content[0].text JSON -> 回退到 result 本身为对象。
+     */
+    extractProfileFromToolResult(result) {
+        if (!isRecord(result)) {
+            return null;
+        }
+        const content = result.content;
+        if (Array.isArray(content)) {
+            for (const item of content) {
+                if (!isRecord(item))
+                    continue;
+                if (typeof item.text === "string" && item.text.trim()) {
+                    try {
+                        const parsed = JSON.parse(item.text);
+                        if (isRecord(parsed)) {
+                            return parsed;
+                        }
+                    }
+                    catch {
+                        // text 不是 JSON，继续
+                    }
+                }
+            }
+        }
+        if (isRecord(result)) {
+            return result;
+        }
+        return null;
+    }
     async disconnectMcpServers() {
+        // 共享连接（子 agent）不关闭，由所有者（父 agent）管理生命周期
+        if (!this.state.ownsMcpConnections) {
+            this.state.mcpConnections = [];
+            this.state.exposedTools = [];
+            return;
+        }
         const connections = this.state.mcpConnections;
         this.state.mcpConnections = [];
         this.state.exposedTools = [];
@@ -1878,3 +3528,5 @@ export class ACodeRuntime extends EventEmitter {
         }, this.state.provider.mcpToolTimeoutMs)));
     }
 }
+/** skill 重扫防抖间隔（毫秒） */
+ACodeRuntime.SKILL_REFRESH_DEBOUNCE_MS = 500;