@thincoder/core 0.9.1

package/tool-docs/edit.md

@@ -0,0 +1,30 @@
+Edit a file as a patch — targeted by content or by line number. Two targeting forms (mutually exclusive — use one): ① line-based: `line: N` replaces that single line, `startLine: N, endLine: M` replaces the inclusive 1-based line range — no old_string needed when you know the line number; give new_string to replace, or OMIT new_string to delete the line/range; ② content-based: old_string is the current content of the region to change (must match exactly once); new_string is the desired result of that region. old_string matching is tolerant: exact match first, then a unique whitespace-only variant, then fuzzy match (unique window with ≥90% of lines identical after trimming, tab→space indent and quote normalization — ASCII single, curly single/double and backtick quotes all unify to straight double quotes). Lines shared by old/new are kept; lines only in new_string take their position relative to the shared lines (LCS order); lines only in old_string are deleted — a replacement never leaves old lines behind (zero overlap → old lines are replaced by new_string, not kept). A unique single-line old_string paired with a single-line new_string replaces that exact line in place (line count unchanged). To add a new line without removing anything use insert_after. replace_all keeps literal replacement of every occurrence — the diff rules do not apply.
+
+**Routing — pick the right edit tool:**
+- Delete a line/range by number → omit new_string: edit with `line: N` / `startLine: N, endLine: M`
+- Line numbers fresh (just read) → `line`/`startLine`/`endLine` targeting — precise, no content copy needed
+- Line numbers may have drifted / content has whitespace-encoding noise → `hashline_edit` (content-hash addressing — position-independent)
+- Add a line/entry after a known line → insert_after
+- Same change across multiple files → apply_patch
+- Rewrite an entire file → write
+- Rename a symbol project-wide → `lsp` or `grep` first to map every caller
+
+**Batch multiple edits into ONE call via the `edits` array** (preferred over N single edit calls): multiple changes to the SAME file go into one `edits` array (entries are applied serially, each based on the previous one's result); independent changes across MULTIPLE files also go into the same `edits` array — one call, atomic (any failure writes nothing). A batched call is one permission ask, one undo unit, and one turn instead of N. A top-level path may accompany the array — entries without their own path inherit it (entry paths override).
+
+Parameters:
+- path: File path (single form: required; with the edits array: optional — the default for entries without their own path)
+- old_string: Current content of the region to change (must match exactly once — tolerant matching: exact → whitespace-only variant → fuzzy ≥90% line-equal). Mutually exclusive with line/startLine/endLine — required unless line targeting is used
+- new_string: Desired result of the region — diffed against old_string (shared lines kept; old-only lines deleted — a replacement never leaves old lines behind). Content-based edits: required — an explicit empty string is an error (protects against forgetting it). Line-based edits (line/startLine/endLine): give it to replace the line/range, or OMIT it to delete — an explicit empty string is NOT deletion (error — omit instead)
+- line: 1-based line number — replace that single line with new_string, or OMIT new_string to DELETE it (mutually exclusive with old_string and startLine/endLine)
+- startLine / endLine: 1-based inclusive line range to replace with new_string (given together; mutually exclusive with old_string) — OMIT new_string to DELETE the range
+- replace_all: Replace all occurrences instead of just one (default false; content-based targeting only)
+- edits: Array of {path?, old_string?, new_string?, line?, startLine?, endLine?, replace_all?} entries — batch form; mutually exclusive with top-level old_string/new_string/line/startLine/endLine — a top-level path is allowed and applies to entries without their own path
+
+Notes:
+- Prefer this over write for targeted edits — it's safer and keeps changes targeted
+- If old_string matches zero times (even fuzzy): error. If it matches multiple times without replace_all: error — add more surrounding context to make it unique
+- Content-based edits: new_string empty is an explicit error (protects against forgetting it).
+- Line-based edits: OMIT new_string to delete the line/range — deleting by number is an explicit, bounded intent.
+- Returns `Edited <path>: replaced N occurrence(s)` (delete-mode: `Deleted line N of <path>` / `Deleted lines N-M of <path>`) + git diff + syntax-check note + context block (L..-L..).
+- Never fabricate the old_string — copy it verbatim from the actual file using read first
+- use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed

package/tool-docs/execute.md

@@ -0,0 +1,21 @@
+Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real child `node` process — a pure node ESM environment: top-level `await` and dynamic `import()` are available, no globals are injected. File reads/writes/searches belong to the dedicated read/ls/glob/grep/write/edit tools — not to execute. If a script genuinely needs fs/path, `import` the `node:` module inside the code (one explicit import line).
+
+**Route to execute instead of bash:**
+- `node -e "…"` → execute (inline code; top-level await + import() + console all work)
+- `node <script.mjs>` → execute with scriptFile (runs the file in a child node process)
+- `node --test <file>` / `node --check <file>` → execute with scriptFile + nodeArgs
+
+Parameters:
+- code: JavaScript to run inline. Top-level `await` and `import('./x.mjs')` are supported. Pure node ESM — no preloaded helpers; import `node:fs`/`node:path` etc. yourself when needed. File reads/writes go through the dedicated read/ls/glob/grep/write/edit tools. Use this OR scriptFile.
+- scriptFile: run a .mjs/.js file with node (self-contained — the file imports what it needs). Path relative to workdir — no directory restriction. Use this OR code.
+- 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 — no directory restriction; default cwd)
+- filter: optional — only return output lines matching this regex (case-insensitive)
+- timeoutMs: Timeout in milliseconds (default 30000, max 600000 — covers `node --test` suites and package scripts)
+
+Notes:
+- `console.log(...)` prints to the result; objects are JSON-stringified where needed.
+- A non-zero exit / thrown exception returns the stderr (error + stack) as the result.
+- Output is capped at ~50KB; when a script overruns it, an explicit `[output truncated]` marker is appended — print large results in chunks, or have the script write them to a file (node:fs) and read that file back with the `read` tool.
+- Use `write`/`edit`/`apply_patch` for source edits. Still use `bash` for package-manager/CLI subprocesses (`npm test`/`npm publish`/`vsce`), servers, and interactive/TTY programs — execute covers in-process JS and `node <script>`/`node --test`/`node --check`, not arbitrary CLI or long-running programs.
+- Irreversibility: it runs with full filesystem access and no automatic undo — script side effects are permanent; checkpoint (git) before risky bulk operations.

