@thincoder/core 0.9.4 → 0.10.1

package/tool-args.mjs

@@ -0,0 +1,73 @@
+/**
+ * tool-args.mjs — 工具调用参数的可读展示**单源**（B7 1a 上提：体 = CLI
+ * `thincoder-cli/src/tui/tool-args.mjs` `describeToolArgs` 现体——覆盖 15+ 工具族，最全）。
+ *
+ * 消费面：CLI 标题行 ∕ 恢复面（核件同名转口——`toolArgsLines` 留端）· desk
+ * `agent-bridge.mjs` 保名转口（`describeToolArgs as summarizeArgs`——回调桥 ∕ 待决门 payload 共用一份口径）·
+ * advisor 进度行（端装配层经 `seams.describeArgs` 注入——`advisor/loop.mjs`）。
+ * 单源一句话：按工具挑关键参数的可读单行摘要；未知工具回退单行紧凑 JSON。
+ *
+ * 已登记差额（B7 §2 修正轮 1 ⑨——展示面、非语义差）：默认分支截断 = 本档简版切片（`slice`
+ * 码元截断）替代 CLI `render.mjs` `sliceByWidth`（宽度感知 ∕ 全角计宽）⇒ 全角字符截断
+ * 续接点可异于 CLI 现端（160 ∕ 80 两档触发）。
+ */
+
+/** 单行参数摘要：按工具挑关键字段（卡片头口径），未知工具回退 JSON。 */
+export function describeToolArgs(name, args) {
+  if (!args || typeof args !== "object") return ""
+  const a = args
+  switch (name) {
+    case "bash": case "cmd-shell": {
+      const cmd = String(a.command ?? "").replace(/\s+/g, " ").trim()
+      return cmd ? cmd + (a.workdir ? `  (in ${a.workdir})` : "") : ""
+    }
+    case "read": case "write": case "edit": case "hashline_edit": {
+      const p = a.path ? String(a.path) : ""
+      const extras = [
+        a.offset ? `offset ${a.offset}` : "",
+        a.limit ? `limit ${a.limit}` : "",
+        name === "edit" && a.old_string ? `old: ${String(a.old_string).replace(/\s+/g, " ").trim().slice(0, 30)}` : "",
+      ].filter(Boolean).join(", ")
+      return p ? `"${p}"${extras ? " · " + extras : ""}` : extras
+    }
+    case "grep": case "glob": case "code_search": case "doc_search": case "search": {
+      const pat = a.pattern ?? a.query ?? ""
+      const p = a.path ? ` in "${a.path}"` : ""
+      return `/${String(pat)}/${p}`
+    }
+    case "ls": {
+      const p = a.path ? String(a.path) : "."
+      return a.filter ? `${p}  (filter: ${String(a.filter)})` : p
+    }
+    case "websearch": return String(a.query ?? "")
+    case "subagent": case "coder": case "explore": case "plan": case "eng-coder": case "eng-designer": {
+      const task = String(a.task ?? "").replace(/\s+/g, " ").trim()
+      if (task) return task.slice(0, 60) + (task.length > 60 ? "…" : "")
+      // action-only 调用（status ∕ observe ∕ send ∕ cancel ∕ escalate ∕ consume-design…）无 task——action 兜底（2.4 批）
+      return a.action ? `(${String(a.action)})` : ""
+    }
+    case "advisor": return String(a.type ?? "review")
+    case "read_image": return String(a.path ?? "")
+    case "question": return String(a.question ?? "").replace(/\s+/g, " ").trim().slice(0, 60)
+    case "memory": {
+      // §6 action-routed summary (D-M5): one readable line per action
+      const action = String(a.action ?? "")
+      if (action === "put") return String(a.title ?? "")
+      if (action === "search") return String(a.query ?? "")
+      if (action === "list") return [a.layer && `layer ${a.layer}`, a.type && `type ${a.type}`, a.keyword && `kw ${a.keyword}`].filter(Boolean).join(" ")
+      if (action === "delete") return a.id ? `id ${a.id}${a.layer ? ` (layer ${a.layer})` : ""}` : `batch ${a.layer ?? ""} ${a.type ? `type ${a.type} ` : ""}${a.keyword ? `kw ${a.keyword}` : ""}`.trim()
+      if (action === "clear") return `clear ${a.layer ?? ""}`
+      return action || JSON.stringify(a)
+    }
+    case "lsp": return [a.subcommand, a.uri].filter(Boolean).map(String).join(" ")
+    case "repo_outline": return a.path ? String(a.path) : ""
+    case "checkpoint": return [a.checkpointAction ?? a.action, a.checkpointId, a.path].filter(Boolean).map(String).join(" ")
+    case "git": return [a.action, a.ref, a.name, a.message].filter(Boolean).map(String).join(" ").slice(0, 60)
+    default: {
+      // MCP 工具 ∕ 未知工具：单行紧凑 JSON（与卡片头原始 JSON 截断口径同族）。硬上限 160：
+      // 超大 arguments（如 execute 的千字符 code）绝不进单行头。截断 = 简版切片（见档头差额）。
+      const s = JSON.stringify(a)
+      return s.length > 160 ? s.slice(0, 156) + "…" : s.length > 80 ? s.slice(0, 78) + "…" : s
+    }
+  }
+}

