aiterm-mcp 0.9.1 → 0.11.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?` |
-| `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` |
+| `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?` |
 
-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: empty `model` values and any `reasoning_effort` for `grok_agent` / `composer_agent` are rejected up front; a missing CLI binary or a nonexistent `cwd` fails for all three. A rejected launch 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 `model` as `-m` and `reasoning_effort` as `-c model_reasoning_effort=…` without validating the effort value, since Codex's accepted values vary by version. Grok/Composer reject `reasoning_effort`: Grok CLI `--effort` is only for headless `grok -p`, and the interactive TUI ignores it with a warning. Pass an absolute path for `cwd` — `~` is not expanded. Codex launch responses always report the effective model/effort and where each came from (argument, terminal-config inheritance, or CLI default), with an explicit warning when the effective effort is `ultra` (max reasoning plus proactive automatic delegation). `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` — explicitly passed `model` / `reasoning_effort` values also rewrite the matching top-level pins in that copy, so terminal pins don't silently leak into the child — 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?` |
-| `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` |
+| `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?` |
 
-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: empty `model` and any Grok/Composer `reasoning_effort` are errors, while a missing CLI or nonexistent `cwd` fails for all three; a failed launch leaves no session behind. Codex forwards `model` as `-m` and `reasoning_effort` as `-c model_reasoning_effort=…`; Grok/Composer reject effort because interactive TUI does not support it (Grok CLI `--effort` is headless-only). 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");
 }
