aiterm-mcp 0.9.1 → 0.10.0

package/README.ja.md

@@ -45,11 +45,11 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 ### 2. その端末の中に他のコーディングエージェントを起動する — オーケストレーションの旗艦
 
-同じ primitive が別エージェントの TUI を宿す。3 つの起動ツールが、各ベンダーの対話型コーディングエージェント TUI を新しい永続端末の中に起動し、`session_id` を返す。以後はどのシェルとも同じ `pty_read` / `pty_send` で操作する——出力をトークン削減して読み、次の一手を送る。（TUI は全画面アプリなので `pty_read({ screen: true })` で描画済みの画面が得られる。）`agent_done: true` を付けると hook ベースのターン完了待ちが有効になり、`pty_send({ wait: "agent_done" })` が agent のターン終了後に返る。Codex/Grok/Composer は、各ベンダー CLI が認証済みなら実 smoke 済み。これはベンダー自身の CLI が導入・認証済みであることが必要——[要件](#要件)参照。
+同じ primitive が別エージェントの TUI を宿す。3 つの起動ツールが、各ベンダーの対話型コーディングエージェント TUI を新しい永続端末の中に起動し、`session_id` を返す。以後はどのシェルとも同じ `pty_read` / `pty_send` で操作する——出力をトークン削減して読み、次の一手を送る。（TUI は全画面アプリなので `pty_read({ screen: true })` で描画済みの画面が得られる。）`agent_done: true` を付けると hook ベースのターン完了待ちが有効になり、`pty_send({ wait: "agent_done" })` が agent のターン終了後に返る。`codex_agent` は起動時 `prompt` も待てる——`prompt`、`agent_done:true`、`wait:"agent_done"` を渡すと、まず TUI を起動し、入力欄の ready を待ってから初回 prompt を送り、その初回ターンの Stop hook 後に返る。Codex/Grok/Composer は、各ベンダー CLI が認証済みなら後続 `pty_send(wait:"agent_done")` は実 smoke 済み。Codex の初回 prompt wait も実 smoke 済み。Grok/Composer の初回 prompt wait は post-OAuth smoke が通るまで意図的に未公開。これはベンダー自身の CLI が導入・認証済みであることが必要——[要件](#要件)参照。
 
 ```text
 codex_agent({ session_name: "codex1", cwd: "/repo", agent_done: true,
-              prompt: "port test/legacy.py to vitest" })
+              wait: "agent_done", 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" })
@@ -60,11 +60,11 @@ pty_send("codex1", "also fix the imports it broke", { wait: "agent_done" })
 
 | ツール | 起動するもの | 主な引数 |
 | --- | --- | --- |
-| `codex_agent` | Codex CLI（OpenAI・モデルは CLI の既定） | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?`, `agent_done?` |
+| `codex_agent` | Codex CLI（OpenAI・モデルは CLI の既定） | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
 | `grok_agent` | Grok Build の `grok-build` モデル（xAI） | `prompt?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`）, `cwd?`, `session_name?`, `agent_done?` |
 | `composer_agent` | Grok Build の `grok-composer-2.5-fast` モデル（xAI） | `grok_agent` と同じ |
 
-各ベンダーの CLI が導入・認証済みであること（`codex_agent` は `codex`、Grok 系 2 つは `grok`）。バイナリは `CODEX_BIN` / `GROK_BIN` → `~/.local/bin/codex` / `~/.grok/bin/grok` → `PATH` の順で解決する。前提は **session を作る前に**検証する——`grok_agent` / `composer_agent` は範囲外の `reasoning_effort` を先に弾き（値集合は固定＝`low`/`medium`/`high`/`xhigh`/`max`）、CLI バイナリ不在・実在しない `cwd` は 3 つとも失敗する。前提（`reasoning_effort`・バイナリ・`cwd`）で弾かれた起動は **session の残骸をゼロ**にして返し、起動キーストロークを送れなければ session を畳む。（その先でベンダー CLI が実際に立ち上がったか・認証できたかは aiterm は検証しない——`openAgent` は起動コマンドを送った時点で返る。起動できたかは session を読んで確認する。）（`codex_agent` は Codex の受理値が版で変わるため、`reasoning_effort` を検証せず config override〔`-c model_reasoning_effort=…`〕として Codex CLI へ渡す。）`cwd` は絶対パスで渡す——`~` は展開されない。`agent_done` は launch ごとの managed vendor home を使い、通常の hook file は書き換えない。Codex は managed `CODEX_HOME` に `auth.json` だけを symlink し、`config.toml` はコピーする。Grok/Composer はさらに `GROK_HOME` と `HOME` を隔離し、compat hook/plugin 混入を抑える。一方で Grok OAuth は通常 Grok home の `auth.json` と `auth.json.lock` をセットで共有し、複数セッション間で refresh lock が分裂しないようにする。初回の未 bind `pty_send({ wait: "agent_done" })` は、vendor TUI の入力欄が出るまで待ち、入力受付状態でなければ文字列を送らず送信前エラーにする。`agent_done` は `getuid`・安全な一時ファイル・hard link 検査など POSIX ファイルシステム前提を使うため、対応は Linux / WSL2 / macOS。Windows ネイティブでは core PTY と agent launcher は使えるが、`agent_done` はまだ未対応。
+各ベンダーの CLI が導入・認証済みであること（`codex_agent` は `codex`、Grok 系 2 つは `grok`）。バイナリは `CODEX_BIN` / `GROK_BIN` → `~/.local/bin/codex` / `~/.grok/bin/grok` → `PATH` の順で解決する。前提は **session を作る前に**検証する——`grok_agent` / `composer_agent` は範囲外の `reasoning_effort` を先に弾き（値集合は固定＝`low`/`medium`/`high`/`xhigh`/`max`）、CLI バイナリ不在・実在しない `cwd` は 3 つとも失敗する。前提（`reasoning_effort`・バイナリ・`cwd`）で弾かれた起動は **session の残骸をゼロ**にして返し、起動キーストロークを送れなければ session を畳む。（初回 prompt wait を使わない場合、その先でベンダー CLI が実際に立ち上がったか・認証できたかは aiterm は検証しない——起動できたかは session を読んで確認する。）（`codex_agent` は Codex の受理値が版で変わるため、`reasoning_effort` を検証せず config override〔`-c model_reasoning_effort=…`〕として Codex CLI へ渡す。）`cwd` は絶対パスで渡す——`~` は展開されない。`agent_done` は launch ごとの managed vendor home を使い、通常の hook file は書き換えない。Codex は managed `CODEX_HOME` に `auth.json` だけを symlink し、`config.toml` はコピーする。Grok/Composer はさらに `GROK_HOME` と `HOME` を隔離し、compat hook/plugin 混入を抑える。一方で Grok OAuth は通常 Grok home の `auth.json` と `auth.json.lock` をセットで共有し、複数セッション間で refresh lock が分裂しないようにする。初回の未 bind `pty_send({ wait: "agent_done" })` は、vendor TUI の入力欄が出るまで待ち、入力受付状態でなければ文字列を送らず送信前エラーにする。`codex_agent` launcher の `wait:"agent_done"` も同じく `prompt` と `agent_done:true` が必須。TUI が入力欄 ready にならない場合は prompt を送らず、`initial_prompt=not_sent` として session を調査可能なまま残す。起動時 prompt が `pending`/`sent` の間は、混入防止のため通常 `pty_send` も拒否する。手動介入は `pty_key`、または意図的な `pty_send(..., force:true)` で行う。`agent_done` は `getuid`・安全な一時ファイル・hard link 検査など POSIX ファイルシステム前提を使うため、対応は Linux / WSL2 / macOS。Windows ネイティブでは core PTY と agent launcher は使えるが、`agent_done` はまだ未対応。
 
 **Claude launcher はあえて無い**し、エージェント間のプロトコルも無い: aiterm の役目は、あなたの Claude（や任意の MCP クライアント）が*他の*エージェントに手を伸ばして端末を操作できるようにすること。起動したエージェントは単なるもう 1 本の永続セッションなので、この README の他のすべて（トークン削減読取・完了検出・人の `attach` での監視/介入）がそのまま効く。
 
@@ -219,15 +219,15 @@ aiterm は同じ核心の洞察——端末を出会いの場にする——を
 
 | ツール | 起動するもの | 主な引数 |
 | --- | --- | --- |
-| `codex_agent` | Codex CLI（OpenAI・モデルは CLI の既定） | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?`, `agent_done?` |
+| `codex_agent` | Codex CLI（OpenAI・モデルは CLI の既定） | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
 | `grok_agent` | Grok Build の `grok-build` モデル（xAI） | `prompt?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`）, `cwd?`, `session_name?`, `agent_done?` |
 | `composer_agent` | Grok Build の `grok-composer-2.5-fast` モデル（xAI） | `grok_agent` と同じ |
 
-各ベンダーの CLI が導入・認証済みであること（`codex_agent` は `codex`、Grok 系 2 つは `grok`）。バイナリは `CODEX_BIN` / `GROK_BIN` → `~/.local/bin/codex` / `~/.grok/bin/grok` → `PATH` の順で解決する。前提はセッション作成前に検証し（grok/composer は範囲外の `reasoning_effort` を弾く。CLI 不在・実在しない `cwd` は 3 つとも失敗）、起動に失敗してもセッションの残骸は残さない。詳細は [その端末の中に他のコーディングエージェントを起動する](#2-その端末の中に他のコーディングエージェントを起動する--オーケストレーションの旗艦)。`cwd` は絶対パスで渡す——`~` は展開されない。`agent_done` は hook-backed で、Codex/Grok/Composer は Linux/WSL2/macOS で実 smoke 済み。Windows ネイティブでは agent launcher は使えるが `agent_done` はまだ未対応。Codex の managed `CODEX_HOME` は `auth.json` だけを symlink し、`config.toml` をコピーし、`hooks.json` は aiterm が所有する。初回の未 bind agent send では `pty_send({ wait:"agent_done" })` が vendor TUI の入力欄を待ち、未 ready なら送信前エラーにする。Grok OAuth mode では hook/config 隔離は launch ごとに維持しつつ、通常 Grok home の `auth.json` と `auth.json.lock` をセットで共有する。OAuth auth 不在ならセッション残骸なしで失敗する。
+各ベンダーの CLI が導入・認証済みであること（`codex_agent` は `codex`、Grok 系 2 つは `grok`）。バイナリは `CODEX_BIN` / `GROK_BIN` → `~/.local/bin/codex` / `~/.grok/bin/grok` → `PATH` の順で解決する。前提はセッション作成前に検証し（grok/composer は範囲外の `reasoning_effort` を弾く。CLI 不在・実在しない `cwd` は 3 つとも失敗）、起動に失敗してもセッションの残骸は残さない。詳細は [その端末の中に他のコーディングエージェントを起動する](#2-その端末の中に他のコーディングエージェントを起動する--オーケストレーションの旗艦)。`cwd` は絶対パスで渡す——`~` は展開されない。`agent_done` は hook-backed で、Codex/Grok/Composer は Linux/WSL2/macOS の後続 `pty_send(wait:"agent_done")` で実 smoke 済み。Codex は launcher の `prompt + wait:"agent_done"` も実 smoke 済み。Windows ネイティブでは agent launcher は使えるが `agent_done` はまだ未対応。Codex の managed `CODEX_HOME` は `auth.json` だけを symlink し、`config.toml` をコピーし、`hooks.json` は aiterm が所有する。初回の未 bind agent send では `pty_send({ wait:"agent_done" })` が vendor TUI の入力欄を待ち、未 ready なら送信前エラーにする。`codex_agent` launcher の `wait:"agent_done"` は `prompt` と `agent_done:true` が必須で、TUI ready 後にだけ初回 prompt を送る。入力欄 ready にならない場合は prompt を送らず、`initial_prompt=not_sent` を返して session を残す。Grok OAuth mode では hook/config 隔離は launch ごとに維持しつつ、通常 Grok home の `auth.json` と `auth.json.lock` をセットで共有する。OAuth auth 不在ならセッション残骸なしで失敗する。
 
 ### 完了検出（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 を待ってターン境界後の画面を返す。送信前 ready 失敗は MCP エラー、送信後 timeout は `is_complete=False via agent_timeout` で返り、成功扱いしない。完結した 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_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` が付く。
 
 ### トークン削減
 

package/README.md

@@ -45,11 +45,11 @@ 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. Three launchers each start one vendor's interactive coding-agent TUI inside a fresh persistent terminal and return a `session_id`. 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. Codex/Grok/Composer all have passing live smokes when their vendor CLI is authenticated. This needs the vendor's own CLI installed and authenticated — see [Requirements](#requirements).
+The same primitive hosts another agent's TUI. Three launchers each start one vendor's interactive coding-agent TUI inside a fresh persistent terminal and return a `session_id`. 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. `codex_agent` can additionally wait for its 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 all have passing live smokes for follow-up `pty_send(wait:"agent_done")` when their vendor CLI is authenticated; Codex initial-prompt wait is also live-smoked. 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).
 
 ```text
 codex_agent({ session_name: "codex1", cwd: "/repo", agent_done: true,
-              prompt: "port test/legacy.py to vitest" })
+              wait: "agent_done", 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" })
@@ -60,11 +60,11 @@ One call per model, so the tool name itself tells you which model you get:
 
 | Tool | Launches | Key args |
 | --- | --- | --- |
-| `codex_agent` | Codex CLI (OpenAI; the CLI's default model) | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?`, `agent_done?` |
+| `codex_agent` | Codex CLI (OpenAI; the CLI's default model) | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
 | `grok_agent` | Grok Build, model `grok-build` (xAI) | `prompt?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`), `cwd?`, `session_name?`, `agent_done?` |
 | `composer_agent` | Grok Build, model `grok-composer-2.5-fast` (xAI) | same as `grok_agent` |
 
-The vendor CLI must be installed and authenticated (`codex` for `codex_agent`; `grok` for both Grok tools). aiterm resolves the binary via `CODEX_BIN` / `GROK_BIN`, then `~/.local/bin/codex` / `~/.grok/bin/grok`, then `PATH`. Prerequisites are checked **before** a session exists: for `grok_agent` / `composer_agent` an out-of-range `reasoning_effort` is rejected up front (the value set is fixed — `low`/`medium`/`high`/`xhigh`/`max`); a missing CLI binary or a nonexistent `cwd` fails for all three. A rejected launch — bad `reasoning_effort`, an unresolvable binary, or a nonexistent `cwd` — leaves **zero leftover session** behind, and if the launch keystroke itself can't be delivered aiterm tears the session down. (aiterm does *not* then verify the vendor CLI actually started or authenticated — `openAgent` returns once the launch command is sent; read the session to confirm the agent came up.) (`codex_agent` forwards `reasoning_effort` to the Codex CLI as a config override — `-c model_reasoning_effort=…` — rather than validating it, since Codex's accepted values vary by version.) Pass an absolute path for `cwd` — `~` is not expanded. `agent_done` uses launch-local managed vendor homes and does not edit your normal hook files; Codex links only `auth.json` and copies `config.toml` into its managed `CODEX_HOME`, while Grok/Composer additionally isolate `GROK_HOME` and `HOME` to suppress compat hook/plugin contamination. Grok OAuth uses the normal Grok home's `auth.json` and `auth.json.lock` as a pair so refresh locking does not split across sessions. Before the first unbound `pty_send({ wait: "agent_done" })`, aiterm waits for the vendor TUI's input prompt and fails before sending if the prompt is not ready, avoiding dropped startup input. `agent_done` currently requires POSIX filesystem semantics (`getuid`, secure temp files, hard-link checks), so it is supported on Linux, WSL2, and macOS; native Windows can still use the core PTY tools and agent launchers without `agent_done`.
+The vendor CLI must be installed and authenticated (`codex` for `codex_agent`; `grok` for both Grok tools). aiterm resolves the binary via `CODEX_BIN` / `GROK_BIN`, then `~/.local/bin/codex` / `~/.grok/bin/grok`, then `PATH`. Prerequisites are checked **before** a session exists: for `grok_agent` / `composer_agent` an out-of-range `reasoning_effort` is rejected up front (the value set is fixed — `low`/`medium`/`high`/`xhigh`/`max`); a missing CLI binary or a nonexistent `cwd` fails for all three. A rejected launch — bad `reasoning_effort`, an unresolvable binary, or a nonexistent `cwd` — leaves **zero leftover session** behind, and if the launch keystroke itself can't be delivered aiterm tears the session down. (Without an initial prompt wait, aiterm does *not* then verify the vendor CLI actually started or authenticated — read the session to confirm the agent came up.) (`codex_agent` forwards `reasoning_effort` to the Codex CLI as a config override — `-c model_reasoning_effort=…` — rather than validating it, since Codex's accepted values vary by version.) Pass an absolute path for `cwd` — `~` is not expanded. `agent_done` uses launch-local managed vendor homes and does not edit your normal hook files; Codex links only `auth.json` and copies `config.toml` into its managed `CODEX_HOME`, while Grok/Composer additionally isolate `GROK_HOME` and `HOME` to suppress compat hook/plugin contamination. Grok OAuth uses the normal Grok home's `auth.json` and `auth.json.lock` as a pair so refresh locking does not split across sessions. Before the first unbound `pty_send({ wait: "agent_done" })`, aiterm waits for the vendor TUI's input prompt and fails before sending if the prompt is not ready, avoiding dropped startup input. `codex_agent` launcher `wait:"agent_done"` has the same requirement and is only valid with both `prompt` and `agent_done:true`; if the TUI is not ready, the prompt is not sent and the session is left inspectable with `initial_prompt=not_sent`. While an initial prompt is still `pending`/`sent`, ordinary `pty_send` is rejected to prevent mixed input; manual takeover can still use `pty_key`, or `pty_send(..., force:true)` if you intentionally want to type into that live TUI. `agent_done` currently requires POSIX filesystem semantics (`getuid`, secure temp files, hard-link checks), so it is supported on Linux, WSL2, and macOS; native Windows can still use the core PTY tools and agent launchers without `agent_done`.
 
 There is deliberately **no Claude launcher**, and no protocol between the agents: aiterm's job is to let your Claude (or any MCP client) reach for *other* agents and drive their terminals. Because a launched agent is just another persistent session, everything else in this README applies to it: token-reduced reads, completion detection, and a human `attach` to watch or take over.
 