package/tool-docs/advisor.md

@@ -0,0 +1,9 @@
+Run an independent review of your work. `type` is REQUIRED — one of exactly two values: 'design' reviews design / requirement documents BEFORE implementation (documents=[...] with the explicit doc paths; plus batchDoc when a batch record is in flight); 'code' reviews the code you changed AFTER implementation (paths=[...] to scope files/directories; documents=[...] adds acceptance-criteria context). A call without a type (or with a conflicting object.type) is refused — no default, no silent fallback.
+
+The advisor is an independent read-only sub-agent (explores the codebase, reads files, traces callers via grep/lsp). Code review converges: round 1 full review → round 2 verifies the agent's fix claims → round 3+ re-checks only the fix claims. Design review is a single pass against methodology and requirements. Criteria come from .thincoder/advisor.md (if present) or sensible defaults. After the review you MUST produce a response table (format = discipline rules); on all-clear, call verify.
+
+object={type,target,status,reason,exclude} optionally anchors the review target — mechanically injected at the start of the review message; absent = no injection.
+
+ASYNC (depth 0 only): the review runs in the BACKGROUND by default — ack immediately, the report arrives automatically in a digest turn. One shared pool (agent.poolLimits.advisor, default 4 — configurable via /config 并发池 or config.json; pool-full and same-scope launches are refused stating the current limit) — launch reviews one at a time. Inside a child (depth>0) reviews are always synchronous (async:true rejected).
+
+Returns the verdict: all-clear (call verify) or a findings list to fix.

package/tool-docs/batch.md

@@ -0,0 +1 @@
+Batch-record lifecycle tool (一段一作者 — six append-only sections, one author each). actions: create (depth-0 only — write a new six-section skeleton record; pass path + topic + source) · append (add text to the END of YOUR section — existing lines are never rewritten or deleted) · status (update YOUR section's `**状态行**：` line — the value must carry exactly ONE legal keyword of your section's STATUS_WORDS entry, decorated only by surrounding symbols / a trailing ISO date / whitespace; prose goes to the separate `note` field, which lands as a parenthetical) · close (depth-0 only — freeze the record: §1 → 「已收口 <date>」, every further write is refused). Identity fixes what you may write (段白名单): main agent (depth 0) — append §1/§4/§6, status §1 only, create/close; eng-designer — §2; eng-coder — §5; design review (review binding) — §3. A write outside your own section is refused. Skeleton placeholders (dead literals — `#<编号>` / `<板块>` and the older `<BATCH-ID>` / `<讨论来源>`) in the record header or in your target section block append/status: fill them first (the main agent fills the header right after create); `<§N 模板占位：…>` template lines are legal and never blocked. Target record: sub-agents and design reviews have NO path parameter in practice — the record arrives via the spawn binding / the review instance key (passing path is refused); depth-0 MAY pass path (若传则须可读), omitting it picks the unique in-flight record (0 or ≥2 in flight ⇒ refuse — pass path). A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped). Credential values are stripped mechanically before writing (never write a token or designId value). Failures are hard and visible (no silent fallback): if a write is refused or fails, say so in your report — “§× 未写入”.

package/tool-docs/code_search.md

@@ -0,0 +1 @@
+Search the project's source code for relevant code. Use this to find functions, classes, or code patterns across the codebase. Returns matching code chunks with file paths and line numbers. Prefer doc_search for the intended design (design docs, conventions); code_search for the implementation as written. For what was said in a session (conversation/chat history), use read_history.

package/tool-docs/consult_start.md

@@ -0,0 +1,5 @@
+Start a parallel multi-model consultation (会诊) for a hard problem you are stuck on (repeated failures, no headway). Call it directly when the user asks for 会诊 / consult — an explicit user request applies even if you are not 'stuck'.
+
+Several configured models (agent.consultModels — at most 5; an unconfigured pool is an explicit error) analyze the same problem INDEPENDENTLY and in parallel. Non-blocking: returns immediately with a consult id; the consultants keep running in the background across turns. When EVERY model has replied (or failed), the full verdict text is delivered to you automatically — as a system reminder at the next run start, or digested on its own while the session is idle — judge and adopt each opinion yourself with your own tools (opinions are suggestions, not gates). To stop a session early (user changed their mind / wants the tokens back), call consult_stop(id) — a stopped session delivers no digest.
+
+The brief should carry the symptom, what you already tried (the failure trail), and entry-point files; do NOT paste raw error logs — consultants pull the main session history themselves via their main_history tool.

package/tool-docs/consult_stop.md

@@ -0,0 +1,3 @@
+Cancel a still-running consultation session (会诊) — the user changed their mind, the problem resolved, or you want the tokens back. Aborts every consultant that is still running; a stopped session delivers NO digest (its already-collected partial replies are dropped). Sessions that finished on their own are no longer cancellable — their verdict text is delivered automatically.
+
+Returns JSON {abandoned: <pending count>, cancelled: true} — or {error: "unknown consult id"} (already finished/cancelled).

