thincoder 0.12.52 → 0.12.54

package/src/tools/execute.md

@@ -11,7 +11,7 @@ Parameters:
 - nodeArgs: (scriptFile) extra node flags before the script, e.g. ["--test"], ["--check"]. Eval-like flags (--eval/--input-type/--inspect) are rejected.
 - workdir: run in this directory (relative to cwd, confined to the workspace; default cwd)
 - filter: optional — only return output lines matching this regex (case-insensitive)
-- timeoutMs: Timeout in milliseconds (default 30000, max 60000)
+- timeoutMs: Timeout in milliseconds (default 30000, max 600000 — covers slow `node --test` suites and long package scripts)
 
 Notes:
 - `console.log(...)` and `log(...)` both print to the result; objects are JSON-stringified by `log`.

package/src/tools/execute.mjs

@@ -161,8 +161,8 @@ export const executeTool = {
       timeoutMs: {
         type: "integer",
         minimum: 1,
-        maximum: 60000,
-        description: `Timeout in milliseconds (default ${DEFAULT_TIMEOUT}, max 60000)`,
+        maximum: 600000,
+        description: `Timeout in milliseconds (default ${DEFAULT_TIMEOUT}, max 600000)`,
       },
     },
     required: [],
@@ -175,7 +175,7 @@ export const executeTool = {
     catch (e) { return `Error: ${e.message}` }
 
     const t = Number(args.timeoutMs)
-    const timeoutMs = Number.isFinite(t) && t > 0 ? Math.min(t, 60_000) : DEFAULT_TIMEOUT
+    const timeoutMs = Number.isFinite(t) && t > 0 ? Math.min(t, 600_000) : DEFAULT_TIMEOUT
 
     let childArgs
     if (args.scriptFile) {

package/src/tools/fetch.md

@@ -2,6 +2,7 @@ Fetch a URL and return its content as text. HTML pages are stripped to readable
 
 Parameters:
 - url (required): http/https URL
+- proxy: http://host:port explicit proxy (optional) — use ONLY when passed; no proxy = direct. config.json proxy is NOT auto-applied (2026-08-31 ruling); pick per target (github/foreign sites need a proxy, gitee/domestic don't)
 
 Notes:
 - Follows redirects automatically

package/src/tools/file.mjs

@@ -38,6 +38,36 @@ export function markDirty(abs) { dirtyPaths.add(abs) }
 export function clearDirty(abs) { dirtyPaths.delete(abs) }
 export function isDirty(abs) { return dirtyPaths.has(abs) }
 
+// 2026-08-31 工具顺手度优化（用户批准）：写入工具记录受影响行范围——insert_after
+// 精确判定：after_line 在未受影响区（< lastWrite.startLine）→ 行号未漂移 → 允许
+// （消掉"我写的文件被当外部修改、必须重 read"的摩擦）；受影响区内 → 拒绝（护栏保留）；
+// write 全文重写 → 全文件受影响，任何 after_line 拒绝。
+const lastWrites = new Map() // abs → { type: 'write'|'edit'|'insert', startLine, shift }
+export function recordWrite(abs, write) {
+  lastWrites.set(abs, write)
+  dirtyPaths.delete(abs) // 本 session 写入——等效于刚 read 过（快照在 lastWrites）
+}
+export function lastWriteOf(abs) { return lastWrites.get(abs) }
+export function clearLastWrite(abs) { lastWrites.delete(abs) }
+
+/** 2026-08-31 工具顺手度（用户批准"可以啊"）：写入工具返回带上下文窗口——
+ *  模型拿到的不只是"inserted at L395"，而是"L395 这行是什么内容"——下次再操作时
+ *  能自检"我的行号 vs 实际内容"是否匹配，匹配不上 = 行号漂了，先 read——
+ *  死循环就断了（根因：模型对行号锚点的"新鲜度"没有感知——数字本身不携带语义）。
+ *  write 全文重写跳过（无行号锚点——模型刚写的知道内容）。 */
+async function appendWriteContext(abs, writeLine, baseResult) {
+  const content = normalizeEOL(await readFile(abs, "utf8"))
+  const lines = content.split("\n")
+  const start = Math.max(1, writeLine - 3)
+  const end = Math.min(lines.length, writeLine + 3)
+  const ctxLines = []
+  for (let i = start; i <= end; i++) {
+    const marker = i === writeLine ? "→" : " "
+    ctxLines.push(`${marker} L${i}\t${lines[i - 1]}`)
+  }
+  return `${baseResult}\ncontext (L${start}-L${end}):\n${ctxLines.join("\n")}`
+}
+
 export const readTool = {
   name: "read",
   description: DESC("read"),
@@ -61,6 +91,7 @@ export const readTool = {
     const content = normalizeEOL(await readFile(abs, "utf8"))
     // A read refreshes the agent's view — line numbers are fresh again.
     clearDirty(abs)
+    clearLastWrite(abs) // 2026-08-31：read 同时清写入快照（新视图以 read 为准）
     const lines = content.split("\n")
     const offset = Math.max(1, args.offset ?? 1)
     const limit = Math.min(args.limit ?? MAX_READ_LINES, MAX_READ_LINES)
@@ -171,7 +202,7 @@ export const writeTool = {
     const eol = prev != null ? detectFileEol(prev) : majorityEol(dirname(abs))
     const content = eol === "\r\n" ? normalizeEOL(args.content).replace(/\n/g, "\r\n") : args.content
     await writeFile(abs, content, "utf8")
-    markDirty(abs)
+    recordWrite(abs, { type: "write", startLine: 1, shift: 0 }) // 全文重写——全文件受影响
     const diff = gitDiffOne(ctx.cwd, abs)
     return `Wrote ${args.content.length} chars to ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
   },
@@ -189,12 +220,78 @@ export const editTool = {
       old_string: { type: "string", description: "Exact text to replace" },
       new_string: { type: "string", description: "Replacement text" },
       replace_all: { type: "boolean", description: "Replace all occurrences (default false)" },
+      edits: {
+        type: "array",
+        description: "2026-08-31 工具顺手度：一次多文件原子替换——任一失败全不写（先全量检查所有替换可执行）。与 path/old_string/new_string 互斥。",
+        items: {
+          type: "object",
+          properties: {
+            path: { type: "string" },
+            old_string: { type: "string" },
+            new_string: { type: "string" },
+            replace_all: { type: "boolean" },
+          },
+          required: ["path", "old_string", "new_string"],
+        },
+      },
     },
-    required: ["path", "old_string", "new_string"],
+    required: [],
   },
   readonly: false,
-  touchedPaths(args) { return args.path ? [args.path] : [] },
+  touchedPaths(args) {
+    if (args.edits) return args.edits.map((e) => e.path).filter(Boolean)
+    return args.path ? [args.path] : []
+  },
   async execute(args, ctx) {
+    // 2026-08-31 工具顺手度（用户批准）：数组形态——一次多文件原子替换
+    if (args.edits) {
+      if (!Array.isArray(args.edits) || args.edits.length === 0) {
+        throw new Error("edits must be a non-empty array of {path, old_string, new_string}")
+      }
+      if (args.path || args.old_string !== undefined || args.new_string !== undefined) {
+        throw new Error("edits array is mutually exclusive with path/old_string/new_string")
+      }
+      // 原子：先全量 read+match 检查（所有文件都能替换）——任一失败全不写
+      const prepared = []
+      for (const e of args.edits) {
+        if (!e.path) throw new Error("each edit must have a path")
+        if (!e.old_string) throw new Error(`edit for ${e.path}: old_string must not be empty`)
+        const abs = resolveInCwd(ctx, e.path)
+        const raw = await readFile(abs, "utf8")
+        const content = normalizeEOL(raw)
+        const occurrences = content.split(e.old_string).length - 1
+        if (occurrences === 0) {
+          throw new Error(
+            `edit aborted (atomic — no files written): old_string not found in ${e.path}\n` +
+            `  searched: "${e.old_string.slice(0, 100).split("\n")[0]}${e.old_string.length > 100 ? "…" : ""}"`
+          )
+        }
+        if (occurrences > 1 && !e.replace_all) {
+          throw new Error(
+            `edit aborted (atomic — no files written): old_string matches ${occurrences} times in ${e.path}; ` +
+            `provide more context or set replace_all`
+          )
+        }
+        const updated = e.replace_all
+          ? content.split(e.old_string).join(e.new_string)
+          : content.replace(e.old_string, () => e.new_string)
+        const matchIdx = content.indexOf(e.old_string)
+        const editStartLine = matchIdx >= 0 ? content.slice(0, matchIdx).split("\n").length : 1
+        const lineShift = e.new_string.split("\n").length - e.old_string.split("\n").length
+        prepared.push({ abs, path: e.path, raw, updated, editStartLine, lineShift, occurrences: e.replace_all ? occurrences : 1 })
+      }
+      // 全部检查通过——逐个写
+      const results = []
+      for (const p of prepared) {
+        await writeFile(p.abs, joinWithEol(normalizeEOL(p.updated).split("\n"), p.raw), "utf8")
+        recordWrite(p.abs, { type: "edit", startLine: p.editStartLine, shift: p.lineShift })
+        const withCtx = await appendWriteContext(p.abs, p.editStartLine, `Edited ${p.path}: replaced ${p.occurrences} occurrence(s)`)
+        results.push(withCtx)
+      }
+      return results.join("\n")
+    }
+
+    // 单文件（现状路径）
     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)")
@@ -219,7 +316,11 @@ export const editTool = {
       throw new Error(
         `old_string not found in ${args.path}\n` +
         `  searched: "${preview}${args.old_string.length > 100 ? "…" : ""}"\n` +
-        `  hints: whitespace mismatch? file already changed? try reading the file first` +
+        (lastWriteOf(abs)?.type === "write"
+          ? `  hints: this file was modified since your last read (write 全文重写后内容全变) — re-read it to refresh your copy of the content, then retry\n`
+          : isDirty(abs)
+            ? `  hints: this file was modified since your last read (a prior write marked it dirty) — re-read it to refresh your copy of the content, then retry\n`
+            : `  hints: whitespace mismatch? file already changed? try reading the file first\n`) +
         candText
       )
     }
@@ -235,9 +336,14 @@ export const editTool = {
     // normalizeEOL first: new_string may carry \r\n (e.g. pasted from a raw CRLF
     // read); without normalizing, split leaves stray \r and CRLF join makes \r\r\n.
     await writeFile(abs, joinWithEol(normalizeEOL(updated).split("\n"), raw), "utf8")
-    markDirty(abs)
+    // 2026-08-31 工具顺手度：记录受影响区（替换首行 + 行数差）——insert_after 精确判定
+    const matchIdx = content.indexOf(args.old_string)
+    const editStartLine = matchIdx >= 0 ? content.slice(0, matchIdx).split("\n").length : 1
+    const lineShift = args.new_string.split("\n").length - args.old_string.split("\n").length
+    recordWrite(abs, { type: "edit", startLine: editStartLine, shift: lineShift })
     const diff = gitDiffOne(ctx.cwd, abs)
-    return `Edited ${args.path}: replaced ${args.replace_all ? occurrences : 1} occurrence(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
+    const baseResult = `Edited ${args.path}: replaced ${args.replace_all ? occurrences : 1} occurrence(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
+    return await appendWriteContext(abs, editStartLine, baseResult)
   },
 }
 
@@ -265,7 +371,24 @@ export const insertAfterTool = {
     // inserting at a drifted position (the failure mode that corrupted test
     // structure repeatedly). after_regex callers get the same gate — a stale
     // target line is just as wrong, and the rule is simpler to reason about.
-    if (isDirty(abs)) {
+    // 2026-08-31 工具顺手度（用户批准）：判定精确化——本 session 写入工具记录受影响区
+    // （lastWrite），after_line 在未受影响区（<= startLine）→ 行号未漂移 → 允许
+    // （消掉"我写的文件被当外部修改"的摩擦）；受影响区内/write 全文重写 → 拒绝。
+    const lw = lastWriteOf(abs)
+    if (lw && args.after_line != null) {
+      if (lw.type === "write") {
+        throw new Error(
+          `${args.path} 刚被 write 全文重写（was modified since your last read）——任何行号都可能漂移，必须重 read。`
+        )
+      }
+      if (args.after_line > lw.startLine) {
+        throw new Error(
+          `${args.path} 的 after_line ${args.after_line} 在上次写入（L${lw.startLine}）之后——` +
+          `行号已漂移 ${lw.shift >= 0 ? "+" : ""}${lw.shift}，请用新行号或先 read。`
+        )
+      }
+      // after_line <= startLine → 行号未漂移 → 允许
+    } else if (isDirty(abs)) {
       throw new Error(
         `${args.path} was modified since your last read — line numbers may be stale.\n` +
         `Read the file again (read tool) to refresh line numbers, then retry insert_after.`
@@ -307,9 +430,10 @@ export const insertAfterTool = {
     // edit — a CRLF file must not silently become LF here either).
     const updated = joinWithEol(lines, raw)
     await writeFile(abs, updated, "utf8")
-    markDirty(abs)
+    recordWrite(abs, { type: "insert", startLine: targetLine, shift: normalizeEOL(args.content).split("\n").length })
     const diff = gitDiffOne(ctx.cwd, abs)
-    return `Inserted after line ${targetLine} in ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
+    const baseResult = `Inserted after line ${targetLine} in ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
+    return await appendWriteContext(abs, targetLine + 1, baseResult)
   },
 }
 
@@ -399,9 +523,10 @@ export const hashlineEditTool = {
     // Write back in the file's original EOL style (same rule as edit / apply_patch).
     const updated = joinWithEol(lines, raw)
     await writeFile(abs, updated, "utf8")
-    markDirty(abs)
+    recordWrite(abs, { type: "edit", startLine: pos + 1, shift: newLines.length - target.length })
     const diff = gitDiffOne(ctx.cwd, abs)
-    return `Edited ${args.path}: replaced ${target.length} line(s) at L${pos + 1} with ${newLines.length} line(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}${corrupted ? `\n${FFFD_WARNING}` : ""}`
+    const baseResult = `Edited ${args.path}: replaced ${target.length} line(s) at L${pos + 1} with ${newLines.length} line(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}${corrupted ? `\n${FFFD_WARNING}` : ""}`
+    return await appendWriteContext(abs, pos + 1, baseResult)
   },
 }
 

package/src/tools/git-checkpoint.mjs

@@ -0,0 +1,143 @@
+/**
+ * git-checkpoint.mjs — git 工具 checkpoint action 子系统（CHECKPOINT.md F2/F6）。
+ * git.mjs 的 checkpoint case 委托到这里：list/create/rewind/cat/versions + F6 懒清理 +
+ * F2/D7 提示行 + 文件树格式化。CLI 与 VS Code 两端同构（镜像，修改须两端同批）。
+ */
+import { runGit } from "./shared.mjs"
+import { escapeXml } from "../agent/helpers.mjs"
+import {
+  createCheckpoint,
+  listCheckpoints,
+  rewind,
+  listFileVersions,
+  catFile,
+  isGitRepo,
+  deleteCheckpointsForCwd,
+} from "../git/checkpoint.mjs"
+
+/** F6 lazy fallback (CHECKPOINT.md D3): an EXTERNAL git commit (via bash / IDE — not the git
+ *  tool) leaves this cwd's checkpoints as pre-commit state. Compare HEAD commit time
+ *  (epoch SECONDS from %ct) against the newest snapshot's meta.time (ms): `%ct × 1000` aligns
+ *  both to ms. HEAD newer → every snapshot predates the commit → clear all. All-or-nothing:
+ *  any snapshot NEWER than HEAD (e.g. a manual create after the external commit) skips the
+ *  whole clear. Best-effort — never blocks the checkpoint op. */
+export async function lazyClearIfCommitted(cwd) {
+  try {
+    const cps = await listCheckpoints(cwd)
+    if (cps.length === 0) return
+    const headSec = runGit(cwd, ["log", "-1", "--format=%ct"])
+    const headMs = Number.parseInt(headSec, 10) * 1000
+    if (!Number.isFinite(headMs) || headMs <= 0) return
+    const newest = cps[0] // listCheckpoints returns newest → oldest
+    if (headMs > newest.time) await deleteCheckpointsForCwd(cwd)
+  } catch {
+    // best-effort (NF7 philosophy) — a lazy-clear failure must not break list/create
+  }
+}
+
+/** checkpoint case 主入口（git 工具 checkpoint action 的全部子动作）。 */
+export async function executeCheckpointAction(args, ctx) {
+  const { checkpointAction: sub, checkpointId: id, path } = args
+  if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
+
+  if (!sub) return "checkpoint: missing checkpointAction — use: list | create | rewind | cat | versions"
+
+  // F6 lazy fallback (list/create entry): an EXTERNAL git commit (HEAD time newer
+  // than the newest snapshot) means every snapshot predates a safety baseline —
+  // clear them. All-or-nothing: if any snapshot is newer than HEAD, skip entirely.
+  if (sub === "list" || sub === "create") await lazyClearIfCommitted(ctx.cwd)
+
+  if (sub === "create") {
+    const cp = await createCheckpoint(ctx.cwd)
+    return `Checkpoint ${cp.id} created (${cp.files} file(s): ${cp.tracked.length} tracked, ${cp.untracked.length} untracked)`
+  }
+  if (sub === "versions") {
+    if (!path) throw new Error("path is required for versions — the file whose history you want")
+    const versions = await listFileVersions(ctx.cwd, path)
+    if (versions.length === 0) return `No snapshot copies of "${path}" found (it was never part of an auto/protection snapshot).`
+    return (
+      `Historical versions of "${path}" (${versions.length}, newest first):\n` +
+      versions.map((v) =>
+        `  ${v.snapshotId}  ${new Date(v.time).toISOString()}  ${v.size}B  sha:${v.sha}  (${v.source})` +
+        (v.sha === versions[versions.indexOf(v) - 1]?.sha ? "  ← same content as previous" : "")
+      ).join("\n") +
+      `\nRestore a version: checkpointAction=rewind checkpointId=<snapshotId> path="${path}"`
+    )
+  }
+  if (sub === "rewind") {
+    if (!id) throw new Error("checkpointId is required for rewind — use checkpointAction=list to see snapshot ids")
+    if (!path) throw new Error("path is required for rewind — full restore is disabled (as dangerous as `git checkout -- .`). Restore files individually. Use checkpointAction=versions path=<file> to list a file's historical versions.")
+    const s = await rewind(ctx.cwd, id, { path })
+    return `Restored "${path}" (${s.type}) from checkpoint ${id}.\n(The pre-restore state was snapshotted first — you can restore again to go back.)`
+  }
+  if (sub === "cat") {
+    if (!id) throw new Error("checkpointId is required for cat — use checkpointAction=list to see snapshot ids")
+    if (!path) throw new Error("path is required for cat — specify which file to read")
+    return await catFile(ctx.cwd, id, path)
+  }
+  if (sub === "list") {
+    const cps = await listCheckpoints(ctx.cwd)
+    if (cps.length === 0) return "(no checkpoints yet)"
+
+    // Specific id: show the file tree within that snapshot
+    if (id) {
+      const cp = cps.find((c) => c.id === id)
+      if (!cp) throw new Error(`checkpoint ${id} not found`)
+      return formatFileTree(cp)
+    }
+
+    // Overview: list of all snapshots (file names are XML-escaped: they are
+    // untrusted input that flows back into the model's context). F2/D7: fixed
+    // hint line at the tail — the recovery entry for a snapshot after an accident.
+    return cps.map((c) => {
+      const parts = [`${c.id}  ${new Date(c.time).toISOString()}`]
+      if (c.tracked.length) parts.push(`${c.tracked.length} tracked: ${c.tracked.map(escapeXml).join(", ")}`)
+      if (c.untracked.length) parts.push(`${c.untracked.length} untracked: ${c.untracked.map(escapeXml).join(", ")}`)
+      return parts.join("  ")
+    }).join("\n") + "\n(意外丢弃改动？checkpointAction=rewind 可恢复操作前状态)"
+  }
+  throw new Error(`Unknown checkpoint action: ${sub}. Use: list | create | rewind | cat | versions`)
+}
+
+/** Format a checkpoint's file list as a directory tree (directories first, indented display) */
+function formatFileTree(cp) {
+  // File names are XML-escaped: untrusted input that flows back into the model's context
+  const all = [
+    ...(cp.tracked ?? []).map((f) => ({ path: escapeXml(f), type: "" })),
+    ...(cp.untracked ?? []).map((f) => ({ path: escapeXml(f), type: " (untracked)" })),
+  ]
+  if (all.length === 0) return "(empty checkpoint)"
+
+  all.sort((a, b) => a.path.localeCompare(b.path))
+
+  const tree = new Map()
+  for (const { path, type } of all) {
+    const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "."
+    if (!tree.has(dir)) tree.set(dir, [])
+    tree.get(dir).push({ name: path.slice(dir === "." ? 0 : dir.length + 1), type })
+  }
+
+  const lines = []
+  const dirs = [...tree.keys()].sort()
+  for (const dir of dirs) {
+    if (dir !== "." && !lines.includes(dir + "/")) {
+      const parts = dir.split("/")
+      for (let i = 1; i <= parts.length; i++) {
+        const prefix = parts.slice(0, i).join("/") + "/"
+        if (!lines.includes(prefix)) lines.push(prefix)
+      }
+    }
+  }
+  for (const dir of dirs) {
+    if (dir !== ".") {
+      for (const { name, type } of tree.get(dir)) {
+        lines.push(`  ${dir}/${name}${type}`)
+      }
+    }
+  }
+  for (const { name, type } of tree.get(".") ?? []) {
+    lines.push(name + type)
+  }
+
+  return lines.join("\n")
+}

package/src/tools/git-ext.mjs

@@ -0,0 +1,173 @@
+/**
+ * git-ext.mjs — git 工具 F7 扩展 action（clone/init/rebase/remote/clean/switch/apply/worktree/
+ * archive/blame/mv）+ 共享 git 辅助函数（validateRef/runGitStrict/filterLines/snapshotBefore，
+ * 供 git.mjs 核心 action 复用——500 行硬限拆分）。CLI 与 VS Code 两端同构（镜像，修改须两端同批）。
+ */
+import { runGit, truncate } from "./shared.mjs"
+import { execFileSync } from "node:child_process"
+
+/** Keep only output lines matching a regex (git filter, case-insensitive). */
+export function filterLines(output, filter) {
+  if (!filter) return output
+  try {
+    const re = new RegExp(filter, "i")
+    const lines = output.split("\n").filter((l) => re.test(l))
+    return lines.length ? lines.join("\n") : `(no lines matched filter "${filter}")`
+  } catch (e) {
+    return `Error: filter regex invalid: ${e.message}`
+  }
+}
+
+/** Run git and report failure (stderr + exit code) instead of swallowing it.
+ *  Used by write ops (commit/push/rm) where a silent "" would masquerade as success. */
+export function runGitStrict(cwd, cmdArgs, config = []) {
+  try {
+    const out = execFileSync("git", [...config, ...cmdArgs], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim().replace(/\r/g, "")
+    return { ok: true, out }
+  } catch (e) {
+    return { ok: false, out: String(e.stdout || "").trim(), err: String(e.stderr || e.message || "").trim() }
+  }
+}
+
+/** Validate a git ref / branch / tag / remote name (no option injection, no whitespace). */
+export function validateRef(ref, what = "git ref") {
+  if (!/^[A-Za-z0-9._/~^@][A-Za-z0-9._/~^@{}-]*$/.test(ref)) throw new Error(`Invalid ${what}: ${ref}`)
+  return ref
+}
+
+/** Normalize args.config into `-c key=value` pairs (git -c overrides, e.g. a proxy).
+ *  Values are execFileSync array args (no shell injection) — still reject newlines/empty. */
+export function gitConfigArgs(config) {
+  if (config == null) return []
+  if (!Array.isArray(config)) throw new Error("config must be an array of \"key=value\" strings")
+  const out = []
+  for (const c of config) {
+    if (typeof c !== "string" || !c.trim() || c.includes("\n")) throw new Error(`invalid git -c config entry: ${String(c).slice(0, 60)}`)
+    out.push("-c", c)
+  }
+  return out
+}
+
+/** Snapshot the working tree before a destructive op (reset --hard / checkout file / restore /
+ *  stash pop / branch|tag delete / clean / rebase). Best-effort — a snapshot failure must not
+ *  block the op (the approval/permission layer is the real gate). Returns a note line or "". */
+export async function snapshotBefore(ctx, label) {
+  try {
+    const { createCheckpoint, isGitRepo } = await import("../git/checkpoint.mjs")
+    if (!isGitRepo(ctx.cwd)) return ""
+    const cp = await createCheckpoint(ctx.cwd)
+    return `[snapshot ${cp.id} created before ${label}]\n`
+  } catch {
+    return ""
+  }
+}
+
+/** F7 扩展 action 主入口（git 工具 switch 的 fall-through 组委托到这里）。 */
+export async function executeExtAction(args, ctx) {
+  switch (args.action) {
+    case "clone": {
+      // Clone a repo into a NEW directory — non-destructive (never touches existing work).
+      if (!args.remote) return "Error: clone requires remote (URL or local path)"
+      const cmdArgs = ["clone", args.remote]
+      if (args.path) cmdArgs.push(args.path)
+      const r = runGitStrict(ctx.cwd, cmdArgs, gitConfigArgs(args.config))
+      return r.ok ? truncate(r.out || `Cloned ${args.remote}`) : truncate(`git clone failed: ${r.err || r.out}`)
+    }
+    case "init": {
+      const r = runGitStrict(ctx.cwd, ["init"])
+      return r.ok ? truncate(r.out || "Initialized empty git repository") : truncate(`git init failed: ${r.err || r.out}`)
+    }
+    case "rebase": {
+      // Belt-and-braces snapshot: bare rebase refuses uncommitted changes (unless
+      // --autostash), but --autostash restore-failure / interrupted-rebase scenarios
+      // can leave the working tree damaged — the snapshot makes that recoverable.
+      // The snapshot line is included on FAILURE too: a rejected rebase (unstaged
+      // changes) is exactly when the model must know its work is protected (F1 loop).
+      const snap = await snapshotBefore(ctx, "rebase")
+      const sub = args.rebaseAction ?? "start"
+      const cmdArgs = ["rebase"]
+      if (sub === "abort") cmdArgs.push("--abort")
+      else if (sub === "continue") cmdArgs.push("--continue")
+      else { if (!args.ref) return "Error: rebase requires ref (branch/commit to rebase onto)"; cmdArgs.push(validateRef(args.ref)) }
+      const r = runGitStrict(ctx.cwd, cmdArgs)
+      return r.ok ? truncate(snap + (r.out || `Rebase ${sub} complete`)) : truncate(snap + `git rebase failed: ${r.err || r.out} — use rebaseAction=abort to abort`)
+    }
+    case "remote": {
+      const sub = args.remoteAction ?? "list"
+      if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["remote", "-v"]) || "(no remotes)", args.filter))
+      if (!args.remote) return `Error: remote ${sub} requires remote (name)`
+      validateRef(args.remote, "remote name")
+      if (sub === "add" || sub === "set-url") {
+        if (!args.remoteUrl) return `Error: remote ${sub} requires remoteUrl`
+        const r = runGitStrict(ctx.cwd, ["remote", sub === "add" ? "add" : "set-url", args.remote, args.remoteUrl])
+        return r.ok ? `Remote ${args.remote} ${sub === "add" ? "added" : "URL set"}` : truncate(`git remote ${sub} failed: ${r.err || r.out}`)
+      }
+      if (sub === "remove") {
+        const r = runGitStrict(ctx.cwd, ["remote", "remove", args.remote])
+        return r.ok ? `Remote ${args.remote} removed` : truncate(`git remote remove failed: ${r.err || r.out}`)
+      }
+      return "Error: remote requires remoteAction — use: list | add | remove | set-url"
+    }
+    case "clean": {
+      // Destructive: removes untracked files/dirs — snapshot first (guard parity).
+      // dryRun (-n) is a preview: no deletion, no snapshot.
+      const snap = args.dryRun ? "" : await snapshotBefore(ctx, "clean")
+      const cmdArgs = ["clean", args.dryRun ? "-n" : "-f", "-d"]
+      const r = runGitStrict(ctx.cwd, cmdArgs)
+      return r.ok ? truncate(snap + (r.out || (args.dryRun ? "Nothing to clean (dry run)" : "Clean complete"))) : truncate(snap + `git clean failed: ${r.err || r.out}`)
+    }
+    case "switch": {
+      if (!args.name) return "Error: switch requires name (branch)"
+      validateRef(args.name, "branch")
+      const cmdArgs = ["switch"]
+      if (args.create) cmdArgs.push("-c")
+      cmdArgs.push(args.name)
+      const r = runGitStrict(ctx.cwd, cmdArgs)
+      return r.ok ? truncate(r.out || `Switched to branch ${args.name}`) : truncate(`git switch failed: ${r.err || r.out}`)
+    }
+    case "apply": {
+      // Apply a patch — non-destructive (fails cleanly on conflict, applies nothing).
+      if (!args.path) return "Error: apply requires path (patch file)"
+      const r = runGitStrict(ctx.cwd, ["apply", "--", args.path])
+      return r.ok ? truncate(r.out || `Applied ${args.path}`) : truncate(`git apply failed: ${r.err || r.out}`)
+    }
+    case "worktree": {
+      const sub = args.worktreeAction ?? "list"
+      if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["worktree", "list"]) || "(no worktrees)", args.filter))
+      if (sub === "add") {
+        if (!args.path) return "Error: worktree add requires path (new worktree directory)"
+        const cmdArgs = ["worktree", "add", args.path]
+        if (args.ref) cmdArgs.push(validateRef(args.ref))
+        const r = runGitStrict(ctx.cwd, cmdArgs)
+        return r.ok ? truncate(r.out || `Worktree added at ${args.path}`) : truncate(`git worktree add failed: ${r.err || r.out}`)
+      }
+      if (sub === "remove") {
+        if (!args.path) return "Error: worktree remove requires path"
+        const r = runGitStrict(ctx.cwd, ["worktree", "remove", args.path])
+        return r.ok ? truncate(r.out || `Worktree removed: ${args.path}`) : truncate(`git worktree remove failed: ${r.err || r.out}`)
+      }
+      return "Error: worktree requires worktreeAction — use: list | add | remove"
+    }
+    case "archive": {
+      // Write a tar of a commit/branch — non-destructive (output file only).
+      if (!args.path) return "Error: archive requires path (output file)"
+      const cmdArgs = ["archive", "--format=tar", "-o", args.path]
+      if (args.ref) cmdArgs.push(validateRef(args.ref))
+      else cmdArgs.push("HEAD")
+      const r = runGitStrict(ctx.cwd, cmdArgs)
+      return r.ok ? truncate(r.out || `Archived ${args.ref ?? "HEAD"} to ${args.path}`) : truncate(`git archive failed: ${r.err || r.out}`)
+    }
+    case "blame": {
+      if (!args.path) return "Error: blame requires path (file)"
+      const out = runGit(ctx.cwd, ["blame", "--", args.path])
+      return truncate(out || `(no blame output for ${args.path})`)
+    }
+    case "mv": {
+      if (!args.path || !args.dest) return "Error: mv requires path (source) and dest (destination)"
+      const r = runGitStrict(ctx.cwd, ["mv", "--", args.path, args.dest])
+      return r.ok ? truncate(r.out || `Moved ${args.path} → ${args.dest}`) : truncate(`git mv failed: ${r.err || r.out}`)
+    }
+    default:
+      throw new Error(`Unknown ext action: ${args.action}`)
+  }
+}

package/src/tools/git.md

@@ -1,6 +1,6 @@
 Run a git command. Only works inside a git repository.
 
-**Route to git instead of bash:** `git status`→status, `git log`→log, `git diff`→diff, `git show`→show, `git add`→add, `git rm`→rm, `git commit -m`→commit, `git push <remote> <branch> <tag>`→push, `git tag`→tag, `git branch`→branch, `git checkout`→checkout, `git restore`→restore, `git stash`→stash, `git fetch/pull`→fetch/pull, `git reset`→reset, `git revert`→revert, `git merge`→merge, `git cherry-pick`→cherry-pick.
+**Route to git instead of bash:** `git status`→status, `git log`→log, `git diff`→diff, `git show`→show, `git add`→add, `git rm`→rm, `git commit -m`→commit, `git push <remote> <branch> <tag>`→push, `git tag`→tag, `git branch`→branch, `git checkout`→checkout, `git restore`→restore, `git stash`→stash, `git fetch/pull`→fetch/pull, `git reset`→reset, `git revert`→revert, `git merge`→merge, `git cherry-pick`→cherry-pick, `git ls-remote`→ls-remote, `git clone`→clone, `git init`→init, `git rebase`→rebase, `git remote`→remote, `git clean`→clean, `git switch`→switch, `git apply`→apply, `git worktree`→worktree, `git archive`→archive, `git blame`→blame, `git mv`→mv.
 
 - action='diff': unified diff — what changed since last commit. staged=true for staged-only; ref=<ref> to compare a commit/branch; path=<dir> to scope.
 - action='status': working tree state — staged / unstaged / untracked / conflicts, categorized.
@@ -19,15 +19,29 @@ Run a git command. Only works inside a git repository.
 - action='revert': revert a commit (safe). ref=<commit> (default HEAD).
 - action='merge': merge ref=<branch/commit>; conflicts reported for you to resolve.
 - action='cherry-pick': cherry-pick ref=<commit>.
+- action='ls-remote': light remote-ref check — which refs a remote has (read-only, network). remote=<origin>, ref=<branch/tag> optional, config for proxy.
+- action='clone': clone a repo. remote required (URL or local path); path optional (target dir).
+- action='init': init a repo in the current (work)dir.
+- action='rebase': rebase onto ref. rebaseAction=start (ref required) / abort / continue（操作前自动快照，checkpointAction=rewind 恢复）.
+- action='remote': manage remotes. remoteAction=list / add / remove / set-url; remoteUrl for add/set-url.
+- action='clean': remove untracked files/dirs. dryRun for -n preview（真删除操作前自动快照，checkpointAction=rewind 恢复）.
+- action='switch': switch branch. name required; create for -c (new branch).
+- action='apply': apply a patch. path required (patch file).
+- action='worktree': manage worktrees. worktreeAction=list / add (path, ref) / remove (path).
+- action='archive': write a tar of ref (default HEAD). path required (output file).
+- action='blame': file blame. path required.
+- action='mv': rename/move. path (source) + dest required.
 - action='checkpoint': git snapshots. checkpointAction=list/create/rewind/cat/versions; checkpointId required for rewind/cat.
+- Destructive ops (checkout -- path / restore / reset --hard / stash pop / branch|tag delete / clean / rebase) auto-snapshot first — restore via checkpointAction=rewind.
 
 Parameters:
-- action (required): diff / status / log / show / checkpoint / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick
+- action (required): diff / status / log / show / checkpoint / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick / ls-remote / clone / init / rebase / remote / clean / switch / apply / worktree / archive / blame / mv
 - workdir: run git in this workspace subdirectory (monorepo / multi-repo). Confined to the workspace. Default: cwd
-- path: (diff/log/add/commit/checkout/restore/rm) file or directory to scope / stage / restore
-- ref: (show/diff/checkout/reset/revert/merge/cherry-pick/tag:create/branch:create) commit/branch/ref; (push/pull/fetch) the branch or tag (space-separated for multiple)
-- name: (branch/tag) the branch or tag name
-- remote: (push/fetch/pull) remote name (e.g. origin); default: current upstream
+- config: (network actions push/fetch/pull/ls-remote/clone) git -c overrides, e.g. ["http.proxy=http://10.2.2.112:3128"] for blocked remotes
+- path: (diff/log/add/commit/checkout/restore/rm/apply/archive/blame/mv/worktree) file or directory to scope / stage / restore
+- ref: (show/diff/checkout/reset/revert/merge/cherry-pick/tag:create/branch:create/rebase/worktree:add/archive) commit/branch/ref; (push/pull/fetch) the branch or tag (space-separated for multiple)
+- name: (branch/tag/switch) the branch or tag name
+- remote: (push/fetch/pull/remote/clone) remote name (e.g. origin) or URL; default: current upstream
 - tags: (push) also push all tags (--tags)
 - staged: (diff) staged changes; (restore) the staged copy
 - count: (log) number of commits (default 10)
@@ -37,3 +51,4 @@ Parameters:
 - tagAction: (tag) list / create / delete — branchAction: (branch) list / create / delete / switch — stashAction: (stash) push / pop / list
 - filter: (read-only actions) keep only output lines matching this regex (case-insensitive)
 - checkpointAction: (checkpoint) list / create / rewind / cat / versions — checkpointId: snapshot id (rewind/cat)
+- remoteAction: (remote) list / add / remove / set-url — remoteUrl: (remote add/set-url) URL — rebaseAction: (rebase) start / abort / continue — dryRun: (clean) -n preview — create: (switch) -c — dest: (mv) destination — worktreeAction: (worktree) list / add / remove