@thincoder/core 0.10.7 → 0.10.9

package/tool-docs/batch.md

@@ -1 +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, plus optional ledger / board that fill the record's 台账 header line at creation) · 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) — create/close; append/status domains are mode-dependent: engineering — append §1/§4/§6, status §1; normal — append §1/§2/§4/§5/§6, status §1/§2/§5 (the main agent holds the designer seat and records direct implementation); eng-designer — §2; eng-coder — §5; a normal-mode coder bound via batchDoc — §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's structural lines block append/status until filled: create with ledger / board fills them at creation; if omitted, the main agent fills the header by file edit right after create (citing these literals in a section's prose is fine — only the header is checked); `<§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 — “§× 未写入”.
+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, plus optional ledger / board that fill the record's 台账 header line at creation) · 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). Writing §1 已收口 closes the record and runs the closeout-chain gate: §2 / §3 / §4 / §6 must each carry content, or §1 declares it inapplicable with `> 不适用：§N —— <reason>` (§2 / §3 / §4 only; §5 is exempt; §6 never). Reopening a frozen record = §1 → 进行中 with `note` = the reason: the tool rewrites the §1 status line and appends a 「重开记录」 line — no other existing line is touched. · close (depth-0 only — freeze the record: §1 → 「已收口 <date>」, every further write is refused except the reopen conjunction; runs the same closeout-chain gate as status — an incomplete chain is refused, naming the missing sections). Closing a record — the close action, or status writing §1 已收口 — also writes the ledger: this record's unsettled rows (task_book → this record, status 待讨论 / 待设计 / 在途, trigger ≠ 认账不排期 — a policy call leaves its row untouched, and a row already 条件 is skipped with zero writes) get trigger → 条件, with the resume sentence 「原批 <record> 已收口，须另起批次接手」 landing in resume_when (a non-empty resume_when keeps its value — the sentence is appended to evidence instead); each changed / skipped row is named in a `[ledger reanchor]` receipt block (a ledger write failure — busy store / no derivable project root — is named there too and never blocks the freeze). Identity fixes what you may write (段白名单): main agent (depth 0) — create/close; append/status domains are mode-dependent: engineering — append §1/§4/§6, status §1; normal — append §1/§2/§4/§5/§6, status §1/§2/§5 (the main agent holds the designer seat and records direct implementation); eng-designer — §2; eng-coder — §5; a normal-mode coder bound via batchDoc — §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's structural lines block append/status until filled: create with ledger / board fills them at creation; if omitted, the main agent fills the header by file edit right after create (citing these literals in a section's prose is fine — only the header is checked); `<§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). Document-check gate: appending §2 / §5 as a sub-agent and closing a record (or setting §1 to 已收口) run the doc-check gate before the write — REFUSED ⇒ the write is refused and the record's bytes stay unchanged (do not close a record after a refused append); ERROR ⇒ a closeout is refused while an append still lands with an ERROR receipt line; no PROJECT-MANIFEST.json ⇒ the gate does not run and the receipt says so. Failures are hard and visible (no silent fallback): if a write is refused or fails, say so in your report — “§× 未写入”.

package/tool-docs/browser.md

@@ -45,4 +45,4 @@ Notes:
 - Session assumptions: the session may be closed externally or timed out — never assume it is alive; on `closed externally`, just run the action again (fresh session, login kept).
 - When not to use it: static page / API → `fetch`; a link needing no interaction → just produce the URL; a step needing a human (2FA, payment) → ask the user to do it in a headed session.
 
-CLI, VS Code and desktop share this description verbatim (single source: core `tool-docs/`).
+CLI, VS Code and desktop share this description verbatim.

package/tool-docs/doc_check.md

@@ -0,0 +1,54 @@
+Run a built-in documentation-discipline check on a project and report its findings.
+Read-only. In the default `report` mode it is non-gating: it reports, it never blocks, never sets an exit code, and its output is never a reason to refuse a task or a user instruction.
+When the engine files are newer than this session's start time (or unreadable), `report` prefixes its output with one
+`[doc_check note]` line naming the stale files — that reading came from an engine loaded at startup and is not usable as
+delivery evidence. Nothing else changes: `report` still produces no verdict and no existing line is altered (no stale files ⇒
+the report is byte-identical).
+
+What it checks — exactly two criteria, both driven by the checked project's declarations:
+- Anchors — every documentation pointer (a `*.md` token, optionally carrying directory segments, optionally followed by a section
+  indicator `§N` / `§N.M` / `§N.M.K`) must resolve: the file must exist on disk (`档缺` when it does not), and when a section
+  indicator is given the target file must carry a heading numbered with it (`节缺` when it does not). Line-number coordinates
+  (`<doc>:12`) are not section references and are not judged as such. Files inside fenced code blocks and executable lines
+  (command / pattern code spans) are skipped whole.
+- Line width — a line whose character count (CJK counts as 1) exceeds the declared threshold, unless it is a table row, inside a
+  fenced code block, an executable line, a quote-block line, or inside an exempt zone.
+
+It cannot — in `report` mode — write anything, gate anything, or turn a finding into a refusal.
+
+Arguments — `target` (optional): the project root to check; defaults to the session anchor, relative paths resolve against it.
+A workspace target (several projects below it) is reported with the full candidate list — pass the project root you mean.
+`mode` (optional) — `report` (default: the whole declared domain) or `gate` (the delivery gate below).
+`docs` (optional, gate only) — the documents this round touched, as paths relative to the project root or absolute; omitted in
+gate mode ⇒ the documents this session wrote. Passing `docs` with `mode: "report"` is refused rather than silently ignored.
+
+Delivery gate — `mode: "gate"`, for the end of a design or development round. Every listed doc is judged **whole**: a
+pre-existing dangling pointer or overlong line anywhere in it counts, not only this round's edited lines. The first line is the
+machine-readable verdict — `DOC-CHECK GATE: PASS` / `DOC-CHECK GATE: REFUSED（命中 K 条）` / `DOC-CHECK GATE: ERROR（reason）` —
+and consumers judge by that prefix; the hits are fixed in the same round and are never booked to the ledger. The gate refuses
+**one delivery**, not a user instruction: an explicit user go-ahead is followed, with the hits written into the delivery.
+The gate narrows the judged set, not the parse baseline: bare-name pointers still resolve across the whole declared domain, so
+judging one doc never turns a pointer into a false `档缺`.
+Before running the criteria the gate checks engine-version consistency: the six engine files (`doc-check/index.mjs` /
+`doc-check/anchors.mjs` / `doc-check/width.mjs` / `doc-check/version.mjs` / `agent-tools/doc-check.mjs` / this tool description) each have their mtime
+compared with this process's start time — newer, or unreadable, ⇒ `DOC-CHECK GATE: ERROR（引擎已更新…）` instead of a PASS,
+because a session keeps the engine modules it loaded at startup. `ERROR` is fail-closed (no PASS means not passed): restart the
+session and re-run; a missing / unreadable manifest ⇒ fix the declaration surface; a multi-project workspace ⇒ name the project
+root, per the stated cause.
+
+Do not wire it as a gate or CI step in `report` mode, and do not treat a finding as a reason to refuse an instruction — a
+machine check never outranks a user instruction.
+
+Routing — use it when you write or revise a project's documents and want the declared discipline checked in one pass. It is not
+a reader: use `doc_search` / `read` to read documents and `grep` to search them; this tool only reports discipline findings.
+
+Side effects and permissions — none. The tool is read-only: no writes, no approval prompt, safe to run in parallel with other calls.
+
+Parameter source and failure shape — every parameter comes from `<target>/PROJECT-MANIFEST.json` `checkConfig` (`scanDirs` /
+`lineWidth` / `widthExemptZones` / `anchors.exclude` / `anchors.roots`); no repository path is hard-coded, so another project runs it with its own
+declarations. Changing those declarations changes the behavior. A missing or unreadable manifest is surfaced as an error line
+naming the file — the check never fabricates a result; in gate mode it yields the `ERROR` first line instead of a PASS.
+`anchors.roots` (optional string array of project-root-relative directories) widens anchor resolution only — never the line-width scope.
+
+Consistency — the checks and this description are one core implementation: every end that loads the core tool registry gets the
+same semantics.

package/tool-docs/fetch.md

@@ -1,4 +1,4 @@
-Fetch a URL and return its content as text. HTML pages are stripped to readable text. Use after websearch to read full documents.
+Fetch a URL and return its content. With a DeepSeek provider configured the URL is fetched through DeepSeek's servers and returned as Markdown ([deepseek] title + content); otherwise it is fetched locally and HTML is stripped to readable text. Private/metadata URLs are never sent. Use after websearch to read full documents.
 
 Parameters:
 - url (required): http/https URL
@@ -8,5 +8,6 @@ Notes:
 - Follows redirects automatically
 - Timeout: 15 seconds
 - HTML pages are converted to plain text (scripts, styles, navigation stripped)
-- Non-HTML responses are returned as-is (truncated at ~50000 chars)
+- Non-HTML responses are returned as-is (truncated at ~200000 chars)
 - Proxy support: set `"proxy": {"uri": "http://host:port", "web": true}` in config.json or `HTTPS_PROXY` env var
+- fetch.backend: "local" disables the DeepSeek backend.

package/tool-docs/ledger.md

@@ -1,6 +1,8 @@
 台账统一入口——action = add / update / close / query / count。query / count 只读全角色；add / update / close 写仅主 agent。
-- add：新增条目入待讨论。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）。
-- update：按六态允许表迁移：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外拒。status 缺省 = 仅更新字段；executor 缺省 = 进入待设计 / 在途自动写本会话，出在途 / 撤回清空。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`——「｜」零空格；旧空直写）；`evidenceReplace: true` 与 evidence 同传 = 整段替换；旗独传（无新文）∥ 新值全空白 ⇒ 拒。
-- close：勾销（待核销 → 已核销）；追认核销（待讨论 / 待设计 → 已核销，须有 evidence——可随本调用传入（一跳核销），判结果值：缺 / 全空白拒）；在途 → 已核销 不可跳；撤回（任意态 → 已废弃）。软删除（写 closed_at，行保留）。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`；旧空直写）；`evidenceReplace: true` 同传 = 整段替换；旗独传 / 新值全空白 ⇒ 拒；缺省 = 判行值。
-- query：SQLite 行集，等值过滤（status / kind / board / trigger）缺省 = 全部行；行集逐行携 aged（未决四态 ∧ 行龄 > 30 天）。六态 = 待讨论 / 待设计 / 在途 / 待核销 / 已核销 / 已废弃。
-- count：未决四态（待讨论 / 待设计 / 在途 / 待核销）COUNT(*)。
+- add：新增条目入待讨论。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）；resume_when = 复启条件句（可空；值非空——空串 / 全空白拒；句内可带锚 `@YYYY-MM-DD`（机判到期）或 `@事件件名`（机器不判））。task_book 写门（add ∥ update 同判，判本笔写入面）：结果行 在途 / 待核销 ∥ trigger = 归批 ⇒ task_book 必填（缺 / 空串 / 全空白拒）；本笔新写 task_book（非空值）∥ 本笔新写 trigger = 归批 ⇒ 该指针的文件部分（首个 `§` 前子串）须可解析且指出的档在盘，否则拒。本笔不动指针 ⇒ 零判零阻——旧指针所指档已被清理不阻 status / evidence / 其它字段更新（「档在不在盘」是读数 taskBookOnDisk，不是门）。
+- update：按六态允许表迁移：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外拒。id ∥ batch 恰携其一。status 缺省 = 仅更新字段；executor 缺省 = 进入待设计 / 在途自动写本会话，出在途 / 撤回清空；resume_when 同 update 可空字段（缺省 = 不变）。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`——「｜」零空格；旧空直写）；`evidenceReplace: true` 与 evidence 同传 = 整段替换；旗独传（无新文）∥ 新值全空白 ⇒ 拒。
+- update --batch：批级批量迁移（batch = 批档指针，与该档 task_book 同址的行一次处理）——携 status ⇒ 逐行按迁移表重判；不携 status ⇒ 纯字段补丁（status 零写）。回执 { batch, status, applied, skipped }；被跳过的行逐行点名 { id, from, why }（why = 逐行拒因原文），其余行照落；事务级失败整批回滚。batch 值须可解析且批档在盘，否则拒。
+- close：勾销（待核销 → 已核销）；追认核销（待讨论 / 待设计 → 已核销，须有 evidence——可随本调用传入（一跳核销），判结果值：缺 / 全空白拒）；在途 → 已核销 不可跳；撤回（任意态 → 已废弃）。软删除（写 closed_at，行保留）。id ∥ batch 恰携其一。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`；旧空直写）；`evidenceReplace: true` 同传 = 整段替换；旗独传 / 新值全空白 ⇒ 拒；缺省 = 判行值。
+- close --batch：批级批量结算——只销已到 待核销 的行（勾销）；待讨论 / 待设计 逐行点名跳过（追认核销不入批量面，转单行 close），在途 逐行点名跳过（不可跳）；已核销 / 已废弃 行静默不计。status 可不给（缺省 = 已核销），给了只能是 已核销。
+- query：SQLite 行集，等值过滤（status / kind / board / trigger / task_book）缺省 = 全部行；行集逐行携 aged（未决四态 ∧ 行龄 > 30 天）/ evidenceOversize（evidence 超软上限 300 字——读数非拒写）/ taskBookOnDisk（task_book 文件部分解析成立 ∧ 该档在盘 ⇒ true；缺指针 / 不可解析 / 不在盘 ⇒ false——读数非门，不拦任何写入）/ overdue（出口态字串 ∥ null：resume_due / dangling / unlabeled / aged，首中优先）。六态 = 待讨论 / 待设计 / 在途 / 待核销 / 已核销 / 已废弃。
+- count：回报 { count, overdue, evidenceOversize }——count = 未决四态（待讨论 / 待设计 / 在途 / 待核销）行数；overdue = 其中命中出口态的行数；evidenceOversize = 其中 evidence 超限行数。task_book 等值过滤。

package/tool-docs/manifest.md

@@ -1,11 +1,11 @@
 Read, initialize, or point-edit the project manifest (PROJECT-MANIFEST.json) — the project-level state file (phase / docRoot / checkConfig / codePaths / index / advisor). Attached to the main agent only; subagents can neither see nor write it.
 
 Actions:
-- read [target] — report the manifest state with a stable anchor `state=ok|missing|invalid|ambiguous|no-project`. The ok state prints the manifest JSON plus missingKeys / unknownKeys / errors rows (only when non-empty). Never throws — a missing manifest is reported, not refused.
+- read [target] — report the manifest state with a stable anchor `state=ok|missing|invalid|workspace|no-project`. The ok state prints the manifest JSON plus missingKeys / unknownKeys / errors rows (only when non-empty). Never throws — a missing manifest is reported, not refused.
 - init [target] — create the default manifest where the project root resolves (the target itself when no project is discoverable). Refused when a manifest already exists — init never overwrites.
 - write <key> <value> [target] — point-edit one node: read the current manifest, set the node, write it back through the writer gate. The resulting manifest must pass validation (a fault is refused with the disk byte-for-byte unchanged); a missing manifest is refused — run init first (write never creates one).
 
-target — explicit target directory; defaults to the session anchor, relative paths resolve against it. An ambiguous target (2+ candidate projects) is refused with the full candidate list — the mechanism never picks one.
+target — explicit target directory; defaults to the session anchor, relative paths resolve against it. A workspace target (several projects below it) is reported by `read` and refused by `init` / `write` — with the facts, the full candidate list and a next step: name the project root you mean and pass it as target.
 
 key — dot path into the manifest, one of the writable nodes: version / phase / promptsLanding / codePaths, or a sub-key of docRoot / checkConfig / index / advisor (e.g. docRoot.design / index.publicRepos / advisor.docMap). Whole-object writes of those four families are refused, as is any key outside the set (spelling protection).
 
@@ -14,3 +14,15 @@ value — parsed as JSON first (null / true / 5 / ["a","b"]), falling back to a
 Refusals throw `manifest <action>: refused — …` and leave the disk unchanged. The written file is picked up by the session's project-state line on the next turn (mtime-gated) — the tool never touches in-memory state.
 
 read is read-only (planMode passes, no approval); init / write are side effects (approval gate). Writes go through writeManifest / initManifest with writer "main" — the fail-closed subagent default is never used.
+
+Key catalog — the writable nodes: what each is; when to change it; wrong ⇒ consequence.
+- `version` — schema version (a number); change on file migration; wrong ⇒ validation refuses (disk unchanged).
+- `phase` — project stage, `initial-dev` / `production`; change when the stage is crossed; wrong ⇒ validation refuses.
+- `promptsLanding` — declared prompt-landing directory; change when it moves; no failure consequence (no shape check, no in-core reader — a registration face).
+- `codePaths` — path segment names (replaces the default `["src"]`); change when the layout moves; wrong ⇒ no segment is classified (the fallback still runs).
+- `docRoot.requirements` · `docRoot.specs` · `docRoot.design` · `docRoot.modules` · `docRoot.batches` — each doc-layer root path (a string | a multi-root array | `null` = absent); change when a layer moves root; wrong ⇒ validation refuses, or checks / batch landing / review roots point elsewhere.
+- `checkConfig.scanDirs` · `checkConfig.lineWidth` · `checkConfig.widthExemptZones` · `checkConfig.anchors` · `checkConfig.exemptions` — machine-check settings (scan dirs / width / exempt zones / anchors / exemptions); change when the check scope changes; wrong ⇒ checks run on a wrong scope silently (missed scans / wrong width / dead exemptions).
+- `index.codeExtensions` · `index.docExtensions` — extra code / doc extensions (unioned, add-only); change when a file type is missing from the index; wrong ⇒ that type stays out of the index (extras harmless; a missing entry = a miss).
+- `index.excludePaths` — project-root-relative path prefixes (for the index); change to keep a directory out of the index; wrong ⇒ that directory is still indexed, or another is wrongly excluded.
+- `index.publicRepos` — public-repo paths (resolvable from this repo root); change when wiring a public repo into the index or cross-repo refs; wrong ⇒ that repo is unreachable for retrieval (empty origin set / wrong path).
+- `advisor.docMap` · `advisor.standardsDoc` — review pointers (map file / single standards doc; empty = not declared); change when the review injection face changes; wrong ⇒ review injection lands nothing (an unreadable doc ⇒ review with no doc).

package/tool-docs/ssh.md

@@ -0,0 +1,51 @@
+Open and drive a persistent interactive SSH session (remote login shell) on a host. The session survives across tool calls; password hosts get a credential window — the value never appears in tool args or results (an explicit opt-in can store it as ciphertext on this machine).
+
+**Route to ssh instead of bash:**
+- a one-shot non-interactive command over ssh → `bash` with `ssh host <command>` (cheaper, no session)
+- an interactive shell that must survive several calls (network device CLI, interactive prompts) → ssh
+
+Parameters:
+- action (required): connect | send | read | secret_input | close | list | credentials | forget
+- host: connect / forget — target host (IP or name)
+- user: connect — login user (optional: your local ssh config decides, else the user recorded for this host locally)
+- port: connect / forget — TCP port (optional, default 22)
+- label: connect — short human label for this session (optional); secret_input — label for the value being sent
+- promptPattern: connect — regex that marks the shell prompt as ready (optional): send/read then settle the moment the prompt appears instead of waiting out the silence window
+- identityFile: connect — private-key path to offer as `-i` (`~` expands); remembered for this host and reused when omitted (optional)
+- id: send / read / secret_input / close — session id from connect (`ssh#N`)
+- data: send — text to type into the session (a trailing newline is passed as-is; otherwise Enter is sent as `\r`)
+- settle: send — wait for the ready verdict before returning (default true); false returns right after the bytes are written
+- timeoutMs: send / read — wait budget override (default 10000; the wait then returns partial output with a readable line)
+- maxChars: read — return cap override (default 8000; the full output stays in the session log)
+
+Output:
+- every result starts with the session status line: `[ssh (ssh#3) 10.0.0.5 — ready · idle 3s]`
+- connect returns the first screen; send returns the round's output plus the ready verdict (silence | prompt matched | timeout); read returns what arrived since the last read
+
+Notes:
+- Key-first: keys, your ssh config and ssh-agent are always tried before any saved credential — a connect succeeds without a window
+  when a key works, and the credential store is not read at all in that case. To make a password host prompt-free, install a key once:
+  `ssh-keygen -t ed25519` (if you have none), then `ssh-copy-id user@host` (or append `id_ed25519.pub` to the host's
+  `~/.ssh/authorized_keys`), then reconnect.
+- Credential discipline: the password is asked for in a window and reaches ssh only through its child-process environment — never in tool
+  args, never echoed in a result, never stored in plaintext. Any captured output containing that value (or a value given to secret_input)
+  is scrubbed from the returned text and from the session log.
+- Saving a credential is opt-in: the credential window carries a `save` checkbox (off by default). When checked and authentication succeeds,
+  the password is stored encrypted with your OS user account (Windows DPAPI) in a per-user file outside the repository; the store holds only
+  ciphertext. A saved credential is reused silently — the next connect skips the window, and only after key
+  authentication fails. The residual risk is honest: another process running as the same logged-in user can decrypt it; this protects the
+  file at rest, not a compromised account. Saving is Windows-only for now; on other platforms the checkbox does not appear and the window
+  keeps asking.
+- Fail-soft: an unreadable/undecryptable entry, a damaged store or a missing backend falls back to the credential window (the connection is
+  not broken; undecryptable entries are kept). If the server rejects a saved credential it is deleted and the window is shown. A failed save
+  never affects the connection.
+- secret_input is for device prompts (enable password, sudo, key passphrases): it opens the same kind of window, writes the value plus Enter, and returns only the output — the value is never shown.
+- Sessions: at most 4 live at once (a connect beyond the cap is refused — close one first). A session idle for 600s with no send/read is closed automatically. `close` ends it (stdin EOF → 1.5s grace → the process tree is killed). Ctrl+I (interrupt) does not kill sessions; a user Stop does.
+- Output is capped per return (8000 chars, tail kept); the full stream is always in the session log whose path connect returns.
+- Not for full-screen terminal UIs (vim/top/screen): output is read as a text stream — paged output such as `--More--` is shown as-is, not driven for you.
+- Host keys follow your local ssh config — the tool never rewrites known_hosts. A changed or untrusted key stops the connect with a readable error before any credential is asked for.
+- read / list / credentials are read-only (no approval prompt); connect / send / secret_input / close / forget pass the approval gate like any side-effecting tool, and secret_input shows a masked placeholder — the value itself is never in the approval text.
+- credentials lists saved entries (host / user / saved / last used — never a value); forget deletes the entry for a host (and optional port) and is idempotent — the next connect asks in the window again.
+- Not for file transfer or port forwarding — run `scp` / `sftp` / `ssh -L` through bash.
+
+Availability: where the end has no UI to collect a credential (headless / ACP), connecting to a password host fails with a readable error — use keys or an ssh-agent there.