package/tool-docs/context.md

@@ -0,0 +1,7 @@
+Manage your own context window — see how full it is, drop stale tool output, or compact the earlier conversation into a summary at a moment of your own choosing.
+
+- action='stats': current usage — total vs the compaction threshold, per-segment shares, and how much is prunable / reclaimable.
+- action='prune': drop the CONTENT of stale tool results (older than the protected tail) and replace it with a short stub — tool pairing stays intact, the session record keeps the full text, and the tool can simply be re-run.
+- action='compact': compact the earlier conversation now, with 'focus' — write what the UPCOMING work needs (1–3 sentences: goal, files, constraints that must survive); the summary is weighted toward that focus and the current task list + goal are attached automatically. It runs at the next safe point (before the next request — never mid-exchange) on the same chain as automatic compaction: same summary chain, same panel, same failure chain (3 consecutive failures → deterministic truncation). The receipt carries this session's record path.
+
+Nothing here runs on its own — the automatic threshold compaction stays in place as a fallback; whether to compact is your call. Errors come back as 'Error: ...' and change nothing.

package/tool-docs/doc_search.md

@@ -0,0 +1 @@
+Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules. Prefer this over code_search when you need to understand the project's intended design rather than existing implementation. Returns matching doc chunks: path, heading, line range, relevance score, content excerpt. For what was said in sessions (conversation/chat history — decisions, rulings), use read_history.

package/tool-docs/edit.md

