thincoder 0.7.0 → 0.7.1

package/src/tools.mjs

@@ -1,14 +1,14 @@
 /**
  * tools.mjs — 内置工具集
- * read / write / edit / bash / glob / grep / websearch / ls / fetch / delete / git_diff / git_status / git_log / question，零依赖实现。
+ * read / write / edit / insert_after / apply_patch / bash / glob / grep / websearch / ls / fetch / delete / git_diff / git_status / git_log / question / checkpoint，零依赖实现。
  * 工具描述从 src/tools/*.md 加载（方便人读和修改）。
  * readonly 标记供 agent 调度：只读工具可并行，有副作用工具串行。
  */
 
 import { spawn, execFileSync } from "node:child_process"
 import { mkdir, readFile, readdir, stat, writeFile, unlink } from "node:fs/promises"
-import { readFileSync, existsSync } from "node:fs"
-import { dirname, join, resolve, relative } from "node:path"
+import { readFileSync, existsSync, realpathSync } from "node:fs"
+import { dirname, join, resolve, relative, isAbsolute, sep } from "node:path"
 import { fileURLToPath } from "node:url"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -19,6 +19,7 @@ const MAX_READ_LINES = 2000
 // 这里截断必须远高于落盘阈值，否则被截掉的内容在落盘前就永远丢了
 const MAX_OUTPUT_CHARS = 200_000
 const BASH_TIMEOUT_MS = 120_000
+const MAX_RESPONSE_BODY_BYTES = 5_000_000
 const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".turbo", "coverage"])
 
 /** 每个工具：{ name, description, parameters, readonly, execute(args, ctx) }（定义见文件末尾导出） */
@@ -48,6 +49,31 @@ function truncate(text, max = MAX_OUTPUT_CHARS) {
   return text.slice(0, max) + `\n[... truncated: ${text.length - max} chars omitted — redirect to a file if you need the full output]`
 }
 
+/** 限量读取响应体：超 limit 字节即取消流，防超大页面把整个 body 缓冲进内存 */
+async function readBodyText(response, limit = MAX_RESPONSE_BODY_BYTES) {
+  if (!response.body) return ""
+  const reader = response.body.getReader()
+  const chunks = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (value) {
+        chunks.push(value)
+        total += value.length
+      }
+      if (total >= limit) {
+        await reader.cancel()
+        break
+      }
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  return new TextDecoder("utf-8").decode(Buffer.concat(chunks))
+}
+
 /** 创建独立的流解码器（编码嗅探：ASCII → UTF-8 → GBK 回退） */
 function makeDecoder() {
   let decoder = null
@@ -91,12 +117,83 @@ function gitDiffOne(cwd, abs) {
   }
 }
 
+/** 目标可能不存在（write 新文件），逐级向上找真实存在的祖先做 realpath */
+function realpathNearest(abs) {
+  let cur = abs
+  const tail = []
+  while (!existsSync(cur)) {
+    const parent = dirname(cur)
+    if (parent === cur) return abs // 到根了，原样返回（不会发生）
+    tail.unshift(cur.slice(parent.length + 1))
+    cur = parent
+  }
+  try {
+    const real = realpathSync(cur)
+    return tail.length ? join(real, ...tail) : real
+  } catch {
+    return abs
+  }
+}
+
+// cwd 的 realpath 缓存：进程内 cwd 不变，只需解析一次
+const realCwdCache = new Map()
+function realCwd(cwd) {
+  if (!realCwdCache.has(cwd)) realCwdCache.set(cwd, realpathNearest(resolve(cwd)))
+  return realCwdCache.get(cwd)
+}
+
+function assertInside(cwd, resolved, p) {
+  const rel = relative(cwd, resolved)
+  // 跨盘符时 relative 返回绝对路径（Windows）；startsWith("..") 会误伤 cwd 内的 "..foo"，故精确判断
+  if (isAbsolute(rel) || rel === ".." || rel.startsWith(".." + sep)) {
+    throw new Error(`Access denied outside working directory: ${p}`)
+  }
+}
+
 function resolveInCwd(ctx, p) {
-  const resolved = resolve(ctx.cwd, p)
-  if (relative(ctx.cwd, resolved).startsWith("..")) throw new Error(`Access denied outside working directory: ${p}`)
+  const cwd = realCwd(ctx.cwd)
+  const resolved = resolve(cwd, p)
+  assertInside(cwd, resolved, p)
+  // 防 symlink 逃逸：cwd 内若存在指向外部的符号链接，realpath 后会落到 cwd 外
+  const real = realpathNearest(resolved)
+  assertInside(cwd, real, p)
   return resolved
 }
 
