aiterm-mcp 0.10.0 → 0.12.0

package/README.ja.md

@@ -20,6 +20,8 @@
 >
 > *MCP = Model Context Protocol — Claude Code のようなツールが AI に機能を差し込むためのオープン標準。*
 
+**言葉でなく実測で:** このリポジトリ自身の 203 テストで、`pty_read` はコンテキストに載るトークンを生ログの **約 7.1 分の 1** に減らす。しかも pass/fail の判定は畳んでも残る。→ [組み込みシェルツールとの使い分け](#組み込みシェルツールとの使い分け)
+
 9 ツール: 6 つの **PTY ツール**（`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`）で 1 本の永続端末を開き・操作し・読む。加えて 3 つの **エージェント起動ツール**（`codex_agent` / `grok_agent` / `composer_agent`）が、別のコーディングエージェントの TUI を新しい端末の中に起動する。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
 **状態:** 開発継続中 · この分野では新参で、別の形に賭けている（[既存手段との比較](#既存手段との比較)参照）· 動作対象は Linux · WSL2 · macOS · Windows ネイティブ（core PTY ツール。`agent_done` は現時点では POSIX/WSL/macOS のみ）· MIT · [変更履歴](CHANGELOG.md)。
@@ -174,6 +176,40 @@ flowchart LR
 
 primitive は「PTY を 1 個握る」ことだけ。それ以外——SSH・コンテナ・REPL・起動したエージェント TUI——は、永続端末の中で動く「対話的な何か」に過ぎず、同じ `pty_send` / `pty_read` で操作する。各起動ツールは自分専用の新しい PTY を開く。PTY は tmux 上にあるので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
+## 組み込みシェルツールとの使い分け
+
+MCP クライアントには最初からシェルツールが付いている。軽い用事はそれで足りるし、aiterm が活きる場面は別にある。その線引きを、同じコマンドで両方に通して確かめた。トークンの数え方は両側で揃えてある（文字数 ÷ 4、aiterm が実際に使う見積り式）ので、比較はフェアだ。
+
+ちょっとしたコマンドなら、組み込みツールのほうが速い。`git log --oneline -5` を 1 回で返すのに対して、aiterm は `pty_send` と `pty_read` で 2 回のやり取りが要る。この 1 往復ぶんの差が、軽いコマンドではそのまま損になる（~7 秒 vs ~13 秒）。
+
+出力が長いとき、あるいは状態を次の呼び出しへ持ち越したいときに、この 2 往復目が元を取る。
+
+| コマンド | 組み込みシェル | aiterm | 判定 |
+| --- | --- | --- | --- |
+| `git log --oneline -5` | 1 回・~7 秒 | 2 回・~13 秒 | **シェル**（往復が少ない） |
+| `npm test`（203 テスト） | ~4,292 tok | ~607 tok | **aiterm**（判定は残る） |
+| `find node_modules -type f` | ~500 tok¹ | ~456 tok | 互角。aiterm は先頭も末尾も残す |
+| `grep -rn "session" src/` | ~2,989 tok | ~1,096 tok | **aiterm**（長い行は切られる²） |
+
+例えばこのリポジトリの 203 テストを走らせてみる。組み込みツールはログ 223 行をまるごと——~4,292 トークン——コンテキストに流し込む。aiterm は同じ出力を head+tail に畳んで ~607 トークンまで縮める。
+
+```text
+[aiterm demo: 51 行 / ~607 tok (raw 223 行 / ~4292 tok); 172 行 hidden] [is_complete=True via mark]
+```
+
+モデルに読ませるトークンは約 **7.1 分の 1** に減る。それでも判定は残る。畳んだ後の tail に `ℹ tests 203 / ℹ pass 203 / ℹ fail 0` がちゃんと載っている。削れたのは繰り返しのノイズで、ログを開いた目的の行は生きている。実行時間はほぼ同じなので、これだけ長いコマンドになると 2 往復の差は誤差に埋もれる。
+
+aiterm はセッションの状態も持ち越せる。組み込みツールは呼び出しごとにまっさらなシェルを立てるので、cwd は毎回プロジェクト直下に戻り、環境変数も引き継がれない。試しに `cd /tmp && export BENCH_VAR=hello123` を送って、別の呼び出しで読み返してみる。
+
+```text
+組み込みシェル  →  var=                   # 空。env は消え、cwd はプロジェクト直下に戻る
+aiterm          →  cwd=/tmp var=hello123  # 1 本の tmux セッションが両方を保つ
+```
+
+cd でディレクトリを移り、環境変数を立て、ビルドを走らせる。ssh で一度ログインして、その接続のまま 10 個コマンドを打つ。REPL や起動したエージェントの TUI を 1 ターンずつ操作する。こういう流れは、1 本の tmux セッションが状態を握っていて初めて成り立つ。端末に何かを覚えておいてほしいときは、aiterm を使う。
+
+<sub>¹ いまのハーネスは ~192 KB の出力をいったんファイルに逃がして、先頭 ~2 KB だけを見せる。そのためトークン数はほぼ並ぶ。aiterm は行数を正確に返すうえ、あとから `line_range="A:B"` で好きな範囲（先頭でも末尾でも）を取り出せる。² `rtk` の grep 縮約は長い行（~80 字）を切り詰めて、あふれを `[+N more]` にまとめる。ざっと眺めるには向くが、全行をそのまま読みたいときは組み込みツールを使う。</sub>
+
 ## 既存手段との比較
 
 aiterm は 2 つの系譜の交点にいる——端末を操作する MCP サーバと、より新しい「エージェント同士が共有端末越しに会話する」という発想（[aiterm の立ち位置](#aiterm-の立ち位置)参照）。各軸の並びはこうなる——相手が強い所も含めて、正直に。
@@ -208,7 +244,7 @@ aiterm は同じ核心の洞察——端末を出会いの場にする——を
 | --- | --- | --- |
 | `pty_open` | 端末を 1 個握り `session_id` を返す | `name?`, `shell="bash"` |
 | `pty_send` | テキスト(コマンド)を送る | `session_id`, `text`, `enter=true`, `wait`, `timeout`, `screen`, `lines`, `mark`, `force`, `rtk`, `raw` |
-| `pty_read` | 出力を削減して読む（既定は増分） | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk` |
+| `pty_read` | 出力を削減して読む（既定は増分） | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk`, `agent_transcript` |
 | `pty_key` | 制御キーを送る | `session_id`, `key`（`C-c`/`Enter`/`Up`…） |
 | `pty_close` | セッションを閉じる | `session_id` |
 | `pty_list` | セッション一覧 | （なし） |
@@ -225,6 +261,8 @@ aiterm は同じ核心の洞察——端末を出会いの場にする——を
 
 各ベンダーの 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 不在ならセッション残骸なしで失敗する。
 
+エージェントの回答が `wait:"agent_done"` の画面 tail（ペイン高 ≒ 24 行）より長くて切れたら、`pty_read({ agent_transcript: true })` で全文回収する。managed home 配下の vendor 構造化 transcript から、直近完了ターンの最終 assistant メッセージを平文で返す（再プロンプト不要）。Codex は Stop hook の `turn_id` で join、Grok/Composer は最後の実ユーザー行より後ろの assistant 行を採る。読み取り専用で、`screen`/`full`/`rtk`/`line_range`/`wait` とは併用不可（`lines` のみ可）。transcript 不在・非 agent session・抽出不能はいずれも明示エラー（黙って空を返さない）。
+
 ### 完了検出（5 層）
 
 `pty_read({ wait: true })` は、プロセス終了 / `mark:true` sentinel の自動検出（後述）/ `until` 一致（**既定はリテラル部分一致**、`until_regex: true` で正規表現）/ 出力静止 ∧ シェル復帰（quiescence）/ timeout の 5 層で「コマンドが終わったか」を判定する。ネスト中（SSH・コンテナ・REPL・起動したエージェントの TUI の中）はシェル復帰判定が効かないので、`until` で内側プロンプトを指定するか、`mark: true` で送れば `pty_read({ wait: true })` が sentinel を自動検出する（until 不要・ネストでも効く）——全画面のエージェント TUI なら、出力が落ち着いた時点で `{ screen: true }` を読む。`agent_done:true` で起動したセッションは代わりに `pty_send({ wait:"agent_done" })` を使える。必要な場合はまず agent TUI の入力欄を待ち、その後 vendor Stop hook を待ってターン境界後の画面を返す。`codex_agent` launcher の `wait:"agent_done"` は起動時 `prompt` に同じ待機を行う。`pty_send` の送信前 ready 失敗は MCP エラー、launcher の初回 prompt ready 失敗は `initial_prompt=not_sent` を返す。送信後 timeout は `is_complete=False via agent_timeout` で返り、成功扱いしない。agent session の通常 `pty_read` には `agent_event_seen=true completion_attribution=none` のような補助 metadata が付くことがあるが、古い hook event を `is_complete=True` に昇格しない。完結した hook JSONL 行が壊れていた場合は、切り分け用に timeout suffix へ `malformed_events=N` が付く。ターンは完了したが端末 screen/log が flush 窓内で安定しなかった場合は、`agent_done_but_screen_unstable` が付く。

package/README.md

@@ -20,6 +20,8 @@
 >
 > *MCP = Model Context Protocol — the open standard that lets tools like Claude Code plug capabilities into an AI.*
 
+**Measured, not claimed:** on this repo's own 203-test suite, a `pty_read` puts **~7.1× fewer tokens** in your context than the raw log — and the pass/fail verdict survives the fold. → [When to reach for it vs. the built-in shell](#when-to-reach-for-it-vs-the-built-in-shell)
+
 Nine tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal, plus three **agent launchers** — `codex_agent` / `grok_agent` / `composer_agent` — that each start another coding agent's TUI inside a fresh one. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
 
 **Status:** actively maintained · the newcomer here, betting on a different shape (see [vs. the alternatives](#vs-the-alternatives)) · runs on Linux · WSL2 · macOS · native Windows for the core PTY tools (`agent_done` is POSIX/WSL/macOS only for now) · MIT · see the [CHANGELOG](CHANGELOG.md).
@@ -60,11 +62,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?`, `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` |
+| `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. (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`.
+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.
 
@@ -174,6 +176,42 @@ flowchart LR
 
 One PTY is the only primitive. Everything else — SSH, containers, REPLs, and the launched agent TUIs — is just something interactive running inside a persistent terminal, driven with the same `pty_send` / `pty_read`. Each launcher opens its own fresh PTY. Because the PTYs live in tmux, sessions outlive the MCP server and the AI client.
 
+## When to reach for it vs. the built-in shell
+
+Your MCP client already has a shell tool, and it wins on some jobs. aiterm wins on others. We measured both on the same commands in this repo, counting tokens the same way on each side (characters ÷ 4, aiterm's own estimator), so the comparison is apples-to-apples.
+
+Start with the built-in tool for a light one-shot. `git log --oneline -5` is one round-trip; aiterm is two — `pty_send` then `pty_read` — and that second round-trip costs more than a light command saves (~7 s vs ~13 s).
+
+The second round-trip pays for itself once the output runs long, or the state has to outlive the call.
+
+| Command | Built-in shell | aiterm | Verdict |
+| --- | --- | --- | --- |
+| `git log --oneline -5` | 1 call, ~7 s | 2 calls, ~13 s | **shell** (fewer round-trips) |
+| `npm test` (203 tests) | ~4,292 tok | ~607 tok | **aiterm** (~7.1× fewer, verdict kept) |
+| `find node_modules -type f` | ~500 tok¹ | ~456 tok | tokens tie; aiterm keeps head and tail + `line_range` |
+| `grep -rn "session" src/` | ~2,989 tok | ~1,096 tok | **aiterm** (~2.7×; long lines get clipped²) |
+
+On the repo's own 203-test suite the reduction is real and safe. The built-in tool drops the whole 223-line log — ~4,292 tokens — into context. aiterm folds its own capture of the run down to ~607:
+
+```text
+[aiterm demo: 51 行 / ~607 tok (raw 223 行 / ~4292 tok); 172 行 hidden] [is_complete=True via mark]
+```
+
+<sub>`行` = lines; the meta line is quoted verbatim from aiterm's real output.</sub>
+
+That is about **7.1× fewer** tokens reaching the model, and the verdict survives the fold: the tail still carries `ℹ tests 203 / ℹ pass 203 / ℹ fail 0`. The reduction drops the noise and keeps the line you opened the log for. Wall-clock effectively ties, so on a run this long the extra round-trip is a small part of the total.
+
+aiterm also holds state across calls. The built-in tool runs each call in a fresh shell, so cwd resets between calls and the environment doesn't carry. Send `cd /tmp && export BENCH_VAR=hello123`, then read it back in a second, separate call:
+
+```text
+built-in shell  →  var=                   # empty; env dropped, cwd back at project root
+aiterm          →  cwd=/tmp var=hello123  # one tmux session holds both
+```
+
+`cd` then set env then build, `ssh` once then run ten commands on the authenticated session, drive a live REPL or a launched agent's TUI turn by turn — one tmux session holds all of it. Reach for aiterm when the terminal has to remember something.
+
+<sub>¹ Today's harness auto-offloads the ~192 KB dump to a file and previews only a ~2 KB head, so the token counts nearly tie; aiterm reports the accurate line count and lets `line_range="A:B"` pull any slice later, head or tail. ² The `rtk` grep reducer truncates long lines (~80 chars) and folds the overflow into `[+N more]`, which suits scanning; use the built-in tool when you need every full line.</sub>
+
 ## vs. the alternatives
 
 aiterm sits at the intersection of two families: terminal-driving MCP servers, and the newer "agents talk to each other through a shared terminal" idea (see [Where aiterm fits](#where-aiterm-fits)). Here's how the axes line up — honestly, including where the others are strong.
@@ -208,10 +246,10 @@ On top of that sits a productized layer a raw tmux bridge doesn't have: **token-
 | --- | --- | --- |
 | `pty_open` | Grab one terminal, return a `session_id` | `name?`, `shell="bash"` |
 | `pty_send` | Send text (a command) | `session_id`, `text`, `enter=true`, `wait`, `timeout`, `screen`, `lines`, `mark`, `force`, `rtk`, `raw` |
-| `pty_read` | Read output, token-reduced (incremental by default) | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk` |
+| `pty_read` | Read output, token-reduced (incremental by default) | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk`, `agent_transcript` |
 | `pty_key` | Send a control key | `session_id`, `key` (`C-c`/`Enter`/`Up`…) |
 | `pty_close` | Close a session | `session_id` |
-| `pty_list` | List sessions | (none) |
+| `pty_list` | List sessions (agent rows carry `agent=<kind>` metadata) | (none) |
 
 ### Interactive agent launchers
 
@@ -219,11 +257,13 @@ 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?`, `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` |
+| `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: 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.
 
-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.
+When an agent's answer is longer than the `wait:"agent_done"` screen tail (pane height ≈ 24 lines), recover it in full with `pty_read({ agent_transcript: true })`. It returns the most recently completed turn's final assistant message in plain text, read from the vendor's structured session transcript under the managed home — no re-prompting. Codex joins on the Stop hook `turn_id`; Grok/Composer take the assistant rows after the last real user row. Read-only, and mutually exclusive with `screen`/`full`/`rtk`/`line_range`/`wait` (`lines` is allowed). A missing transcript, a non-agent session, or an unextractable message is an explicit error, never a silent empty.
 
 ### Completion detection (5 layers)
 

package/dist/core.js

@@ -55,6 +55,9 @@ const AGENT_TUI_READY_LINES = 45;
 const MAX_LINES_BEFORE_ELIDE = 60;
 const HEAD_LINES = 30;
 const TAIL_LINES = 20;
+const MAX_LINE_CHARS_BEFORE_ELIDE = 2000;
+const LINE_HEAD_CHARS = 1200;
+const LINE_TAIL_CHARS = 600;
 const DEDUP_MIN_RUN = 3; // 同一行がこれ以上連続したら 1 行＋件数に畳む
 const MAX_FULL_BYTES = 8 * 1024 * 1024; // full/range 読取で一度にメモリへ載せる上限（B7）
 // 安全: send 前に弾く破壊的コマンド（外部システム境界の防御）
@@ -62,7 +65,7 @@ const DESTRUCTIVE = [
     // rm -rf の危険な対象形（best-effort・force で越えられる）。先頭の任意クオート ['"]? で
     // `rm -rf "/"` / `'/'` / `"~"` を捕捉。`\.\/\*`=./*（相対 glob）、`\.\.?\/?\s*$`=. / .. / ./ / ../
     // （カレント/親そのもの）。`./build` 等の相対サブディレクトリは末尾でないので非該当（過剰ブロック回避）。
-    /\brm\s+-[rfRF]*[rf][rfRF]*\s+['"]?(\/|~|\$HOME|\.\/\*|\.\.?\/?\s*$|\*\s*$)/i,
+    /\brm\s+-[rfRF]*[rf][rfRF]*\s+(?:--\s+)?['"]?(\/|~|\$HOME|\.\/\*|\.\.?\/?\s*$|\*\s*$)/i,
     /\bmkfs(\.\w+)?\b/i,
     /\bdd\b[^\n]*\bof=\/dev\//i,
     />\s*\/dev\/(sd|nvme|hd|mmcblk)/i,
@@ -442,6 +445,26 @@ function dedupRuns(lines) {
     }
     return out;
 }
+function surrogateSafeEnd(text, end) {
+    return end > 0 && end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1]) && /[\uDC00-\uDFFF]/.test(text[end])
+        ? end + 1
+        : end;
+}
+function surrogateSafeStart(text, start) {
+    return start > 0 && start < text.length && /[\uD800-\uDBFF]/.test(text[start - 1]) && /[\uDC00-\uDFFF]/.test(text[start])
+        ? start - 1
+        : start;
+}
+function elideLongLines(lines) {
+    return lines.map((line) => {
+        if (line.length <= MAX_LINE_CHARS_BEFORE_ELIDE)
+            return line;
+        const headEnd = surrogateSafeEnd(line, LINE_HEAD_CHARS);
+        const tailStart = surrogateSafeStart(line, line.length - LINE_TAIL_CHARS);
+        const omitted = tailStart - headEnd;
+        return `${line.slice(0, headEnd)}… 〈行内 ${omitted} 文字省略。全文は raw:true か line_range で取得〉 …${line.slice(tailStart)}`;
+    });
+}
 /** RTK 4戦略を移植: 制御除去 / 空白正規化 / 連続重複圧縮 / head+tail 折りたたみ。返り値 [body, meta]。 */
 export function reduceOutput(raw, name, elide = true) {
     const rawLinesN = (raw.match(/\n/g)?.length ?? 0) + (raw && !raw.endsWith("\n") ? 1 : 0);
@@ -454,6 +477,8 @@ export function reduceOutput(raw, name, elide = true) {
         const hint = `… 〈${elided} 行省略。全文は full=true、範囲は line_range="A:B"〉 …`;
         lines = [...lines.slice(0, HEAD_LINES), hint, ...lines.slice(lines.length - TAIL_LINES)];
     }
+    if (elide)
+        lines = elideLongLines(lines);
     const body = lines.join("\n");
     const meta = `[aiterm ${name}: ${lines.length} 行 / ~${estimateTokens(body)} tok ` +
         `(raw ${rawLinesN} 行 / ~${estimateTokens(raw)} tok)` +
@@ -588,17 +613,25 @@ async function waitCompletion(name, untilStr, untilRegex, timeout) {
             stable++;
             if (stable >= STABLE_POLLS) {
                 const fg = paneCurrentCommand(name);
-                if (SHELLS.has(fg)) {
+                // サイズ標本は過去・fg は今、の時間差 race を閉じる: fg 取得（サブプロセス spawn）の間に
+                // 出力が伸びていたら「静止」は不成立として周回をやり直す。閉じないと、コマンド完了直後の
+                // 出力＋シェル復帰が quiescent に誤帰属され、mark/until が帰属を取り損ねる
+                // （macOS CI 実測: sleep 0.6 の mark 送信が via quiescent に化けた・B1 flake の根因）。
+                // 次周回の先頭で新増分に対する mark/until 判定が走る。
+                if (safeStatSize(logpath(name)) !== size) {
+                    stable = 0;
+                }
+                else if (SHELLS.has(fg)) {
                     if (isWin)
                         await settleWinLog(name);
                     return [true, "quiescent"]; // 出力静止 ∧ シェル復帰 ＝ 確証つき完了
                 }
-                // ネスト中（前面が ssh/docker/REPL 等でシェル集合外）は quiescence の「シェル復帰」条件を
-                // 原理的に満たせない。until も mark も無ければこれ以上待っても確証は増えない（until/dead/
-                // quiescent/mark のいずれも発火し得ない）ので、出力静止時点で「未確定」のまま早期返却する。
-                // markActive のときは sentinel を待つべく早期返却せず、非シェル前面（sleep 等）でも待ち続ける。
-                // fg==="" は前面コマンド取得失敗＝ネスト断定不可なので早期返却せず従来どおり timeout まで待つ。
-                if (!until && !markActive && fg !== "") {
+                else if (!until && !markActive && fg !== "") {
+                    // ネスト中（前面が ssh/docker/REPL 等でシェル集合外）は quiescence の「シェル復帰」条件を
+                    // 原理的に満たせない。until も mark も無ければこれ以上待っても確証は増えない（until/dead/
+                    // quiescent/mark のいずれも発火し得ない）ので、出力静止時点で「未確定」のまま早期返却する。
+                    // markActive のときは sentinel を待つべく早期返却せず、非シェル前面（sleep 等）でも待ち続ける。
+                    // fg==="" は前面コマンド取得失敗＝ネスト断定不可なので早期返却せず従来どおり timeout まで待つ。
                     if (isWin)
                         await settleWinLog(name);
                     return [false, "nested"];
@@ -639,6 +672,14 @@ function rtkRewrite(text) {
         return (r.stdout ?? "").replace(/\n+$/, "");
     return text;
 }
+function assertNotDestructive(text, code, context = "") {
+    for (const pat of DESTRUCTIVE) {
+        if (pat.test(text)) {
+            throw new AitermError(`${context}破壊的の可能性があるコマンドを遮断しました: /${pat.source}/\n` +
+                `  本当に実行するなら force を有効にして再実行してください。`, code);
+        }
+    }
+}
 // ---------------------------------------------------------------- 操作（return で返す / 失敗は AitermError）
 export function openSession(name, shell = "bash") {
     fs.mkdirSync(SOCKDIR, { recursive: true });
@@ -715,14 +756,8 @@ export function send(name, text, o = {}) {
     if (!o.raw) {
         text = text.replace(PASTE_MARKERS_RE, "").replace(ANSI_RE, "").replace(CTRL_RE, "");
     }
-    if (!o.force) {
-        for (const pat of DESTRUCTIVE) {
-            if (pat.test(text)) {
-                throw new AitermError(`破壊的の可能性があるコマンドを遮断しました: /${pat.source}/\n` +
-                    `  本当に実行するなら force を有効にして再実行してください。`, 3);
-            }
-        }
-    }
+    if (!o.force)
+        assertNotDestructive(text, 3);
     if (o.mark) {
         // mark の sentinel は POSIX シェル構文。前面が fish/csh/tcsh 等の非 POSIX 対話シェルだと "$?" が
         // 壊れて sentinel が成立しない。黙って壊れた完了検出を作らず、明示エラーで until を促す（B8）。
@@ -735,6 +770,8 @@ export function send(name, text, o = {}) {
     writeLastcmd(name, text); // read rtk の reducer 分類用（書換/mark 前の素のコマンド）
     if (o.rtk)
         text = rtkRewrite(text);
+    if (o.rtk && !o.force)
+        assertNotDestructive(text, 3, "rtk 変換後: ");
     if (o.mark) {
         // 実出力は rc=<数字>、この行のエコーは rc=%d(リテラル)。MARK_DONE_RE は数字アンカーで後者に免疫。
         text = text + `; printf '\\n<<<AITERM_DONE rc=%d>>>\\n' "$?"`;
@@ -796,6 +833,13 @@ export function utf8SafeEnd(buf, end) {
         return end; // 不正な先行バイト: そのまま（stripControl 等に委ねる）
     return end - i >= need ? end : i; // 末尾文字が完結していれば end、不完全なら開始位置まで戻す
 }
+/** 途中 offset から読んだ Buffer の先頭にある UTF-8 継続バイトを最大3バイト捨てる。 */
+export function utf8SafeSliceStart(buf) {
+    let start = 0;
+    while (start < buf.length && start < 3 && (buf[start] & 0xc0) === 0x80)
+        start++;
+    return buf.subarray(start);
+}
 export async function readOutput(name, o = {}) {
     assertSessionName(name);
     const timeout = o.timeout ?? DEFAULT_TIMEOUT;
@@ -855,7 +899,7 @@ export async function readOutput(name, o = {}) {
         let from = 0;
         if (size > MAX_FULL_BYTES)
             from = size - MAX_FULL_BYTES;
-        text = readRange(from, size).toString("utf8");
+        text = utf8SafeSliceStart(readRange(from, size)).toString("utf8");
         if (from > 0)
             text = `[… 先頭 ${from} バイトを省略（ログがサイズ上限を超過。close で破棄されます）…]\n` + text;
         if (o.range) {
@@ -873,11 +917,12 @@ export async function readOutput(name, o = {}) {
         // 空を返して「何も読めない」状態になる。末尾越えは先頭から読み直す（POSIX では no-op）。
         if (off > size)
             off = 0;
-        const buf = readRange(off, size); // 増分のみをメモリに載せる
-        // 末尾の不完全マルチバイト列は次回へ持ち越す（B3）。off は前回この分岐が safeEnd を書くので先頭は割れない。
+        const initial = readRange(off, size); // 増分のみをメモリに載せる
+        const buf = utf8SafeSliceStart(initial);
+        // 先頭の継続バイトは捨て、末尾の不完全マルチバイト列は次回へ持ち越す（B3）。
         const safeLen = utf8SafeEnd(buf, buf.length);
         text = buf.subarray(0, safeLen).toString("utf8");
-        nextOffset = off + safeLen;
+        nextOffset = off + (initial.length - buf.length) + safeLen;
         if (o.lines)
             text = text.split("\n").slice(-o.lines).join("\n");
     }
@@ -909,8 +954,26 @@ export async function readOutput(name, o = {}) {
 }
 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}");
-    if (r.code === 0 && r.stdout.trim())
-        return r.stdout.replace(/\s+$/, "");
+    if (r.code === 0 && r.stdout.trim()) {
+        return r.stdout
+            .replace(/\s+$/, "")
+            .split("\n")
+            .map((line) => {
+            const name = line.split("\t", 1)[0];
+            const meta = tryLoadAgentMetadata(name);
+            if (!meta)
+                return line;
+            const agent = [
+                `agent=${meta.kind}`,
+                "agent_done=true",
+                meta.vendor_session_id ? `vendor_session_id=${meta.vendor_session_id}` : null,
+            ]
+                .filter(Boolean)
+                .join(" ");
+            return `${line}\t${agent}`;
+        })
+            .join("\n");
+    }
     return "(セッション無し)";
 }
 export function closeSession(name) {
@@ -918,6 +981,14 @@ export function closeSession(name) {
     if (agentWaitLocks.has(name)) {
         throw new AitermError(`agent session '${name}' は agent_done 待機中のため close できません`, 2);
     }
+    {
+        // 別プロセスの待機は in-memory Set に映らない。生きた file lock があれば close で state を消さない
+        const foreign = liveWaitLocks(name);
+        if (foreign.length > 0) {
+            const d = foreign[0];
+            throw new AitermError(`agent session '${name}' は別プロセス${d.pid != null ? `（pid ${d.pid}）` : ""}の agent_done 待機中のため close できません`, 2);
+        }
+    }
     tmux("kill-session", "-t", name);
     for (const p of [logpath(name), offsetpath(name), lastcmdpath(name), markpath(name)]) {
         try {
@@ -934,6 +1005,14 @@ export function killAll() {
     if (agentWaitLocks.size > 0) {
         throw new AitermError(`agent_done 待機中の session があるため killAll できません: ${Array.from(agentWaitLocks).join(",")}`, 2);
     }
+    {
+        // 別プロセスの待機（file lock が生きているもの）も巻き添えにしない
+        const foreign = liveWaitLocks(null);
+        if (foreign.length > 0) {
+            const list = foreign.map((d) => `${d.session}${d.pid != null ? `(pid ${d.pid})` : ""}`).join(",");
+            throw new AitermError(`agent_done 待機中の session があるため killAll できません: ${list}`, 2);
+        }
+    }
     tmux("kill-server");
     // B9: SOCKDIR 内の .log/.offset/.lastcmd/.mark 残骸も掃除する（残すと B5 の stale-log 復活の温床）。
     try {
@@ -1025,13 +1104,27 @@ function readFileRange(p, from, to) {
     }
 }
 function writeJson0600(p, v) {
-    fs.writeFileSync(p, JSON.stringify(v, null, 2) + "\n", { mode: 0o600 });
+    // truncate-in-place はクラッシュ/ENOSPC の窓で空・途中 JSON を残すので、temp→rename の原子的置換にする
+    const tmp = `${p}.${randomBytes(6).toString("hex")}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(v, null, 2) + "\n", { mode: 0o600, flag: "wx" });
     try {
-        fs.chmodSync(p, 0o600);
+        fs.chmodSync(tmp, 0o600);
     }
     catch {
         /* noop */
     }
+    try {
+        fs.renameSync(tmp, p);
+    }
+    catch (e) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* noop */
+        }
+        throw e;
+    }
 }
 function writeText0600(p, text) {
     fs.writeFileSync(p, text, { mode: 0o600 });
@@ -1050,7 +1143,94 @@ 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"|'model'|model)\s*=/.test(l))
+            return false;
+        if (overrides.effort && /^\s*(?:"model_reasoning_effort"|'model_reasoning_effort'|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}"|'${key}'|${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 managedCodexConfigSummary(configPath, hookTrustBypass) {
+    let body;
+    try {
+        body = fs.readFileSync(configPath, "utf8");
+    }
+    catch {
+        return "";
+    }
+    const rows = body.split(/\r?\n/);
+    const mcpServers = rows.filter((line) => /^\s*\[mcp_servers\./.test(line)).length;
+    const firstTable = rows.findIndex((line) => /^\s*\[/.test(line));
+    const topLevel = rows.slice(0, firstTable === -1 ? rows.length : firstTable);
+    const valueOf = (key) => {
+        const row = topLevel.find((line) => new RegExp(`^\\s*(?:"${key}"|'${key}'|${key})\\s*=\\s*(.+?)\\s*(?:#.*)?$`).test(line));
+        if (!row)
+            return null;
+        const raw = row.match(/=\s*(.+?)(?:\s+#.*)?$/)?.[1].trim() ?? null;
+        if (!raw)
+            return null;
+        const quoted = raw.match(/^(?:"([^"\\]*)"|'([^'\\]*)')$/);
+        return quoted ? quoted[1] ?? quoted[2] : raw;
+    };
+    const bits = [`mcp_servers ${mcpServers} 個継承`];
+    const approvalPolicy = valueOf("approval_policy");
+    const sandboxMode = valueOf("sandbox_mode");
+    if (approvalPolicy)
+        bits.push(`approval_policy=${approvalPolicy}`);
+    if (sandboxMode)
+        bits.push(`sandbox_mode=${sandboxMode}`);
+    if (hookTrustBypass)
+        bits.push("hook trust bypass 有効");
+    return `managed config: ${bits.join(" / ")}`;
+}
+function createManagedCodexHome(name, launchId, overrides = {}) {
     const srcHome = realCodexHome();
     let srcSt;
     try {
@@ -1078,17 +1258,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);
@@ -1271,19 +1456,107 @@ 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;
-    let fd;
+// wait lock の鮮度猶予: lock は open(O_EXCL)→pid 書込みの2段なので、中身が読めない直後の lock を
+// stale と誤判定しないための下限。これより古くて pid が読めない lock だけ残骸として回収する。
+const WAIT_LOCK_FRESH_MS = 5_000;
+function isPidAlive(pid) {
     try {
-        fd = fs.openSync(p, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | nofollow, 0o600);
+        process.kill(pid, 0);
+        return true;
     }
     catch (e) {
-        if (e.code === "EEXIST") {
-            throw new AitermError(`agent session '${meta.aiterm_session}' は別プロセスの agent_done 待機中です`, 2);
+        // ESRCH=不在。EPERM 等の判定不能は生存扱い（誤回収より拒否に倒す）
+        return e.code !== "ESRCH";
+    }
+}
+// wait lock が「生きた待機」か「消滅プロセスの残骸」かを判定する。
+// 前提: 呼び出し側は in-memory agentWaitLocks を先に確認している。よって pid=自プロセスの lock は
+// 例外経路で release が漏れた残骸と確定できる。
+function probeWaitLock(p) {
+    let pid = null;
+    let at = null;
+    let ageMs = 0;
+    try {
+        const st = fs.lstatSync(p);
+        if (!st.isFile() || st.isSymbolicLink())
+            return { pid: null, at: null, live: true };
+        ageMs = Math.max(0, Date.now() - st.mtimeMs);
+        const v = JSON.parse(fs.readFileSync(p, "utf8").split("\n", 1)[0]);
+        if (typeof v.pid === "number" && Number.isInteger(v.pid) && v.pid > 0)
+            pid = v.pid;
+        if (typeof v.at === "string")
+            at = v.at;
+    }
+    catch {
+        /* pid 不明のまま鮮度判定に落ちる */
+    }
+    if (pid == null)
+        return { pid: null, at, live: ageMs < WAIT_LOCK_FRESH_MS };
+    if (pid === process.pid)
+        return { pid, at, live: false };
+    return { pid, at, live: isPidAlive(pid) };
+}
+function unlinkStaleWaitLock(p) {
+    try {
+        const st = fs.lstatSync(p);
+        if (st.isFile() && !st.isSymbolicLink() && st.uid === currentUid())
+            fs.unlinkSync(p);
+    }
+    catch {
+        /* noop */
+    }
+}
+// close/killAll 用: 生きた別プロセス待機の wait lock を列挙する（stale 残骸は数えない）。
+function liveWaitLocks(name) {
+    const dir = existingAgentsDir();
+    if (!dir)
+        return [];
+    let files;
+    try {
+        files = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        if (!f.endsWith(".wait.lock"))
+            continue;
+        const session = f.slice(0, f.indexOf("."));
+        if (name != null && session !== name)
+            continue;
+        if (agentWaitLocks.has(session))
+            continue; // in-process 待機は呼び出し側の既存ガードが担当
+        const probe = probeWaitLock(path.join(dir, f));
+        if (probe.live)
+            out.push({ session, pid: probe.pid, at: probe.at });
+    }
+    return out;
+}
+function waitLockBusyError(session, probe) {
+    const detail = probe.pid != null ? `（pid ${probe.pid}${probe.at ? ` / ${probe.at} 開始` : ""}）` : "";
+    return new AitermError(`agent session '${session}' は別プロセスの agent_done 待機中です${detail}`, 2);
+}
+function acquireAgentWaitFileLock(meta) {
+    const p = agentWaitLockPath(meta.aiterm_session, meta.launch_id);
+    const nofollow = fs.constants.O_NOFOLLOW ?? 0;
+    let fd = null;
+    for (let attempt = 0; attempt < 2 && fd == null; attempt++) {
+        try {
+            fd = fs.openSync(p, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | nofollow, 0o600);
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            const probe = probeWaitLock(p);
+            // 生きた待機、または回収後の再取得でも EEXIST（=直後に別プロセスが取得した race）は拒否
+            if (probe.live || attempt > 0)
+                throw waitLockBusyError(meta.aiterm_session, probe);
+            unlinkStaleWaitLock(p);
         }
-        throw e;
     }
+    if (fd == null)
+        throw new AitermError(`agent session '${meta.aiterm_session}' は別プロセスの agent_done 待機中です`, 2);
     try {
         fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }) + "\n", undefined, "utf8");
     }
@@ -1307,11 +1580,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,
@@ -1538,6 +1811,148 @@ function latestAgentDoneEvent(meta) {
     }
     return latest;
 }
+function findLatestCodexTranscript(codexHome, vendorSessionId) {
+    const sessionsDir = path.join(codexHome, "sessions");
+    let latestFile = null;
+    let latestMtime = -Infinity;
+    const visit = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const file = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                visit(file);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.startsWith("rollout-") || !entry.name.endsWith(".jsonl") || !entry.name.includes(vendorSessionId))
+                continue;
+            try {
+                const mtimeMs = fs.statSync(file).mtimeMs;
+                if (mtimeMs > latestMtime) {
+                    latestFile = file;
+                    latestMtime = mtimeMs;
+                }
+            }
+            catch {
+                // 探索中に消えた transcript は候補にしない。候補が無ければ明示エラーにする。
+            }
+        }
+    };
+    visit(sessionsDir);
+    return latestFile;
+}
+function transcriptUnavailable() {
+    throw new AitermError("transcript がまだありません。ターン完了後に再取得してください。", 2);
+}
+function transcriptNotFound(vendor) {
+    throw new AitermError(`最終 assistant メッセージを特定できませんでした（vendor=${vendor}）。screen で確認してください。`, 2);
+}
+function readTranscriptLines(file) {
+    try {
+        return fs.readFileSync(file, "utf8").split("\n");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            transcriptUnavailable();
+        throw new AitermError(`transcript を読めません: ${e.message}`, 2);
+    }
+}
+/** agent vendor の構造化 transcript から直近完了ターンの最終回答を読む。 */
+export async function readAgentTranscript(name, o = {}) {
+    const meta = loadAgentMetadata(name);
+    if (!meta.vendor_session_id) {
+        throw new AitermError(`agent session '${name}' はまだターンが完了していません。agent_done 完了後に再取得してください。`, 2);
+    }
+    const done = latestAgentDoneEvent(meta);
+    const turnId = done?.turn_id ?? null;
+    let text = "";
+    if (meta.kind === "codex") {
+        if (!meta.codex_home)
+            transcriptUnavailable();
+        const transcript = findLatestCodexTranscript(meta.codex_home, meta.vendor_session_id);
+        if (!transcript)
+            transcriptUnavailable();
+        const lines = readTranscriptLines(transcript);
+        const matching = [];
+        let finalAnswer = "";
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const payload = record?.payload;
+            if (record?.type === "response_item" &&
+                payload?.type === "message" &&
+                payload?.role === "assistant" &&
+                payload?.internal_chat_message_metadata_passthrough?.turn_id === turnId &&
+                Array.isArray(payload?.content)) {
+                for (const item of payload.content) {
+                    if (item?.type === "output_text" && typeof item.text === "string")
+                        matching.push(item.text);
+                }
+            }
+            if (record?.type === "event_msg" &&
+                payload?.type === "agent_message" &&
+                payload?.phase === "final_answer" &&
+                typeof payload?.message === "string") {
+                finalAnswer = payload.message;
+            }
+        }
+        text = matching.join("\n") || finalAnswer;
+    }
+    else {
+        if (!meta.grok_home)
+            transcriptUnavailable();
+        // cwd 未指定で起動した TUI はサーバープロセスの cwd を継承する。metadata に null が残る既存
+        // launch との互換のため、その実際の起動 cwd を path 導出に使う（launch 側は変更しない）。
+        const cwd = meta.cwd ?? process.cwd();
+        const transcript = path.join(meta.grok_home, "sessions", encodeURIComponent(cwd), meta.vendor_session_id, "chat_history.jsonl");
+        const lines = readTranscriptLines(transcript);
+        let lastUser = -1;
+        const records = [];
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const record = JSON.parse(line);
+                records.push(record);
+                if (record?.type === "user" && !("synthetic_reason" in record))
+                    lastUser = records.length - 1;
+            }
+            catch {
+                // 外部 transcript の壊れた1行は残りの完結行を読む妨げにしない。
+            }
+        }
+        text = records
+            .slice(lastUser + 1)
+            .filter((record) => record?.type === "assistant" && typeof record?.content === "string")
+            .map((record) => record.content)
+            .join("\n");
+    }
+    if (!text.trim())
+        transcriptNotFound(meta.kind);
+    if (o.lines != null)
+        text = text.split("\n").slice(-o.lines).join("\n");
+    const rawChars = text.length;
+    const [body, outputMeta] = reduceOutput(text, name, true);
+    const transcriptMeta = [
+        "agent_transcript",
+        `vendor=${meta.kind}`,
+        `turn_id=${turnId ?? "unknown"}`,
+        `raw_chars=${rawChars}`,
+    ].join(" ");
+    return `${body}\n${outputMeta} [${transcriptMeta}]`;
+}
 function inferAgentFrontend(name, meta, screen) {
     const fg = paneCurrentCommand(name);
     const view = screen ?? captureScreen(name, AGENT_TUI_READY_LINES);
@@ -1868,23 +2283,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");
     }
@@ -1929,15 +2352,55 @@ 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);
+    const launch = `起動設定: model=${describePin(model, pins.model)} effort=${describePin(effort, pins.effort)}。` +
+        (effectiveEffort === "ultra"
+            ? "⚠ effort=ultra は max 推論＋proactive 自動委譲 ON（子エージェント自動生成・使用量急増に注意）。"
+            : "");
+    const summary = meta?.kind === "codex" && meta.codex_home ? managedCodexConfigSummary(configPath, true) : "";
+    return summary ? `${launch}\n${summary}\n` : launch;
+}
 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);