@@ -1040,7 +1050,61 @@ function createEmpty0600NoFollow(p) {
 function realCodexHome() {
     return process.env.CODEX_HOME || path.join(process.env.HOME ?? os.homedir(), ".codex");
 }
-function createManagedCodexHome(name, launchId) {
+// 引数で model/effort を渡された時は managed config のピンを上書きする（端末 config の
+// model/model_reasoning_effort ピン——例: effort=ultra は proactive 自動委譲 ON——が対話子へ
+// 黙って波及するのを防ぐ）。TOML の top-level キーは最初のテーブルヘッダより前にしか置けないため、
+// 既存行の除去は先頭領域に限定し、上書き行はファイル先頭へ置く。
+function applyCodexConfigOverrides(body, overrides) {
+    const lines = [];
+    if (overrides.model)
+        lines.push(`model = ${JSON.stringify(overrides.model)}`);
+    if (overrides.effort)
+        lines.push(`model_reasoning_effort = ${JSON.stringify(overrides.effort)}`);
+    if (!lines.length)
+        return body;
+    if (body == null)
+        return lines.join("\n") + "\n";
+    const rows = body.split(/\r?\n/);
+    let firstTable = rows.findIndex((l) => /^\s*\[/.test(l));
+    if (firstTable === -1)
+        firstTable = rows.length;
+    const head = rows.slice(0, firstTable).filter((l) => {
+        if (overrides.model && /^\s*model\s*=/.test(l))
+            return false;
+        if (overrides.effort && /^\s*model_reasoning_effort\s*=/.test(l))
+            return false;
+        return true;
+    });
+    let out = [...lines, ...head, ...rows.slice(firstTable)].join("\n");
+    if (!out.endsWith("\n"))
+        out += "\n";
+    return out;
+}
+function readCodexConfigPins(configPath) {
+    let body;
+    try {
+        body = fs.readFileSync(configPath, "utf8");
+    }
+    catch {
+        return { model: { present: false, value: null }, effort: { present: false, value: null } };
+    }
+    const rows = body.split(/\r?\n/);
+    let firstTable = rows.findIndex((l) => /^\s*\[/.test(l));
+    if (firstTable === -1)
+        firstTable = rows.length;
+    const pick = (key) => {
+        for (const l of rows.slice(0, firstTable)) {
+            const m = l.match(new RegExp(`^\\s*${key}\\s*=\\s*(.*)$`));
+            if (m) {
+                const v = m[1].trim().match(/^"([^"\\]*)"\s*(?:#.*)?$/);
+                return { present: true, value: v ? v[1] : null };
+            }
+        }
+        return { present: false, value: null };
+    };
+    return { model: pick("model"), effort: pick("model_reasoning_effort") };
+}
+function createManagedCodexHome(name, launchId, overrides = {}) {
     const srcHome = realCodexHome();
     let srcSt;
     try {
@@ -1068,17 +1132,22 @@ function createManagedCodexHome(name, launchId) {
     }
     fs.symlinkSync(authSrc, path.join(managedHome, "auth.json"));
     const configSrc = path.join(srcHome, "config.toml");
+    let configBody = null;
     try {
         const st = fs.statSync(configSrc);
-        if (st.isFile()) {
-            fs.copyFileSync(configSrc, path.join(managedHome, "config.toml"));
-            fs.chmodSync(path.join(managedHome, "config.toml"), 0o600);
-        }
+        if (st.isFile())
+            configBody = fs.readFileSync(configSrc, "utf8");
     }
     catch (e) {
         if (e.code !== "ENOENT")
             throw e;
     }
+    const configOut = applyCodexConfigOverrides(configBody, overrides);
+    if (configOut != null) {
+        const configDst = path.join(managedHome, "config.toml");
+        fs.writeFileSync(configDst, configOut, { mode: 0o600 });
+        fs.chmodSync(configDst, 0o600);
+    }
     const hookScript = codexHookScriptPath();
     if (!fs.existsSync(hookScript)) {
         throw new AitermError(`Codex Stop hook wrapper が見つかりません。npm run build を実行してください: ${hookScript}`, 2);
@@ -1242,6 +1311,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;
@@ -1278,11 +1366,11 @@ function acquireAgentWaitFileLock(meta) {
         }
     };
 }
-function createCodexAgentMetadata(name, cwd, initialPrompt) {
+function createCodexAgentMetadata(name, cwd, initialPrompt, overrides = {}) {
     const launchId = randomBytes(16).toString("hex");
     const eventFile = agentEventPath(name, launchId);
     createEmpty0600NoFollow(eventFile);
-    const codexHome = createManagedCodexHome(name, launchId);
+    const codexHome = createManagedCodexHome(name, launchId, overrides);
     const meta = {
         kind: "codex",
         aiterm_session: name,
@@ -1364,7 +1452,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 +1471,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 +1549,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 +1572,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 +1713,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 +1772,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)
@@ -1701,23 +1927,31 @@ function resolveAgentBin(kind) {
 function shq(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
-function buildAgentCmd(kind, bin, effort, prompt, meta = null) {
+// grok CLI はモデル未指定だと端末側 default に従うため、ツール契約として既定 slug を固定する。
+// codex は既定 slug を持たず端末 config／CLI 既定に委ねる（起動応答で実効値を報告する）。
+const GROK_MODEL_DEFAULTS = {
+    grok: "grok-4.5",
+    composer: "grok-composer-2.5-fast",
+};
+function buildAgentCmd(kind, bin, model, effort, prompt, meta = null) {
     const parts = [shq(bin)];
     if (kind === "codex") {
         if (meta?.kind === "codex")
             parts.push("--dangerously-bypass-hook-trust");
-        // codex は config override で reasoning effort（例: low/medium/high）を渡す。
+        // model/effort は CLI 引数で明示（config 継承より優先）。agent_done 時は managed home 側
+        // config.toml も同値で上書き済み（applyCodexConfigOverrides）。
+        if (model)
+            parts.push("-m", shq(model));
         if (effort)
             parts.push("-c", `model_reasoning_effort=${shq(effort)}`);
     }
     else {
-        // grok / composer は同じ grok CLI をモデル違いで起動。effort は low/medium/high/xhigh/max。
+        // grok / composer は同じ grok CLI をモデル違いで起動。--effort は headless（grok -p）専用で
+        // 対話 TUI では警告の上無視されるため渡さない（openAgent が指定を事前拒否する）。
         parts.push("--no-auto-update");
         if (meta?.kind === "grok" || meta?.kind === "composer")
             parts.push("--no-alt-screen");
-        parts.push("--model", kind === "composer" ? "grok-composer-2.5-fast" : "grok-build");
-        if (effort)
-            parts.push("--effort", shq(effort));
+        parts.push("--model", shq(model ?? GROK_MODEL_DEFAULTS[kind]));
         if ((meta?.kind === "grok" || meta?.kind === "composer") && prompt)
             parts.push("--verbatim");
     }
@@ -1762,15 +1996,53 @@ function agentLabel(kind) {
             ? "Grok Build(Grok)"
             : "Codex";
 }
-// grok CLI の --effort が受ける値集合（codex は CLI 側の値集合が版で変わるため縛らない）。
-const GROK_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+// 起動応答にモデル/effort の実効値と出所を明示する。codex は端末 config のピン（model /
+// model_reasoning_effort）が対話子へ波及する構造のため、引数・端末config継承・CLI既定の
+// どれで起動したかを起動時点で可視化し、実効 effort=ultra は proactive 自動委譲 ON を警告する。
+function buildAgentLaunchNote(kind, model, effort, meta) {
+    if (kind !== "codex") {
+        return (`起動設定: model=${model ?? GROK_MODEL_DEFAULTS[kind]}（${model ? "引数" : "ツール既定"}）。` +
+            "reasoning effort は対話 TUI 非対応＝未指定で起動。");
+    }
+    const configPath = meta?.kind === "codex" && meta.codex_home
+        ? path.join(meta.codex_home, "config.toml")
+        : path.join(realCodexHome(), "config.toml");
+    const pins = readCodexConfigPins(configPath);
+    const describePin = (arg, pin) => arg
+        ? `${arg}（引数）`
+        : pin.present
+            ? pin.value
+                ? `${pin.value}（端末config継承）`
+                : "端末config継承（値未解析）"
+            : "CLI既定";
+    const effectiveEffort = effort ?? (pins.effort.present ? pins.effort.value : null);
+    return (`起動設定: model=${describePin(model, pins.model)} effort=${describePin(effort, pins.effort)}。` +
+        (effectiveEffort === "ultra"
+            ? "⚠ effort=ultra は max 推論＋proactive 自動委譲 ON（子エージェント自動生成・使用量急増に注意）。"
+            : ""));
+}
 export function openAgent(kind, opts = {}) {
     const label = agentLabel(kind);
     // 前提検証は session を作る前に全部済ませる（失敗の残骸 session を作らない）。
-    // effort → bin → cwd の順: effort 検証は CLI 不在の端末でも同じ結果になる（テスト可能性）。
+    // model/effort → bin → cwd の順: model/effort 検証は CLI 不在の端末でも同じ結果になる（テスト可能性）。
+    let model = null;
+    if (opts.model != null) {
+        model = opts.model.trim();
+        if (!model)
+            throw new AitermError("model が空文字です（省略するか有効なモデル名を指定してください）", 2);
+    }
     const effort = opts.reasoning_effort ?? null;
-    if (effort && kind !== "codex" && !GROK_EFFORTS.has(effort)) {
-        throw new AitermError(`reasoning_effort '${effort}' は不正です（${label} は low/medium/high/xhigh/max）`, 2);
+    // grok CLI の --effort は headless（grok -p）専用で、対話 TUI では警告の上無視される。
+    // 黙って no-op の引数を受けない＝起動前に明示エラーで拒否する（codex は CLI 側の値集合が
+    // 版で変わるため縛らず送信まで通す）。
+    if (effort && kind === "grok") {
+        throw new AitermError(`${label} は reasoning_effort を指定できません。grok CLI の --effort は headless（grok -p）専用で、` +
+            "対話 TUI では警告の上無視されます（grok-4.5 の TUI 既定 effort は high）。" +
+            "effort 制御が必要なら通常 PTY で `grok -p --effort low|medium|high ...` を使ってください", 2);
+    }
+    if (effort && kind === "composer") {
+        throw new AitermError(`${label} は reasoning_effort を指定できません。grok-composer-2.5-fast は reasoning effort 非対応です` +
+            "（モデルカタログ supports_reasoning_effort=false）", 2);
     }
     const agentDone = !!opts.agent_done;
     const bin = resolveAgentBin(kind);
@@ -1808,13 +2080,15 @@ export function openAgent(kind, opts = {}) {
     const binForCmd = isWin ? toWslPath(bin) : bin;
     const cwdForCmd = cwd && isWin ? toWslPath(cwd) : cwd;
     const [sid, hint] = openSession(opts.session_name ?? null, "bash");
+    let launchNote = "";
     try {
         const meta = agentDone
             ? kind === "codex"
-                ? createCodexAgentMetadata(sid, cwd, !!opts.prompt)
-                : createGrokAgentMetadata(kind, sid, cwd, !!opts.prompt)
+                ? createCodexAgentMetadata(sid, cwd, opts.prompt ? "pending" : "none", { model, effort })
+                : createGrokAgentMetadata(kind, sid, cwd, opts.prompt ? "pending" : "none")
             : null;
-        const cmd = buildAgentCmd(kind, binForCmd, effort, opts.prompt ?? null, meta);
+        launchNote = buildAgentLaunchNote(kind, model, effort, meta);
+        const cmd = buildAgentCmd(kind, binForCmd, model, effort, opts.prompt ?? null, meta);
         const envPrefix = agentEnvPrefix(meta, sid);
         const full = cwdForCmd ? `cd ${shq(cwdForCmd)} && ${envPrefix}${cmd}` : `${envPrefix}${cmd}`;
         // force:true で送る。起動骨格は `bin '...'` の固定形で、prompt/cwd/effort は shq でクオート済みの
@@ -1834,10 +2108,68 @@ export function openAgent(kind, opts = {}) {
     }
     return [
         sid,
-        `${label} を session ${sid} で起動した。${agentDone ? "agent_done 待機が有効。" : ""}` +
+        `${label} を session ${sid} で起動した。${launchNote}${agentDone ? "agent_done 待機が有効。" : ""}` +
             `${agentDone && kind !== "codex" ? " hook 汚染防止のため Grok 実行中は一時 HOME を使う。" : ""}\n${hint}\n` +
             `TUI の描画には数秒かかる。少し置いてから pty_read(${sid}, screen:true) で画面を読み、` +
             `pty_send(${sid}, "...") で入力・pty_key(${sid}, "Enter"/"Up"/"C-c" 等) で操作する（対話）。` +
             `起動直後に増分 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,
+        model: opts.model ?? 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

@@ -180,34 +180,55 @@ server.registerTool("pty_list", {
 });
 // 対話型エージェント起動ツール（モデルごとに1つ＝ツール名/説明でどのモデルか一目で分かる）。
 // いずれも永続端末に TUI を起動し session_id を返す。以後 pty_read/pty_send で対話操作する。
-const agentEffortDesc = (grokLike) => "reasoning effort（思考レベル）。" +
-    (grokLike ? "low/medium/high/xhigh/max" : "low/medium/high 等") +
-    "。省略時は CLI 既定。";
+const agentModelDesc = (kind) => kind === "codex"
+    ? "起動モデル（例: gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna）。省略時は端末 config／CLI 既定を継承" +
+        "（端末側のピンがそのまま効く。実効値は起動応答に明示される）"
+    : `起動モデル。省略時は ${kind === "grok" ? "grok-4.5" : "grok-composer-2.5-fast"}`;
+const agentEffortDesc = (grokLike) => grokLike
+    ? "指定不可（grok CLI の --effort は headless 専用で、対話 TUI では警告の上無視される。" +
+        "composer は effort 自体非対応）。指定すると起動前にエラーを返す"
+    : "reasoning effort（思考レベル）。low/medium/high/xhigh/max/ultra（CLI 版依存）。" +
+        "ultra は max 推論＋proactive 自動委譲 ON＝使用量急増注意（明示要求時のみ）。省略時は端末 config／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: {
             prompt: z.string().nullish().describe("起動時に渡す初手プロンプト（任意）。省略で素のTUI起動"),
-            // grok/composer の effort は有限集合＝schema で拒否（session を作る前に弾く）。
+            model: z.string().nullish().describe(agentModelDesc(kind)),
+            // grok/composer の effort は対話 TUI で無効（headless 専用）＝core 側が起動前に明示エラーで拒否。
             // codex は CLI 側の値集合が版で変わるため縛らない（core 側も同方針）。
-            reasoning_effort: (grokLike ? z.enum(["low", "medium", "high", "xhigh", "max"]) : z.string())
-                .nullish()
-                .describe(agentEffortDesc(grokLike)),
+            reasoning_effort: z.string().nullish().describe(agentEffortDesc(grokLike)),
             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') を使えるようにする"),
+            ...initialPromptWaitSchema,
         },
-    }, async ({ prompt, reasoning_effort, cwd, session_name, agent_done }) => {
+    }, async ({ prompt, model, 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,
+                model: model ?? 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}`);
         }
@@ -216,12 +237,13 @@ function registerAgentTool(toolName, kind, desc, grokLike) {
         }
     });
 }
-registerAgentTool("codex_agent", "codex", "【Codex (OpenAI・モデルは Codex CLI の既定)】の対話エージェント TUI を永続端末に起動する。実装・レビュー・調査を対話で回す。" +
-    "起動後は pty_read で画面を読み pty_send で操作する。reasoning_effort を引数で指定可。", false);
-registerAgentTool("grok_agent", "grok", "【Grok Build の Grok モデル (grok-build)】の対話エージェント TUI を永続端末に起動する。" +
-    "起動後は pty_read/pty_send で対話操作。reasoning_effort を引数で指定可。", true);
-registerAgentTool("composer_agent", "composer", "【Grok Build の Composer モデル (grok-composer-2.5-fast)】の対話エージェント TUI を永続端末に起動する。" +
-    "起動後は pty_read/pty_send で対話操作。reasoning_effort を引数で指定可。", true);
+registerAgentTool("codex_agent", "codex", "【Codex (OpenAI)】の対話エージェント TUI を永続端末に起動する。実装・レビュー・調査を対話で回す。" +
+    "起動後は pty_read で画面を読み pty_send で操作する。model / reasoning_effort を引数で指定可" +
+    "（省略時は端末 config／CLI 既定を継承。実効値は起動応答に明示）。", false);
+registerAgentTool("grok_agent", "grok", "【Grok Build の Grok モデル (既定 grok-4.5)】の対話エージェント TUI を永続端末に起動する。" +
+    "起動後は pty_read/pty_send で対話操作。model を引数で指定可。reasoning_effort は対話 TUI 非対応（指定はエラー）。", true);
+registerAgentTool("composer_agent", "composer", "【Grok Build の Composer モデル (既定 grok-composer-2.5-fast)】の対話エージェント TUI を永続端末に起動する。" +
+    "起動後は pty_read/pty_send で対話操作。model を引数で指定可。reasoning_effort は非対応（指定はエラー）。", true);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

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