+/**
+ * 破坏性预检用的粗切分：&& || ; | 换行 命令替换 子 shell 都视作命令边界。
+ * 宁多切不少切——防 "cd x && git checkout ."、"echo $(git checkout .)" 这类写法绕过行首锚定
+ */
+function shellSegments(command) {
+  return command.split(/&&|\|\||[;|\n]|\$\(|`|[(]/)
+}
+
+/**
+ * 单个命令段是否会销毁未提交改动：
+ * checkout -- / checkout . / reset --hard / clean -f* / restore（动工作区的）
+ * checkout <branch>、restore --staged、clean -n（dry-run）不算
+ */
+function isDestructiveGitSegment(seg) {
+  if (!/^\s*git\s/.test(seg)) return false
+  if (/\scheckout\s+(?:--|\.(?:\s|$))/.test(seg)) return true
+  if (/\sreset\s+--hard\b/.test(seg)) return true
+  if (/\sclean\s+-\S*f/.test(seg)) return true
+  if (/\srestore\s/.test(seg) && (/--worktree/.test(seg) || !/--staged/.test(seg))) return true
+  return false
+}
+
+/** cwd 是否在 git 仓库内（预检用，失败静默视为不在） */
+function insideGitRepo(cwd) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
 // ---------------------------------------------------------------- read
 
 const readTool = {
@@ -114,6 +211,7 @@ const readTool = {
   readonly: true,
   async execute(args, ctx) {
     const abs = resolveInCwd(ctx, args.path)
+    // 注意：整文件一次性读入内存，大文件会被完整缓冲（offset/limit 只影响返回切片）
     const content = await readFile(abs, "utf8")
     const lines = content.split("\n")
     const offset = Math.max(1, args.offset ?? 1)
@@ -168,6 +266,9 @@ const editTool = {
   readonly: false,
   async execute(args, ctx) {
     const abs = resolveInCwd(ctx, args.path)
+    if (!args.old_string) {
+      throw new Error("old_string must not be empty (empty string matches everywhere and would corrupt the file)")
+    }
     const content = await readFile(abs, "utf8")
     const occurrences = content.split(args.old_string).length - 1
     if (occurrences === 0) {
@@ -184,7 +285,8 @@ const editTool = {
     }
     const updated = args.replace_all
       ? content.split(args.old_string).join(args.new_string)
-      : content.replace(args.old_string, args.new_string)
+      // 函数式替换：避免 new_string 里的 $ 替换模式（匹配串/前后文引用）被展开
+      : content.replace(args.old_string, () => args.new_string)
     await writeFile(abs, updated, "utf8")
     const diff = gitDiffOne(ctx.cwd, abs)
     return `Edited ${abs}: replaced ${args.replace_all ? occurrences : 1} occurrence(s)${diff ? "\n" + diff : ""}`
@@ -215,7 +317,10 @@ const insertAfterTool = {
     let targetLine
     if (args.after_line != null) {
       targetLine = args.after_line
-      if (targetLine < 0 || targetLine > lines.length) {
+      if (!Number.isInteger(targetLine)) {
+        throw new Error(`after_line must be an integer, got: ${args.after_line}`)
+      }
+      if (targetLine < 1 || targetLine > lines.length) {
         throw new Error(`after_line ${targetLine} out of range (file has ${lines.length} lines)`)
       }
     } else if (args.after_regex) {
@@ -239,6 +344,134 @@ const insertAfterTool = {
   },
 }
 
+// ---------------------------------------------------------------- apply_patch
+
+/**
+ * 解析统一 diff（unified diff）：返回 [{ path, isNew, hunks: [{ ops: [{type:" "|"-"|"+", text}] }] }]
+ * 按 @@ 头的行数计数消费 hunk 行——LLM 常把上下文空行剥成纯空行，靠计数而不是行首字符判断 hunk 边界
+ */
+function parsePatch(patch) {
+  // 补丁文本常来自 CRLF 终端/模型输出，行尾 \r 会混进 hunk 内容导致上下文对不上，统一剥掉
+  const lines = patch.replace(/\r(?=\n|$)/g, "").split("\n")
+  const files = []
+  let cur = null
+  let i = 0
+  const stripPrefix = (p) => p.replace(/^[ab]\//, "")
+  while (i < lines.length) {
+    const line = lines[i]
+    if (line.startsWith("--- ")) {
+      const oldPath = line.slice(4).trim()
+      const plus = lines[i + 1]
+      if (!plus?.startsWith("+++ ")) throw new Error(`Malformed patch: expected "+++" line after "${line}"`)
+      const newPath = plus.slice(4).trim()
+      if (newPath === "/dev/null") throw new Error("Deleting files via patch is not supported — use the delete tool")
+      cur = { path: stripPrefix(newPath), isNew: oldPath === "/dev/null", hunks: [] }
+      files.push(cur)
+      i += 2
+      continue
+    }
+    if (line.startsWith("@@")) {
+      if (!cur) throw new Error("Malformed patch: hunk header before any file header")
+      const m = line.match(/^@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@/)
+      if (!m) throw new Error(`Malformed patch: bad hunk header "${line}" (need @@ -old,count +new,count @@)`)
+      let oldNeed = m[1] == null ? 1 : Number(m[1])
+      let newNeed = m[2] == null ? 1 : Number(m[2])
+      const hunk = { ops: [] }
+      i++
+      while (oldNeed > 0 || newNeed > 0) {
+        if (i >= lines.length) throw new Error("Malformed patch: hunk truncated (line counts in @@ header not satisfied)")
+        const hl = lines[i]
+        if (hl.startsWith("\\")) { i++; continue } // ""
+        const tag = hl === "" ? " " : hl[0] // 纯空行按上下文行宽容处理
+        const text = hl === "" ? "" : hl.slice(1)
+        if (tag === " ") { hunk.ops.push({ type: " ", text }); oldNeed--; newNeed-- }
+        else if (tag === "-") { hunk.ops.push({ type: "-", text }); oldNeed-- }
+        else if (tag === "+") { hunk.ops.push({ type: "+", text }); newNeed-- }
+        else throw new Error(`Malformed patch: unexpected line "${hl.slice(0, 60)}" inside hunk`)
+        i++
+      }
+      cur.hunks.push(hunk)
+      continue
+    }
+    i++ // diff --git / index / 空行等元信息跳过
+  }
+  if (files.length === 0) throw new Error("No file changes found in patch (need --- / +++ headers)")
+  return files
+}
+
+/** 在内存行数组上按序应用 hunks；任何一步失败抛错（调用方保证不落盘）。比较时忽略行尾 \r，上下文行保留原始字节 */
+function applyHunks(fileLines, hunks, eol, path) {
+  const cr = eol === "\r\n" ? "\r" : ""
+  for (let h = 0; h < hunks.length; h++) {
+    const oldSeq = hunks[h].ops.filter((o) => o.type !== "+").map((o) => o.text)
+    if (oldSeq.length === 0) throw new Error(`Hunk ${h + 1} in ${path} has no context/removed lines to locate`)
+    const matches = []
+    for (let pos = 0; pos + oldSeq.length <= fileLines.length; pos++) {
+      let ok = true
+      for (let j = 0; j < oldSeq.length; j++) {
+        if (fileLines[pos + j].replace(/\r$/, "") !== oldSeq[j]) { ok = false; break }
+      }
+      if (ok) matches.push(pos)
+    }
+    if (matches.length === 0) {
+      const preview = oldSeq.slice(0, 3).join(" ⏎ ")
+      throw new Error(`Hunk ${h + 1} in ${path} does not apply — context not found: "${preview}${oldSeq.length > 3 ? "…" : ""}". Read the file first and regenerate the patch from actual content.`)
+    }
+    if (matches.length > 1) throw new Error(`Hunk ${h + 1} in ${path} matches ${matches.length} locations — add more context lines to make it unique`)
+    const pos = matches[0]
+    const out = []
+    let src = pos
+    for (const op of hunks[h].ops) {
+      if (op.type === " ") out.push(fileLines[src++]) // 上下文保留原始行（行尾/空白原样）
+      else if (op.type === "-") src++
+      else out.push(op.text + cr)
+    }
+    fileLines.splice(pos, oldSeq.length, ...out)
+  }
+}
+
+const applyPatchTool = {
+  name: "apply_patch",
+  description: DESC("apply_patch"),
+  parameters: {
+    type: "object",
+    properties: {
+      patch: { type: "string", description: "Unified diff. May span multiple files; --- / +++ headers per file, @@ -old,count +new,count @@ hunks. Use --- /dev/null to create a file." },
+    },
+    required: ["patch"],
+  },
+  readonly: false,
+  /** 供 agent 层追踪触碰文件（多路径，替代单 path 参数） */
+  touchedPaths(args) {
+    try { return parsePatch(args.patch ?? "").map((f) => f.path) } catch { return [] }
+  },
+  async execute(args, ctx) {
+    const files = parsePatch(args.patch ?? "")
+    // 先全部读入内存试算：任何一个 hunk 不上就整体抛错，不写半个补丁（原子性）
+    const planned = []
+    for (const f of files) {
+      const abs = resolveInCwd(ctx, f.path)
+      if (f.isNew) {
+        if (existsSync(abs)) throw new Error(`Cannot create ${f.path}: file already exists`)
+        const content = f.hunks.flatMap((h) => h.ops.filter((o) => o.type === "+").map((o) => o.text)).join("\n") + "\n"
+        planned.push({ abs, path: f.path, content, isNew: true })
+      } else {
+        const original = await readFile(abs, "utf8").catch(() => { throw new Error(`File not found: ${f.path}`) })
+        const eol = original.includes("\r\n") ? "\r\n" : "\n"
+        const lines = original.split("\n")
+        applyHunks(lines, f.hunks, eol, f.path)
+        planned.push({ abs, path: f.path, content: lines.join("\n"), isNew: false })
+      }
+    }
+    for (const p of planned) {
+      await mkdir(dirname(p.abs), { recursive: true })
+      await writeFile(p.abs, p.content, "utf8")
+    }
+    const summary = planned.map((p) => `  ${p.isNew ? "created " : "modified"} ${p.path}`).join("\n")
+    return `Applied patch to ${planned.length} file(s):\n${summary}`
+  },
+}
+
 // ---------------------------------------------------------------- syntax_check
 
 const syntaxCheckTool = {
@@ -285,25 +518,38 @@ const bashTool = {
   },
   readonly: false,
   async execute(args, ctx) {
-    // 安全预检：销毁性 git 操作（checkout -- / reset --hard）先检查未提交改动，
-    // 有则拒绝——防一键清掉几小时工作（像今天 git checkout -- 六个文件那次）
-    const DESTRUCTIVE_GIT = /^git\s+(?:checkout\s+--?\s+|reset\s+--hard\b)/
-    if (DESTRUCTIVE_GIT.test(args.command)) {
+    // 安全预检：销毁性 git 操作先检查未提交改动，有则拒绝——防一键清掉几小时工作
+    if (shellSegments(args.command).some(isDestructiveGitSegment)) {
+      if (!insideGitRepo(ctx.cwd)) {
+        throw new Error(`Refusing destructive git command: not a git repository: ${ctx.cwd}`)
+      }
       const status = execFileSync("git", ["status", "--porcelain"], {
         cwd: ctx.cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
       }).trim()
       if (status) {
         throw new Error(
-          `Refusing destructive git command: uncommitted changes exist. Commit or stash first.\n\n${status}`
+          `Refusing destructive git command: uncommitted changes exist. Commit or stash first.\n` +
+          `(If uncommitted work was already lost, the checkpoint tool can restore the auto-snapshot: action=list, then action=rewind.)\n\n${status}`
         )
       }
     }
 
     return new Promise((resolve) => {
+      // detached: 让子进程成为进程组组长，超时/中断时才能整树杀掉（POSIX 用负 pid 组杀，
+      // Windows 用 taskkill /T）——只 kill 壳进程会把孙进程（如 npm test）留在后台继续跑
+      const killTree = () => {
+        if (process.platform === "win32") {
+          try { execFileSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" }) } catch {}
+        } else {
+          try { process.kill(-child.pid, "SIGKILL") } catch {}
+          try { child.kill("SIGKILL") } catch {} // 组杀失败时兜底杀本体
+        }
+      }
       const child = spawn(args.command, {
         cwd: ctx.cwd,
         shell: true,
         windowsHide: true,
+        detached: process.platform !== "win32",
         stdio: ["ignore", "pipe", "pipe"],
         env: {
           ...process.env,
@@ -332,15 +578,16 @@ const bashTool = {
         }
       }
       const onStderr = (d) => {
-        errBuf += sanitizeOutput(errDecoder(d))
+        const s = sanitizeOutput(errDecoder(d)) // 始终解码，防 pending 无限累积
+        if (errBuf.length < 2_000_000) errBuf += s
       }
 
       child.stdout.on("data", onStdout)
       child.stderr.on("data", onStderr)
 
-      const timer = setTimeout(() => child.kill(), args.timeout ?? BASH_TIMEOUT_MS)
+      const timer = setTimeout(killTree, args.timeout ?? BASH_TIMEOUT_MS)
       if (ctx.signal) {
-        ctx.signal.addEventListener("abort", () => child.kill(), { once: true })
+        ctx.signal.addEventListener("abort", killTree, { once: true })
       }
       child.on("error", (error) => {
         clearTimeout(timer)
@@ -416,7 +663,7 @@ function globToRegex(pattern) {
   const DS = "\u0001" // **/ 的占位符（零或多级目录）
   const DP = "\u0002" // ** 的占位符
   const escaped = pattern
-    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/[.+^${}()|\\]/g, "\\$&") // [ ] 不转义，保留为 glob 字符组语法
     .replace(/\*\*\//g, DS)
     .replace(/\*\*/g, DP)
     .replace(/\*/g, "[^/]*")
@@ -458,7 +705,7 @@ const grepTool = {
       try {
         content = await readFile(file, "utf8")
       } catch {
-        return // 二进制/不可读文件跳过
+        return // 不可读文件跳过；二进制会被按 utf8 读入并照常搜索（可能产生乱码匹配）
       }
       const lines = content.split("\n")
       if (wantCtx) fileLines.set(file, lines)
@@ -545,7 +792,7 @@ const websearchTool = {
           : AbortSignal.timeout(15_000),
       })
       if (!response.ok) throw new Error(`HTTP ${response.status}`)
-      html = await response.text()
+      html = await readBodyText(response)
     } catch (error) {
       throw new Error(`websearch request failed: ${error.cause?.code ?? error.message}`)
     }
@@ -577,10 +824,10 @@ function stripTags(html) {
     .replace(/&#0*(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
     .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
     .replace(/&ensp;/g, " ")
-    .replace(/&amp;/g, "&")
     .replace(/&lt;/g, "<")
     .replace(/&gt;/g, ">")
     .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, "&") // &amp; 必须最后解码，否则 &amp;lt; 会被二次解码成 <
     .replace(/\s+/g, " ")
     .trim()
 }
@@ -649,7 +896,7 @@ const fetchTool = {
     if (!response.ok) throw new Error(`fetch failed: HTTP ${response.status}`)
 
     const contentType = response.headers.get("content-type") ?? ""
-    const body = await response.text()
+    const body = await readBodyText(response)
     if (!contentType.includes("text/html")) return truncate(body)
     return truncate(htmlToText(body))
   },
@@ -668,16 +915,16 @@ function htmlToText(html) {
     .replace(/&#0*(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
     .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
     .replace(/&nbsp;|&ensp;/g, " ")
-    .replace(/&amp;/g, "&")
     .replace(/&lt;/g, "<")
     .replace(/&gt;/g, ">")
     .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, "&") // &amp; 必须最后解码，否则 &amp;lt; 会被二次解码成 <
     .replace(/[ \t]+/g, " ")
     .replace(/\n\s*\n\s*\n+/g, "\n\n")
     .trim()
 }
 
-export const builtinTools = [readTool, writeTool, editTool, insertAfterTool, syntaxCheckTool, bashTool, globTool, grepTool, websearchTool, lsTool, fetchTool]
+export const builtinTools = [readTool, writeTool, editTool, insertAfterTool, applyPatchTool, syntaxCheckTool, bashTool, globTool, grepTool, websearchTool, lsTool, fetchTool]
 
 // ---------------------------------------------------------------- delete
 
@@ -730,6 +977,8 @@ const gitDiffTool = {
   readonly: true,
   execute(args, ctx) {
     const ref = args.ref ?? "HEAD"
+    // ref 由模型提供且位于 "--" 之前：校验字符集，防 "--output=..." 之类被 git 当成选项
+    if (!/^[A-Za-z0-9._\/~^][A-Za-z0-9._\/~^-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
     const flags = args.staged ? ["--staged"] : []
     const paths = args.path ? [args.path] : []
     const out = runGit(ctx.cwd, ["diff", ...flags, ref, "--", ...paths])
@@ -763,7 +1012,9 @@ const gitStatusTool = {
       // 尝试匹配 "XY path" 或 "XY  path"（可变间距）
       const m = clean.match(/^(..?)\s+(.+)$/)
       if (!m) continue
-      const [, status, file] = m
+      const [, status, rawFile] = m
+      // 重命名条目 porcelain 输出为 "R  old -> new"，拆开明确展示而非当成一个字面文件名
+      const file = status.includes("R") && rawFile.includes(" -> ") ? rawFile.replace(" -> ", " → ") : rawFile
       const idx = status[0] ?? " "
       const wt = status[1] ?? " "
       if (idx === "U" || wt === "U" || (idx === "A" && wt === "A")) {
@@ -843,5 +1094,40 @@ function runGit(cwd, cmdArgs) {
   }
 }
 
-export { deleteTool, gitDiffTool, gitStatusTool, gitLogTool, questionTool }
-builtinTools.push(deleteTool, gitDiffTool, gitStatusTool, gitLogTool, questionTool)
+// ---------------------------------------------------------------- checkpoint
+
+const checkpointTool = {
+  name: "checkpoint",
+  description: DESC("checkpoint"),
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["list", "create", "rewind"], description: "list snapshots / create one now / restore a snapshot by id" },
+      id: { type: "string", description: "Snapshot id (required for rewind)" },
+    },
+    required: ["action"],
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    const { createCheckpoint, listCheckpoints, rewind, isGitRepo } = await import("./checkpoint.mjs")
+    if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
+    if (args.action === "create") {
+      const cp = await createCheckpoint(ctx.cwd)
+      return `Checkpoint ${cp.id} created (${cp.files} file(s) captured)`
+    }
+    if (args.action === "rewind") {
+      if (!args.id) throw new Error("id is required for rewind — use action=list to see snapshot ids")
+      const s = await rewind(ctx.cwd, args.id)
+      return `Rewound to checkpoint ${args.id}: patch ${s.patchApplied ? "applied" : "(empty)"}, ${s.restored} untracked file(s) restored, ${s.deleted} file(s) deleted.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
+    }
+    if (args.action === "list") {
+      const cps = await listCheckpoints(ctx.cwd)
+      if (cps.length === 0) return "(no checkpoints yet — one is auto-created before each user task)"
+      return cps.map((c) => `${c.id}  ${new Date(c.time).toISOString()}  ${c.untracked} untracked file(s)`).join("\n")
+    }
+    throw new Error(`Unknown action: ${args.action}`)
+  },
+}
+
+export { deleteTool, gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool }
+builtinTools.push(deleteTool, gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool)