@@ -1975,13 +2438,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 ? "pending" : "none")
+                ? 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 でクオート済みの
@@ -2001,7 +2466,7 @@ 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" 等) で操作する（対話）。` +
@@ -2039,6 +2504,7 @@ export async function openAgentWithInitialPrompt(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,

package/dist/index.js

@@ -61,8 +61,12 @@ server.registerTool("pty_send", {
             .boolean()
             .default(false)
             .describe("完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して" +
-            "完了確定する（ネスト中や非シェル前面でも効く確実な完了検出。手で until を組む必要なし）"),
-        force: z.boolean().default(false).describe("破壊的コマンドゲートを越える"),
+            "完了確定する（ネスト中や非シェル前面でも効く確実な完了検出。手で until を組む必要なし）。" +
+            " enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key(\"Enter\") で実行される）。"),
+        force: z
+            .boolean()
+            .default(false)
+            .describe("破壊的コマンドゲートを越える。agent 起動時 prompt の完了待ち中の混入防止ガードも同時に解除する"),
         rtk: z.boolean().default(false).describe("既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）"),
         raw: z.boolean().default(false).describe("送信前サニタイズを無効化"),
     },
@@ -88,7 +92,9 @@ server.registerTool("pty_send", {
 });
 server.registerTool("pty_read", {
     description: "セッションの出力をトークン削減して読む（既定は前回読取位置からの増分）。" +
-        "削減: 制御文字除去 / 反復圧縮 / head+tail 折りたたみ＋復元ヒント＋メタ併記。",
+        "削減: 制御文字除去 / 反復圧縮 / head+tail 折りたたみ＋復元ヒント＋メタ併記。" +
+        "agent_transcript:true は agent session の直近完了ターンの最終 assistant メッセージを vendor transcript から平文で返す。" +
+        "長い回答が screen tail で切れた時の回収用。",
     inputSchema: {
         session_id: z.string(),
         wait: z
@@ -110,9 +116,19 @@ server.registerTool("pty_read", {
         line_range: z.string().nullish().describe('全文からの行範囲 "A:B"'),
         raw: z.boolean().default(false).describe("削減せず生テキスト"),
         rtk: z.boolean().default(false).describe("直前コマンド別の自前 reducer(git/grep/pytest 等)で縮約"),
+        agent_transcript: z
+            .boolean()
+            .default(false)
+            .describe("agent session の直近完了ターンの最終 assistant メッセージを vendor transcript から平文で返す。長い回答が screen tail で切れた時の回収用"),
     },
-}, async ({ session_id, wait, until, until_regex, timeout, screen, full, lines, line_range, raw, rtk }) => {
+}, async ({ session_id, wait, until, until_regex, timeout, screen, full, lines, line_range, raw, rtk, agent_transcript }) => {
     try {
+        if (agent_transcript) {
+            if (screen || full || rtk || wait || line_range != null) {
+                throw new Error("agent_transcript:true は screen / full / rtk / line_range / wait と併用できません。lines のみ指定できます。");
+            }
+            return ok(await core.readAgentTranscript(session_id, { lines: lines ?? null }));
+        }
         let range = null;
         if (line_range) {
             const idx = line_range.indexOf(":");
@@ -122,7 +138,11 @@ server.registerTool("pty_read", {
             // 下端は負値を 0 にクランプする（"-3:5" が負 slice にならないように・C12）。
             const loN = Math.max(0, parseInt(lo, 10) || 0);
             const hiN = hi ? parseInt(hi, 10) : NaN;
-            range = [loN, Number.isNaN(hiN) || hiN < 0 ? null : hiN];
+            const upper = Number.isNaN(hiN) || hiN < 0 ? null : hiN;
+            if (upper !== null && upper < loN) {
+                throw new Error(`line_range ${JSON.stringify(line_range)} が不正です: 上端が下端より小さい`);
+            }
+            range = [loN, upper];
         }
         const out = await core.readOutput(session_id, {
             wait,
@@ -168,7 +188,7 @@ server.registerTool("pty_close", {
     }
 });
 server.registerTool("pty_list", {
-    description: "握っているセッション一覧（名前 / 現在の前面コマンド / attach 状態 / サイズ）。",
+    description: "握っているセッション一覧（名前 / 現在の前面コマンド / attach 状態 / サイズ / agent 情報）。",
     inputSchema: {},
 }, async () => {
     try {
@@ -180,9 +200,15 @@ 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") {
@@ -198,11 +224,10 @@ function registerAgentTool(toolName, kind, desc, grokLike) {
         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
@@ -211,10 +236,11 @@ function registerAgentTool(toolName, kind, desc, grokLike) {
                 .describe("managed Stop hook を有効化し、pty_send(wait:'agent_done') を使えるようにする"),
             ...initialPromptWaitSchema,
         },
-    }, async ({ prompt, reasoning_effort, cwd, session_name, agent_done, wait, timeout, screen, lines }) => {
+    }, async ({ prompt, model, reasoning_effort, cwd, session_name, agent_done, wait, timeout, screen, lines }) => {
         try {
             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,
@@ -231,12 +257,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/dist/rtk.js

@@ -61,6 +61,7 @@ export function reducePytest(output) {
     let summaryLine = "";
     const failures = [];
     const xfailLines = [];
+    let pytestEvidence = false;
     let state = "header";
     let current = [];
     const flush = () => {
@@ -76,14 +77,18 @@ export function reducePytest(output) {
             continue;
         }
         if (t.startsWith("===") && t.includes("FAILURES")) {
+            pytestEvidence = true;
             state = "failures";
             continue;
         }
         if (t.startsWith("===") && t.includes("short test summary")) {
+            pytestEvidence = true;
             state = "summary";
             flush();
             continue;
         }
+        if (t.includes("no tests ran in"))
+            pytestEvidence = true;
         if (t.startsWith("===") &&
             (t.includes("passed") || t.includes("failed") || t.includes("skipped") || t.includes("error"))) {
             // 収集エラーのみ（`=== 1 error in Xs ===`）も要約行として拾う。拾わないと全ゼロ扱いで
@@ -125,6 +130,10 @@ export function reducePytest(output) {
     }
     flush();
     const [p, f, s, xf, xp, e] = parsePytestCounts(summaryLine);
+    if (/\b\d+\s+(?:passed|failed|skipped|xfailed|xpassed|errors?)\b/.test(summaryLine))
+        pytestEvidence = true;
+    if (!pytestEvidence)
+        return null;
     if (p === 0 && f === 0 && s === 0 && xf === 0 && xp === 0 && e === 0)
         return "Pytest: No tests collected";
     // error(収集/内部エラー)は失敗の一種＝緑扱いにしない。extras に含め、"N passed" 早期 return を止める。

package/package.json

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