package/tool-docs/subagent.md

@@ -7,7 +7,8 @@ ONE tool, NINE actions — pick by what you need:
 - 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. Selectors — pass exactly ONE: designId (a single slot; optional for a single-design session), designIds (an explicit non-empty list), expired:true (every expired slot), or olderThanDays:N (every slot older than N days). 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); batch calls report per-slot lines + a `consumed N` count line. Do NOT call while the chain is still open — fix rounds reuse the same slot.
-- action:'design-slots' (engineering mode, parent side): READ-ONLY inventory of this session's approved design token slots — one line per slot (designId, live|expired, ageDays, expiresAt, batch), oldest first, ending with a total/live/expired count line. Nothing is written. Use it to see what still holds a slot before consuming; the expired / olderThanDays selectors act on the same set.
+- action:'design-slots' (engineering mode, parent side): READ-ONLY inventory of this session's approved design token slots — one line per slot (designId, live|expired, ageDays, expiresAt, batch, designToken), oldest first, ending with a total/live/expired count line. Nothing is written. Use it to see what still holds a slot before consuming; the expired / olderThanDays selectors act on the same set.
+  Every row carries its designToken value (expired ones included — status marks them; a malformed record shows designToken=—). Pass designId to filter to a single slot (trimmed exact match; unknown = refused with the held id list; empty string = no filter). Take designId + designToken verbatim onto the eng-coder spawn — the gate checks exact equality.
 - 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.
