thincoder 0.12.60 → 0.12.62

package/src/tools/{system.mjs → bash.mjs}

@@ -4,25 +4,12 @@ import {
   truncate,
   makeDecoder,
   BASH_TIMEOUT_MS,
-  IGNORED_DIRS,
-  resolveInCwd,
-  globToRegex,
-  splitGlobPatterns,
-  compileGlobMatchers,
-  normalizeEOL,
 } from "./shared.mjs";
 import { spawn, execFileSync } from "node:child_process";
-import { readFile, readdir, stat, lstat } from "node:fs/promises";
-import { join } from "node:path";
 
 /** Maximum buffer size per stream (stdout / stderr) before truncation */
 const MAX_STREAM_BUF = 2_000_000
 
-/** Escape a string for literal regex matching (grep literal=true). */
-function escapeRegExp(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-}
-
 /** Keep only output lines matching a regex (bash filter, case-insensitive). */
 function applyLineFilter(output, filter) {
   let re
@@ -85,13 +72,6 @@ function killProcessTree(child) {
   }
 }
 
-/**
- * Run a bash command: spawn, stream stdout/stderr with buffering and decoding,
- * enforce timeout and signal abort, return formatted result.
- *
- * Returns a promise that resolves to the formatted output string (stdout + stderr + status + truncation note).
- */
-
 /**
  * Detect destructive git commands and auto-snapshot BEFORE execution.
  * The scenario: the model writes uncommitted code, then (after breaking things)
@@ -129,6 +109,12 @@ async function gitGuardSnapshot(command, cwd) {
   }
 }
 
+/**
+ * Run a bash command: spawn, stream stdout/stderr with buffering and decoding,
+ * enforce timeout and signal abort, return formatted result.
+ *
+ * Returns a promise that resolves to the formatted output string (stdout + stderr + status + truncation note).
+ */
 function runBash(command, cwd, { timeout, signal, onOutput, shell }) {
   return new Promise((resolve) => {
     // Windows + default cmd: force UTF-8 code page for this child process (each spawn
@@ -280,226 +266,3 @@ export const bashTool = {
     return hint ? `${hint}\n${body}` : body
   },
 }
-
-// ---------------------------------------------------------------- glob
-
-export const globTool = {
-  name: "glob",
-  description: DESC("glob"),
-  parameters: {
-    type: "object",
-    properties: {
-      pattern: { type: "string", description: "Glob pattern — supports **, *, ?, [..], {a,b} braces, and space-separated exclusion (\"**/*.js !test/**\")" },
-      path: { type: "string", description: "Directory to search in (default cwd)" },
-    },
-    required: ["pattern"],
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    const base = resolveInCwd(ctx, args.path ?? ".")
-    // §17 调用侧拆分（评审 #5 职责分层）：空格分隔 include !exclude 多模式在这里拆；
-    // globToRegex 只收单个模式（数组由 compileGlobMatchers 收）。
-    let match
-    try {
-      const parts = splitGlobPatterns(args.pattern)
-      if (parts.length === 0) return "Error: pattern is required"
-      match = compileGlobMatchers(parts).test
-    } catch (e) {
-      return `glob error: invalid pattern "${args.pattern}": ${e.message}`
-    }
-    const results = []
-    for await (const relPath of walkFiles(base)) {
-      if (match(relPath)) {
-        results.push(relPath)
-        if (results.length >= 1000) break
-      }
-    }
-    if (results.length === 0) return "(no matches)"
-    return truncate(results.sort().join("\n"))
-  },
-}
-
-/** Recursively traverse files, yield relative paths (skip IGNORED_DIRS) */
-async function* walkFiles(dir, rel = "") {
-  let entries
-  try {
-    entries = await readdir(dir, { withFileTypes: true })
-  } catch {
-    return
-  }
-  for (const e of entries) {
-    // Skip ignored dirs AND symbolic links (symlinks to directories would cause infinite loops)
-    if (e.isSymbolicLink()) continue
-    if (e.isDirectory() && IGNORED_DIRS.has(e.name)) continue
-    const relPath = rel ? `${rel}/${e.name}` : e.name
-    if (e.isDirectory()) {
-      yield* walkFiles(join(dir, e.name), relPath)
-    } else {
-      yield relPath
-    }
-  }
-}
-
-/** Glob to regex: **\/ matches zero or more directory levels, ** crosses directories, * within segment, ? single char within segment */
-
-// ---------------------------------------------------------------- grep
-
-export const grepTool = {
-  name: "grep",
-  description: DESC("grep"),
-  parameters: {
-    type: "object",
-    properties: {
-      pattern: { type: "string", description: "Regular expression, or a literal string when literal=true" },
-      path: { type: "string", description: "Directory or file to search (default cwd)" },
-      glob: { type: "string", description: "Only search files matching this glob — supports **, *, ?, [..], {a,b} braces and space-separated exclusion (\"**/*.js !test/**\")" },
-      ignoreCase: { type: "boolean", description: "Case-insensitive match (default false)" },
-      literal: { type: "boolean", description: "Literal string match — no regex interpretation (default false)" },
-      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"],
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    const base = resolveInCwd(ctx, args.path ?? ".")
-    let regex
-    try {
-      const pat = args.literal ? escapeRegExp(String(args.pattern)) : args.pattern
-      regex = new RegExp(pat, args.ignoreCase ? "i" : "")
-    } catch (e) {
-      throw new Error(`grep pattern /${args.pattern}/ is not a valid regex: ${e.message}`, { cause: e })
-    }
-    // §17 调用侧拆分：glob 参数支持空格分隔 include !exclude 多模式（include/exclude 求交）。
-    let fileTest = null
-    if (args.glob) {
-      try {
-        const parts = splitGlobPatterns(args.glob)
-        if (parts.length > 0) fileTest = compileGlobMatchers(parts).test
-      } catch (e) {
-        throw new Error(`grep glob /${args.glob}/ is invalid: ${e.message}`, { cause: e })
-      }
-    }
-    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[] (cached only when context lines requested)
-
-    async function search(file) {
-      let content
-      try {
-        // Large file guard: skip files over 10MB to prevent OOM
-        const fst = await stat(file)
-        if (fst.size > 10_000_000) return
-        content = normalizeEOL(await readFile(file, "utf8"))
-      } catch {
-        return // Skip unreadable files; binary files will be read as UTF-8 and searched (may produce garbled matches)
-      }
-      const lines = content.split("\n")
-      if (wantCtx) fileLines.set(file, lines)
-      for (let i = 0; i < lines.length; i++) {
-        if (regex.test(lines[i])) {
-          hits.push({ file, line: i + 1, text: lines[i] })
-          if (hits.length >= 200) return
-        }
-      }
-    }
-
-    async function walk(target, rel) {
-      if (hits.length >= 200) return
-      // Use lstat to avoid following symlinks — prevents ./evil → /etc from making grep scan the entire system
-      let s
-      try { s = await lstat(target) } catch { return }
-      if (!s.isDirectory()) {
-        // rel 为相对搜索基的路径（排除前缀如 !test/** 必须按目录路径作用——不能用裸文件名）；
-        // 单文件目标（path 指向文件）时 rel 为空 → 退化为按文件名过滤（既有语义）。
-        if (!fileTest || fileTest(rel || target.split(/[\\/]/).pop())) await search(target)
-        return
-      }
-      let entries
-      try {
-        entries = await readdir(target, { withFileTypes: true })
-      } catch {
-        return
-      }
-      for (const e of entries) {
-        if (e.isDirectory() && IGNORED_DIRS.has(e.name)) continue
-        await walk(join(target, e.name), rel ? `${rel}/${e.name}` : e.name)
-      }
-    }
-
-    await walk(base, "")
-    if (hits.length === 0) return "(no matches)"
-
-    // No context: keep original path:line: content format
-    if (!wantCtx) {
-      return truncate(hits.map((h) => `${h.file}:${h.line}: ${h.text}`).join("\n"))
-    }
-
-    // With context: matching lines use ':', context lines use '-' (like ripgrep); overlapping ranges in same file are merged and de-duplicated
-    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"))
-  },
-}
-
-// ---------------------------------------------------------------- websearch
-
-export const lsTool = {
-  name: "ls",
-  description: DESC("ls"),
-  parameters: {
-    type: "object",
-    properties: {
-      path: { type: "string", description: "Directory path (default cwd)" },
-      filter: { type: "string", description: "Only list entries matching this glob (e.g. '*.mjs', '*test*')" },
-    },
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    const abs = resolveInCwd(ctx, args.path ?? ".")
-    const filterRe = args.filter ? globToRegex(args.filter) : null
-    let entries
-    try {
-      entries = await readdir(abs, { withFileTypes: true })
-    } catch (e) {
-      if (e.code === "ENOENT" || e.code === "ENOTDIR") throw new Error(`ls: ${args.path ?? "."} — ${e.code === "ENOTDIR" ? "not a directory" : "not found"}`, { cause: e })
-      throw e
-    }
-    const rows = await Promise.all(
-      entries
-        .filter((e) => !filterRe || filterRe.test(e.name))
-        .slice(0, 500)
-        .map(async (e) => {
-        const s = await stat(join(abs, e.name)).catch(() => null)
-        const isDir = e.isDirectory()
-        return {
-          dir: isDir,
-          name: e.name + (isDir ? "/" : ""),
-          size: s?.size ?? 0,
-          mtime: s ? s.mtime.toISOString().slice(0, 16).replace("T", " ") : "?",
-        }
-      }),
-    )
-    rows.sort((a, b) => (a.dir === b.dir ? a.name.localeCompare(b.name) : a.dir ? -1 : 1))
-    if (rows.length === 0) return "(no entries)"
-    const out = rows.map((r) => `${r.dir ? "d" : "-"}  ${r.name.padEnd(40)} ${String(r.size).padStart(10)}  ${r.mtime}`)
-    return truncate(out.join("\n"))
-  },
-}

package/src/tools/file.mjs

@@ -21,6 +21,10 @@ import { join, relative, dirname } from "node:path";
 
 const MAX_FILE_READ_BYTES = 10_000_000
 const MAX_IMAGE_BYTES = 15_000_000
+// DUAL-END-TRUNCATION (F-1, C 方案——2026-09-09)：read 双端尾行数——窗口截断大文件时
+// 返回 头 N 行（N = 请求窗口，默认 MAX_READ_LINES）+ 省略注 + 尾 M 行（本常量）。M 与
+// 窗口合计（2500 行）为"整读上限"——K=0（尾区与窗口相接）时整印剩余、不产生假省略注。
+export const READ_TAIL_LINES = 500
 
 // ────────────────────────────────────────
 // Dirty-file tracking (read-before-insert guard)
@@ -95,17 +99,30 @@ export const readTool = {
     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)
-    const slice = lines.slice(offset - 1, offset - 1 + limit)
-    const numbered = slice.map((l, i) => {
-      const ln = offset + i
-      if (args.hashes) {
-        const h = createHash("sha256").update(l).digest("hex").slice(0, 12)
-        return `${ln}\t[${h}] ${l}`
-      }
+    const windowEnd = offset - 1 + limit // index just past the requested window
+    const render = (slice, startLn) => slice.map((l, i) => {
+      const ln = startLn + i
+      if (args.hashes) return `${ln}\t[${hashLine(l)}] ${l}`
       return `${ln}\t${l}`
     }).join("\n")
-    const suffix = offset - 1 + limit < lines.length ? `\n... (${lines.length} lines total, use offset to continue)` : ""
-    return truncate(numbered + suffix)
+    // DUAL-END-TRUNCATION (F-1, C 方案——DUAL-END-TRUNCATION.md 2026-09-09):
+    // 大文件（> MAX_READ_LINES 行）窗口截断时返回 头（请求窗口）+ 中段省略注 +
+    // 文件真实尾部（末 READ_TAIL_LINES 行——现尾注升级为真实尾行内容——offload 产物
+    // 的尾端结论可见）。≤ 阈值文件任何窗口走旧头向路径（字节零变化）；窗口覆盖全文件
+    // 也走旧路径。与 hashes 模式照常交互（头尾行 hash 照算）。
+    if (windowEnd >= lines.length || lines.length <= MAX_READ_LINES) {
+      const suffix = windowEnd < lines.length ? `\n... (${lines.length} lines total, use offset to continue)` : ""
+      return truncate(render(lines.slice(offset - 1, windowEnd), offset) + suffix)
+    }
+    const head = render(lines.slice(offset - 1, windowEnd), offset)
+    // 尾区 = 文件末 READ_TAIL_LINES 行；尾区起点落在窗口内（重叠）→ 尾区从窗口后开始
+    // —— 任何行不打印两次；剩余全被覆盖（K=0）→ 整印余段且无假省略注。
+    const tailStart = Math.max(windowEnd, lines.length - READ_TAIL_LINES)
+    const middle = tailStart - windowEnd
+    const tail = render(lines.slice(tailStart), tailStart + 1)
+    return middle > 0
+      ? `${head}\n…(truncated: ${middle} lines in middle, use offset to continue)\n${tail}`
+      : `${head}\n${tail}`
   },
 }
 
@@ -145,11 +162,14 @@ export const readImageTool = {
 
     // Vision capability gate: injecting an image into a text-only model's history poisons the whole
     // conversation (every subsequent request 400s on the image part). Refuse before reading the file.
+    // F-3（IMAGE-DOWNGRADE-VISION——2026-09-09）：软引导句逐字锚（设计档照抄——CLI 无 extension
+    // 式自动降级——模型收到错误后自选 spawn 视觉渠道子代理路径）。
     const model = ctx.agent?.provider?.model
     if (model && !specForModel(model).multimodal) {
       throw new Error(
         `Model "${model}" does not support image input — read_image is unavailable with this provider. ` +
-        `Verify visual output programmatically (file size, dimensions, pixel checks via code) or ask the user to switch to a vision-capable provider.`
+        `Verify visual output programmatically (file size, dimensions, pixel checks via code) or ask the user to switch to a vision-capable provider.\n` +
+        `模型不支持图像——可 spawn 一个视觉模型子代理（subagent model 参数指视觉渠道）用 read_image 读图`
       )
     }
     const mime = IMAGE_EXTENSIONS[ext]

package/src/tools/git.md

@@ -7,7 +7,7 @@ Run a git command. Only works inside a git repository.
 - action='log': recent commits. count (default 10), oneline=true compact, path=<file> for one file's history.
 - action='show': a commit's details (--stat). ref=<ref> (default HEAD).
 - action='add': stage files — path=<file> (granular) or all changes when path omitted.
-- action='commit': stage + commit. message required; path=<file> for granular staging.
+- action='commit': commit. message required; path=<file> → `git commit --only <paths>` — commits those files' working-tree content only (other staged batches are NOT mixed in — atomic); without path → add -A + full commit. New (untracked) files aren't committable by path alone — `git add` them first (staging extra is safe: --only still commits only the listed files).
 - action='rm': untrack a file/dir (git rm --cached, kept on disk). path required.
 - action='push'/'fetch'/'pull': sync with remote. remote=<origin>, ref=<branch or tag> (space-separated for multiple), tags=true for --tags.
 - action='tag': manage tags. tagAction=list (optional filter) / create (name, optional ref) / delete (name; snapshots first).

package/src/tools/git.mjs

@@ -149,14 +149,22 @@ export const gitTool = {
       }
       case "commit": {
         if (!args.message) return "Error: commit requires message"
-        // Granular staging when path given (only stage these); otherwise stage all (add -A).
-        // 多路径：空格分隔（ref 先例——2026-09-05 发版痛点）
-        const staged = args.path ? args.path.split(/\s+/).filter(Boolean) : null
-        const add = runGitStrict(ctx.cwd, staged?.length ? ["add", "--", ...staged] : ["add", "-A"])
-        if (!add.ok) return truncate(`git add failed: ${add.err || add.out || "(no output)"}`)
-        const commit = runGitStrict(ctx.cwd, ["commit", "-m", args.message])
+        // F-3 (QUICKFIX-BATCH-2)：path 给定（含空串——空/空白 trim 后空一律明确错误，绝不
+        // 回落 add -A）→ git commit --only <paths>——从工作树取列文件提交（忽略索引他批——
+        // 原子——不再先 add）。空格分隔唯一形态（含空格文件名不支持）。无 path（缺省）→ add
+        // -A 全量（单代理语义保留）。
         const parts = []
-        if (add.out) parts.push(add.out)
+        let commit
+        if (args.path !== undefined && args.path !== null) {
+          const trimmed = args.path.trim()
+          if (!trimmed) return "Error: commit path is empty/whitespace — give at least one file path (space-separated)"
+          commit = runGitStrict(ctx.cwd, ["commit", "--only", "-m", args.message, "--", ...trimmed.split(/\s+/)])
+        } else {
+          const add = runGitStrict(ctx.cwd, ["add", "-A"])
+          if (!add.ok) return truncate(`git add failed: ${add.err || add.out || "(no output)"}`)
+          if (add.out) parts.push(add.out)
+          commit = runGitStrict(ctx.cwd, ["commit", "-m", args.message])
+        }
         if (commit.ok) {
           if (commit.out) parts.push(commit.out)
           // F6: commit = new safety baseline — clear this project's checkpoints
@@ -346,30 +354,3 @@ export const gitTool = {
   },
 }
 
-// ---------------------------------------------------------------- question
-
-export const questionTool = {
-  name: "question",
-  description: DESC("question"),
-  parameters: {
-    type: "object",
-    properties: {
-      question: { type: "string", description: "The question to ask the user" },
-      options: {
-        type: "array",
-        items: { type: "string" },
-        description: "Single-choice options for the user to pick from (optional)",
-      },
-    },
-    required: ["question"],
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    if (!ctx.onQuestion) throw new Error("question tool not supported in this context (no UI to ask)")
-    // §22 D-Q3 机械限制（2026-09-06 用户裁定：100 字符 / 4 条——超限拒绝回模型，不弹卡、不调 onQuestion）
-    if (args.question.length > 100) return "(error: question too long (>100 chars) — ask ONE short question; background belongs in your normal reply text)"
-    if (Array.isArray(args.options) && args.options.length > 4) return "(error: too many options (>4) — offer at most 4 plain-string options)"
-    return ctx.onQuestion(args.question, args.options ?? [])
-  },
-}
-

package/src/tools/index.mjs

@@ -3,9 +3,11 @@ export { toOpenAISchema } from "./shared.mjs";
 
 import { readTool, writeTool, editTool, insertAfterTool, readImageTool, hashlineEditTool } from "./file.mjs";
 import { applyPatchTool, deleteTool } from "./patch.mjs";
-import { bashTool, globTool, grepTool, lsTool } from "./system.mjs";
+import { bashTool } from "./bash.mjs";
+import { globTool, grepTool, lsTool } from "./search.mjs";
 import { websearchTool, fetchTool } from "./web.mjs";
-import { gitTool, questionTool } from "./git.mjs";
+import { gitTool } from "./git.mjs";
+import { questionTool } from "./question.mjs";
 import { checklistTool } from "./checklist.mjs";
 import { lintTool } from "./linter.mjs";
 import { lspTool } from "./lsp.mjs";

package/src/tools/ops.mjs

@@ -176,14 +176,27 @@ function asyncEntryDone(agent, id) {
   return entry.done === true || entry.status === "done"
 }
 
-/** Any async entry matching pred that is still running/queued (not done). */
-function hasRunningAsync(agent, pred) {
-  for (const e of asyncPool(agent).values()) {
+/** 评审池双载体（第 10 批 §18.3 #2）：agent ∪ history——未初始化的载体不进集合。 */
+function advisorPools(agent) {
+  return [agent?._asyncAdvisors, agent?.history?._asyncAdvisors].filter((m) => m instanceof Map)
+}
+
+/** Any entry matching pred that is still running/queued (not done) — in the given pool. */
+function hasRunningIn(pool, pred) {
+  for (const e of pool?.values() ?? []) {
     if (pred(e) && !(e.done === true || e.status === "done")) return true
   }
   return false
 }
 
+/** "advisor settled" 真判据（第 10 批 §18.3 #2 修正）：**评审池真实态**——双载体
+ *  （agent._asyncAdvisors ∪ history._asyncAdvisors）无 running/queued 条目（与 §11.2 的
+ *  未决评审判定 advisorReviewPending 同源语义）。修前读**子代理池**的 role==="advisor"
+ *  条目——评审条目只在 _asyncAdvisors → 恒无命中 → 恒真 0ms 秒过（用户实证）。 */
+function advisorSettled(agent) {
+  return !advisorPools(agent).some((pool) => hasRunningIn(pool, (e) => e.status === "running" || e.status === "queued"))
+}
+
 /** "consult done" — every consult session has drained (pending 0) or was
  *  explicitly stopped (its children were aborted). No sessions → true (vacuously). */
 function consultAllDone(agent) {
@@ -221,10 +234,10 @@ export async function evaluateWaitForCondition(condition, ctx) {
   const agent = ctx?.agent
   switch (parsed.kind) {
     case "advisor":
-      // Advisor reviews run as blocking tool calls (runAdvisorReview) or as
-      // advisor-role async children — "settled" = no advisor-role entry still
-      // running/queued in the async pool.
-      return !hasRunningAsync(agent, (e) => e.role === "advisor")
+      // 第 10 批修正（§18.3 #2——修前恒真 0ms 秒过）：判据 = 评审池真实态（双载体）——
+      // 不再读子代理池的 role==="advisor" 条目（该池永无此类条目）；语义与 §11.2 未决
+      // 评审判定同源（advisorReviewPending）。
+      return advisorSettled(agent)
     case "subagent":
       return asyncEntryDone(agent, parsed.arg)
     case "consult":

package/src/tools/question.md

@@ -8,6 +8,7 @@ Notes:
 - The agent loop pauses until the user answers
 - The answer is injected as the next user message
 - Returns the user's answer — the chosen option or free text — as the next message; the loop resumes when it arrives.
+- Availability: this tool needs an interactive UI — in contexts without one (headless runs, subagent children) it returns an error instead of asking; put the question in your reply text instead.
 - Use sparingly — prefer making reasonable decisions when possible
 - Ask ONE question per call — never bundle multiple sub-questions into one question string; ask the next one after the answer arrives.
 - Keep the question text short — one or two sentences. Background, context, and analysis belong in your normal reply text, NOT in the question.

package/src/tools/question.mjs

@@ -0,0 +1,26 @@
+import { DESC } from "./shared.mjs";
+
+export const questionTool = {
+  name: "question",
+  description: DESC("question"),
+  parameters: {
+    type: "object",
+    properties: {
+      question: { type: "string", description: "The question to ask the user" },
+      options: {
+        type: "array",
+        items: { type: "string" },
+        description: "Single-choice options for the user to pick from (optional)",
+      },
+    },
+    required: ["question"],
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    if (!ctx.onQuestion) throw new Error("question tool not supported in this context (no UI to ask)")
+    // §22 D-Q3 机械限制（2026-09-06 用户裁定：100 字符 / 4 条——超限拒绝回模型，不弹卡、不调 onQuestion）
+    if (args.question.length > 100) return "(error: question too long (>100 chars) — ask ONE short question; background belongs in your normal reply text)"
+    if (Array.isArray(args.options) && args.options.length > 4) return "(error: too many options (>4) — offer at most 4 plain-string options)"
+    return ctx.onQuestion(args.question, args.options ?? [])
+  },
+}

package/src/tools/read.md

@@ -11,7 +11,7 @@ Read a text file. Returns numbered lines. Use offset/limit to page large files.
 Parameters:
 - path (required): File path, relative to cwd or absolute (alias: filePath)
 - offset: 1-based line number to start reading from
-- limit: Max lines to return (default 2000)
+- limit: Max lines to return (default 2000) — windows over files beyond that return head + `…(truncated: K lines in middle, use offset to continue)` + the file's real tail lines, so the file end is never hidden
 - hashes: Include SHA256 content hashes per line (for hashline_edit). Set true before using hashline_edit.
 
 Notes:

package/src/tools/read_image.md

@@ -5,4 +5,4 @@ Parameters:
 
 Notes:
 - Raster formats only (png/jpg/gif/webp): no mainstream vision API (Kimi, Anthropic, OpenAI, Gemini) accepts svg or bmp, and an unsupported image part in history makes every subsequent request fail with 400. svg files are returned as text source instead (readable by any model); bmp is rejected — convert to PNG first.
-- This tool only works with models that support vision/image input (Kimi K3, Qwen3.8, MiniMax M3, GLM-5.3-Flash). Pure text models (DeepSeek V4, GLM-5) will receive an error — except svg, which needs no vision support since it is read as text.
+- This tool only works with models that support vision/image input (capability is spec-driven — the model spec decides, not a hardcoded list). Models without vision support will receive an error — except svg, which needs no vision support since it is read as text.