minimal-agent 0.11.0 → 0.13.0

package/src/tools/agent/agent.ts

@@ -3,14 +3,12 @@
  *  src/tools/agent/agent.ts —— Agent 工具（fork 子 agent / 多 agent 并行）
  * ------------------------------------------------------------
  *  借鉴 Claude Code 官方 AgentTool/ForkAgent 的核心思想，按 minimal-agent
- *  内核架构做同步等效实现：
+ *  内核架构做可恢复的前台/后台等效实现：
  *    - 官方 fork = 「隔离 context 嵌套跑同一主循环 + 摘要回传（完整历史不进
- *      父上下文）」。我们不需要它的后台任务队列/AsyncLocalStorage 身份追踪
- *      （那是为 Ink UI 后台任务服务的）——本工具同步 await 一个嵌套 runQuery，
- *      声明 isConcurrencySafe:true 后，模型在同一轮发出 N 个 Agent 调用时，
- *      loop.ts 现成的并行 worker 队列自动把它们并发执行。这就是并行的全部来源。
- *    - 同轮混入任一非并发安全工具（如 Edit）会整轮退化串行——这是想要的安全
- *      语义（写操作与并行 fork 不该交错）。
+ *      父上下文）」。本工具在隔离 history 中嵌套运行同一主循环，并将私有历史、
+ *      进度和结果写入会话运行存储；前台、后台和重启后续接共用同一执行内核。
+ *    - 同轮多个 Agent 调用仍由 loop.ts 的并行 worker 执行；write scopes 与可选
+ *      worktree 负责隔离真正可并行的写任务。
  *
  *  已知限制（如实声明）：
  *    - 子 agent 的 LoopEvent 不外泄：-p / stream-json 宿主只看到本工具的一对
@@ -28,6 +26,8 @@
  */
 
 import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { access } from 'node:fs/promises';
 import { withAskSource } from '../../askBridge.js';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { z } from 'zod';
@@ -59,6 +59,7 @@ import {
   worktreeChangedFiles,
   worktreeDiffStat,
 } from './worktree.js';
+import { appendAgentEvent, loadAgentRecord, saveAgentRecord, type AgentTaskRecord, type LiveAgentTask } from './agentTaskService.js';
 
 // ---------------- 0. 环内模块懒加载（见文件头「循环依赖纪律」） ----------------
 
@@ -116,6 +117,8 @@ const inputSchema = z.object({
     .describe(
       'general 预计修改的工作目录相对路径。范围互不重叠时可并行；缺省时按整个工作目录串行。explore 不需要。',
     ),
+  run_in_background: z.boolean().optional().describe('立即返回 agent_id，子任务在后台运行；用 TaskOutput/TaskStop 管理'),
+  resume_agent_id: z.string().regex(/^agent_[0-9a-f-]{36}$/i).optional().describe('继续当前会话中此前完成、中断或失败的 Agent 历史'),
 });
 type AgentInput = z.infer<typeof inputSchema>;
 
@@ -124,9 +127,10 @@ const parameters = toToolParameters(inputSchema);
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
 // 借鉴官方 AgentTool prompt 文案（任务书自包含 / 同轮并行 / 何时不用）。
 
