thincoder 0.12.40 → 0.12.42

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 本文件记录 ThinCoder CLI 的发布历史。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，版本遵循[语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.12.42] — 2026-08-24
+
+### Changed
+
+- **工程模式发起权归用户**：设计评审只能由用户发起——agent 准备设计后只呈递+提醒「设计就绪」，不再自行调 advisor（此前 agent 可自行判断"讨论完了"直接提交评审并开发，属越权）；评审打回后每轮呈递发现+修复建议、用户逐条拍板再改，不再自行修完重送
+- **交付 code review 改为自动流程节点**：eng-coder 返回后自动评审（不问用户）；工程模式下 guard 推回维持关闭
+- 提示词注意力优化：核心规则开头立纲 + 结尾钉死 + 状态表补「Review fix loop」态；设计文档 ENGINEERING-MODE/WORKLOOP/PROMPT-DECOUPLING 同步
+
+## [0.12.41] — 2026-08-23
+
+### Added
+
+- **git 工具最全扩充**：add（分文件）/push（带 remote/ref/tags）/tag/branch/checkout/restore/stash/fetch/pull/reset/revert/merge/cherry-pick + `workdir`（子目录/多 repo）；破坏性操作先非破坏快照
+- **execute `scriptFile` + `nodeArgs`**：跑 workspace `.mjs` 文件（`node <script>` / `node --test` / `node --check`），不再只能 inline
+- **子agent/advisor 显示使用的模型**（subagent/escalate/consult/advisor）
+- 反向路由：git/execute/grep/ls/read/delete 描述 + discipline「Tool routing」全工具总表
+
+### Changed
+
+- `codemode.mjs` → `execute.mjs`（`codeModeTool` → `executeTool`，与 VS Code 对齐）
+
+### Fixed
+
+- `runGit` `.trim()` 剥掉 porcelain 前导空格导致 unstaged 被误分类成 staged
+- VS Code `snapshotBefore` 破坏性 stash → 非破坏 `git stash create`+`store`
+
 ## [0.12.40] — 2026-08-23
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.12.40",
+  "version": "0.12.42",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/acp/bridge.mjs

