thincoder 0.12.58 → 0.12.60

package/src/tools/file.mjs

@@ -10,10 +10,10 @@ import {
   detectFileEol,
   joinWithEol,
   majorityEol,
-  findCandidates,
   FFFD_WARNING,
 } from "./shared.mjs";
 import { applyEditBatch } from "./edit-batch.mjs";
+import { runSingleEdit } from "./edit-diff.mjs";
 import { specForModel } from "../config.mjs";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, stat, writeFile, unlink } from "node:fs/promises";
@@ -73,6 +73,7 @@ export const readTool = {
     type: "object",
     properties: {
       path: { type: "string", description: "File path (relative to cwd or absolute)" },
+      filePath: { type: "string", description: "Alias for path (supported for API compatibility)" },
       offset: { type: "number", description: "1-based line number to start from" },
       limit: { type: "number", description: `Max lines to return (default ${MAX_READ_LINES})` },
       allowExternal: { type: "boolean", description: "No-op retained for API compatibility — path resolution no longer asserts a working-directory boundary (all paths resolve relative to cwd)." },
@@ -82,7 +83,8 @@ export const readTool = {
   },
   readonly: true,
   async execute(args, ctx) {
-    const abs = args.allowExternal ? resolveExternal(ctx, args.path) : resolveInCwd(ctx, args.path)
+    const p = args.path ?? args.filePath
+    const abs = args.allowExternal ? resolveExternal(ctx, p) : resolveInCwd(ctx, p)
     // Large file guard: check size first, reject reading entire file if >10MB (offset/limit only affect the returned slice, not buffering)
     const st = await stat(abs).catch(() => null)
     if (st && st.size > MAX_FILE_READ_BYTES) throw new Error(`File too large (${Math.round(st.size / 1_000_000)}MB > 10MB limit). Use bash with head/tail or grep for targeted extraction.`)
@@ -214,22 +216,27 @@ export const editTool = {
   parameters: {
     type: "object",
     properties: {
-      path: { type: "string", description: "File path" },
-      old_string: { type: "string", description: "Exact text to replace" },
-      new_string: { type: "string", description: "Replacement text" },
+      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 (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. Mutually exclusive with path/old_string/new_string.",
+        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: ["path", "old_string", "new_string"],
         },
       },
     },
@@ -237,7 +244,13 @@ export const editTool = {
   },
   readonly: false,
   touchedPaths(args) {
-    if (args.edits) return args.edits.map((e) => e.path).filter(Boolean)
+    // 2026-09-05 用户裁定：顶层 path = 批默认——仅当有条目缺 path 时计入（条目全带 path
+    // 时顶层 path 不实际使用——不虚报进 _touchedFiles）
+    if (args.edits) {
+      const out = args.edits.map((e) => e.path).filter(Boolean)
+      if (args.path && args.edits.some((e) => !e.path)) out.push(args.path)
+      return out
+    }
     return args.path ? [args.path] : []
   },
   async execute(args, ctx) {
@@ -245,67 +258,9 @@ export const editTool = {
     // （应用逻辑在 edit-batch.mjs——2026-09-01 拆出，500 行硬限，先例 git-ext.mjs）
     if (args.edits) return applyEditBatch(args, ctx)
 
-    // 单文件（现状路径）
-    const abs = resolveInCwd(ctx, args.path)
-    if (!args.old_string) {
-      throw new Error("old_string must not be empty (empty string matches everywhere and would corrupt the file)")
-    }
-    // #5（2026-09-01 交付评审尾巴）：new_string 非字符串（含 undefined）在写盘前拒绝——
-    // 原缺陷：replace 回调返回 undefined 被字符串化成 "undefined" 写入盘，随后
-    // args.new_string.split 才 TypeError——文件已损坏 + 错误信息不知所云。
-    if (typeof args.new_string !== "string") {
-      throw new Error(
-        `new_string must be a string${args.new_string === undefined ? " (missing)" : ` (got ${typeof args.new_string})`} — nothing written`,
-      )
-    }
-    const raw = await readFile(abs, "utf8")
-    const content = normalizeEOL(raw)
-    const occurrences = content.split(args.old_string).length - 1
-    if (occurrences === 0) {
-      // Give clues to help the model locate: first-line preview + common causes
-      const preview = args.old_string.slice(0, 100).split("\n")[0]
-      // Similarity candidates (LCS, line-level, top 3, score ≥ 0.5) — turns the
-      // "not found" black box into a pointer at the most likely intended line.
-      // Multi-line old_string: only its first line is scored (marked accordingly).
-      const cands = findCandidates(content.split("\n"), args.old_string)
-      let candText = ""
-      if (cands.length > 0) {
-        const header = args.old_string.includes("\n")
-          ? `  similar lines (old_string line 1: "${args.old_string.split("\n")[0].slice(0, 80)}"):`
-          : "  similar lines:"
-        candText = "\n" + header + "\n" + cands.map((c) => `    L${c.line}: ${c.preview} (${Math.round(c.score * 100)}%)`).join("\n")
-      }
-      throw new Error(
-        `old_string not found in ${args.path}\n` +
-        `  searched: "${preview}${args.old_string.length > 100 ? "…" : ""}"\n` +
-        (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
-      )
-    }
-    if (occurrences > 1 && !args.replace_all) {
-      throw new Error(`old_string matches ${occurrences} times in ${args.path}; provide more context or set replace_all`)
-    }
-    const updated = args.replace_all
-      ? content.split(args.old_string).join(args.new_string)
-      // Functional replacement: avoid $-substitution patterns in new_string (match string / backreference) being expanded
-      : content.replace(args.old_string, () => args.new_string)
-    // Write back in the file's ORIGINAL EOL style (first-newline rule) — a CRLF
-    // file must not come back as LF (that rewrites every line in the diff).
-    // 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")
-    // 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)
-    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)
+    // 单文件（现状路径）——执行体整段迁出至 edit-diff.mjs（EDIT.md §6——
+    // 行级 LCS 判定：零重叠→替换即删 / 一般 diff→LCS / 空 new→显式报错）
+    return runSingleEdit(args, ctx)
   },
 }
 
@@ -453,7 +408,7 @@ export const hashlineEditTool = {
       const hashDump = fileHashes.slice(0, maxShow).map((h, i) => `${h}  L${i + 1}: ${lines[i].slice(0, 80)}`).join("\n")
       const preview = target.join(" ")
       throw new Error(
-        `Hash sequence not found in ${args.path}: ${preview}\n` +
+        `Hash sequence not found in ${args.path}: ${preview} — for fresh hashes, re-read the file with hashes=true\n` +
         `The file may have been modified since you last read it. Current hashes (first ${maxShow} lines):\n${hashDump}` +
         (corrupted ? `\n${FFFD_WARNING}` : "")
       )

package/src/tools/file_ops.md

@@ -13,4 +13,5 @@ Parameters:
 Notes:
 - Paths resolve relative to cwd — no directory restriction (same boundary as bash; the approval gate is the guard).
 - `dest` is overwritten if it already exists. `copy` is recursive for directories.
-- To create a directory, use `write` (creates parent dirs) or `bash mkdir`.
+- To create a directory, use `write` (creates parent dirs) or `bash mkdir`.
+- Returns `Moved|Copied|Renamed <source> -> <dest>` or `Error: ...` (same-path and missing-path errors).

package/src/tools/get_current_time.md

@@ -3,4 +3,6 @@ Get the current date, time, weekday, and timezone.
 **Route to get_current_time instead of bash:**
 - `date` / `time` → get_current_time
 
-Use it whenever a task depends on the current time or date (deadlines, freshness, timestamps) rather than shelling out.
+Use it whenever a task depends on the current time or date (deadlines, freshness, timestamps) rather than shelling out.
+
+Returns `Date` / `Timezone` / `Weekday` / `Local` lines (UTC + local timezone).

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,13 +143,16 @@ 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"])
+        // 多路径：空格分隔（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])
         const parts = []
@@ -189,9 +192,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
@@ -361,6 +366,9 @@ export const questionTool = {
   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/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/hashline_edit.md

@@ -10,3 +10,5 @@ Notes:
 - Hashes are position-independent: they identify lines by content, not by line number (which changes after edits)
 - If the hash sequence isn't found, the error will include the current file's hashes so you can retry with corrected values
 - Prefer this over edit when: 1) the file may have mixed whitespace/encoding, 2) you want to edit a block of lines with a single call
+- Replacement text replaces the lines identified by the hashes — content not present in new_content is deleted. For a new line after a known line, use insert_after. For a single simple string swap, use edit.
+- use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed

package/src/tools/index.mjs

@@ -10,7 +10,7 @@ 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 = [
@@ -19,7 +19,7 @@ export const builtinTools = [
   websearchTool, lsTool, fetchTool, deleteTool,
   gitTool, questionTool,
   checklistTool, lintTool, lspTool, executeTool,
-  fileOpsTool, processTool, getCurrentTimeTool,
+  fileOpsTool, processTool, getCurrentTimeTool, waitForTool,
   treeTool,
 ];
 
@@ -29,6 +29,6 @@ export {
   websearchTool, lsTool, fetchTool, deleteTool,
   gitTool, questionTool,
   checklistTool, lintTool, lspTool, executeTool,
-  fileOpsTool, processTool, getCurrentTimeTool,
+  fileOpsTool, processTool, getCurrentTimeTool, waitForTool,
   treeTool,
 };

package/src/tools/insert_after.md

@@ -8,7 +8,8 @@ Parameters:
 
 Notes:
 - Either after_line or after_regex is required; if both are given, after_line wins.
-- Use this instead of `edit` when you're adding a new function, import, or block — no need to fabricate surrounding context for exact matching.
+- Use this instead of edit when you're adding a new line — a checklist item, a doc heading, a line of prose, a function, an import, or a block — no need to fabricate surrounding context for exact matching.
 - The inserted content becomes its own line; it's equivalent to `lines.splice(targetLine, 0, content)`.
 - Returns a diff of the change.
 - **Read-before-insert guard**: if the file was modified by any write tool (write/edit/insert_after/hashline_edit/apply_patch/delete) since your last `read`, this tool REFUSES with an error — line numbers may be stale. Read the file again, then retry. This prevents after_line from silently landing at a drifted position.
+- use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed

package/src/tools/lint.md

@@ -3,6 +3,8 @@ Without 'full', runs a fast node --check (JS/TS syntax only, catches parse error
 With 'full', runs the language-aware cascade: tsc –noEmit (TS); ruff (Python); cargo check (Rust); go vet (Go). JS/JSX files fall back to node --check; TS uses tsc --noEmit (requires tsconfig.json).
 Use the fast default after every write/edit; use 'full' before declaring a task complete.
 
+Returns the check result: `Syntax OK: <path>` / `Syntax error in <path>: <message>` (or the language checker's output — `✓ no issues` or the failure text).
+
 Parameters:
 - path: File to check (default: most recently modified file)
 - full: Run the full language-aware cascade instead of just node --check (default false)

package/src/tools/lsp.md

@@ -1,7 +1,10 @@
-LSP code intelligence: go to definition, find references, hover info, document symbols, diagnostics. Use this to understand code structure without grep-guessing function locations or type shapes.
+LSP code intelligence: go to definition, find references, hover info, document symbols, diagnostics. Use this to understand code structure without grep-guessing function locations or type shapes. Find files with glob / repo_outline — use lsp for definition / references / diagnostics
 
 Parameters:
 - subcommand (required): LSP operation — "definition" | "references" | "hover" | "symbols" | "diagnostics"
 - uri (required): Target file path (relative to project root)
 - line: 1-based line number (for definition/references/hover)
 - character: 1-based character offset (for definition/references/hover)
+
+Notes:
+- Returns the requested LSP result: definition location, references, hover info, document symbols, or diagnostics — or an error message.