-const description = `- Launches a stateless sub-agent with a fresh, isolated context to execute one self-contained subtask; returns only its final report text (its full working history never enters this conversation).
+const description = `- Launches an isolated sub-agent for one self-contained task. Every run returns an agent_id; run_in_background=true continues without blocking, and resume_agent_id continues its persisted private history across user turns or an app restart.
 - The sub-agent CANNOT see this conversation. The \`prompt\` must be fully self-contained: background, exact file paths, what to look for / do, and the expected output format.
 - **To parallelize, emit multiple Agent calls in ONE assistant message** — they run concurrently. This is the main value of this tool.
+- Background Agent progress/results are read with TaskOutput and stopped with TaskStop. Do not poll: TaskOutput(block=true) waits efficiently.
 - Use for: exploring/researching several independent areas of a codebase at once, parallel information gathering from multiple sources, independent analyses that will be synthesized afterwards, and (with agent_type:'general') genuinely parallelizable write/execute work.
 - Do NOT use for: single targeted lookups that one or two direct tool calls would answer (a fork starts cold and re-derives context — slower and costlier), or strictly sequential work. Only general execution agents may ask the user, and only when genuinely blocked.
 - agent_type: 'explore' (default) = strictly read-only research; 'general' = read-write execution. For direct writes, declare relative write_scopes; disjoint scopes may run concurrently, overlapping or omitted scopes are serialized.
@@ -222,6 +226,10 @@ export function extractCoveredFiles(
 export interface AgentTaskDeps {
   chat?: RunQueryOptions['chat'];
   executeTool?: RunQueryOptions['executeTool'];
+  initialHistory?: RunQueryOptions['history'];
+  captureHistory?: (history:RunQueryOptions['history'])=>void|Promise<void>;
+  existingWorktree?: AgentWorktree;
+  onWorktreeCreated?: (worktree: AgentWorktree) => void | Promise<void>;
 }
 
 function positiveInt(value: string | undefined): number | undefined {
@@ -296,10 +304,10 @@ export async function runAgentTask(
   const allowedTools = def.resolveAllowedTools(ALL_TOOLS.map((t) => t.name));
 
   // ---- worktree 隔离（仅 general 显式要求时） ----
-  let wt: AgentWorktree | null = null;
+  let wt: AgentWorktree | null = deps.existingWorktree ?? null;
   const isolation = input.isolation ?? ctx.subagentConfig?.defaultWriteIsolation ?? 'none';
-  if (def.type === 'general' && isolation === 'worktree') {
-    const created = await createAgentWorktree(`fork-${randomUUID().slice(0, 8)}`);
+  if (def.type === 'general' && isolation === 'worktree' && !wt) {
+    const created = await createAgentWorktree(`fork-${randomUUID().slice(0, 8)}`, ctx.cwd);
     if (!created.ok) {
       return {
         ok: false,
@@ -307,8 +315,9 @@ export async function runAgentTask(
       };
     }
     wt = created;
+    await deps.onWorktreeCreated?.(created);
   }
-  const cwd = wt?.path ?? getWorkingDir();
+  const cwd = wt?.path ?? ctx.cwd ?? getWorkingDir();
   let writeScopes: string[];
   try {
     writeScopes = def.type === 'general'
@@ -348,6 +357,7 @@ export async function runAgentTask(
       surface: 'subagent',
       cwd,
       workspaceId: ctx.workspaceId,
+      sessionId: ctx.sessionId,
       interactiveAsk: childRuntime.interactiveAsk,
       memoryAccess: childMemoryAccess,
       currentUserInput: input.prompt,
@@ -364,7 +374,7 @@ export async function runAgentTask(
   };
 
   // ---- 子 history：一条 system（压缩按 role 定位，必须存在）+ runQuery 自己 push 任务书 ----
-  const history: RunQueryOptions['history'] = [
+  const history: RunQueryOptions['history'] = deps.initialHistory?.length ? [...deps.initialHistory] : [
     { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools) },
   ];
   const historyLenBefore = history.length;
@@ -582,6 +592,7 @@ export async function runAgentTask(
   } finally {
     stopTimeout();
     releaseLease?.();
+    await deps.captureHistory?.(history);
   }
 
   // ---- 结局映射（直接查 signal 状态，不依赖事件旗标） ----
@@ -684,6 +695,130 @@ async function call(input: AgentInput, signal?: AbortSignal): Promise<ToolResult
   return runAgentTask(input, signal, {});
 }
 
+export async function runManagedAgentTask(
+  input: AgentInput,
+  signal: AbortSignal | undefined,
+  ctx: ToolCallContext,
+  deps: AgentTaskDeps = {},
+): Promise<ToolResult> {
+  if (!ctx.sessionState) return runAgentTask(input, signal, ctx);
+  const id = input.resume_agent_id ?? `agent_${randomUUID()}`;
+  let initialHistory: RunQueryOptions['history'] | undefined;
+  let resumedWorktree: AgentWorktree | undefined;
+  let coreInput = { ...input, run_in_background: undefined, resume_agent_id: undefined };
+  if (input.resume_agent_id) {
+    const live = ctx.sessionState.agentTasks.tasks.get(id);
+    if (live?.status === 'running') return { ok: false, error: `Agent ${id} 正在运行，不能并发恢复` };
+    const saved = await loadAgentRecord(ctx, id);
+    if (!saved) return { ok: false, error: `找不到可恢复 Agent：${id}` };
+    initialHistory = saved.history;
+    resumedWorktree = saved.worktree && await access(saved.worktree.path)
+      .then(() => saved.worktree)
+      .catch(() => undefined);
+    coreInput = {
+      ...(saved.input as AgentInput),
+      prompt: input.prompt,
+      description: input.description || saved.description,
+      run_in_background: undefined,
+      resume_agent_id: undefined,
+    };
+  }
+  const abort = new AbortController();
+  const combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+  let settle!: () => void;
+  const completion = new Promise<void>((resolvePromise) => { settle = resolvePromise; });
+  const task: LiveAgentTask = {
+    id,
+    status: 'running',
+    description: coreInput.description,
+    input: coreInput as unknown as Record<string, unknown>,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    abort,
+    completion,
+    events: new EventEmitter(),
+  };
+  ctx.sessionState.agentTasks.tasks.set(id, task);
+  await saveAgentRecord(ctx, task);
+  await appendAgentEvent(ctx, id, { phase: 'started', resumed: Boolean(input.resume_agent_id) });
+
+  const run = async (): Promise<ToolResult> => {
+    let captured = initialHistory;
+    let lastPersistedProgressAt = 0;
+    const managedContext: ToolCallContext = {
+      ...ctx,
+      reportProgress: (line, detail) => {
+        ctx.reportProgress?.(line, detail);
+        task.progress = line;
+        task.events.emit('change');
+        if (Date.now() - lastPersistedProgressAt >= 1_000) {
+          lastPersistedProgressAt = Date.now();
+          void saveAgentRecord(ctx, task).catch(() => undefined);
+          void appendAgentEvent(ctx, id, { phase: 'progress', message: line })
+            .catch(() => undefined);
+        }
+      },
+    };
+    try {
+      const result = await runAgentTask(coreInput, combined, managedContext, {
+        ...deps,
+        initialHistory,
+        existingWorktree: resumedWorktree,
+        onWorktreeCreated: async (worktree) => {
+          task.worktree = worktree;
+          await saveAgentRecord(ctx, task);
+        },
+        captureHistory: (history) => { captured = [...history]; },
+      });
+      task.result = result;
+      task.history = captured;
+      task.status = abort.signal.aborted ? 'stopped' : result.ok ? 'completed' : 'failed';
+      if (task.worktree && !await access(task.worktree.path).then(() => true).catch(() => false)) {
+        task.worktree = undefined;
+      }
+      task.updatedAt = Date.now();
+      await saveAgentRecord(ctx, task);
+      await appendAgentEvent(ctx, id, { phase: task.status, ok: result.ok });
+      return result;
+    } catch (error) {
+      task.status = abort.signal.aborted ? 'stopped' : 'failed';
+      task.result = { ok: false, error: (error as Error).message };
+      task.history = captured;
+      task.updatedAt = Date.now();
+      await saveAgentRecord(ctx, task).catch(() => undefined);
+      await appendAgentEvent(ctx, id, { phase: task.status, error: (error as Error).message })
+        .catch(() => undefined);
+      return task.result;
+    } finally {
+      task.events.emit('change');
+      settle();
+    }
+  };
+
+  if (input.run_in_background) {
+    void run();
+    return {
+      ok: true,
+      content: `后台 Agent 已启动。agent_id=${id}\n使用 TaskOutput 获取进度/结果，TaskStop 停止。`,
+      metadata: {
+        kind: 'agent', agentId: id, status: 'running',
+        agentType: input.agent_type ?? 'explore', description: input.description,
+        isolation: input.isolation ?? 'none', turns: 0, toolCalls: 0,
+        failedToolCalls: 0, durationMs: 0, changedFiles: [],
+      },
+    };
+  }
+  const result = await run();
+  if (result.ok && result.metadata?.kind === 'agent') {
+    result.metadata.agentId = id;
+    result.metadata.status = 'completed';
+    result.content = `agent_id=${id}\n${result.content}`;
+  } else if (!result.ok) {
+    result.error = `agent_id=${id}\n${result.error}`;
+  }
+  return result;
+}
+
 // ---------------- 5. 导出 ----------------
 
 export const agentTool: Tool<AgentInput> = {
@@ -698,5 +833,5 @@ export const agentTool: Tool<AgentInput> = {
   maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
   interruptBehavior: () => 'block',
   call,
-  callWithContext: runAgentTask,
+  callWithContext: runManagedAgentTask,
 };

package/src/tools/agent/agentTaskService.js

@@ -0,0 +1,60 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readRuntimeJson, sessionRuntimeDir, withRuntimeFileLock, writeRuntimeJson, } from '../../session/runtimeStore.js';
+export function createAgentTaskState() {
+    return { tasks: new Map() };
+}
+function dir(ctx, id) {
+    return join(sessionRuntimeDir(ctx), 'agents', id);
+}
+export async function appendAgentEvent(ctx, id, event) {
+    const path = join(dir(ctx, id), 'events.jsonl');
+    await mkdir(dir(ctx, id), { recursive: true, mode: 0o700 });
+    await withRuntimeFileLock(path, () => appendFile(path, `${JSON.stringify({ at: Date.now(), ...event })}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    }));
+}
+export async function saveAgentRecord(ctx, record) {
+    const persisted = {
+        id: record.id,
+        status: record.status,
+        description: record.description,
+        input: record.input,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        ...(record.progress ? { progress: record.progress } : {}),
+        ...(record.worktree ? { worktree: record.worktree } : {}),
+        ...(record.result ? { result: record.result } : {}),
+    };
+    const recordDir = dir(ctx, record.id);
+    await withRuntimeFileLock(join(recordDir, '.record'), async () => {
+        await writeRuntimeJson(join(recordDir, 'state.json'), persisted);
+        if (record.history) {
+            await writeRuntimeJson(join(recordDir, 'history.json'), record.history);
+        }
+    });
+}
+export async function loadAgentRecord(ctx, id) {
+    const state = await readRuntimeJson(join(dir(ctx, id), 'state.json'), undefined);
+    if (!state)
+        return undefined;
+    const history = await readRuntimeJson(join(dir(ctx, id), 'history.json'), undefined);
+    return {
+        ...state,
+        status: state.status === 'running' ? 'interrupted' : state.status,
+        history,
+    };
+}
+export function getLiveAgentTask(state, id) {
+    return state?.tasks.get(id);
+}
+export async function stopAllAgentTasks(state) {
+    const running = [...state.tasks.values()].filter((t) => t.status === 'running');
+    running.forEach((t) => t.abort.abort());
+    await Promise.race([
+        Promise.allSettled(running.map((t) => t.completion)).then(() => undefined),
+        new Promise((r) => setTimeout(r, 5000)),
+    ]);
+    state.tasks.clear();
+}

