minimal-agent 0.11.0 → 0.13.0

package/src/tools/bash/bash.ts

@@ -63,6 +63,11 @@ import { requestUserChoice } from '../../askBridge.js';
 import { classifyCommand } from '../../irreversible/rules.js';
 import { startBackgroundTask } from '../tasks/backgroundTaskService.js';
 import { processExecutionMetadata } from '../tasks/processEvidence.js';
+import {
+  permanentDeleteReason,
+  type ShellKind,
+} from '../shared/permanentDeleteGuard.js';
+import { ToolOutputStore } from '../shared/toolOutputStore.js';
 
 // ---------------- 0. 常量 ----------------
 
@@ -110,6 +115,17 @@ function detectWindowsBash(): string | null {
 
 const WIN_BASH = detectWindowsBash();
 
+/**
+ * 本工具这一刻**真正**把命令交给谁执行。
+ *
+ * 单一出处：description（告诉模型该写哪种语法）与 permanentDeleteGuard（按哪套动词
+ * 匹配删除命令）必须看同一个判断，否则就会出现「description 说这是 cmd、守卫却按
+ * bash 匹配」这种两头对不上的裂缝 —— del / rd 会因此直接穿过全部三层防护。
+ */
+function effectiveShellKind(): ShellKind {
+  return process.platform === 'win32' && !WIN_BASH ? 'cmd' : 'bash';
+}
+
 /**
  * G1：stdout / stderr 即时缓冲上限（各自）。命令狂输出（如 cat 大文件 / yes）时，
  * 在最终统一截断之前先把内存封顶，防 OOM。取最终展示截断阈值的 2 倍 —— 正常输出不受影响，
@@ -330,8 +346,11 @@ Some commands return non-zero exit codes for informational (non-error) reasons.
  - \`test\` / \`[\` exit 1 → condition is false (the answer to a question, not a failure)
 Only exit codes ≥ 2 from these commands indicate a real failure. For all other commands, non-zero exit codes are treated as failures normally.
 
-# Safety
-The following command patterns are blocked at the tool level and will fail before execution (no need to try them):
+# Safety - three levels, from strict to lenient
+
+## 1. Blocked outright (fails before execution - do NOT retry with variants)
+
+Catastrophic commands (no legitimate use):
  - \`rm -rf /\` and variants targeting root, $HOME, ~, or system directories (/etc, /usr, /bin, /Windows, /Users, /home, ...)
  - Filesystem destruction: \`mkfs\`, \`format X:\`, \`dd of=/dev/sdX\`, redirects to raw block devices
  - Power management: \`shutdown\`, \`reboot\`, \`halt\`, \`poweroff\`, \`init 0/6\`
@@ -339,9 +358,37 @@ The following command patterns are blocked at the tool level and will fail befor
  - Pipe-to-shell from network: \`curl ... | sh\`, \`wget ... | bash\`, etc.
  - \`chmod 777 /\`, Windows full-disk \`del /s\` / \`rmdir /s\`, \`diskpart\`
 
-If you have a legitimate use case that requires one of the above patterns, ask the user to run the command themselves in their terminal — do not try to bypass the check.
-
-Separately, Bash scans for common destructive-but-recoverable patterns (\`git reset --hard\`, \`git push -f\` / \`--force\` / \`--force-with-lease\`, \`git checkout .\`, \`git restore .\`, \`git clean -f\`, \`git stash drop/clear\`, \`git branch -D\`, \`git commit --amend\` / \`--no-verify\`, \`rm -rf <path>\`, \`DROP TABLE\`, \`TRUNCATE\`, \`DELETE FROM\`, \`kubectl delete\`, \`terraform destroy\`, etc.) and prepends a \`⚠️ 警告:\` line to the output. These commands are NOT blocked — the warning is informational. Treat it as a signal to double-check intent and surface the warning to the user when relevant.${
+Permanent deletion (bypasses the OS Trash / Recycle Bin - use the Trash tool instead):
+ - \`rm\`, \`unlink\`, \`rmdir\` (any shell-level file/dir deletion, any target)
+ - \`find ... -delete\`
+ - \`git clean -f\` / \`git clean --force\` (\`-n\` / \`--dry-run\` is fine)
+
+To delete files or directories use the **Trash** tool (\`action: "move"\` - recoverable); to clean Git untracked files use Trash with \`action: "git-clean"\`.
+Do NOT work around this by switching to \`find -delete\`, Python \`os.remove\`, Node \`fs.rm\`, or other shell variants - they are blocked the same way.
+If a permanent deletion is truly required, ask the user to run it themselves in their terminal.
+
+## 2. Requires user confirmation (irreversible)
+
+These have legitimate uses but destroy the last copy - execution pauses and asks the user to confirm. In non-interactive contexts (sub-agents, cron, batch mode) they are automatically cancelled.
+ - \`git push --force\` / \`-f\`, and \`git push origin +branch\` (+refspec = force push)
+ - \`git push --delete <branch>\` / \`git push :<branch>\` (deleting remote branches)
+ - \`git filter-branch\` / \`git filter-repo\` (rewriting history)
+ - \`git reflog expire --expire=now\` / \`git gc --prune=now\` (destroying reflog)
+ - \`shred -u\` / \`shred --remove\` (overwrite and delete - unrecoverable)
+ - SQL data destruction: \`DROP DATABASE\`, \`DROP TABLE\`, \`TRUNCATE TABLE\`
+
+## 3. Warning only (command still runs)
+
+These execute normally; a \`⚠️ 警告:\` line is prepended to the output as a reminder. They are NOT blocked.
+ - \`git reset --hard\` (reflog keeps it recoverable)
+ - \`git push --force-with-lease\` (rejects if the remote has unseen commits - the safe force-push form)
+ - \`git checkout -- .\` / \`git restore .\` (discards uncommitted changes)
+ - \`git branch -D\`, \`git stash drop\` / \`git stash clear\` (local, recoverable via reflog in most cases)
+ - \`git commit --amend\`, \`git commit --no-verify\`
+ - \`DELETE FROM ...\` (SQL row deletion; DROP/TRUNCATE are in level 2)
+ - \`kubectl delete\`, \`terraform destroy\`
+
+Regular Git operations (commit, add, status, log, diff, pull, fetch, checkout <branch>, merge, rebase, etc.) run without extra restrictions.${
   process.platform !== 'win32'
     ? ''
     : WIN_BASH
@@ -372,6 +419,12 @@ async function call(input: BashInput, signal?: AbortSignal, context?: ToolCallCo
       error: `安全检查拒绝执行：${forbiddenReason}\n命令：${command}`,
     };
   }
+  // 传**实际执行命令的 shell**，不是工具名：win32 上找不到 Git Bash 时下面走的是
+  // cmd.exe（见 WIN_BASH 探测），description 也会告诉模型「这里是 cmd」，模型于是写
+  // del / rd —— 按 'bash' 匹配的话这两个词一个都拦不住（黑名单与 irreversible 规则表
+  // 同样只认 POSIX 形态），等于三层全空。
+  const permanentDelete = permanentDeleteReason(command, effectiveShellKind());
+  if (permanentDelete) return { ok:false, error:`永久删除检查拒绝执行：${permanentDelete}\n命令：${command}` };
 
   // 4a-1. 不可逆动作闸门：毁掉「最后一份副本」的命令要**停下来问人**。
   //
@@ -422,20 +475,21 @@ async function call(input: BashInput, signal?: AbortSignal, context?: ToolCallCo
       const cwd = context?.cwd ?? getWorkingDir();
       const task = await startBackgroundTask(
         WIN_BASH
-          ? { command, executable: WIN_BASH, args: ['-c', command], cwd, env: sanitizedChildEnv(), sessionId: context?.sessionId, shellKind: 'bash' as const }
+          ? { command, executable: WIN_BASH, args: ['-c', command], cwd, env: sanitizedChildEnv(), sessionId: context?.sessionId, workspaceId: context?.workspaceId, shellKind: 'bash' as const }
           : {
               command: process.platform === 'win32' ? `chcp 65001 >nul & ${command}` : command,
               cwd,
               env: sanitizedChildEnv(),
               shell: true,
               sessionId: context?.sessionId,
+              workspaceId: context?.workspaceId,
               shellKind: 'bash' as const,
             },
         context?.sessionState?.backgroundTasks,
       );
       return {
         ok: true,
-        content: `${destructiveWarning ? `⚠️ 警告: ${destructiveWarning}\n` : ''}后台任务已启动。task_id=${task.id}\nlog=${task.logPath}\n使用 TaskOutput 增量读取输出，TaskStop 停止进程。`,
+        content: `${destructiveWarning ? `⚠️ 警告: ${destructiveWarning}\n` : ''}后台任务已启动。task_id=${task.id.replace(/^proc_/,'')}\nprocess_id=${task.id}\nlog=${task.logPath}\n使用 TaskOutput 增量读取输出，TaskStop 停止进程。`,
         metadata: processExecutionMetadata({ shell: 'bash', mode: 'background', command, status: 'started', taskId: task.id }),
       };
     } catch (error) {
@@ -449,6 +503,10 @@ async function call(input: BashInput, signal?: AbortSignal, context?: ToolCallCo
   //     Windows 无 bash:    cmd.exe，命令前缀 chcp 65001 强制 UTF-8 输出
   let stdout = '';
   let stderr = '';
+  const outputStore = new ToolOutputStore({
+    workspaceId: context?.workspaceId,
+    sessionId: context?.sessionId,
+  });
   let exitCode: number | null = null;
   let timedOut = false;
   let killedBySignal = false;
@@ -496,12 +554,16 @@ async function call(input: BashInput, signal?: AbortSignal, context?: ToolCallCo
       child.stdout?.setEncoding('utf8');
       child.stderr?.setEncoding('utf8');
       child.stdout?.on('data', (chunk) => {
-        // G1：即时封顶，防止狂输出命令在最终截断前撑爆内存（OOM）。不强行 kill，
-        // 让命令自己跑完或被 timeout 收走；超出上限的部分直接丢弃，最终仍按上限截断展示。
-        if (stdout.length < MAX_STREAM_BUFFER_CHARS) stdout += chunk;
+        if (!outputStore.append('stdout', chunk)) {
+          child.stdout?.pause();
+          outputStore.onDrain(() => child.stdout?.resume());
+        }
       });
       child.stderr?.on('data', (chunk) => {
-        if (stderr.length < MAX_STREAM_BUFFER_CHARS) stderr += chunk;
+        if (!outputStore.append('stderr', chunk)) {
+          child.stderr?.pause();
+          outputStore.onDrain(() => child.stderr?.resume());
+        }
       });
       child.on('error', (e) => {
         ac.signal.removeEventListener('abort', onKill);
@@ -524,6 +586,9 @@ async function call(input: BashInput, signal?: AbortSignal, context?: ToolCallCo
     clearTimeout(timer);
     signal?.removeEventListener('abort', onAbort);
   }
+  const storedOutput = await outputStore.finish();
+  stdout = storedOutput.stdout;
+  stderr = storedOutput.stderr;
 
   // 4b-2. ATTACH_IMAGE sentinel：脚本可以打一行 `<<<ATTACH_IMAGE:path>>>` 让模型亲眼看图。
   //       协议行**从 content 剥掉**（那是给宿主看的，不是给模型读的噪声）；被拒的条目
@@ -555,15 +620,18 @@ async function call(input: BashInput, signal?: AbortSignal, context?: ToolCallCo
     parts.push(`\n[被信号中断]`);
   }
   parts.push(`\n[exit code: ${exitCode === null ? 'killed' : exitCode}]`);
+  const outputReference = storedOutput.path
+    ? `\n[完整输出: ${storedOutput.path}; bytes=${storedOutput.bytes}; sha256=${storedOutput.sha256}; complete=${storedOutput.complete}]`
+    : '';
 
   let combinedOutput = parts.join('\n');
 
   // 4d. 大小兜底
-  if (combinedOutput.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+  if (combinedOutput.length + outputReference.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+    const suffix = `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，预览已截断)${outputReference}`;
     combinedOutput =
-      combinedOutput.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
-      `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
-  }
+      combinedOutput.slice(0, Math.max(0, DEFAULT_MAX_RESULT_SIZE_CHARS - suffix.length)) + suffix;
+  } else combinedOutput += outputReference;
 
   // 4e. 中断 / 超时仍然算硬失败
   //     失败也带上已解析的附图：脚本挂掉前截的那张诊断图正是最该看的。

package/src/tools/capabilities.js

@@ -1,8 +1,13 @@
 const TOOL_CAPABILITIES = Object.freeze({
     Read: 'files.read', Glob: 'files.read', Grep: 'files.read',
+    Snip: 'files.read',
     Edit: 'files.write', MultiEdit: 'files.write', Write: 'files.write',
     Bash: 'shell',
     PowerShell: 'shell', TaskOutput: 'background.process', TaskStop: 'background.process',
+    Trash: 'files.trash',
+    TaskCreate: 'task.management', TaskGet: 'task.management', TaskUpdate: 'task.management', TaskList: 'task.management',
+    Skill: 'skill.invoke', EnterWorktree: 'worktree.session', ExitWorktree: 'worktree.session',
+    TerminalCapture: 'terminal.capture',
     LSP: 'code.intelligence', NotebookEdit: 'files.write',
     WebSearch: 'web.search', WebFetch: 'web.fetch', WebBrowser: 'web.browser',
     Download: 'network.download',

package/src/tools/capabilities.ts

@@ -14,15 +14,25 @@ export type CapabilityId =
   | 'media'
   | 'memory'
   | 'code.intelligence'
-  | 'background.process';
+  | 'background.process'
+  | 'files.trash'
+  | 'task.management'
+  | 'skill.invoke'
+  | 'worktree.session'
+  | 'terminal.capture';
 
 export type ToolBudgetClass = 'core' | 'task' | 'auxiliary';
 
 const TOOL_CAPABILITIES: Readonly<Record<string, CapabilityId>> = Object.freeze({
   Read: 'files.read', Glob: 'files.read', Grep: 'files.read',
+  Snip: 'files.read',
   Edit: 'files.write', MultiEdit: 'files.write', Write: 'files.write',
   Bash: 'shell',
   PowerShell: 'shell', TaskOutput: 'background.process', TaskStop: 'background.process',
+  Trash: 'files.trash',
+  TaskCreate: 'task.management', TaskGet: 'task.management', TaskUpdate: 'task.management', TaskList: 'task.management',
+  Skill: 'skill.invoke', EnterWorktree: 'worktree.session', ExitWorktree: 'worktree.session',
+  TerminalCapture: 'terminal.capture',
   LSP: 'code.intelligence', NotebookEdit: 'files.write',
   WebSearch: 'web.search', WebFetch: 'web.fetch', WebBrowser: 'web.browser',
   Download: 'network.download',

package/src/tools/edit/edit.js

@@ -20,6 +20,7 @@ import { filePathField } from '../shared/schemas.js';
 import { assertFresh, hashFileBytes, recordRead, wasTruncated } from '../shared/fileState.js';
 import { fileActivityMetadata } from '../shared/fileActivity.js';
 import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
 /** 编辑文件大小上限：1GB。防止模型试图 Edit 超大文件撑爆内存。 */
 const MAX_EDIT_FILE_SIZE_BYTES = 1024 * 1024 * 1024;
 // ---------------- 1. Zod 输入 schema ----------------
@@ -96,10 +97,11 @@ async function call(input, state, cwd) {
             await atomicWriteFile(filePath, new_string);
             recordRead(filePath, { contentHash: hashFileBytes(encodeTextFile(new_string, 'utf8')) }, state);
             emitFileMutation(filePath);
+            const patch = buildPatchSummary('', new_string, input.file_path);
             return {
                 ok: true,
-                content: `已创建新文件：${filePath}（${new_string.length} 字符）`,
-                metadata: await fileActivityMetadata(filePath, 'created', 'not_run', 'support', cwd),
+                content: `已创建新文件：${filePath}（${new_string.length} 字符）\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+                metadata: await fileActivityMetadata(filePath, 'created', 'not_run', 'support', cwd, patch),
             };
         }
         catch (e) {
@@ -186,12 +188,13 @@ async function call(input, state, cwd) {
     // 输出：报告改了几处 + 行变化
     const linesBefore = original.split('\n').length;
     const linesAfter = replaced.split('\n').length;
+    const patch = buildPatchSummary(original, normalizedReplaced, input.file_path);
     return {
         ok: true,
         content: `已编辑 ${filePath}\n` +
             `替换次数：${replaceAll ? occurrences : 1}\n` +
-            `行数：${linesBefore} → ${linesAfter}`,
-        metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd),
+            `行数：${linesBefore} → ${linesAfter}\n` + (patch.unifiedDiff ?? '[diff omitted: too large]'),
+        metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd, patch),
     };
 }
 // ---------------- 5. 模糊匹配提示 ----------------

package/src/tools/edit/edit.ts

@@ -35,6 +35,7 @@ import { filePathField } from '../shared/schemas.js';
 import { assertFresh, hashFileBytes, recordRead, wasTruncated, type FileReadState } from '../shared/fileState.js';
 import { fileActivityMetadata } from '../shared/fileActivity.js';
 import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
 
 /** 编辑文件大小上限：1GB。防止模型试图 Edit 超大文件撑爆内存。 */
 const MAX_EDIT_FILE_SIZE_BYTES = 1024 * 1024 * 1024;
@@ -124,10 +125,11 @@ async function call(input: EditInput, state?: FileReadState, cwd?: string): Prom
       await atomicWriteFile(filePath, new_string);
       recordRead(filePath, { contentHash: hashFileBytes(encodeTextFile(new_string, 'utf8')) }, state);
       emitFileMutation(filePath);
+      const patch = buildPatchSummary('', new_string, input.file_path);
       return {
         ok: true,
-        content: `已创建新文件：${filePath}（${new_string.length} 字符）`,
-      metadata: await fileActivityMetadata(filePath, 'created', 'not_run', 'support', cwd),
+        content: `已创建新文件：${filePath}（${new_string.length} 字符）\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+        metadata: await fileActivityMetadata(filePath, 'created', 'not_run', 'support', cwd, patch),
       };
     } catch (e) {
       return { ok: false, error: `创建文件失败：${(e as Error).message}` };
@@ -222,13 +224,14 @@ async function call(input: EditInput, state?: FileReadState, cwd?: string): Prom
   // 输出：报告改了几处 + 行变化
   const linesBefore = original.split('\n').length;
   const linesAfter = replaced.split('\n').length;
+  const patch = buildPatchSummary(original, normalizedReplaced, input.file_path);
   return {
     ok: true,
     content:
       `已编辑 ${filePath}\n` +
       `替换次数：${replaceAll ? occurrences : 1}\n` +
-      `行数：${linesBefore} → ${linesAfter}`,
-      metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd),
+      `行数：${linesBefore} → ${linesAfter}\n` + (patch.unifiedDiff ?? '[diff omitted: too large]'),
+    metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd, patch),
   };
 }
 