package/src/tui.mjs

@@ -206,7 +206,6 @@ export function layoutInput(chars, cursor, width) {
   return { lines, cursorLine, cursorCol }
 }
 
-/** 文本按宽度折行（保留 \n），返回行数组 */
 /**
  * 显示净化：控制字符会破坏终端网格数学（\r 回车覆盖、\t 宽度误判致整帧错位、ANSI/响铃冲屏）。
  * 只动显示层——模型看到的工具结果原文不变；session 里已存的脏 display 回放时也经此净化。
@@ -222,6 +221,7 @@ export function sanitizeDisplay(s) {
     .replace(/\n+$/, "")
 }
 
+/** 文本按宽度折行（保留 \n），返回行数组 */
 export function wrapText(text, width) {
   const lines = []
   for (const rawLine of text.split("\n")) {
@@ -406,9 +406,17 @@ export async function startTUI(agent, opts = {}) {
     let boxLines = inputLines
     if (state.question) {
       const q = state.question
-      boxLines = q.options.length > 0
-        ? q.options.map((opt, i) => (i === (q.selected ?? 0) ? "▸ " : "  ") + opt)
-        : ["▸ " + (q.answer ?? "")]
+      if (q.options.length > 0) {
+        // 选项窗口：只显示选中项 ±2，选项过多时防输入框无限增高撑破锚定布局
+        const sel = q.selected ?? 0
+        const QWIN = 5
+        const start = Math.max(0, Math.min(sel - 2, q.options.length - QWIN))
+        boxLines = q.options
+          .slice(start, start + QWIN)
+          .map((opt, i) => (start + i === sel ? "▸ " : "  ") + opt)
+      } else {
+        boxLines = ["▸ " + (q.answer ?? "")]
+      }
     }
     const inputBoxH = boxLines.length + 2
 
@@ -434,8 +442,18 @@ export async function startTUI(agent, opts = {}) {
     const taskPanelH = visibleTasks.length
     // 子 agent 流式输出占位（显示时占最多 2 行）
     const subOutLen = (state.subOutput && state.processing) ? wrapText(state.subOutput, W - 8).slice(-2).length : 0
-    // 权限预览占位
-    const permPreviewLen = state.permission ? 1 + state.permissionPreview.reduce((s, l) => s + wrapText(`  ${l}`, W - 1).length, 0) : 0
+    // 权限预览占位：字符数之外再封顶显示行数（rows-8），多行短行也能把帧撑过终端高度，破坏锚定布局
+    let permPreviewLines = []
+    if (state.permission) {
+      const maxLines = Math.max(1, rows - 8)
+      outer: for (const l of state.permissionPreview) {
+        for (const wrapped of wrapText(`  ${l}`, W - 1)) {
+          if (permPreviewLines.length >= maxLines) break outer
+          permPreviewLines.push(wrapped)
+        }
+      }
+    }
+    const permPreviewLen = state.permission ? 1 + permPreviewLines.length : 0
     const convH = Math.max(1, rows - headerH - inputBoxH - statusH - pickerH - taskPanelH - subOutLen - permPreviewLen)
 
     // 对话区内容行（含流式缓冲）；markdown 表格先按显示宽度重排
@@ -519,13 +537,11 @@ export async function startTUI(agent, opts = {}) {
       }
     }
 
-    // 权限审批内容预览（黄色，紧挨输入框上方）
+    // 权限审批内容预览（黄色，紧挨输入框上方）；用上方已封顶的 permPreviewLines，渲染行数与占位一致
     if (state.permission) {
       out.push(`${ansi.bold}${C.warn}❯ 权限请求${ansi.reset}${ansi.clearLine}`)
-      for (const line of state.permissionPreview) {
-        for (const wrapped of wrapText(`  ${line}`, W - 1)) {
-          out.push(`${C.warn}${wrapped}${ansi.reset}${ansi.clearLine}`)
-        }
+      for (const wrapped of permPreviewLines) {
+        out.push(`${C.warn}${wrapped}${ansi.reset}${ansi.clearLine}`)
       }
     }
 
@@ -697,8 +713,8 @@ export async function startTUI(agent, opts = {}) {
 
     const callbacks = {
       onToken: (t) => {
-        // 子 agent 流式输出：前缀匹配 explore/coder/plan 的 token 进 subOutput
-        const subMatch = t.match(/^(explore|coder|plan)\//)
+        // 子 agent 流式输出：前缀匹配 explore/coder/plan/sub（无角色子 agent 用 sub/）的 token 进 subOutput
+        const subMatch = t.match(/^(explore|coder|plan|sub)\//)
         if (subMatch) {
           state.currentSub = subMatch[1]
           state.subOutput = (state.subOutput + t.slice(subMatch[0].length)).slice(-300)
@@ -710,6 +726,14 @@ export async function startTUI(agent, opts = {}) {
         scheduleRender()
       },
       onReasoning: (t) => {
+        // 子 agent 的思考 token 同样带 role/ 前缀，进 subOutput 滚动区，不污染主思考流
+        const subMatch = t.match(/^(explore|coder|plan|sub)\//)
+        if (subMatch) {
+          state.currentSub = subMatch[1]
+          state.subOutput = (state.subOutput + t.slice(subMatch[0].length)).slice(-300)
+          scheduleRender()
+          return
+        }
         ensureAssistantLabel()
         state.reasoning += t
         scheduleRender()
@@ -722,8 +746,9 @@ export async function startTUI(agent, opts = {}) {
       },
       onToolResult: (name, result) => {
         state.currentTool = null
-        // 子 agent 结束：清空流式缓冲，报告进对话区
-        const isSubagent = name.startsWith("explore/") || name.startsWith("coder/") || name.startsWith("plan/")
+        // 子 agent 结束（父 agent 侧的 subagent 工具结果带着最终报告）：清空流式缓冲，报告进对话区。
+        // 注意只能用精确匹配——子 agent 内部工具调用不 relay 到 TUI（刷了满屏的教训）
+        const isSubagent = name === "subagent"
         if (isSubagent) {
           state.subOutput = ""
           state.currentSub = null
@@ -877,6 +902,10 @@ export async function startTUI(agent, opts = {}) {
         ...cap(args.new_string ?? "", 500).split("\n").map((l) => `+ ${l}`),
       ]
     }
+    if (base === "apply_patch") {
+      // 补丁本身就是可读的 diff，直接预览
+      return cap(args.patch ?? "", 1500).split("\n")
+    }
     if (base === "delete") return [`${args.path}${args.force ? "（force：跟踪文件也删）" : ""}`]
     if (base === "subagent") return cap(args.task ?? "", 500).split("\n")
     if (base === "memory_put") return [`[${args.type ?? ""}] ${args.title ?? ""}`, ...cap(args.content ?? "", 500).split("\n")]