thincoder 0.12.59 → 0.12.61

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]
@@ -217,21 +237,26 @@ export const editTool = {
     type: "object",
     properties: {
       path: { type: "string", description: "File path — single form: required; with the edits array: optional top-level default for entries without their own path" },
-      old_string: { type: "string", description: "Exact text to replace" },
-      new_string: { type: "string", description: "Replacement text" },
+      old_string: { type: "string", description: "Exact text to replace (tolerant matching: exact → whitespace-only variant → fuzzy match at ≥90% line equality after whitespace/indent/quote normalization). Mutually exclusive with line/startLine/endLine" },
+      new_string: { type: "string", description: "Replacement text — content-based edits require it (empty is an explicit error); with line-based targeting (line/startLine/endLine) give it to replace the line/range, or OMIT it to delete (an explicit empty string is an error — omission is the delete signal)" },
+      line: { type: "integer", description: "1-based line number — replace that single line with new_string, or OMIT new_string to DELETE the line; no old_string needed (mutually exclusive with old_string and startLine/endLine)" },
+      startLine: { type: "integer", description: "1-based first line of the range to replace with new_string (inclusive — requires endLine; mutually exclusive with old_string); OMIT new_string to DELETE the range" },
+      endLine: { type: "integer", description: "1-based last line of the range to replace with new_string (inclusive — requires startLine; mutually exclusive with old_string); OMIT new_string to DELETE the range" },
       replace_all: { type: "boolean", description: "Replace all occurrences (default false)" },
       edits: {
         type: "array",
-        description: "Batch form — multiple edits in ONE call, atomic (any failure writes nothing; same-file entries apply serially, each based on the previous result). Use it for multiple changes to the same file AND for independent changes across multiple files — prefer one batched call over N single edits. A top-level path is allowed — it defaults entries without their own path (entry paths win). Mutually exclusive with top-level old_string/new_string — provide each change's old/new inside its edits entry.",
+        description: "Batch form — multiple edits in ONE call, atomic (any failure writes nothing; same-file entries apply serially, each based on the previous result). Use it for multiple changes to the same file AND for independent changes across multiple files — prefer one batched call over N single edits. A top-level path is allowed — it defaults entries without their own path (entry paths win). Mutually exclusive with top-level old_string/new_string/line/startLine/endLine — provide each change's targeting (old_string, or line / startLine+endLine) inside its edits entry; new_string replaces when given, and line-targeted entries may omit it to DELETE the line/range.",
         items: {
           type: "object",
           properties: {
             path: { type: "string" },
             old_string: { type: "string" },
             new_string: { type: "string" },
+            line: { type: "integer" },
+            startLine: { type: "integer" },
+            endLine: { type: "integer" },
             replace_all: { type: "boolean" },
           },
-          required: ["old_string", "new_string"],
         },
       },
     },
@@ -253,8 +278,8 @@ export const editTool = {
     // （应用逻辑在 edit-batch.mjs——2026-09-01 拆出，500 行硬限，先例 git-ext.mjs）
     if (args.edits) return applyEditBatch(args, ctx)
 
-    // 单文件（现状路径）——执行体整段迁出至 edit-diff.mjs（TOOLS.md §15 D15.1——
-    // 行级 LCS 判定：零重叠→插入 / 一般 diff→LCS / 空 new→显式报错）
+    // 单文件（现状路径）——执行体整段迁出至 edit-diff.mjs（EDIT.md §6——
+    // 行级 LCS 判定：零重叠→替换即删 / 一般 diff→LCS / 空 new→显式报错）
     return runSingleEdit(args, ctx)
   },
 }

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