package/src/tools/edit/multi-edit.js

@@ -22,6 +22,7 @@ import { filePathField } from '../shared/schemas.js';
 import { assertFresh, hashFileBytes, recordRead, wasTruncated } from '../shared/fileState.js';
 import { fileActivityMetadata } from '../shared/fileActivity.js';
 import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
 // ---------------- 1. Zod 输入 schema ----------------
 const editItemSchema = z.object({
     old_string: z.string().min(1).describe('要替换的原文本（不允许为空 —— 创建新文件请用 Edit 工具）'),
@@ -168,10 +169,11 @@ async function call(input, state, cwd) {
     catch (e) {
         return { ok: false, error: `写入失败：${e.message}` };
     }
+    const patch = buildPatchSummary(originalContent, finalContent, input.file_path);
     return {
         ok: true,
-        content: `已对 ${filePath} 应用 ${edits.length} 处修改`,
-        metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd),
+        content: `已对 ${filePath} 应用 ${edits.length} 处修改\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+        metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd, patch),
     };
 }
 // ---------------- 5. 导出 ----------------

package/src/tools/edit/multi-edit.ts

@@ -37,6 +37,7 @@ import { filePathField } from '../shared/schemas.js';
 import { assertFresh, hashFileBytes, recordRead, wasTruncated, type FileReadState } from '../shared/fileState.js';
 import { fileActivityMetadata } from '../shared/fileActivity.js';
 import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
 
 // ---------------- 1. Zod 输入 schema ----------------
 const editItemSchema = z.object({
@@ -199,10 +200,11 @@ async function call(input: MultiEditInput, state?: FileReadState, cwd?: string):
     return { ok: false, error: `写入失败：${(e as Error).message}` };
   }
 
+  const patch = buildPatchSummary(originalContent, finalContent, input.file_path);
   return {
     ok: true,
-    content: `已对 ${filePath} 应用 ${edits.length} 处修改`,
-    metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd),
+    content: `已对 ${filePath} 应用 ${edits.length} 处修改\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+    metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd, patch),
   };
 }
 