@@ -66,7 +66,12 @@ export function buildAcpCallbacks({ sessionId, notify, request, log = () => {} }
   }
 
   const callbacks = {
-    onToken: (text) => update("agent_message_chunk", { content: { type: "text", text } }),
+    onToken: (text) => {
+      // Strip the subagent `[model]` metadata token (role#id/[model]<name>) — it's a
+      // TUI/webview display signal, not conversation content, and must not reach ACP clients.
+      if (/^[\w-]+#\d+\/\[model\]/.test(text)) return
+      update("agent_message_chunk", { content: { type: "text", text } })
+    },
     onReasoning: (text) => update("agent_thought_chunk", { content: { type: "text", text } }),
     onUsage: (usage) => update("usage_update", { usage }),
     onWait: ({ phase, seconds }) => log(`[rate-limit] ${phase} waiting ~${seconds}s`),

package/src/agent-tools/consult.mjs

@@ -177,6 +177,8 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     agent._subAgentCounter = (agent._subAgentCounter ?? 0) + 1
     const subId = agent._subAgentCounter
     const relayPrefix = `consult#${subId}/`
+    // Report this consultant's model to the display layer (each consultant may use a different model).
+    ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (provider.model ?? ""))
     const childCallbacks = {
       onToken: ctx.callbacks?.onToken ? (t) => ctx.callbacks.onToken(`${relayPrefix}${t}`) : null,
       onReasoning: ctx.callbacks?.onReasoning ? (r) => ctx.callbacks.onReasoning(`${relayPrefix}${r}`) : null,

package/src/agent-tools/escalate.mjs

@@ -93,6 +93,8 @@ export const escalateTool = {
     const subId = parent._subAgentCounter
     const tag = label(pick)
     const relayPrefix = `escalate#${subId}/`
+    // Report the escalated model to the display layer (it may differ from the parent's).
+    ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (provider.model ?? tag))
 
     // No wall-clock watchdog — turn cap only, exactly like subagent (the verified write
     // path). Rationale (2026-08-16): a fixed wall-clock aborts NORMAL-but-slow surgery —

package/src/agent-tools/subagent.mjs

@@ -161,6 +161,10 @@ export const subagentTool = {
     parent._subAgentCounter = (parent._subAgentCounter ?? 0) + 1
     const subId = parent._subAgentCounter
     const relayPrefix = `${role ?? "sub"}#${subId}/`
+    // Report the subagent's effective model to the display layer (it may differ from the
+    // parent's). Emitted as a `[model]` metadata token via the relay prefix — the TUI/webview
+    // parse it into the subagent block's header instead of showing it as content.
+    ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (childProvider.model ?? ""))
     const childOpts = {
       onPermissionRequest: childPermission,
       onToken: ctx.callbacks?.onToken

package/src/prompts/discipline.md

@@ -20,6 +20,15 @@ UI & interface design:
 - Free-text for a discrete value forces the user to guess the exact spelling, needs manual validation, and fails silently on typos. This has happened repeatedly (e.g. reasoning-effort levels typed by hand).
 - Free-text is correct ONLY when the input is genuinely open-ended (a name, a path, a message).
 
+Tool routing — use the dedicated tool, not bash:
+- **git operations** → `git` tool (action=status/diff/log/show/add/commit/push/tag/branch/checkout/restore/stash/fetch/pull/reset/revert/merge/cherry-pick; `workdir` for sub-repos). Never run git via bash.
+- **JavaScript** → `execute` (inline code; or `scriptFile`+`nodeArgs` for `node <file>` / `node --test` / `node --check`). Never `bash node -e`.
+- **File reads/searches** → `read` / `grep` / `ls` / `glob` — never `cat` / `type` / `findstr` / `dir` / shell-grep.
+- **File mutations** → `write` / `edit` / `apply_patch` / `hashline_edit` / `insert_after` / `file_ops` (move/copy/rename) / `delete`.
+- **Process / time / sleep / tree** → the dedicated tools (never `tasklist`/`ps`/`date`/`tree` via bash).
+- Each tool's description carries a "Route to X instead of bash" mapping.
+- **bash IS correct for**: package-manager/CLI subprocesses (`npm`/`vsce`/`ovsx`, git-CLI-only flags the tool lacks), servers, interactive/TTY programs, and one-off shell pipelines no dedicated tool expresses.
+
 Review discipline (standard mode only — engineering mode has its own review timing rules):
 - **Advisor:** call after changing code. Must provide scope: `paths` (files/dirs to review) or `documents` (context).
 - **After each advisor review, reply with a response table** — exact header `| # | Action | Detail |` (the runtime extracts this header; keep it verbatim). One row per issue; `#` = the advisor's issue number (`Orig#` on rounds 2+).

package/src/prompts/engineering.md

@@ -4,8 +4,12 @@
 
 You are the ARCHITECT. In this mode your deliverables are:
 1. the requirements + design documents (docs/),
-2. the design review (via `advisor` with `type="design"`),
-3. the approved implementation plan handed to an eng-coder.
+2. the approved implementation plan handed to an eng-coder.
+
+You PREPARE and REMIND — you never FIRE. The design review and the start of
+implementation are both initiated by the user, not by you (2026-08-24
+decision: an agent that judges "discussion is done" by itself and fires
+review + development is not engineering mode).
 
 You do NOT write implementation code yourself. Writing or editing code files
 directly violates this workflow — implementation is done by `eng-coder`
@@ -32,30 +36,39 @@ subagents only.
 2. **Design.** Write the design document in `docs/` (problem statement,
    solution approach, full affected-file list, verifiable acceptance criteria).
    Do NOT open any code file for editing before this document exists.
-3. **Design review.** Call `advisor` with `type="design"`, passing
-   `documents=[...]` — the explicit list of doc paths to review (requirements +
-   design + referenced docs; METHODOLOGY.md is read by the advisor itself).
-   This runs a dedicated design review in an isolated context.
-   - If advisor finds issues: fix the design, re-submit.
+3. **Remind readiness — never self-initiate review.** Present the design
+   summary and say it is ready for review, then WAIT. You do NOT call the
+   advisor yourself — the initiation right belongs to the user: you prepare
+   and remind, the user fires.
+4. **User-initiated design review.** Only when the user asks for it, call
+   `advisor` with `type="design"`, passing `documents=[...]` — the explicit
+   list of doc paths to review (requirements + design + referenced docs;
+   METHODOLOGY.md is read by the advisor itself). This runs a dedicated
+   design review in an isolated context.
+   - If advisor finds issues: present the findings AND your proposed fix for
+     each item, and let the user decide item by item — design questions are
+     decided WITH the user, not guessed by you (a fix without user input is
+     at best a formal patch). Amend per their call, then remind them it is
+     ready for re-review. Never fix-and-resubmit on your own.
    - If advisor approves: it returns a design token in plain text in its response.
    - If the advisor keeps rejecting after 3 rounds, STOP and report the open
      issues to the user — do not loop silently.
-4. **User sign-off.** Present the design summary AND the advisor's findings
+5. **User sign-off.** Present the design summary AND the advisor's findings
    (any remaining 🟡 advisories the user should know about) and WAIT for
    explicit approval before any implementation step.
-5. **Implement via eng-coder.** Spawn a subagent with `role="eng-coder"`,
+6. **Implement via eng-coder.** Spawn a subagent with `role="eng-coder"`,
    providing the METHODOLOGY task structure: the **Docs involved** list (design
    doc + requirements + referenced docs), the file list, the acceptance
    criteria. Pass the designToken via the `designToken` PARAMETER — never in
    the task text. The token is required — eng-coder cannot modify files
    without it.
-6. **Delivery review.** After eng-coder returns, verify the delivery against
-   the acceptance criteria from the design (run the tests it claims pass, read
-   the changed files). The eng-coder self-reviewed inside the subagent — its
-   advisor(code) call happens there. Re-review with the `advisor` tool
-   (`type="code"`, `documents=[...]` = the task's Docs involved list) only when
-   the user asks or the delivery looks wrong.
-7. **Verify.** Run `verify` — it must pass before you claim the task complete.
+7. **Delivery review — automatic flow node.** After eng-coder returns, verify
+   the delivery against the acceptance criteria from the design (run the
+   tests it claims pass, read the changed files) AND run the code review with
+   the `advisor` tool (`type="code"`, `documents=[...]` = the task's Docs
+   involved list). This review happens automatically — no user initiation
+   needed (2026-08-24 decision).
+8. **Verify.** Run `verify` — it must pass before you claim the task complete.
 
 ## Work Loop (every user message)
 
@@ -66,10 +79,12 @@ passed?
 | State | Default action |
 |---|---|
 | Requirements exploration | Clarify (who/what/why — never how), explore the current state, then write the REQUIREMENTS doc — three layers per METHODOLOGY: overall goal / functional user stories / non-functional standards (flow step 1) |
-| Design | Write or refine the DESIGN doc (approach + rationale, architecture/interface, affected files, key decisions), organized by business domain per METHODOLOGY, ask for confirmation (flow steps 2-3) |
-| Awaiting approval | Present design summary + advisor findings, WAIT for explicit approval (flow step 4) |
+| Design | Write or refine the DESIGN doc (approach + rationale, architecture/interface, affected files, key decisions), organized by business domain per METHODOLOGY, ask for confirmation (flow steps 1-2) |
+| Design ready | Present the design summary, say it is ready for review, WAIT — do NOT call advisor yourself; the user initiates the design review (flow steps 3-4) |
+| Review fix loop | Present findings + proposed fixes, the user decides item by item, amend per their call, remind for re-review (flow step 4) |
+| Awaiting approval | Present design summary + advisor findings, WAIT for explicit approval (flow step 5) |
 | Implementation | eng-coder is working — do not redesign in parallel |
-| Delivery review | Verify the delivery against the acceptance criteria (the eng-coder self-reviewed inside the subagent); re-review with advisor (type="code", documents = Docs involved) only when the user asks or the delivery looks wrong; report |
+| Delivery review | Verify the delivery against the acceptance criteria AND run advisor (type="code", documents = Docs involved) — automatic flow node, no user initiation (flow step 7); report |
 | Wrapped up | Report, wait for next instruction |
 
 Then handle the message:
@@ -83,13 +98,16 @@ Then handle the message:
   design doc path, file list, acceptance criteria; token via the `designToken`
   parameter, never in the task text.
 - **Question / discussion** → answer; write any decision to the relevant doc.
-- **eng-coder delivery** → verify the acceptance criteria (the eng-coder
-  self-reviewed before delivering); re-review only when the user asks, report.
+- **eng-coder delivery** → verify the acceptance criteria AND run the advisor
+  code review (automatic flow node — never wait for the user to ask); report.
 
 End every turn with three checks: ① decisions written to docs? ② current state
-named and next step stated? ③ what the user must do (approve / clarify / continue)?
-No code edits outside approved minor fixes (typos in docs you own, etc. —
-never implementation code). No unprompted advisor calls.
+named and next step stated? ③ what the user must do (initiate review / approve /
+clarify / continue)?
+No code edits outside approved minor fixes (post-delivery-review minor fixes
+once the design is approved, typos in docs you own, etc. — anything larger
+goes back to eng-coder). Design review ONLY when the user initiates it;
+delivery code review is an automatic flow node.
 
 ## Questioning Style (requirement clarification)
 
@@ -118,10 +136,15 @@ cannot enumerate. When using the `question` tool:
   constraint, or preference during design discussion or review, update the
   relevant docs (design doc, METHODOLOGY.md, ENGINEERING-MODE.md) right away —
   do not wait to be asked. A decision that isn't in a doc didn't land.
-- Advisor is mandatory at both design and code gates — regardless of
-  `/advisor` toggle state. Use `advisor`'s configured model if set; otherwise
-  the main model is used automatically. The key property is independent
-  context — every review runs in a fresh isolated session.
+- Review initiation split: the DESIGN review is called ONLY when the user
+  explicitly asks (e.g. "评审吧") — remind them when the design is ready,
+  never fire it yourself; each round of findings goes back to the user for
+  item-by-item decisions, no self-fix-resubmit loops. The CODE review at
+  eng-coder delivery is an automatic flow node — run it without asking.
+  Both hold regardless of `/advisor` toggle state. Use `advisor`'s configured
+  model if set; otherwise the main model is used automatically. The key
+  property is independent context — every review runs in a fresh isolated
+  session.
 - **Advisor response table.** After each advisor review you run, reply with a
   response table — exact header `| # | Action | Detail |`, one row per issue;
   `#` = the advisor's issue number (`Orig#` on rounds 2+).
@@ -135,9 +158,9 @@ cannot enumerate. When using the `question` tool:
   - A 🔴 you neither fix nor surface blocks convergence. `Deferred` fits 🟡/🔵
     improvements or a 🔴 needing a user decision first — never a way to silently
     drop a real defect; surface any unresolved 🔴 to the user.
-- **Review timing**: do NOT call advisor unprompted or repeatedly. Reviews
-  happen only when: the user explicitly asks, the system pushes back, or a
-  mandatory flow node requires it (the eng-coder self-reviews before delivery —
-  its advisor(code) call happens inside the subagent; you verify the delivery
-  against the acceptance criteria instead of re-reviewing).
+- **Review timing**: design review — ONLY user-initiated (you prepare and
+  remind, the user fires); each round of findings goes back to the user for
+  decisions. Delivery code review — automatic flow node after eng-coder
+  returns, run it without asking. Beyond these, do NOT call advisor
+  unprompted or repeatedly.
   If advisor fails or is interrupted, stop retrying — report to the user.

package/src/tools/delete.md

@@ -1,5 +1,7 @@
 Delete a file. Use when the agent created a temporary or junk file that should be cleaned up, or when the user explicitly asks to delete something. Refuses to delete git-tracked files as a safety measure — tracked files should be edited or removed via bash with explicit user confirmation.
 
+**Route to delete instead of bash:** `del file` / `rm file` → delete (single files). Use bash `rm -rf` only for directories (delete is single-file).
+
 Parameters:
 - path (required): File path, relative to cwd or absolute
 - force: Allow deleting git-tracked files (default false)

package/src/tools/execute.md

@@ -1,10 +1,14 @@
-Execute JavaScript code with full Node access. Runs in a real `node` process with top-level `await` and dynamic `import()` — so you can load and call the project's own `.mjs` modules directly. Use this to compose multiple operations into one call — read, write, glob, grep, log, import, or require() — without shelling out to `bash node -e`.
+Execute JavaScript — either inline `code` or a workspace `scriptFile`. Runs in a real `node` process with top-level `await` and dynamic `import()`. Use inline `code` to compose multiple operations into one call — read, write, glob, grep, log, import, or require() — without shelling out to `bash node -e`.
 
 **Route to execute instead of bash:**
-- `node -e "…"` → execute (top-level await + import() + console all work)
+- `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 (required): JavaScript to run. Top-level `await` and `import('./x.mjs')` are supported. Globals: readFile(path), writeFile(path, content), glob(pattern), grep(pattern, file), log(...args) — plus native require/process/console/fetch/import.
+- code: JavaScript to run inline. Top-level `await` and `import('./x.mjs')` are supported. Globals: readFile(path), writeFile(path, content), glob(pattern), grep(pattern, file), log(...args) — plus native require/process/console/fetch/import. Use this OR scriptFile.
+- scriptFile: run a workspace .mjs/.js file with node (self-contained — no prelude; the file imports what it needs). Path relative to workdir, confined to the workspace. 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, confined to the workspace; default cwd)
 - filter: optional — only return output lines matching this regex (case-insensitive)
 - timeoutMs: Timeout in milliseconds (default 30000, max 60000)
@@ -14,4 +18,4 @@ Notes:
 - File paths are confined to the workspace root (`..` traversal is denied) — but `require`/`process`/`import()` are full Node, same boundary as bash.
 - A non-zero exit / thrown exception returns the stderr (error + stack) as the result.
 - Output capped at ~50KB; use `writeFile` to a file if you need more.
-- Use `write`/`edit`/`apply_patch` for source edits and `bash` for subprocess/CLI runs (`npm test`, `node --test`, servers) — execute is for in-process JS, not spawning programs.
+- 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.

package/src/tools/{codemode.mjs → execute.mjs}

@@ -1,5 +1,5 @@
 /**
- * tools/codemode.mjs — CodeMode: JavaScript execution tool
+ * tools/execute.mjs — JavaScript execution tool
  *
  * Gives the model an `execute` tool that runs JS in a child `node
  * --input-type=module --eval` process — NOT the in-process vm sandbox it used
@@ -15,7 +15,9 @@
  * process/import() is available — same boundary as bash, no fake sandbox.
  *
  * Parameters:
- *   code       — JS to run (top-level await and import() supported)
+ *   code       — JS to run inline (top-level await and import() supported). Use this OR scriptFile.
+ *   scriptFile — run a workspace .mjs/.js file with node (self-contained, no prelude). Use this OR code.
+ *   nodeArgs   — (scriptFile) extra node flags before the script (e.g. --test, --check); eval-like flags rejected
  *   workdir    — run in this sub-directory (confined to the workspace)
  *   filter     — return only output lines matching this regex (case-insensitive)
  *   timeoutMs  — timeout (default 30s, max 60s)
@@ -59,12 +61,11 @@ function applyFilter(output, filter) {
   }
 }
 
-/** Spawn node, run code + prelude, capture stdout/stderr, enforce timeout/abort.
+/** Spawn node with the given args, capture stdout/stderr, enforce timeout/abort.
  *  Resolves { text, ok } — ok=false on non-zero exit / timeout / abort. */
-function runNodeEval(code, baseDir, root, timeoutMs, signal) {
+function runNode(childArgs, baseDir, root, timeoutMs, signal) {
   return new Promise((resolvePromise) => {
-    const src = `await import(${JSON.stringify(PRELUDE_URL)});\n${code}`
-    const child = spawn(process.execPath, ["--input-type=module", "--eval", src], {
+    const child = spawn(process.execPath, childArgs, {
       cwd: baseDir,
       env: { ...process.env, THINCODER_EXEC_ROOT: root },
       stdio: ["ignore", "pipe", "pipe"],
@@ -118,7 +119,19 @@ function runNodeEval(code, baseDir, root, timeoutMs, signal) {
   })
 }
 
-export const codeModeTool = {
+/** Validate nodeArgs (extra node flags for scriptFile mode, e.g. --test / --check). Forbids
+ *  eval-like flags that would conflict with scriptFile mode or re-open inline injection. */
+function validateNodeArgs(nodeArgs) {
+  if (!nodeArgs) return []
+  const arr = Array.isArray(nodeArgs) ? nodeArgs : String(nodeArgs).split(/\s+/).filter(Boolean)
+  const forbidden = /^(--eval|-e|--input-type|--print|-p|--inspect|--inspect-brk)(=|$)/i
+  for (const a of arr) {
+    if (forbidden.test(a)) throw new Error(`nodeArgs flag not allowed: ${a}`)
+  }
+  return arr
+}
+
+export const executeTool = {
   name: "execute",
   description: DESC("execute"),
   parameters: {
@@ -126,7 +139,16 @@ export const codeModeTool = {
     properties: {
       code: {
         type: "string",
-        description: "JavaScript code to execute (top-level await and dynamic import() supported). Use provided globals: readFile/writeFile/glob/grep/log, plus native require/process/console/fetch/import.",
+        description: "JavaScript code to execute (top-level await and dynamic import() supported). Use provided globals: readFile/writeFile/glob/grep/log, plus native require/process/console/fetch/import. Use this OR scriptFile.",
+      },
+      scriptFile: {
+        type: "string",
+        description: "Run a workspace .mjs/.js file with node (self-contained, no prelude). Path relative to workdir, confined to the workspace. Use this OR code. For `node <script>` / `node --test <file>` / `node --check <file>`.",
+      },
+      nodeArgs: {
+        type: "array",
+        items: { type: "string" },
+        description: "(scriptFile) Extra node flags before the script, e.g. [\"--test\"], [\"--check\"]. Eval-like flags (--eval/--input-type/--inspect) are rejected.",
       },
       workdir: {
         type: "string",
@@ -143,15 +165,11 @@ export const codeModeTool = {
         description: `Timeout in milliseconds (default ${DEFAULT_TIMEOUT}, max 60000)`,
       },
     },
-    required: ["code"],
+    required: [],
   },
   readonly: false,
 
   async execute(args, ctx) {
-    const code = args.code ?? ""
-    if (code.length > MAX_SCRIPT) {
-      return `Error: script too large (${code.length} > ${MAX_SCRIPT} bytes). Split into smaller scripts or use individual tools.`
-    }
     let baseDir
     try { baseDir = resolveBaseDir(ctx.cwd, args.workdir) }
     catch (e) { return `Error: ${e.message}` }
@@ -159,7 +177,27 @@ export const codeModeTool = {
     const t = Number(args.timeoutMs)
     const timeoutMs = Number.isFinite(t) && t > 0 ? Math.min(t, 60_000) : DEFAULT_TIMEOUT
 
-    const { text, ok } = await runNodeEval(code, baseDir, ctx.cwd, timeoutMs, ctx.signal)
+    let childArgs
+    if (args.scriptFile) {
+      if (args.code?.trim()) return "Error: pass code OR scriptFile, not both"
+      // scriptFile mode: run a workspace .mjs/.js file with node [nodeArgs...]. Self-contained —
+      // no prelude (a real node process imports what it needs). Confined to the workspace.
+      const scriptAbs = resolve(baseDir, args.scriptFile)
+      if (!isInside(ctx.cwd, scriptAbs)) return `Error: scriptFile escapes the workspace: ${args.scriptFile}`
+      let nodeArgs
+      try { nodeArgs = validateNodeArgs(args.nodeArgs) }
+      catch (e) { return `Error: ${e.message}` }
+      childArgs = [...nodeArgs, scriptAbs]
+    } else {
+      const code = args.code ?? ""
+      if (!code.trim()) return "Error: either code or scriptFile is required"
+      if (code.length > MAX_SCRIPT) {
+        return `Error: script too large (${code.length} > ${MAX_SCRIPT} bytes). Split into smaller scripts or use individual tools.`
+      }
+      childArgs = ["--input-type=module", "--eval", `await import(${JSON.stringify(PRELUDE_URL)});\n${code}`]
+    }
+
+    const { text, ok } = await runNode(childArgs, baseDir, ctx.cwd, timeoutMs, ctx.signal)
     // Only filter successful output — never swallow an error report behind a filter.
     if (!ok) return text
     return args.filter ? applyFilter(text, args.filter) : text

package/src/tools/git.md

@@ -1,21 +1,39 @@
-Run a git command. Use this to see uncommitted changes, staged changes, diff against a ref, recent commits, or manage checkpoints. Only works inside a git repository.
-- action='diff': Show unified diff — what changed since last commit. Set staged=true for staged-only diff, ref=<ref> to compare against a specific commit/branch, path=<dir> to scope to a file or directory.
-- action='status': Show working tree state — staged, unstaged, untracked files, and conflicts. Returns categorized lists.
-- action='log': Show recent commit history. Set count to limit, oneline=true for compact format, path=<file> to see history of one file.
-- action='show': Show a commit's details (--stat). Set ref=<ref> to inspect a specific commit (default HEAD).
-- action='checkpoint': Manage git-based snapshots. Use checkpointAction to choose: list (overview), create (snapshot now), rewind (restore snapshot by id), cat (read a file from a snapshot).
-- action='rm': Untrack a file/directory (git rm --cached — keeps the file on disk). path is required.
-- action='commit': Stage all changes and commit. message is required. Confirms with the user (outward action).
-- action='push': Push the current branch to the remote. Confirms with the user (outward action).
+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.
+
+- 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': stage + commit. message required; path=<file> for granular staging.
+- 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='checkpoint': git snapshots. checkpointAction=list/create/rewind/cat/versions; checkpointId required for rewind/cat.
 
 Parameters:
-- action (required): diff / status / log / show / checkpoint / rm / commit / push
-- staged: (diff) Show staged changes instead of working tree
-- path: (diff/log/checkpoint:cat/checkpoint:rewind/rm) File or directory to scope to
-- ref: (show) Commit ref to inspect (default HEAD)
-- count: (log) Number of commits (default 10)
-- oneline: (log) One-line-per-commit format
-- message: (commit) Commit message — required for commit
-- filter: Optional — keep only status/diff/log output lines matching this regex (case-insensitive)
-- checkpointAction: (checkpoint) list snapshots / create one / restore by id / read file from snapshot
-- checkpointId: (checkpoint) Snapshot id — required for rewind and cat; optional for list (shows file tree)
+- action (required): diff / status / log / show / checkpoint / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick
+- workdir: run git in this workspace subdirectory (monorepo / multi-repo). Confined to the workspace. Default: cwd
+- path: (diff/log/add/commit/checkout/restore/rm) file or directory to scope / stage / restore
+- ref: (show/diff/checkout/reset/revert/merge/cherry-pick/tag:create/branch:create) commit/branch/ref; (push/pull/fetch) the branch or tag (space-separated for multiple)
+- name: (branch/tag) the branch or tag name
+- remote: (push/fetch/pull) remote name (e.g. origin); 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)

package/src/tools/git.mjs

@@ -5,7 +5,7 @@ import {
 } from "./shared.mjs";
 import { escapeXml } from "../agent/helpers.mjs";
 import { execFileSync } from "node:child_process";
-import { join } from "node:path";
+import { join, resolve, relative, isAbsolute, sep } from "node:path";
 
 /** Keep only output lines matching a regex (git filter, case-insensitive). */
 function filterLines(output, filter) {
@@ -19,6 +19,17 @@ function filterLines(output, filter) {
   }
 }
 
+/** Run git PRESERVING per-line leading whitespace. runGit trims the WHOLE output, which
+ *  strips a porcelain line's leading " " (the unstaged marker) and misclassifies an
+ *  unstaged-only first line as staged. status uses this so the staged/unstaged column survives. */
+function runGitRaw(cwd, cmdArgs) {
+  try {
+    return execFileSync("git", cmdArgs, { cwd, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }).replace(/\r/g, "").replace(/\n$/, "")
+  } catch (e) {
+    return String(e.stdout || "").replace(/\r/g, "")
+  }
+}
+
 /** Run git and report failure (stderr + exit code) instead of swallowing it.
  *  Used by write ops (commit/push/rm) where a silent "" would masquerade as success. */
 function runGitStrict(cwd, cmdArgs) {
@@ -30,21 +41,66 @@ function runGitStrict(cwd, cmdArgs) {
   }
 }
 
+/** Validate a git ref / branch / tag / remote name (no option injection, no whitespace). */
+function validateRef(ref, what = "git ref") {
+  if (!/^[A-Za-z0-9._\/~^@][A-Za-z0-9._\/~^@{}\-]*$/.test(ref)) throw new Error(`Invalid ${what}: ${ref}`)
+  return ref
+}
+
+/** True when `abs` is inside `root` (handles `..` and cross-drive, which relative()
+ *  returns as an absolute path on Windows). */
+function isInside(root, abs) {
+  const rel = relative(root, abs)
+  if (isAbsolute(rel)) return false
+  return rel !== ".." && !rel.startsWith(".." + sep)
+}
+
+/** Resolve workdir relative to cwd, asserting it stays within the workspace. */
+function resolveBaseDir(cwd, workdir) {
+  if (!workdir || typeof workdir !== "string") return cwd
+  const abs = resolve(cwd, workdir)
+  if (!isInside(cwd, abs)) throw new Error(`workdir escapes the workspace: ${workdir}`)
+  return abs
+}
+
+/** Snapshot the working tree before a destructive op (reset --hard / checkout file / restore /
+ *  stash pop / branch|tag delete). Best-effort — a snapshot failure must not block the op
+ *  (the approval/permission layer is the real gate). Returns a note line or "". */
+async function snapshotBefore(ctx, label) {
+  try {
+    const { createCheckpoint, isGitRepo } = await import("../git/checkpoint.mjs")
+    if (!isGitRepo(ctx.cwd)) return ""
+    const cp = await createCheckpoint(ctx.cwd)
+    return `[snapshot ${cp.id} created before ${label}]\n`
+  } catch {
+    return ""
+  }
+}
+
 export const gitTool = {
   name: "git",
   description: DESC("git"),
   parameters: {
     type: "object",
     properties: {
-      action: { type: "string", enum: ["diff", "status", "log", "show", "checkpoint", "rm", "commit", "push"], description: "diff / status / log / show / checkpoint / rm / commit / push" },
+      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"], description: "diff / status / log / show / checkpoint / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick" },
       // diff/log params
       staged: { type: "boolean", description: "(diff) Show staged changes instead of working tree" },
-      path: { type: "string", description: "(diff/log/checkpoint:cat/versions/rewind/rm) File or directory to scope to" },
-      ref: { type: "string", description: "(show) Commit ref to show (default HEAD)" },
+      path: { type: "string", description: "(diff/log/add/commit/checkout/restore/checkpoint:cat/versions/rewind/rm) File or directory to scope to / stage / restore" },
+      ref: { type: "string", description: "(show/diff/checkout/reset/revert/merge/cherry-pick/tag:create/branch:create) Commit/branch/ref; (push/pull/fetch) the branch or tag to push/pull/fetch (space-separated for multiple)" },
       count: { type: "number", description: "(log) Number of commits (default 10)" },
       oneline: { type: "boolean", description: "(log) One-line-per-commit format" },
-      message: { type: "string", description: "(commit) Commit message — required for commit" },
+      message: { type: "string", description: "(commit) Commit message — required for commit; (stash:push) stash message" },
       filter: { type: "string", description: "Optional: keep only status/diff/log output lines matching this regex (case-insensitive)" },
+      // write-op params
+      name: { type: "string", description: "(branch/tag) The branch or tag name (create/delete/switch)" },
+      remote: { type: "string", description: "(push/fetch/pull) Remote name (e.g. origin). Default: current upstream" },
+      workdir: { type: "string", description: "Run git in this workspace subdirectory (monorepo / multi-repo). Confined to the workspace. Default: cwd" },
+      tags: { type: "boolean", description: "(push) Also push all tags (--tags)" },
+      mode: { type: "string", enum: ["soft", "mixed", "hard"], description: "(reset) reset mode — hard snapshots the tree first + needs confirmation" },
+      tagAction: { type: "string", enum: ["list", "create", "delete"], description: "(tag) list tags / create one / delete one" },
+      branchAction: { type: "string", enum: ["list", "create", "delete", "switch"], description: "(branch) list branches / create / delete / switch to one" },
+      stashAction: { type: "string", enum: ["push", "pop", "list"], description: "(stash) push (stash now) / pop (apply+drop) / list" },
       // checkpoint params
       checkpointAction: { type: "string", enum: ["list", "create", "rewind", "cat", "versions"], description: "(checkpoint) list snapshots / create one / restore by id / read file from snapshot / list a file's historical versions" },
       checkpointId: { type: "string", description: "(checkpoint) Snapshot id — required for rewind and cat; optional for list (shows file tree)" },
@@ -53,6 +109,9 @@ export const gitTool = {
   },
   readonly: false,
   async execute(args, ctx) {
+    // workdir: run git in a workspace subdirectory (monorepo / multi-repo). Shadow ctx.cwd so
+    // every action + snapshotBefore + checkpoint resolves against the workdir, confined to the workspace.
+    if (args.workdir) ctx = { ...ctx, cwd: resolveBaseDir(ctx.cwd, args.workdir) }
     switch (args.action) {
       case "diff": {
         const ref = args.ref ?? "HEAD"
@@ -63,7 +122,9 @@ export const gitTool = {
         return truncate(filterLines(out || "(no changes)", args.filter))
       }
       case "status": {
-        const porcelain = runGit(ctx.cwd, ["status", "--porcelain"])
+        // Preserve per-line leading whitespace — porcelain " M"/"M " staged/unstaged markers are
+        // significant (runGit trims the whole output's leading space, corrupting an unstaged-first-line).
+        const porcelain = runGitRaw(ctx.cwd, ["status", "--porcelain"])
         if (!porcelain) return "(clean — no changes)"
 
         const staged = []
@@ -119,7 +180,8 @@ export const gitTool = {
       }
       case "commit": {
         if (!args.message) return "Error: commit requires message"
-        const add = runGitStrict(ctx.cwd, ["add", "-A"])
+        // Granular staging when path given (only stage these); otherwise stage all (add -A).
+        const add = runGitStrict(ctx.cwd, args.path ? ["add", "--", args.path] : ["add", "-A"])
         if (!add.ok) return truncate(`git add failed: ${add.err || add.out || "(no output)"}`)
         const commit = runGitStrict(ctx.cwd, ["commit", "-m", args.message])
         const parts = []
@@ -129,9 +191,145 @@ export const gitTool = {
         return truncate(parts.join("\n") || "(commit produced no output)")
       }
       case "push": {
-        const r = runGitStrict(ctx.cwd, ["push"])
+        const cmdArgs = ["push"]
+        if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
+        if (args.ref) for (const r of args.ref.split(/\s+/).filter(Boolean)) cmdArgs.push(validateRef(r, "ref"))
+        if (args.tags) cmdArgs.push("--tags")
+        const r = runGitStrict(ctx.cwd, cmdArgs)
         return r.ok ? truncate(r.out || "(push complete — no output)") : truncate(`git push failed: ${r.err || r.out || "(no output)"}`)
       }
+      case "add": {
+        // Granular staging: stage `path` when given, else all changes (add -A).
+        const cmdArgs = args.path ? ["add", "--", args.path] : ["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}`)
+      }
+      case "tag": {
+        const sub = args.tagAction
+        if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["tag", "-l"]) || "(no tags)", args.filter))
+        if (sub === "create") {
+          if (!args.name) return "Error: tag create requires name"
+          validateRef(args.name, "tag")
+          const cmdArgs = ["tag", args.name]
+          if (args.ref) cmdArgs.push(validateRef(args.ref))
+          const r = runGitStrict(ctx.cwd, cmdArgs)
+          return r.ok ? `Tag ${args.name} created` : truncate(`git tag failed: ${r.err || r.out}`)
+        }
+        if (sub === "delete") {
+          if (!args.name) return "Error: tag delete requires name"
+          validateRef(args.name, "tag")
+          const snap = await snapshotBefore(ctx, `tag delete ${args.name}`)
+          const r = runGitStrict(ctx.cwd, ["tag", "-d", args.name])
+          return r.ok ? truncate(snap + `Tag ${args.name} deleted`) : truncate(`git tag -d failed: ${r.err || r.out}`)
+        }
+        return "Error: tag requires tagAction — use: list | create | delete"
+      }
+      case "branch": {
+        const sub = args.branchAction
+        if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["branch", "--all", "-vv"]) || "(no branches)", args.filter))
+        if (sub === "create") {
+          if (!args.name) return "Error: branch create requires name"
+          validateRef(args.name, "branch")
+          const cmdArgs = ["branch", args.name]
+          if (args.ref) cmdArgs.push(validateRef(args.ref))
+          const r = runGitStrict(ctx.cwd, cmdArgs)
+          return r.ok ? `Branch ${args.name} created` : truncate(`git branch failed: ${r.err || r.out}`)
+        }
+        if (sub === "switch") {
+          if (!args.name) return "Error: branch switch requires name"
+          validateRef(args.name, "branch")
+          const r = runGitStrict(ctx.cwd, ["checkout", args.name])
+          return r.ok ? `Switched to branch ${args.name}` : truncate(`git checkout ${args.name} failed: ${r.err || r.out}`)
+        }
+        if (sub === "delete") {
+          if (!args.name) return "Error: branch delete requires name"
+          validateRef(args.name, "branch")
+          const snap = await snapshotBefore(ctx, `branch delete ${args.name}`)
+          const r = runGitStrict(ctx.cwd, ["branch", "-d", args.name])
+          return r.ok ? truncate(snap + `Branch ${args.name} deleted`) : truncate(`git branch -d failed: ${r.err || r.out}`)
+        }
+        return "Error: branch requires branchAction — use: list | create | delete | switch"
+      }
+      case "checkout": {
+        if (args.path) {
+          // Restore file from index (discards working-tree changes to it) — destructive: snapshot first.
+          const snap = await snapshotBefore(ctx, `checkout -- ${args.path}`)
+          const r = runGitStrict(ctx.cwd, ["checkout", "--", args.path])
+          return r.ok ? truncate(snap + `Restored ${args.path}`) : truncate(`git checkout -- ${args.path} failed: ${r.err || r.out}`)
+        }
+        if (args.ref) {
+          validateRef(args.ref, "ref")
+          const r = runGitStrict(ctx.cwd, ["checkout", args.ref])
+          return r.ok ? truncate(r.out || `Checked out ${args.ref}`) : truncate(`git checkout ${args.ref} failed: ${r.err || r.out}`)
+        }
+        return "Error: checkout requires ref (branch/commit) or path (file to restore)"
+      }
+      case "restore": {
+        if (!args.path) return "Error: restore requires path"
+        const snap = await snapshotBefore(ctx, `restore ${args.path}`)
+        const cmdArgs = ["restore"]
+        if (args.staged) cmdArgs.push("--staged")
+        cmdArgs.push("--", args.path)
+        const r = runGitStrict(ctx.cwd, cmdArgs)
+        return r.ok ? truncate(snap + `Restored ${args.path}`) : truncate(`git restore failed: ${r.err || r.out}`)
+      }
+      case "stash": {
+        const sub = args.stashAction
+        if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["stash", "list"]) || "(no stashes)", args.filter))
+        if (sub === "push") {
+          const cmdArgs = ["stash", "push"]
+          if (args.message) cmdArgs.push("-m", args.message)
+          const r = runGitStrict(ctx.cwd, cmdArgs)
+          return r.ok ? truncate(r.out || "Stashed") : truncate(`git stash push failed: ${r.err || r.out}`)
+        }
+        if (sub === "pop") {
+          const snap = await snapshotBefore(ctx, "stash pop")
+          const r = runGitStrict(ctx.cwd, ["stash", "pop"])
+          return r.ok ? truncate(snap + (r.out || "Popped")) : truncate(`git stash pop failed: ${r.err || r.out}`)
+        }
+        return "Error: stash requires stashAction — use: push | pop | list"
+      }
+      case "fetch": {
+        const cmdArgs = ["fetch"]
+        if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
+        if (args.ref) cmdArgs.push(validateRef(args.ref, "ref"))
+        const r = runGitStrict(ctx.cwd, cmdArgs)
+        return r.ok ? truncate(r.out || "(fetch complete — no output)") : truncate(`git fetch failed: ${r.err || r.out}`)
+      }
+      case "pull": {
+        const cmdArgs = ["pull"]
+        if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
+        if (args.ref) cmdArgs.push(validateRef(args.ref, "ref"))
+        const r = runGitStrict(ctx.cwd, cmdArgs)
+        return r.ok ? truncate(r.out || "(pull complete — no output)") : truncate(`git pull failed: ${r.err || r.out}`)
+      }
+      case "reset": {
+        const mode = args.mode ?? "mixed"
+        if (!["soft", "mixed", "hard"].includes(mode)) return "Error: reset mode must be soft | mixed | hard"
+        let snap = ""
+        if (mode === "hard") snap = await snapshotBefore(ctx, "reset --hard") // destructive: drops working-tree changes
+        const cmdArgs = ["reset", `--${mode}`]
+        if (args.ref) cmdArgs.push(validateRef(args.ref))
+        const r = runGitStrict(ctx.cwd, cmdArgs)
+        return r.ok ? truncate(snap + (r.out || `Reset (${mode}) complete`)) : truncate(`git reset failed: ${r.err || r.out}`)
+      }
+      case "revert": {
+        const ref = validateRef(args.ref ?? "HEAD")
+        const r = runGitStrict(ctx.cwd, ["revert", "--no-edit", ref])
+        return r.ok ? truncate(r.out || `Reverted ${ref}`) : truncate(`git revert failed: ${r.err || r.out}`)
+      }
+      case "merge": {
+        if (!args.ref) return "Error: merge requires ref (branch/commit to merge)"
+        validateRef(args.ref, "ref")
+        const r = runGitStrict(ctx.cwd, ["merge", "--no-edit", args.ref])
+        return r.ok ? truncate(r.out || `Merged ${args.ref}`) : truncate(`git merge failed: ${r.err || r.out} — resolve conflicts, then commit`)
+      }
+      case "cherry-pick": {
+        if (!args.ref) return "Error: cherry-pick requires ref (commit)"
+        validateRef(args.ref, "ref")
+        const r = runGitStrict(ctx.cwd, ["cherry-pick", args.ref])
+        return r.ok ? truncate(r.out || `Cherry-picked ${args.ref}`) : truncate(`git cherry-pick failed: ${r.err || r.out}`)
+      }
       case "checkpoint": {
         const { createCheckpoint, listCheckpoints, rewind, listFileVersions, isGitRepo } = await import("../git/checkpoint.mjs")
         if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
@@ -191,7 +389,7 @@ export const gitTool = {
         throw new Error(`Unknown checkpoint action: ${sub}. Use: list | create | rewind | cat | versions`)
       }
       default:
-        return `Unknown action '${args.action}'. Use: diff | status | log | show | checkpoint | rm | commit | push`
+        return `Unknown action '${args.action}'. Use: diff | status | log | show | checkpoint | add | rm | commit | push | tag | branch | checkout | restore | stash | fetch | pull | reset | revert | merge | cherry-pick`
     }
   },
 }

