aiterm-mcp 0.15.1 → 0.17.0

package/README.ja.md

@@ -24,10 +24,13 @@
 
 12 ツール: 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を、`diagnostics`が安全なfactory readinessを返す。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
-**v0.12.2 は release candidate（公開待ち）です。** factory diagnostics と local
+**v0.17.0 を 2026-07-18 に公開。** 親エージェントは 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
 runtime-error store は canonical dotagents config の `collection.enabled: true` が明示された
-場合だけ収集し、既定OFF、network送信は行いません。npm公開、tag、CI、registry登録、registry由来install
-の確認は未実施です。
+場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
+Publishing）で公開し、GitHub Release が Official MCP Registry を再登録します。
 
 **状態:** 開発継続中 · この分野では新参で、別の形に賭けている（[既存手段との比較](#既存手段との比較)参照）· 動作対象は Linux · WSL2 · macOS · Windows ネイティブ（core PTY ツール。`agent_done` は現時点では POSIX/WSL/macOS のみ）· MIT · [変更履歴](CHANGELOG.md)。
 
@@ -52,14 +55,15 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 ### 2. その端末の中に他のコーディングエージェントを起動する — オーケストレーションの旗艦
 
-同じ primitive が別エージェントの TUI を宿す。4 つの起動ツールが、Claude/Codex/Grok/Composer の対話 TUI を新しい永続端末の中に起動し、`session_id` を返す。既存の人間向けtextに加えて`aiterm.agent-launch-result.v1` structured receiptも返すため、durable callerは表示文字列を解析せずsession handleを取得できる。以後は同じ `pty_read` / `pty_send` で継続操作する。`agent_done:true` なら Stop hook でターン完了を待てる。managed Claudeでは全turnに`wait:"agent_done"`を必須とする。durable machine callerは`claude_turn({ action:"issue"|"recover", session_id, operation_id, ... })`を使い、人間向けerror文字列を解析せず`accepted`／`pending`／`completed`／`unknown`を判定できる。recoveryは再送せず、検証済み完了だけがexact `raw_output`を持つ。通常の`pty_send`／`pty_read`は対話callerと人間向けに維持する。`C-c`後もmarkerを保持し、Stopが来なければsessionをcloseする。`claude_agent` と `codex_agent` は、TUI ready 後に初回 `prompt` を送り `wait:"agent_done"` で待つ入口も公開する。Codex/Grok/Composer の live smoke は成功済み。Claude実モデルの初回／follow-up smokeは明示承認待ちであり、まだ成功扱いしない。
+同じ primitive が別エージェントの TUI を宿す。4 つの起動ツールが、Claude/Codex/Grok/Composer の対話 TUI を新しい永続端末の中に起動し、`session_id` を返す。既存の人間向けtextに加えて`aiterm.agent-launch-result.v1` structured receiptも返すため、durable callerは表示文字列を解析せずsession handleを取得できる。以後は同じ `pty_read` / `pty_send` で継続操作する。**起動は常に managed**（aiterm 所有の Stop hook 付き）で、agent session への `pty_send` は非ブロックの **dispatch** になり `event_cursor` 入り receipt を即返す。完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` をホストのバックグラウンドタスクとして実行し、exit 時に receipt の `outcome` で判定する（exit 0=done / 3=timeout=未完了・既定600秒 / 4=closed。親はブロックもポーリングもしない）。起動時 `prompt` を渡した launch は structured receipt にコピペ可能な `wait_command` と `event_cursor` を含む。durable machine callerは`claude_turn({ action:"issue"|"recover", session_id, operation_id, ... })`を使い、人間向けerror文字列を解析せず`accepted`／`pending`／`completed`／`unknown`を判定できる。recoveryは再送せず、検証済み完了だけがexact `raw_output`を持つ。通常の`pty_send`／`pty_read`は対話callerと人間向けに維持する。`C-c`後もmarkerを保持し、Stopが来なければsessionをcloseする。`claude_agent` と `codex_agent` の初回 `prompt` は ready gate 経由で送信して待たずに返る（Grok/Composer は argv 渡し）。手動でキー操作したい場合は `pty_open` で素の端末を開き vendor CLI を自分で起動する。
 
 ```text
-codex_agent({ session_name: "codex1", cwd: "/repo", agent_done: true,
-              wait: "agent_done", prompt: "port test/legacy.py to vitest" })
+codex_agent({ session_name: "codex1", cwd: "/repo",
+              prompt: "port test/legacy.py to vitest" })
                                     → { session_id: "codex1", … }   # Codex が永続端末で稼働開始
 pty_read("codex1", { screen: true })   → 何をしているか読む（トークン削減）
-pty_send("codex1", "also fix the imports it broke", { wait: "agent_done" })
+pty_send("codex1", "also fix the imports it broke")   # 非ブロックdispatch＝event_cursor入りreceipt
+$ aiterm-wait --session codex1 --cursor <event_cursor>   # exit 0=done / 3=timeout(未完了) / 4=closed。回収は pty_read(agent_transcript:true)
                                     → 操舵し、Codex の次の入力境界で返る
 ```
 
@@ -67,12 +71,12 @@ pty_send("codex1", "also fix the imports it broke", { wait: "agent_done" })
 
 | ツール | 起動するもの | 主な引数 |
 | --- | --- | --- |
-| `claude_agent` | Claude Code CLI（Anthropic） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`）, `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
-| `codex_agent` | Codex CLI（OpenAI・端末設定／CLI既定、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`/`ultra`）, `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
-| `grok_agent` | Grok Build（xAI、既定`grok-4.5`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?`, `agent_done?` |
-| `composer_agent` | Grok Build（xAI、既定`grok-composer-2.5-fast`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?`, `agent_done?` |
+| `claude_agent` | Claude Code CLI（Anthropic） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`）, `cwd?`, `session_name?` |
+| `codex_agent` | Codex CLI（OpenAI・端末設定／CLI既定、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`/`ultra`）, `cwd?`, `session_name?` |
+| `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_agent` は `claude`、`codex_agent` は `codex`、Grok 系は `grok`）。バイナリは `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`、各既定path、`PATH` の順で解決する。CLI不在・不正なmodel/effort・実在しない`cwd`はsession作成前に失敗し、残骸を残さない。Claudeの`agent_done:true`は通常settingsを継承しないlaunch専用settingsとStop hookを使い、本文なしeventとowner-only bounded resultを分離する。`pty_read({ agent_transcript:true })`はdigestとbyte数を検証したresultだけを返し、Claude private transcriptを読まない。timeoutは成功扱いせず同じsessionを残し、後着resultをprompt再送なしで回収できる。managed Claudeでは通常`pty_send(wait:"none")`とC-c以外の`pty_key`を拒否する。自由なkey操作が必要なら`agent_done:false`で起動し、managed routeでは中断に`C-c`、解除に`pty_close`を使う。
+各ベンダーの CLI が導入・認証済みであること（`claude_agent` は `claude`、`codex_agent` は `codex`、Grok 系は `grok`）。バイナリは `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`、各既定path、`PATH` の順で解決する。CLI不在・不正なmodel/effort・実在しない`cwd`はsession作成前に失敗し、残骸を残さない。Claudeは通常settingsを継承しないlaunch専用settingsとStop hookを使い、本文なしeventとowner-only bounded resultを分離する。`pty_read({ agent_transcript:true })`はdigestとbyte数を検証したresultだけを返し、Claude private transcriptを読まない。後着resultは同じsessionからprompt再送なしで回収できる。managed ClaudeではC-c以外の`pty_key`を拒否する（手動介入は`pty_send`の`force:true`）。中断は`C-c`、解除は`pty_close`。
 
 エージェント間の隠れたプロトコルは無い。起動したClaude/Codex/Grok/Composerは利用者がattachできるもう1本の永続sessionであり、MCPクライアントが通常のPTY操作で駆動する。
 
@@ -257,7 +261,7 @@ aiterm は同じ核心の洞察——端末を出会いの場にする——を
 | `pty_key` | 制御キーを送る | `session_id`, `key`（`C-c`/`Enter`/`Up`…） |
 | `pty_close` | 冪等に閉じ、`closed` / `already_closed`を返す | `session_id` |
 | `pty_list` | セッション一覧 | （なし） |
-| `claude_turn` | 相関済みmanaged Claude operationを送信または回収 | `action`, `session_id`, `operation_id`, `text?`, `timeout?` |
+| `claude_turn` | 相関済みmanaged Claude operationをdispatch（issue）または回収（recover） | `action`, `session_id`, `operation_id`, `text?` |
 | `diagnostics` | 機械可読 JSON による read-only factory readiness | （なし） |
 
 `diagnostics` は PTY やエージェントを起動しない。パッケージ版、MCP 呼出 readiness、read-only な PTY 一覧要約、bounded runtime-error-store status、任意 vendor launcher の可用性だけを返す。path・環境値・認証情報・コマンド本文・PTY 出力・raw log は意図的に返さない。通常未設定の任意依存は `not_applicable`、安全に確定できない状態は `unverified` と表す。
@@ -274,18 +278,18 @@ consumer は `aiterm-runtime-errors snapshot` を読み、durable ingestion 後
 
 | ツール | 起動するもの | 主な引数 |
 | --- | --- | --- |
-| `claude_agent` | Claude Code CLI（Anthropic） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`）, `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
-| `codex_agent` | Codex CLI（OpenAI・端末設定／CLI既定、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`/`ultra`）, `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
-| `grok_agent` | Grok Build（xAI、既定`grok-4.5`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?`, `agent_done?` |
-| `composer_agent` | Grok Build（xAI、既定`grok-composer-2.5-fast`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?`, `agent_done?` |
+| `claude_agent` | Claude Code CLI（Anthropic） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`）, `cwd?`, `session_name?` |
+| `codex_agent` | Codex CLI（OpenAI・端末設定／CLI既定、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`/`ultra`）, `cwd?`, `session_name?` |
+| `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作成前に明示失敗する。Claude/Codexは初回prompt完了待ちを公開し、4 launcherすべてが対応環境で同じfollow-up `pty_send(wait:"agent_done")`契約を使う。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へ依存しない。既存3 vendorのlive smokeはgreen、Claude実モデルsmokeは承認待ちでありfixture成功と混同しない。
 
-エージェントの回答が `wait:"agent_done"` の画面 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・抽出不能は明示エラー。
+エージェントの回答が画面 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・抽出不能は明示エラー。
 
 ### 完了検出（5 層）
 
-`pty_read({ wait: true })` は、プロセス終了 / `mark:true` sentinel の自動検出（後述）/ `until` 一致（**既定はリテラル部分一致**、`until_regex: true` で正規表現）/ 出力静止 ∧ シェル復帰（quiescence）/ timeout の 5 層で「コマンドが終わったか」を判定する。ネスト中（SSH・コンテナ・REPL・起動したエージェントの TUI の中）はシェル復帰判定が効かないので、`until` で内側プロンプトを指定するか、`mark: true` で送れば `pty_read({ wait: true })` が sentinel を自動検出する（until 不要・ネストでも効く）——全画面のエージェント TUI なら、出力が落ち着いた時点で `{ screen: true }` を読む。`agent_done:true` で起動したセッションは代わりに `pty_send({ wait:"agent_done" })` を使える。必要な場合はまず agent TUI の入力欄を待ち、その後 vendor Stop hook を待ってターン境界後の画面を返す。`codex_agent` launcher の `wait:"agent_done"` は起動時 `prompt` に同じ待機を行う。`pty_send` の送信前 ready 失敗は MCP エラー、launcher の初回 prompt ready 失敗は `initial_prompt=not_sent` を返す。送信後 timeout は `is_complete=False via agent_timeout` で返り、成功扱いしない。agent session の通常 `pty_read` には `agent_event_seen=true completion_attribution=none` のような補助 metadata が付くことがあるが、古い hook event を `is_complete=True` に昇格しない。完結した hook JSONL 行が壊れていた場合は、切り分け用に timeout suffix へ `malformed_events=N` が付く。ターンは完了したが端末 screen/log が flush 窓内で安定しなかった場合は、`agent_done_but_screen_unstable` が付く。
+`pty_read({ wait: true })` は、プロセス終了 / `mark:true` sentinel の自動検出（後述）/ `until` 一致（**既定はリテラル部分一致**、`until_regex: true` で正規表現）/ 出力静止 ∧ シェル復帰（quiescence）/ timeout の 5 層で「コマンドが終わったか」を判定する。ネスト中（SSH・コンテナ・REPL・起動したエージェントの TUI の中）はシェル復帰判定が効かないので、`until` で内側プロンプトを指定するか、`mark: true` で送れば `pty_read({ wait: true })` が sentinel を自動検出する（until 不要・ネストでも効く）——全画面のエージェント TUI なら、出力が落ち着いた時点で `{ screen: true }` を読む。agent session は第6の正確な層を使う: vendor Stop hook が完了 event を書き、`pty_send` dispatch が返した `event_cursor` 境界から `aiterm-wait --cursor` が完了を観測する（親はブロックもポーリングもしない）。`pty_send` の送信前 ready 失敗は MCP エラー、launcher の初回 prompt ready 失敗は `initial_prompt=not_sent` を返す。agent session の通常 `pty_read` には `agent_event_seen=true completion_attribution=none` のような補助 metadata が付くことがあるが、古い hook event を `is_complete=True` に昇格しない。完結した hook JSONL 行が壊れていた場合は、`aiterm-wait` receipt の `malformed_events` に数えられる。ターンは完了したが端末 screen/log が flush 窓内で安定しなかった場合は、`agent_done_but_screen_unstable` が付く。
 
 ### トークン削減
 

package/README.md

@@ -24,16 +24,18 @@
 
 Twelve 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, and `diagnostics` for safe factory readiness. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
 
-**v0.15.0 was published on 2026-07-18.** It brings the interactive agent
-launchers, durable `claude_turn` issue/recovery, machine-readable launch and
-idempotent close receipts, the hardened TUI readiness gate, and the new
-`aiterm-wait` completion-push binary to npm. 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 tag-triggered CI with npm provenance (OIDC Trusted Publishing);
-the GitHub Release re-registers the Official MCP Registry entry.
-
-**Status:** actively maintained · the newcomer here, betting on a different shape (see [vs. the alternatives](#vs-the-alternatives)) · runs on Linux · WSL2 · macOS · native Windows for the core PTY tools (`agent_done` is POSIX/WSL/macOS only for now) · MIT · see the [CHANGELOG](CHANGELOG.md).
+**v0.17.0 was published on 2026-07-18.** 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
+tag-triggered CI with npm provenance (OIDC Trusted Publishing); the GitHub
+Release re-registers the Official MCP Registry entry.
+
+**Status:** actively maintained · the newcomer here, betting on a different shape (see [vs. the alternatives](#vs-the-alternatives)) · runs on Linux · WSL2 · macOS · native Windows for the core PTY tools (managed completion is POSIX/WSL/macOS only for now) · MIT · see the [CHANGELOG](CHANGELOG.md).
 
 ## Why now
 
@@ -62,27 +64,29 @@ pty_read(id, { wait: true })       → read the token-reduced output, completion
 
 ### 2. Launch other coding agents into that terminal — the orchestration flagship
 
-The same primitive hosts another agent's TUI. Four launchers each start one vendor's interactive coding-agent TUI inside a fresh persistent terminal and return a `session_id`. Their existing human-readable text is accompanied by an `aiterm.agent-launch-result.v1` structured receipt, so durable callers never parse display text for the session handle. From there you drive it with the same `pty_read` / `pty_send` you'd use on any shell: read its output token-reduced, send it the next step. (The TUIs are full-screen apps, so `pty_read({ screen: true })` gives you the rendered view.) Agent launchers can also opt into hook-backed turn completion with `agent_done: true`, letting `pty_send({ wait: "agent_done" })` return after the agent turn ends. A managed Claude session requires that wait mode for every turn. Durable machine callers use `claude_turn({ action: "issue" | "recover", session_id, operation_id, ... })`: it returns fixed `accepted` / `pending` / `completed` / `unknown` states without parsing human-facing errors, never resends during recovery, and includes exact `raw_output` only for a verified completion. The same operation ID is carried through the dispatch receipt, active marker, Stop event, and result. The ordinary `pty_send` / `pty_read` surface remains available for interactive callers and humans. `C-c` keeps the marker for a delayed Stop; if no Stop arrives, close the session. `claude_agent` and `codex_agent` can additionally wait for their initial `prompt`: pass `prompt`, `agent_done: true`, and `wait: "agent_done"`; aiterm starts the TUI first, waits until its input area is ready, submits the prompt, then returns after that first turn's Stop hook. Codex/Grok/Composer have passing live smokes for follow-up completion, and Codex initial-prompt wait is also live-smoked. Claude's real-model initial/follow-up smoke remains an explicit approval gate. Grok/Composer initial-prompt wait is intentionally not exposed until the post-OAuth smoke passes. This needs the vendor's own CLI installed and authenticated — see [Requirements](#requirements).
+The same primitive hosts another agent's TUI. Four launchers each start one vendor's interactive coding-agent TUI inside a fresh persistent terminal and return a `session_id`. Their existing human-readable text is accompanied by an `aiterm.agent-launch-result.v1` structured receipt, so durable callers never parse display text for the session handle; when the launch carries an initial `prompt`, the receipt also includes the `event_cursor` and a ready-made `wait_command` for the completion waiter. From there you drive it with the same `pty_read` / `pty_send` you'd use on any shell: read its output token-reduced, send it the next step. (The TUIs are full-screen apps, so `pty_read({ screen: true })` gives you the rendered view.) Every launch is **managed**: aiterm installs its own Stop hook, so turn completion is a first-class event. Sending to an agent session is a non-blocking **dispatch** — the call returns immediately with an `event_cursor`, and completion arrives via [`aiterm-wait`](#completion-push-for-parent-agents-aiterm-wait). Durable machine callers use `claude_turn({ action: "issue" | "recover", session_id, operation_id, ... })`: it returns fixed `accepted` / `pending` / `completed` / `unknown` states without parsing human-facing errors, never resends during recovery, and includes exact `raw_output` only for a verified completion. The same operation ID is carried through the dispatch receipt, active marker, Stop event, and result. The ordinary `pty_send` / `pty_read` surface remains available for interactive callers and humans. `C-c` keeps the marker for a delayed Stop; if no Stop arrives, close the session. An initial `prompt` on `claude_agent`/`codex_agent` is submitted through the same ready gate and the launcher returns without waiting; on Grok/Composer it is passed on the CLI's argv. This needs the vendor's own CLI installed and authenticated — see [Requirements](#requirements).
 
 ```text
-codex_agent({ session_name: "codex1", cwd: "/repo", agent_done: true,
-              wait: "agent_done", prompt: "port test/legacy.py to vitest" })
+codex_agent({ session_name: "codex1", cwd: "/repo",
+              prompt: "port test/legacy.py to vitest" })
                                     → { session_id: "codex1", … }   # Codex now live in a persistent terminal
 pty_read("codex1", { screen: true })   → read what it's doing (token-reduced)
-pty_send("codex1", "also fix the imports it broke", { wait: "agent_done" })
-                                    → steer it, then return once Codex reaches its next turn boundary
+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
+pty_read("codex1", { agent_transcript: true })           → collect the full answer
 ```
 
 One call per model, so the tool name itself tells you which model you get:
 
 | Tool | Launches | Key args |
 | --- | --- | --- |
-| `claude_agent` | Claude Code CLI (Anthropic) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`), `cwd?`, `session_name?`, `agent_done?`, `launch_operation_id?`, `wait?`, `timeout?`, `screen?`, `lines?` |
-| `codex_agent` | Codex CLI (OpenAI; terminal config/CLI default unless overridden) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`/`ultra`; ultra enables proactive automatic delegation), `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
-| `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?`, `agent_done?` |
-| `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?`, `agent_done?` |
+| `claude_agent` | Claude Code CLI (Anthropic) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`), `cwd?`, `session_name?`, `launch_operation_id?` |
+| `codex_agent` | Codex CLI (OpenAI; terminal config/CLI default unless overridden) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`/`ultra`; ultra enables proactive automatic delegation), `cwd?`, `session_name?` |
+| `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). aiterm resolves the binary via `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`, then `~/.local/bin/claude` / `~/.local/bin/codex` / `~/.grok/bin/grok`, then `PATH`. Prerequisites are checked **before** a session exists: empty `model` values and unsupported effort values are rejected up front; a missing CLI binary or a nonexistent `cwd` fails for all four. A rejected launch leaves **zero leftover session** behind. Claude and Codex launchers forward `model` and `reasoning_effort` through their vendor CLI's public flags; Grok/Composer reject `reasoning_effort` because it is headless-only. Pass an absolute path for `cwd` — `~` is not expanded. Durable callers can make a promptless managed Claude launch exactly replayable by passing an explicit `session_name`, `agent_done:true`, and a `launch_operation_id` formatted as `sha256:<64 lowercase hex>`. Repeating the identical launch returns the same structured session receipt without starting the CLI twice; a different correlation ID or launch argument for that session fails explicitly. With `agent_done:true`, Claude uses launch-local managed settings containing only aiterm's Stop hook: normal user/project/local hooks are not inherited, the hook event contains no answer body, and the bounded owner-only result is returned by `pty_read({ agent_transcript:true })` without reading Claude's private transcript. A timeout remains `is_complete=False`; the same session and a late result remain recoverable without re-sending the prompt. Ordinary `pty_send(wait:"none")` and non-interrupt keys are rejected on this managed Claude route; use `wait:"agent_done"`, `pty_key("C-c")`, and `pty_close`. Start with `agent_done:false` when unconstrained manual key-by-key driving is desired. Codex uses a managed `CODEX_HOME`; Grok/Composer isolate their managed homes and pass validated OAuth state through `GROK_AUTH_PATH`. Before the first unbound completion-waiting send, aiterm waits for the vendor TUI's input prompt and fails before sending if it is not ready. `agent_done` requires POSIX filesystem semantics, so it is supported on Linux, WSL2, and macOS; native Windows can still use launchers without `agent_done`.
+The vendor CLI must be installed and authenticated (`claude` for `claude_agent`; `codex` for `codex_agent`; `grok` for both Grok tools). aiterm resolves the binary via `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`, then `~/.local/bin/claude` / `~/.local/bin/codex` / `~/.grok/bin/grok`, then `PATH`. Prerequisites are checked **before** a session exists: empty `model` values and unsupported effort values are rejected up front; a missing CLI binary or a nonexistent `cwd` fails for all four. A rejected launch leaves **zero leftover session** behind. Claude and Codex launchers forward `model` and `reasoning_effort` through their vendor CLI's public flags; Grok/Composer reject `reasoning_effort` because it is headless-only. Pass an absolute path for `cwd` — `~` is not expanded. Durable callers can make a promptless Claude launch exactly replayable by passing an explicit `session_name` and a `launch_operation_id` formatted as `sha256:<64 lowercase hex>`. Repeating the identical launch returns the same structured session receipt without starting the CLI twice; a different correlation ID or launch argument for that session fails explicitly. Claude uses launch-local managed settings containing only aiterm's Stop hook: normal user/project/local hooks are not inherited, the hook event contains no answer body, and the bounded owner-only result is returned by `pty_read({ agent_transcript:true })` without reading Claude's private transcript. A late result remains recoverable from the same session without re-sending the prompt. Non-interrupt keys are rejected on the managed Claude route; use dispatch, `pty_key("C-c")`, and `pty_close` (`force:true` on `pty_send` is the manual-intervention escape). For unconstrained manual key-by-key driving, open a plain `pty_open` session and start the vendor CLI yourself. Codex uses a managed `CODEX_HOME`; Grok/Composer isolate their managed homes and pass validated OAuth state through `GROK_AUTH_PATH`. Before the first unbound dispatch, aiterm waits for the vendor TUI's input prompt and fails before sending if it is not ready. Managed completion requires POSIX filesystem semantics (Linux, WSL2, macOS).
 
 There is no hidden protocol between agents: a launched Claude, Codex, Grok, or Composer is another user-visible persistent terminal session. The MCP client drives that TUI with ordinary PTY operations, and a human can attach to watch or take over.
 
@@ -264,12 +268,12 @@ On top of that sits a productized layer a raw tmux bridge doesn't have: **token-
 | Tool | Role | Key args |
 | --- | --- | --- |
 | `pty_open` | Grab one terminal, return a `session_id` | `name?`, `shell="bash"` |
-| `pty_send` | Send text (a command) | `session_id`, `text`, `enter=true`, `wait`, `timeout`, `screen`, `lines`, `operation_id`, `mark`, `force`, `rtk`, `raw` |
+| `pty_send` | Send text; on an agent session this is a non-blocking **dispatch** returning an `event_cursor` | `session_id`, `text`, `enter=true`, `mark`, `force`, `rtk`, `raw` |
 | `pty_read` | Read output, token-reduced (incremental by default) | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk`, `agent_transcript`, `operation_id` |
 | `pty_key` | Send a control key | `session_id`, `key` (`C-c`/`Enter`/`Up`…) |
 | `pty_close` | Close idempotently; return `closed` / `already_closed` | `session_id` |
 | `pty_list` | List sessions (agent rows carry `agent=<kind>` metadata) | (none) |
-| `claude_turn` | Issue or recover one correlated managed-Claude operation | `action`, `session_id`, `operation_id`, `text?`, `timeout?` |
+| `claude_turn` | Issue (dispatch-only) or recover one correlated managed-Claude operation | `action`, `session_id`, `operation_id`, `text?` |
 | `diagnostics` | Read-only factory readiness as machine-readable JSON | (none) |
 
 `diagnostics` never starts a PTY or agent. It reports package version, MCP call readiness, a read-only PTY-list summary, bounded runtime-error-store status, and optional vendor-launcher availability. It deliberately excludes paths, environment values, credentials, command text, PTY output, and raw logs; normal unset optional dependencies are `not_applicable`, while an indeterminate probe is `unverified`.
@@ -286,31 +290,29 @@ Each launcher starts a specific vendor's interactive coding-agent TUI inside a f
 
 | Tool | Launches | Key args |
 | --- | --- | --- |
-| `claude_agent` | Claude Code CLI (Anthropic) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`), `cwd?`, `session_name?`, `agent_done?`, `launch_operation_id?`, `wait?`, `timeout?`, `screen?`, `lines?` |
-| `codex_agent` | Codex CLI (OpenAI; terminal config/CLI default unless overridden) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`/`ultra`; ultra enables proactive automatic delegation), `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
-| `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?`, `agent_done?` |
-| `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?`, `agent_done?` |
+| `claude_agent` | Claude Code CLI (Anthropic) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`), `cwd?`, `session_name?`, `launch_operation_id?` |
+| `codex_agent` | Codex CLI (OpenAI; terminal config/CLI default unless overridden) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`/`ultra`; ultra enables proactive automatic delegation), `cwd?`, `session_name?` |
+| `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. Claude and Codex expose initial-prompt completion waiting; all four use the same follow-up `pty_send(wait:"agent_done")` contract where supported. 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 `agent_done` 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. 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.
 
-When an agent's answer is longer than the `wait:"agent_done"` screen tail (pane height ≈ 24 lines), interactive callers can 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.
+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.
 
 ### Completion detection (5 layers)
 
-`pty_read({ wait: true })` decides "is the command done?" via five layers: process exit / a `mark:true` sentinel (auto-detected — see below) / an `until` match (a literal substring by default; pass `until_regex: true` for a regex) / output is quiescent ∧ the shell is back (quiescence) / timeout. While nested (inside SSH, a container, a REPL, or a launched agent's TUI), the "shell is back" check cannot fire, so pass `until` with the inner prompt — or send with `mark: true` and `pty_read({ wait: true })` auto-detects the completion sentinel (no `until` needed, works nested too) — or, for a full-screen agent TUI, read `{ screen: true }` once its output settles. Sessions launched with `agent_done:true` can instead use `pty_send({ wait:"agent_done" })`, which first waits for the agent TUI input prompt when needed, then waits for the vendor Stop hook and returns the screen after the turn boundary; `claude_agent` and `codex_agent` launcher `wait:"agent_done"` do the same for the initial `prompt`. Pre-send readiness failures are MCP errors for `pty_send`, while launch-time initial prompt readiness failures return the session with `initial_prompt=not_sent`; timeouts after sending are reported as `is_complete=False via agent_timeout`, not as success. A late Claude completion remains recoverable from the same session with `pty_read({ agent_transcript:true })`, without resending. Normal `pty_read` on an agent session can append auxiliary metadata such as `agent_event_seen=true completion_attribution=none`, but a stale hook event is not promoted to `is_complete=True`. If a complete hook JSONL line is malformed, the timeout suffix includes `malformed_events=N` for diagnosis. If the turn is done but the terminal screen/log does not settle within the flush window, aiterm appends `agent_done_but_screen_unstable`.
+`pty_read({ wait: true })` decides "is the command done?" via five layers: process exit / a `mark:true` sentinel (auto-detected — see below) / an `until` match (a literal substring by default; pass `until_regex: true` for a regex) / output is quiescent ∧ the shell is back (quiescence) / timeout. While nested (inside SSH, a container, a REPL, or a launched agent's TUI), the "shell is back" check cannot fire, so pass `until` with the inner prompt — or send with `mark: true` and `pty_read({ wait: true })` auto-detects the completion sentinel (no `until` needed, works nested too) — or, for a full-screen agent TUI, read `{ screen: true }` once its output settles. Agent sessions use the sixth, exact layer instead: the vendor Stop hook writes a completion event, `pty_send` dispatch returns the `event_cursor` boundary, and `aiterm-wait --cursor` observes the completion without the parent blocking or polling. Pre-send readiness failures are MCP errors for `pty_send`, while launch-time initial prompt readiness failures return the session with `initial_prompt=not_sent`. A late Claude completion remains recoverable from the same session with `pty_read({ agent_transcript:true })`, without resending. Normal `pty_read` on an agent session can append auxiliary metadata such as `agent_event_seen=true completion_attribution=none`, but a stale hook event is not promoted to `is_complete=True`. If a complete hook JSONL line is malformed, the `aiterm-wait` receipt counts it in `malformed_events` for diagnosis. If the turn is done but the terminal screen/log does not settle within the flush window, aiterm appends `agent_done_but_screen_unstable`.
 
 ### Completion push for parent agents (`aiterm-wait`)
 
-The `wait:"agent_done"` route blocks the caller's tool call. For fire-and-forget orchestration ("B-style": dispatch now, collect later, never poll), the `aiterm-wait` binary turns the Stop-hook completion event into a process exit that a host harness can treat as a push notification:
-
-1. Launch the child agent (`agent_done: true`) and start `aiterm-wait --session <id> [--operation sha256:<64hex>] [--timeout <sec>]` as a **background task of the parent's harness**.
-2. Dispatch the prompt with `claude_turn issue` (`timeout: 0`) or `pty_send(wait:"agent_done", timeout: 0)` — the TUI ready gate and submit sequencing still run; the call returns immediately.
-3. The parent is free. When the child's turn ends, the vendor Stop hook appends the event, `aiterm-wait` exits with a one-line receipt (`aiterm.agent-wait-result.v1`, outcome `done` / `timeout` / `closed`), and a harness that re-invokes its agent on background-task exit (Claude Code does) wakes the parent with zero polling.
-4. The parent collects the result exactly as before: `claude_turn recover` (Claude) or `pty_read` (other vendors). The waiter carries the signal, never the payload.
+As of v0.16 a parent agent **never blocks** on aiterm — there is no wait parameter anywhere (v0.17 makes the waiter's exit codes mirror its outcome). The whole flow is dispatch + one universal waiter:
 
-`aiterm-wait` is a **pure reader**: it takes no locks, never writes session state, and never dispatches — so any number of waiters can run beside the MCP server and beside each other (one per launch), and `pty_close`/concurrent sends are unaffected. Start the waiter *before* dispatching (or pass `--operation`, which is start-order-independent) so no completion can slip past the observation boundary.
+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.
+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.
+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.
 
-Codex CLI as the *parent* currently has no equivalent "wake on background completion" hook (its `notify` config is human-facing and MCP notifications are not surfaced to the model — see openai/codex#17543 / #18056), so a Codex parent still uses the blocking wait or manual recovery until upstream support lands.
+`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
 
@@ -380,7 +382,7 @@ MIT
 
 ## Grok OAuth isolation
 
-For `agent_done`, Grok/Composer keep launch-local `GROK_HOME` and fake `HOME`.
+For managed completion, Grok/Composer keep launch-local `GROK_HOME` and fake `HOME`.
 The child receives `GROK_AUTH_PATH` pointing at the validated normal auth
 canonical file; managed homes never contain auth or lock symlinks/copies.
 aiterm does not create locks or copy credentials back. An inherited

package/dist/aiterm-wait-cli.js

@@ -1,20 +1,23 @@
 #!/usr/bin/env node
 // aiterm-wait — agent turn 完了eventの純リーダー観測CLI。
 // 完了/timeout/close を1行のJSON receiptで返してexitする。lock・PTY・dispatch状態には一切触れない。
-// 親AIホストのバックグラウンドタスクとして起動し、exitを「完了通知」として使う。
+// 親AIホストのバックグラウンドタスクとして起動し、exitを「観測終了の通知」として使う。
+// exit≠完了: exit code は outcome を映す（0=done / 3=timeout=未完了 / 4=closed / 1=エラー）。
+// 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> [--operation sha256:<64hex>] [--timeout <sec>]";
+const USAGE = "usage: aiterm-wait --session <name> [--cursor <event_cursor>] [--operation sha256:<64hex>] [--timeout <sec>]";
 export function parseArgs(argv) {
     let session = null;
     let operationId = null;
     let timeout = null;
+    let cursor = null;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
-        if (a === "--session" || a === "--operation" || a === "--timeout") {
+        if (a === "--session" || a === "--operation" || a === "--timeout" || a === "--cursor") {
             const v = argv[i + 1];
             if (v === undefined)
                 throw new Error(`${a} に値がありません。${USAGE}`);
@@ -33,6 +36,13 @@ export function parseArgs(argv) {
                     throw new Error(`--operation が不正です。${USAGE}`);
                 operationId = v;
             }
+            else if (a === "--cursor") {
+                if (cursor !== null)
+                    throw new Error(`--cursor が重複しています。${USAGE}`);
+                if (!/^\d+$/.test(v))
+                    throw new Error(`--cursor は0以上の整数byte offsetだけを受理します。${USAGE}`);
+                cursor = Number(v);
+            }
             else {
                 if (timeout !== null)
                     throw new Error(`--timeout が重複しています。${USAGE}`);
@@ -49,18 +59,22 @@ export function parseArgs(argv) {
     }
     if (session === null)
         throw new Error(`--session は必須です。${USAGE}`);
-    return { session, operationId, timeout: timeout ?? 600 };
+    return { session, operationId, timeout: timeout ?? 600, cursor };
 }
 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 };
 export async function main(argv) {
     const cmd = parseArgs(argv);
     const result = await observeAgentDone(cmd.session, {
         operation_id: cmd.operationId,
         timeout: cmd.timeout,
+        cursor: cmd.cursor,
     });
     emit(result);
+    process.exitCode = OUTCOME_EXIT_CODES[result.outcome];
 }
 function isDirectExecution() {
     const entry = process.argv[1];

package/dist/core.js

@@ -1215,9 +1215,6 @@ export function readOnlyPtyListDiagnostic() {
 }
 function closeSessionInternal(name, observeDependency = true) {
     assertSessionName(name);
-    if (agentWaitLocks.has(name)) {
-        throw new AitermError(`agent session '${name}' は agent_done 待機中のため close できません`, 2);
-    }
     {
         // 別プロセスの待機は in-memory Set に映らない。生きた file lock があれば close で state を消さない
         const foreign = liveWaitLocks(name);
@@ -1266,9 +1263,6 @@ export function closeSessionResult(name) {
     };
 }
 export function killAll() {
-    if (agentWaitLocks.size > 0) {
-        throw new AitermError(`agent_done 待機中の session があるため killAll できません: ${Array.from(agentWaitLocks).join(",")}`, 2);
-    }
     {
         // 別プロセスの待機（file lock が生きているもの）も巻き添えにしない
         const foreign = liveWaitLocks(null);
@@ -1332,16 +1326,8 @@ export function killAll() {
     return "killed all sessions on this socket";
 }
 const DEFAULT_AGENT_DONE_TIMEOUT = 600;
-const agentWaitLocks = new Set();
 const agentMetadataNegativeCache = new Map();
 let agentTuiReadyStableSamplesTestOverride = null;
-function normalizeAgentLauncherWait(v) {
-    if (v == null || v === "none")
-        return "none";
-    if (v === "agent_done")
-        return "agent_done";
-    throw new AitermError('wait は "none" または "agent_done" を指定してください', 2);
-}
 function codexHookScriptPath() {
     return path.join(path.dirname(fileURLToPath(import.meta.url)), "codex-stop-hook.js");
 }
@@ -2031,61 +2017,12 @@ function liveWaitLocks(name) {
         const session = f.slice(0, f.indexOf("."));
         if (name != null && session !== name)
             continue;
-        if (agentWaitLocks.has(session))
-            continue; // in-process 待機は呼び出し側の既存ガードが担当
         const probe = probeWaitLock(path.join(dir, f));
         if (probe.live)
             out.push({ session, pid: probe.pid, at: probe.at });
     }
     return out;
 }
-function waitLockBusyError(session, probe) {
-    const detail = probe.pid != null ? `（pid ${probe.pid}${probe.at ? ` / ${probe.at} 開始` : ""}）` : "";
-    return new AitermError(`agent session '${session}' は別プロセスの agent_done 待機中です${detail}`, 2);
-}
-function acquireAgentWaitFileLock(meta) {
-    const p = agentWaitLockPath(meta.aiterm_session, meta.launch_id);
-    const nofollow = fs.constants.O_NOFOLLOW ?? 0;
-    let fd = null;
-    for (let attempt = 0; attempt < 2 && fd == null; attempt++) {
-        try {
-            fd = fs.openSync(p, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | nofollow, 0o600);
-        }
-        catch (e) {
-            if (e.code !== "EEXIST")
-                throw e;
-            const probe = probeWaitLock(p);
-            // 生きた待機、または回収後の再取得でも EEXIST（=直後に別プロセスが取得した race）は拒否
-            if (probe.live || attempt > 0)
-                throw waitLockBusyError(meta.aiterm_session, probe);
-            unlinkStaleWaitLock(p);
-        }
-    }
-    if (fd == null)
-        throw new AitermError(`agent session '${meta.aiterm_session}' は別プロセスの agent_done 待機中です`, 2);
-    try {
-        fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }) + "\n", undefined, "utf8");
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-    try {
-        fs.chmodSync(p, 0o600);
-    }
-    catch {
-        /* noop */
-    }
-    return () => {
-        try {
-            const st = fs.lstatSync(p);
-            if (st.isFile() && !st.isSymbolicLink() && st.uid === currentUid())
-                fs.unlinkSync(p);
-        }
-        catch {
-            /* noop */
-        }
-    };
-}
 function createClaudeAgentMetadata(name, cwd, initialPrompt, launchOperationId, launchRequestDigest) {
     const launchId = randomBytes(16).toString("hex");
     const eventFile = agentEventPath(name, launchId);
@@ -2489,8 +2426,11 @@ 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 がまだありません。ターン完了後に再取得してください。", 2);
+    throw new AitermError(`transcript がまだありません。ターン完了後に再取得してください。${AGENT_WAIT_GUIDE}`, 2);
 }
 function transcriptNotFound(vendor) {
     throw new AitermError(`最終 assistant メッセージを特定できませんでした（vendor=${vendor}）。screen で確認してください。`, 2);
@@ -2557,18 +2497,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から再取得してください。`, 2);
+            throw new AitermError(`${label} はまだ完了していません。Stop完了後に同じsessionから再取得してください。${AGENT_WAIT_GUIDE}`, 2);
         }
     }
     // wait timeout は「失敗」ではなく状態不明。後着した同一launchの完了eventから
     // vendor session をbindし、promptを再送せず結果だけ回収できるようにする。
     recoverAgentVendorSession(meta);
     if (!meta.vendor_session_id) {
-        throw new AitermError(`agent session '${name}' はまだターンが完了していません。agent_done 完了後に再取得してください。`, 2);
+        throw new AitermError(`agent session '${name}' はまだターンが完了していません。agent_done 完了後に再取得してください。${AGENT_WAIT_GUIDE}`, 2);
     }
     const done = latestAgentDoneEvent(meta, operationId);
     if (operationId && !done) {
-        throw new AitermError(`operation ${operationId} はまだ完了していません。同じoperation_idで後から再取得してください。`, 2);
+        throw new AitermError(`operation ${operationId} はまだ完了していません。同じoperation_idで後から再取得してください。${AGENT_WAIT_GUIDE}`, 2);
     }
     const turnId = done?.turn_id ?? null;
     let text = "";
@@ -2711,42 +2651,8 @@ function assertInitialPromptNotPendingForSend(name, force) {
     throw new AitermError(`agent session '${name}' は起動時 prompt の完了待ちです。通常 pty_send は混入防止のため送信しません。` +
         `完了後に pty_send(wait:"agent_done") するか、手動介入が必要な場合だけ force:true を明示してください。`, 2);
 }
-async function waitAgentDoneEvent(meta, startOffset, timeout, expectedOperationId = null) {
-    const deadline = performance.now() + timeout * 1000;
-    let cursor = startOffset;
-    let carry = "";
-    let malformedEvents = 0;
-    for (;;) {
-        const size = safeStatSize(meta.event_file);
-        if (size < cursor) {
-            cursor = 0;
-            carry = "";
-        }
-        if (size > cursor) {
-            if (size - cursor > AGENT_EVENT_MAX_BYTES) {
-                throw new AitermError("agent event file の増分が大きすぎます。該当セッションを閉じて起動し直してください。", 2);
-            }
-            carry += readFileRange(meta.event_file, cursor, size).toString("utf8");
-            cursor = size;
-            const parts = carry.split("\n");
-            carry = parts.pop() ?? "";
-            const scanned = scanAgentDoneLines(parts, meta, expectedOperationId);
-            malformedEvents += scanned.malformedEvents;
-            if (scanned.ambiguousVendorSession) {
-                throw new AitermError("agent event file に複数の vendor_session_id が混在しています。該当セッションを閉じて起動し直してください。", 2);
-            }
-            if (scanned.event) {
-                bindAgentVendorSession(meta, scanned.event);
-                if (meta.vendor_session_id)
-                    writeAgentMetadata(meta);
-                return { event: scanned.event, malformedEvents };
-            }
-        }
-        if (performance.now() >= deadline)
-            return { event: null, malformedEvents };
-        await sleep(AGENT_DONE_POLL_MS);
-    }
-}
+// 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以外は未完了`;
 // 外部waiterプロセス用の純リーダー観測。lock・PTY・metadata書込・dispatch状態には一切触れない。
 // event fileのtail規律（未終端行保持・増分上限）はwaitAgentDoneEventと同一だが、
 // vendor_session_idのbind永続化を行わない点だけ意図的に異なる（waiterは観測者であって所有者でない）。
@@ -2756,11 +2662,14 @@ export async function observeAgentDone(name, o = {}) {
     if (operationId && meta.kind !== "claude") {
         throw new AitermError("operation_id はClaude agent sessionだけで使用できます", 2);
     }
+    if (o.cursor != null && (!Number.isInteger(o.cursor) || o.cursor < 0)) {
+        throw new AitermError("cursor は0以上の整数byte offsetで指定してください", 2);
+    }
     const timeout = o.timeout ?? DEFAULT_AGENT_DONE_TIMEOUT;
     const metadataFile = agentMetadataPath(meta.aiterm_session, meta.launch_id);
-    // operation相関があるならoperation_idの一意性で誤帰属を防げるため先頭から全走査できる
-    // （waiter起動がdispatchより遅れても取りこぼさない）。相関なしはwaiter起動時EOFを境界にする。
-    const startOffset = operationId ? 0 : safeStatSize(meta.event_file);
+    // 境界の優先順: dispatch receipt の event_cursor（起動順序に依存しない）→ operation相関
+    // （operation_idの一意性で先頭から全走査できる）→ waiter起動時EOF（waiter先行起動が前提）。
+    const startOffset = o.cursor ?? (operationId ? 0 : safeStatSize(meta.event_file));
     const deadline = performance.now() + timeout * 1000;
     let cursor = startOffset;
     let carry = "";
@@ -2806,24 +2715,6 @@ export async function observeAgentDone(name, o = {}) {
         await sleep(AGENT_DONE_POLL_MS);
     }
 }
-function agentDoneSuffix(wait, vendor, operationId = null) {
-    const ev = wait.event;
-    if (!ev) {
-        const malformed = wait.malformedEvents ? ` malformed_events=${wait.malformedEvents}` : "";
-        const operation = operationId ? ` operation_id=${operationId}` : "";
-        return ` [is_complete=False via agent_timeout vendor=${vendor}${operation}${malformed}]`;
-    }
-    const bits = [
-        "is_complete=True",
-        "via agent_done",
-        `vendor=${ev.vendor}`,
-        ev.turn_id ? `turn_id=${ev.turn_id}` : null,
-        ev.vendor_session_id ? `vendor_session_id=${ev.vendor_session_id}` : null,
-        ev.operation_id ? `operation_id=${ev.operation_id}` : null,
-        `done_status=${ev.done_status}`,
-    ].filter(Boolean);
-    return ` [${bits.join(" ")}]`;
-}
 function isAgentTuiReady(kind, screen) {
     if (kind === "claude") {
         return screen.includes("Claude Code") && /(^|\n)\s*❯/.test(screen);
@@ -2890,12 +2781,6 @@ async function settleAgentDoneScreenImpl(sample, sleepFn, opts = {}) {
     }
     return { unstable: true, samples };
 }
-async function settleAgentDoneScreen(name, lines) {
-    return settleAgentDoneScreenImpl(() => ({
-        screen: captureScreen(name, lines),
-        logSize: safeStatSize(logpath(name)),
-    }), sleep);
-}
 export async function __testSettleAgentDoneScreen(samples, opts = {}) {
     if (samples.length === 0)
         throw new AitermError("screen settle test samples が空です", 2);
@@ -2939,135 +2824,96 @@ async function sendAgentPromptText(name, text) {
 }
 export async function sendInitialAgentPrompt(name, text, o = {}) {
     assertSessionName(name);
-    const waitMode = normalizeAgentLauncherWait(o.wait);
     const meta = loadAgentMetadata(name);
-    if (agentWaitLocks.has(name))
-        throw new AitermError(`agent session '${name}' は別の agent_done 待機中です`, 2);
     if (meta.initial_prompt === "done") {
         throw new AitermError(`agent session '${name}' の起動時 prompt は既に完了しています`, 2);
     }
     if (meta.initial_prompt === "pending" || meta.initial_prompt === "sent") {
         throw new AitermError(`agent session '${name}' は起動時 prompt の完了待ちです。初回応答完了後に再度操作してください。`, 2);
     }
-    const releaseFileLock = acquireAgentWaitFileLock(meta);
-    const timeout = o.timeout ?? DEFAULT_AGENT_DONE_TIMEOUT;
-    const screen = o.screen ?? true;
-    agentWaitLocks.add(name);
+    setInitialPromptState(meta, "not_sent");
+    const ready = await waitAgentTuiReady(name, meta, o.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
+    if (!ready.ready) {
+        return {
+            text: `initial_prompt=not_sent vendor=${meta.kind} ready=false samples=${ready.samples}\n` +
+                `agent session '${name}' の ${agentLabel(meta.kind)} TUI が入力受付状態になりません。prompt は送信していません。`,
+            event_cursor: null,
+        };
+    }
+    const startOffset = safeStatSize(meta.event_file);
     try {
-        setInitialPromptState(meta, "not_sent");
-        const ready = await waitAgentTuiReady(name, meta, o.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
-        if (!ready.ready) {
-            return (`initial_prompt=not_sent vendor=${meta.kind} ready=false samples=${ready.samples}\n` +
-                `agent session '${name}' の ${agentLabel(meta.kind)} TUI が入力受付状態になりません。prompt は送信していません。`);
-        }
-        const startOffset = safeStatSize(meta.event_file);
-        try {
-            if (meta.kind === "claude") {
-                prepareSendText(text, { raw: false, force: true });
-                reserveAnonymousClaudeTurn(meta);
-            }
-            await sendAgentPromptText(name, text);
-            setInitialPromptState(meta, "pending");
-        }
-        catch (e) {
-            setInitialPromptState(meta, "failed");
-            throw e;
-        }
-        if (waitMode === "none") {
-            return (`initial_prompt=pending vendor=${meta.kind}\n` +
-                `起動時 prompt を送信しました。完了後の follow-up は pty_send(wait:"agent_done") を使ってください。`);
-        }
-        const wait = await waitAgentDoneEvent(meta, startOffset, timeout);
-        if (wait.event) {
-            setInitialPromptState(meta, "done");
+        if (meta.kind === "claude") {
+            prepareSendText(text, { raw: false, force: true });
+            reserveAnonymousClaudeTurn(meta);
         }
-        else {
-            setInitialPromptState(meta, "pending");
-        }
-        const settled = wait.event
-            ? await settleAgentDoneScreen(name, o.lines ?? 0)
-            : { unstable: false, samples: 0 };
-        const out = await readOutput(name, {
-            screen,
-            lines: o.lines ?? null,
-            timeout: 0,
-        });
-        writeOffset(name, safeStatSize(logpath(name)));
-        return out + agentDoneSuffix(wait, meta.kind) + (settled.unstable ? " [agent_done_but_screen_unstable]" : "");
+        await sendAgentPromptText(name, text);
+        setInitialPromptState(meta, "pending");
     }
-    finally {
-        agentWaitLocks.delete(name);
-        releaseFileLock();
+    catch (e) {
+        setInitialPromptState(meta, "failed");
+        throw e;
     }
+    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) を使う。`,
+        event_cursor: startOffset,
+    };
+}
+export function isAgentSession(name) {
+    assertSessionName(name);
+    return tryLoadAgentMetadata(name) !== null;
 }
-export async function sendAndWaitAgentDone(name, text, o = {}) {
+// v0.16.0: 親をブロックする wait 経路は廃止した。send は ready gate と submit 分離を内蔵した
+// dispatch として即返り、event_cursor（送信直前の event file 境界）を receipt で返す。
+// 完了通知は aiterm-wait（--cursor で境界を渡す）、回収は pty_read / claude_turn recover が担う。
+export async function dispatchAgentTurn(name, text, o = {}) {
     assertSessionName(name);
-    if (o.enter === false)
-        throw new AitermError('wait:"agent_done" は enter:false と併用できません', 2);
-    if (o.mark)
-        throw new AitermError('wait:"agent_done" と mark:true は併用できません', 2);
-    if (o.rtk)
-        throw new AitermError('wait:"agent_done" と rtk:true は併用できません', 2);
     const meta = loadAgentMetadata(name);
     const operationId = o.operation_id == null ? null : validateOperationId(o.operation_id);
     if (operationId && meta.kind !== "claude") {
         throw new AitermError("operation_id はClaude agent sessionだけで使用できます", 2);
     }
-    if (agentWaitLocks.has(name))
-        throw new AitermError(`agent session '${name}' は別の agent_done 待機中です`, 2);
-    const releaseFileLock = acquireAgentWaitFileLock(meta);
-    const timeout = o.timeout ?? DEFAULT_AGENT_DONE_TIMEOUT;
-    const screen = o.screen ?? true;
-    agentWaitLocks.add(name);
-    try {
-        bindCompletedInitialPrompt(meta);
-        if (!meta.vendor_session_id) {
-            const ready = await waitAgentTuiReady(name, meta, o.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
-            if (!ready.ready) {
-                throw new AitermError(`agent session '${name}' の ${agentLabel(meta.kind)} TUI が入力受付状態になりません。文字列は送信していません。` +
-                    "少し後で pty_read(screen:true) を確認し、TUI が起動済みなら再度 pty_send(wait:\"agent_done\") してください。", 2);
-            }
-        }
-        const startOffset = safeStatSize(meta.event_file);
-        if (meta.kind === "claude") {
-            // durable／anonymousを分岐する前に同じsend preflightを通す。拒否されるpromptの
-            // receipt／active markerだけを残して、来ないStopを待つ状態を作らない。
-            prepareSendText(text, { raw: o.raw, force: o.force });
-            if (operationId) {
-                reserveClaudeOperation(meta, operationId);
-            }
-            else
-                reserveAnonymousClaudeTurn(meta);
+    bindCompletedInitialPrompt(meta);
+    if (!meta.vendor_session_id) {
+        const ready = await waitAgentTuiReady(name, meta, o.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
+        if (!ready.ready) {
+            throw new AitermError(`agent session '${name}' の ${agentLabel(meta.kind)} TUI が入力受付状態になりません。文字列は送信していません。` +
+                "少し後で pty_read(screen:true) を確認し、TUI が起動済みなら再度 pty_send してください。", 2);
         }
-        send(name, text, {
-            enter: false,
-            force: o.force,
-            raw: o.raw,
-            mark: false,
-            rtk: false,
-            preserveAgentOperation: meta.kind === "claude",
-        });
-        // Codex TUI は literal text 投入直後の Enter を取り落とすことがある。agent 経路だけ submit を分離する。
-        await sleep(AGENT_SUBMIT_DELAY_MS);
-        sendKey(name, "Enter", { preserveAgentOperation: meta.kind === "claude" });
-        const wait = await waitAgentDoneEvent(meta, startOffset, timeout, operationId);
-        const settled = wait.event
-            ? await settleAgentDoneScreen(name, o.lines ?? 0)
-            : { unstable: false, samples: 0 };
-        const out = await readOutput(name, {
-            screen,
-            lines: o.lines ?? null,
-            timeout: 0,
-        });
-        writeOffset(name, safeStatSize(logpath(name)));
-        return out + agentDoneSuffix(wait, meta.kind, operationId) + (settled.unstable ? " [agent_done_but_screen_unstable]" : "");
     }
-    finally {
-        agentWaitLocks.delete(name);
-        releaseFileLock();
+    const startOffset = safeStatSize(meta.event_file);
+    if (meta.kind === "claude") {
+        // durable／anonymousを分岐する前に同じsend preflightを通す。拒否されるpromptの
+        // receipt／active markerだけを残して、来ないStopを待つ状態を作らない。
+        prepareSendText(text, { raw: o.raw, force: o.force });
+        if (operationId) {
+            reserveClaudeOperation(meta, operationId);
+        }
+        else
+            reserveAnonymousClaudeTurn(meta);
     }
+    send(name, text, {
+        enter: false,
+        force: o.force,
+        raw: o.raw,
+        mark: false,
+        rtk: false,
+        preserveAgentOperation: meta.kind === "claude",
+    });
+    // Codex TUI は literal text 投入直後の Enter を取り落とすことがある。agent 経路だけ submit を分離する。
+    await sleep(AGENT_SUBMIT_DELAY_MS);
+    sendKey(name, "Enter", { preserveAgentOperation: meta.kind === "claude" });
+    return {
+        schema: "aiterm.agent-dispatch.v1",
+        session_id: meta.aiterm_session,
+        launch_id: meta.launch_id,
+        vendor: meta.kind,
+        event_cursor: startOffset,
+        operation_id: operationId,
+    };
 }
-export async function runClaudeOperation({ session_id: name, action, operation_id: operationIdInput, text, timeout, }) {
+export async function runClaudeOperation({ session_id: name, action, operation_id: operationIdInput, text, }) {
     assertSessionName(name);
     if (action !== "issue" && action !== "recover") {
         throw new AitermError('action は "issue" または "recover" を指定してください', 2);
@@ -3080,22 +2926,12 @@ export async function runClaudeOperation({ session_id: name, action, operation_i
         if (typeof text !== "string" || text.length === 0) {
             throw new AitermError("claude_turn issueには空でないtextが必要です", 2);
         }
-        const waitTimeout = timeout ?? DEFAULT_AGENT_DONE_TIMEOUT;
-        if (!Number.isFinite(waitTimeout) || waitTimeout < 0 || waitTimeout > 3600) {
-            throw new AitermError("claude_turn timeoutは0〜3600秒で指定してください", 2);
-        }
-        await sendAndWaitAgentDone(name, text, {
-            operation_id: operationId,
-            timeout: waitTimeout,
-            screen: false,
-            lines: 0,
-        });
+        // v0.16.0: issue は dispatch-only。完了通知は aiterm-wait --operation、回収は recover が担う。
+        await dispatchAgentTurn(name, text, { operation_id: operationId });
     }
     else {
         if (text != null)
             throw new AitermError("claude_turn recoverにtextは指定できません", 2);
-        if (timeout != null)
-            throw new AitermError("claude_turn recoverにtimeoutは指定できません", 2);
     }
     const inspected = inspectClaudeOperation(meta, operationId, action);
     if (action === "issue" && inspected.status === "pending") {
@@ -3497,37 +3333,26 @@ export function openAgent(kind, opts = {}) {
             `起動直後に増分 pty_read すると空/半描画になり得るので screen:true を使う。`,
     ];
 }
-async function sendInitialPromptWithoutAgentDone(name, kind, text, opts = {}) {
-    const ready = await waitAgentTuiReadyByKind(name, kind, opts.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
-    if (!ready.ready) {
-        return (`initial_prompt=not_sent vendor=${kind} ready=false samples=${ready.samples}\n` +
-            `agent session '${name}' の ${agentLabel(kind)} TUI が入力受付状態になりません。prompt は送信していません。`);
-    }
-    await sendAgentPromptText(name, text);
-    return `initial_prompt=sent vendor=${kind}\n起動時 prompt を送信しました。完了待ちは通常の pty_read で行ってください。`;
-}
 export async function openAgentWithInitialPrompt(kind, opts = {}) {
-    const waitMode = normalizeAgentLauncherWait(opts.wait);
     const prompt = opts.prompt ?? null;
-    const agentDone = !!opts.agent_done;
-    if (opts.launch_operation_id != null && (prompt !== null || waitMode !== "none")) {
-        throw new AitermError('launch_operation_idはpromptなし・wait:"none"のmanaged Claude launchだけで指定できます', 2);
-    }
-    if (waitMode === "agent_done" && !prompt) {
-        throw new AitermError('wait:"agent_done" は prompt 指定時だけ使えます', 2);
-    }
-    if (waitMode === "agent_done" && !agentDone) {
-        throw new AitermError('wait:"agent_done" には agent_done:true が必要です', 2);
-    }
-    if (!prompt) {
-        return openAgent(kind, opts);
-    }
-    if (kind !== "codex" && kind !== "claude") {
-        if (waitMode === "agent_done") {
-            throw new AitermError(`${agentLabel(kind)} の起動時 prompt wait は未対応です。` +
-                `agent_done:true で prompt なし起動後、TUI のログイン/ready を確認してから pty_send(wait:"agent_done") を使ってください。`, 2);
-        }
-        return openAgent(kind, opts);
+    if (opts.launch_operation_id != null && prompt !== null) {
+        throw new AitermError("launch_operation_idはpromptなしのmanaged Claude launchだけで指定できます", 2);
+    }
+    // v0.16.0: launcher は常に managed（Stop hook つき）で立つ。手動運転したい場合は
+    // pty_open で素の PTY を開き、vendor CLI を自分で send する。
+    // 第3要素は「起動時点でturnが走っているか」の event_cursor: Grok/Composer の argv prompt は
+    // event file 新規作成直後の起動＝境界0、prompt なしの起動は turn なし＝null。
+    if (!prompt || (kind !== "codex" && kind !== "claude")) {
+        const [sid, hint] = openAgent(kind, {
+            session_name: opts.session_name ?? null,
+            model: opts.model ?? null,
+            reasoning_effort: opts.reasoning_effort ?? null,
+            cwd: opts.cwd ?? null,
+            prompt,
+            agent_done: true,
+            launch_operation_id: opts.launch_operation_id ?? null,
+        });
+        return [sid, hint, prompt ? 0 : null];
     }
     const [sid, hint] = openAgent(kind, {
         session_name: opts.session_name ?? null,
@@ -3535,22 +3360,14 @@ export async function openAgentWithInitialPrompt(kind, opts = {}) {
         reasoning_effort: opts.reasoning_effort ?? null,
         cwd: opts.cwd ?? null,
         prompt: null,
-        agent_done: agentDone,
+        agent_done: true,
         launch_operation_id: opts.launch_operation_id ?? null,
     });
     try {
-        const initial = agentDone
-            ? await sendInitialAgentPrompt(sid, prompt, {
-                wait: waitMode,
-                timeout: opts.timeout ?? undefined,
-                ready_timeout: opts.ready_timeout ?? undefined,
-                screen: opts.screen ?? undefined,
-                lines: opts.lines ?? null,
-            })
-            : await sendInitialPromptWithoutAgentDone(sid, kind, prompt, {
-                ready_timeout: opts.ready_timeout ?? undefined,
-            });
-        return [sid, `${hint}\n${initial}`];
+        const initial = await sendInitialAgentPrompt(sid, prompt, {
+            ready_timeout: opts.ready_timeout ?? undefined,
+        });
+        return [sid, `${hint}\n${initial.text}`, initial.event_cursor];
     }
     catch (e) {
         const code = e instanceof AitermError ? e.code : 1;

package/dist/index.js

@@ -86,27 +86,19 @@ server.registerTool("pty_open", {
     }
 });
 server.registerTool("pty_send", {
-    description: "セッションへテキスト(コマンド)を送る。通常は送信だけ行い、出力は pty_read で取得する。" +
-        "agent_done:true で起動した Claude/Codex/Grok/Composer セッションは wait:'agent_done' で Stop hook まで待てる。" +
-        "managed Claude sessionはturn相関のためwait:'agent_done'を必須とし、通常送信を拒否する。",
+    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}。ポーリング不要）。` +
+        "結果回収は pty_read(agent_transcript:true)、Claude の durable turn は claude_turn を使う。" +
+        "force:true は agent session への手動介入用の素送信。",
     inputSchema: {
         session_id: z.string(),
         text: z
             .string()
-            .describe("送る文字列（コマンド）。UTF-8で最大64KiB"),
-        enter: z.boolean().default(true).describe("末尾で Enter を送る"),
-        wait: z
-            .enum(["none", "agent_done"])
-            .default("none")
-            .describe("none=従来通り送信のみ（managed Claudeでは拒否）。agent_done=agent Stop hook まで待って最終画面を返す"),
-        timeout: z.number().default(600).describe("wait:'agent_done' の最大待ち秒数"),
-        screen: z.boolean().default(true).describe("wait:'agent_done' の返り値を描画済みスクリーンにする"),
-        lines: z.number().int().nullish().describe("wait:'agent_done' で返す末尾 N 行"),
-        operation_id: z
-            .string()
-            .regex(/^sha256:[0-9a-f]{64}$/)
-            .nullish()
-            .describe("Claudeのdurable caller operation ID。wait:'agent_done'時だけ指定し、timeout後の同一結果回収へ使う"),
+            .describe("送る文字列（コマンド／prompt）。UTF-8で最大64KiB"),
+        enter: z.boolean().default(true).describe("末尾で Enter を送る（agent dispatch では常に submit）"),
         mark: z
             .boolean()
             .default(false)
@@ -116,28 +108,59 @@ server.registerTool("pty_send", {
         force: z
             .boolean()
             .default(false)
-            .describe("破壊的コマンドゲートを越える。agent 起動時 prompt の完了待ち中の混入防止ガードも同時に解除する"),
+            .describe("破壊的コマンドゲートを越える。agent session では dispatch せず素送信する（手動介入用）"),
         rtk: z.boolean().default(false).describe("既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）"),
         raw: z.boolean().default(false).describe("送信前サニタイズを無効化"),
     },
-}, async ({ session_id, text, enter, wait, timeout, screen, lines, operation_id, mark, force, rtk, raw }) => {
+    outputSchema: {
+        schema: z.literal("aiterm.pty-send-result.v1"),
+        mode: z.enum(["sent", "agent_dispatch"]),
+        session_id: z.string(),
+        event_cursor: z.number().int().nullable(),
+        launch_id: z.string().nullable(),
+        vendor: z.enum(["claude", "codex", "grok", "composer"]).nullable(),
+    },
+}, async ({ session_id, text, enter, mark, force, rtk, raw }) => {
     try {
-        if (wait === "agent_done") {
-            return ok(await core.sendAndWaitAgentDone(session_id, text, {
-                enter,
-                mark,
-                force,
-                rtk,
-                raw,
-                timeout,
-                screen,
-                lines: lines ?? null,
-                operation_id: operation_id ?? null,
-            }));
+        if (!force && core.isAgentSession(session_id)) {
+            if (enter === false)
+                throw new Error("agent session への dispatch は enter:false と併用できません（手動介入は force:true）");
+            if (mark)
+                throw new Error("agent session への dispatch は mark:true と併用できません");
+            if (rtk)
+                throw new Error("agent session への dispatch は rtk:true と併用できません");
+            const receipt = await core.dispatchAgentTurn(session_id, text, { raw });
+            return {
+                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)",
+                    },
+                ],
+                structuredContent: {
+                    schema: "aiterm.pty-send-result.v1",
+                    mode: "agent_dispatch",
+                    session_id: receipt.session_id,
+                    event_cursor: receipt.event_cursor,
+                    launch_id: receipt.launch_id,
+                    vendor: receipt.vendor,
+                },
+            };
         }
-        if (operation_id != null)
-            throw new Error("operation_idはwait:'agent_done'時だけ指定できます");
-        return ok(core.send(session_id, text, { enter, mark, force, rtk, raw }));
+        const out = core.send(session_id, text, { enter, mark, force, rtk, raw });
+        return {
+            content: [{ type: "text", text: out }],
+            structuredContent: {
+                schema: "aiterm.pty-send-result.v1",
+                mode: "sent",
+                session_id,
+                event_cursor: null,
+                launch_id: null,
+                vendor: null,
+            },
+        };
     }
     catch (e) {
         return fail(e);
@@ -279,7 +302,6 @@ server.registerTool("claude_turn", {
         session_id: z.string(),
         operation_id: z.string().regex(/^sha256:[0-9a-f]{64}$/),
         text: z.string().optional().describe("issueだけに指定するbounded turn本文"),
-        timeout: z.number().min(0).max(3600).optional().describe("issueだけに指定するStop待ち秒数"),
     },
     outputSchema: {
         schema: z.literal("aiterm.claude-operation-result.v1"),
@@ -290,14 +312,13 @@ server.registerTool("claude_turn", {
         raw_output: z.string().nullable(),
         reason: z.enum(["operation_not_found", "result_unknown"]).nullable(),
     },
-}, async ({ action, session_id, operation_id, text, timeout }) => {
+}, async ({ action, session_id, operation_id, text }) => {
     try {
         const result = await core.runClaudeOperation({
             action,
             session_id,
             operation_id,
             text: text ?? undefined,
-            timeout,
         });
         return {
             content: [{ type: "text", text: JSON.stringify(result) }],
@@ -323,68 +344,61 @@ 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}。ポーリング不要）。` +
+    `結果回収は pty_read(agent_transcript:true)。`;
 function registerAgentTool(toolName, kind, desc) {
-    const initialPromptWaitSchema = {};
-    if (kind === "codex" || kind === "claude") {
-        initialPromptWaitSchema.wait = z
-            .enum(["none", "agent_done"])
-            .default("none")
-            .describe("none=従来通り起動/初回prompt送信のみ。agent_done=起動時promptのStop hookまで待つ（agent_done:true必須）");
-        initialPromptWaitSchema.timeout = z.number().default(600).describe("wait:'agent_done' の最大待ち秒数");
-        initialPromptWaitSchema.screen = z.boolean().default(true).describe("wait:'agent_done' の返り値を描画済みスクリーンにする");
-        initialPromptWaitSchema.lines = z.number().int().nullish().describe("wait:'agent_done' で返す末尾 N 行");
-    }
     const correlatedLaunchSchema = {};
     if (kind === "claude") {
         correlatedLaunchSchema.launch_operation_id = z
             .string()
             .regex(/^sha256:[0-9a-f]{64}$/)
             .optional()
-            .describe("promptless managed launchのexact replay相関ID。session_nameとagent_done:trueが必須");
+            .describe("promptless managed launchのexact replay相関ID。session_name必須");
     }
     server.registerTool(toolName, {
         description: desc,
         inputSchema: {
-            prompt: z.string().nullish().describe("起動時に渡す初手プロンプト（任意）。省略で素のTUI起動"),
+            prompt: z.string().nullish().describe("起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る"),
             model: z.string().nullish().describe(agentModelDesc(kind)),
             // grok/composer の effort は対話 TUI で無効（headless 専用）＝core 側が起動前に明示エラーで拒否。
             // codex は CLI 側の値集合が版で変わるため縛らない（core 側も同方針）。
             reasoning_effort: z.string().nullish().describe(agentEffortDesc(kind)),
             cwd: z.string().nullish().describe("作業ディレクトリ（対象リポのルート等・任意）"),
             session_name: z.string().nullish().describe("セッション名（省略で自動採番）"),
-            agent_done: z
-                .boolean()
-                .default(false)
-                .describe("managed Stop hook を有効化し、pty_send(wait:'agent_done') を使えるようにする"),
             ...correlatedLaunchSchema,
-            ...initialPromptWaitSchema,
         },
         outputSchema: {
             schema: z.literal("aiterm.agent-launch-result.v1"),
             provider: z.literal(kind),
             session_id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/),
             managed_completion: z.boolean(),
+            // 起動時 prompt でturnが走っている時だけ非null（additive拡張）。wait_command はそのままホストの
+            // バックグラウンドタスクとして実行できる完了待ちコマンド。
+            event_cursor: z.number().int().nullable(),
+            wait_command: z.string().nullable(),
         },
-    }, async ({ prompt, model, reasoning_effort, cwd, session_name, agent_done, launch_operation_id, wait, timeout, screen, lines }) => {
+    }, async ({ prompt, model, reasoning_effort, cwd, session_name, launch_operation_id }) => {
         try {
-            const [sid, hint] = await core.openAgentWithInitialPrompt(kind, {
+            const [sid, hint, eventCursor] = await core.openAgentWithInitialPrompt(kind, {
                 prompt: prompt ?? undefined,
                 model: model ?? undefined,
                 reasoning_effort: reasoning_effort ?? undefined,
                 cwd: cwd ?? undefined,
                 session_name: session_name ?? undefined,
-                agent_done: agent_done ?? false,
                 launch_operation_id: launch_operation_id ?? undefined,
-                wait: wait ?? "none",
-                timeout,
-                screen,
-                lines,
             });
             const structured = {
                 schema: "aiterm.agent-launch-result.v1",
                 provider: kind,
                 session_id: sid,
-                managed_completion: agent_done ?? false,
+                managed_completion: true,
+                event_cursor: eventCursor,
+                wait_command: eventCursor === null ? null : `aiterm-wait --session ${sid} --cursor ${eventCursor}`,
             };
             return {
                 content: [{ type: "text", text: `session_id: ${sid}\n${hint}` }],
@@ -397,14 +411,22 @@ function registerAgentTool(toolName, kind, desc) {
     });
 }
 registerAgentTool("claude_agent", "claude", "【Claude Code (Anthropic)】の対話エージェントTUIを永続端末に起動する。`claude -p`ではなく、" +
-    "同じ利用者可視sessionへpty_sendで継続入力する。agent_done:trueではisolated settingsのmanaged Stop hookで完了と結果を回収する。");
+    "同じ利用者可視sessionへpty_sendで継続入力する。常にmanaged（isolated settingsのStop hook）で起動する。" +
+    agentCompletionDesc +
+    "Claude の durable turn は claude_turn でも回収できる。");
 registerAgentTool("codex_agent", "codex", "【Codex (OpenAI)】の対話エージェント TUI を永続端末に起動する。実装・レビュー・調査を対話で回す。" +
-    "起動後は pty_read で画面を読み pty_send で操作する。model / reasoning_effort を引数で指定可" +
+    "turn は pty_send で送る（自動で非ブロック dispatch になる）。" +
+    agentCompletionDesc +
+    "model / reasoning_effort を引数で指定可" +
     "（省略時は端末 config／CLI 既定を継承。実効値は起動応答に明示）。");
 registerAgentTool("grok_agent", "grok", "【Grok Build の Grok モデル (既定 grok-4.5)】の対話エージェント TUI を永続端末に起動する。" +
-    "起動後は pty_read/pty_send で対話操作。model を引数で指定可。reasoning_effort は対話 TUI 非対応（指定はエラー）。");
+    "turn は pty_send で送る（自動で非ブロック dispatch になる）。" +
+    agentCompletionDesc +
+    "model を引数で指定可。reasoning_effort は対話 TUI 非対応（指定はエラー）。");
 registerAgentTool("composer_agent", "composer", "【Grok Build の Composer モデル (既定 grok-composer-2.5-fast)】の対話エージェント TUI を永続端末に起動する。" +
-    "起動後は pty_read/pty_send で対話操作。model を引数で指定可。reasoning_effort は非対応（指定はエラー）。");
+    "turn は pty_send で送る（自動で非ブロック dispatch になる）。" +
+    agentCompletionDesc +
+    "model を引数で指定可。reasoning_effort は非対応（指定はエラー）。");
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.15.1",
+  "version": "0.17.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": [