package/src/tools/glob/glob.js

@@ -3,12 +3,13 @@
  *  src/tools/glob.ts —— Glob 工具（按文件名模式匹配）
  * ------------------------------------------------------------
  *  对应 kakadeai 主仓库的 GlobTool。
- *  实现用 fast-glob（npm 包），默认按 mtime 倒序排列（新文件在前）。
+ *  实现用 fast-glob（npm 包），默认按发现顺序流式返回。
  *  支持限制候选数量，并通过结构化元数据返回大小和修改时间。
  * ============================================================
  */
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import fg from 'fast-glob';
+import { stat } from 'node:fs/promises';
 import { z } from 'zod';
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
@@ -23,10 +24,34 @@ const inputSchema = z.object({
         .string()
         .optional()
         .describe('搜索的根目录（默认当前工作目录）；省略时不要传 "undefined" 字符串'),
-    sort_by: z.enum(['modified', 'path']).default('modified').optional().describe('排序字段，默认 modified'),
-    order: z.enum(['asc', 'desc']).default('desc').optional().describe('排序方向，默认 desc（最新在前）'),
-    offset: z.number().int().min(0).optional().describe('跳过前 N 个结果，默认 0'),
-    limit: z.number().int().min(0).max(10_000).optional().describe('最多返回多少个候选文件；默认 200，0 表示不限制'),
+    strategy: z
+        .enum(['fast', 'complete'])
+        .default('fast')
+        .optional()
+        .describe('fast 在收集够分页候选后提前停止；完整排序请用 complete'),
+    sort_by: z
+        .enum(['discovery', 'modified', 'path'])
+        .default('discovery')
+        .optional()
+        .describe('排序字段，默认 discovery'),
+    order: z
+        .enum(['asc', 'desc'])
+        .default('desc')
+        .optional()
+        .describe('排序方向，默认 desc（最新在前）'),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe('跳过前 N 个结果，默认 0'),
+    limit: z
+        .number()
+        .int()
+        .min(0)
+        .max(10_000)
+        .optional()
+        .describe('最多返回多少个候选文件；默认 200，0 表示不限制'),
 });
 // ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
 const parameters = toToolParameters(inputSchema);