package/src/tools/grep.md

@@ -1,5 +1,7 @@
 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)

package/src/tools/index.mjs

@@ -9,7 +9,7 @@ import { gitTool, questionTool } from "./git.mjs";
 import { checklistTool } from "./checklist.mjs";
 import { lintTool } from "./linter.mjs";
 import { lspTool } from "./lsp.mjs";
-import { codeModeTool } from "./codemode.mjs";
+import { executeTool } from "./execute.mjs";
 import { fileOpsTool, processTool, getCurrentTimeTool, sleepTool } from "./ops.mjs";
 import { treeTool } from "./tree.mjs";
 
@@ -18,7 +18,7 @@ export const builtinTools = [
   readImageTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
   gitTool, questionTool,
-  checklistTool, lintTool, lspTool, codeModeTool,
+  checklistTool, lintTool, lspTool, executeTool,
   fileOpsTool, processTool, getCurrentTimeTool, sleepTool,
   treeTool,
 ];
@@ -28,7 +28,7 @@ export {
   readImageTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
   gitTool, questionTool,
-  checklistTool, lintTool, lspTool, codeModeTool,
+  checklistTool, lintTool, lspTool, executeTool,
   fileOpsTool, processTool, getCurrentTimeTool, sleepTool,
   treeTool,
 };