package/tool-docs/fetch.md

@@ -0,0 +1,12 @@
+Fetch a URL and return its content as text. HTML pages are stripped to readable text. Use after websearch to read full documents.
+
+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
+- Timeout: 15 seconds
+- HTML pages are converted to plain text (scripts, styles, navigation stripped)
+- Non-HTML responses are returned as-is (truncated at ~50000 chars)
+- Proxy support: set `"proxy": {"uri": "http://host:port", "web": true}` in config.json or `HTTPS_PROXY` env var

package/tool-docs/file_ops.md

@@ -0,0 +1,17 @@
+Move, copy, or rename a file/directory.
+
+**Route to file_ops instead of bash:**
+- `mv a b` → file_ops action=move
+- `cp a b` / `copy` → file_ops action=copy
+- `ren a b` / `rename a b` → file_ops action=rename
+
+Parameters:
+- action (required): move | copy | rename
+- source (required): source path, relative to cwd or absolute
+- dest (required): destination path
+
+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`.
+- Returns `Moved|Copied|Renamed <source> -> <dest>` or `Error: ...` (same-path and missing-path errors).

package/tool-docs/get_current_time.md

@@ -0,0 +1,8 @@
+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.
+
+Returns `Date` / `Timezone` / `Weekday` / `Local` lines (UTC + local timezone).

package/tool-docs/git.md

@@ -0,0 +1,54 @@
+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, `git ls-remote`→ls-remote, `git clone`→clone, `git init`→init, `git rebase`→rebase, `git remote`→remote, `git clean`→clean, `git switch`→switch, `git apply`→apply, `git worktree`→worktree, `git archive`→archive, `git blame`→blame, `git mv`→mv.
+
+- action='diff': unified diff — what changed since last commit. staged=true for staged-only; ref=<ref> to compare a commit/branch; path=<dir> to scope.
+- action='status': working tree state — staged / unstaged / untracked / conflicts, categorized.
+- 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': 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).
+- action='branch': manage branches. branchAction=list / create (name, optional ref) / switch (name) / delete (name; snapshots first).
+- action='checkout': switch to ref=<branch/commit>, or restore a file path=<file> (discards its working-tree changes; snapshots first).
+- action='restore': restore a file from index/HEAD. path required; staged=true restores the staged copy; snapshots first.
+- action='stash': manage the stash. stashAction=list / push (message) / pop (snapshots first).
+- action='reset': reset to ref (default HEAD). mode=soft/mixed/hard; hard snapshots the tree first (drops working-tree changes).
+- action='revert': revert a commit (safe). ref=<commit> (default HEAD).
+- action='merge': merge ref=<branch/commit>; conflicts reported for you to resolve.
+- action='cherry-pick': cherry-pick ref=<commit>.
+- action='ls-remote': light remote-ref check — which refs a remote has (read-only, network). remote=<origin>, ref=<branch/tag> optional, config for proxy.
+- action='clone': clone a repo. remote required (URL or local path); path optional (target dir).
+- action='init': init a repo in the current (work)dir.
+- action='rebase': rebase onto ref. rebaseAction=start (ref required) / abort / continue（操作前自动快照，checkpointAction=rewind 恢复）.
+- action='remote': manage remotes. remoteAction=list / add / remove / set-url; remoteUrl for add/set-url.
+- action='clean': remove untracked files/dirs. dryRun for -n preview（真删除操作前自动快照，checkpointAction=rewind 恢复）.
+- action='switch': switch branch. name required; create for -c (new branch).
+- action='apply': apply a patch. path required (patch file).
+- action='worktree': manage worktrees. worktreeAction=list / add (path, ref) / remove (path).
+- action='archive': write a tar of ref (default HEAD). path required (output file).
+- action='blame': file blame. path required.
+- action='mv': rename/move. path (source) + dest required.
+- action='checkpoint': git snapshots. checkpointAction=list/create/rewind/cat/versions; checkpointId required for rewind/cat.
+- Destructive ops (checkout -- path / restore / reset --hard / stash pop / branch|tag delete / clean / rebase) auto-snapshot first — restore via checkpointAction=rewind.
+
+Parameters:
+- action (required): diff / status / log / show / checkpoint / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick / ls-remote / clone / init / rebase / remote / clean / switch / apply / worktree / archive / blame / mv
+- workdir: run git in this subdirectory (monorepo / multi-repo). Path relative to cwd — no directory restriction. Default: the discovered project repo root（缺省 = 发现的项目仓根；显式 workdir 优先）
+- config: (network actions push/fetch/pull/ls-remote/clone) git -c overrides, e.g. ["http.proxy=http://10.2.2.112:3128"] for blocked remotes
+- path: (diff/log/add/commit/checkout/restore/rm/apply/archive/blame/mv/worktree) file or directory to scope / stage / restore
+- ref: (show/diff/checkout/reset/revert/merge/cherry-pick/tag:create/branch:create/rebase/worktree:add/archive) commit/branch/ref; (push/pull/fetch) the branch or tag (space-separated for multiple)
+- name: (branch/tag/switch) the branch or tag name
+- remote: (push/fetch/pull/remote/clone) remote name (e.g. origin) or URL; default: current upstream
+- tags: (push) also push all tags (--tags)
+- staged: (diff) staged changes; (restore) the staged copy
+- count: (log) number of commits (default 10)
+- oneline: (log) one-line-per-commit
+- message: (commit) commit message — required; (stash:push) stash message
+- mode: (reset) soft / mixed / hard — hard snapshots the tree first + needs confirmation
+- tagAction: (tag) list / create / delete — branchAction: (branch) list / create / delete / switch — stashAction: (stash) push / pop / list
+- filter: (read-only actions) keep only output lines matching this regex (case-insensitive)
+- checkpointAction: (checkpoint) list / create / rewind / cat / versions — checkpointId: snapshot id (rewind/cat)
+- remoteAction: (remote) list / add / remove / set-url — remoteUrl: (remote add/set-url) URL — rebaseAction: (rebase) start / abort / continue — dryRun: (clean) -n preview — create: (switch) -c — dest: (mv) destination — worktreeAction: (worktree) list / add / remove

package/tool-docs/glob.md

@@ -0,0 +1,11 @@
+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 `**` (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
+- Prefer patterns with a literal anchor (extension or subdirectory) over bare wildcards

package/tool-docs/grep.md

@@ -0,0 +1,19 @@
+Search file contents with a regex. Returns matching lines as path:line: content.
+
+**Route to grep instead of bash:** `findstr /c:"pat" file` / `grep -rn pat .` → grep. Searching file contents is a read — never shell out for it.
+
+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 — 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
+- after: Lines of context to show after each match (grep -A). Default 0
+
+Notes:
+- Skips node_modules, .git, dist, build, .turbo, coverage
+- Results capped at 200 matches
+- Binary/unreadable files are silently skipped
+- Use this to find usages, definitions, patterns; use glob to find files by name
+- With before/after: matching lines use `:` separator, context lines use `-` (like ripgrep); overlapping context ranges in the same file are merged and de-duplicated

package/tool-docs/hashline_edit.md

@@ -0,0 +1,14 @@
+Edit a file using content-hash addressing instead of string matching. More reliable than edit when whitespace or encoding varies — hashes are computed from exact line bytes on disk.
+
+Parameters:
+- path (required): File path
+- old_hashes (required): Array of SHA256 hashes (12-char hex) identifying lines to replace. Read the file with hashes=true first to obtain these hashes. For a single line, pass [hash]; for a contiguous block, pass [hash1, hash2, ...] in order.
+- new_content (required): Replacement text (multi-line ok, \n separated)
+
+Notes:
+- The hash of each line is computed as SHA256(line_content).slice(0, 12) — the same algorithm used by read(hashes=true)
+- 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/tool-docs/insert_after.md

@@ -0,0 +1,15 @@
+Insert a line of text after a specific line in a file. Safer than `edit` for adding new content — no need to copy surrounding context for exact string matching.
+
+Parameters:
+- path (required): File path
+- content (required): Text to insert (will be placed as a new line after the target line)
+- after_line: Line number to insert after (1-based). Preferred when you know the exact line number from `read`.
+- after_regex: JavaScript regex to find the line to insert after. Must match exactly one line; if it matches multiple, the tool errors and shows the matching line numbers.
+
+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 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/tool-docs/lint.md

@@ -0,0 +1,10 @@
+Run the appropriate linter/checker for a file. Auto-detects based on file extension and project config.
+Without 'full', runs a fast node --check (JS/TS syntax only, catches parse errors in milliseconds).
+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 — `✓ <checker>: no issues` or `✗ <checker>: <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/tool-docs/ls.md