@@ -1,4 +1,4 @@
-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.
+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 applies to content-based edits only: 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`
@@ -9,22 +9,11 @@ Edit a file as a patch — targeted by content or by line number. Two targeting
 - 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
+**Batch multiple changes into ONE call via the `edits` array** (preferred over N single edit calls) — same file or across files; atomic: any failure writes nothing. One permission ask, one undo unit, and one turn instead of N. Per-entry shape and targeting are in the schema.
 
 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/eng.md

@@ -0,0 +1 @@
+Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents. Returns the mode state — 'Engineering mode activated/exited' (an already-active state is acknowledged).

package/tool-docs/execute.md

@@ -3,15 +3,7 @@ Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real ch
 **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)
+- `node --test <file>` / `node --check <file>` → execute with scriptFile + nodeArgs (timeoutMs up to 600000 — long suites fit)
 
 Notes:
 - `console.log(...)` prints to the result; objects are JSON-stringified where needed.

package/tool-docs/git.md

@@ -1,54 +1,28 @@
 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.
+**Route to git instead of bash** — every sub-command maps to the same-named action: status / log / diff / show / 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.
 
-- 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
+- diff: unified diff since last commit (`staged` — staged only; `ref` — compare a commit/branch; `path` — scope).
+- status: working tree state — staged / unstaged / untracked / conflicts.
+- log: recent commits (`count`, `oneline`, `path` — one file's history).
+- show: one commit with --stat (`ref`, default HEAD).
+- add: stage files — `path` (granular) or all changes.
+- rm: untrack a file/dir (`git rm --cached` — kept on disk; `path` required).
+- commit: `message` required. With `path` → `git commit --only <paths>`: commits those files' working-tree content only, atomic — other staged batches are NOT mixed in; without → add -A + full commit. New (untracked) files: `git add` them first (staging extra is safe — `--only` commits only the listed files).
+- push / fetch / pull: sync with remote — `remote`, `ref` (space-separated for multiple); `tags` for --tags.
+- tag / branch: manage via `tagAction` / `branchAction` — list / create (name, optional ref) / delete (snapshots first); branch also switch (name).
+- checkout: switch to `ref`; with `path`, restore a file from the index (discards its working-tree changes — snapshots first).
+- restore: restore a file from index/HEAD (`path` required; `staged` restores the staged copy — snapshots first).
+- stash: `stashAction` push (message) / pop / list (pop snapshots first).
+- reset: `ref` (default HEAD), `mode` soft / mixed / hard — hard drops working-tree changes (snapshots first).
+- revert: revert a commit (safe, `ref` default HEAD); merge: `ref` — conflicts come back for you to resolve; cherry-pick: `ref`.
+- rebase: `rebaseAction` start / abort / continue (snapshots first).
+- ls-remote: light remote-ref check — read-only, network (`remote`, optional `ref`).
+- clone: `remote` required (URL or local path), optional `path` (target dir); init: create a repo in the current workdir.
+- remote: manage remotes — `remoteAction` list / add / remove / set-url (`remoteUrl` for add / set-url).
+- clean: remove untracked files/dirs — `dryRun` previews (-n; the real clean snapshots first).
+- switch: switch branch (`name` required; `create` = -c); apply: apply a patch (`path` required); archive: tar of a `ref` (`path` required, output file); blame: file blame (`path` required); mv: rename/move (`path` + `dest` required); worktree: `worktreeAction` list / add / remove.
+- checkpoint: local snapshots — `checkpointAction` list / create / rewind / cat / versions (`checkpointId` for rewind / cat).
+- Destructive ops (checkout -- path / restore / reset --hard / stash pop / branch|tag delete / clean / rebase) auto-snapshot first; restore a snapshot via `checkpointAction=rewind`.
+- Failures come back as errors — `git <action> failed: <reason>` — nothing is silently swallowed.
+- `filter` narrows any read-only action's output (case-insensitive regex); `config` (git -c overrides, e.g. a proxy) applies to the network actions (push / fetch / pull / ls-remote / clone). Other parameter defaults and applicability live in the schema.

package/tool-docs/goal.md

@@ -0,0 +1,6 @@
+Manage a long-running autonomous goal.
+action='set': create or replace the goal — must have a verifiable completion criterion (a machine-checkable proof, not vague effort).
+action='complete': mark achieved — only after the criterion's check has actually passed.
+action='blocked': report an impasse (requires 'reason') — only after 3 genuine attempts.
+action='cancel': abandon the goal.
+Returns a status line — the goal set/updated/completed/blocked/cancelled confirmation, or Error: ... with the reason.

package/tool-docs/ledger_add.md

@@ -0,0 +1 @@
+台账新增条目（写命令，仅主 agent）——入待讨论（六态状态机入口）。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）。

package/tool-docs/ledger_close.md

@@ -0,0 +1 @@
+台账收口（写命令，仅主 agent）——勾销：待核销 → 已核销；追认核销：待讨论 / 待设计 → 已核销（须已有 evidence，缺则拒）；在途 → 已核销 不可跳（仍经 待核销）；撤回：任意态 → 已废弃。归档 = 软删除（写 closed_at，行保留）。

package/tool-docs/ledger_count.md

@@ -0,0 +1 @@
+台账计数单源：未决四态（待讨论 / 待设计 / 在途 / 待核销）COUNT(*)，只读、全角色可用。

package/tool-docs/ledger_query.md

@@ -0,0 +1 @@
+台账查询（需求池 / 技术待办）——SQLite 行集，只读、全角色可用。未决四态 = 待讨论 / 待设计 / 在途 / 待核销；已核销 / 已废弃 = 归档态（软删除，行保留）。过滤参数缺省 = 全部行。

package/tool-docs/ledger_update.md

@@ -0,0 +1 @@
+台账更新条目（写命令，仅主 agent）——状态迁移按六态允许迁移表：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外迁移被拒。status 缺省 = 仅更新字段。

package/tool-docs/main_history.md

@@ -0,0 +1 @@
+Read the main agent's conversation history — what has been tried, the exact errors, recent context. Ground your analysis in the actual failure trail instead of guessing. Output is capped (~60k chars — older messages are trimmed with a note).

package/tool-docs/memory.md

@@ -0,0 +1,10 @@
+Manage long-term memory in ONE tool — the action parameter picks the operation:
+- search — find knowledge saved in previous sessions; each result row carries [layer] + entry id (the id's prefix = the layer)
+- put — save knowledge for future sessions; type = rule (coding standards) / knowledge (project facts) / decision (architecture decisions) / pattern (debugging/workflow patterns)
+- list — inventory what memory holds; one row per entry: [layer] id [type] title (date); a truncated list notes the full count
+- delete — SINGLE: {id, layer} removes the entry shown in put/search/list output — layer is optional: passed, it is validated against the id prefix (a mismatch is refused — guards against deleting the wrong entry); omitted, the id prefix routes the delete (any id from put/search/list is directly deletable). BATCH (no id): {layer, type and/or keyword} removes every matching entry in that layer — layer + at least one of type/keyword required; without confirm:true it returns the count + preview instead; layer-wide wipes without filters are refused on every layer
+- clear — {layer: "personal", confirm: true} wipes ALL personal memory entries. clear is personal-only: a missing layer or a project/team layer is refused (use delete batch filters on shared layers)
+Layer = the memory tier: personal (private) / project (shared via this repo's .thincoder/memory/) / team (CLI only, git-synced); the [layer] tag, the id prefix, and the layer parameter are the same concept — pass a result row's [layer] as layer.
+Deleting project/team entries removes the local markdown file and its index row — team deletion is local only; a later team sync may resurrect the file while the remote still has it.
+Save bugs, conventions, and preferences here — they persist across sessions.
+Session message history (what was said in this or past sessions) is NOT in memory — search session messages with read_history.

package/tool-docs/notify_parent.md

@@ -0,0 +1,9 @@
+A one-way channel to your PARENT (the agent that spawned you) — you are a subagent, so there is no user to ask. Queue a message on the parent's side; your turn is not interrupted and nothing is consumed from it.
+
+- kind:'ask' — a question whose answer changes your next step and that you cannot answer from the materials you can read (task book / design doc / repo). The parent replies with subagent action:'send'; you receive it as an ordinary instruction at your next turn boundary. One ask at a time while a previous one still waits in the parent's queue.
+- kind:'note' — an FYI that needs no answer (a premise you found broken, a conflict you resolved and want visible early).
+- NON-BLOCKING: returns immediately — keep working on the unaffected parts, keep the affected part pending. No fetch, no polling; finish first = report the unanswered part as not done.
+- SYNCHRONOUS SPAWN: if the parent is blocked on your run, nothing can be sent back — `send` reaches only a RUNNING ASYNC child; the message is read when the parent's call returns (it may re-spawn you with an answer). Do not idle-wait.
+- Out of scope: naming / implementation / wording details, anything a read or a command would answer, trade-offs the task book already states — use the stop-and-report discipline, not this channel.
+- Availability: subagents only (depth > 0). At depth 0 you talk to the user through your normal reply or the question tool.
+- Limits: message ≤1,500 chars; the parent's in-flight queue holds ≤20 messages — exceeding either is an explicit error (nothing is silently dropped).

package/tool-docs/peer_instances.md

@@ -0,0 +1 @@
+peer_instances — read-only: list other live ThinCoder instances sharing this workspace cwd. Returns [{ pid, end, sessionId, slots }]; never includes self; pure read — writes nothing.

package/tool-docs/plan.md

@@ -0,0 +1,5 @@
+Enter or exit plan mode.
+In plan mode you are restricted to READ-ONLY tools: read files, search code, run read-only shell commands.
+Use plan mode before complex multi-step tasks — explore the codebase, design the architecture, present a plan to the user.
+Exit plan mode to present the plan for the user's approval; implement only after they approve.
+For simple single-file edits, skip plan mode and just make the change.

package/tool-docs/process.md

@@ -1,10 +1,14 @@
-List running processes, optionally filtered by name. Returns process name / PID / memory.
+List running processes, optionally filtered by name — or kill a process tree / a background bash task. List returns process name / PID / memory; kill returns a one-line confirmation.
 
 **Route to process instead of bash:**
 - `tasklist` (Windows) / `ps aux` (POSIX) → process
 
 Parameters:
-- name (optional): substring filter (case-insensitive), e.g. "node", "python"
+- action (optional, default 'list'): list — show running processes; kill — terminate a process tree (target: pid) or a background bash task (target: id)
+- name: (list) substring filter (case-insensitive), e.g. "node", "python"
+- pid: (kill) process id — the whole tree is terminated (taskkill /T /F on win32; POSIX group kill)
+- id: (kill) background bash task id — the `bash#N` from the bash async ack; its process tree is terminated, the entry leaves the pool, and no digest will arrive (the log so far stays readable)
 
 Notes:
-- List-only. To kill a process, use `bash taskkill /PID <pid> /F` (Windows) or `bash kill <pid>` — and confirm with the user first.
+- kill is destructive: pass exactly one target (pid or id — never both), and it goes through the same approval gate as other destructive actions — confirm before killing.
+- Repeating a kill is idempotent (same confirmation, no double kill); an unknown or already-finished bash task id comes back as `Error: ...`.

package/tool-docs/question.md

@@ -13,4 +13,5 @@ Notes:
 - 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.
+- Ask here when no default can carry the work forward (new scope, a ruling on a criterion) — this blocks; when a reasonable default exists, ask in your ordinary reply text and keep going — a reply arriving while you work steers the work from there.
 - 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_history.md

@@ -0,0 +1,7 @@
+Query message history — THIS session by default, any session on disk with `path`. Recall what was said or done earlier: design decisions, tool-call timing, past rulings.
+
+Default (no path): this session's full record (never compacted, audit-complete). Filters combine with AND (role / keyword / tool / since-until / limit / direction — semantics per parameter; keyword with path="all" matches FTS words / phrases). Returns a JSON array in chronological order: [{ts, role, name?, tool_call_id?, content (≈500 chars, truncated marker), tool_calls ([{name, arguments}] — arguments capped at 300 chars)}]. Messages without ts return ts:null; content is truncated — the full text is in the session file.
+
+Cross-session (`path`, optional): a session file path deep-queries THAT session with the same filters (relative paths resolve against the project cwd) — from the derived session index when it covers that session, otherwise from the session file itself (a file over 50,000 messages or 200,000 lines is refused as "session too large"). "cwd:<dir>" lists that directory's session slots (slot + file path + title + count + updatedAt; copy one into path= to deep-query it). "all" searches every INDEXED session (cross-project; rows carry session.file) — sessions never indexed yet are invisible (query them with path=<file>, or index first with the CLI `thincoder session index --rebuild`).
+
+检索/记忆族选哪个：查**本会话**说过/裁定过 → read_history（默认）；查**别的会话/项目**旧对话 → read_history 带 path/cwd 参数；查**本 run 改过哪些文件** → recent_changes；查**跨会话已存知识/约定**（memory）→ memory search；查**项目设计文档** → doc_search；查**代码实现** → code_search；查 git 历史快照 → checkpoint cat/versions。read_history 只查会话消息——文件级改动用 recent_changes——知识与约定用 memory——互相不替代。

package/tool-docs/recent_changes.md

@@ -0,0 +1 @@
+Show files modified in this agent run (write/edit/insert_after/delete). Use when you need to remember which files you've already touched — during long multi-file tasks, it's easy to lose track. This is scoped to the current run, unlike git status which shows all uncommitted changes. For session-level history (what was said in a session), use read_history.

package/tool-docs/repo_outline.md

@@ -0,0 +1 @@
+Show the project's file dependency outline: which files import/export from which, and what symbols they export. Use when you need to understand the project structure, find where a function is defined, or see what files depend on a module. Pass a path to focus on a single file's relationships. Find code by keyword or snippet with code_search.

