aiterm-mcp 0.19.2 → 0.20.0

package/README.ja.md

@@ -20,17 +20,17 @@
 >
 > *MCP = Model Context Protocol — Claude Code のようなツールが AI に機能を差し込むためのオープン標準。*
 
+**工場での役割:** aiterm-mcpはdotagents開発工場が管理する自作コア10製品の一つです。
+永続PTYと外部agent実行レーンを所有し、dotagentsが製品横断の導入・統合契約を所有します。
+
 **言葉でなく実測で:** このリポジトリ自身の 203 テストで、`pty_read` はコンテキストに載るトークンを生ログの **約 7.1 分の 1** に減らす。しかも pass/fail の判定は畳んでも残る。→ [組み込みシェルツールとの使い分け](#組み込みシェルツールとの使い分け)
 
 13 ツール: 6 つの **PTY ツール**（`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`）で 1 本の永続端末を開き・操作し・読む。加えて 4 つの **エージェント起動ツール**（`claude_agent` / `codex_agent` / `grok_agent` / `composer_agent`）が別のコーディングエージェントの TUI を新しい端末の中に起動し、`claude_turn`がdurable caller向けの構造化issue／recoveryを、`claude_approval`がmanaged Claudeの相関済み承認UI中継を、`diagnostics`が安全なfactory readinessを返す。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
-**v0.18.1 を 2026-07-18 に公開**（0.18.0＋stale案内文言の修理1件）。実運用障害の還流による agent dispatch の hardening:
-全 dispatch／launch receipt に **submit 座礁観測** `submit_residue` を追加
-（送信 prompt が vendor TUI の composer に未 submit のまま残存していないかを有界に観測して報告する。
-陽性証拠のみ・auto-retry なし）。agent への prompt paste は tmux **bracketed paste**（pane ごとの
-negotiation）で包み、語中の文字化けと Enter 取り落としを抑制。初回 prompt 前の ready gate は
-busy 表示中（esc to interrupt）の Codex/Claude を ready と数えない。
-v0.16/0.17 以来、親エージェントは aiterm 上で一切ブロックしない:
+**v0.19.2 を 2026-07-20 に公開。** v0.19系では相関済みmanaged Claude approval中継を追加し、
+複数行shell配送を維持し、native Windowsのfactory diagnosticsを拡張しました。v0.18系では
+`submit_residue`、tmux bracketed paste、busyなCodex/Claude画面をreadyと数えないgateにより
+agent dispatchを強化しました。v0.16/0.17以来、親エージェントはaiterm上で一切ブロックしません:
 agent session への send は常に非ブロック dispatch になり、完了待ちは `aiterm-wait` 一本
 （exit code が receipt の outcome を映す: 0=done / 3=timeout=未完了 / 4=closed）、初回 prompt 付き
 launch は structured receipt にコピペ可能な `wait_command` を含む。factory diagnostics と local
@@ -290,7 +290,7 @@ consumer は `aiterm-runtime-errors snapshot` を読み、durable ingestion 後
 | `grok_agent` | Grok Build（xAI、既定`grok-4.5`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?` |
 | `composer_agent` | Grok Build（xAI、既定`grok-composer-2.5-fast`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?` |
 
-対応するCLI（`claude` / `codex` / `grok`）の導入・認証が必要。解決順は`CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`、既定path、`PATH`。前提違反はsession作成前に明示失敗する。4 launcherすべてが同じ非ブロックdispatch契約を使い、Claude/Codexの初回promptはready gate経由で送信される。Claudeはisolated managed settingsとhook-captured resultを使い、private transcriptへ依存しない。既存3 vendorのlive smokeはgreen、Claude実モデルsmokeは承認待ちでありfixture成功と混同しない。
+対応するCLI（`claude` / `codex` / `grok`）の導入・認証が必要。解決順は`CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`、既定path、`PATH`。前提違反はsession作成前に明示失敗する。4 launcherすべてが同じ非ブロックdispatch契約を使い、Claude/Codexの初回promptはready gate経由で送信される。Claudeはisolated managed settingsとhook-captured resultを使い、private transcriptへ依存しない。Claude／Codex／Grok／Composerのlive smokeはすべてgreenであり、fixtureによる検証とは区別して記録する。
 
 エージェントの回答が画面 tailより長ければ、対話callerは`pty_read({ agent_transcript:true })`で再promptなしに全文回収する。Claudeはmanaged Stop hookがowner-only resultへ保存した本文をdigest/byte数で検証して返し、private transcriptを読まない。durable machine callerは`claude_turn`を使う。`issue`は一度だけ送信し、`recover`は決して再送せず、`pending`を破損やidentity不一致と区別する。検証済みの`completed`だけがexact `raw_output`を持ち、`unknown`は未dispatchと帰属不能を区別する。不一致・破損は成功statusへ丸めずtool errorのままにする。IDなしの対話turnも匿名markerで直列化するため、現在Stop待ちの間に古い回答を返さない。CodexはStop hookの`turn_id`で構造化transcriptへjoinし、Grok/Composerは最後の実user行より後ろのassistant行を採る。不在・非agent・抽出不能は明示エラー。
 

package/README.md

@@ -20,24 +20,24 @@
 >
 > *MCP = Model Context Protocol — the open standard that lets tools like Claude Code plug capabilities into an AI.*
 
+**Factory role:** aiterm-mcp is one of the ten self-owned core products managed by
+the dotagents development factory. It owns the persistent PTY and external-agent
+execution lane; dotagents owns the cross-product installation and integration
+contract.
+
 **Measured, not claimed:** on this repo's own 203-test suite, a `pty_read` puts **~7.1× fewer tokens** in your context than the raw log — and the pass/fail verdict survives the fold. → [When to reach for it vs. the built-in shell](#when-to-reach-for-it-vs-the-built-in-shell)
 
 Thirteen tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal, four **agent launchers** — `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` — that each start another coding agent's TUI inside a fresh one, `claude_turn` for durable structured issue/recovery, `claude_approval` for correlated managed-Claude approval prompts, and `diagnostics` for safe factory readiness. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
 
-**v0.18.1 was published on 2026-07-18** (v0.18.0 plus one stale-guidance
-message fix). Field-failure hardening for agent
-dispatch: every dispatch/launch receipt now carries a **submit-strand
-observation** `submit_residue` (a bounded screen poll that reports when the
-sent prompt is still sitting unsubmitted in the vendor TUI's composer —
-positive evidence only, no auto-retry), agent prompt pastes are wrapped in
-tmux **bracketed paste** (negotiated per pane) against mid-word corruption and
-dropped submits, and the pre-prompt ready gate no longer counts a busy
-Codex/Claude screen ("esc to interrupt") as ready. As of v0.16/0.17 a parent
-agent never blocks on aiterm: every send to an agent session is a non-blocking
-dispatch, completion is one universal `aiterm-wait` waiter whose exit codes
-mirror the receipt outcome (`0`=done / `3`=timeout, not finished /
-`4`=closed), and a launch with an initial prompt returns a ready-made
-`wait_command` in its structured receipt.
+**v0.19.2 was published on 2026-07-20.** The v0.19 line adds the correlated
+managed-Claude approval relay, preserves multiline shell delivery, and extends
+factory diagnostics on native Windows. The v0.18 line hardened agent dispatch
+with `submit_residue`, tmux bracketed paste, and a ready gate that rejects busy
+Codex/Claude screens. As of v0.16/0.17 a parent agent never blocks on aiterm:
+every send to an agent session is a non-blocking dispatch, completion is one
+universal `aiterm-wait` waiter whose exit codes mirror the receipt outcome
+(`0`=done / `3`=timeout, not finished / `4`=closed), and a launch with an
+initial prompt returns a ready-made `wait_command` in its structured receipt.
 Factory diagnostics and the local runtime-error store collect only when
 canonical dotagents config explicitly sets `collection.enabled: true`;
 collection is off by default and performs no network I/O. It ships via
@@ -84,7 +84,7 @@ codex_agent({ session_name: "codex1", cwd: "/repo",
 pty_read("codex1", { screen: true })   → read what it's doing (token-reduced)
 pty_send("codex1", "also fix the imports it broke")
                                     → non-blocking dispatch; receipt carries event_cursor
-$ aiterm-wait --session codex1 --cursor <event_cursor>   # host background task; exit code 0=done, 3=timeout (not done), 4=closed
+$ aiterm-wait --session codex1 --cursor <event_cursor>   # never in the parent's foreground; exit 0=done, 3=timeout (not done), 4=closed
 pty_read("codex1", { agent_transcript: true })           → collect the full answer
 ```
 
@@ -309,7 +309,7 @@ Each launcher starts a specific vendor's interactive coding-agent TUI inside a f
 | `grok_agent` | Grok Build, model `grok-4.5` by default (`model?` overrides) (xAI) | `prompt?`, `model?`, `reasoning_effort?` unsupported (an explicit value is an error; Grok CLI `--effort` is headless-only), `cwd?`, `session_name?` |
 | `composer_agent` | Grok Build, model `grok-composer-2.5-fast` by default (`model?` overrides) (xAI) | `prompt?`, `model?`, `reasoning_effort?` unsupported (an explicit value is an error), `cwd?`, `session_name?` |
 
-The vendor CLI must be installed and authenticated (`claude` for `claude_agent`; `codex` for `codex_agent`; `grok` for both Grok tools). Binary resolution uses `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`, then each documented default location, then `PATH`. Missing binaries, invalid model/effort values, and nonexistent `cwd` fail before a session is created. All four share the same non-blocking dispatch contract for follow-up turns; `claude_agent`/`codex_agent` submit an initial `prompt` through the ready gate. Claude uses isolated managed settings and a hook-captured bounded result rather than private transcript access. Codex/Grok/Composer live smokes are green; Claude real-model smoke remains approval-gated and is not claimed from fixtures. Native Windows can launch agents but managed completion is not supported yet.
+The vendor CLI must be installed and authenticated (`claude` for `claude_agent`; `codex` for `codex_agent`; `grok` for both Grok tools). Binary resolution uses `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`, then each documented default location, then `PATH`. Missing binaries, invalid model/effort values, and nonexistent `cwd` fail before a session is created. All four share the same non-blocking dispatch contract for follow-up turns; `claude_agent`/`codex_agent` submit an initial `prompt` through the ready gate. Claude uses isolated managed settings and a hook-captured bounded result rather than private transcript access. Claude, Codex, Grok, and Composer live smokes are green; fixture coverage remains a separate claim. Native Windows can launch agents but managed completion is not supported yet.
 
 When an agent's answer is longer than the on-screen tail (pane height ≈ 24 lines), callers recover it in full with `pty_read({ agent_transcript: true })`. It returns the most recently completed turn's final assistant message in plain text with no re-prompting. Claude reads the bounded owner-only result captured by the managed Stop hook and verifies its digest/byte count; it never reads Claude's private transcript. Durable machine callers should use `claude_turn`: `issue` sends once, `recover` never sends, `pending` is distinct from unsafe or malformed state, and only `completed` carries the exact verified `raw_output`. `unknown` distinguishes `operation_not_found` from a receipt whose result can no longer be attributed. Mismatch and corruption remain tool errors rather than being folded into a successful status. ID-less interactive Claude turns are still serialized by an anonymous marker, so an older answer is not returned while the current Stop is pending. Codex joins its structured transcript on the Stop hook `turn_id`; Grok/Composer take the assistant rows after the last real user row. A missing result/transcript, a non-agent session, or an unextractable message is an explicit error, never a silent empty.
 
@@ -323,9 +323,11 @@ As of v0.16 a parent agent **never blocks** on aiterm — there is no wait param
 
 1. Launch the child (`claude_agent` / `codex_agent` / ...; every launch is managed). Send a turn with plain `pty_send` (or `claude_turn issue` for durable Claude operations). The call passes the TUI ready gate, submits, and returns immediately with an `event_cursor` in its structured receipt — plus a `submit_residue` observation: `true` means the sent text still lingered in the composer after submit (likely stranded; inspect the screen before re-pressing Enter), `false` means no residue was observed (not a proof of submission), `null` means not applicable.
 2. Run `aiterm-wait --session <id> --cursor <event_cursor> [--operation sha256:<64hex>] [--timeout <sec>]` (a launch with an initial `prompt` returns this command ready-made as `wait_command` in its structured receipt). It observes the vendor Stop-hook completion event as a **pure reader** and exits with a one-line `aiterm.agent-wait-result.v1` receipt. **Exit ≠ done**: the receipt's `outcome` is authoritative, and the exit code mirrors it — `0` = `done`, `3` = `timeout` (the turn is **not** finished; default `--timeout` is 600 s), `4` = `closed`, `1` = error. On `timeout` just re-run the waiter with the same cursor. The `--cursor` boundary makes it start-order independent: no completion can slip past even if the waiter starts late.
-3. Host integration picks the invocation style: a harness that re-invokes its agent when a background task exits (Claude Code) runs the waiter **in the background** and gets woken with zero polling; a host without that mechanism runs it as a foreground shell command. Either way the aiterm MCP call itself never blocks.
+3. **The parent never runs the waiter in its own foreground.** Waiting is correct — but the waiter is a separate process, not the parent's turn. A harness that re-invokes its agent when a background task exits (Claude Code) runs the waiter **in the background** and gets woken with zero polling. So that this is not left to interpretation, aiterm reads `clientInfo.name` from the MCP `initialize` handshake and its receipts name the concrete invocation for the detected host — for Claude Code, literally `Bash(command: "aiterm-wait …", run_in_background: true)`. Unknown or undeclared hosts get the generic "start it as a process that does not block the parent's turn" wording; nothing else about the contract changes. Every receipt leads with the same rule: dispatch and let go, then go do something else or end the turn.
 4. Collect the result exactly as before: `pty_read(agent_transcript: true)`, or `claude_turn recover` for durable Claude operations. The waiter carries the signal, never the payload.
 
+**If your host has no completion push** (no mechanism that re-invokes the agent when a background process exits), `--timeout 0` is a one-shot check instead of a wait: it scans the event file once and returns `running` (exit `5`) when the turn is still in flight, `done` (exit `0`) when it finished, `closed` (exit `4`) when the session is gone. It is deliberately absent from the receipts and tool descriptions — a host that *does* get pushed should be woken, not poll. An unknown session name is an error, never `running`, so a typo cannot masquerade as a child that is still working.
+
 `aiterm-wait` takes no locks, never writes session state, and never dispatches — any number can run beside the MCP server and each other, and `pty_close`/concurrent sends are unaffected.
 
 ### Token reduction

package/dist/aiterm-wait-cli.js

@@ -2,14 +2,16 @@
 // aiterm-wait — agent turn 完了eventの純リーダー観測CLI。
 // 完了/timeout/close を1行のJSON receiptで返してexitする。lock・PTY・dispatch状態には一切触れない。
 // 親AIホストのバックグラウンドタスクとして起動し、exitを「観測終了の通知」として使う。
-// exit≠完了: exit code は outcome を映す（0=done / 3=timeout=未完了 / 4=closed / 1=エラー）。
+// exit≠完了: exit code は outcome を映す（0=done / 5=running=未完了 / 3=timeout=未完了 / 4=closed / 1=エラー）。
+// --timeout 0 は待たずに一度だけ観測する照会で、未完了は running（timeout と混同させない）。
 // receipt の outcome が正で、done 以外は未完了。timeout の既定は core の DEFAULT_AGENT_DONE_TIMEOUT（600秒）。
 import { fileURLToPath } from "node:url";
 import * as fs from "node:fs";
 import { AitermError, observeAgentDone } from "./core.js";
 const SESSION_RE = /^[A-Za-z0-9_-]{1,64}$/;
 const OPERATION_RE = /^sha256:[0-9a-f]{64}$/;
-const USAGE = "usage: aiterm-wait --session <name> [--cursor <event_cursor>] [--operation sha256:<64hex>] [--timeout <sec>]";
+const USAGE = "usage: aiterm-wait --session <name> [--cursor <event_cursor>] [--operation sha256:<64hex>] [--timeout <sec>]" +
+    "（--timeout 0 は待たずに一度だけ観測する照会で、未完了は outcome=running / exit 5）";
 export function parseArgs(argv) {
     let session = null;
     let operationId = null;
@@ -65,7 +67,14 @@ function emit(value) {
     process.stdout.write(JSON.stringify(value) + "\n");
 }
 // outcome → exit code。exit status しか見えないホストでも done とそれ以外を誤読できないようにする。
-const OUTCOME_EXIT_CODES = { done: 0, timeout: 3, closed: 4 };
+// Record で全 outcome を型に強制する: 語を足して対応表を直し忘れると undefined→exit 0 になり、
+// 「まだ終わっていない」が「完了」として親へ届く。その取りこぼしを compile error で止める。
+const OUTCOME_EXIT_CODES = {
+    done: 0,
+    running: 5,
+    timeout: 3,
+    closed: 4,
+};
 export async function main(argv) {
     const cmd = parseArgs(argv);
     const result = await observeAgentDone(cmd.session, {

package/dist/core.js

@@ -2497,7 +2497,7 @@ function bindCompletedInitialPrompt(meta) {
     }
     const size = safeStatSize(meta.event_file);
     if (size === 0) {
-        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了待ちです。aiterm-wait --session ${meta.aiterm_session} --cursor 0 で完了（outcome=done）を確認してから再度操作してください。`, 2);
+        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了待ちです。${agentWaitGuide(meta.aiterm_session)}`, 2);
     }
     const text = readFileRange(meta.event_file, 0, size).toString("utf8");
     const lines = text.split("\n");
@@ -2509,7 +2509,7 @@ function bindCompletedInitialPrompt(meta) {
     if (!scanned.event) {
         const malformed = scanned.malformedEvents ? ` malformed_events=${scanned.malformedEvents}` : "";
         const partial = tail.trim() ? " partial_event=true" : "";
-        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了 event をまだ確認できません。aiterm-wait --session ${meta.aiterm_session} --cursor 0 で完了（outcome=done）を確認してから再度操作してください。${malformed}${partial}`, 2);
+        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了 event をまだ確認できません。${agentWaitGuide(meta.aiterm_session)}${malformed}${partial}`, 2);
     }
     bindAgentVendorSession(meta, scanned.event);
     setInitialPromptState(meta, "done");
@@ -2630,11 +2630,8 @@ function findLatestCodexTranscript(codexHome, vendorSessionId) {
     visit(sessionsDir);
     return latestFile;
 }
-// 未完了系エラーの共通出口案内。pollingへ誘導せず、正規の完了待ち手段を必ず指す。
-const AGENT_WAIT_GUIDE = "完了待ちは aiterm-wait --session <session_id> のバックグラウンド実行で受ける（polling不要。" +
-    "receiptのoutcome=doneを確認してから再取得）。";
 function transcriptUnavailable() {
-    throw new AitermError(`transcript がまだありません。ターン完了後に再取得してください。${AGENT_WAIT_GUIDE}`, 2);
+    throw new AitermError(`transcript がまだありません。ターン完了後に再取得してください。${agentWaitGuide()}`, 2);
 }
 function transcriptNotFound(vendor) {
     throw new AitermError(`最終 assistant メッセージを特定できませんでした（vendor=${vendor}）。screen で確認してください。`, 2);
@@ -2701,18 +2698,18 @@ export async function readAgentTranscript(name, o = {}) {
         const active = readClaudeOperationMarker(meta);
         if (active) {
             const label = active.operationId ? `operation ${active.operationId}` : "operation_idなしのClaude turn";
-            throw new AitermError(`${label} はまだ完了していません。Stop完了後に同じsessionから再取得してください。${AGENT_WAIT_GUIDE}`, 2);
+            throw new AitermError(`${label} はまだ完了していません。Stop完了後に同じsessionから再取得してください。${agentWaitGuide(name)}`, 2);
         }
     }
     // wait timeout は「失敗」ではなく状態不明。後着した同一launchの完了eventから
     // vendor session をbindし、promptを再送せず結果だけ回収できるようにする。
     recoverAgentVendorSession(meta);
     if (!meta.vendor_session_id) {
-        throw new AitermError(`agent session '${name}' はまだターンが完了していません。agent_done 完了後に再取得してください。${AGENT_WAIT_GUIDE}`, 2);
+        throw new AitermError(`agent session '${name}' はまだターンが完了していません。agent_done 完了後に再取得してください。${agentWaitGuide(name)}`, 2);
     }
     const done = latestAgentDoneEvent(meta, operationId);
     if (operationId && !done) {
-        throw new AitermError(`operation ${operationId} はまだ完了していません。同じoperation_idで後から再取得してください。${AGENT_WAIT_GUIDE}`, 2);
+        throw new AitermError(`operation ${operationId} はまだ完了していません。同じoperation_idで後から再取得してください。${agentWaitGuide(name)}`, 2);
     }
     const turnId = done?.turn_id ?? null;
     let text = "";
@@ -2853,10 +2850,37 @@ function assertInitialPromptNotPendingForSend(name, force) {
     if (meta.initial_prompt !== "pending" && meta.initial_prompt !== "sent")
         return;
     throw new AitermError(`agent session '${name}' は起動時 prompt の完了待ちです。通常 pty_send は混入防止のため送信しません。` +
-        `aiterm-wait --session ${name} --cursor 0 で完了（outcome=done）を確認してから再度 pty_send するか、手動介入が必要な場合だけ force:true を明示してください。`, 2);
+        `${agentWaitGuide(name)}完了後に再度 pty_send するか、手動介入が必要な場合だけ force:true を明示してください。`, 2);
 }
 // aiterm-wait の exit 契約（CLI と各所の案内文で共有する正）。exit≠完了: outcome が done の時だけ完了。
 export const AITERM_WAIT_OUTCOME_NOTE = `exit 0=done / 3=timeout（既定${DEFAULT_AGENT_DONE_TIMEOUT}秒・未完了） / 4=closed。receiptのoutcomeが正で、done以外は未完了`;
+// 親ホストの識別（MCP initialize の clientInfo.name）。完了待ちコマンドを「親のターンを塞がない
+// 起動形」で名指しするためだけに使う。分からない時は汎用文へ落ち、機能は一切変えない。
+let parentClientName = null;
+export function setParentClient(name) {
+    const trimmed = typeof name === "string" ? name.trim() : "";
+    parentClientName = trimmed === "" ? null : trimmed;
+}
+// 完了待ちを親のターンを塞がない形で起動する具体形。ホストが分かる時は実際の呼び出し形を名指しする
+// （抽象名詞の「バックグラウンドで」だけでは親が foreground 実行へ落ちるため・ADR 0017）。
+export function agentWaitLaunchForm(command) {
+    if (parentClientName === "claude-code") {
+        return `Bash(command: ${JSON.stringify(command)}, run_in_background: true)`;
+    }
+    return `\`${command}\` を親のターンを塞がない別プロセスとして起動`;
+}
+// dispatch / 起動時 prompt 送信後の共通案内。第一文で「待たない」を宣言し、待ち方は後段に置く。
+export function agentDispatchGuide(session, cursor) {
+    const cmd = `aiterm-wait --session ${session} --cursor ${cursor}`;
+    return (`投げっぱなしでよい＝ここで待たない。親は自分の作業へ戻るか、このターンを終える。\n` +
+        `完了通知: ${agentWaitLaunchForm(cmd)}。exit が完了通知（${AITERM_WAIT_OUTCOME_NOTE}）。\n` +
+        `foreground 実行は親を最大 ${DEFAULT_AGENT_DONE_TIMEOUT} 秒塞ぐので使わない。回収: pty_read(agent_transcript:true)`);
+}
+// 未完了 session へ触った時の共通案内。ここでも待つのは waiter プロセスであって親ではない。
+export function agentWaitGuide(session) {
+    const cmd = `aiterm-wait --session ${session ?? "<session_id>"} --cursor 0`;
+    return `完了通知は ${agentWaitLaunchForm(cmd)} で受ける（親はここで待たない・polling 不要）。receipt の outcome=done を確認してから再取得する。`;
+}
 // 外部waiterプロセス用の純リーダー観測。lock・PTY・metadata書込・dispatch状態には一切触れない。
 // event fileのtail規律（未終端行保持・増分上限）はwaitAgentDoneEventと同一だが、
 // vendor_session_idのbind永続化を行わない点だけ意図的に異なる（waiterは観測者であって所有者でない）。