@@ -0,0 +1,12 @@
+List directory contents with type, size, and modification time. Directories listed first. Use to see what a directory contains (glob only matches files).
+
+**Route to ls instead of bash:** `dir /b` / `ls` / `dir` → ls. Listing a directory is a read — never shell out for it.
+
+Parameters:
+- path: Directory path (default cwd)
+- filter: Only list entries matching this glob (e.g. '*.mjs', '*test*') — a wildcard filter, not a full listing
+
+Notes:
+- Shows first 500 entries
+- Directories are suffixed with `/` and listed before files
+- Use this for a quick overview; use glob when you have a specific file pattern in mind

package/tool-docs/lsp.md

@@ -0,0 +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. 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.

package/tool-docs/process.md

@@ -0,0 +1,10 @@
+List running processes, optionally filtered by name. Returns process name / PID / memory.
+
+**Route to process instead of bash:**
+- `tasklist` (Windows) / `ps aux` (POSIX) → process
+
+Parameters:
+- name (optional): substring filter (case-insensitive), e.g. "node", "python"
+
+Notes:
+- List-only. To kill a process, use `bash taskkill /PID <pid> /F` (Windows) or `bash kill <pid>` — and confirm with the user first.

package/tool-docs/question.md

@@ -0,0 +1,16 @@
+Ask the user a question and wait for their response. Use when the task is ambiguous, you need a design decision, or you're stuck and need human judgment.
+
+Parameters:
+- question (required): The question to ask the user
+- options: Array of single-choice options for the user to pick from (optional). MUST be plain strings, e.g. ["A", "B", "C"] — never objects.
+
+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.
+{{inject:question-ui-face}}
+- 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.
+- Routine confirmations (confirm gates) belong in your plain reply text — the user answers in their next message. Use this tool ONLY when you need the user's decision or input to proceed.
+- After receiving an answer about a design convention, tool preference, or recurring pattern: save it with the memory tool (action: put). This prevents asking the same question in future sessions — the user shouldn't have to repeat their preferences.