@@ -42,7 +42,7 @@ export const gitTool = {
       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", "clone", "init", "rebase", "remote", "clean", "switch", "apply", "worktree", "archive", "blame", "mv"], description: "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 — clean/rebase 操作前自动快照，checkpointAction=rewind 恢复" },
       // 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/apply/archive/blame/mv/worktree) File or directory to scope to / stage / restore（checkout/restore 操作前自动快照，checkpointAction=rewind 恢复）" },
+      path: { type: "string", description: "(diff/log/add/commit/checkout/restore/checkpoint:cat/versions/rewind/rm/apply/archive/blame/mv/worktree) File or directory to scope to / stage / restore（checkout/restore 操作前自动快照，checkpointAction=rewind 恢复）— add/rm/commit: space-separated for multiple（git add a b c——2026-09-05 发版痛点；含空格的文件名会被按多路径拆分——请用 bash git 处理）" },
       ref: { type: "string", description: "(diff/show/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)" },
       count: { type: "number", description: "(log) Number of commits (default 10)" },
       oneline: { type: "boolean", description: "(log) One-line-per-commit format" },
@@ -143,17 +143,28 @@ export const gitTool = {
       }
       case "rm": {
         if (!args.path) return "Error: rm requires path (the file/directory to untrack, relative to repo root)"
-        const r = runGitStrict(ctx.cwd, ["rm", "--cached", "-r", "--", args.path])
-        return r.ok ? truncate(r.out || `Untracked ${args.path} (kept on disk)`) : truncate(`git rm failed: ${r.err || r.out}`)
+        const paths = args.path.split(/\s+/).filter(Boolean)
+        const r = runGitStrict(ctx.cwd, ["rm", "--cached", "-r", "--", ...paths])
+        return r.ok ? truncate(r.out || `Untracked ${paths.join(" ")} (kept on disk)`) : truncate(`git rm failed: ${r.err || r.out}`)
       }
       case "commit": {
         if (!args.message) return "Error: commit requires message"
-        // Granular staging when path given (only stage these); otherwise stage all (add -A).
-        const add = runGitStrict(ctx.cwd, args.path ? ["add", "--", args.path] : ["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
@@ -189,9 +200,11 @@ export const gitTool = {
       }
       case "add": {
         // Granular staging: stage `path` when given, else all changes (add -A).
-        const cmdArgs = args.path ? ["add", "--", args.path] : ["add", "-A"]
+        // 多路径：空格分隔（ref 先例 L175——2026-09-05 发版痛点——git add 单路径被迫 N 次调用）
+        const paths = args.path ? args.path.split(/\s+/).filter(Boolean) : null
+        const cmdArgs = paths?.length ? ["add", "--", ...paths] : ["add", "-A"]
         const r = runGitStrict(ctx.cwd, cmdArgs)
-        return r.ok ? truncate(r.out || `Staged ${args.path || "all changes"}`) : truncate(`git add failed: ${r.err || r.out}`)
+        return r.ok ? truncate(r.out || `Staged ${paths?.join(" ") || "all changes"}`) : truncate(`git add failed: ${r.err || r.out}`)
       }
       case "tag": {
         const sub = args.tagAction
@@ -341,27 +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)")
-    return ctx.onQuestion(args.question, args.options ?? [])
-  },
-}
-

package/src/tools/glob-dialect.mjs

@@ -0,0 +1,130 @@
+/**
+ * glob-dialect.mjs — glob 方言（TOOLS.md §17 — 2026-09-06）单一权威模块（CLI）。
+ *
+ * `{a,b}` brace expansion is handled BEFORE the sentinel/escape flow (braces must
+ * not be literal-escaped — a bare "star-star slash star .{js,txt}" pattern
+ * previously escaped to a literal that silently matched nothing). Unsupported
+ * extglob dialects (`?(x)`/`@(a|b)`/`+(x)`/`*(x)`/`!(x)`) and malformed braces
+ * (empty `{}`, unclosed `{`, nested `{a,{b,c}}`) are EXPLICIT errors — never a
+ * silent no-match. Exclude prefixes (`!pattern`) are the CALLER's job: the
+ * glob/grep tools whitespace-split the pattern expression (splitGlobPatterns —
+ * never inside a brace group) and pass the parts to compileGlobMatchers, which
+ * intersects includes and excludes.
+ *
+ * Extracted from shared.mjs (2026-09-06 advisor #5 — shared.mjs exceeded the
+ * 500-line cap after §17); shared.mjs re-exports these symbols so all existing
+ * importers (system.mjs / ls filter / tests) keep their import paths.
+ */
+
+const BRACE_OPEN = "\u0003", BRACE_SEP = "\u0004", BRACE_CLOSE = "\u0005"
+const EXT_GLOB_RE = /[@?+*!]\(/
+
+export const GLOB_EXTGLOB_ERROR =
+  "glob syntax error: unsupported extglob syntax — ?(x)/@(a|b)/+(x)/*(x)/!(x) are not supported; use {a,b} brace expansion or multiple space-separated patterns instead"
+export const GLOB_EMPTY_BRACE_ERROR =
+  'glob syntax error: empty brace group "{}" — put at least one alternative between the braces (e.g. {js,txt})'
+export const GLOB_UNCLOSED_BRACE_ERROR =
+  'glob syntax error: unclosed brace group — add a matching "}" (e.g. {js,txt})'
+export const GLOB_NESTED_BRACE_ERROR =
+  "glob syntax error: nested brace groups are not supported (e.g. {a,{b,c}}) — use a flat alternative list (e.g. {a,b,c})"
+
+function assertNoExtglob(pattern) {
+  if (EXT_GLOB_RE.test(pattern)) throw new Error(GLOB_EXTGLOB_ERROR)
+}
+
+/** Replace every {a,b,c} group with placeholder alternation markers. Runs BEFORE
+ *  the sentinel/escape flow so the inserted alternation survives literal escaping. */
+function expandBraces(pattern) {
+  for (;;) {
+    const open = pattern.indexOf("{")
+    if (open === -1) return pattern
+    let close = -1
+    for (let j = open + 1; j < pattern.length; j++) {
+      if (pattern[j] === "{") throw new Error(GLOB_NESTED_BRACE_ERROR)
+      if (pattern[j] === "}") { close = j; break }
+    }
+    if (close === -1) throw new Error(GLOB_UNCLOSED_BRACE_ERROR)
+    const inner = pattern.slice(open + 1, close)
+    if (inner === "") throw new Error(GLOB_EMPTY_BRACE_ERROR)
+    const alts = inner.split(",").map((a) => a.trim())
+    pattern = pattern.slice(0, open) + BRACE_OPEN + alts.join(BRACE_SEP) + BRACE_CLOSE + pattern.slice(close + 1)
+  }
+}
+
+/** Convert a single glob pattern to a RegExp (anchored full match). Supports the
+ *  recursive "star-star" forms, single-star, "?", "[..]" character classes and
+ *  {a,b} brace expansion. Malformed braces and unsupported extglob syntax throw
+ *  explicit errors (no silent mismatch). */
+export function globToRegex(pattern) {
+  pattern = String(pattern)
+  assertNoExtglob(pattern)
+  pattern = expandBraces(pattern)
+  // Sentinel chars: \u0001/\u0002 never appear in real glob patterns (they
+  // come from model output or the filesystem) — safe as **/ and ** placeholders.
+  const DS = "\u0001", DP = "\u0002"
+  const escaped = pattern
+    .replace(/\*\*\//g, DS).replace(/\*\*/g, DP)
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")
+    .replace(new RegExp(DS, "g"), "(?:.+/)?")
+    .replace(new RegExp(DP, "g"), ".*")
+    .replace(new RegExp(BRACE_OPEN, "g"), "(?:")
+    .replace(new RegExp(BRACE_SEP, "g"), "|")
+    .replace(new RegExp(BRACE_CLOSE, "g"), ")")
+  return new RegExp(`^${escaped}$`)
+}
+
+/** Whitespace-split a glob expression into parts WITHOUT splitting inside {a,b}
+ *  brace groups and WITHOUT splitting literal spaces inside a single pattern
+ *  (2026-09-06 audit F1 / advisor #4): a whitespace run is a pattern separator
+ *  ONLY when the next non-space token starts an exclusion ("!" — the §17
+ *  "include !exclude" form). So a BARE pattern like "docs/my file/*.md" and an
+ *  exclude like "!docs/my file/**" each stay ONE part; the standard
+ *  "js-pattern 空格 !test-pattern" form still splits into its two parts. */
+export function splitGlobPatterns(expr) {
+  const s = String(expr ?? "").trim()
+  if (!s) return []
+  const parts = []
+  let depth = 0
+  let cur = ""
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]
+    if (ch === "{") depth++
+    else if (ch === "}") depth = Math.max(0, depth - 1)
+    if (/\s/.test(ch) && depth === 0) {
+      let j = i
+      while (j < s.length && /\s/.test(s[j])) j++
+      if (s[j] === "!") {
+        if (cur) { parts.push(cur); cur = "" }
+        i = j - 1 // next loop iteration continues at the "!"
+        continue
+      }
+      // literal space inside a pattern (or trailing) — keep it in the current part
+      cur += ch
+      continue
+    }
+    cur += ch
+  }
+  if (cur) parts.push(cur)
+  return parts
+}
+
+/** Compile whitespace-split pattern parts (see splitGlobPatterns) into a matcher:
+ *  non-"!" parts are includes, leading-"!" parts are excludes — a rel path matches
+ *  when it matches ≥1 include (or there are no includes) and no exclude. Every
+ *  part runs the full brace/error dialect through globToRegex (excludes too). */
+export function compileGlobMatchers(parts) {
+  const includes = []
+  const excludes = []
+  for (const p of parts) {
+    const part = String(p)
+    if (part.startsWith("!")) excludes.push(part.slice(1))
+    else if (part !== "") includes.push(part)
+  }
+  const include = includes.map((p) => globToRegex(p))
+  const exclude = excludes.map((p) => globToRegex(p))
+  const test = (relPath) =>
+    (include.length === 0 || include.some((re) => re.test(relPath))) &&
+    !exclude.some((re) => re.test(relPath))
+  return { include, exclude, test }
+}

package/src/tools/glob.md

@@ -1,11 +1,11 @@
-Find files by glob pattern. Returns matching paths. Supports `**` for recursive matching (e.g. `src/**/*.mjs` for all .mjs in src/, `**/*.test.mjs` for all test files).
+Find files by glob pattern. Returns matching paths (relative to the search path), sorted, capped at 1000. Use this to discover file structure; use grep to search file contents.
 
 Parameters:
-- pattern (required): Glob pattern — supports **, *, ?, and character classes
+- pattern (required): Glob pattern — supports `**` (recursive), `**/`, `*` (within a segment), `?` (single char), `[..]` character classes, and `{a,b}` brace expansion (e.g. `**/*.{js,txt}` matches .js and .txt files at any depth). Space-separated multiple patterns with a leading `!` are EXCLUSIONS — `**/*.js !test/**` matches .js files except those under test/. Pattern matching is relative to `path`. A pattern containing a literal space is fine on its own (spaces only separate patterns when a `!` exclusion is present). An expression splits ONLY before `!`-exclusion tokens — to match several extensions in one include, use a `{a,b}` group (e.g. `**/*.{js,md}`); adjacent space-separated includes are not a supported form.
 - path: Directory to search in (default cwd)
 
 Notes:
+- Invalid glob syntax is an EXPLICIT error — never a silent no-match. Unsupported extglob dialects (`?(x)`/`@(a|b)`/`+(x)`) and malformed braces (empty `{}`, unclosed `{`, nested `{a,{b,c}}`) return `glob error: ...` — use `{a,b}` or a space-separated `!exclude` pattern instead.
 - Skips node_modules, .git, dist, build, .turbo, coverage
 - Results capped at 1000 matches
-- Use this to discover file structure; use grep to search file contents
 - Prefer patterns with a literal anchor (extension or subdirectory) over bare wildcards

package/src/tools/grep.md

@@ -5,7 +5,7 @@ Search file contents with a regex. Returns matching lines as path:line: content.
 Parameters:
 - pattern (required): JavaScript regular expression, or a literal string when literal=true
 - path: Directory or file to search (default cwd)
-- glob: Only search files matching this glob (e.g. '*.mjs')
+- glob: Only search files matching this glob — supports `**`, `*`, `?`, `[..]`, `{a,b}` braces and space-separated exclusion (`"**/*.js !test/**"` = .js files outside test/); e.g. '*.mjs'
 - ignoreCase: Case-insensitive match (default false)
 - literal: Literal string match — no regex interpretation (default false; use for strings with `. \` etc.)
 - before: Lines of context to show before each match (grep -B). Default 0

package/src/tools/index.mjs

@@ -2,34 +2,35 @@
 export { toOpenAISchema } from "./shared.mjs";
 
 import { readTool, writeTool, editTool, insertAfterTool, readImageTool, hashlineEditTool } from "./file.mjs";
-import { readPdfTool } from "./pdf.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";
 import { executeTool } from "./execute.mjs";
-import { fileOpsTool, processTool, getCurrentTimeTool } from "./ops.mjs";
+import { fileOpsTool, processTool, getCurrentTimeTool, waitForTool } from "./ops.mjs";
 import { treeTool } from "./tree.mjs";
 
 export const builtinTools = [
   readTool, writeTool, editTool, insertAfterTool, hashlineEditTool, applyPatchTool,
-  readImageTool, readPdfTool, bashTool, globTool, grepTool,
+  readImageTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
   gitTool, questionTool,
   checklistTool, lintTool, lspTool, executeTool,
-  fileOpsTool, processTool, getCurrentTimeTool,
+  fileOpsTool, processTool, getCurrentTimeTool, waitForTool,
   treeTool,
 ];
 
 export {
   readTool, writeTool, editTool, insertAfterTool, hashlineEditTool, applyPatchTool,
-  readImageTool, readPdfTool, bashTool, globTool, grepTool,
+  readImageTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
   gitTool, questionTool,
   checklistTool, lintTool, lspTool, executeTool,
-  fileOpsTool, processTool, getCurrentTimeTool,
+  fileOpsTool, processTool, getCurrentTimeTool, waitForTool,
   treeTool,
 };

package/src/tools/ops.mjs

@@ -1,11 +1,14 @@
 /**
  * ops.mjs — operational tools: file_ops (move/copy/rename), process (list),
- * get_current_time. Each exists so the model reaches for a dedicated tool
- * instead of shelling out to `bash` for the same operation (parity with thinworker).
+ * get_current_time, wait_for (condition wait). Each exists so the model reaches
+ * for a dedicated tool instead of shelling out to `bash` for the same operation
+ * (parity with thinworker).
  */
 import { DESC, resolveInCwd, truncate } from "./shared.mjs"
 import { cp, rename, rm } from "node:fs/promises"
+import { existsSync } from "node:fs"
 import { execFileSync } from "node:child_process"
+import net from "node:net"
 
 // ─── file_ops ──────────────────────────────────────────────────
 
@@ -111,4 +114,186 @@ export const getCurrentTimeTool = {
     const days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
     return `Date: ${now.toISOString()} (UTC)\nTimezone: ${tz}\nWeekday: ${days[now.getDay()]}\nLocal: ${now.toLocaleString()}`
   },
-}
+}
+
+// ─── wait_for ───────────────────────────────────────────────────
+
+/** wait_for bounds (TOOLS.md §16): a BUILT-IN ceiling replaces the unbounded
+ *  sleep-then-wait — timeout_ms defaults to 30s (config.json agent.waitForTimeoutMs
+ *  overrides), capped at WAIT_FOR_MAX_TIMEOUT_MS (600s — the execute-tool timeout
+ *  convention, Math.min(t, 600_000)); interval_ms defaults to 1s with a 100ms
+ *  floor so polling never busy-spins. */
+export const WAIT_FOR_DEFAULT_TIMEOUT_MS = 30_000
+export const WAIT_FOR_MAX_TIMEOUT_MS = 600_000
+export const WAIT_FOR_DEFAULT_INTERVAL_MS = 1_000
+export const WAIT_FOR_MIN_INTERVAL_MS = 100
+
+// Condition-source seam (§16 评审 #4): production uses the real evaluator
+// (evaluateWaitForCondition); tests inject a deterministic fake source via
+// setWaitForConditionSource (default null — production path unchanged).
+let injectedConditionSource = null
+export function setWaitForConditionSource(source) {
+  injectedConditionSource = typeof source === "function" ? source : null
+}
+
+/** Parse a wait_for condition into { kind, arg }. Unknown conditions are an
+ *  EXPLICIT error enumerating the supported forms (评审 #2 — never a silent
+ *  wait on a misspelled condition). */
+export function parseWaitForCondition(condition) {
+  const c = String(condition ?? "").trim()
+  let m
+  if (c === "advisor settled") return { kind: "advisor", arg: null }
+  if (c === "consult done") return { kind: "consult", arg: null }
+  if ((m = c.match(/^subagent id:\s*(\d+) done$/))) return { kind: "subagent", arg: String(Number(m[1])) }
+  if ((m = c.match(/^file exists:\s*(.+)$/))) return { kind: "file", arg: m[1].trim() }
+  if ((m = c.match(/^port open:\s*(\d+)$/))) return { kind: "port", arg: Number(m[1]) }
+  throw new Error(
+    `wait_for: unsupported condition "${c}" — supported: "advisor settled", "subagent id:N done", "consult done", "file exists:path", "port open:N"`,
+  )
+}
+
+/** Async-subagent pool of an agent — ctx.agent 可达性（评审 #1）：dispatch 把
+ *  agent 实例放进工具 ctx（agent/dispatch.mjs toolCtx.agent），池挂在 agent 上
+ *  （深度 0 的 VS Code 侧 agent._asyncSubagents 与 history._asyncSubagents 同
+ *  一 Map——见 agent.mjs；CLI 侧直接是 agent._asyncSubagents）。 */
+function asyncPool(agent) {
+  if (!agent) return new Map()
+  if (agent._asyncSubagents instanceof Map) return agent._asyncSubagents
+  return agent.history?._asyncSubagents instanceof Map ? agent.history._asyncSubagents : new Map()
+}
+
+/** "subagent id:N done" — the async entry for N settled (status done / done flag)
+ *  or already left the pool (moved to pending results / digested / never spawned —
+ *  nothing is left to wait on). Absent ids are done by vacuity: the model waits on
+ *  ids its own spawn ack just returned, so an id no longer in the pool means done.
+ *  Dual key lookup (2026-09-06 advisor #1): VS Code pool keys are the numeric
+ *  spawn-time id, the CLI keys them as String(id) — accept both. */
+function asyncEntryDone(agent, id) {
+  const pool = asyncPool(agent)
+  const key = String(id)
+  const entry = pool.get(key) ?? pool.get(Number(key)) ?? null
+  if (!entry) return true
+  return entry.done === true || entry.status === "done"
+}
+
+/** 评审池双载体（第 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) {
+  const sessions = agent?._consultSessions
+  if (!sessions || sessions.size === 0) return true
+  for (const s of sessions.values()) {
+    if (!s.stopped && (s.pending ?? 0) > 0) return false
+  }
+  return true
+}
+
+/** "port open:N" — 127.0.0.1 probe with a short connect timeout (never hangs a poll). */
+function portOpenProbe(port) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: "127.0.0.1", port, timeout: 400 })
+    let settled = false
+    const finish = (v) => {
+      if (settled) return
+      settled = true
+      socket.destroy()
+      resolve(v)
+    }
+    socket.once("connect", () => finish(true))
+    socket.once("error", () => finish(false))
+    socket.once("timeout", () => finish(false))
+  })
+}
+
+/** Real condition evaluator (production path) — returns a boolean; throws on an
+ *  unsupported condition string. Polling is async (await setTimeout) — the event
+ *  loop keeps running so background async work (subagents/consult) can settle
+ *  between polls (评审 #1 — no blocking spin). */
+export async function evaluateWaitForCondition(condition, ctx) {
+  const parsed = parseWaitForCondition(condition)
+  const agent = ctx?.agent
+  switch (parsed.kind) {
+    case "advisor":
+      // 第 10 批修正（§18.3 #2——修前恒真 0ms 秒过）：判据 = 评审池真实态（双载体）——
+      // 不再读子代理池的 role==="advisor" 条目（该池永无此类条目）；语义与 §11.2 未决
+      // 评审判定同源（advisorReviewPending）。
+      return advisorSettled(agent)
+    case "subagent":
+      return asyncEntryDone(agent, parsed.arg)
+    case "consult":
+      return consultAllDone(agent)
+    case "file":
+      return existsSync(resolveInCwd(ctx, parsed.arg))
+    case "port":
+      return await portOpenProbe(parsed.arg)
+    default:
+      return false
+  }
+}
+
+async function evalConditionSource(condition, ctx) {
+  if (injectedConditionSource) return injectedConditionSource(condition, ctx)
+  return evaluateWaitForCondition(condition, ctx)
+}
+
+export const waitForTool = {
+  name: "wait_for",
+  description: DESC("wait_for"),
+  parameters: {
+    type: "object",
+    properties: {
+      condition: { type: "string", description: 'Condition expression — "advisor settled", "subagent id:N done", "consult done", "file exists:path", "port open:N"' },
+      interval_ms: { type: "integer", description: "Poll interval in ms (default 1000, floor 100)" },
+      timeout_ms: { type: "integer", description: "Overall timeout in ms (default 30000, cap 600000; config.json agent.waitForTimeoutMs overrides the default)" },
+    },
+    required: ["condition"],
+  },
+  readonly: true,
+  async execute(args, ctx = {}) {
+    const condition = typeof args?.condition === "string" ? args.condition.trim() : ""
+    if (!condition) return "Error: condition is required"
+    const intervalMs = Math.max(WAIT_FOR_MIN_INTERVAL_MS, Math.floor(args?.interval_ms ?? WAIT_FOR_DEFAULT_INTERVAL_MS))
+    const cfgTimeout = ctx?.agent?.config?.agent?.waitForTimeoutMs
+    const base = Number.isFinite(args?.timeout_ms)
+      ? args.timeout_ms
+      : Number.isFinite(cfgTimeout) && cfgTimeout > 0 ? cfgTimeout : WAIT_FOR_DEFAULT_TIMEOUT_MS
+    const timeoutMs = Math.min(Math.max(1, Math.floor(base)), WAIT_FOR_MAX_TIMEOUT_MS)
+    const started = Date.now()
+    let polls = 0
+    for (;;) {
+      // Cancel/interrupt-safe exit（T-W7）：Ctrl+C / 定向 abort 传播——不吞信号、
+      // 不把用户停变成工具错误（dispatch 对 aborted signal 原样再抛）。
+      if (ctx.signal?.aborted) throw new Error("wait_for: interrupted by abort signal")
+      polls++
+      const ok = await evalConditionSource(condition, ctx)
+      if (ok === true) {
+        return `wait_for: condition satisfied after ${Date.now() - started}ms (${polls} check${polls === 1 ? "" : "s"}): "${condition}"`
+      }
+      const remaining = started + timeoutMs - Date.now()
+      if (remaining <= 0) {
+        return `wait_for: timed out after ${timeoutMs}ms waiting for "${condition}" (${polls} checks — condition never became true)`
+      }
+      await new Promise((r) => setTimeout(r, Math.min(intervalMs, remaining)))
+    }
+  },
+}