package/src/tools/agent/agentTaskService.ts

@@ -0,0 +1,113 @@
+import { EventEmitter } from 'node:events';
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Message, ToolCallContext, ToolResult } from '../../types.js';
+import type { AgentWorktree } from './worktree.js';
+import {
+  readRuntimeJson,
+  sessionRuntimeDir,
+  withRuntimeFileLock,
+  writeRuntimeJson,
+} from '../../session/runtimeStore.js';
+
+export type AgentTaskStatus =
+  'running' | 'completed' | 'failed' | 'stopped' | 'interrupted';
+export interface AgentTaskRecord {
+  id: string;
+  status: AgentTaskStatus;
+  description: string;
+  input: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+  progress?: string;
+  worktree?: AgentWorktree;
+  result?: ToolResult;
+  history?: Message[];
+}
+export interface LiveAgentTask extends AgentTaskRecord {
+  abort: AbortController;
+  completion: Promise<void>;
+  events: EventEmitter;
+}
+export interface AgentTaskState {
+  tasks: Map<string, LiveAgentTask>;
+}
+export function createAgentTaskState(): AgentTaskState {
+  return { tasks: new Map() };
+}
+function dir(ctx: ToolCallContext, id: string) {
+  return join(sessionRuntimeDir(ctx), 'agents', id);
+}
+export async function appendAgentEvent(
+  ctx: ToolCallContext,
+  id: string,
+  event: Record<string, unknown>,
+): Promise<void> {
+  const path = join(dir(ctx, id), 'events.jsonl');
+  await mkdir(dir(ctx, id), { recursive: true, mode: 0o700 });
+  await withRuntimeFileLock(path, () =>
+    appendFile(path, `${JSON.stringify({ at: Date.now(), ...event })}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    }),
+  );
+}
+export async function saveAgentRecord(
+  ctx: ToolCallContext,
+  record: AgentTaskRecord,
+): Promise<void> {
+  const persisted: AgentTaskRecord = {
+    id: record.id,
+    status: record.status,
+    description: record.description,
+    input: record.input,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    ...(record.progress ? { progress: record.progress } : {}),
+    ...(record.worktree ? { worktree: record.worktree } : {}),
+    ...(record.result ? { result: record.result } : {}),
+  };
+  const recordDir = dir(ctx, record.id);
+  await withRuntimeFileLock(join(recordDir, '.record'), async () => {
+    await writeRuntimeJson(join(recordDir, 'state.json'), persisted);
+    if (record.history) {
+      await writeRuntimeJson(join(recordDir, 'history.json'), record.history);
+    }
+  });
+}
+export async function loadAgentRecord(
+  ctx: ToolCallContext,
+  id: string,
+): Promise<AgentTaskRecord | undefined> {
+  const state = await readRuntimeJson<AgentTaskRecord | undefined>(
+    join(dir(ctx, id), 'state.json'),
+    undefined,
+  );
+  if (!state) return undefined;
+  const history = await readRuntimeJson<Message[] | undefined>(
+    join(dir(ctx, id), 'history.json'),
+    undefined,
+  );
+  return {
+    ...state,
+    status: state.status === 'running' ? 'interrupted' : state.status,
+    history,
+  };
+}
+export function getLiveAgentTask(
+  state: AgentTaskState | undefined,
+  id: string,
+): LiveAgentTask | undefined {
+  return state?.tasks.get(id);
+}
+export async function stopAllAgentTasks(state: AgentTaskState): Promise<void> {
+  const running = [...state.tasks.values()].filter(
+    (t) => t.status === 'running',
+  );
+  running.forEach((t) => t.abort.abort());
+  await Promise.race([
+    Promise.allSettled(running.map((t) => t.completion)).then(() => undefined),
+    new Promise<void>((r) => setTimeout(r, 5000)),
+  ]);
+  state.tasks.clear();
+}

package/src/tools/agent/agentTypes.js

@@ -35,6 +35,9 @@ export const EXPLORE_ALLOWED_TOOLS = [
     'Read',
     'Glob',
     'Grep',
+    'Snip',
+    'LSP',
+    'Skill',
     'WebSearch',
     'WebFetch',
     'WebBrowser',
@@ -42,6 +45,8 @@ export const EXPLORE_ALLOWED_TOOLS = [
     'ListMemories',
     'ReviewMemories',
     'SearchConversations',
+    'TaskGet',
+    'TaskList',
 ];
 /** 借鉴官方 EXPLORE_AGENT「READ-ONLY MODE」文案中文化。 */
 const EXPLORE_APPENDIX = `# 本次子任务类型：只读调研（explore）

package/src/tools/agent/agentTypes.ts

@@ -53,6 +53,9 @@ export const EXPLORE_ALLOWED_TOOLS: readonly string[] = [
   'Read',
   'Glob',
   'Grep',
+  'Snip',
+  'LSP',
+  'Skill',
   'WebSearch',
   'WebFetch',
   'WebBrowser',
@@ -60,6 +63,8 @@ export const EXPLORE_ALLOWED_TOOLS: readonly string[] = [
   'ListMemories',
   'ReviewMemories',
   'SearchConversations',
+  'TaskGet',
+  'TaskList',
 ];
 
 /** 借鉴官方 EXPLORE_AGENT「READ-ONLY MODE」文案中文化。 */

package/src/tools/bash/bash.js

@@ -56,6 +56,8 @@ 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, } from '../shared/permanentDeleteGuard.js';
+import { ToolOutputStore } from '../shared/toolOutputStore.js';
 // ---------------- 0. 常量 ----------------
 const DEFAULT_TIMEOUT_MS = 120_000; // 2 min
 const MAX_TIMEOUT_MS = 600_000; // 10 min
@@ -103,6 +105,16 @@ function detectWindowsBash() {
     return null;
 }
 const WIN_BASH = detectWindowsBash();
+/**
+ * 本工具这一刻**真正**把命令交给谁执行。
+ *
+ * 单一出处：description（告诉模型该写哪种语法）与 permanentDeleteGuard（按哪套动词
+ * 匹配删除命令）必须看同一个判断，否则就会出现「description 说这是 cmd、守卫却按
+ * bash 匹配」这种两头对不上的裂缝 —— del / rd 会因此直接穿过全部三层防护。
+ */
+function effectiveShellKind() {
+    return process.platform === 'win32' && !WIN_BASH ? 'cmd' : 'bash';
+}
 /**
  * G1：stdout / stderr 即时缓冲上限（各自）。命令狂输出（如 cat 大文件 / yes）时，
  * 在最终统一截断之前先把内存封顶，防 OOM。取最终展示截断阈值的 2 倍 —— 正常输出不受影响，
@@ -309,8 +321,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\`
@@ -318,9 +333,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.
+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\`
 
-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.${process.platform !== 'win32'
+Regular Git operations (commit, add, status, log, diff, pull, fetch, checkout <branch>, merge, rebase, etc.) run without extra restrictions.${process.platform !== 'win32'
     ? ''
     : WIN_BASH
         ? `
@@ -347,6 +390,13 @@ async function call(input, signal, context) {
             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. 不可逆动作闸门：毁掉「最后一份副本」的命令要**停下来问人**。
     //
     // 与上面黑名单的分工：黑名单是「灾难且无正当用途」→ 直接拒；这里是
@@ -389,18 +439,19 @@ async function call(input, signal, context) {
         try {
             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' }
+                ? { command, executable: WIN_BASH, args: ['-c', command], cwd, env: sanitizedChildEnv(), sessionId: context?.sessionId, workspaceId: context?.workspaceId, shellKind: 'bash' }
                 : {
                     command: process.platform === 'win32' ? `chcp 65001 >nul & ${command}` : command,
                     cwd,
                     env: sanitizedChildEnv(),
                     shell: true,
                     sessionId: context?.sessionId,
+                    workspaceId: context?.workspaceId,
                     shellKind: 'bash',
                 }, 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 }),
             };
         }
@@ -414,6 +465,10 @@ async function call(input, signal, context) {
     //     Windows 无 bash:    cmd.exe，命令前缀 chcp 65001 强制 UTF-8 输出
     let stdout = '';
     let stderr = '';
+    const outputStore = new ToolOutputStore({
+        workspaceId: context?.workspaceId,
+        sessionId: context?.sessionId,
+    });
     let exitCode = null;
     let timedOut = false;
     let killedBySignal = false;
@@ -456,14 +511,16 @@ async function call(input, signal, context) {
             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);
@@ -489,6 +546,9 @@ async function call(input, signal, context) {
         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 剥掉**（那是给宿主看的，不是给模型读的噪声）；被拒的条目
     //       如实写进输出（静默丢弃会让脚本作者以为图发出去了，无从 debug）。
@@ -518,13 +578,18 @@ async function call(input, signal, context) {
         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. 中断 / 超时仍然算硬失败
     //     失败也带上已解析的附图：脚本挂掉前截的那张诊断图正是最该看的。
     if (timedOut || killedBySignal) {