@@ -219,15 +219,15 @@ Each launcher starts a specific vendor's interactive coding-agent TUI inside a f
 
 | Tool | Launches | Key args |
 | --- | --- | --- |
-| `codex_agent` | Codex CLI (OpenAI; the CLI's default model) | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?`, `agent_done?` |
+| `codex_agent` | Codex CLI (OpenAI; the CLI's default model) | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?`, `agent_done?`, `wait?`, `timeout?`, `screen?`, `lines?` |
 | `grok_agent` | Grok Build, model `grok-build` (xAI) | `prompt?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`), `cwd?`, `session_name?`, `agent_done?` |
 | `composer_agent` | Grok Build, model `grok-composer-2.5-fast` (xAI) | same as `grok_agent` |
 
-The vendor CLI must be installed and authenticated (`codex` for `codex_agent`; `grok` for both Grok tools). aiterm resolves the binary via `CODEX_BIN` / `GROK_BIN`, then `~/.local/bin/codex` / `~/.grok/bin/grok`, then `PATH`. Prerequisites are validated before a session is created (grok/composer reject an out-of-range `reasoning_effort`; a missing CLI or a nonexistent `cwd` fails for all three), and a failed launch leaves no session behind. Full details under [Launch other coding agents into that terminal](#2-launch-other-coding-agents-into-that-terminal--the-orchestration-flagship). Pass an absolute path for `cwd` — `~` is not expanded. `agent_done` is hook-backed for agent launchers; Codex/Grok/Composer have passing live smokes on Linux/WSL2/macOS; native Windows can launch agents but `agent_done` is not supported yet. Codex managed `CODEX_HOME` links only `auth.json`, copies `config.toml`, and owns its own `hooks.json`. Before the first unbound agent send, `pty_send({ wait:"agent_done" })` waits for the vendor TUI input prompt and fails before sending if it is not ready. In Grok OAuth mode, aiterm keeps hook/config isolation per launch but shares both `auth.json` and `auth.json.lock` with the normal Grok home; missing OAuth auth fails without leaving a session behind.
+The vendor CLI must be installed and authenticated (`codex` for `codex_agent`; `grok` for both Grok tools). aiterm resolves the binary via `CODEX_BIN` / `GROK_BIN`, then `~/.local/bin/codex` / `~/.grok/bin/grok`, then `PATH`. Prerequisites are validated before a session is created (grok/composer reject an out-of-range `reasoning_effort`; a missing CLI or a nonexistent `cwd` fails for all three), and a failed launch leaves no session behind. Full details under [Launch other coding agents into that terminal](#2-launch-other-coding-agents-into-that-terminal--the-orchestration-flagship). Pass an absolute path for `cwd` — `~` is not expanded. `agent_done` is hook-backed for agent launchers; Codex/Grok/Composer have passing live smokes on Linux/WSL2/macOS for follow-up `pty_send(wait:"agent_done")`, and Codex has a live smoke for launcher `prompt + wait:"agent_done"`. Native Windows can launch agents but `agent_done` is not supported yet. Codex managed `CODEX_HOME` links only `auth.json`, copies `config.toml`, and owns its own `hooks.json`. Before the first unbound agent send, `pty_send({ wait:"agent_done" })` waits for the vendor TUI input prompt and fails before sending if it is not ready. `codex_agent` launcher `wait:"agent_done"` requires `prompt` plus `agent_done:true`; it sends the initial prompt only after the TUI is ready, and returns `initial_prompt=not_sent` without sending if the TUI is blocked before input. In Grok OAuth mode, aiterm keeps hook/config isolation per launch but shares both `auth.json` and `auth.json.lock` with the normal Grok home; missing OAuth auth fails without leaving a session behind.
 
 ### 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; pre-send readiness failures are MCP errors and timeouts after sending are reported as `is_complete=False via agent_timeout`, not as success. 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. 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; `codex_agent` launcher `wait:"agent_done"` does 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. 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`.
 
 ### Token reduction
 

package/dist/core.js

@@ -711,6 +711,7 @@ export function send(name, text, o = {}) {
     const enter = o.enter ?? true;
     if (!sessionExists(name))
         throw new AitermError(`session '${name}' が無い（open してください）`, 2);
+    assertInitialPromptNotPendingForSend(name, !!o.force);
     if (!o.raw) {
         text = text.replace(PASTE_MARKERS_RE, "").replace(ANSI_RE, "").replace(CTRL_RE, "");
     }
@@ -812,7 +813,7 @@ export async function readOutput(name, o = {}) {
         if (o.raw)
             return rawTxt;
         const [body, meta] = reduceOutput(rawTxt, name, true);
-        return body + "\n" + meta + (status ? completionSuffix(status) : "");
+        return body + "\n" + meta + agentReadMetadataSuffix(name, rawTxt) + (status ? completionSuffix(status) : "");
     }
     // ログ全体を毎回メモリに載せず、必要な範囲だけ fd で読む（B7）。size は statSync で取る。
     let size = 0;
@@ -892,17 +893,19 @@ export async function readOutput(name, o = {}) {
             const [reduced, rname] = rtk.reduce(cmd, framed);
             if (reduced !== null) {
                 const meta = `[aiterm ${name}: rtk:${rname} 適用 / ~${estimateTokens(reduced)} tok (raw ~${estimateTokens(text)} tok)]`;
+                const agentMeta = agentReadMetadataSuffix(name);
                 if (status)
-                    return reduced + "\n" + meta + completionSuffix(status);
-                return reduced + "\n" + meta;
+                    return reduced + "\n" + meta + agentMeta + completionSuffix(status);
+                return reduced + "\n" + meta + agentMeta;
             }
         }
         // reducer 非該当 → 汎用削減へフォールバック
     }
     const [body, meta] = reduceOutput(text, name, !o.range);
+    const agentMeta = agentReadMetadataSuffix(name);
     if (status)
-        return body + "\n" + meta + completionSuffix(status);
-    return body + "\n" + meta;
+        return body + "\n" + meta + agentMeta + completionSuffix(status);
+    return body + "\n" + meta + agentMeta;
 }
 export function listSessions() {
     const r = tmux("list-sessions", "-F", "#{session_name}\t#{pane_current_command}\t#{?session_attached,attached,detached}\t#{window_width}x#{window_height}");
@@ -975,6 +978,13 @@ export function killAll() {
 }
 const DEFAULT_AGENT_DONE_TIMEOUT = 600;
 const agentWaitLocks = new Set();
+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");
 }
@@ -1242,6 +1252,25 @@ function createManagedGrokHome(name, launchId) {
 function writeAgentMetadata(meta) {
     writeJson0600(agentMetadataPath(meta.aiterm_session, meta.launch_id), meta);
 }
+function normalizeInitialPromptState(v) {
+    if (v === true)
+        return "pending";
+    if (v === false || v == null)
+        return "none";
+    if (v === "none" ||
+        v === "not_sent" ||
+        v === "sent" ||
+        v === "pending" ||
+        v === "done" ||
+        v === "failed") {
+        return v;
+    }
+    return "none";
+}
+function setInitialPromptState(meta, state) {
+    meta.initial_prompt = state;
+    writeAgentMetadata(meta);
+}
 function acquireAgentWaitFileLock(meta) {
     const p = agentWaitLockPath(meta.aiterm_session, meta.launch_id);
     const nofollow = fs.constants.O_NOFOLLOW ?? 0;
@@ -1364,7 +1393,7 @@ function loadAgentMetadata(name) {
             created_at: typeof m.created_at === "string" ? m.created_at : "",
             cwd: typeof m.cwd === "string" ? m.cwd : null,
             vendor_session_id: typeof m.vendor_session_id === "string" ? m.vendor_session_id : null,
-            initial_prompt: m.initial_prompt === true,
+            initial_prompt: normalizeInitialPromptState(m.initial_prompt),
             hook_route: "managed_codex_home",
             node_platform: process.platform,
             codex_home: expectedHome,
@@ -1383,7 +1412,7 @@ function loadAgentMetadata(name) {
         created_at: typeof m.created_at === "string" ? m.created_at : "",
         cwd: typeof m.cwd === "string" ? m.cwd : null,
         vendor_session_id: typeof m.vendor_session_id === "string" ? m.vendor_session_id : null,
-        initial_prompt: m.initial_prompt === true,
+        initial_prompt: normalizeInitialPromptState(m.initial_prompt),
         hook_route: "managed_grok_home",
         node_platform: process.platform,
         grok_home: expectedGrokHome,
@@ -1461,8 +1490,12 @@ function bindAgentVendorSession(meta, ev) {
     }
 }
 function bindCompletedInitialPrompt(meta) {
-    if (!meta.initial_prompt || meta.vendor_session_id)
+    if (meta.initial_prompt !== "pending" && meta.initial_prompt !== "sent")
         return;
+    if (meta.vendor_session_id) {
+        setInitialPromptState(meta, "done");
+        return;
+    }
     const size = safeStatSize(meta.event_file);
     if (size === 0) {
         throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了待ちです。初回応答完了後に再度 pty_send(wait:"agent_done") してください。`, 2);
@@ -1480,8 +1513,69 @@ function bindCompletedInitialPrompt(meta) {
         throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了 event をまだ確認できません。初回応答完了後に再度 pty_send(wait:"agent_done") してください。${malformed}${partial}`, 2);
     }
     bindAgentVendorSession(meta, scanned.event);
-    meta.initial_prompt = false;
-    writeAgentMetadata(meta);
+    setInitialPromptState(meta, "done");
+}
+function tryLoadAgentMetadata(name) {
+    try {
+        return loadAgentMetadata(name);
+    }
+    catch {
+        return null;
+    }
+}
+function latestAgentDoneEvent(meta) {
+    const size = safeStatSize(meta.event_file);
+    if (size === 0 || size > AGENT_EVENT_MAX_BYTES)
+        return null;
+    const text = readFileRange(meta.event_file, 0, size).toString("utf8");
+    let latest = null;
+    for (const line of text.split("\n")) {
+        if (!line.trim() || Buffer.byteLength(line, "utf8") > 64 * 1024)
+            continue;
+        const parsed = parseAgentDoneEvent(line, meta);
+        if (parsed.event)
+            latest = parsed.event;
+    }
+    return latest;
+}
+function inferAgentFrontend(name, meta, screen) {
+    const fg = paneCurrentCommand(name);
+    const view = screen ?? captureScreen(name, AGENT_TUI_READY_LINES);
+    if (isAgentTuiReady(meta.kind, view))
+        return "agent_tui";
+    if (SHELLS.has(fg)) {
+        if (/(^|\n)\s*>\s/.test(view))
+            return "shell_continuation";
+        return "shell";
+    }
+    return "unknown";
+}
+function agentReadMetadataSuffix(name, screen) {
+    const meta = tryLoadAgentMetadata(name);
+    if (!meta)
+        return "";
+    const ev = latestAgentDoneEvent(meta);
+    const bits = [
+        "agent",
+        `vendor=${meta.kind}`,
+        `initial_prompt=${meta.initial_prompt}`,
+        `agent_event_seen=${ev ? "true" : "false"}`,
+        "completion_attribution=none",
+        ev?.turn_id ? `last_turn_id=${ev.turn_id}` : null,
+        `frontend=${inferAgentFrontend(name, meta, screen)}`,
+    ].filter(Boolean);
+    return ` [${bits.join(" ")}]`;
+}
+function assertInitialPromptNotPendingForSend(name, force) {
+    if (force)
+        return;
+    const meta = tryLoadAgentMetadata(name);
+    if (!meta)
+        return;
+    if (meta.initial_prompt !== "pending" && meta.initial_prompt !== "sent")
+        return;
+    throw new AitermError(`agent session '${name}' は起動時 prompt の完了待ちです。通常 pty_send は混入防止のため送信しません。` +
+        `完了後に pty_send(wait:"agent_done") するか、手動介入が必要な場合だけ force:true を明示してください。`, 2);
 }
 async function waitAgentDoneEvent(meta, startOffset, timeout) {
     const deadline = performance.now() + timeout * 1000;
@@ -1560,6 +1654,9 @@ async function waitAgentTuiReadyImpl(kind, sample, sleepFn, opts = {}) {
 async function waitAgentTuiReady(name, meta, timeoutMs = AGENT_TUI_READY_TIMEOUT_MS) {
     return waitAgentTuiReadyImpl(meta.kind, () => captureScreen(name, AGENT_TUI_READY_LINES), sleep, { timeoutMs });
 }
+async function waitAgentTuiReadyByKind(name, kind, timeoutMs = AGENT_TUI_READY_TIMEOUT_MS) {
+    return waitAgentTuiReadyImpl(kind, () => captureScreen(name, AGENT_TUI_READY_LINES), sleep, { timeoutMs });
+}
 async function settleAgentDoneScreenImpl(sample, sleepFn, opts = {}) {
     const minDelayMs = opts.minDelayMs ?? AGENT_DONE_SETTLE_MIN_MS;
     const pollMs = opts.pollMs ?? AGENT_DONE_SCREEN_SETTLE_POLL_MS;
@@ -1616,6 +1713,76 @@ export async function __testWaitAgentTuiReady(kind, samples, opts = {}) {
     }, opts);
     return { ...result, sleeps };
 }
+async function sendAgentPromptText(name, text) {
+    send(name, text, {
+        enter: false,
+        force: true,
+        raw: false,
+        mark: false,
+        rtk: false,
+    });
+    await sleep(AGENT_SUBMIT_DELAY_MS);
+    sendKey(name, "Enter");
+}
+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);
+    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 {
+            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");
+        }
+        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]" : "");
+    }
+    finally {
+        agentWaitLocks.delete(name);
+        releaseFileLock();
+    }
+}
 export async function sendAndWaitAgentDone(name, text, o = {}) {
     assertSessionName(name);
     if (o.enter === false)
@@ -1811,8 +1978,8 @@ export function openAgent(kind, opts = {}) {
     try {
         const meta = agentDone
             ? kind === "codex"
-                ? createCodexAgentMetadata(sid, cwd, !!opts.prompt)
-                : createGrokAgentMetadata(kind, sid, cwd, !!opts.prompt)
+                ? createCodexAgentMetadata(sid, cwd, opts.prompt ? "pending" : "none")
+                : createGrokAgentMetadata(kind, sid, cwd, opts.prompt ? "pending" : "none")
             : null;
         const cmd = buildAgentCmd(kind, binForCmd, effort, opts.prompt ?? null, meta);
         const envPrefix = agentEnvPrefix(meta, sid);
@@ -1841,3 +2008,60 @@ 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 (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") {
+        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);
+    }
+    const [sid, hint] = openAgent(kind, {
+        session_name: opts.session_name ?? null,
+        reasoning_effort: opts.reasoning_effort ?? null,
+        cwd: opts.cwd ?? null,
+        prompt: null,
+        agent_done: agentDone,
+    });
+    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}`];
+    }
+    catch (e) {
+        const code = e instanceof AitermError ? e.code : 1;
+        const message = e instanceof Error ? e.message : String(e);
+        throw new AitermError(`session_id: ${sid}\n` +
+            `起動後の初回 prompt 処理で失敗しました。session は調査/復旧用に残しています。\n${message}`, code);
+    }
+}

package/dist/index.js

@@ -184,6 +184,16 @@ const agentEffortDesc = (grokLike) => "reasoning effort（思考レベル）。"
     (grokLike ? "low/medium/high/xhigh/max" : "low/medium/high 等") +
     "。省略時は CLI 既定。";
 function registerAgentTool(toolName, kind, desc, grokLike) {
+    const initialPromptWaitSchema = {};
+    if (kind === "codex") {
+        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 行");
+    }
     server.registerTool(toolName, {
         description: desc,
         inputSchema: {
@@ -199,15 +209,20 @@ function registerAgentTool(toolName, kind, desc, grokLike) {
                 .boolean()
                 .default(false)
                 .describe("managed Stop hook を有効化し、pty_send(wait:'agent_done') を使えるようにする"),
+            ...initialPromptWaitSchema,
         },
-    }, async ({ prompt, reasoning_effort, cwd, session_name, agent_done }) => {
+    }, async ({ prompt, reasoning_effort, cwd, session_name, agent_done, wait, timeout, screen, lines }) => {
         try {
-            const [sid, hint] = core.openAgent(kind, {
+            const [sid, hint] = await core.openAgentWithInitialPrompt(kind, {
                 prompt: prompt ?? undefined,
                 reasoning_effort: reasoning_effort ?? undefined,
                 cwd: cwd ?? undefined,
                 session_name: session_name ?? undefined,
                 agent_done: agent_done ?? false,
+                wait: wait ?? "none",
+                timeout,
+                screen,
+                lines,
             });
             return ok(`session_id: ${sid}\n${hint}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.9.1",
+  "version": "0.10.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 Codex/Grok/Composer agent TUIs in a persistent terminal. Token-reducing reads.",
   "keywords": [