package/tool-docs/settings.md

@@ -0,0 +1,6 @@
+Adjust ThinCoder runtime configuration — persisted to config.json AND hot-applied to the live agent config.
+Actions: list (all keys + values, flattened) | get <key> | set <key> <value> — dot paths into config.json, any nesting.
+set persists to disk (only the set key is written — defaults are never baked in) and takes effect in the running session immediately (turn-boundary keys apply next turn); the value survives restarts.
+Known keys are type-checked: scalar keys against the built-in defaults (agent.maxTurns a number, traces.enabled a boolean); keys whose default is null against their real consumption shape — defaultModel "provider:model", agent.subagentModel / shell non-empty string, memory.team object with a repo — so a value the app would silently drop is refused (null clears the key: the entry is removed from config.json and the built-in default applies; string-typed keys refuse null — no "unset" state to fall back to). Unknown keys under a known section are stored as given.
+SENSITIVE keys (path segment matching apiKey/key/token/secret/password/authorization/auth/cookie/credential, or any key under a headers/env segment) are NEVER echoed in plaintext — list/get/set replies show ••••（masked）; setting a sensitive key is allowed and stored, but never echoed back.
+list/get are read-only (planMode ok, no approval); set is a side effect (approval gate). The /config TUI command is the human equivalent.

package/tool-docs/skill.md

@@ -0,0 +1,5 @@
+Load a project skill from .thincoder/skills/.
+Skills contain reusable instructions, workflows, or reference material.
+Use this when the user references a skill by name, or when a task matches a known skill's description.
+Call with action='list' to see available skills; call with action='load' and name=<skill> to activate one.
+Returns the skill list ('list'), the load confirmation ('load' — instructions arrive in the next message), or Error: ... with the available skills.

package/tool-docs/subagent.md

