@zqagent/core 0.1.30 → 0.2.4

package/dist/tools/explore.js

@@ -1,3 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/tools/ToolRegistry.ts
 var ToolRegistry = class {
   /** 工具名 → 工具规格 的映射表 */
@@ -72,12 +79,13 @@ var ToolRegistry = class {
   /**
    * 执行工具
    *
+   * @param ctx 执行上下文（引擎注入的中断信号等）
    * @throws 工具未注册时抛出错误
    */
-  execute(name, args) {
+  execute(name, args, ctx) {
     const spec = this.tools.get(name);
     if (!spec) throw new Error(`Tool not registered: ${name}`);
-    return spec.func(args);
+    return spec.func(args, ctx);
   }
   /**
    * 构建默认 Schema
@@ -103,15 +111,77 @@ function contextTokens(u) {
   return u.input + u.cacheRead + u.cacheWrite;
 }
 
+// src/providers/diagnostics.ts
+function isNetworkErrorText(text) {
+  const t = text.toLowerCase();
+  return [
+    "connection error",
+    "fetch failed",
+    "econnreset",
+    "econnrefused",
+    "etimedout",
+    "ehostunreach",
+    "enetunreach",
+    "enotfound",
+    "eai_again",
+    "socket hang up",
+    "und_err",
+    "network",
+    "timed out",
+    "tls",
+    "certificate",
+    "unable_to_verify",
+    "self signed"
+  ].some((m) => t.includes(m));
+}
+function asRecord(v) {
+  return v && typeof v === "object" ? v : null;
+}
+function causeChain(err, maxNodes = 6) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [err];
+  while (queue.length > 0 && out.length < maxNodes) {
+    const cur = queue.shift();
+    if (!cur || typeof cur !== "object" || seen.has(cur)) continue;
+    seen.add(cur);
+    const rec = asRecord(cur);
+    if (!rec) continue;
+    out.push(rec);
+    if (rec["cause"]) queue.push(rec["cause"]);
+    const errs = rec["errors"];
+    if (Array.isArray(errs)) queue.push(...errs);
+  }
+  return out;
+}
+function isErrorCodeLike(v) {
+  return /^[A-Z][A-Z0-9_]*$/.test(v);
+}
+function errorCode(err) {
+  for (const src of causeChain(err)) {
+    for (const k of ["code", "errno"]) {
+      const v = src[k];
+      if (typeof v === "string" && v) return v;
+    }
+    const name = src["name"];
+    if (typeof name === "string" && name !== "Error" && isErrorCodeLike(name)) {
+      return name;
+    }
+  }
+  return void 0;
+}
+
 // src/engine/compaction.ts
 var DEFAULT_THRESHOLD_PCT = 0.8;
-var DEFAULT_CAP_TOKENS = 25e4;
 var DEFAULT_CONTEXT_WINDOW = 128e3;
 var MODEL_CONTEXT_WINDOWS = {
   // ==================== OpenAI ====================
-  // 来源: OpenAI官方API文档
+  // 来源: OpenAI 官方 API 文档 (platform.openai.com/docs/models)
   "gpt-5.5": 105e4,
   "gpt-5.4": 105e4,
+  "gpt-4.1": 1047576,
+  "gpt-4.1-mini": 1047576,
+  "gpt-4.1-nano": 1047576,
   "gpt-4o": 128e3,
   "gpt-4o-mini": 128e3,
   "gpt-4-turbo": 128e3,
@@ -123,52 +193,86 @@ var MODEL_CONTEXT_WINDOWS = {
   "o1-mini": 128e3,
   o3: 2e5,
   "o3-mini": 2e5,
+  o4: 2e5,
+  "o4-mini": 2e5,
   // ==================== Anthropic ====================
-  // 注: Claude系列模型上下文窗口多为200K，但Claude 4系列在特定平台(如Amazon Bedrock)可能支持更高
+  // 来源: Anthropic 官方文档 (docs.anthropic.com)
+  // 注: Claude 系列模型上下文窗口均为 200K
   "claude-3-opus": 2e5,
   "claude-3-sonnet": 2e5,
   "claude-3-haiku": 2e5,
   "claude-3.5-sonnet": 2e5,
+  "claude-3.5-haiku": 2e5,
   "claude-4-sonnet": 2e5,
-  // 基础窗口，实际可能因部署平台而异
   "claude-4-opus": 2e5,
+  "claude-opus-4": 2e5,
+  "claude-sonnet-4": 2e5,
   // ==================== Google Gemini ====================
-  // 来源: Google Colab及OpenRouter
-  // 注: Gemini模型以超大上下文窗口著称，部分版本支持2M
+  // 来源: Google AI 官方文档 (ai.google.dev)
+  // 注: Gemini 模型以超大上下文窗口著称
+  "gemini-2.5-pro": 2e6,
+  "gemini-2.5-flash": 1e6,
+  "gemini-2.0-flash": 1048576,
   "gemini-3-pro": 2e6,
-  // 最高支持2M
   "gemini-3-flash": 1e6,
-  // 支持1M
   // ==================== Meta Llama ====================
-  // 来源: NVIDIA NIM文档及Oracle Cloud文档
+  // 来源: NVIDIA NIM 文档及 Oracle Cloud 文档
   // 注意: 不同部署平台的上下文长度可能有差异
   "llama-4-scout": 128e3,
-  // 实际部署中常见128K
   "llama-4-maverick": 512e3,
-  // 支持512K
   "llama-3.3": 128e3,
   "llama-3.1": 128e3,
+  "llama-3": 128e3,
   // ==================== DeepSeek ====================
-  // 来源: 基于DeepSeek-V4系列公开信息
-  // 注: DeepSeek-V4系列两款模型均支持100万(1M)上下文窗口
+  // 来源: DeepSeek 官方文档 (api-docs.deepseek.com)
+  // 注: deepseek-flash 当前由 DeepSeek-V4.1-Flash 提供服务，上下文 1M
+  "deepseek-flash": 1e6,
+  "deepseek-v4.1-flash": 1e6,
   "deepseek-v4-pro": 1e6,
   "deepseek-v4-flash": 1e6,
   "deepseek-v3": 128e3,
   "deepseek-r1": 128e3,
-  // ==================== Alibaba Qwen ====================
-  // 来源: Replicate平台模型卡片
-  // 注: Qwen 3.5/3.6系列原生支持262K，可扩展至1M
+  "deepseek-reasoner": 128e3,
+  // ==================== Alibaba Qwen (通义千问) ====================
+  // 来源: 阿里云百炼文档 (help.aliyun.com/zh/model-studio)
+  // 注: Qwen3.8 系列支持 1M，Qwen3.5/3.6 原生 262K
+  "qwen3.8-max": 1e6,
+  "qwen3.8-flash": 1e6,
+  "qwen3.7-max": 1e6,
+  "qwen3.7-plus": 1e6,
+  "qwen3.6": 262144,
+  "qwen3.5": 262144,
   "qwen-3.5": 262144,
-  // 原生262K，可扩展至1M
   "qwen-3.6": 262144,
-  // 原生262K，可扩展至1M
+  "qwen-max": 128e3,
+  "qwen-plus": 128e3,
+  "qwen-turbo": 128e3,
+  // ==================== 智谱 GLM ====================
+  // 来源: 智谱 AI 开放文档 (docs.bigmodel.cn)
+  "glm-5.3": 128e3,
+  "glm-5.2": 128e3,
+  "glm-4-plus": 128e3,
+  "glm-4-flash": 128e3,
+  "glm-4": 128e3,
+  // ==================== Kimi / Moonshot ====================
+  // 来源: Moonshot API 文档 (platform.moonshot.cn/docs)
+  "kimi-k3": 256e3,
+  "kimi-k2.7": 256e3,
+  "kimi-k2.6": 256e3,
+  "kimi-k2": 256e3,
+  "moonshot-v1-128k": 128e3,
+  "moonshot-v1-32k": 32e3,
+  "moonshot-v1-8k": 8e3,
+  // ==================== 小米 MiMo ====================
+  "mimo-v2.5-pro": 128e3,
   // ==================== Mistral ====================
-  // 来源: AWS Bedrock文档
+  // 来源: Mistral AI 官方文档及 AWS Bedrock 文档
   "mistral-large-3": 256e3,
-  // ==================== Others ====================
-  // 来源: Kimi官方博客及智谱AI开放文档
-  "kimi-k2": 256e3,
-  "glm-4-plus": 128e3
+  "mistral-large": 128e3,
+  "mistral-small": 128e3,
+  "mixtral-8x22b": 65536,
+  // ==================== MiniMax ====================
+  "minimax-m3": 1e6
 };
 function lookupContextWindow(modelId) {
   const lower = modelId.toLowerCase();
@@ -195,9 +299,13 @@ function estimateTokens(messages) {
   }
   return Math.floor(total / 4);
 }
-function triggerTokens(contextWindow, thresholdPct = DEFAULT_THRESHOLD_PCT, capTokens = DEFAULT_CAP_TOKENS) {
+function triggerTokens(contextWindow, thresholdPct = DEFAULT_THRESHOLD_PCT, capTokens) {
   const window = contextWindow ?? DEFAULT_CONTEXT_WINDOW;
-  return Math.min(Math.floor(thresholdPct * window), capTokens);
+  const base = Math.floor(thresholdPct * window);
+  if (capTokens != null && Number.isFinite(capTokens) && capTokens > 0) {
+    return Math.min(base, Math.floor(capTokens));
+  }
+  return base;
 }
 function shouldCompact(signal, contextWindow, thresholdPct, capTokens) {
   return signal >= triggerTokens(contextWindow, thresholdPct, capTokens);
@@ -553,12 +661,21 @@ var EXPLORER_INSTRUCTIONS = `\u4F60\u662F\u4E00\u4E2A\u53EA\u8BFB\u7684\u4EE3\u7
 3. **\u5305\u542B\u5173\u952E\u4EE3\u7801\u7247\u6BB5** \u2014 \u6458\u5F55\u6700\u76F8\u5173\u7684\u4EE3\u7801\uFF08\u4E0D\u662F\u6574\u6BB5\u590D\u5236\uFF0C\u53EA\u4FDD\u7559\u6838\u5FC3\u903B\u8F91\uFF09
 4. **\u8BB0\u5F55\u610F\u5916\u53D1\u73B0** \u2014 \u6CBF\u9014\u53D1\u73B0\u7684\u4EFB\u4F55\u503C\u5F97\u6CE8\u610F\u7684\u7EC6\u8282\u3001\u4E0D\u4E00\u81F4\u3001\u6F5C\u5728\u95EE\u9898
 5. **\u58F0\u660E\u641C\u7D22\u8303\u56F4** \u2014 \u5982\u679C\u627E\u4E0D\u5230\u67D0\u4E9B\u5185\u5BB9\uFF0C\u660E\u786E\u8BF4\u660E\u4F60\u641C\u7D22\u4E86\u4EC0\u4E48\u3001\u5C1D\u8BD5\u4E86\u4EC0\u4E48\uFF0C\u907F\u514D\u8C03\u7528\u65B9\u91CD\u590D\u641C\u7D22`;
-var GEN_SESSION_NAME_INSTRUCTIONS = `\u4F60\u662F\u4E00\u4E2A\u4F1A\u8BDD\u547D\u540D\u52A9\u624B\u3002\u6839\u636E\u7528\u6237\u7684\u8F93\u5165\uFF0C\u751F\u6210\u4E00\u4E2A\u7B80\u77ED\u3001\u6E05\u6670\u3001\u63CF\u8FF0\u6027\u7684\u4F1A\u8BDD\u540D\u79F0\u3002\u540D\u79F0\u5E94\u6982\u62EC\u4F1A\u8BDD\u7684\u4E3B\u8981\u4E3B\u9898\u6216\u76EE\u6807\uFF0C\u907F\u514D\u4F7F\u7528\u6A21\u7CCA\u6216\u901A\u7528\u7684\u8BCD\u6C47\u3002`;
+var GEN_SESSION_NAME_INSTRUCTIONS = `\u4F60\u662F\u4E00\u4E2A\u4F1A\u8BDD\u547D\u540D\u52A9\u624B\u3002\u6839\u636E\u7528\u6237\u7684\u8F93\u5165\uFF0C\u751F\u6210\u4E00\u4E2A\u7B80\u77ED\u3001\u6E05\u6670\u3001\u63CF\u8FF0\u6027\u7684\u4F1A\u8BDD\u540D\u79F0\u3002\u540D\u79F0\u5E94\u6982\u62EC\u4F1A\u8BDD\u7684\u4E3B\u8981\u4E3B\u9898\u6216\u76EE\u6807\uFF0C\u907F\u514D\u4F7F\u7528\u6A21\u7CCA\u6216\u901A\u7528\u7684\u8BCD\u6C47\u3002
+
+\u8981\u6C42\uFF1A
+1. \u53EA\u8F93\u51FA\u540D\u79F0\u672C\u8EAB\uFF0C\u4E0D\u8981\u5F15\u53F7\u3001\u6807\u70B9\u3001\u6362\u884C\u6216\u4EFB\u4F55\u89E3\u91CA\uFF1B
+2. \u540D\u79F0\u4E0D\u8D85\u8FC7 20 \u4E2A\u5B57\u7B26\u3002`;
 
 // src/engine/TurnEngine.ts
 function genReqId() {
   return crypto.randomBytes(6).toString("base64url");
 }
+var INTERACTIVE_TOOLS = /* @__PURE__ */ new Set([
+  "ask_user",
+  "propose_plan",
+  "request_directory"
+]);
 function toolResultMessage(tc, result, taskId) {
   const content = typeof result === "string" ? result : JSON.stringify(result, null, 2);
   return {
@@ -605,6 +722,23 @@ function preview(value, maxLen = 200) {
   const flat = text.replace(/\n/g, "\\n");
   return flat.length <= maxLen ? flat : flat.slice(0, maxLen - 3) + "...";
 }
+function isTransientNetworkError(exc) {
+  const status = exc?.status;
+  if (typeof status === "number") {
+    return false;
+  }
+  const msg = `${exc instanceof Error ? exc.message : String(exc)} ${errorCode(exc) ?? ""}`;
+  return isNetworkErrorText(msg);
+}
+function networkRetryMax() {
+  const n = Number(process.env.NETWORK_RETRY_MAX);
+  return Number.isFinite(n) && n >= 0 ? n : 2;
+}
+function networkRetryBaseMs() {
+  const n = Number(process.env.NETWORK_RETRY_BASE_MS);
+  return Number.isFinite(n) && n >= 0 ? n : 800;
+}
+var sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
 function isRetriableError(exc) {
   const status = exc?.status;
   if (typeof status === "number") {
@@ -615,6 +749,7 @@ function isRetriableError(exc) {
     (exc instanceof Error ? exc.message : exc) ?? ""
   ).toLowerCase();
   const markers = [
+    "connection error",
     "fetch failed",
     "econnreset",
     "etimedout",
@@ -647,6 +782,12 @@ var TurnEngine = class _TurnEngine {
   _hook;
   // 中断标记：requestInterrupt() 置位后，引擎在下一个安全点停止
   _cancel = false;
+  // 在飞的 LLM 流式中止句柄：requestInterrupt() 直接 abort，
+  // 否则流静默挂死时引擎永远等不到检查标志位的安全点
+  _llmAbort = null;
+  // 在一轮工具执行期间生效的中止句柄：requestInterrupt() 一并 abort，
+  // 使正在执行的可中断工具（run_shell）立即终止子进程，而不是等它自然结束
+  _toolAbort = null;
   // Steering 消息队列：外部排队注入的用户级指令，迭代间隙注入
   _steering = [];
   // 上下文压缩
@@ -654,6 +795,10 @@ var TurnEngine = class _TurnEngine {
   _lastContextTokens = null;
   /** 显式配置的上下文窗口大小（token 数），未设置时为 undefined（走自动检测） */
   _contextWindow;
+  /** 压缩触发阈值比例（默认 0.8） */
+  _thresholdPct;
+  /** 压缩触发阈值绝对上限（null = 不限制） */
+  _capTokens;
   // 产出文件追踪（本轮 Turn 中成功写入的文件）
   _producedFiles = [];
   _turnStartTime = 0;
@@ -700,18 +845,25 @@ var TurnEngine = class _TurnEngine {
     this.model = opts.model;
     this.instructions = opts.instructions;
     this.genSessionNamePrompt = opts.genSessionNamePrompt || GEN_SESSION_NAME_INSTRUCTIONS;
-    this.maxIterations = opts.maxIterations ?? 150;
+    this.maxIterations = opts.maxIterations ?? 300;
     this.messages = opts.messages ? [...opts.messages] : [];
     this._hook = opts.hook;
     this._contextWindow = opts.contextWindow;
+    this._thresholdPct = opts.thresholdPct ?? DEFAULT_THRESHOLD_PCT;
+    this._capTokens = opts.capTokens ?? null;
     this._reasoningEffort = opts.reasoningEffort;
     if (this.messages.length === 0 || this.messages[0].role !== "system") {
       this.messages.unshift({ role: "system", content: this.instructions });
     }
   }
-  /** 外部中断：置位取消标记，引擎会在安全点停止 */
+  /**
+   * 外部中断：置位取消标记 + 掐断在飞的 LLM 请求 + 中止正在执行的工具，
+   * 引擎随后按中断收尾
+   */
   requestInterrupt() {
     this._cancel = true;
+    this._llmAbort?.abort();
+    this._toolAbort?.abort();
   }
   /** 设置审批回调 */
   setApprover(approver) {
@@ -813,7 +965,10 @@ var TurnEngine = class _TurnEngine {
         {
           reqId: `llm_chat_${Date.now()}_${genReqId()}`,
           logTime: (/* @__PURE__ */ new Date()).toISOString()
-        }
+        },
+        // 不设 maxTokens：推理模型（deepseek 等）的思考会占用输出配额，
+        // 过小会导致 content 为空从而拿不到名称；命名 prompt 已约束只输出短标题。
+        {}
       );
       return name;
     }
@@ -844,6 +999,47 @@ var TurnEngine = class _TurnEngine {
     return [];
   }
   // ===================== 核心循环 =====================
+  /**
+   * 中断收尾：保留已流式输出的内容、记一条 interrupted 提示，
+   * 产出 INTERRUPTED + TURN_END 事件并结束本轮。
+   *
+   * 两处调用：流式结束后发现取消标记、以及流被 abort 中断抛错时。
+   */
+  *_finishInterrupted(args) {
+    const { iterations, reqId, streamed, streamedThinking } = args;
+    if (streamed) {
+      this.messages.push(
+        assistantMessage(
+          {
+            text: streamed,
+            toolCalls: [],
+            finishReason: null,
+            reasoning: streamedThinking || null,
+            usage: null
+          },
+          this.model,
+          this.taskId
+        )
+      );
+    }
+    this._appendNotice("interrupted");
+    this._emitHook((h) => h.onInterrupted?.(iterations));
+    yield {
+      type: "interrupted" /* INTERRUPTED */,
+      data: { iterations, reqId, taskId: this.taskId }
+    };
+    const files = this._buildProducedFiles();
+    yield {
+      type: "turn_end" /* TURN_END */,
+      data: {
+        status: "interrupted",
+        iterations,
+        produced_files: files,
+        taskId: this.taskId
+      }
+    };
+    this._emitHook((h) => h.onTurnEnd?.("interrupted", iterations, files));
+  }
   /**
    * 核心迭代循环
    *
@@ -853,6 +1049,8 @@ var TurnEngine = class _TurnEngine {
    */
   async *_loop() {
     let iterations = 0;
+    let netRetries = 0;
+    const netMax = networkRetryMax();
     while (true) {
       if (iterations >= this.maxIterations) {
         const files = this._buildProducedFiles();
@@ -884,23 +1082,26 @@ var TurnEngine = class _TurnEngine {
         };
         this._emitHook((h) => h.onEvent?.("llm_request" /* LLM_REQUEST */, llmReqData));
         yield { type: "llm_request" /* LLM_REQUEST */, data: llmReqData };
-        this._emitHook((h) => h.onCompacting?.());
-        yield { type: "compacting" /* COMPACTING */, data: { taskId: this.taskId } };
+        const startInfo = this._compactionStartInfo("threshold");
+        this._emitHook((h) => h.onCompacting?.(startInfo));
+        yield {
+          type: "compacting" /* COMPACTING */,
+          data: { taskId: this.taskId, ...startInfo }
+        };
         const result = await this._compactNow(compactReqId);
         if (result.notice) {
           compactionNotice = result.notice;
           this._appendNotice("compacted", result.notice);
-          this._emitHook(
-            (h) => h.onCompacted?.(
-              this.compactionState ? "\u4E0A\u4E0B\u6587\u5DF2\u538B\u7F29" : "\u4E0A\u4E0B\u6587\u5DF2\u88C1\u526A"
-            )
-          );
+          const doneInfo = this._compactionDoneInfo(result);
+          this._emitHook((h) => h.onCompacted?.(result.notice, doneInfo));
           yield {
             type: "compacted" /* COMPACTED */,
             data: {
               reqId: compactReqId,
               taskId: this.taskId,
               method: result.method,
+              messagesBefore: doneInfo.messagesBefore,
+              messagesAfter: doneInfo.messagesAfter,
               ...result.boundaryIndex !== void 0 ? { boundaryIndex: result.boundaryIndex } : {},
               ...result.modelUsed ? { model: result.modelUsed } : {},
               ...result.summaryPreview ? { summaryPreview: result.summaryPreview } : {},
@@ -928,11 +1129,18 @@ var TurnEngine = class _TurnEngine {
         };
         this._emitHook((h) => h.onEvent?.("llm_request" /* LLM_REQUEST */, llmReqData));
         yield { type: "llm_request" /* LLM_REQUEST */, data: llmReqData };
+        this._llmAbort = new AbortController();
+        if (this._cancel) this._llmAbort.abort();
         const chunks = await this.provider.stream(
           this.model,
           outbound,
           schemas,
-          { reqId, logTime, reasoningEffort: this._reasoningEffort }
+          {
+            reqId,
+            logTime,
+            reasoningEffort: this._reasoningEffort,
+            signal: this._llmAbort.signal
+          }
         );
         for await (const chunk of chunks) {
           if (this._cancel) break;
@@ -965,6 +1173,15 @@ var TurnEngine = class _TurnEngine {
           }
         }
       } catch (exc) {
+        if (this._cancel && turn === null) {
+          yield* this._finishInterrupted({
+            iterations,
+            reqId,
+            streamed,
+            streamedThinking
+          });
+          return;
+        }
         const overflow = isContextOverflow(exc);
         if (overflow && !this._cancel) {
           const overflowReqId = `compact_${Date.now()}_${genReqId()}`;
@@ -978,22 +1195,31 @@ var TurnEngine = class _TurnEngine {
           };
           this._emitHook((h) => h.onEvent?.("llm_request" /* LLM_REQUEST */, llmReqData));
           yield { type: "llm_request" /* LLM_REQUEST */, data: llmReqData };
-          this._emitHook((h) => h.onCompacting?.());
-          yield { type: "compacting" /* COMPACTING */, data: { taskId: this.taskId } };
+          const startInfo = this._compactionStartInfo("overflow");
+          this._emitHook((h) => h.onCompacting?.(startInfo));
+          yield {
+            type: "compacting" /* COMPACTING */,
+            data: { taskId: this.taskId, ...startInfo }
+          };
           const result = await this._compactNow(overflowReqId, true);
           if (result.notice) {
             const notice = result.notice;
             this._appendNotice("compacted", notice);
-            this._emitHook((h) => h.onCompacted?.(notice));
+            const doneInfo = this._compactionDoneInfo(result);
+            this._emitHook((h) => h.onCompacted?.(notice, doneInfo));
             yield {
               type: "compacted" /* COMPACTED */,
               data: {
                 reqId: overflowReqId,
                 taskId: this.taskId,
                 method: result.method,
+                messagesBefore: doneInfo.messagesBefore,
+                messagesAfter: doneInfo.messagesAfter,
                 ...result.boundaryIndex !== void 0 ? { boundaryIndex: result.boundaryIndex } : {},
                 ...result.modelUsed ? { model: result.modelUsed } : {},
-                ...result.summaryPreview ? { summaryPreview: result.summaryPreview } : {}
+                ...result.summaryPreview ? { summaryPreview: result.summaryPreview } : {},
+                ...result.keptUserMessages !== void 0 ? { keptUserMessages: result.keptUserMessages } : {},
+                ...result.droppedUserMessages !== void 0 ? { droppedUserMessages: result.droppedUserMessages } : {}
               }
             };
             if (streamed) {
@@ -1014,6 +1240,20 @@ var TurnEngine = class _TurnEngine {
             continue;
           }
         }
+        if (!this._cancel && !streamed && isTransientNetworkError(exc) && netRetries < netMax) {
+          netRetries++;
+          const reason = `${exc instanceof Error ? exc.message : String(exc)}`.slice(0, 200);
+          const waitMs = networkRetryBaseMs() * 2 ** (netRetries - 1);
+          this._appendNotice("retry", `\u7F51\u7EDC\u4E2D\u65AD\uFF0C\u6B63\u5728\u91CD\u8BD5\uFF08${netRetries}/${netMax}\uFF09\uFF1A${reason}`);
+          this._emitHook((h) => h.onRetry?.(netRetries, netMax, reason));
+          yield {
+            type: "llm_retry" /* LLM_RETRY */,
+            data: { attempt: netRetries, max: netMax, reason, waitMs, iteration: iterations, reqId }
+          };
+          iterations--;
+          await sleepMs(waitMs);
+          continue;
+        }
         const errMsg = exc instanceof Error ? exc.message : String(exc);
         const errorType = exc instanceof Error ? exc.constructor.name : "unknown";
         const errorStack = exc instanceof Error ? exc.stack : void 0;
@@ -1068,39 +1308,14 @@ var TurnEngine = class _TurnEngine {
         this._emitHook((h) => h.onTurnEnd?.("error", iterations, files));
         return;
       }
+      netRetries = 0;
       if (this._cancel && turn === null) {
-        if (streamed) {
-          this.messages.push(
-            assistantMessage(
-              {
-                text: streamed,
-                toolCalls: [],
-                finishReason: null,
-                reasoning: streamedThinking || null,
-                usage: null
-              },
-              this.model,
-              this.taskId
-            )
-          );
-        }
-        this._appendNotice("interrupted");
-        this._emitHook((h) => h.onInterrupted?.(iterations));
-        yield {
-          type: "interrupted" /* INTERRUPTED */,
-          data: { iterations, reqId, taskId: this.taskId }
-        };
-        const files = this._buildProducedFiles();
-        yield {
-          type: "turn_end" /* TURN_END */,
-          data: {
-            status: "interrupted",
-            iterations,
-            produced_files: files,
-            taskId: this.taskId
-          }
-        };
-        this._emitHook((h) => h.onTurnEnd?.("interrupted", iterations, files));
+        yield* this._finishInterrupted({
+          iterations,
+          reqId,
+          streamed,
+          streamedThinking
+        });
         return;
       }
       if (turn === null) {
@@ -1219,9 +1434,14 @@ var TurnEngine = class _TurnEngine {
    *      PERMISSION_REQUIRED 事件并调用 approver；被拒/未知工具
    *      直接产出错误结果，不进入执行。
    *   B. 分类执行：低风险工具并发执行（Promise.all），其余串行；
+   *      交互类工具（ask_user / propose_plan / request_directory）虽然
+   *      风险级别为 low，但需要用户逐条作答，一律串行；
    *      每个结果都转成 tool 消息追加到历史并产出 TOOL_FINISHED。
    */
   async *_handleToolCalls(toolCalls) {
+    const abort = new AbortController();
+    this._toolAbort = abort;
+    if (this._cancel) abort.abort();
     const cleared = [];
     for (const tc of toolCalls) {
       tc.id = tc.id || `tool_${Date.now()}_${genReqId()}`;
@@ -1367,7 +1587,7 @@ var TurnEngine = class _TurnEngine {
     }
     const concurrent = cleared.filter((tc) => {
       const spec = this.registry.get(tc.name);
-      return spec?.metadata.riskLevel === "low" && !spec.metadata.requiresApproval;
+      return spec?.metadata.riskLevel === "low" && !spec.metadata.requiresApproval && !INTERACTIVE_TOOLS.has(tc.name);
     });
     const serial = cleared.filter((tc) => !concurrent.includes(tc));
     if (concurrent.length > 0) {
@@ -1383,7 +1603,8 @@ var TurnEngine = class _TurnEngine {
           try {
             let result = this.registry.execute(
               tc.name,
-              tc.arguments
+              tc.arguments,
+              { signal: abort.signal }
             );
             if (result instanceof Promise) result = await result;
             return { result, status: "ok" };
@@ -1452,7 +1673,8 @@ var TurnEngine = class _TurnEngine {
       try {
         result = this.registry.execute(
           tc.name,
-          tc.arguments
+          tc.arguments,
+          { signal: abort.signal }
         );
         if (result instanceof Promise) result = await result;
         status = "ok";
@@ -1489,6 +1711,7 @@ var TurnEngine = class _TurnEngine {
         }
       };
     }
+    if (this._toolAbort === abort) this._toolAbort = null;
   }
   // ===================== 辅助方法 =====================
   /**
@@ -1562,10 +1785,54 @@ var TurnEngine = class _TurnEngine {
     return false;
   }
   // ===================== 自动压缩 =====================
+  /** 当前上下文 token 用量：优先采信 API 返回的精确数量，否则用 chars/4 估算 */
+  _compactionTokens() {
+    if (this._lastContextTokens != null) {
+      return { tokens: this._lastContextTokens, estimated: false };
+    }
+    return {
+      tokens: estimateTokens(this._outboundMessages()),
+      estimated: true
+    };
+  }
   /** 检查是否需要压缩（每轮 LLM 调用前） */
   _compactionDue() {
-    const signal = this._lastContextTokens ?? estimateTokens(this._outboundMessages());
-    return shouldCompact(signal, this._getContextWindow());
+    const { tokens } = this._compactionTokens();
+    return shouldCompact(
+      tokens,
+      this._getContextWindow(),
+      this._thresholdPct,
+      this._capTokens
+    );
+  }
+  /** 组装压缩开始时的用量信息（供 hook 与 COMPACTING 事件携带） */
+  _compactionStartInfo(trigger) {
+    const { tokens, estimated } = this._compactionTokens();
+    const contextWindow = this._getContextWindow();
+    return {
+      trigger,
+      tokens,
+      estimated,
+      contextWindow,
+      thresholdPct: this._thresholdPct,
+      thresholdTokens: triggerTokens(
+        contextWindow,
+        this._thresholdPct,
+        this._capTokens
+      ),
+      outboundMessages: this._outboundMessages().length
+    };
+  }
+  /** 组装压缩结果信息（供 hook 与 COMPACTED 事件携带） */
+  _compactionDoneInfo(result) {
+    return {
+      method: result.method === "trimmed" ? "trimmed" : "summarized",
+      messagesBefore: result.messagesBefore ?? 0,
+      messagesAfter: result.messagesAfter ?? 0,
+      ...result.modelUsed ? { model: result.modelUsed } : {},
+      ...result.keptUserMessages !== void 0 ? { keptUserMessages: result.keptUserMessages } : {},
+      ...result.droppedUserMessages !== void 0 ? { droppedUserMessages: result.droppedUserMessages } : {}
+    };
   }
   /** 获取当前模型的上下文窗口大小（token 数）。优先级：显式配置 > 自动检测 > 默认值 128K。 */
   _getContextWindow() {
@@ -1575,8 +1842,13 @@ var TurnEngine = class _TurnEngine {
   /** 执行压缩策略（对齐 Python 版 _compact_now） */
   async _compactNow(reqId, force = false) {
     const contextWindow = this._getContextWindow();
+    const messagesBefore = this._outboundMessages().length;
     const keep = Math.floor(
-      KEEP_RECENT_FRACTION * triggerTokens(contextWindow)
+      KEEP_RECENT_FRACTION * triggerTokens(
+        contextWindow,
+        this._thresholdPct,
+        this._capTokens
+      )
     );
     const model = this.model;
     let state = null;
@@ -1608,7 +1880,9 @@ var TurnEngine = class _TurnEngine {
         boundaryIndex: state.boundaryIndex,
         summaryPreview: state.summaryText.slice(0, 200),
         keptUserMessages: state.userMessages.length,
-        droppedUserMessages: state.userMessagesDropped
+        droppedUserMessages: state.userMessagesDropped,
+        messagesBefore,
+        messagesAfter: this._outboundMessages().length
       };
     }
     if (failed || force) {
@@ -1619,7 +1893,9 @@ var TurnEngine = class _TurnEngine {
         return {
           notice: "\u4E0A\u4E0B\u6587\u5DF2\u88C1\u526A \u2014 \u6700\u65E7\u7684\u8F6E\u6B21\u5DF2\u4E22\u5F03\uFF08\u6458\u8981\u4E0D\u53EF\u7528\uFF09",
           method: "trimmed",
-          boundaryIndex: trimmed.boundaryIndex
+          boundaryIndex: trimmed.boundaryIndex,
+          messagesBefore,
+          messagesAfter: this._outboundMessages().length
         };
       }
     }
@@ -1633,9 +1909,9 @@ var TurnEngine = class _TurnEngine {
       return;
     }
     if (result && typeof result === "object") {
-      const path4 = result.path;
-      if (path4) {
-        this._producedFiles.push(path4);
+      const path8 = result.path;
+      if (path8) {
+        this._producedFiles.push(path8);
         return;
       }
       const changed = result.changed_files;
@@ -1717,20 +1993,36 @@ var TurnEngine = class _TurnEngine {
   }
 };
 
+// src/engine/limits.ts
+function parseMaxIterations(value, fallback) {
+  if (value === void 0 || value === null || value.trim() === "") {
+    return fallback;
+  }
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return Math.floor(n);
+}
+
 // src/tools/pathSafety.ts
 import * as fs2 from "fs";
 import * as path from "path";
-function isWithinRoot(workspace, target) {
+function isInsideRelative(rel) {
+  return !path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${path.sep}`);
+}
+function isFilesystemRoot(p) {
+  return path.parse(p).root === p;
+}
+function resolveWithinRoot(workspace, target) {
+  const abs = path.resolve(workspace, target);
   let rootReal;
   try {
     rootReal = fs2.realpathSync(workspace);
   } catch {
     const rootAbs = path.resolve(workspace);
-    const abs2 = path.resolve(workspace, target);
-    const rel2 = path.relative(rootAbs, abs2);
-    return !rel2.startsWith("..") && !path.isAbsolute(rel2);
+    if (!isInsideRelative(path.relative(rootAbs, abs))) return null;
+    return { root: rootAbs, real: abs };
   }
-  const abs = path.resolve(workspace, target);
+  if (isFilesystemRoot(rootReal)) return null;
   let real;
   try {
     real = fs2.realpathSync(abs);
@@ -1744,26 +2036,36 @@ function isWithinRoot(workspace, target) {
           real = path.join(fs2.realpathSync(probe), ...tail);
           break;
         } catch {
-          return false;
+          return null;
         }
       }
       tail.unshift(path.basename(probe));
       const parent = path.dirname(probe);
-      if (parent === probe) return false;
+      if (parent === probe) return null;
       probe = parent;
     }
   }
-  const rel = path.relative(rootReal, real);
-  return !rel.startsWith("..") && !path.isAbsolute(rel);
+  if (!isInsideRelative(path.relative(rootReal, real))) return null;
+  return { root: rootReal, real };
+}
+function isWithinRoot(workspace, target) {
+  return resolveWithinRoot(workspace, target) !== null;
 }
 
 // src/permissions/PermissionEngine.ts
 import * as path2 from "path";
 var READ_ONLY_MODES = /* @__PURE__ */ new Set(["discuss" /* DISCUSS */, "plan" /* PLAN */]);
-var WRITE_TOOLS = /* @__PURE__ */ new Set(["write_file", "replace_in_file", "apply_patch", "apply_unified_diff"]);
+var WRITE_TOOLS = /* @__PURE__ */ new Set([
+  "write_file",
+  "replace_in_file",
+  "apply_patch",
+  "apply_unified_diff"
+]);
 var SHELL_TOOL = "run_shell";
 var BASE_RISK = {
-  ...Object.fromEntries([...WRITE_TOOLS].map((n) => [n, "write_local" /* WRITE_LOCAL */])),
+  ...Object.fromEntries(
+    [...WRITE_TOOLS].map((n) => [n, "write_local" /* WRITE_LOCAL */])
+  ),
   [SHELL_TOOL]: "exec" /* EXEC */
 };
 function classify(toolName, metadata) {
@@ -1781,6 +2083,14 @@ var SHELL_OPERATORS = [";", "&", "|", ">", "<", "`", "$(", "(", "\n", "\r"];
 function hasShellOperators(command) {
   return SHELL_OPERATORS.some((op) => command.includes(op));
 }
+function commandBin(command) {
+  const first = String(command ?? "").trim().split(/\s+/)[0] ?? "";
+  return first.split("/").pop() ?? first;
+}
+function isBareCommand(command) {
+  const first = String(command ?? "").trim().split(/\s+/)[0] ?? "";
+  return first.length > 0 && !first.includes("/");
+}
 var PermissionEngine = class {
   /** 工作区根目录（写入路径必须位于其下） */
   workspaceRoot;
@@ -1811,12 +2121,20 @@ var PermissionEngine = class {
     const isShell = risk === "exec" /* EXEC */;
     const consequential = isConsequential(risk);
     if (READ_ONLY_MODES.has(this.mode) && consequential) {
-      return { allowed: false, reason: `${this.mode} \u6A21\u5F0F\u4E3A\u53EA\u8BFB`, needsUser: false };
+      return {
+        allowed: false,
+        reason: `${this.mode} \u6A21\u5F0F\u4E3A\u53EA\u8BFB`,
+        needsUser: false
+      };
     }
     if (isWrite) {
       const filePath = args["path"];
       if (filePath && !this._underWritableRoot(filePath)) {
-        return { allowed: false, reason: `\u8DEF\u5F84\u4E0D\u5728\u53EF\u5199\u76EE\u5F55\u4E0B: ${filePath}`, needsUser: false };
+        return {
+          allowed: false,
+          reason: `\u8DEF\u5F84\u4E0D\u5728\u53EF\u5199\u76EE\u5F55\u4E0B: ${filePath}`,
+          needsUser: false
+        };
       }
     }
     if (!consequential) {
@@ -1830,8 +2148,15 @@ var PermissionEngine = class {
       if (this._commandAllowed(command)) {
         return { allowed: true, reason: "\u547D\u4EE4\u5728\u767D\u540D\u5355\u4E2D", needsUser: false };
       }
-      if (command && this.sessionAllowCommands.has(command)) {
-        return { allowed: true, reason: "\u4F1A\u8BDD\u5DF2\u5141\u8BB8\u6B64\u547D\u4EE4", needsUser: false };
+      if (!hasShellOperators(command) && isBareCommand(command)) {
+        const bin = commandBin(command);
+        if (bin && this.sessionAllowCommands.has(bin)) {
+          return {
+            allowed: true,
+            reason: "\u4F1A\u8BDD\u5DF2\u5141\u8BB8\u6B64\u547D\u4EE4",
+            needsUser: false
+          };
+        }
       }
     }
     if (this.sessionAllowTools.has(toolName)) {
@@ -1843,9 +2168,10 @@ var PermissionEngine = class {
   allowToolForSession(toolName) {
     this.sessionAllowTools.add(toolName);
   }
-  /** 将命令加入会话白名单 */
+  /** 将命令加入会话白名单（按可执行程序名记录，同类命令后续直接放行） */
   allowCommandForSession(command) {
-    if (command) this.sessionAllowCommands.add(command);
+    const bin = commandBin(command);
+    if (bin) this.sessionAllowCommands.add(bin);
   }
   /**
    * 检查路径是否在可写根目录下
@@ -1879,10 +2205,11 @@ function makeReadFile(workspace) {
     const filePath = String(args.path ?? "");
     const startLine = Math.max(1, Number(args.start_line ?? 1));
     const maxLines = Math.min(Number(args.max_lines ?? DEFAULT_MAX_LINES), DEFAULT_MAX_LINES);
-    const target = path3.resolve(root, filePath);
-    if (!isWithinRoot(root, target)) {
+    const resolved = resolveWithinRoot(root, filePath);
+    if (!resolved) {
       return { error: "\u8DEF\u5F84\u5728\u5DE5\u4F5C\u533A\u4E4B\u5916" };
     }
+    const target = resolved.real;
     if (!fs3.existsSync(target) || !fs3.statSync(target).isFile()) {
       return { error: `\u4E0D\u662F\u6587\u4EF6: ${filePath}` };
     }
@@ -1904,7 +2231,7 @@ function makeReadFile(workspace) {
     }
     const end = startLine + selected.length - 1;
     const result = {
-      path: path3.relative(root, target),
+      path: path3.relative(resolved.root, target),
       start_line: startLine,
       end_line: end,
       total_lines: total,
@@ -1916,38 +2243,14 @@ function makeReadFile(workspace) {
     return result;
   };
 }
-function makeWriteFile(workspace) {
-  const root = path3.resolve(workspace);
-  return function write_file(args) {
-    const filePath = String(args.path ?? "");
-    const content = String(args.content ?? "");
-    const overwrite = args.overwrite !== false;
-    const target = path3.resolve(root, filePath);
-    if (!isWithinRoot(root, target)) {
-      return { error: "\u8DEF\u5F84\u5728\u5DE5\u4F5C\u533A\u4E4B\u5916" };
-    }
-    if (fs3.existsSync(target) && fs3.statSync(target).isDirectory()) {
-      return { error: "\u8DEF\u5F84\u662F\u76EE\u5F55\uFF0C\u4E0D\u662F\u6587\u4EF6" };
-    }
-    if (fs3.existsSync(target) && !overwrite) {
-      return { error: "\u6587\u4EF6\u5DF2\u5B58\u5728 (overwrite=false)" };
-    }
-    try {
-      fs3.mkdirSync(path3.dirname(target), { recursive: true });
-      fs3.writeFileSync(target, content, "utf-8");
-    } catch (exc) {
-      return { error: `\u5199\u5165\u5931\u8D25: ${String(exc)}` };
-    }
-    return path3.relative(root, target);
-  };
-}
 function makeListFiles(workspace) {
   const root = path3.resolve(workspace);
   return function list_files(args) {
     const dirPath = String(args.path ?? ".");
     const maxResults = Math.min(Number(args.max_results ?? 100), 100);
-    const target = path3.resolve(root, dirPath);
-    if (!isWithinRoot(root, target)) return { error: "\u8DEF\u5F84\u5728\u5DE5\u4F5C\u533A\u4E4B\u5916" };
+    const resolved = resolveWithinRoot(root, dirPath);
+    if (!resolved) return { error: "\u8DEF\u5F84\u5728\u5DE5\u4F5C\u533A\u4E4B\u5916" };
+    const target = resolved.real;
     if (!fs3.existsSync(target) || !fs3.statSync(target).isDirectory()) {
       return { error: `\u4E0D\u662F\u76EE\u5F55: ${dirPath}` };
     }
@@ -1961,45 +2264,13 @@ function makeListFiles(workspace) {
         results.push(e.isDirectory() ? `${e.name}/` : e.name);
       }
       results.sort();
-      return { path: path3.relative(root, target), entries: results.slice(0, maxResults) };
+      return { path: path3.relative(resolved.root, target), entries: results.slice(0, maxResults) };
     } catch (exc) {
       return { error: `\u5217\u51FA\u6587\u4EF6\u5931\u8D25: ${String(exc)}` };
     }
   };
 }
-function makeReplaceInFile(workspace) {
-  const root = path3.resolve(workspace);
-  return function replace_in_file(args) {
-    const filePath = String(args.path ?? "");
-    const oldStr = String(args.old ?? "");
-    const newStr = String(args.new ?? "");
-    const expectedReplacements = Math.max(1, Number(args.expected_replacements ?? 1));
-    if (!oldStr) return { error: "old \u4E0D\u80FD\u4E3A\u7A7A" };
-    const target = path3.resolve(root, filePath);
-    if (!isWithinRoot(root, target)) return { error: "\u8DEF\u5F84\u5728\u5DE5\u4F5C\u533A\u4E4B\u5916" };
-    if (!fs3.existsSync(target) || !fs3.statSync(target).isFile()) {
-      return { error: `\u4E0D\u662F\u6587\u4EF6: ${filePath}` };
-    }
-    try {
-      const content = fs3.readFileSync(target, "utf-8");
-      const count = content.split(oldStr).length - 1;
-      if (count !== expectedReplacements) {
-        return { error: `\u671F\u671B ${expectedReplacements} \u5904\u66FF\u6362\uFF0C\u5B9E\u9645\u627E\u5230 ${count} \u5904: ${filePath}` };
-      }
-      const updated = content.replaceAll(oldStr, newStr);
-      fs3.writeFileSync(target, updated, "utf-8");
-      return {
-        path: path3.relative(root, target),
-        replacements: count,
-        chars_before: content.length,
-        chars_after: updated.length
-      };
-    } catch (exc) {
-      return { error: `\u66FF\u6362\u5931\u8D25: ${String(exc)}` };
-    }
-  };
-}
-function registerFileTools(registry, workspace) {
+function registerReadOnlyFileTools(registry, workspace) {
   const readFile = makeReadFile(workspace);
   registry.register(
     (args) => readFile(args),
@@ -2021,49 +2292,6 @@ function registerFileTools(registry, workspace) {
       }
     }
   );
-  const writeFile = makeWriteFile(workspace);
-  registry.register(
-    (args) => writeFile(args),
-    { category: "filesystem", riskLevel: "medium", capabilities: ["write_file"], requiresApproval: true },
-    {
-      type: "function",
-      function: {
-        name: "write_file",
-        description: "\u5199\u5165\u4E00\u4E2A UTF-8 \u6587\u672C\u6587\u4EF6\u3002\u7528\u4E8E\u521B\u5EFA\u65B0\u6587\u4EF6\u6216\u5B8C\u5168\u91CD\u5199\u73B0\u6709\u6587\u4EF6\u3002",
-        parameters: {
-          type: "object",
-          properties: {
-            path: { type: "string", description: "\u6587\u4EF6\u8DEF\u5F84 (\u76F8\u5BF9\u4E8E\u5DE5\u4F5C\u533A)" },
-            content: { type: "string", description: "\u6587\u4EF6\u5185\u5BB9 (UTF-8)" },
-            overwrite: { type: "boolean", description: "\u662F\u5426\u8986\u76D6\u5DF2\u5B58\u5728\u7684\u6587\u4EF6 (\u9ED8\u8BA4 true)" }
-          },
-          required: ["path", "content"]
-        }
-      }
-    }
-  );
-  const replaceFile = makeReplaceInFile(workspace);
-  registry.register(
-    (args) => replaceFile(args),
-    { category: "filesystem", riskLevel: "medium", capabilities: ["edit_file"], requiresApproval: true },
-    {
-      type: "function",
-      function: {
-        name: "replace_in_file",
-        description: "\u5728\u6587\u4EF6\u4E2D\u7CBE\u786E\u66FF\u6362\u4E00\u6BB5\u6587\u672C\u3002\u5148\u6309\u9884\u671F\u6B21\u6570\u7CBE\u786E\u5339\u914D old \u5B57\u7B26\u4E32\uFF0C\u7136\u540E\u66FF\u6362\u4E3A new\u3002\u7528\u4E8E\u5C0F\u8303\u56F4\u7CBE\u786E\u7F16\u8F91\u3002",
-        parameters: {
-          type: "object",
-          properties: {
-            path: { type: "string", description: "\u6587\u4EF6\u8DEF\u5F84 (\u76F8\u5BF9\u4E8E\u5DE5\u4F5C\u533A)" },
-            old: { type: "string", description: "\u8981\u88AB\u66FF\u6362\u7684\u7CBE\u786E\u6587\u672C" },
-            new: { type: "string", description: "\u66FF\u6362\u540E\u7684\u65B0\u6587\u672C" },
-            expected_replacements: { type: "integer", description: "\u671F\u671B\u7684\u66FF\u6362\u6B21\u6570 (\u9ED8\u8BA4 1)" }
-          },
-          required: ["path", "old", "new"]
-        }
-      }
-    }
-  );
   const listFiles = makeListFiles(workspace);
   registry.register(
     (args) => listFiles(args),
@@ -2085,47 +2313,515 @@ function registerFileTools(registry, workspace) {
   );
 }
 
+// src/tools/execAsync.ts
+import { spawn } from "child_process";
+
+// src/tools/killTree.ts
+import { spawnSync } from "child_process";
+function killTree(pid) {
+  if (!pid) return;
+  if (process.platform === "win32") {
+    try {
+      spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { windowsHide: true });
+    } catch {
+    }
+    return;
+  }
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+    }
+  }
+}
+
+// src/tools/execAsync.ts
+var liveChildren = /* @__PURE__ */ new Set();
+var exitCleanupInstalled = false;
+function trackChild(pid) {
+  if (!pid) return;
+  liveChildren.add(pid);
+  if (exitCleanupInstalled) return;
+  exitCleanupInstalled = true;
+  process.once("exit", () => {
+    for (const p of liveChildren) killTree(p);
+  });
+}
+var DEFAULT_MAX_BUFFER = 1024 * 1024 * 5;
+var KILL_GRACE_MS = 1e3;
+function makeSink(maxBuffer) {
+  const chunks = [];
+  let len = 0;
+  let over = false;
+  return {
+    push(chunk) {
+      if (len >= maxBuffer) {
+        over = true;
+        return;
+      }
+      const room = maxBuffer - len;
+      if (chunk.length > room) {
+        chunks.push(chunk.subarray(0, room));
+        len = maxBuffer;
+        over = true;
+        return;
+      }
+      chunks.push(chunk);
+      len += chunk.length;
+    },
+    done: () => Buffer.concat(chunks),
+    over: () => over
+  };
+}
+function execAsync(file, argv, opts = {}) {
+  return new Promise((resolve7) => {
+    const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
+    const out = makeSink(maxBuffer);
+    const err = makeSink(maxBuffer);
+    if (opts.signal?.aborted) {
+      resolve7({
+        status: null,
+        stdout: Buffer.alloc(0),
+        stderr: Buffer.alloc(0),
+        timedOut: false,
+        truncated: false,
+        aborted: true
+      });
+      return;
+    }
+    let child;
+    try {
+      child = spawn(file, argv, {
+        ...opts.cwd !== void 0 ? { cwd: opts.cwd } : {},
+        ...opts.env !== void 0 ? { env: opts.env } : {},
+        // 自成进程组（POSIX）：超时/中断时用 killTree 一次收掉整棵进程树
+        detached: process.platform !== "win32",
+        stdio: [opts.input === void 0 ? "ignore" : "pipe", "pipe", "pipe"],
+        windowsHide: true
+      });
+    } catch (e) {
+      resolve7({
+        status: null,
+        stdout: Buffer.alloc(0),
+        stderr: Buffer.alloc(0),
+        error: e,
+        timedOut: false,
+        truncated: false
+      });
+      return;
+    }
+    trackChild(child.pid);
+    let settled = false;
+    let timedOut = false;
+    let aborted = false;
+    let spawnError;
+    let timer = null;
+    let graceTimer = null;
+    const onAbort = () => {
+      aborted = true;
+      killAndSettle();
+    };
+    const finish = (status) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (graceTimer) clearTimeout(graceTimer);
+      if (child.pid !== void 0) liveChildren.delete(child.pid);
+      opts.signal?.removeEventListener("abort", onAbort);
+      const result = {
+        status,
+        stdout: out.done(),
+        stderr: err.done(),
+        timedOut,
+        truncated: out.over() || err.over()
+      };
+      if (aborted) result.aborted = true;
+      if (spawnError) result.error = spawnError;
+      resolve7(result);
+    };
+    const killAndSettle = () => {
+      killTree(child.pid);
+      if (settled || graceTimer) return;
+      graceTimer = setTimeout(() => {
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        finish(null);
+      }, KILL_GRACE_MS);
+    };
+    if (opts.timeoutMs !== void 0 && opts.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        killAndSettle();
+      }, opts.timeoutMs);
+    }
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+    child.stdout?.on("data", (c) => out.push(c));
+    child.stderr?.on("data", (c) => err.push(c));
+    child.on("error", (e) => {
+      spawnError = e;
+      if (child.pid === void 0) finish(null);
+    });
+    if (opts.input !== void 0 && child.stdin) {
+      child.stdin.on("error", () => {
+      });
+      child.stdin.end(opts.input);
+    }
+    child.on("close", (code) => finish(code));
+  });
+}
+
+// src/tools/shellRuntime.ts
+import * as path4 from "path";
+var WINDOWS_SUFFIXES = [".exe", ".cmd", ".bat", ".com", ""];
+function pathApi(platform) {
+  return platform === "win32" ? path4.win32 : path4.posix;
+}
+function joinPath(platform, ...parts) {
+  return pathApi(platform).join(...parts);
+}
+function findExecutable(name, ctx) {
+  if (name.includes("/") || name.includes("\\")) {
+    return ctx.fileExists(name) ? name : null;
+  }
+  const suffixes = ctx.platform === "win32" ? WINDOWS_SUFFIXES : [""];
+  const delimiter = ctx.platform === "win32" ? ";" : ":";
+  const dirs = (ctx.env.PATH ?? "").split(delimiter).filter((d) => d.length > 0);
+  for (const dir of dirs) {
+    for (const suffix of suffixes) {
+      const candidate = joinPath(ctx.platform, dir, name + suffix);
+      if (ctx.fileExists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+// src/tools/shellBackground.ts
+import { spawn as spawn2 } from "child_process";
+var DEFAULT_BUFFER_LIMIT = 64 * 1024;
+var RingBuffer = class {
+  constructor(limit = DEFAULT_BUFFER_LIMIT) {
+    this.limit = limit;
+  }
+  limit;
+  chunks = [];
+  size = 0;
+  add(chunk) {
+    if (!chunk) return;
+    this.chunks.push(chunk);
+    this.size += chunk.length;
+    while (this.size > this.limit && this.chunks.length > 1) {
+      this.size -= this.chunks.shift().length;
+    }
+    if (this.size > this.limit) {
+      const joined = this.chunks.join("");
+      this.chunks = [joined.slice(-this.limit)];
+      this.size = this.chunks[0].length;
+    }
+  }
+  get() {
+    const joined = this.chunks.join("");
+    return joined.length > this.limit ? joined.slice(-this.limit) : joined;
+  }
+};
+var ShellTaskManager = class {
+  tasks = /* @__PURE__ */ new Map();
+  seq = 0;
+  cleanupInstalled = false;
+  /** 启动一个后台任务，立即返回快照（不等退出） */
+  start(opts) {
+    this.installCleanup();
+    const id = `shell-${++this.seq}-${Date.now().toString(36)}`;
+    const child = spawn2(opts.file, opts.argv, {
+      cwd: opts.cwd,
+      env: opts.env,
+      detached: process.platform !== "win32",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const task = {
+      id,
+      command: opts.command,
+      scope: opts.scope ?? null,
+      child,
+      stdout: new RingBuffer(),
+      stderr: new RingBuffer(),
+      status: "running",
+      exitCode: null,
+      signal: null,
+      startedAt: Date.now(),
+      endedAt: null
+    };
+    this.tasks.set(id, task);
+    child.stdout?.on("data", (d) => task.stdout.add(d.toString("utf-8")));
+    child.stderr?.on("data", (d) => task.stderr.add(d.toString("utf-8")));
+    child.on("error", (err) => task.stderr.add(`[spawn error] ${err.message}
+`));
+    child.on("exit", (code, signal) => {
+      task.exitCode = code;
+      task.signal = signal;
+      task.endedAt = Date.now();
+      if (task.status !== "killed") task.status = "exited";
+    });
+    child.unref();
+    return this.snapshot(task);
+  }
+  /** 读取任务输出与状态 */
+  output(taskId) {
+    const task = this.tasks.get(taskId);
+    if (!task) return { error: `\u672A\u77E5\u7684\u540E\u53F0\u4EFB\u52A1: ${taskId}` };
+    return this.snapshot(task);
+  }
+  /** 终止任务（进程树）并返回快照；传 scope 时只允许终止该归属下的任务 */
+  kill(taskId, scope) {
+    const task = this.tasks.get(taskId);
+    if (!task) return { error: `\u672A\u77E5\u7684\u540E\u53F0\u4EFB\u52A1: ${taskId}` };
+    if (scope !== void 0 && task.scope !== scope) {
+      return { error: `\u672A\u77E5\u7684\u540E\u53F0\u4EFB\u52A1: ${taskId}` };
+    }
+    if (task.status === "running") {
+      task.status = "killed";
+      task.endedAt = Date.now();
+      killTree(task.child.pid);
+    }
+    return this.snapshot(task);
+  }
+  /** 列出任务快照（调试/展示用）；传 scope 时只返回该归属下的任务 */
+  list(scope) {
+    const all = [...this.tasks.values()];
+    return (scope === void 0 ? all : all.filter((t) => t.scope === scope)).map(
+      (t) => this.snapshot(t)
+    );
+  }
+  /** 终止全部任务（进程退出时调用） */
+  disposeAll() {
+    for (const task of this.tasks.values()) {
+      if (task.status === "running") {
+        task.status = "killed";
+        killTree(task.child.pid);
+      }
+    }
+  }
+  snapshot(task) {
+    return {
+      task_id: task.id,
+      command: task.command,
+      status: task.status,
+      running: task.status === "running",
+      exit_code: task.exitCode,
+      signal: task.signal,
+      stdout: task.stdout.get(),
+      stderr: task.stderr.get(),
+      duration_ms: (task.endedAt ?? Date.now()) - task.startedAt
+    };
+  }
+  installCleanup() {
+    if (this.cleanupInstalled) return;
+    this.cleanupInstalled = true;
+    process.once("exit", () => this.disposeAll());
+  }
+};
+
+// src/tools/shell.ts
+var MAX_BUFFER = 1024 * 1024 * 5;
+function decodeOutput(buf) {
+  if (!buf || buf.length === 0) return "";
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(buf);
+  } catch {
+    for (const enc of ["gbk", "big5", "shift_jis", "latin1"]) {
+      try {
+        return new TextDecoder(enc).decode(buf);
+      } catch {
+      }
+    }
+    return buf.toString("latin1");
+  }
+}
+var shellTasks = new ShellTaskManager();
+
+// src/tools/nodeGrep.ts
+import * as fs4 from "fs";
+import * as path5 from "path";
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  "node_modules",
+  ".svn",
+  ".hg",
+  "dist",
+  "build",
+  ".next",
+  ".cache"
+]);
+function looksBinary(buf) {
+  const n = Math.min(buf.length, 8192);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+function nodeGrep(opts) {
+  const maxMatches = opts.maxMatches ?? 50;
+  const maxFileBytes = opts.maxFileBytes ?? 1024 * 1024;
+  let regex;
+  try {
+    regex = new RegExp(opts.pattern);
+  } catch (err) {
+    throw new Error(`\u65E0\u6548\u7684\u6B63\u5219\u8868\u8FBE\u5F0F: ${opts.pattern}\uFF08${String(err)}\uFF09`);
+  }
+  const target = path5.resolve(opts.workspace, opts.target);
+  if (!fs4.existsSync(target)) {
+    throw new Error(`\u641C\u7D22\u8DEF\u5F84\u4E0D\u5B58\u5728: ${opts.target}`);
+  }
+  const matches = [];
+  const scanFile = (file) => {
+    let stat2;
+    try {
+      stat2 = fs4.statSync(file);
+    } catch {
+      return false;
+    }
+    if (!stat2.isFile() || stat2.size > maxFileBytes) return false;
+    let buf;
+    try {
+      buf = fs4.readFileSync(file);
+    } catch {
+      return false;
+    }
+    if (looksBinary(buf)) return false;
+    const rel = path5.relative(opts.workspace, file) || path5.basename(file);
+    const lines = buf.toString("utf-8").split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const raw = lines[i].replace(/\r$/, "");
+      if (regex.test(raw)) {
+        matches.push({ file: rel, line: i + 1, text: raw.trim().slice(0, 200) });
+        if (matches.length >= maxMatches) return true;
+      }
+    }
+    return false;
+  };
+  const stat = fs4.statSync(target);
+  if (stat.isFile()) {
+    scanFile(target);
+    return matches;
+  }
+  const stack = [target];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs4.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path5.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) stack.push(full);
+      } else if (entry.isFile()) {
+        if (scanFile(full)) return matches;
+      }
+    }
+  }
+  return matches;
+}
+
+// src/tools/ripgrep.ts
+import * as fs5 from "fs";
+import * as os from "os";
+import * as path6 from "path";
+import { createRequire } from "module";
+var cached;
+function extractBundledRipgrep() {
+  try {
+    const req = typeof __require === "function" ? __require : createRequire(path6.join(process.cwd(), "__zqagent__.js"));
+    const sea = req("node:sea");
+    if (!sea?.isSea?.() || typeof sea.getAsset !== "function") return null;
+    const asset = sea.getAsset("rg");
+    if (!asset) return null;
+    const dir = fs5.mkdtempSync(path6.join(os.tmpdir(), "zqagent-rg-"));
+    const file = path6.join(dir, process.platform === "win32" ? "rg.exe" : "rg");
+    fs5.writeFileSync(file, Buffer.from(asset));
+    fs5.chmodSync(file, 493);
+    return file;
+  } catch {
+    return null;
+  }
+}
+function resolveRipgrep() {
+  if (cached !== void 0) return cached;
+  const explicit = (process.env.ZQAGENT_RG ?? "").trim();
+  if (explicit && fs5.existsSync(explicit)) {
+    cached = explicit;
+    return cached;
+  }
+  const bundled = extractBundledRipgrep();
+  if (bundled) {
+    cached = bundled;
+    return cached;
+  }
+  cached = findExecutable("rg", {
+    platform: process.platform,
+    env: process.env,
+    fileExists: (p) => {
+      try {
+        return fs5.statSync(p).isFile();
+      } catch {
+        return false;
+      }
+    }
+  });
+  return cached;
+}
+
 // src/tools/search.ts
-import { execFileSync } from "child_process";
+function parseRgOutput(result) {
+  return result.split("\n").map((l) => l.replace(/\r$/, "")).filter((l) => l.length > 0).slice(0, 50).map((line) => {
+    const m = /^(.+?):(\d+):(.*)$/.exec(line);
+    if (!m) return { file: line.trim(), line: 0, text: "" };
+    return { file: m[1], line: Number(m[2]), text: m[3].trim().slice(0, 200) };
+  });
+}
 function makeGrep(workspace) {
-  return function grep(args) {
+  return async function grep(args) {
     const pattern = String(args.pattern ?? "");
     const filePath = String(args.path ?? ".");
     if (!pattern.trim()) {
       return { error: "\u641C\u7D22\u6A21\u5F0F\u4E0D\u80FD\u4E3A\u7A7A" };
     }
-    const execOpts = {
-      cwd: workspace,
-      encoding: "utf-8",
-      timeout: 1e4,
-      maxBuffer: 1024 * 1024 * 2
-    };
-    try {
-      let result;
-      try {
-        result = execFileSync(
-          "rg",
-          ["--line-number", "--no-heading", "--max-count", "50", pattern, filePath],
-          execOpts
-        ).toString();
-      } catch {
-        result = execFileSync(
-          "grep",
-          ["-rn", "--max-count", "50", pattern, filePath],
-          execOpts
-        ).toString();
+    const rg = resolveRipgrep();
+    if (rg) {
+      const res = await execAsync(
+        rg,
+        [
+          // --with-filename：单文件模式下 rg 默认不输出文件名前缀，会导致
+          // "行号:内容" 被误当成 "文件:行号:内容" 解析而错位；显式要求带文件名。
+          "--with-filename",
+          "--line-number",
+          "--no-heading",
+          "--max-count",
+          "50",
+          pattern,
+          filePath
+        ],
+        {
+          cwd: workspace,
+          timeoutMs: 1e4,
+          maxBuffer: 1024 * 1024 * 2
+        }
+      );
+      if (res.status === 0) {
+        const matches = parseRgOutput(decodeOutput(res.stdout));
+        return { query: pattern, engine: "ripgrep", matches, count: matches.length };
       }
-      const lines = result.trim().split("\n").slice(0, 50);
-      const matches = lines.map((line) => {
-        const [file, lineno, ...rest] = line.split(":");
-        return { file, line: Number(lineno), text: rest.join(":").trim().slice(0, 200) };
-      });
-      return { query: pattern, matches, count: matches.length };
-    } catch (exc) {
-      if (exc instanceof Error && "status" in exc && exc.status === 1) {
-        return { query: pattern, matches: [], count: 0 };
+      if (res.status === 1) {
+        return { query: pattern, engine: "ripgrep", matches: [], count: 0 };
       }
-      return { error: `\u641C\u7D22\u5931\u8D25: ${String(exc)}` };
+    }
+    try {
+      const matches = nodeGrep({ pattern, target: filePath, workspace });
+      return { query: pattern, engine: "node", matches, count: matches.length };
+    } catch (exc) {
+      return { error: `\u641C\u7D22\u5931\u8D25: ${String(exc instanceof Error ? exc.message : exc)}` };
     }
   };
 }
@@ -2138,7 +2834,7 @@ function registerSearchTool(registry, workspace) {
       type: "function",
       function: {
         name: "grep",
-        description: "\u5728\u6587\u4EF6\u4E2D\u641C\u7D22\u6587\u672C\u6A21\u5F0F\u3002\u8FD4\u56DE\u5339\u914D\u7684\u6587\u4EF6\u540D\u3001\u884C\u53F7\u548C\u5185\u5BB9\u3002\u4F18\u5148\u4F7F\u7528 ripgrep (rg) \u4EE5\u83B7\u5F97\u66F4\u597D\u7684\u6027\u80FD\u3002",
+        description: "\u5728\u6587\u4EF6\u4E2D\u641C\u7D22\u6587\u672C\u6A21\u5F0F\uFF08\u652F\u6301\u5B8C\u6574 JS \u6B63\u5219\u8BED\u6CD5\uFF09\u3002\u8FD4\u56DE\u5339\u914D\u7684\u6587\u4EF6\u540D\u3001\u884C\u53F7\u548C\u5185\u5BB9\uFF0C\u6700\u591A 50 \u6761\u3002\u4F18\u5148\u4F7F\u7528 ripgrep (rg) \u4EE5\u83B7\u5F97\u66F4\u597D\u7684\u6027\u80FD\uFF1Brg \u4E0D\u53EF\u7528\u65F6\u81EA\u52A8\u56DE\u9000\u5230\u5185\u7F6E\u626B\u63CF\u5668\u3002",
         parameters: {
           type: "object",
           properties: {
@@ -2153,90 +2849,138 @@ function registerSearchTool(registry, workspace) {
 }
 
 // src/tools/git.ts
-import { execFileSync as execFileSync2 } from "child_process";
+import * as fs6 from "fs";
+import * as path7 from "path";
+async function runGit(repoDir, args, timeout = 15e3) {
+  const res = await execAsync("git", ["-c", "core.quotepath=false", ...args], {
+    cwd: repoDir,
+    timeoutMs: timeout,
+    maxBuffer: 1024 * 1024 * 5,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+  });
+  return {
+    status: res.status ?? 1,
+    stdout: decodeOutput(res.stdout),
+    stderr: decodeOutput(res.stderr) || (res.error?.message ?? "")
+  };
+}
+async function resolveRepoRoot(workspace, pathArg) {
+  let dir = workspace;
+  if (pathArg) {
+    const abs = path7.resolve(workspace, pathArg);
+    try {
+      dir = fs6.statSync(abs).isDirectory() ? abs : path7.dirname(abs);
+    } catch {
+      dir = abs;
+    }
+  }
+  const res = await runGit(dir, ["rev-parse", "--show-toplevel"], 1e4);
+  if (res.status === 0 && res.stdout.trim()) return res.stdout.trim();
+  return workspace;
+}
+function repoDirArg(workspace, raw) {
+  if (typeof raw !== "string") return void 0;
+  const v = raw.trim();
+  if (!v) return void 0;
+  const base = path7.resolve(workspace);
+  const abs = path7.resolve(base, v);
+  const rel = path7.relative(base, abs);
+  if (rel.startsWith("..") || path7.isAbsolute(rel)) return void 0;
+  return abs;
+}
+function toPathspec(repoRoot, workspace, pathArg) {
+  if (!pathArg) return null;
+  const abs = path7.resolve(workspace, pathArg);
+  let rel = path7.relative(repoRoot, abs);
+  if (rel === "") return ".";
+  if (rel.startsWith("..") || path7.isAbsolute(rel)) {
+    try {
+      const realRepo = fs6.realpathSync(repoRoot);
+      const realAbs = fs6.realpathSync(abs);
+      const rel2 = path7.relative(realRepo, realAbs);
+      if (rel2 === "") return ".";
+      if (!rel2.startsWith("..") && !path7.isAbsolute(rel2)) return rel2;
+    } catch {
+    }
+    return null;
+  }
+  return rel;
+}
 function makeGitLog(workspace) {
-  return function git_log(args) {
+  return async function git_log(args) {
     const filePath = args.path ? String(args.path) : void 0;
     const maxCount = Math.min(Number(args.max_count ?? 20), 200);
     if (maxCount < 1) return { error: "max_count \u5FC5\u987B >= 1" };
+    const repo = await resolveRepoRoot(workspace, repoDirArg(workspace, args.repo) ?? filePath);
     const cmd = [
-      "-C",
-      workspace,
       "log",
       `-n${maxCount}`,
       "--pretty=format:%h%x1f%an%x1f%ad%x1f%s",
       "--date=short"
     ];
-    if (filePath) cmd.push("--", filePath);
-    try {
-      const out = execFileSync2("git", cmd, { encoding: "utf-8", timeout: 15e3 });
-      const commits = out.trim().split("\n").filter(Boolean).map((line) => {
-        const parts = line.split("");
-        if (parts.length === 4) {
-          return { hash: parts[0], author: parts[1], date: parts[2], subject: parts[3] };
-        }
-        return { raw: line };
-      });
-      return { count: commits.length, commits };
-    } catch (exc) {
-      const err = exc;
-      return { error: (err.stderr ?? err.message ?? "git log failed").slice(0, 300) };
-    }
+    const pathspec = toPathspec(repo, workspace, filePath);
+    if (pathspec) cmd.push("--", pathspec);
+    const res = await runGit(repo, cmd);
+    if (res.status !== 0) {
+      return { error: (res.stderr || "git log failed").trim().slice(0, 300) };
+    }
+    const commits = res.stdout.split("\n").map((l) => l.replace(/\r$/, "")).filter((l) => l.length > 0).map((line) => {
+      const parts = line.split("");
+      if (parts.length === 4) {
+        return { hash: parts[0], author: parts[1], date: parts[2], subject: parts[3] };
+      }
+      return { raw: line };
+    });
+    return { repo, count: commits.length, commits };
   };
 }
 function makeGitStatus(workspace) {
-  return function git_status(_args) {
-    try {
-      const out = execFileSync2(
-        "git",
-        ["-C", workspace, "status", "--porcelain"],
-        { encoding: "utf-8", timeout: 1e4 }
-      );
-      const lines = out.trim().split("\n").filter(Boolean);
-      const entries = lines.map((line) => {
-        const status = line.slice(0, 2).trim();
-        const file = line.slice(3);
-        return { status, file };
-      });
-      return {
-        clean: entries.length === 0,
-        entries,
-        count: entries.length
-      };
-    } catch (exc) {
-      const err = exc;
-      if ((err.stderr ?? "").toLowerCase().includes("not a git repository")) {
+  return async function git_status(args) {
+    const filePath = args.path ? String(args.path) : void 0;
+    const repo = await resolveRepoRoot(workspace, repoDirArg(workspace, args.repo) ?? filePath);
+    const res = await runGit(repo, ["status", "--porcelain"], 1e4);
+    if (res.status !== 0) {
+      const msg = res.stderr;
+      if (msg.toLowerCase().includes("not a git repository")) {
         return { error: "\u4E0D\u662F git \u4ED3\u5E93" };
       }
-      return { error: (err.stderr ?? err.message ?? "git status failed").slice(0, 300) };
-    }
+      return { error: (msg || "git status failed").trim().slice(0, 300) };
+    }
+    const lines = res.stdout.split("\n").map((l) => l.replace(/\r$/, "")).filter((l) => l.length > 0);
+    const entries = lines.map((line) => {
+      const status = line.slice(0, 2).trim();
+      const index = line.slice(0, 1).trim();
+      const worktree = line.slice(1, 2).trim();
+      let file = line.slice(3);
+      const renameArrow = file.indexOf(" -> ");
+      if (renameArrow >= 0) file = file.slice(renameArrow + 4);
+      return { status, file, index, worktree };
+    });
+    return { repo, clean: entries.length === 0, entries, count: entries.length };
   };
 }
 function makeGitDiff(workspace) {
-  return function git_diff(args) {
+  return async function git_diff(args) {
     const staged = args.staged === true;
     const filePath = args.path ? String(args.path) : void 0;
     const contextLines = Math.min(Number(args.context ?? 3), 10);
+    const repo = await resolveRepoRoot(workspace, repoDirArg(workspace, args.repo) ?? filePath);
     const cmd = ["diff"];
     if (staged) cmd.push("--staged");
     cmd.push(`-U${contextLines}`);
-    if (filePath) cmd.push("--", filePath);
-    try {
-      const out = execFileSync2("git", ["-C", workspace, ...cmd], {
-        encoding: "utf-8",
-        timeout: 15e3,
-        maxBuffer: 1024 * 1024 * 2
-      });
-      return {
-        staged,
-        path: filePath ?? null,
-        diff: out.slice(0, 5e4),
-        truncated: out.length > 5e4
-      };
-    } catch (exc) {
-      const err = exc;
-      return { error: (err.stderr ?? err.message ?? "git diff failed").slice(0, 300) };
+    const pathspec = toPathspec(repo, workspace, filePath);
+    if (pathspec) cmd.push("--", pathspec);
+    const res = await runGit(repo, cmd);
+    if (res.status !== 0) {
+      return { error: (res.stderr || "git diff failed").trim().slice(0, 300) };
     }
+    return {
+      repo,
+      staged,
+      path: filePath ?? null,
+      diff: res.stdout.slice(0, 5e4),
+      truncated: res.stdout.length > 5e4
+    };
   };
 }
 function registerGitTools(registry, workspace) {
@@ -2248,11 +2992,11 @@ function registerGitTools(registry, workspace) {
       type: "function",
       function: {
         name: "git_log",
-        description: "\u67E5\u770B\u6700\u8FD1\u7684 git \u63D0\u4EA4\u5386\u53F2 (hash, \u4F5C\u8005, \u65E5\u671F, \u4E3B\u9898)\u3002\u53EF\u9009\u5730\u9650\u5B9A\u5230\u67D0\u4E2A\u8DEF\u5F84\u3002\u7528\u4E8E\u5728\u7F16\u8F91\u524D\u4E86\u89E3\u4EE3\u7801\u7684\u6F14\u8FDB\u8FC7\u7A0B\u3002\u53EA\u8BFB\u3002",
+        description: "\u67E5\u770B\u6700\u8FD1\u7684 git \u63D0\u4EA4\u5386\u53F2 (hash, \u4F5C\u8005, \u65E5\u671F, \u4E3B\u9898)\u3002\u53EF\u9009\u5730\u9650\u5B9A\u5230\u67D0\u4E2A\u8DEF\u5F84\uFF08\u8BE5\u8DEF\u5F84\u6240\u5728\u4ED3\u5E93\u4F1A\u88AB\u81EA\u52A8\u5B9A\u4F4D\uFF09\u3002\u7528\u4E8E\u5728\u7F16\u8F91\u524D\u4E86\u89E3\u4EE3\u7801\u7684\u6F14\u8FDB\u8FC7\u7A0B\u3002\u53EA\u8BFB\u3002",
         parameters: {
           type: "object",
           properties: {
-            path: { type: "string", description: "\u53EF\u9009\uFF1A\u9650\u5B9A\u5230\u67D0\u4E2A\u6587\u4EF6\u6216\u76EE\u5F55" },
+            path: { type: "string", description: "\u53EF\u9009\uFF1A\u9650\u5B9A\u5230\u67D0\u4E2A\u6587\u4EF6\u6216\u76EE\u5F55\uFF08\u5E76\u6309\u5176\u6240\u5728\u4ED3\u5E93\u67E5\u8BE2\uFF09" },
             max_count: { type: "integer", description: "\u8FD4\u56DE\u591A\u5C11\u6761\u63D0\u4EA4 (\u9ED8\u8BA4 20\uFF0C\u6700\u5927 200)" }
           }
         }
@@ -2270,7 +3014,9 @@ function registerGitTools(registry, workspace) {
         description: "\u67E5\u770B\u5DE5\u4F5C\u533A git \u72B6\u6001 (\u5DF2\u4FEE\u6539\u3001\u5DF2\u6682\u5B58\u3001\u672A\u8DDF\u8E2A\u7684\u6587\u4EF6)\u3002\u53EA\u8BFB\u3002",
         parameters: {
           type: "object",
-          properties: {}
+          properties: {
+            path: { type: "string", description: "\u53EF\u9009\uFF1A\u4F18\u5148\u67E5\u8BE2\u8BE5\u8DEF\u5F84\u6240\u5728\u7684\u4ED3\u5E93\uFF08\u9ED8\u8BA4\u5DE5\u4F5C\u533A\u6839\uFF09" }
+          }
         }
       }
     }
@@ -2288,7 +3034,7 @@ function registerGitTools(registry, workspace) {
           type: "object",
           properties: {
             staged: { type: "boolean", description: "\u662F\u5426\u67E5\u770B\u5DF2\u6682\u5B58\u7684\u66F4\u6539 (\u9ED8\u8BA4 false)" },
-            path: { type: "string", description: "\u53EF\u9009\uFF1A\u9650\u5B9A\u5230\u67D0\u4E2A\u6587\u4EF6" },
+            path: { type: "string", description: "\u53EF\u9009\uFF1A\u9650\u5B9A\u5230\u67D0\u4E2A\u6587\u4EF6\uFF08\u5E76\u6309\u5176\u5728\u4ED3\u5E93\u4E2D\u7684\u8DEF\u5F84\uFF09" },
             context: { type: "integer", description: "\u4E0A\u4E0B\u6587\u884C\u6570 (\u9ED8\u8BA4 3)" }
           }
         }
@@ -2303,7 +3049,7 @@ function buildExplorerEngine(opts) {
   if (opts.readonlyRegistrars) {
     opts.readonlyRegistrars(registry);
   } else {
-    registerFileTools(registry, opts.workspace);
+    registerReadOnlyFileTools(registry, opts.workspace);
     registerSearchTool(registry, opts.workspace);
     registerGitTools(registry, opts.workspace);
   }
@@ -2317,7 +3063,8 @@ function buildExplorerEngine(opts) {
     permissions,
     model: opts.model,
     instructions: EXPLORER_INSTRUCTIONS,
-    maxIterations: 10
+    maxIterations: parseMaxIterations(process.env.EXPLORE_MAX_ITERATIONS, 30),
+    hook: opts.hook
   });
 }
 function makeExploreTool(opts) {
@@ -2328,7 +3075,8 @@ function makeExploreTool(opts) {
       workspace: opts.workspace,
       provider: opts.provider,
       model: opts.model,
-      readonlyRegistrars: opts.readonlyRegistrars
+      readonlyRegistrars: opts.readonlyRegistrars,
+      hook: opts.hookFactory?.()
     });
     let report = "";
     let status = "unknown";