@@ -19,15 +20,11 @@ Available roles (exposed per mode; the role is REQUIRED for action:'spawn' — a
 - 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).
 
-Task book (eng-coder / eng-designer spawns — six mandatory fields): 目标与理由 (goal & why), round (initial|fix — the structured parameter), 已知事实 (known facts), 设计要点与禁止范围 (design points & forbidden scope), 验收标准 (acceptance criteria), 交付报告格式 (delivery-report format). Keep the labels (Chinese or the English equivalents) — the gate matches these markers; a missing field is a dispatch defect and the spawn is refused.
+Task book (every spawn role): four core structured parameters — goal (goal & why), knownFacts (the facts you already verified), acceptance (machine-verifiable criteria), reportFormat (delivery-report format) — plus ONE fifth parameter named by role: designPoints (design points & forbidden scope) for eng-coder/eng-designer, scope (scope & forbidden scope — what to read / what not to touch) for explore/plan/coder. All five are required: a missing, blank or non-string value is refused with the parameter named, and one role's fifth name never substitutes for the other's. They are composed into the child's brief in that order. A free-text task is an optional supplement, never the whole brief; round (initial|fix) is mandatory for eng-coder/eng-designer.
 
-Copy this skeleton verbatim into every task book — fill the blanks, do not relabel the six lines:
-**目标与理由**：…
-**round**：initial | fix（此字段=结构化参数——spawn 时同时传 `round`）
-**已知事实**：…
-**设计要点与禁止范围**：…
-**验收标准**：…
-**交付报告格式**：…
+Pass one parameter per field — contents only (the runtime adds the labels):
+subagent(role="eng-coder", round="initial", goal="…", knownFacts="…", designPoints="…", acceptance="…", reportFormat="…", batchDoc="<batch record>", designToken="…")
+subagent(role="explore", goal="…", knownFacts="…", scope="…", acceptance="…", reportFormat="…")
 
 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).
 