@@ -0,0 +1,31 @@
+ONE tool, EIGHT actions — pick by what you need:
+
+- action:'spawn' (DEFAULT): run a sub-agent in its own isolated context — its reads, searches and tool calls never reach your history; only the final report comes back. Spawn MULTIPLE subagents in the SAME response for parallel work — they run concurrently.
+- action:'status': NON-BLOCKING progress query — returns immediately, consumes nothing, never fetches. Pass the spawn id for one child (role, state: running|queued|done, model, elapsed, turn, position, plus a touched-files summary — first 5 + a count) or omit it for a pool overview — see what a running child has changed BEFORE cancelling it. Background advisor reviews share this surface (pass the review id — role:'advisor', reviewType/round/elapsedSec, same shape).
+- action:'observe': SEE what a running async subagent is DOING right now (progress vs stuck) — pass the id; returns state, turn, the tool(s) executing right now (omitted when none), and the last N one-line turn summaries, newest first (default 5, via recent). Readonly; running/queued/done all answer — queued returns a placeholder, done gives the activity summary only, NOT the report (it rides the auto channel). Judge stuck vs progressing BEFORE cancelling or steering.
+- action:'send': STEER a running async subagent mid-flight — id + message (a direction, e.g. "check X, don't fixate on Y"). The child consumes it at its next turn boundary as an ORDINARY user instruction (non-interrupting; its discipline is unchanged — guidance, not a deviation waiver); returns {id, status:'delivered', queued}. Only RUNNING async children are targetable — sync/queued/settled/unknown error clearly; if the child settles first, its report carries an 'undelivered' note.
+- action:'escalate' (飞刀): hand an implementation task to a STRONGER model from your consult models; it gets WRITE access and does the work itself, then returns a post-op report (what changed, why, verification). Escalate EARLY, when the task calls for stronger hands (complex refactors, intractable bugs, intricate algorithms — or beyond your comfortable ability). Not available in engineering mode (implementation goes through eng-coder). Default-async at depth 0: ack {id, role:'escalate', status:'running'} returns immediately; the report arrives automatically with its mutations merged into your bookkeeping (pooled with the other role-domain spawns).
+- action:'cancel': STOP ONE background subagent — the id from the spawn return is REQUIRED (a blanket cancel is unsupported; Ctrl+C stops everything). Running aborts immediately ({id, status:'cancelled'}); queued is removed ({id, status:'cancelled', was:'queued'}; later positions shift). Other children and the session keep running. Cancel is a last resort: verify alarming signals with reliable checks (git/node — not guesses) first, and prefer scoped recovery — a running child's in-flight work dies with it, partial changes stay unmerged and unaudited. Background advisor reviews cancel the same way (pass the review id — no token is issued for a cancelled review).
+- action:'consume-design' (engineering mode, parent side): chain-terminal token consumption — after the delivery is verified and the chain closes out, consume this design's token slot (designId; optional for a single-design session). A consumed slot mechanically rejects further spawns for the same designId — new work (deviation fixes included) needs a fresh design review and token. Idempotent (unknown/already-consumed = a no-op notice). Do NOT call while the chain is still open — fix rounds reuse the same slot.
+- action:'panel': DIAGNOSE + fix the subagent panel (the collapsible blocks the user sees; headless/VS Code degrade to a 'no panel' pool view). view (default): the live blocks (key, role, status: running|done|awaitingDigest) exactly as the user sees them — digested-stuck entries carry digested:true. freeze: pass a digested-stuck block key (e.g. 'eng-coder#9' — {action:'panel', freeze:'role#N'}) to reclaim it into the conversation — passes ONLY for awaitingDigest blocks with no live pool entry and no pending report (a still-pending report would break the digestion order — refused).
+
+Why delegate? The child's noise never reaches your window — delegation keeps your context lean and the child focused; parallel children save wall-clock time, and coder/eng-coder children self-review (verify + advisor) before their reports arrive.
+
+Available roles (exposed per mode; the role is REQUIRED for action:'spawn' — a missing or misspelled role is refused):
+- explore — read-only search & analysis (read/search family); no git context — evidence comes from reads and the task book; its report must list what it searched and what it did NOT find. Say quick / medium / thorough (default medium).
+- plan — read-only planning; NEVER edits; returns a step-by-step plan.
+- coder — full implementation; the parent's complete read/write/execute toolset plus verify and advisor self-review. Its report carries a delivery table, one row per requirement (Done / Simplified / Not done — no deferred column).
+- eng-coder — engineering mode only (replaces coder): same toolset plus the design-driven methodology overlay; its delivery protocol (implementation → audit → self-fix → advisor re-review → converged delivery) runs fully inside the child. REQUIRES a valid designToken from a passed advisor(type='design') review (its reply also echoes a designId — pass it: required to pick between concurrent designs, optional for one; echo it back in the delivery report). REQUIRES a batchDoc — the batch record path, the task book this spawn implements (refused without it or when it does not resolve to a readable file).
+- eng-designer — engineering mode only: the SOLE author of the requirements/design documents and of the batch record's design section. Writes no implementation code, does not edit prompts, does not fire reviews, needs NO designToken. Surveys on its own; may only spawn read-only explore children (sync, ≤6 per batch). REQUIRES a batchDoc (same gate as eng-coder).
+
+Mode filtering: normal mode exposes explore/plan/coder; engineering mode exposes explore/eng-designer/eng-coder — off-mode roles are refused mechanically (enums filtered at assembly; the spawn gate re-checks).
+
+Async spawn: top-level spawns are async by default — never pass async:false at depth 0 (the spawn returns {id, status:"running"} immediately; the report arrives automatically; if your next step needs it, end the turn and let the digest deliver it — do not poll; the explicit async:false is a mechanism parameter, not for model use). Inside subagents (depth>0) spawns are always synchronous. Async spawns are pooled per role domain — 4 concurrent eng-coders plus 4 concurrent other-role spawns by default (agent.poolLimits overrides both); a full domain queues further spawns with a position while the other keeps starting.
+
+Task scheduling: declare files (the file paths this task will modify) and dependsOn (ids from prior async returns whose outcome this task needs) to let the scheduler order your spawns. Overlapping-file tasks serialize and dependents start in order: a conflicting/dependent spawn queues (position/reason) and auto-starts when the conflict clears / the dependency settles (cancel to drop). A cancelled/failed dependency leaves it queued marked "dependency cancelled" until you decide (AUTO sessions auto-start). Unknown ids error; a consumed id counts as satisfied. Omit both for a plain immediate spawn (no scheduler involvement).
+
+Writing the prompt:
+- The child starts with zero context — brief it like a colleague who just walked in: goal, what you already know, the specifics.
+- Put exact paths and commands in — do not make it search for what you already know.
+- Do not delegate understanding: resolve the paths/line numbers the task hinges on first.
+- Once it runs, leave that scope to it — don't redo its searches in parallel or finish manually midway.

package/tool-docs/task.md

