thincoder 0.6.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) }（定义见文件末尾导出） */
@@ -45,7 +46,59 @@ function sanitizeOutput(s) {
 
 function truncate(text, max = MAX_OUTPUT_CHARS) {
   if (text.length <= max) return text
-  return text.slice(0, max) + `\n... (truncated, ${text.length - max} chars omitted)`
+  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
+  let pending = Buffer.alloc(0)
+  return (d, flush = false) => {
+    pending = Buffer.concat([pending, d])
+    if (!decoder) {
+      const hasHighByte = pending.some((b) => b >= 0x80)
+      if (!hasHighByte) {
+        const s = pending.toString("ascii")
+        pending = Buffer.alloc(0)
+        return s
+      }
+      for (let trim = 0; trim <= 3 && !decoder; trim++) {
+        try {
+          new TextDecoder("utf-8", { fatal: true }).decode(pending.subarray(0, pending.length - trim))
+          decoder = new TextDecoder("utf-8")
+        } catch { /* 继续尝试 */ }
+      }
+      if (!decoder) decoder = new TextDecoder("gbk")
+    }
+    const s = decoder.decode(pending, { stream: !flush })
+    pending = Buffer.alloc(0)
+    return s
+  }
 }
 
 /** 对单个文件取 git diff，失败静默返回空 */
@@ -64,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 = {
@@ -87,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)
@@ -141,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) {
@@ -157,13 +285,224 @@ 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 : ""}`
   },
 }
 
+// ---------------------------------------------------------------- insert_after
+
+const insertAfterTool = {
+  name: "insert_after",
+  description: DESC("insert_after"),
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "File path" },
+      after_line: { type: "number", description: "Line number to insert after (1-based). Takes priority over after_regex." },
+      after_regex: { type: "string", description: "JavaScript regex to find the line to insert after (must match exactly one line)" },
+      content: { type: "string", description: "Text to insert (with leading newline if you need a blank line)" },
+    },
+    required: ["path", "content"],
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    const abs = resolveInCwd(ctx, args.path)
+    const text = await readFile(abs, "utf8")
+    const lines = text.split("\n")
+
+    let targetLine
+    if (args.after_line != null) {
+      targetLine = args.after_line
+      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) {
+      const regex = new RegExp(args.after_regex)
+      const matches = []
+      for (let i = 0; i < lines.length; i++) {
+        if (regex.test(lines[i])) matches.push(i + 1)
+      }
+      if (matches.length === 0) throw new Error(`after_regex /${args.after_regex}/ matched no lines in ${abs}`)
+      if (matches.length > 1) throw new Error(`after_regex /${args.after_regex}/ matched ${matches.length} lines (${matches.slice(0, 5).join(", ")}${matches.length > 5 ? "…" : ""}); use a more specific pattern or after_line instead`)
+      targetLine = matches[0]
+    } else {
+      throw new Error("Either after_line or after_regex is required")
+    }
+
+    lines.splice(targetLine, 0, args.content)
+    const updated = lines.join("\n")
+    await writeFile(abs, updated, "utf8")
+    const diff = gitDiffOne(ctx.cwd, abs)
+    return `Inserted after line ${targetLine} in ${abs}${diff ? "\n" + diff : ""}`
+  },
+}
+
+// ---------------------------------------------------------------- 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 = {
+  name: "syntax_check",
+  description: DESC("syntax_check"),
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "File path (.js/.mjs/.cjs only)" },
+    },
+    required: ["path"],
+  },
+  readonly: true,
+  execute(args, ctx) {
+    const abs = resolveInCwd(ctx, args.path)
+    if (!/\.(?:[mc]?js)$/.test(abs)) {
+      return `syntax_check only supports .js/.mjs/.cjs files; ${abs} skipped.`
+    }
+    try {
+      execFileSync(process.execPath, ["--check", abs], {
+        cwd: ctx.cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+      })
+      return `Syntax OK: ${abs}`
+    } catch (e) {
+      // node --check 把错误写到 stderr
+      const msg = (e.stderr || e.stdout || e.message || "").trim()
+      return `Syntax error in ${abs}:\n${msg || "(unknown)"}`
+    }
+  },
+}
+
 // ---------------------------------------------------------------- bash
 
 const bashTool = {
@@ -179,27 +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,
-        // 无 TTY 环境：stdin 置空（vim/less 这类交互程序立刻吃到 EOF 退出，而不是干等），
-        // 并通过环境变量缴械编辑器/分页器/花哨输出
+        detached: process.platform !== "win32",
         stdio: ["ignore", "pipe", "pipe"],
         env: {
           ...process.env,
@@ -211,71 +561,50 @@ const bashTool = {
           TERM: "dumb",
         },
       })
-      // 编码嗅探：cmd 自带消息是 GBK，git/node 等程序是 UTF-8，平台判断不了。
-      // 策略：纯 ASCII 段两种编码一致，直接透传不判定；遇到高位字节才用
-      // fatal UTF-8 试解（容忍尾部 1~3 字节截断），失败则判 GBK；一经判定不再变更。
-      // 已知边界：GBK 字节流极低概率恰好构成合法 UTF-8 序列，会误判为 UTF-8 产生乱码。
-      // 更严谨的做法是 chcp 探测控制台代码页，但当前策略覆盖 99.9% 场景，不值得那份复杂度。
-      let decoder = null
-      let pending = Buffer.alloc(0)
-      const feed = (d, flush = false) => {
-        pending = Buffer.concat([pending, d])
-        if (!decoder) {
-          const hasHighByte = pending.some((b) => b >= 0x80)
-          if (!hasHighByte) {
-            // 纯 ASCII：UTF-8/GBK 完全一致，透传即可（无需判定）
-            const s = pending.toString("ascii")
-            pending = Buffer.alloc(0)
-            return s
-          }
-          for (let trim = 0; trim <= 3 && !decoder; trim++) {
-            try {
-              new TextDecoder("utf-8", { fatal: true }).decode(pending.subarray(0, pending.length - trim))
-              decoder = new TextDecoder("utf-8")
-            } catch {
-              // 继续尝试
-            }
-          }
-          if (!decoder) decoder = new TextDecoder("gbk")
-        }
-        const s = decoder.decode(pending, { stream: !flush })
-        pending = Buffer.alloc(0)
-        return s
-      }
-
-      let out = ""
+      // stdout / stderr 各自独立解码（同进程通常同编码，但分开收集更干净，
+      // 且允许模型按 stderr 快速定位错误）
+      const outDecoder = makeDecoder()
+      const errDecoder = makeDecoder()
+      let outBuf = ""
+      let errBuf = ""
       let truncatedNote = ""
-      const onData = (d) => {
-        const s = sanitizeOutput(feed(d))
-        // 输出实时透传给 UI；本地缓冲超 2MB 后停止累积（防内存爆炸）
-        if (s) ctx.onOutput?.(s)
-        if (out.length < 2_000_000) {
-          out += s
-        } else if (!truncatedNote) {
-          truncatedNote = "\n... (output exceeded 2MB, remainder discarded)"
+
+      const onStdout = (d) => {
+        const s = sanitizeOutput(outDecoder(d))
+        if (s) {
+          ctx.onOutput?.(s)
+          if (outBuf.length < 2_000_000) outBuf += s
+          else if (!truncatedNote) truncatedNote = "\n[... output exceeded 2MB, remainder discarded]"
         }
       }
-      child.stdout.on("data", onData)
-      child.stderr.on("data", onData)
+      const onStderr = (d) => {
+        const s = sanitizeOutput(errDecoder(d)) // 始终解码，防 pending 无限累积
+        if (errBuf.length < 2_000_000) errBuf += s
+      }
 
-      const timer = setTimeout(() => child.kill(), args.timeout ?? BASH_TIMEOUT_MS)
-      // 用户中止：杀进程
+      child.stdout.on("data", onStdout)
+      child.stderr.on("data", onStderr)
+
+      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)
-        resolve(truncate(`Command failed: ${error.message}\n${out}`))
+        resolve(truncate(`Command failed: ${error.message}\n[stdout]:\n${outBuf || "(empty)"}`))
       })
       child.on("close", (code, signal) => {
         clearTimeout(timer)
-        out += sanitizeOutput(feed(Buffer.alloc(0), true)) // 最终判定 + 冲刷解码器尾部
-        const suffix = signal
-          ? `\n(killed: ${ctx.signal?.aborted ? "user interrupted" : "timeout"})`
-          : code !== 0
-            ? `\n(exit code ${code})`
-            : ""
-        resolve(truncate((out.trim() || "(no output)") + suffix + truncatedNote))
+        // 冲刷解码器尾部
+        outBuf += sanitizeOutput(outDecoder(Buffer.alloc(0), true))
+        errBuf += sanitizeOutput(errDecoder(Buffer.alloc(0), true))
+        const status = signal
+          ? `killed: ${ctx.signal?.aborted ? "user interrupted" : "timeout"}`
+          : `exit code ${code}`
+        const parts = [`[stdout]:\n${outBuf.trim() || "(empty)"}`]
+        if (errBuf.trim()) parts.push(`[stderr]:\n${errBuf.trim()}`)
+        parts.push(`(${status})`)
+        resolve(truncate(parts.join("\n\n") + truncatedNote))
       })
     })
   },
@@ -334,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, "[^/]*")
@@ -355,6 +684,8 @@ const grepTool = {
       pattern: { type: "string", description: "Regular expression" },
       path: { type: "string", description: "Directory or file to search (default cwd)" },
       glob: { type: "string", description: "Only search files matching this glob (e.g. '*.mjs')" },
+      before: { type: "integer", description: "Lines of context to show before each match (grep -B). Default 0" },
+      after: { type: "integer", description: "Lines of context to show after each match (grep -A). Default 0" },
     },
     required: ["pattern"],
   },
@@ -363,26 +694,31 @@ const grepTool = {
     const base = resolveInCwd(ctx, args.path ?? ".")
     const regex = new RegExp(args.pattern)
     const fileFilter = args.glob ? globToRegex(args.glob) : null
-    const matches = []
+    const before = Math.max(0, Math.floor(args.before ?? 0))
+    const after = Math.max(0, Math.floor(args.after ?? 0))
+    const wantCtx = before > 0 || after > 0
+    const hits = [] // { file, line(1-based), text }
+    const fileLines = new Map() // file -> string[]（仅 wantCtx 时缓存）
 
     async function search(file) {
       let content
       try {
         content = await readFile(file, "utf8")
       } catch {
-        return // 二进制/不可读文件跳过
+        return // 不可读文件跳过；二进制会被按 utf8 读入并照常搜索（可能产生乱码匹配）
       }
       const lines = content.split("\n")
+      if (wantCtx) fileLines.set(file, lines)
       for (let i = 0; i < lines.length; i++) {
         if (regex.test(lines[i])) {
-          matches.push(`${file}:${i + 1}: ${lines[i]}`)
-          if (matches.length >= 200) return
+          hits.push({ file, line: i + 1, text: lines[i] })
+          if (hits.length >= 200) return
         }
       }
     }
 
     async function walk(target) {
-      if (matches.length >= 200) return
+      if (hits.length >= 200) return
       const s = await stat(target)
       if (!s.isDirectory()) {
         if (!fileFilter || fileFilter.test(target.split(/[\\/]/).pop())) await search(target)
@@ -401,8 +737,32 @@ const grepTool = {
     }
 
     await walk(base)
-    if (matches.length === 0) return "(no matches)"
-    return truncate(matches.join("\n"))
+    if (hits.length === 0) return "(no matches)"
+
+    // 无上下文：保持原 path:line: content 格式
+    if (!wantCtx) {
+      return truncate(hits.map((h) => `${h.file}:${h.line}: ${h.text}`).join("\n"))
+    }
+
+    // 带上下文：匹配行用 ':'，上下文行用 '-'（同 ripgrep）；同文件相邻区间去重合并
+    const fileMatched = new Map() // file -> Set<line>
+    for (const h of hits) {
+      if (!fileMatched.has(h.file)) fileMatched.set(h.file, new Set())
+      fileMatched.get(h.file).add(h.line)
+    }
+    const out = []
+    for (const [file, matchedLines] of fileMatched) {
+      const lines = fileLines.get(file) ?? []
+      const lineSet = new Set()
+      for (const ml of matchedLines) {
+        for (let l = Math.max(1, ml - before); l <= Math.min(lines.length, ml + after); l++) lineSet.add(l)
+      }
+      for (const l of [...lineSet].sort((a, b) => a - b)) {
+        const sep = matchedLines.has(l) ? ":" : "-"
+        out.push(`${file}${sep}${l}${sep} ${lines[l - 1]}`)
+      }
+    }
+    return truncate(out.join("\n"))
   },
 }
 
@@ -432,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}`)
     }
@@ -464,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()
 }
@@ -536,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))
   },
@@ -555,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, bashTool, globTool, grepTool, websearchTool, lsTool, fetchTool]
+export const builtinTools = [readTool, writeTool, editTool, insertAfterTool, applyPatchTool, syntaxCheckTool, bashTool, globTool, grepTool, websearchTool, lsTool, fetchTool]
 
 // ---------------------------------------------------------------- delete
 
@@ -617,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])
@@ -650,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")) {
@@ -730,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)