package/tool-docs/timer.md

@@ -8,5 +8,6 @@ Beyond a one-shot countdown, three schedule forms are available, one per call (`
 All times are local to the host.
 `cancel` takes the id from the set confirmation and stops that timer; `list` shows every pending timer with its next due time. Repeating timers occupy one pending slot each until cancelled.
 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.
+Delivery: 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).
+A user turn gets no delivery: while a session turn is running, an expired timer waits for the next delivery round (suspension window / idle latch); 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/websearch.md

@@ -1,4 +1,4 @@
-Search the web via Bing. Returns result titles, URLs, and snippets. Use for looking up current information, docs, error messages.
+Search the web (DeepSeek Search when a DeepSeek provider is configured; otherwise Tavily with a key, else Bing). Returns result titles, URLs, and snippets — DeepSeek results also carry a date · authority (0–4) · rerank (0–3) line and a long summary. Use for looking up current information, docs, error messages.
 
 Parameters:
 - query (required): Search query
@@ -14,3 +14,5 @@ Notes:
 - Follow up with `fetch` to read full pages from the results
 - **Weak engine warning**: Bing's index is noisy for technical queries — if a first websearch returns irrelevant/townhall-grade results, DO NOT retry the same query. Configure a search MCP tool (e.g. `glm-websearch` via the MCP config) for technical lookups; websearch is the fallback.
 - Proxy: NOT auto-applied from config.json (2026-08-31 ruling). Pass `proxy: "http://host:port"` explicitly when the target needs one; omit for domestic targets.
+- Backend priority: DeepSeek (auto — a providers[] entry with baseURL host api.deepseek.com and a key) → Tavily → Bing. websearch.backend: "local" disables the DeepSeek backend.
+- DeepSeek query operators: site:, lang:, after:/before:, and quoted phrases pass through as-is; limit maps to count (1–20).

package/tools/browser.mjs

@@ -6,7 +6,7 @@
  * `clipboard` 全量；免审 = `navigate` ∥ `type` ∥ `snapshot` ∥ `screenshot` ∥ `wait` ∥ `close` +
  * `hover` ∥ `wheel` ∥ `insert` ∥ `touch` 手势（swipe / pinch）——同一钩子按参数分类，机制零新增。
  * 失败回执**返回**（不 throw）——首行 `Error: …` = 模型面失败形（`bash`/`execute` 既例；dispatch 侧按该前缀
- * 判失败——`agent/dispatch-run.mjs:77` ∥ `:129` ∥ `:135`）。
+ * 判失败——`agent/dispatch-run.mjs` 的 `runPreparedItem`（三处））。
  * 异步面（§2.11——批 browser-async-fix）：`async:true`（depth-0 专项）⇒ `agent-tools/browser-async.mjs`
  * 起跑（ack 即返——本档薄接线；depth 第二道在此，schema 删参在 `agent/helpers.mjs` `excludeSubagentTools`）。
  */

package/tools/execute.mjs

@@ -61,7 +61,7 @@ function applyFilter(output, filter) {
 }
 
 /** 树杀单源 = `tools/process-tree.mjs`（TOOLS.md §6.14 落位表行 2：自本档抽出以断
- *  `shared → git-run → execute → shared` 环）；**再导出面保留**（`test/tool-seams.test.mjs:26` 消费，
+ *  `shared → git-run → execute → shared` 环）；**再导出面保留**（
  *  `configureProcessTreeKill` 缺省径零改）。 */
 export { killProcessTree }
 

package/tools/git-run.mjs

@@ -33,7 +33,7 @@ export const GIT_NET_TIMEOUT_MS = 300_000
 /** 网路面五动作（300s 档——合法耗时可远超本地；依据 = 需求档 §4.7 TTY-DRIVE N3 候选参照值）。 */
 const GIT_NET_ACTIONS = new Set(["push", "fetch", "pull", "clone", "ls-remote"])
 
-/** 测试态缝（模块级 · 缺省 null = 生产零行为变——先例 `manifest-discovery.mjs:15-20` · `session-gc.mjs:186`）。
+/** 测试态缝（模块级 · 缺省 null = 生产零行为变——先例 `manifest-discovery.mjs` 的 `_setProjectRootForTest` · `session-gc.mjs` 的 `_setSessionGcDelayForTest`）。
  *  用例 `finally` 复位；不经用户参数面（边界：不新增参数 / 用户选项）。 */
 let gitTimeoutOverride = null
 export function _setGitTimeoutForTest(ms) { gitTimeoutOverride = ms }
@@ -100,7 +100,7 @@ export function spawnGit(cwd, args, { timeout, maxBuffer } = {}) {
     }
     const treeKill = () => { try { killProcessTree(child) } catch { /* 尽力而为 */ } }
     // 超时动作序（§6.14）：① 直接子 → ② 逾 1.5s 树杀（`killProcessTree`，尽力而为）→ ③ 逾 1.5s 未 `close`
-    // 亦 settle（kick——孙进程持管道时 `close` 永不触发，`bash.mjs:200-217` 同款）。上界 = timeout + 3s。
+    // 亦 settle（kick——孙进程持管道时 `close` 永不触发，`bash.mjs` 的 `runBash` 同款）。上界 = timeout + 3s。
     // 平台分岔（§6.14 平台注的后果）：win32 上 SIGTERM 实为硬终止且**不连带子进程**——父一死，
     // `taskkill /PID <父> /T` 就够不到孙进程（实测：helper 孤儿存活、管道不放 ⇒ 只能等 kick）⇒
     // win32 直接走树杀（须在树仍可寻址时执行）；POSIX 保留宽限序（组杀在头进程死后仍可达全组）。

package/tools/git.mjs

@@ -40,14 +40,14 @@ function resolveBaseDir(cwd, workdir) {
  *  二者仍可经显式 `workdir` 指落点。 */
 const NO_REPO_DISCOVERY = new Set(["init", "clone"])
 
-/** 歧义（多态）消息：候选全列（绝对路径、按名排序）+ 指引显式 `workdir`——不猜（§6.13 解析序行 5）；
+/** 工作区（多仓）消息：下辖仓全列（绝对路径、按名排序）+ 指引显式 `workdir`（§6.13 解析序行 5）；
  *  **两档变体**（#188——按 `matched`）：带档级 ⇒ 「.git ∧ PROJECT-MANIFEST.json」；裸仓级 ⇒ 「.git」
- *  且注明 none carries …（不书带档句——§6.13 A22）。 */
-function ambiguousRepoMessage(candidates, cwd, matched) {
+ *  且注明 none carries …（不书带档句——§6.13 A22）。事实行，非错误框定（用户裁定「cwd 下多仓是常态」）。 */
+function workspaceRepoMessage(candidates, cwd, matched) {
   const head = matched === "git"
-    ? `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git (none carries ${MANIFEST_REL})`
-    : `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git and ${MANIFEST_REL}`
-  return `${head} — pass workdir to run git in the intended one (no silent pick):\n` + candidates.map((c) => `- ${c}`).join("\n")
+    ? `${cwd} is a workspace holding ${candidates.length} repositories — subdirectories carry .git (none carries ${MANIFEST_REL})`
+    : `${cwd} is a workspace holding ${candidates.length} repositories — subdirectories carry .git and ${MANIFEST_REL}`
+  return `${head} — pass workdir to run git in the intended one:\n` + candidates.map((c) => `- ${c}`).join("\n")
 }
 
 export const gitTool = {
@@ -96,13 +96,13 @@ export const gitTool = {
     if (args.workdir) ctx = { ...ctx, cwd: resolveBaseDir(ctx.cwd, args.workdir) }
     // 仓发现（§6.13 · #62）：缺省路径（无 workdir）⇒ 单源 = `discoverRepos`（仓梯——#188 含裸仓级）
     // ——工作区根（非仓）⇒ 唯一带档子仓 / 零档时唯一裸仓：重定向 `ctx.cwd` + 结果首行注记；零 ⇒ 原值
-    // 落 §6.12 fail-closed（零行为变）；多 ⇒ throw（列该级候选 + 指 workdir，不猜——消息按 `matched`
+    // 落 §6.12 fail-closed（零行为变）；多 ⇒ throw（下辖仓全列 + 指 `workdir`——消息按 `matched`
     // 两档变体）。判据 = workdir 真值在场（与上行同源——空串与缺省同判）；`init` / `clone` 例外
     // 不做发现。self / none 态 ctx 对象引用透传（不 clone）。
     let repoNote = ""
     if (!args.workdir && !NO_REPO_DISCOVERY.has(args.action)) {
       const discovered = discoverRepos(ctx.cwd)
-      if (discovered.kind === "ambiguous") throw new Error(ambiguousRepoMessage(discovered.candidates, ctx.cwd, discovered.matched))
+      if (discovered.kind === "workspace") throw new Error(workspaceRepoMessage(discovered.candidates, ctx.cwd, discovered.matched))
       if (discovered.kind === "unique") {
         ctx = { ...ctx, cwd: discovered.root }
         repoNote = `(repo: ${discovered.root})`

package/tools/index.mjs

@@ -14,6 +14,7 @@ import { executeTool } from "./execute.mjs";
 import { fileOpsTool, processTool, getCurrentTimeTool, waitForTool } from "./ops.mjs";
 import { treeTool } from "./tree.mjs";
 import { browserTool } from "./browser.mjs";
+import { sshTool } from "./ssh.mjs";
 
 // Instance-independent built-in table. `read_image` is deliberately NOT here:
 // its registration is capability-gated per model — see `assembleBuiltinTools`.
@@ -26,6 +27,7 @@ export const builtinTools = [
   fileOpsTool, processTool, getCurrentTimeTool, waitForTool,
   treeTool,
   browserTool,
+  sshTool,
 ];
 
 export {
@@ -37,6 +39,7 @@ export {
   fileOpsTool, processTool, getCurrentTimeTool, waitForTool,
   treeTool,
   browserTool,
+  sshTool,
 };
 
 // ── Full built-in registry (CORE-UNIFICATION TOOLS #70) ─────────────────────

package/tools/ops.mjs

@@ -60,7 +60,7 @@ export const processTool = {
       id: { type: "number", description: "kill target: background task id — a bash#N (bash async ack) or browser#N (browser async ack): bash ⇒ its process tree is terminated; browser ⇒ a queued task is dropped, a running one is aborted (the browser itself is not killed); either way the entry leaves the pool and no digest will arrive." },
     },
   },
-  // #9：动作分级——list 保持只读分类（dispatch-gates `isSubagentReadonlyAction`：planMode 放行/
+  // #9：动作分级——list 保持只读分类（dispatch-gates `isReadonlyAction`：planMode 放行/
   // 免审批）；kill 是破坏性动作（审批门）。`parallel` 保既有调度形（list 恒可批并行）。
   readonly: false,
   parallel: true,

package/tools/process-tree.mjs

@@ -1,8 +1,8 @@
 /**
  * tools/process-tree.mjs — 平台感知树杀单源（自 `execute.mjs` 抽出——TOOLS.md §6.14 落位表行 2）。
- * 抽出理由 = **断环**：`shared → git-run → execute → shared` 会 TDZ（`execute.mjs:29` 在模块求值期
+ * 抽出理由 = **断环**：`shared → git-run → execute → shared` 会 TDZ（`execute.mjs` 在模块求值期
  * 调 `DESC`（`const`））⇒ 树杀须住两不依赖档。行为逐字同（win32 `taskkill /T /F` · POSIX 组杀 + 直杀兜底）。
- * `execute.mjs` 保持再导出面（`test/tool-seams.test.mjs:26` 消费）。
+ * `execute.mjs` 保持再导出面。
  */
 import { execFileSync } from "node:child_process"
 

package/tools/ssh-askpass.mjs

@@ -0,0 +1,35 @@
+/**
+ * ssh-askpass.mjs — SSH 口令助手（独立进程入口；设计 = `docs/core/design/TOOLS.md` §6.22 ② · D-TO18）。
+ *
+ * 调用面 = ssh 经包装档（`<node> <本档> %*`）执行本档：argv[1] = 提示语本体
+ * （上游 `readpass.c` `ssh_askpass()`：`execlp(askpass, askpass, msg, NULL)`）。
+ * 输出面 = stdout **仅一行**（ssh 读首行作答复；`readpass.c` 取到首个 \r|\n 即止）。
+ * 秘密来源 = 环境变量 `TC_SSH_SECRET`（ssh 子进程环境——不入 argv / ps；§6.22 ②「秘密传递」行）。
+ * 零日志 / 零落盘 / 零回显——本档只写 stdout，不碰任何持久面。
+ *
+ * 答复判定（三分支，逐条有据）：
+ * 1. `SSH_ASKPASS_PROMPT === "confirm"` ⇒ `yes`——上游 `readpass.c` 的 `RP_ASK_PERMISSION`
+ *    径（如 `AddKeysToAgent=ask` 的 `ask_permission()`）；设计 §6.22 ② 同句。
+ * 2. 有秘密且提示语是主机确认句 ⇒ `yes`——**host-key 确认径不设该环境提示**
+ *    （`sshconnect.c` `confirm()` 走 `read_passphrase(msg, RP_ECHO)`，非 `RP_ASK_PERMISSION`
+ *    ⇒ 无 hint），故以提示语首行判定（确认句首行 = `The authenticity of host …`）。
+ * 3. 有秘密 ⇒ 秘密本体（password ∥ keyboard-interactive 两径同走 `read_passphrase`）。
+ *    无秘密 ⇒ `yes`——无秘密的场合 = 预探连（`NumberOfPasswordPrompts=0`），此刻**只可能**
+ *    收到确认类提问：password ∥ keyboard-interactive 被该选项短路（`sshconnect2.c`
+ *    `userauth_passwd` / `userauth_kbdint` 两处同判 `attempt++ >= number_of_password_prompts`）、
+ *    私钥口令提示亦被短路（`load_identity_file` 循环 `i <= number_of_password_prompts`）。
+ */
+const SECRET_ENV = "TC_SSH_SECRET"
+/** 主机确认句判据（首行；Windows `.cmd` 中介可能截断 argv——首行判据对截断不敏感）。 */
+const HOST_CONFIRM_RE = /authenticity of host|continue connecting/i
+
+const prompt = String(process.argv[2] ?? "")
+const hint = String(process.env.SSH_ASKPASS_PROMPT ?? "")
+const secret = process.env[SECRET_ENV]
+
+let answer
+if (hint === "confirm" || (secret && HOST_CONFIRM_RE.test(prompt))) answer = "yes"
+else if (secret) answer = secret
+else answer = "yes"
+
+process.stdout.write(`${answer}\n`)

package/tools/ssh.mjs

@@ -0,0 +1,105 @@
+/**
+ * tools/ssh.mjs — SSH 会话工具面（薄接线）：schema ∥ 参数校验 ∥ `isReadonlyAction` ∥ 回执/错误形
+ * （设计 = `docs/core/design/TOOLS.md` §6.22 —— D-TO17/D-TO18 · 台账 #1436；保存面 D-TO19/D-TO20 · 台账 #1602；
+ * 机制单点 = `agent-tools/ssh-session.mjs`（保存件 = `agent-tools/ssh-vault.mjs`）；描述档 = `tool-docs/ssh.md`）。
+ *
+ * 分类钩子（KD-2 ∥ KD-11 同式——动作级，工具级只读位恒 false）：免审 = `list` ∥ `read` ∥ `credentials`
+ * （只读豁免，NS3 判据）；过门 = `connect` ∥ `send` ∥ `secret_input` ∥ `close` ∥ `forget`——**携密动作仍属
+ * 写动作**，门不放松；携密径审批文案 = 掩码占位（`permission.mjs`，值不回显 ⇒ 不入上下文 / 审批记录）。
+ *
+ * 失败回执**返回**（不 throw）——首行 `Error: …` = 模型面失败形（`bash` / `browser` 既例）；
+ * 无 UI 考（缺 `ctx.onSecretInput` 回调）⇒ 机制档抛可读错（`question.mjs` 无 UI 抛例同旨）。
+ * 会话跨调用存活于池（非本档持有）；depth>0 排除（`agent/helpers.mjs` `SUBAGENT_TOOL_EXCLUSIONS`）。
+ * 动态 import（W8 契约②：agent-tools 静态链达 node:sqlite——端壳静态闭包须保持零命中）。
+ */
+import { DESC } from "./shared.mjs"
+
+export const SSH_ACTIONS = ["connect", "send", "read", "secret_input", "close", "list", "credentials", "forget"]
+
+/** 参数校验（缺必填 / 形错 ⇒ `Error: …`——不执行；§6.22 动作表逐动作必填面）。 */
+export function validateArgs(args) {
+  const action = args?.action
+  if (!SSH_ACTIONS.includes(action)) {
+    return `Error: unknown ssh action "${action ?? ""}" — actions: ${SSH_ACTIONS.join(", ")}`
+  }
+  if (action === "connect") {
+    if (typeof args.host !== "string" || args.host.trim() === "") return "Error: connect requires host"
+    if (args.port !== undefined && args.port !== null && args.port !== "" && !Number.isFinite(Number(args.port))) {
+      return "Error: connect port must be a number"
+    }
+    return null
+  }
+  if (action === "list" || action === "credentials") return null
+  if (action === "forget") {
+    if (typeof args.host !== "string" || args.host.trim() === "") return "Error: forget requires host"
+    if (args.port !== undefined && args.port !== null && args.port !== "" && !Number.isFinite(Number(args.port))) {
+      return "Error: forget port must be a number"
+    }
+    return null
+  }
+  if (typeof args.id !== "string" || args.id.trim() === "") {
+    return `Error: ${action} requires id (the session id from connect, form "ssh#N")`
+  }
+  if (action === "send" && typeof args.data !== "string") return "Error: send requires data"
+  return null
+}
+
+export const sshTool = {
+  name: "ssh",
+  description: DESC("ssh"),
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: SSH_ACTIONS, description: "Action to run (one per call): connect | send | read | secret_input | close | list | credentials | forget." },
+      host: { type: "string", description: "connect / forget: target host (IP or name)." },
+      user: { type: "string", description: "connect: login user (optional: your local ssh config decides, else the user recorded for this host locally)." },
+      port: { type: "number", description: "connect / forget: TCP port (optional, default 22)." },
+      label: { type: "string", description: "connect: short human label for this session (optional); secret_input: label for the value being sent." },
+      promptPattern: { type: "string", description: "connect: regex that marks the shell prompt as ready (optional): send/read then settle the moment the prompt appears instead of waiting out the silence window." },
+      id: { type: "string", description: "send / read / secret_input / close: session id from connect (`ssh#N`)." },
+      data: { type: "string", description: "send: text to type into the session (a trailing newline is passed as-is; otherwise Enter is sent as `\\r`)." },
+      settle: { type: "boolean", description: "send: wait for the ready verdict before returning (default true); false returns right after the bytes are written." },
+      timeoutMs: { type: "number", description: "send / read: wait budget override (default 10000) — on expiry the call returns partial output with a readable line." },
+      maxChars: { type: "number", description: "read: return cap override (default 8000; the full output stays in the session log)." },
+      identityFile: { type: "string", description: "connect: private-key path to offer (`-i`, `~` expands); remembered for this host and reused when omitted (optional)." },
+    },
+    required: ["action"],
+  },
+  // 非工具级只读：动作级分类钩子接管（§6.22 NS3——`list` / `read` / `credentials` 免审）；也因此不进只读角色的子代工具表。
+  readonly: false,
+  isReadonlyAction(args) {
+    return args?.action === "list" || args?.action === "read" || args?.action === "credentials"
+  },
+  async execute(args, ctx) {
+    const invalid = validateArgs(args)
+    if (invalid) return invalid
+    // 动态 import（W8 契约②——与 bash / browser 异步面同式）。
+    const mod = await import("../agent-tools/ssh-session.mjs")
+    const parent = ctx?.agent ?? null
+    const action = args.action
+    let res
+    if (action === "connect") {
+      res = await mod.connectSsh(parent, ctx, {
+        host: args.host, user: args.user ?? null, port: args.port ?? null,
+        label: args.label ?? null, promptPattern: args.promptPattern ?? null,
+        identityFile: args.identityFile ?? null,
+      })
+    } else if (action === "send") {
+      res = await mod.sendSsh(parent, ctx, { id: args.id, data: args.data, settle: args.settle !== false, timeoutMs: args.timeoutMs })
+    } else if (action === "read") {
+      res = await mod.readSsh(parent, ctx, { id: args.id, timeoutMs: args.timeoutMs, maxChars: args.maxChars })
+    } else if (action === "secret_input") {
+      res = await mod.secretInputSsh(parent, ctx, { id: args.id, label: args.label ?? null })
+    } else if (action === "close") {
+      res = await mod.closeSsh(parent, ctx, { id: args.id })
+    } else if (action === "credentials") {
+      res = mod.credentialsSsh()
+    } else if (action === "forget") {
+      res = mod.forgetSsh({ host: args.host, port: args.port ?? null })
+    } else {
+      res = mod.listSsh(parent)
+    }
+    if (res?.error) return res.error.startsWith("Error:") ? res.error : `Error: ${res.error}`
+    return res?.text ?? "(no output)"
+  },
+}