@@ -0,0 +1,7 @@
+Plan and track a task list for complex multi-step work.
+Each call replaces the entire list.
+Keep exactly one item in_progress at a time; mark items done as you complete them; never mark done if tests fail or work is partial.
+Statuses: pending | in_progress | done — synonyms (completed/finished/complete, todo/open/waiting, active/running/working, …) are accepted and normalized with a warning.
+IMPORTANT: title is required and must be a non-empty string — items with empty titles are silently dropped.
+For cross-session / project-level tracking, use `/ledger`.
+Returns the updated task list (or the new item's ID on add).

package/tool-docs/timer.md

@@ -0,0 +1,6 @@
+Set a timer before you start analyzing code.
+When the timer fires, a system reminder will be injected suggesting you try running code or adding debug logs.
+Use this to enforce a thinking budget: you get N seconds to reason, then the timer reminds you to act.
+Returns the set confirmation — the reminder fires at the deadline.
+Delivery: while a turn is running it lands at the next step boundary; when the session is idle it is delivered on the spot and starts a turn — the idle wake is available on the CLI / VSC / desktop foregrounds and suspension windows (headless is structurally unsupported); other paths keep the step-boundary behavior.
+A pending timer survives across runs; at most 8 timers may be pending at once, and further timer calls are rejected until some expire.

package/tool-docs/verify.md

@@ -0,0 +1 @@
+Generic pre-completion verification gate — language/framework/project agnostic. verify does NOT run any test/verification command for you and does NOT require a test per change. You DECLARE your verification status via the verification argument ({ status: 'passed' | 'failed' | 'skipped', command?, summary? } — effects per parameter): the declaration is self-reported evidence — verify only mechanically gates on it ('passed' → allowed; 'failed' → blocked; 'skipped' → allowed but needs a reason). Whether/how to verify is described in natural language in the project's AGENTS.md and is decided + executed by you. The report also carries the changed files (git diff), an advisory node --check hint on changed .js/.mjs (not gating), the task list, and a self-review checklist. Call this BEFORE declaring a coding task complete — do not say 'done' until verify passes.

package/tool-docs/wait_for.md

@@ -5,9 +5,10 @@ Parameters:
   - `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
+  - `bash id:N done` — background bash task N (the id from the bash async ack, `bash#N`) has finished — settled, or already left the pool (nothing left to wait on)
   - `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.
+  - The agent-internal conditions (advisor / subagent / consult / bash) 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)
 

package/tools/bash.mjs

@@ -41,13 +41,16 @@ function posixSyntaxHint(command) {
 // ====================================================================
 // bash — command execution with safety gates
 // ====================================================================
+// #9：异步 ∥ 后台执行（`async: true`——池/起跑/结算/杀单点 = `agent-tools/bash-async.mjs`；
+// 本档 = 薄接线：参数面 + depth 第二道 + 起跑 ack）。同步径（缺省）**逐字零变**。
 
 /**
  * Build environment for child process.
  * Passes through all parent env vars, with non-interactive overrides (EDITOR/PAGER/TERM).
  * Sets PYTHONIOENCODING on Windows to override GBK default for Python scripts.
+ * #9：导出面 = 后台径（`agent-tools/bash-async.mjs`）同源复用（env 单源——勿另建副本）。
  */
-function buildBashEnv() {
+export function buildBashEnv() {
   const isWindows = process.platform === "win32"
   return {
     ...process.env,
@@ -238,8 +241,9 @@ export const bashTool = {
     type: "object",
     properties: {
       command: { type: "string", description: "Shell command to execute" },
-      timeout: { type: "number", description: `Timeout in ms (default ${BASH_TIMEOUT_MS})` },
-      filter: { type: "string", description: "Optional: only return output lines matching this regex (case-insensitive)" },
+      timeout: { type: "number", description: `Timeout in ms (default ${BASH_TIMEOUT_MS} for synchronous runs; background runs have no default — an explicit timeout still applies)` },
+      async: { type: "boolean", description: "Run in the background (default false): returns an ack at once (bash#<id>, log path) and the result arrives as a digest when the process exits. Depth-0 only." },
+      filter: { type: "string", description: "Optional: only return output lines matching this regex (case-insensitive; synchronous runs only)" },
     },
     required: ["command"],
   },
@@ -250,7 +254,28 @@ export const bashTool = {
     // guard anyway. Instead: snapshot every uncommitted file first, then ALLOW
     // the command. The snapshot makes the rollback reversible (defense in depth:
     // the wide matcher also covers variants like `git checkout HEAD -- .`).
+    // 前置两件（guard ∥ hint）同步 ∥ 后台两径同保留（#9）。
     const guard = await gitGuardSnapshot(args.command, ctx.cwd)
+    const hint = posixSyntaxHint(args.command)
+    if (args.async === true) {
+      // depth 第二道（schema 主门 = agent/helpers.mjs excludeSubagentTools 删参——异步面只到
+      // 子代理实装亦拒：留一条显式文案，不静默转同步）。
+      if ((ctx.depth ?? 0) > 0) {
+        return "Error: bash async is depth-0 only — a child agent has no background task pool (run the command synchronously)"
+      }
+      // 动态 import（W8 契约②：agent-tools 静态链达 node:sqlite——端壳静态闭包须保持零命中）。
+      const { launchBgTask } = await import("../agent-tools/bash-async.mjs")
+      const launched = await launchBgTask(ctx.agent, ctx, {
+        command: args.command,
+        timeout: args.timeout ?? null,
+        shell: ctx.agent?.config?.shell ?? null,
+      })
+      if (launched?.error) return `Error: ${launched.error}`
+      // filter 对后台径不适用（无同步结果可滤）——显式注记，不静默丢参。
+      const filterNote = args.filter ? "\n[note: filter applies to synchronous runs only — for this background task read the log and grep it instead]" : ""
+      const body = `${hint ? `${hint}\n` : ""}${launched.ack}${filterNote}`
+      return guard ? `${guard.notice}\n\n${body}` : body
+    }
     const result = await runBash(args.command, ctx.cwd, {
       timeout: args.timeout ?? BASH_TIMEOUT_MS,
       signal: ctx.signal,
@@ -258,7 +283,6 @@ export const bashTool = {
       shell: ctx.agent?.config?.shell ?? null,
     })
     const filtered = args.filter ? applyLineFilter(result, args.filter) : result
-    const hint = posixSyntaxHint(args.command)
     const body = guard ? `${guard.notice}\n\n${filtered}` : filtered
     return hint ? `${hint}\n${body}` : body
   },