@@ -34,12 +59,12 @@ const parameters = toToolParameters(inputSchema);
 const description = `- Fast file pattern matching tool that works with any codebase size
 - Supports glob patterns like "**/*.js" or "src/**/*.ts"
 - Returns structured file candidates with path, size, and modification time
-- Defaults to modification time descending, which is useful for requests like "find the latest contract"
+- Defaults to streaming discovery order; request sort_by=modified with strategy=complete for newest-file queries
 - Discovery does not present files to the user; use Read for selected source files and PresentResult for delivered files
 - Use this tool when you need to find files by name patterns
 - When you need to do an open ended search that may require multiple rounds, prefer the Grep tool for content search`;
 // ---------------- 4. call() ----------------
-async function call(input, runCwd = getWorkingDir()) {
+async function call(input, runCwd = getWorkingDir(), signal) {
     // 以 getWorkingDir() 为锚，而非裸 resolve()（同 grep.ts 的坑：后者落回 process.cwd()，
     // 多工作区宿主进程里会与当前工作区脱节）。resolve 对绝对路径行为不变。
     const cwd = input.path ? resolve(runCwd, input.path) : runCwd;
@@ -47,69 +72,160 @@ async function call(input, runCwd = getWorkingDir()) {
     // Windows 用户/模型可能传 "src\**\*.ts"，这里统一替换。
     // （cwd 用原生路径没问题；fast-glob 内部会处理）
     const pattern = input.pattern.replace(/\\/g, '/');
-    // fast-glob 自带 ignore 一部分（node_modules 之类还是要显式排除）
-    let matches;
+    const offset = input.offset ?? 0, limit = input.limit ?? 200, strategy = input.strategy ?? 'fast', sortBy = input.sort_by ?? 'discovery';
+    const needed = limit === 0 ? Number.POSITIVE_INFINITY : offset + limit + 1;
+    const ignore = ['node_modules', '.git', '.svn', '.hg', '.jj', '.sl', 'dist']
+        .filter((name) => !pattern.split('/').includes(name))
+        .map((name) => `**/${name}/**`);
+    const candidates = [];
+    let scanned = 0;
+    let stoppedEarly = false;
+    const effectiveOrder = input.order ?? (sortBy === 'discovery' ? 'asc' : 'desc');
+    const compare = (a, b) => {
+        const value = sortBy === 'path'
+            ? a.path.localeCompare(b.path)
+            : sortBy === 'modified'
+                ? a.mtime - b.mtime
+                : a.discovery - b.discovery;
+        return value * (effectiveOrder === 'desc' ? -1 : 1);
+    };
+    // 最大堆的根始终是当前保留集合里“最差”的候选，完整扫描只占 O(offset+limit) 内存。
+    const bubbleUp = (index) => {
+        while (index > 0) {
+            const parent = Math.floor((index - 1) / 2);
+            if (compare(candidates[parent], candidates[index]) >= 0)
+                break;
+            [candidates[parent], candidates[index]] = [
+                candidates[index],
+                candidates[parent],
+            ];
+            index = parent;
+        }
+    };
+    const bubbleDown = (index) => {
+        while (true) {
+            const left = index * 2 + 1, right = left + 1;
+            let worst = index;
+            if (left < candidates.length &&
+                compare(candidates[left], candidates[worst]) > 0)
+                worst = left;
+            if (right < candidates.length &&
+                compare(candidates[right], candidates[worst]) > 0)
+                worst = right;
+            if (worst === index)
+                break;
+            [candidates[index], candidates[worst]] = [
+                candidates[worst],
+                candidates[index],
+            ];
+            index = worst;
+        }
+    };
+    const retain = (item) => {
+        if (limit === 0) {
+            candidates.push(item);
+            return;
+        }
+        if (candidates.length < needed) {
+            candidates.push(item);
+            bubbleUp(candidates.length - 1);
+        }
+        else if (compare(item, candidates[0]) < 0) {
+            candidates[0] = item;
+            bubbleDown(0);
+        }
+    };
     try {
-        matches = await fg(pattern, {
+        const stream = fg.stream(pattern, {
             cwd,
             dot: true,
             onlyFiles: true,
             followSymbolicLinks: false,
-            // Explicit patterns win over defaults (fast-glob ignore otherwise always wins).
-            ignore: ['node_modules', '.git', '.svn', '.hg', '.jj', '.sl', 'dist']
-                .filter((name) => !pattern.split('/').includes(name))
-                .map((name) => `**/${name}/**`),
+            ignore,
             absolute: false,
-            stats: true,
         });
+        for await (const raw of stream) {
+            if (signal?.aborted) {
+                stream.destroy?.();
+                throw new Error('aborted');
+            }
+            const path = Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw);
+            scanned++;
+            if (strategy === 'fast' && sortBy === 'discovery') {
+                candidates.push({ path, mtime: 0, size: 0, discovery: scanned });
+                if (candidates.length >= needed) {
+                    stoppedEarly = true;
+                    stream.destroy?.();
+                    break;
+                }
+                continue;
+            }
+            const info = sortBy === 'modified'
+                ? await stat(resolve(cwd, path))
+                : { mtimeMs: 0, size: 0 };
+            const item = {
+                path,
+                mtime: info.mtimeMs,
+                size: info.size,
+                discovery: scanned,
+            };
+            retain(item);
+        }
     }
     catch (e) {
         return { ok: false, error: `glob 失败：${e.message}` };
     }
-    if (matches.length === 0) {
-        return { ok: true, content: `(no files matched pattern "${pattern}" in ${cwd})` };
+    if (candidates.length === 0) {
+        return {
+            ok: true,
+            content: `(no files matched pattern "${pattern}" in ${cwd})`,
+        };
     }
     // 候选携带稳定元数据。发现候选本身不代表文件已经成为会话上下文。
-    const withMtime = await Promise.all(matches.map(async (entry) => ({
-        path: entry.path,
-        mtime: entry.stats?.mtimeMs ?? 0,
-        size: entry.stats?.size ?? 0,
-    })));
-    const direction = (input.order ?? 'desc') === 'desc' ? -1 : 1;
-    withMtime.sort((a, b) => {
-        const compared = (input.sort_by ?? 'modified') === 'path'
-            ? a.path.localeCompare(b.path)
-            : a.mtime - b.mtime;
-        return compared * direction;
-    });
-    const offset = input.offset ?? 0;
-    const limit = input.limit ?? 200;
-    const selected = limit === 0 ? withMtime.slice(offset) : withMtime.slice(offset, offset + limit);
-    const truncated = offset + selected.length < withMtime.length;
+    const withMtime = candidates;
+    withMtime.sort(compare);
+    const selected = limit === 0
+        ? withMtime.slice(offset)
+        : withMtime.slice(offset, offset + limit);
+    const truncated = stoppedEarly || offset + selected.length < withMtime.length;
+    for (const item of selected) {
+        if (item.size === 0 && item.mtime === 0) {
+            const info = await stat(resolve(cwd, item.path)).catch(() => undefined);
+            if (info) {
+                item.size = info.size;
+                item.mtime = info.mtimeMs;
+            }
+        }
+    }
     // 输出：每行一个相对路径
     let content = selected.map((m) => m.path).join('\n');
     // 超条数截断：保留旧文件（头部），丢弃新文件（尾部）
     if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
         content =
             content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
-                `\n\n... (共 ${withMtime.length} 个文件，输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
+                `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
     }
     const workspaceRoot = resolve(runCwd);
     return {
         ok: true,
-        content: `${content}\n\n(匹配 ${withMtime.length} 个，返回 ${selected.length} 个，offset=${offset}${truncated ? '，仍有后续结果' : ''}，按 ${input.sort_by ?? 'modified'} ${input.order ?? 'desc'} 排序)`,
+        content: `${content}\n\n(${stoppedEarly ? `至少扫描 ${scanned} 个` : `匹配 ${scanned} 个`}，返回 ${selected.length} 个，offset=${offset}${truncated ? '，仍有后续结果' : ''}，按 ${sortBy} ${effectiveOrder} 排序)`,
         metadata: {
             kind: 'file_discovery',
             files: selected.flatMap((entry) => {
                 const absolute = resolve(cwd, entry.path);
                 const rel = relative(workspaceRoot, absolute);
-                if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+                if (!rel ||
+                    rel === '..' ||
+                    rel.startsWith(`..${sep}`) ||
+                    isAbsolute(rel))
                     return [];
-                return [{
+                return [
+                    {
                         relativePath: rel.split(sep).join('/'),
                         size: entry.size,
                         modifiedAt: entry.mtime,
-                    }];
+                    },
+                ];
             }),
         },
     };
@@ -124,6 +240,6 @@ export const globTool = {
     isConcurrencySafe: true,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'cancel',
-    call: (input) => call(input),
-    callWithContext: (input, _signal, context) => call(input, context.cwd),
+    call: (input, signal) => call(input, undefined, signal),
+    callWithContext: (input, signal, context) => call(input, context.cwd, signal),
 };