package/src/tools/ls.md

@@ -1,5 +1,7 @@
 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

package/src/tools/read.md

@@ -1,5 +1,7 @@
 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`

package/src/tui/agent-turn.mjs

@@ -3,7 +3,7 @@ import { saveSession } from "../session.mjs"
 import { sliceByWidth } from "./render.mjs"
 import { ansi, C } from "./ansi.mjs"
 import { formatToolSummary } from "./tool-summaries.mjs"
-import { ADVISOR_THINKING_PLACEHOLDER } from "../advisor/run.mjs"
+import { ADVISOR_THINKING_PLACEHOLDER, resolveAdvisorProvider } from "../advisor/run.mjs"
 
 /** Tool execution start timestamps (performance.now ms), keyed by tool name. */
 const _toolTicks = Object.create(null)
@@ -101,6 +101,15 @@ export async function runAgentTurn(ctx, text) {
         if (!state.subTasks[key]) {
           state.subTasks[key] = { key, role: subMatch[1], text: "", tool: null, done: false, started: Date.now() }
         }
+        // `[model]<name>` metadata token: record the subagent's model (may differ from the
+        // parent's) — shown in the subagent header, NOT appended to its content stream.
+        // Only treat as metadata when the model isn't set yet (it's always the FIRST token);
+        // a child content token that happens to start with "[model]" must not be swallowed.
+        if (payload.startsWith("[model]") && state.subTasks[key].model === undefined) {
+          state.subTasks[key].model = payload.slice(7)
+          scheduleRender()
+          return
+        }
         state.subTasks[key].text += payload
         if (state.subTasks[key].text.length > 2000) {
           state.subTasks[key].text = state.subTasks[key].text.slice(-2000)
@@ -149,6 +158,8 @@ export async function runAgentTurn(ctx, text) {
       flushStream()
       ensureAssistantLabel()
       state.currentTool = name
+      // Advisor's effective model (resolved once for the status line + inline title below).
+      const advModel = name === "advisor" ? (() => { try { return resolveAdvisorProvider(agent).model } catch { return null } })() : null
       // Update status bar with current tool and key arguments for user visibility
       if (name === "bash" && args.command) {
         const cmd = args.command.replace(/\s+/g, " ").trim()
@@ -162,13 +173,14 @@ export async function runAgentTurn(ctx, text) {
       } else if (name === "websearch" && args.query) {
         state.status = `search: ${args.query.length > 40 ? args.query.slice(0, 40) + "…" : args.query}`
       } else if (name === "advisor") {
-        state.status = `advisor review (round ${(agent._advisorRound || 0) + 1})`
+        state.status = `advisor review (round ${(agent._advisorRound || 0) + 1}${advModel ? " · " + advModel : ""})`
       } else {
         state.status = `tool: ${name}`
       }
       // Advisor: tag the round in the tool title — the model's own "第N轮" narration
       // is unreliable (it glues onto the previous line), so the round belongs here.
-      const roundTag = name === "advisor" ? ` (round ${(agent._advisorRound || 0) + 1})` : ""
+      // Also show the advisor's effective model (it may differ from the main agent's).
+      const roundTag = name === "advisor" ? ` (round ${(agent._advisorRound || 0) + 1}${advModel ? " · " + advModel : ""})` : ""
       const argSummary = summarize(args)
       // Inline block title — panel tools get both the title AND the
       // streaming output panel, complementary display.

package/src/tui/render-frame.mjs

@@ -62,7 +62,7 @@ export function renderSubagent(allSubs, W) {
   for (const s of subs.slice(0, MAX_SUB_LINES)) {
     const icon = s.done ? "✓" : "…"
     const color = s.done ? C.dim : C.tool
-    const label = `[${s.role}]`.padEnd(10)
+    const label = `[${s.role}${s.model ? " · " + s.model : ""}]`.padEnd(10)
     let content
     if (s.done) {
       const elapsed = Math.floor((Date.now() - s.started) / 1000)
@@ -75,7 +75,7 @@ export function renderSubagent(allSubs, W) {
     } else {
       content = "thinking..."
     }
-    out.push(`${color} ${icon} ${label} ${sliceByWidth(content, Math.max(10, W - 14))}${ansi.reset}`)
+    out.push(`${color} ${icon} ${label} ${sliceByWidth(content, Math.max(10, W - 4 - stringWidth(label)))}${ansi.reset}`)
   }
   if (subs.length > MAX_SUB_LINES) {
     out.push(`${C.dim}  ... +${subs.length - MAX_SUB_LINES} more subagents${ansi.reset}`)