package/tool-docs/read.md

@@ -0,0 +1,20 @@
+Read a text file. Returns numbered lines. Use offset/limit to page large files.
+
+**Route to read instead of bash:** `cat file` / `type file` / `node -e "fs.readFileSync(...)"` → read. Reading a file is a read — never shell out for it.
+
+**Routing:**
+- Don't know which file? → `repo_outline` / `code_search` / `glob` first
+- Know the symbol but not the location? → `code_search` or `lsp definition`
+- Know the file but not the lines? → `grep` to find line numbers, then read that range with offset/limit
+- Reading an image? → `read_image` instead
+
+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) — 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:
+- Always prefer this over `cat` or shell-based reading — it caps output and avoids large dumps
+- Use offset for pagination when the file is large
+- When you plan to edit the file, set hashes=true to get line hashes for hashline_edit — hash-based editing avoids whitespace/encoding matching failures

package/tool-docs/read_image.md

@@ -0,0 +1,8 @@
+Read an image file and return it as multimodal content visible to the model. Use this to view screenshots, UI mockups, diagrams, or any visual content. The model only sees images through this tool — it cannot "see" files directly. Supports png, jpg, gif, webp. The image is base64-encoded and included in the response. Large images (>15MB) are rejected.
+
+Parameters:
+- path (required): Path to image file (relative to cwd or absolute). Supports png, jpg, gif, webp; svg is returned as text source.
+
+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 (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.

package/tool-docs/tree.md

@@ -0,0 +1,14 @@
+Generate a directory tree of the codebase (default depth 3). Skips dotfiles, .git/node_modules/dist/build/bin/obj and other build/vendor dirs, and binary files. Use to quickly see which modules exist and where files live.
+
+**Route to tree instead of bash:**
+- `tree` / `find .` / `dir /s` → tree
+
+Parameters:
+- path: Root directory (default cwd)
+- depth: Tree depth (default 3, max 6). Directories are listed before files, both sorted.
+
+Notes:
+- Capped at 200 entries.
+- Directories end with `/`; tree-drawing uses `├──`/`└──`/`│`.
+- Use depth for a shallow overview; use `ls` for one directory, `glob` for a specific file pattern.
+- Returns the directory text tree — directories first (`dir/`), files after, both sorted, capped at 200 entries.

package/tool-docs/wait_for.md

@@ -0,0 +1,22 @@
+Wait until a condition becomes true — polls the condition every interval_ms and returns as soon as it holds or the timeout_ms ceiling passes. Use it ONLY for genuinely asynchronous waits: an async subagent/consult still settling, a file appearing, a port opening. Synchronous tools (advisor, blocking subagent spawn) return when done — waiting after them is NOT needed and wastes time.
+
+Parameters:
+- condition (required): a semantic condition expression:
+  - `advisor settled` — an in-flight advisor review session has finished (async advisor-role children settled)
+  - `subagent id:N done` — async subagent N (the id your async spawn ack returned) has settled
+  - `consult done` — every consult_start session has drained
+  - `file exists:path` — the file at path exists (path relative to cwd)
+  - `port open:N` — something is listening on 127.0.0.1 port N
+  - The agent-internal conditions (advisor / subagent / consult) apply to ASYNC sessions only — a synchronous call already completed before it returned and has nothing to wait for. An unknown condition is an explicit error (`wait_for: unsupported condition "..."` — the supported forms are listed above), never a silent wait.
+- interval_ms: poll interval (default 1000, floor 100 — polling never busy-spins)
+- timeout_ms: overall ceiling (default 30000; config.json `agent.waitForTimeoutMs` overrides the default; hard cap 600000 like the execute tool)
+
+Returns:
+- `wait_for: condition satisfied after Nms (N checks): "<condition>"` — condition held
+- `wait_for: timed out after Nms waiting for "<condition>" ...` — ceiling passed with the condition still false (never burns beyond the ceiling)
+- interrupts (Ctrl+C / cancel) exit immediately; malformed conditions and unsupported syntax error out explicitly
+
+Notes:
+- Read-only and non-destructive — it only observes (agent pools, the filesystem, a local port probe).
+- Blocking by design — call it ALONE in a turn, not batched with calls that depend on its result.
+- Do not use it to wait after synchronous tools (advisor / blocking subagent spawn / verify return only when done).

package/tool-docs/websearch.md

@@ -0,0 +1,16 @@
+Search the web via Bing. Returns result titles, URLs, and snippets. Use for looking up current information, docs, error messages.
+
+Parameters:
+- query (required): Search query
+- limit: Max results (default 8, max 20)
+- engine: Specific engine to use — "bing" (Bing). Omit to search all engines concurrently.
+- page: Page number for pagination (1-based, default 1). Only used when engine is specified.
+- 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); Bing/foreign sites usually need a proxy, domestic targets don't
+
+Notes:
+- Before searching the web, call the memory tool (action: search) first — you may already know the answer from a previous session. Only reach for websearch if memory comes up empty.
+- Runs synchronously — returns when the search completes (all selected engines run in parallel).
+- Use this for information that is NOT in the local codebase — current docs, error messages, API references
+- Follow up with `fetch` to read full pages from the results
+- **Weak engine warning**: Bing's index is noisy for technical queries — if a first websearch returns irrelevant/townhall-grade results, DO NOT retry the same query. Configure a search MCP tool (e.g. `glm-websearch` via the MCP config) for technical lookups; websearch is the fallback.
+- Proxy: NOT auto-applied from config.json (2026-08-31 ruling). Pass `proxy: "http://host:port"` explicitly when the target needs one; omit for domestic targets.

package/tool-docs/write.md

@@ -0,0 +1,11 @@
+Write content to a file. Creates parent directories; overwrites existing file.
+
+Parameters:
+- path (required): File path, relative to cwd or absolute
+- content (required): Full content to write
+
+Notes:
+- write replaces the WHOLE file — read it first and confirm you intend to rewrite it entirely; for a small change use edit / insert_after.
+- Returns `Wrote N chars to <path>` + git diff + syntax-check note.
+- This overwrites the entire file — use `edit` for targeted changes
+- The file is atomic: it either writes completely or fails