@@ -2914,8 +2938,10 @@ export async function observeAgentDone(name, o = {}) {
             if (scanned.event)
                 return observation("done", scanned.event);
         }
+        // timeout=0 は「待たずに一度だけ見る」照会＝未完了は失敗ではなく running。
+        // 1秒以上を指定した待機の未完了は従来どおり timeout で、待ち方の意味は変えない。
         if (performance.now() >= deadline)
-            return observation("timeout");
+            return observation(timeout === 0 ? "running" : "timeout");
         await sleep(AGENT_DONE_POLL_MS);
     }
 }
@@ -3147,8 +3173,7 @@ export async function sendInitialAgentPrompt(name, text, o = {}) {
     const residue = await detectAgentSubmitResidue(name, meta.kind, text);
     return {
         text: `initial_prompt=pending vendor=${meta.kind} event_cursor=${startOffset}\n` +
-            `起動時 prompt を送信した。完了通知は aiterm-wait --session ${name} --cursor ${startOffset} をホストのバックグラウンドタスクとして実行し、` +
-            `exit 時に receipt の outcome で判定する（${AITERM_WAIT_OUTCOME_NOTE}）。回収は pty_read(agent_transcript:true) を使う。` +
+            `起動時 prompt を送信した。${agentDispatchGuide(name, startOffset)}` +
             agentSubmitResidueWarning(name, residue.residue),
         event_cursor: startOffset,
         submit_residue: residue.residue,
@@ -3622,7 +3647,7 @@ export function openAgent(kind, opts = {}) {
     }
     const driveHint = agentDone && kind === "claude"
         ? `TUI の描画には数秒かかる。少し置いてから pty_read(${sid}, screen:true) で画面を読み、` +
-            `turnはpty_send(${sid}, "...")で送る（自動で非ブロックdispatch・完了通知はaiterm-wait）。中断はpty_key(${sid}, "C-c")、` +
+            `turnはpty_send(${sid}, "...")で送る（自動で非ブロックdispatch＝投げっぱなしでよい・完了通知はaiterm-wait）。中断はpty_key(${sid}, "C-c")、` +
             `Stopが来ない場合の解除はpty_close(${sid})を使う。`
         : `TUI の描画には数秒かかる。少し置いてから pty_read(${sid}, screen:true) で画面を読み、` +
             `pty_send(${sid}, "...") で入力・pty_key(${sid}, "Enter"/"Up"/"C-c" 等) で操作する（対話）。`;

package/dist/index.js

@@ -20,6 +20,15 @@ import { createRequire } from "node:module";
 // 除去済み＝どちらの静的構文も 18〜22 全域を満たせないため（実行時 require が唯一全域で動く）。
 const pkg = createRequire(import.meta.url)("../package.json");
 const server = new McpServer({ name: "aiterm", version: pkg.version });
+/**
+ * dispatch 系の説明で共有する非ブロック規範。tool description は registerTool 時＝initialize 前に
+ * 固定されるため親ホストを名指しできない（ホスト別の具体形は receipt 側が core.agentWaitLaunchForm で出す）。
+ * ここでは「待つな」を断定形で先に置き、foreground 実行の禁止までを説明の側に含める。
+ */
+const NON_BLOCKING_RULE = "dispatch した子は投げっぱなしでよい＝親はここで待たない。" +
+    "完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` を親のターンを塞がない別プロセスとして起動して受け、" +
+    `exit を完了通知として扱う（${core.AITERM_WAIT_OUTCOME_NOTE}。ポーリング不要）。` +
+    "この待ちコマンドを foreground で実行して親のターンを塞ぐことはしない（receipt が実際の起動形を示す）。";
 function ok(s) {
     return { content: [{ type: "text", text: s }] };
 }
@@ -88,9 +97,8 @@ server.registerTool("pty_open", {
 server.registerTool("pty_send", {
     description: "セッションへテキストを送る。通常PTYへは送信のみ（出力は pty_read で取得）。" +
         "agent session（launcher起動）への send は自動で dispatch になる: TUI の ready gate と submit 分離を通して即返り、" +
-        "receipt の event_cursor を返す＝親はブロックしない。完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` を" +
-        "ホストのバックグラウンドタスクとして実行し、exit時にreceiptのoutcomeで判定する" +
-        `（${core.AITERM_WAIT_OUTCOME_NOTE}。ポーリング不要）。` +
+        "receipt の event_cursor を返す。" +
+        NON_BLOCKING_RULE +
         "結果回収は pty_read(agent_transcript:true)、Claude の durable turn は claude_turn を使う。" +
         "force:true は非Claude agent sessionへの手動介入用の素送信。managed Claudeの承認UIはclaude_approvalを使う。",
     inputSchema: {
@@ -137,9 +145,8 @@ server.registerTool("pty_send", {
                 content: [
                     {
                         type: "text",
-                        text: `dispatchした（vendor=${receipt.vendor}）。完了通知: aiterm-wait --session ${receipt.session_id} --cursor ${receipt.event_cursor} を` +
-                            `ホストのバックグラウンドタスクとして実行し、exit時にreceiptのoutcomeで判定（${core.AITERM_WAIT_OUTCOME_NOTE}）。` +
-                            "回収: pty_read(agent_transcript:true)" +
+                        text: `dispatchした（vendor=${receipt.vendor}）。\n` +
+                            core.agentDispatchGuide(receipt.session_id, receipt.event_cursor) +
                             core.agentSubmitResidueWarning(receipt.session_id, receipt.submit_residue),
                     },
                 ],
@@ -404,12 +411,12 @@ const agentEffortDesc = (kind) => kind === "claude"
             "composer は effort 自体非対応）。指定すると起動前にエラーを返す"
         : "reasoning effort（思考レベル）。low/medium/high/xhigh/max/ultra（CLI 版依存）。" +
             "ultra は max 推論＋proactive 自動委譲 ON＝使用量急増注意（明示要求時のみ）。省略時は端末 config／CLI 既定。";
-// 全launcher共通の完了受信ガイド。launch応答のwait_command（起動時promptあり時）／pty_send dispatchの
-// event_cursorから組んだaiterm-waitをホストのバックグラウンドタスクとして1本実行し、exit時にreceiptの
-// outcomeで判定する。
-const agentCompletionDesc = `完了通知は起動応答の wait_command（初回prompt時）または pty_send dispatch 後の ` +
-    `aiterm-wait --session <id> --cursor <event_cursor> をホストのバックグラウンドタスクとして実行し、` +
-    `exit時にreceiptのoutcomeで判定する（${core.AITERM_WAIT_OUTCOME_NOTE}。ポーリング不要）。` +
+// 全launcher共通の完了受信ガイド。待ちコマンドは起動応答の wait_command（初回prompt時）または
+// pty_send dispatch の event_cursor から組む。文型は NON_BLOCKING_RULE と同じく「待たない」が先。
+const agentCompletionDesc = `起動して投げたら投げっぱなしでよい＝親はここで待たない。` +
+    `完了通知は起動応答の wait_command（初回prompt時）または pty_send dispatch 後の ` +
+    `aiterm-wait --session <id> --cursor <event_cursor> を親のターンを塞がない別プロセスとして起動して受ける` +
+    `（${core.AITERM_WAIT_OUTCOME_NOTE}。ポーリング不要・foreground実行はしない）。` +
     `結果回収は pty_read(agent_transcript:true)。`;
 function registerAgentTool(toolName, kind, desc) {
     const correlatedLaunchSchema = {};
@@ -492,6 +499,12 @@ registerAgentTool("composer_agent", "composer", "【Grok Build の Composer モ
     agentCompletionDesc +
     "model を引数で指定可。reasoning_effort は非対応（指定はエラー）。");
 async function main() {
+    // 親ホストを initialize の clientInfo.name から確定させ、receipt の完了待ちコマンドを
+    // そのホストの実際の起動形で名指しする（実測: claude-code は initialize → notifications/initialized
+    // → tools/list の順で送るため、どの tool 呼び出しより先に確定する）。取れない時は汎用文へ落ちるだけ。
+    server.server.oninitialized = () => {
+        core.setParentClient(server.server.getClientVersion()?.name ?? null);
+    };
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "mcpName": "io.github.kitepon-rgb/aiterm-mcp",
   "description": "AI-driven persistent terminal as a local stdio MCP server (tmux-backed). Holds one local PTY; SSH and containers are just commands you send into it. Also launches interactive Claude/Codex/Grok/Composer agent TUIs in a persistent terminal. Token-reducing reads.",
   "keywords": [