thincoder 0.12.52 → 0.12.53

package/src/provider/sse.mjs

@@ -91,15 +91,17 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
       throw new Error(`API error: HTTP ${response.status} — ${errorMsg}`)
     }
     // HTTP < 400 non-SSE: might be a valid single-chunk JSON response (e.g. proxy
-    // stripped SSE framing). Try to parse as a chat.completion.chunk.
+    // stripped SSE framing). Parse `choice.message` (full chat.completion) OR
+    // `choice.delta` (chunk shape) — 2026-08-31: gateways downgrading stream:true
+    // to a complete completion used to return EMPTY content silently (message-only shape).
     try {
       const parsed = JSON.parse(body)
       const choice = parsed.choices?.[0]
       if (choice) {
         const result = { content: "", reasoning: "", toolCalls: [], droppedToolCalls: 0, usage: normalizeUsageCache(parsed.usage ?? null), finishReason: null }
-        const delta = choice.delta ?? {}
+        const delta = choice.delta ?? choice.message ?? {}
         result.content = delta.content ?? ""
-        result.reasoning = delta.reasoning_content ?? ""
+        result.reasoning = delta.reasoning_content ?? delta.reasoning ?? ""
         result.finishReason = choice.finish_reason ?? null
         mergeToolCalls(result, delta)
         if (result.content) onToken?.(result.content)
@@ -118,32 +120,48 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
   let hasChoices = false
   const firedPatterns = sharedFired ?? new Set()
 
-  const processLines = (lines) => {
-    for (const line of lines) {
-      if (!line.startsWith("data:")) continue
-      const data = line.slice(5).trim()
-      if (!data || data === "[DONE]") continue
+  /** Process one complete SSE event (data lines joined with \n per the SSE spec).
+   *  2026-08-31: rows are buffered per event (multi-line data: support that the
+   *  per-line JSON.parse used to crash on — single-line events behave identically). */
+  const handleEvent = (data) => {
+    if (!data || data === "[DONE]") return
+    let json
+    try { json = JSON.parse(data) } catch { return }
 
-      let json
-      try { json = JSON.parse(data) } catch { continue }
+    if (json.usage) result.usage = normalizeUsageCache(json.usage)
+    const choice = json.choices?.[0]
+    if (!choice) return
+    hasChoices = true
+    if (choice.finish_reason) result.finishReason = choice.finish_reason
 
-      if (json.usage) result.usage = normalizeUsageCache(json.usage)
-      const choice = json.choices?.[0]
-      if (!choice) continue
-      hasChoices = true
-      if (choice.finish_reason) result.finishReason = choice.finish_reason
+    const delta = choice.delta ?? choice.message ?? {}
+    // reasoning 方言：DeepSeek/Kimi/GLM 用 reasoning_content，OpenAI o 系和部分
+    // 路由器用 reasoning —— 两个都认（2026-08-31 会诊 #9）
+    const rDelta = delta.reasoning_content ?? delta.reasoning
+    if (rDelta) {
+      result.reasoning += rDelta
+      onReasoning?.(rDelta)
+    }
+    if (delta.content) {
+      result.content += delta.content
+      onToken?.(delta.content)
+    }
+    mergeToolCalls(result, delta)
+  }
 
-      const delta = choice.delta ?? {}
-      if (delta.reasoning_content) {
-        result.reasoning += delta.reasoning_content
-        onReasoning?.(delta.reasoning_content)
-      }
-      if (delta.content) {
-        result.content += delta.content
-        onToken?.(delta.content)
+  const processLines = (lines) => {
+    let currentData = ""
+    for (const line of lines) {
+      if (line.startsWith("data:")) {
+        const v = line.slice(5).trim()
+        if (v === "[DONE]") { currentData = ""; continue }
+        // multi-line data: joins with \n (SSE spec); single-line is the common case
+        currentData = currentData ? currentData + "\n" + v : v
+        continue
       }
-      mergeToolCalls(result, delta)
+      if (line === "" && currentData) { handleEvent(currentData); currentData = "" }
     }
+    if (currentData) handleEvent(currentData)
   }
 
   if (!response.body) throw new Error("No stream response body")
@@ -155,6 +173,9 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
         throw e
       }
       buffer += decoder.decode(chunk, { stream: true })
+      // UTF-8 BOM 剥除（2026-08-31 会诊 #12）：某些网关/负载均衡在流首注入 \uFEFF，
+      // 首行 "data:" 前缀匹配失败会被静默丢弃（首个事件整体消失）。
+      if (buffer.charCodeAt(0) === 0xfeff) buffer = buffer.slice(1)
       const lines = buffer.split("\n")
       buffer = lines.pop()
       processLines(lines)
@@ -186,6 +207,19 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
       result.interruptMessage = signal.reason.message
       return result
     }
+    // 2026-08-31 会诊 #2（流中断丢全部已收内容）：网络级失败（ECONNRESET / 半截 EOF /
+    // proxy 断连）时若已解析出内容，把 partial 交回上层而不是整轮报废重试。
+    // 标记 partial:true + networkError（上层可决定续写/重试/展示部分结果）。
+    if (hasChoices && (result.content || result.toolCalls.length)) {
+      finalizeToolCalls(result)
+      result.partial = true
+      result.networkError = e.message ?? String(e)
+      const existing = result._warnings ??= []
+      if (!existing.some((w) => w.name === "network-partial")) {
+        existing.push({ name: "network-partial", message: `stream interrupted by network error after partial output: ${result.networkError}` })
+      }
+      return result
+    }
     throw e
   }
 

package/src/proxy.mjs

@@ -64,9 +64,12 @@ function abortError(signal) {
  * body 边收边吐（SSE 流式消费方可逐 chunk 读取）；text() 消费流到底（非流式调用方用）。
  * opts.signal 全程有效：abort 即 destroy socket 并 reject/终止流。
  * absoluteForm: 请求行发绝对 URI（http:// 目标的经典代理转发用），默认发 origin-form。
+ * 2026-08-31 会诊 #4：timeout 只覆盖"响应头阶段"；settle 后 body 空闲 > bodyIdleMs 即
+ * 断流（原实现头部 timer 到齐即清，流式中途停摆会无限挂起直到用户 Ctrl+C）。
+ * bodyIdleMs 默认 120s（provider 长生成用 0 即禁用，由调用方决定）。
  * 导出供测试（裸 socket，无需 TLS/CONNECT）；生产路径走 tunnelHttps / proxyFetch。
  */
-export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIMEOUT, absoluteForm = false) {
+export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIMEOUT, absoluteForm = false, bodyIdleMs = 120_000) {
   return new Promise((resolve, reject) => {
     const target = new URL(urlStr)
     const method = opts.method ?? "GET"
@@ -78,6 +81,7 @@ export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIME
     const body = new PassThrough()
     let settled = false
     let headerBuf = ""
+    let idleTimer = null
 
     const timer = setTimeout(() => fail(new Error("Response timeout")), timeout)
     const onAbort = () => { sock.destroy(); fail(abortError(signal)) }
@@ -85,6 +89,7 @@ export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIME
 
     function cleanup() {
       clearTimeout(timer)
+      clearTimeout(idleTimer)
       signal?.removeEventListener("abort", onAbort)
     }
     /** 头部阶段失败 reject；resolve 后失败则终止 body 流（for-await 抛出，不挂起） */
@@ -93,6 +98,11 @@ export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIME
       if (!settled) { settled = true; reject(err) }
       else body.destroy(err)
     }
+    /** body 阶段空闲看门狗：每次数据到达重置；无数据超时 → 断流（流式消费方抛错） */
+    function armIdle() {
+      clearTimeout(idleTimer)
+      if (bodyIdleMs > 0) idleTimer = setTimeout(() => body.destroy(new Error("Response body timeout (idle)")), bodyIdleMs)
+    }
 
     sock.on("data", (d) => {
       if (settled) return // 理论上不会发生（settle 后摘掉本监听器），防御
@@ -113,11 +123,20 @@ export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIME
       sock.removeAllListeners("data")
       settled = true
       cleanup()
+      armIdle()
       const remaining = headerBuf.slice(idx + 4)
       if (remaining) body.write(Buffer.from(remaining, "utf8"))
       sock.pipe(body)
-      // body 结束后才移除 abort 监听（流式中途 abort 要能终止流）
-      body.on("close", () => signal?.removeEventListener("abort", onAbort))
+      // 空闲看门狗随数据到达重置。注意必须用 'readable' 而非 'data'：
+      // 'data' 监听把流切成 flowing 模式，会抢走 readSSE/for-await 未来得及认领的
+      // 已写缓冲（2026-08-31 实测：分包响应头的 remaining 首段被吞，readSSE 等不到 ack）。
+      // 'readable' 不改变流模式，数据仍由消费方按需拉取。
+      body.on("readable", armIdle)
+      // body 结束后才移除 abort 监听（流式中途 abort 要能终止流）；空闲看门狗一并清
+      body.on("close", () => {
+        clearTimeout(idleTimer)
+        signal?.removeEventListener("abort", onAbort)
+      })
       signal?.addEventListener("abort", onAbort, { once: true })
 
       resolve({
@@ -156,12 +175,20 @@ export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIME
 /**
  * HTTPS request through HTTP CONNECT proxy tunnel.
  * CONNECT + TLS 建立后交给 streamHttpResponse — 响应头到齐即 resolve，body 为流式。
+ * 2026-08-31 会诊 #1/#4：
+ *  - TLS 默认全量证书校验（rejectUnauthorized: true）——走代理的流量（含 API key）
+ *    不得在未验证链路上传输；确需自签/内网代理时 opts.insecureTls=true 显式放行。
+ *  - CONNECT/TLS 阶段用 timeout（默认 15s，建隧道快）；**响应头超时**用
+ *    opts._headerTimeoutMs（默认 60s）——原实现共用 15s，DeepSeek 排队 TTFB>15s
+ *    即误报 "Response timeout"，与直连 600s 语义割裂。
  */
 export function tunnelHttps(urlStr, opts, proxyUri, timeout = FETCH_TIMEOUT) {
   return new Promise((resolve, reject) => {
     const target = new URL(urlStr)
     const proxy = new URL(proxyUri)
     const signal = opts?.signal
+    const headerTimeoutMs = Number.isFinite(opts?._headerTimeoutMs) ? opts._headerTimeoutMs : 60_000
+    const bodyIdleMs = opts?._bodyIdleMs ?? 120_000
 
     if (signal?.aborted) return reject(abortError(signal))
 
@@ -181,12 +208,13 @@ export function tunnelHttps(urlStr, opts, proxyUri, timeout = FETCH_TIMEOUT) {
       if (!statusLine.includes("200")) { sock.destroy(); clearTimeout(timer); return reject(new Error(`Proxy CONNECT: ${statusLine}`)) }
       sock.removeAllListeners("data"); clearTimeout(timer)
 
-      const tlsSock = tlsConnect({ socket: sock, servername: target.hostname, rejectUnauthorized: false, timeout })
+      // 安全默认：TLS 全量校验。企业中间人代理场景显式 opts.insecureTls=true 才放行。
+      const tlsSock = tlsConnect({ socket: sock, servername: target.hostname, rejectUnauthorized: opts?.insecureTls !== true })
       if (buf) tlsSock.unshift(Buffer.from(buf))
       tlsSock.on("secureConnect", () => {
         // TLS 之后的请求/响应阶段：abort 交由 streamHttpResponse 接管
         signal?.removeEventListener("abort", onAbort)
-        streamHttpResponse(tlsSock, urlStr, opts, timeout).then(resolve, reject)
+        streamHttpResponse(tlsSock, urlStr, opts, headerTimeoutMs, false, bodyIdleMs).then(resolve, reject)
       })
       tlsSock.on("error", e => { sock.destroy(); reject(e) })
     })
@@ -232,5 +260,7 @@ export async function proxyFetch(urlStr, opts, proxyUri) {
   if (target.protocol === "https:") return tunnelHttps(urlStr, opts, proxyUri)
   // http:// 目标：TCP 直连代理，请求行发绝对 URI（GET http://host/path HTTP/1.1）
   const sock = await tcpConnectProxy(proxyUri, opts?.signal, FETCH_TIMEOUT)
-  return streamHttpResponse(sock, urlStr, opts, FETCH_TIMEOUT, true)
+  const headerTimeoutMs = Number.isFinite(opts?._headerTimeoutMs) ? opts._headerTimeoutMs : FETCH_TIMEOUT
+  const bodyIdleMs = opts?._bodyIdleMs ?? 120_000
+  return streamHttpResponse(sock, urlStr, opts, headerTimeoutMs, true, bodyIdleMs)
 }

package/src/tools/bash.md

@@ -27,9 +27,9 @@ Output format:
 Notes:
 - There is NO TTY — editors, pagers (vim, less), and interactive prompts WILL hang. Always pass non-interactive flags: `git commit -m`, `git --no-pager`, `-y`/`--yes` where applicable
 - The environment sets GIT_PAGER=cat, PAGER=cat, EDITOR=true, TERM=dumb — but still always use non-interactive flags
-- Output is capped at ~200K chars; if you need more, redirect to a file and read it. Truncated output ends with a `[... truncated: N chars omitted]` marker — the missing tail may contain errors.
+- Output is capped at ~200K chars; if you need more, redirect to a file and read it. Truncated output ends with a `[... truncated: N chars omitted]` marker — the missing tail may contain errors, so read the saved log file's tail before trusting success. Use `filter` to narrow instead of hand-piping.
 - Check `[stderr]` for error messages, warnings, and diagnostic output — it is separated from `[stdout]` so you can quickly identify problems.
-- On Windows the shell is **cmd.exe** (NOT Git Bash, NOT PowerShell): `&&`/`||` chaining works, use cmd built-ins (`del`, `dir`, `type`, `findstr`, `tasklist`) and `/dev/null`→`NUL`, `2>/dev/null`→`>nul 2>&1`. Bash-isms (`rm -rf`, `cp -r`, `head`, `$(...)`) FAIL. For complex logic prefer `node -e` over shell gymnastics.
+- On Windows the shell is **cmd.exe** (NOT Git Bash, NOT PowerShell): `&&`/`||` chaining works, use cmd built-ins (`del`, `dir`, `type`, `findstr`, `tasklist`) and `/dev/null`→`NUL`, `2>/dev/null`→`>nul 2>&1`. Bash-isms (`rm -rf`, `cp -r`, `head`, `$(...)`, `${VAR}`, single quotes, `;` separators) FAIL — the tool prepends a hint when it detects POSIX-only syntax, and still executes. For complex logic prefer the execute tool (node) over shell gymnastics.
 - Never use bash to read, copy, or transmit secret files (.env, keys, tokens)
 - Do NOT run destructive commands (rm -rf, force-push, drop table) without explicit user confirmation
 - After commands that change files (git checkout, npm install, etc.), repo_outline and code_search may be stale — re-run them to get current results.

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.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.
 
 - 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,11 +19,13 @@ 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='checkpoint': git snapshots. checkpointAction=list/create/rewind/cat/versions; checkpointId required for rewind/cat.
 
 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
 - workdir: run git in this workspace subdirectory (monorepo / multi-repo). Confined to the workspace. Default: cwd
+- config: (network actions push/fetch/pull/ls-remote) git -c overrides, e.g. ["http.proxy=http://10.2.2.112:3128"] for blocked remotes
 - 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

package/src/tools/git.mjs

@@ -22,9 +22,9 @@ function filterLines(output, filter) {
 /** Run git PRESERVING per-line leading whitespace. runGit trims the WHOLE output, which
  *  strips a porcelain line's leading " " (the unstaged marker) and misclassifies an
  *  unstaged-only first line as staged. status uses this so the staged/unstaged column survives. */
-function runGitRaw(cwd, cmdArgs) {
+function runGitRaw(cwd, cmdArgs, config = []) {
   try {
-    return execFileSync("git", cmdArgs, { cwd, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }).replace(/\r/g, "").replace(/\n$/, "")
+    return execFileSync("git", [...config, ...cmdArgs], { cwd, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }).replace(/\r/g, "").replace(/\n$/, "")
   } catch (e) {
     return String(e.stdout || "").replace(/\r/g, "")
   }
@@ -32,9 +32,9 @@ function runGitRaw(cwd, cmdArgs) {
 
 /** 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. */
-function runGitStrict(cwd, cmdArgs) {
+function runGitStrict(cwd, cmdArgs, config = []) {
   try {
-    const out = execFileSync("git", cmdArgs, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim().replace(/\r/g, "")
+    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() }
@@ -47,6 +47,19 @@ function validateRef(ref, what = "git 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. */
+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
+}
+
 /** True when `abs` is inside `root` (handles `..` and cross-drive, which relative()
  *  returns as an absolute path on Windows). */
 function isInside(root, abs) {
@@ -83,7 +96,7 @@ export const gitTool = {
   parameters: {
     type: "object",
     properties: {
-      action: { type: "string", enum: ["diff", "status", "log", "show", "checkpoint", "add", "rm", "commit", "push", "tag", "branch", "checkout", "restore", "stash", "fetch", "pull", "reset", "revert", "merge", "cherry-pick"], description: "diff / status / log / show / checkpoint / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick" },
+      action: { type: "string", enum: ["diff", "status", "log", "show", "checkpoint", "add", "rm", "commit", "push", "tag", "branch", "checkout", "restore", "stash", "fetch", "pull", "reset", "revert", "merge", "cherry-pick", "ls-remote"], description: "diff / status / log / show / checkpoint / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick / ls-remote" },
       // diff/log params
       staged: { type: "boolean", description: "(diff) Show staged changes instead of working tree" },
       path: { type: "string", description: "(diff/log/add/commit/checkout/restore/checkpoint:cat/versions/rewind/rm) File or directory to scope to / stage / restore" },
@@ -96,6 +109,7 @@ export const gitTool = {
       name: { type: "string", description: "(branch/tag) The branch or tag name (create/delete/switch)" },
       remote: { type: "string", description: "(push/fetch/pull) Remote name (e.g. origin). Default: current upstream" },
       workdir: { type: "string", description: "Run git in this workspace subdirectory (monorepo / multi-repo). Confined to the workspace. Default: cwd" },
+      config: { type: "array", items: { type: "string" }, description: "(network actions: push/fetch/pull/ls-remote) git -c overrides, e.g. [\"http.proxy=http://10.2.2.112:3128\"] for blocked remotes" },
       tags: { type: "boolean", description: "(push) Also push all tags (--tags)" },
       mode: { type: "string", enum: ["soft", "mixed", "hard"], description: "(reset) reset mode — hard snapshots the tree first + needs confirmation" },
       tagAction: { type: "string", enum: ["list", "create", "delete"], description: "(tag) list tags / create one / delete one" },
@@ -112,6 +126,9 @@ export const gitTool = {
     // workdir: run git in a workspace subdirectory (monorepo / multi-repo). Shadow ctx.cwd so
     // every action + snapshotBefore + checkpoint resolves against the workdir, confined to the workspace.
     if (args.workdir) ctx = { ...ctx, cwd: resolveBaseDir(ctx.cwd, args.workdir) }
+    // git -c overrides (proxy etc.) — only network actions need them; passing to every
+    // action would be harmless but noisy. cfgArgs stays [] for local ops.
+    const cfgArgs = gitConfigArgs(args.config)
     switch (args.action) {
       case "diff": {
         const ref = args.ref ?? "HEAD"
@@ -195,9 +212,19 @@ export const gitTool = {
         if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
         if (args.ref) for (const r of args.ref.split(/\s+/).filter(Boolean)) cmdArgs.push(validateRef(r, "ref"))
         if (args.tags) cmdArgs.push("--tags")
-        const r = runGitStrict(ctx.cwd, cmdArgs)
+        const r = runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
         return r.ok ? truncate(r.out || "(push complete — no output)") : truncate(`git push failed: ${r.err || r.out || "(no output)"}`)
       }
+      case "ls-remote": {
+        // Lightweight remote-ref check (which refs a remote has) — network action,
+        // read-only, no snapshot. Config plumbing for blocked/gated remotes.
+        const cmdArgs = ["ls-remote"]
+        if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
+        if (args.ref) for (const r of args.ref.split(/\s+/).filter(Boolean)) cmdArgs.push(validateRef(r, "ref"))
+        const out = runGit(ctx.cwd, cmdArgs, cfgArgs)
+        if (!out) return "(no refs / remote unreachable)"
+        return truncate(filterLines(out, args.filter))
+      }
       case "add": {
         // Granular staging: stage `path` when given, else all changes (add -A).
         const cmdArgs = args.path ? ["add", "--", args.path] : ["add", "-A"]
@@ -293,14 +320,14 @@ export const gitTool = {
         const cmdArgs = ["fetch"]
         if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
         if (args.ref) cmdArgs.push(validateRef(args.ref, "ref"))
-        const r = runGitStrict(ctx.cwd, cmdArgs)
+        const r = runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
         return r.ok ? truncate(r.out || "(fetch complete — no output)") : truncate(`git fetch failed: ${r.err || r.out}`)
       }
       case "pull": {
         const cmdArgs = ["pull"]
         if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
         if (args.ref) cmdArgs.push(validateRef(args.ref, "ref"))
-        const r = runGitStrict(ctx.cwd, cmdArgs)
+        const r = runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
         return r.ok ? truncate(r.out || "(pull complete — no output)") : truncate(`git pull failed: ${r.err || r.out}`)
       }
       case "reset": {