aiterm-mcp 0.21.0 → 0.21.4

package/README.ja.md

@@ -1,17 +1,18 @@
 > **Claude Code から Codex CLI の対話 TUI を操作する——スラッシュコマンドや [`$imagegen`](https://learn.chatgpt.com/docs/image-generation#generate-or-edit-an-image) のようなスキルまで、MCP越しに使える。**
 
 <p align="center">
-  <img src=".github/og.svg" alt="aiterm-mcp — AI が握る 1 本の永続 MCP 端末。その中へ他のコーディングエージェント（Claude/Codex/Grok/Composer）を起動する（tmux ベースの stdio MCP サーバ）" width="100%">
+  <img src=".github/og.png" alt="Aiterm — 異なる知性が一つの持続する実行現場を共有する森の観測拠点" width="100%">
+  <br>
+  <sub><em>この画像は、異なる知性がひとつの持続する実行現場を共有し、それぞれの視点から同じ仕事を前へ進める姿を表しています。</em></sub>
 </p>
 
-# aiterm-mcp
+# Aiterm
 
 [![CI](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
 [![週間ダウンロード](https://img.shields.io/npm/dw/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
 [![node](https://img.shields.io/node/v/aiterm-mcp)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![install size](https://packagephobia.com/badge?p=aiterm-mcp)](https://packagephobia.com/result?p=aiterm-mcp)
 
 > *(English: [README.md](README.md))*
 
@@ -91,12 +92,20 @@ claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
 host統合は、kitepon.devの製品開発を支える内部基盤
 [dotagents](https://github.com/kitepon-rgb/dotagents)が担当します。
 
-**言葉でなく実測で:** このリポジトリ自身の 203 テストで、`pty_read` はコンテキストに載るトークンを生ログの **約 7.1 分の 1** に減らす。しかも pass/fail の判定は畳んでも残る。→ [組み込みシェルツールとの使い分け](#組み込みシェルツールとの使い分け)
+**言葉でなく実測で:** 記録済み203テストのベンチマークでは、`pty_read` はコンテキストに載るトークンを生ログの **約 7.1 分の 1** に減らす。しかも pass/fail の判定は畳んでも残る。→ [組み込みシェルツールとの使い分け](#組み込みシェルツールとの使い分け)
 
 13 ツール: 6 つの **PTY ツール**（`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`）で 1 本の永続端末を開き・操作し・読む。加えて 4 つの **エージェント起動ツール**（`claude_agent` / `codex_agent` / `grok_agent` / `composer_agent`）が別のコーディングエージェントの TUI を新しい端末の中に起動し、`claude_turn`がdurable caller向けの構造化issue／recoveryを、`claude_approval`がmanaged Claudeの相関済み承認UI中継を、`diagnostics`が安全なfactory readinessを返す。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
-**v0.20.3では、壊れた認証から複数のmanaged Claude／Fable sessionが同時にloginへ流れる問題を修理。**
-新規Claude起動はPTY作成前にvendor所有の共有認証を検証し、正常な認証は複数sessionから並行・反復利用できる。
+**v0.21.4ではfresh managed Claudeからuser scope MCPを復元。** 通常hook、plugin、permission、
+project／local MCPの隔離は維持し、`~/.claude.json`で既にuser scope登録された`mcpServers`だけを
+owner-onlyのlaunch設定へsnapshotする。破損したuser MCP設定は、toolなしで黙って起動せずsession作成前に失敗する。
+
+**v0.21.3ではCodexの完了経路からStop hookを撤去。** Codexの完了通知と最終回答の帰属は、
+root rollout transcriptへ永続化される`task_complete.turn_id`をdispatch byte境界以後から観測する。
+hookの実行ファイルが壊れたり消えたりしても`aiterm-wait`は座礁しない。v0.21.0では外部agent launcherへ
+明示的な`write_scope`能力宣言を追加し、v0.21.3で指定したscopeと実効性がstructured launch receiptへ
+確実に残るよう修正した。v0.20.3では、壊れた認証から複数のmanaged Claude／Fable
+sessionが同時にloginへ流れる問題を修理し、新規Claude起動はPTY作成前にvendor所有の共有認証を検証する。
 v0.20では、待たずに一度だけ観測する
 `aiterm-wait --timeout 0` の未完了を、実際に待って終わらなかった`timeout`と区別し、
 `running`（exit 5）で返すようにしました。v0.19系では相関済みmanaged Claude approval中継を追加し、
@@ -133,13 +142,15 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 ### 2. その端末の中に他のコーディングエージェントを起動する — オーケストレーションの旗艦
 
-同じ primitive が別エージェントの TUI を宿す。4 つの起動ツールが、Claude/Codex/Grok/Composer の対話 TUI を新しい永続端末の中に起動し、`session_id` を返す。既存の人間向けtextに加えて`aiterm.agent-launch-result.v1` structured receiptも返すため、durable callerは表示文字列を解析せずsession handleを取得できる。以後は同じ `pty_read` / `pty_send` で継続操作する。**起動は常に managed**（aiterm 所有の Stop hook 付き）で、agent session への `pty_send` は非ブロックの **dispatch** になり `event_cursor` 入り receipt を即返す。完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` をホストのバックグラウンドタスクとして実行し、exit 時に receipt の `outcome` で判定する（exit 0=done / 3=timeout=未完了・既定600秒 / 4=closed。親はブロックもポーリングもしない）。起動時 `prompt` を渡した launch は structured receipt にコピペ可能な `wait_command` と `event_cursor`、そして `submit_residue` 観測を含む（true=prompt が composer に未 submit で残存している疑い＝案内に従い画面確認から復旧 / false=残存観測せず・成立の保証ではない / null=対象外）。dispatch receipt にも同じ観測が付く。durable machine callerは`claude_turn({ action:"issue"|"recover", session_id, operation_id, ... })`を使い、人間向けerror文字列を解析せず`accepted`／`pending`／`completed`／`unknown`を判定できる。recoveryは再送せず、検証済み完了だけがexact `raw_output`を持つ。通常の`pty_send`／`pty_read`は対話callerと人間向けに維持する。`C-c`後もmarkerを保持し、Stopが来なければsessionをcloseする。`claude_agent` と `codex_agent` の初回 `prompt` は ready gate 経由で送信して待たずに返る（Grok/Composer は argv 渡し）。手動でキー操作したい場合は `pty_open` で素の端末を開き vendor CLI を自分で起動する。
+同じ primitive が別エージェントの TUI を宿す。4 つの起動ツールが、Claude/Codex/Grok/Composer の対話 TUI を新しい永続端末の中に起動し、`session_id` を返す。既存の人間向けtextに加えて`aiterm.agent-launch-result.v1` structured receiptも返すため、durable callerは表示文字列を解析せずsession handleを取得できる。以後は同じ `pty_read` / `pty_send` で継続操作する。**起動は常に managed**で、Codexはroot rollout transcriptの`task_complete`、Claude/Grokは隔離されたmanaged Stop hookを完了正本に使う。agent session への `pty_send` は非ブロックの **dispatch** になり `event_cursor` 入り receipt を即返す。完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` をホストのバックグラウンドタスクとして実行し、exit 時に receipt の `outcome` で判定する（exit 0=done / 3=timeout=未完了・既定600秒 / 4=closed。親はブロックもポーリングもしない）。起動時 `prompt` を渡した launch は structured receipt にコピペ可能な `wait_command` と `event_cursor`、そして `submit_residue` 観測を含む（true=prompt が composer に未 submit で残存している疑い＝案内に従い画面確認から復旧 / false=残存観測せず・成立の保証ではない / null=対象外）。dispatch receipt にも同じ観測が付く。durable machine callerは`claude_turn({ action:"issue"|"recover", session_id, operation_id, ... })`を使い、人間向けerror文字列を解析せず`accepted`／`pending`／`completed`／`unknown`を判定できる。recoveryは再送せず、検証済み完了だけがexact `raw_output`を持つ。通常の`pty_send`／`pty_read`は対話callerと人間向けに維持する。`C-c`後もClaude markerを保持し、Stopが来なければsessionをcloseする。`claude_agent` と `codex_agent` の初回 `prompt` は ready gate 経由で送信して待たずに返る（Grok/Composer は argv 渡し）。手動でキー操作したい場合は `pty_open` で素の端末を開き vendor CLI を自分で起動する。
 
 `codex_agent`・`grok_agent`・`composer_agent`は任意の`write_scope`（`"read-only"`または書込み許可パスの説明）も受ける。指定値はlaunch receipt・session metadata・`pty_list`へ保存する。Codexの`write_scope:"read-only"`だけは実効能力壁であり、aitermがCLIの`--sandbox read-only`を付ける。Grok/Composerには対応する対話起動sandboxがなく、Codexにもパス説明をallowlistへ変換するフラグがないため、それらは強制済みと偽らず`write_scope_enforcement:"declaration_only_unsupported"`を返す。`write_scope`を省略した起動は従来どおりである。
 
 ```text
 codex_agent({ session_name: "codex1", cwd: "/repo",
-              prompt: "port test/legacy.py to vitest" })
+              prompt: "port test/legacy.py to vitest",
+              model: "gpt-5.6-sol", reasoning_effort: "high",
+              write_scope: "test/ only; no commit" })
                                     → { session_id: "codex1", … }   # Codex が永続端末で稼働開始
 pty_read("codex1", { screen: true })   → 何をしているか読む（トークン削減）
 pty_send("codex1", "also fix the imports it broke")   # 非ブロックdispatch＝event_cursor入りreceipt
@@ -152,11 +163,11 @@ $ aiterm-wait --session codex1 --cursor <event_cursor>   # exit 0=done / 3=timeo
 | ツール | 起動するもの | 主な引数 |
 | --- | --- | --- |
 | `claude_agent` | Claude Code CLI（Anthropic） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`）, `cwd?`, `session_name?` |
-| `codex_agent` | Codex CLI（OpenAI・端末設定／CLI既定、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`/`ultra`）, `cwd?`, `session_name?` |
-| `grok_agent` | Grok Build（xAI、既定`grok-4.5`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?` |
-| `composer_agent` | Grok Build（xAI、既定`grok-composer-2.5-fast`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?` |
+| `codex_agent` | Codex CLI（OpenAI・端末設定／CLI既定、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`/`ultra`）, `cwd?`, `session_name?`, `write_scope?` |
+| `grok_agent` | Grok Build（xAI、既定`grok-4.5`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?`, `write_scope?` |
+| `composer_agent` | Grok Build（xAI、既定`grok-composer-2.5-fast`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?`, `write_scope?` |
 
-各ベンダーの CLI が導入・認証済みであること（`claude_agent` は `claude`、`codex_agent` は `codex`、Grok 系は `grok`）。バイナリは `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`、各既定path、`PATH` の順で解決する。CLI不在・不正なmodel/effort・実在しない`cwd`はsession作成前に失敗し、残骸を残さない。Claudeはさらに、PTY作成前に同じCLIの`auth status --json`が`loggedIn:true`を返すことを要求する。未認証・malformed・失敗exit・timeoutは残骸ゼロで失敗し、正常なvendor所有の共有認証は複数sessionから利用する。managed Claudeへのexact `/login`・`/logout`は通常dispatchとforce送信の双方で副作用前に拒否するため、認証は通常端末で一度だけ修理する。Claudeは通常settingsを継承しないlaunch専用settingsとStop hookを使い、本文なしeventとowner-only bounded resultを分離する。`pty_read({ agent_transcript:true })`はdigestとbyte数を検証したresultだけを返し、Claude private transcriptを読まない。後着resultは同じsessionからprompt再送なしで回収できる。managed Claudeのactive turn中はC-c以外の`pty_key`と素送信を拒否する。Claudeが`Do you want to proceed?`を表示したら、`claude_approval(action:"inspect", ...)`で画面digestを取得し、表示内容を判断してから、そのdigestと`approve_once`または`deny`を`respond`へ渡す。同じoperation・同じ画面が維持されている時だけ入力し、任意文字列や恒久許可選択肢は中継しない。中断は`C-c`、解除は`pty_close`。
+各ベンダーの CLI が導入・認証済みであること（`claude_agent` は `claude`、`codex_agent` は `codex`、Grok 系は `grok`）。バイナリは `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`、各既定path、`PATH` の順で解決する。CLI不在・不正なmodel/effort・実在しない`cwd`はsession作成前に失敗し、残骸を残さない。Claudeはさらに、PTY作成前に同じCLIの`auth status --json`が`loggedIn:true`を返すことを要求する。未認証・malformed・失敗exit・timeoutは残骸ゼロで失敗し、正常なvendor所有の共有認証は複数sessionから利用する。managed Claudeへのexact `/login`・`/logout`は通常dispatchとforce送信の双方で副作用前に拒否するため、認証は通常端末で一度だけ修理する。Claudeは通常settingsを継承しないlaunch専用settingsとStop hookを使う一方、user scopeの`mcpServers`だけは`~/.claude.json`から別のowner-only launch configへsnapshotし`--mcp-config`で渡す。project／local MCPは継承しない。本文なしeventとowner-only bounded resultを分離し、`pty_read({ agent_transcript:true })`はdigestとbyte数を検証したresultだけを返してClaude private transcriptを読まない。後着resultは同じsessionからprompt再送なしで回収できる。managed Claudeのactive turn中はC-c以外の`pty_key`と素送信を拒否する。Claudeが`Do you want to proceed?`を表示したら、`claude_approval(action:"inspect", ...)`で画面digestを取得し、表示内容を判断してから、そのdigestと`approve_once`または`deny`を`respond`へ渡す。同じoperation・同じ画面が維持されている時だけ入力し、任意文字列や恒久許可選択肢は中継しない。中断は`C-c`、解除は`pty_close`。
 
 エージェント間の隠れたプロトコルは無い。起動したClaude/Codex/Grok/Composerは利用者がattachできるもう1本の永続sessionであり、MCPクライアントが通常のPTY操作で駆動する。
 
@@ -354,17 +365,17 @@ consumer は `aiterm-runtime-errors snapshot` を読み、durable ingestion 後
 | ツール | 起動するもの | 主な引数 |
 | --- | --- | --- |
 | `claude_agent` | Claude Code CLI（Anthropic） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`）, `cwd?`, `session_name?` |
-| `codex_agent` | Codex CLI（OpenAI・端末設定／CLI既定、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`/`ultra`）, `cwd?`, `session_name?` |
-| `grok_agent` | Grok Build（xAI、既定`grok-4.5`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?` |
-| `composer_agent` | Grok Build（xAI、既定`grok-composer-2.5-fast`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?` |
+| `codex_agent` | Codex CLI（OpenAI・端末設定／CLI既定、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`/`ultra`）, `cwd?`, `session_name?`, `write_scope?` |
+| `grok_agent` | Grok Build（xAI、既定`grok-4.5`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?`, `write_scope?` |
+| `composer_agent` | Grok Build（xAI、既定`grok-composer-2.5-fast`、`model?`で上書き） | `prompt?`, `model?`, `reasoning_effort?`は非対応（指定時は明示エラー）, `cwd?`, `session_name?`, `write_scope?` |
 
 対応するCLI（`claude` / `codex` / `grok`）の導入・認証が必要。解決順は`CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`、既定path、`PATH`。前提違反はsession作成前に明示失敗する。ClaudeはPTY作成前に構造化認証statusも検証し、managed session内の`/login`・`/logout`を拒否する。4 launcherすべてが同じ非ブロックdispatch契約を使い、Claude/Codexの初回promptはready gate経由で送信される。Claudeはisolated managed settingsとhook-captured resultを使い、private transcriptへ依存しない。Claude／Codex／Grok／Composerのlive smokeはすべてgreenであり、fixtureによる検証とは区別して記録する。
 
-エージェントの回答が画面 tailより長ければ、対話callerは`pty_read({ agent_transcript:true })`で再promptなしに全文回収する。Claudeはmanaged Stop hookがowner-only resultへ保存した本文をdigest/byte数で検証して返し、private transcriptを読まない。durable machine callerは`claude_turn`を使う。`issue`は一度だけ送信し、`recover`は決して再送せず、`pending`を破損やidentity不一致と区別する。検証済みの`completed`だけがexact `raw_output`を持ち、`unknown`は未dispatchと帰属不能を区別する。不一致・破損は成功statusへ丸めずtool errorのままにする。IDなしの対話turnも匿名markerで直列化するため、現在Stop待ちの間に古い回答を返さない。CodexはStop hookの`turn_id`で構造化transcriptへjoinし、Grok/Composerは最後の実user行より後ろのassistant行を採る。不在・非agent・抽出不能は明示エラー。
+エージェントの回答が画面 tailより長ければ、対話callerは`pty_read({ agent_transcript:true })`で再promptなしに全文回収する。Claudeはmanaged Stop hookがowner-only resultへ保存した本文をdigest/byte数で検証して返し、private transcriptを読まない。durable machine callerは`claude_turn`を使う。`issue`は一度だけ送信し、`recover`は決して再送せず、`pending`を破損やidentity不一致と区別する。検証済みの`completed`だけがexact `raw_output`を持ち、`unknown`は未dispatchと帰属不能を区別する。不一致・破損は成功statusへ丸めずtool errorのままにする。IDなしの対話turnも匿名markerで直列化するため、現在Stop待ちの間に古い回答を返さない。Codexはroot rollout transcriptの`task_complete.turn_id`で完了と最終回答を同じturnへ帰属し、Grok/Composerは最後の実user行より後ろのassistant行を採る。不在・非agent・抽出不能は明示エラー。
 
 ### 完了検出（5 層）
 
-`pty_read({ wait: true })` は、プロセス終了 / `mark:true` sentinel の自動検出（後述）/ `until` 一致（**既定はリテラル部分一致**、`until_regex: true` で正規表現）/ 出力静止 ∧ シェル復帰（quiescence）/ timeout の 5 層で「コマンドが終わったか」を判定する。ネスト中（SSH・コンテナ・REPL・起動したエージェントの TUI の中）はシェル復帰判定が効かないので、`until` で内側プロンプトを指定するか、`mark: true` で送れば `pty_read({ wait: true })` が sentinel を自動検出する（until 不要・ネストでも効く）——全画面のエージェント TUI なら、出力が落ち着いた時点で `{ screen: true }` を読む。agent session は第6の正確な層を使う: vendor Stop hook が完了 event を書き、`pty_send` dispatch が返した `event_cursor` 境界から `aiterm-wait --cursor` が完了を観測する（親はブロックもポーリングもしない）。`pty_send` の送信前 ready 失敗は MCP エラー、launcher の初回 prompt ready 失敗は `initial_prompt=not_sent` を返す。agent session の通常 `pty_read` には `agent_event_seen=true completion_attribution=none` のような補助 metadata が付くことがあるが、古い hook event を `is_complete=True` に昇格しない。完結した hook JSONL 行が壊れていた場合は、`aiterm-wait` receipt の `malformed_events` に数えられる。ターンは完了したが端末 screen/log が flush 窓内で安定しなかった場合は、`agent_done_but_screen_unstable` が付く。
+`pty_read({ wait: true })` は、プロセス終了 / `mark:true` sentinel の自動検出（後述）/ `until` 一致（**既定はリテラル部分一致**、`until_regex: true` で正規表現）/ 出力静止 ∧ シェル復帰（quiescence）/ timeout の 5 層で「コマンドが終わったか」を判定する。ネスト中（SSH・コンテナ・REPL・起動したエージェントの TUI の中）はシェル復帰判定が効かないので、`until` で内側プロンプトを指定するか、`mark: true` で送れば `pty_read({ wait: true })` が sentinel を自動検出する（until 不要・ネストでも効く）——全画面のエージェント TUI なら、出力が落ち着いた時点で `{ screen: true }` を読む。agent session は第6の正確な層を使う: Codexは`pty_send` dispatchが返したtranscript byte境界以後の`task_complete`を、Claude/Grokはevent-file境界以後のmanaged hook eventを`aiterm-wait --cursor`が観測する（親はブロックもポーリングもしない）。`pty_send` の送信前 ready 失敗は MCP エラー、launcher の初回 prompt ready 失敗は `initial_prompt=not_sent` を返す。完結した構造化JSONL行が壊れていた場合は、`aiterm-wait` receipt の `malformed_events` に数えられる。
 
 ### トークン削減
 

package/README.md

@@ -1,17 +1,18 @@
 > **Drive Codex CLI's interactive TUI from Claude Code — including slash commands and skills such as [`$imagegen`](https://learn.chatgpt.com/docs/image-generation#generate-or-edit-an-image) — through MCP.**
 
 <p align="center">
-  <img src=".github/og.svg" alt="aiterm-mcp — one persistent MCP terminal your AI drives, and launches other coding agents (Claude/Codex/Grok/Composer) into (tmux-backed stdio MCP server)" width="100%">
+  <img src=".github/og.png" alt="Aiterm — a shared forest observatory where different intelligences work in one persistent execution space" width="100%">
+  <br>
+  <sub><em>This image represents different intelligences sharing one persistent workspace and advancing the same work from their own perspectives.</em></sub>
 </p>
 
-# aiterm-mcp
+# Aiterm
 
 [![CI](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
 [![weekly downloads](https://img.shields.io/npm/dw/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
 [![node](https://img.shields.io/node/v/aiterm-mcp)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![install size](https://packagephobia.com/badge?p=aiterm-mcp)](https://packagephobia.com/result?p=aiterm-mcp)
 
 > *(日本語: [README.ja.md](README.ja.md))*
 
@@ -91,12 +92,25 @@ execution lane. Cross-product installation and host integration are handled by
 [dotagents](https://github.com/kitepon-rgb/dotagents), the internal development
 toolchain behind kitepon.dev's products.
 
-**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)
+**Measured, not claimed:** in the recorded 203-test benchmark, a `pty_read` puts **~7.1× fewer tokens** in your context than the raw log — and the pass/fail verdict survives the fold. → [When to reach for it vs. the built-in shell](#when-to-reach-for-it-vs-the-built-in-shell)
 
 Thirteen tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal, four **agent launchers** — `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` — that each start another coding agent's TUI inside a fresh one, `claude_turn` for durable structured issue/recovery, `claude_approval` for correlated managed-Claude approval prompts, and `diagnostics` for safe factory readiness. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
 
-**v0.20.3 prevents concurrent managed Claude/Fable sessions from turning one broken
-login into many competing login flows.** Every new Claude launch verifies the
+**v0.21.4 restores user-scoped MCPs in fresh managed Claude sessions.** Aiterm keeps
+normal hooks, plugins, permissions, and project/local MCPs isolated, while snapshotting only
+the already user-scoped `mcpServers` from `~/.claude.json` into an owner-only launch config.
+Malformed user MCP config fails before a session is created instead of silently launching
+Claude without its tools.
+
+**v0.21.3 removes Codex Stop hooks from the completion path.** Codex completion and
+final-message attribution now come from the root rollout transcript's durable
+`task_complete.turn_id`, observed after the dispatch byte boundary. A broken or stale
+hook executable can no longer strand `aiterm-wait`. v0.21.0 added explicit
+`write_scope` declarations for external-agent launchers; v0.21.3 also fixes their
+structured launch receipts so a supplied scope and its enforcement status are retained.
+v0.20.3 prevents concurrent
+managed Claude/Fable sessions from turning one broken login into many competing login
+flows. Every new Claude launch verifies the
 vendor-owned shared credential store before creating a PTY, while healthy credentials
 remain reusable across concurrent and repeated sessions. The v0.20 line also distinguishes
 a non-blocking `aiterm-wait --timeout 0` observation (`running`, exit 5) from a real timed-out
@@ -124,7 +138,7 @@ A lot of 2026's agent tooling is converging on orchestration: a lead model deleg
 
 aiterm predates Build Week, so the event work is kept visible in dated commits. During the submission window (July 14–16, 2026), I extended it with safe serialized delivery for long PTY input, correlated operation IDs and bounded result recovery, machine-readable launch and idempotent close receipts, and a hardened readiness gate that prevents prompts from disappearing during TUI startup redraws. The public comparison from the pre-event release is [`v0.12.2...main`](https://github.com/kitepon-rgb/aiterm-mcp/compare/v0.12.2...main).
 
-I used **Codex with GPT-5.6** as an engineering collaborator: it inspected the implementation, challenged the API and recovery contracts, generated focused regression cases, and helped verify race, security, timeout, and malformed-event paths. I reviewed the diffs and test evidence and retained the final product and architecture decisions. The result is a 262-test regression suite covering normal operation as well as failure and recovery behavior.
+I used **Codex with GPT-5.6** as an engineering collaborator: it inspected the implementation, challenged the API and recovery contracts, generated focused regression cases, and helped verify race, security, timeout, and malformed-event paths. I reviewed the diffs and test evidence and retained the final product and architecture decisions. At that Build Week checkpoint, the regression suite contained 262 tests covering normal operation as well as failure and recovery behavior; current release receipts live in the [CHANGELOG](CHANGELOG.md) and release ADRs.
 
 ## Two ways to use it
 
@@ -143,7 +157,7 @@ pty_read(id, { wait: true })       → read the token-reduced output, completion
 
 ### 2. Launch other coding agents into that terminal — the orchestration flagship
 
-The same primitive hosts another agent's TUI. Four launchers each start one vendor's interactive coding-agent TUI inside a fresh persistent terminal and return a `session_id`. Their existing human-readable text is accompanied by an `aiterm.agent-launch-result.v1` structured receipt, so durable callers never parse display text for the session handle; when the launch carries an initial `prompt`, the receipt also includes the `event_cursor`, a ready-made `wait_command` for the completion waiter, and a `submit_residue` observation (`true` = the prompt is likely still sitting unsubmitted in the composer — the hint explains recovery; `false` = no residue observed, not a proof of submission; `null` = not applicable). From there you drive it with the same `pty_read` / `pty_send` you'd use on any shell: read its output token-reduced, send it the next step. (The TUIs are full-screen apps, so `pty_read({ screen: true })` gives you the rendered view.) Every launch is **managed**: aiterm installs its own Stop hook, so turn completion is a first-class event. Sending to an agent session is a non-blocking **dispatch** — the call returns immediately with an `event_cursor`, and completion arrives via [`aiterm-wait`](#completion-push-for-parent-agents-aiterm-wait). Durable machine callers use `claude_turn({ action: "issue" | "recover", session_id, operation_id, ... })`: it returns fixed `accepted` / `pending` / `completed` / `unknown` states without parsing human-facing errors, never resends during recovery, and includes exact `raw_output` only for a verified completion. The same operation ID is carried through the dispatch receipt, active marker, Stop event, and result. The ordinary `pty_send` / `pty_read` surface remains available for interactive callers and humans. `C-c` keeps the marker for a delayed Stop; if no Stop arrives, close the session. An initial `prompt` on `claude_agent`/`codex_agent` is submitted through the same ready gate and the launcher returns without waiting; on Grok/Composer it is passed on the CLI's argv. This needs the vendor's own CLI installed and authenticated — see [Requirements](#requirements).
+The same primitive hosts another agent's TUI. Four launchers each start one vendor's interactive coding-agent TUI inside a fresh persistent terminal and return a `session_id`. Their existing human-readable text is accompanied by an `aiterm.agent-launch-result.v1` structured receipt, so durable callers never parse display text for the session handle; when the launch carries an initial `prompt`, the receipt also includes the `event_cursor`, a ready-made `wait_command` for the completion waiter, and a `submit_residue` observation (`true` = the prompt is likely still sitting unsubmitted in the composer — the hint explains recovery; `false` = no residue observed, not a proof of submission; `null` = not applicable). From there you drive it with the same `pty_read` / `pty_send` you'd use on any shell: read its output token-reduced, send it the next step. (The TUIs are full-screen apps, so `pty_read({ screen: true })` gives you the rendered view.) Every launch is **managed**: Codex completion comes from its own durable rollout transcript's `task_complete`; Claude and Grok use isolated managed Stop hooks. Sending to an agent session is a non-blocking **dispatch** — the call returns immediately with an `event_cursor`, and completion arrives via [`aiterm-wait`](#completion-push-for-parent-agents-aiterm-wait). Durable machine callers use `claude_turn({ action: "issue" | "recover", session_id, operation_id, ... })`: it returns fixed `accepted` / `pending` / `completed` / `unknown` states without parsing human-facing errors, never resends during recovery, and includes exact `raw_output` only for a verified completion. The same operation ID is carried through the dispatch receipt, active marker, Stop event, and result. The ordinary `pty_send` / `pty_read` surface remains available for interactive callers and humans. `C-c` keeps the marker for a delayed Claude Stop; if no Stop arrives, close the session. An initial `prompt` on `claude_agent`/`codex_agent` is submitted through the same ready gate and the launcher returns without waiting; on Grok/Composer it is passed on the CLI's argv. This needs the vendor's own CLI installed and authenticated — see [Requirements](#requirements).
 
 `codex_agent`, `grok_agent`, and `composer_agent` also accept an optional `write_scope`: either `"read-only"` or a human-readable description of writable paths. A supplied value is retained in the launch receipt, session metadata, and `pty_list`. For Codex, `write_scope: "read-only"` is an effective boundary: aiterm adds the CLI's `--sandbox read-only` flag. Grok/Composer have no corresponding interactive-launch sandbox, and Codex has no path-description allowlist flag; those cases return `write_scope_enforcement: "declaration_only_unsupported"` rather than claiming enforcement. Omitting `write_scope` preserves prior behavior.
 
@@ -151,7 +165,9 @@ For a managed Claude turn stopped at `Do you want to proceed?`, use `claude_appr
 
 ```text
 codex_agent({ session_name: "codex1", cwd: "/repo",
-              prompt: "port test/legacy.py to vitest" })
+              prompt: "port test/legacy.py to vitest",
+              model: "gpt-5.6-sol", reasoning_effort: "high",
+              write_scope: "test/ only; no commit" })
                                     → { 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")
@@ -165,13 +181,13 @@ One call per model, so the tool name itself tells you which model you get:
 | Tool | Launches | Key args |
 | --- | --- | --- |
 | `claude_agent` | Claude Code CLI (Anthropic) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`), `cwd?`, `session_name?`, `launch_operation_id?` |
-| `codex_agent` | Codex CLI (OpenAI; terminal config/CLI default unless overridden) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`/`ultra`; ultra enables proactive automatic delegation), `cwd?`, `session_name?` |
-| `grok_agent` | Grok Build, model `grok-4.5` by default (`model?` overrides) (xAI) | `prompt?`, `model?`, `reasoning_effort?` unsupported (an explicit value is an error; Grok CLI `--effort` is headless-only), `cwd?`, `session_name?` |
-| `composer_agent` | Grok Build, model `grok-composer-2.5-fast` by default (`model?` overrides) (xAI) | `prompt?`, `model?`, `reasoning_effort?` unsupported (an explicit value is an error), `cwd?`, `session_name?` |
+| `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?`, `write_scope?` |
+| `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?`, `write_scope?` |
+| `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?`, `write_scope?` |
 
-The vendor CLI must be installed and authenticated (`claude` for `claude_agent`; `codex` for `codex_agent`; `grok` for both Grok tools). aiterm resolves the binary via `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`, then `~/.local/bin/claude` / `~/.local/bin/codex` / `~/.grok/bin/grok`, then `PATH`. Prerequisites are checked **before** a session exists: empty `model` values and unsupported effort values are rejected up front; a missing CLI binary or a nonexistent `cwd` fails for all four. Before creating a Claude session, aiterm also requires a successful structured `claude auth status --json` result with `loggedIn: true`; unavailable, malformed, or failed authentication leaves **zero leftover session**. Claude sessions share the vendor-owned credential store rather than copying credentials per launch, so multiple sessions can reuse one healthy login. Managed Claude rejects exact `/login` and `/logout` dispatches, including forced sends: repair authentication once in a normal terminal, then relaunch any stale unauthenticated sessions. Claude and Codex launchers forward `model` and `reasoning_effort` through their vendor CLI's public flags; Grok/Composer reject `reasoning_effort` because it is headless-only. Pass an absolute path for `cwd` — `~` is not expanded. Durable callers can make a promptless Claude launch exactly replayable by passing an explicit `session_name` and a `launch_operation_id` formatted as `sha256:<64 lowercase hex>`. Repeating the identical launch returns the same structured session receipt without starting the CLI twice; a different correlation ID or launch argument for that session fails explicitly. Claude uses launch-local managed settings containing only aiterm's Stop hook: normal user/project/local hooks are not inherited, the hook event contains no answer body, and the bounded owner-only result is returned by `pty_read({ agent_transcript:true })` without reading Claude's private transcript. A late result remains recoverable from the same session without re-sending the prompt. While a managed Claude turn is active, raw sends and non-interrupt keys are rejected. If Claude displays `Do you want to proceed?`, call `claude_approval(action:"inspect", ...)`, decide from the visible prompt, then call `respond` with the returned digest and either `approve_once` or `deny`. The response is accepted only while the same operation and screen digest remain current; arbitrary text and persistent-allow choices are never relayed. Use `pty_key("C-c")` to interrupt and `pty_close` to abandon the session. For unconstrained manual key-by-key driving, open a plain `pty_open` session and start the vendor CLI yourself. Codex uses a managed `CODEX_HOME`; Grok/Composer isolate their managed homes and pass validated OAuth state through `GROK_AUTH_PATH`. Before the first unbound dispatch, aiterm waits for the vendor TUI's input prompt and fails before sending if it is not ready. Managed completion requires POSIX filesystem semantics (Linux, WSL2, macOS).
+The vendor CLI must be installed and authenticated (`claude` for `claude_agent`; `codex` for `codex_agent`; `grok` for both Grok tools). aiterm resolves the binary via `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`, then `~/.local/bin/claude` / `~/.local/bin/codex` / `~/.grok/bin/grok`, then `PATH`. Prerequisites are checked **before** a session exists: empty `model` values and unsupported effort values are rejected up front; a missing CLI binary or a nonexistent `cwd` fails for all four. Before creating a Claude session, aiterm also requires a successful structured `claude auth status --json` result with `loggedIn: true`; unavailable, malformed, or failed authentication leaves **zero leftover session**. Claude sessions share the vendor-owned credential store rather than copying credentials per launch, so multiple sessions can reuse one healthy login. Managed Claude rejects exact `/login` and `/logout` dispatches, including forced sends: repair authentication once in a normal terminal, then relaunch any stale unauthenticated sessions. Claude and Codex launchers forward `model` and `reasoning_effort` through their vendor CLI's public flags; Grok/Composer reject `reasoning_effort` because it is headless-only. Pass an absolute path for `cwd` — `~` is not expanded. Durable callers can make a promptless Claude launch exactly replayable by passing an explicit `session_name` and a `launch_operation_id` formatted as `sha256:<64 lowercase hex>`. Repeating the identical launch returns the same structured session receipt without starting the CLI twice; a different correlation ID or launch argument for that session fails explicitly. Claude uses launch-local managed settings containing only aiterm's Stop hook: normal user/project/local hooks are not inherited. User-scoped `mcpServers` are copied separately from `~/.claude.json` into a launch-local owner-only config and passed through `--mcp-config`; project/local MCPs remain isolated. The hook event contains no answer body, and the bounded owner-only result is returned by `pty_read({ agent_transcript:true })` without reading Claude's private transcript. A late result remains recoverable from the same session without re-sending the prompt. While a managed Claude turn is active, raw sends and non-interrupt keys are rejected. If Claude displays `Do you want to proceed?`, call `claude_approval(action:"inspect", ...)`, decide from the visible prompt, then call `respond` with the returned digest and either `approve_once` or `deny`. The response is accepted only while the same operation and screen digest remain current; arbitrary text and persistent-allow choices are never relayed. Use `pty_key("C-c")` to interrupt and `pty_close` to abandon the session. For unconstrained manual key-by-key driving, open a plain `pty_open` session and start the vendor CLI yourself. Codex uses a managed `CODEX_HOME`; Grok/Composer isolate their managed homes and pass validated OAuth state through `GROK_AUTH_PATH`. Before the first unbound dispatch, aiterm waits for the vendor TUI's input prompt and fails before sending if it is not ready. Managed completion requires POSIX filesystem semantics (Linux, WSL2, macOS).
 
-The managed Codex home links authentication, privately snapshots `config.toml` and `agents/*.toml` custom-role definitions, and keeps sessions/caches isolated. A symlinked role definition is resolved into a regular-file snapshot rather than shared with the source home.
+The managed Codex home links authentication, privately snapshots `config.toml` and `agents/*.toml` custom-role definitions, and keeps sessions/caches isolated. A symlinked role definition is resolved into a regular-file snapshot rather than shared with the source home. aiterm does not install a Codex Stop hook: the root rollout transcript is the completion source, so a missing hook executable cannot strand `aiterm-wait`.
 
 There is no hidden protocol between agents: a launched Claude, Codex, Grok, or Composer is another user-visible persistent terminal session. The MCP client drives that TUI with ordinary PTY operations, and a human can attach to watch or take over.
 
@@ -293,7 +309,7 @@ The second round-trip pays for itself once the output runs long, or the state ha
 | `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:
+In the recorded 203-test benchmark 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]
@@ -371,24 +387,24 @@ Each launcher starts a specific vendor's interactive coding-agent TUI inside a f
 | Tool | Launches | Key args |
 | --- | --- | --- |
 | `claude_agent` | Claude Code CLI (Anthropic) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`), `cwd?`, `session_name?`, `launch_operation_id?` |
-| `codex_agent` | Codex CLI (OpenAI; terminal config/CLI default unless overridden) | `prompt?`, `model?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`/`ultra`; ultra enables proactive automatic delegation), `cwd?`, `session_name?` |
-| `grok_agent` | Grok Build, model `grok-4.5` by default (`model?` overrides) (xAI) | `prompt?`, `model?`, `reasoning_effort?` unsupported (an explicit value is an error; Grok CLI `--effort` is headless-only), `cwd?`, `session_name?` |
-| `composer_agent` | Grok Build, model `grok-composer-2.5-fast` by default (`model?` overrides) (xAI) | `prompt?`, `model?`, `reasoning_effort?` unsupported (an explicit value is an error), `cwd?`, `session_name?` |
+| `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?`, `write_scope?` |
+| `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?`, `write_scope?` |
+| `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?`, `write_scope?` |
 
 The vendor CLI must be installed and authenticated (`claude` for `claude_agent`; `codex` for `codex_agent`; `grok` for both Grok tools). Binary resolution uses `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`, then each documented default location, then `PATH`. Missing binaries, invalid model/effort values, and nonexistent `cwd` fail before a session is created. Claude additionally requires a structured healthy authentication status before any PTY exists, and managed Claude rejects `/login` and `/logout`; repair authentication once in a normal terminal. All four share the same non-blocking dispatch contract for follow-up turns; `claude_agent`/`codex_agent` submit an initial `prompt` through the ready gate. Claude uses isolated managed settings and a hook-captured bounded result rather than private transcript access. Claude, Codex, Grok, and Composer live smokes are green; fixture coverage remains a separate claim. Native Windows can launch agents but managed completion is not supported yet.
 
-When an agent's answer is longer than the on-screen tail (pane height ≈ 24 lines), callers recover it in full with `pty_read({ agent_transcript: true })`. It returns the most recently completed turn's final assistant message in plain text with no re-prompting. Claude reads the bounded owner-only result captured by the managed Stop hook and verifies its digest/byte count; it never reads Claude's private transcript. Durable machine callers should use `claude_turn`: `issue` sends once, `recover` never sends, `pending` is distinct from unsafe or malformed state, and only `completed` carries the exact verified `raw_output`. `unknown` distinguishes `operation_not_found` from a receipt whose result can no longer be attributed. Mismatch and corruption remain tool errors rather than being folded into a successful status. ID-less interactive Claude turns are still serialized by an anonymous marker, so an older answer is not returned while the current Stop is pending. Codex joins its structured transcript on the Stop hook `turn_id`; Grok/Composer take the assistant rows after the last real user row. A missing result/transcript, a non-agent session, or an unextractable message is an explicit error, never a silent empty.
+When an agent's answer is longer than the on-screen tail (pane height ≈ 24 lines), callers recover it in full with `pty_read({ agent_transcript: true })`. It returns the most recently completed turn's final assistant message in plain text with no re-prompting. Claude reads the bounded owner-only result captured by the managed Stop hook and verifies its digest/byte count; it never reads Claude's private transcript. Durable machine callers should use `claude_turn`: `issue` sends once, `recover` never sends, `pending` is distinct from unsafe or malformed state, and only `completed` carries the exact verified `raw_output`. `unknown` distinguishes `operation_not_found` from a receipt whose result can no longer be attributed. Mismatch and corruption remain tool errors rather than being folded into a successful status. ID-less interactive Claude turns are still serialized by an anonymous marker, so an older answer is not returned while the current Stop is pending. Codex uses the root rollout transcript's `task_complete.turn_id` both for completion and final-message attribution; Grok/Composer take the assistant rows after the last real user row. A missing result/transcript, a non-agent session, or an unextractable message is an explicit error, never a silent empty.
 
 ### Completion detection (5 layers)
 
-`pty_read({ wait: true })` decides "is the command done?" via five layers: process exit / a `mark:true` sentinel (auto-detected — see below) / an `until` match (a literal substring by default; pass `until_regex: true` for a regex) / output is quiescent ∧ the shell is back (quiescence) / timeout. While nested (inside SSH, a container, a REPL, or a launched agent's TUI), the "shell is back" check cannot fire, so pass `until` with the inner prompt — or send with `mark: true` and `pty_read({ wait: true })` auto-detects the completion sentinel (no `until` needed, works nested too) — or, for a full-screen agent TUI, read `{ screen: true }` once its output settles. Agent sessions use the sixth, exact layer instead: the vendor Stop hook writes a completion event, `pty_send` dispatch returns the `event_cursor` boundary, and `aiterm-wait --cursor` observes the completion without the parent blocking or polling. Pre-send readiness failures are MCP errors for `pty_send`, while launch-time initial prompt readiness failures return the session with `initial_prompt=not_sent`. A late Claude completion remains recoverable from the same session with `pty_read({ agent_transcript:true })`, without resending. Normal `pty_read` on an agent session can append auxiliary metadata such as `agent_event_seen=true completion_attribution=none`, but a stale hook event is not promoted to `is_complete=True`. If a complete hook JSONL line is malformed, the `aiterm-wait` receipt counts it in `malformed_events` for diagnosis. If the turn is done but the terminal screen/log does not settle within the flush window, aiterm appends `agent_done_but_screen_unstable`.
+`pty_read({ wait: true })` decides "is the command done?" via five layers: process exit / a `mark:true` sentinel (auto-detected — see below) / an `until` match (a literal substring by default; pass `until_regex: true` for a regex) / output is quiescent ∧ the shell is back (quiescence) / timeout. While nested (inside SSH, a container, a REPL, or a launched agent's TUI), the "shell is back" check cannot fire, so pass `until` with the inner prompt — or send with `mark: true` and `pty_read({ wait: true })` auto-detects the completion sentinel (no `until` needed, works nested too) — or, for a full-screen agent TUI, read `{ screen: true }` once its output settles. Agent sessions use a sixth exact layer: Codex observes `task_complete` after the dispatch's transcript byte boundary; Claude/Grok observe their managed hook event after the event-file boundary. `aiterm-wait --cursor` performs that vendor-specific observation without the parent blocking or polling. Pre-send readiness failures are MCP errors for `pty_send`, while launch-time initial prompt readiness failures return the session with `initial_prompt=not_sent`. A late completion remains recoverable from the same session with `pty_read({ agent_transcript:true })`, without resending. Malformed complete JSONL records are counted in `malformed_events` for diagnosis rather than treated as done.
 
 ### Completion push for parent agents (`aiterm-wait`)
 
 As of v0.16 a parent agent **never blocks** on aiterm — there is no wait parameter anywhere (v0.17 makes the waiter's exit codes mirror its outcome). The whole flow is dispatch + one universal waiter:
 
 1. Launch the child (`claude_agent` / `codex_agent` / ...; every launch is managed). Send a turn with plain `pty_send` (or `claude_turn issue` for durable Claude operations). The call passes the TUI ready gate, submits, and returns immediately with an `event_cursor` in its structured receipt — plus a `submit_residue` observation: `true` means the sent text still lingered in the composer after submit (likely stranded; inspect the screen before re-pressing Enter), `false` means no residue was observed (not a proof of submission), `null` means not applicable.
-2. Run `aiterm-wait --session <id> --cursor <event_cursor> [--operation sha256:<64hex>] [--timeout <sec>]` (a launch with an initial `prompt` returns this command ready-made as `wait_command` in its structured receipt). It observes the vendor Stop-hook completion event as a **pure reader** and exits with a one-line `aiterm.agent-wait-result.v1` receipt. **Exit ≠ done**: the receipt's `outcome` is authoritative, and the exit code mirrors it — `0` = `done`, `3` = `timeout` (the turn is **not** finished; default `--timeout` is 600 s), `4` = `closed`, `1` = error. On `timeout` just re-run the waiter with the same cursor. The `--cursor` boundary makes it start-order independent: no completion can slip past even if the waiter starts late.
+2. Run `aiterm-wait --session <id> --cursor <event_cursor> [--operation sha256:<64hex>] [--timeout <sec>]` (a launch with an initial `prompt` returns this command ready-made as `wait_command` in its structured receipt). It observes the vendor completion source as a **pure reader**—Codex rollout `task_complete`, or a managed hook event for the other vendors—and exits with a one-line `aiterm.agent-wait-result.v1` receipt. **Exit ≠ done**: the receipt's `outcome` is authoritative, and the exit code mirrors it — `0` = `done`, `3` = `timeout` (the turn is **not** finished; default `--timeout` is 600 s), `4` = `closed`, `1` = error. On `timeout` just re-run the waiter with the same cursor. The `--cursor` boundary makes it start-order independent: no completion can slip past even if the waiter starts late.
 3. **The parent never runs the waiter in its own foreground.** Waiting is correct — but the waiter is a separate process, not the parent's turn. A harness that re-invokes its agent when a background task exits (Claude Code) runs the waiter **in the background** and gets woken with zero polling. So that this is not left to interpretation, aiterm reads `clientInfo.name` from the MCP `initialize` handshake and its receipts name the concrete invocation for the detected host — for Claude Code, literally `Bash(command: "aiterm-wait …", run_in_background: true)`. Unknown or undeclared hosts get the generic "start it as a process that does not block the parent's turn" wording; nothing else about the contract changes. Every receipt leads with the same rule: dispatch and let go, then go do something else or end the turn.
 4. Collect the result exactly as before: `pty_read(agent_transcript: true)`, or `claude_turn recover` for durable Claude operations. The waiter carries the signal, never the payload.
 

package/dist/core.js

@@ -56,6 +56,7 @@ const AGENT_DONE_SCREEN_SETTLE_MIN_SAMPLES = 3;
 const AGENT_SUBMIT_DELAY_MS = 250;
 const AGENT_EVENT_MAX_BYTES = 1024 * 1024;
 const AGENT_EVENT_TAIL_BYTES = 64 * 1024;
+const CODEX_TRANSCRIPT_INCREMENT_MAX_BYTES = 16 * 1024 * 1024;
 const AGENT_METADATA_NEGATIVE_CACHE_TTL_MS = 2_000;
 const AGENT_TUI_READY_TIMEOUT_MS = 30_000;
 const AGENT_TUI_READY_POLL_MS = 500;
@@ -411,6 +412,12 @@ function agentManagedClaudeSettingsPath(name, launchId) {
         throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
     return path.join(agentsDir(), `${name}.${launchId}.claude-settings.json`);
 }
+function agentManagedClaudeMcpConfigPath(name, launchId) {
+    assertSessionName(name);
+    if (!LAUNCH_ID_RE.test(launchId))
+        throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
+    return path.join(agentsDir(), `${name}.${launchId}.claude-mcp.json`);
+}
 function agentClaudeResultPath(name, launchId) {
     assertSessionName(name);
     if (!LAUNCH_ID_RE.test(launchId))
@@ -493,6 +500,7 @@ function cleanupAgentState(name) {
                     f.endsWith(".events.jsonl") ||
                     f.endsWith(".wait.lock") ||
                     f.endsWith(".claude-settings.json") ||
+                    f.endsWith(".claude-mcp.json") ||
                     f.endsWith(".claude-result.json") ||
                     f.endsWith(".claude-operation.json") ||
                     f.endsWith(".claude-approval.json") ||
@@ -1353,6 +1361,7 @@ export function killAll() {
                     f.endsWith(".events.jsonl") ||
                     f.endsWith(".wait.lock") ||
                     f.endsWith(".claude-settings.json") ||
+                    f.endsWith(".claude-mcp.json") ||
                     f.endsWith(".claude-result.json") ||
                     f.endsWith(".claude-operation.json") ||
                     f.endsWith(".claude-dispatch") ||
@@ -1378,15 +1387,18 @@ export function killAll() {
 const DEFAULT_AGENT_DONE_TIMEOUT = 600;
 const agentMetadataNegativeCache = new Map();
 let agentTuiReadyStableSamplesTestOverride = null;
-function codexHookScriptPath() {
-    return path.join(path.dirname(fileURLToPath(import.meta.url)), "codex-stop-hook.js");
-}
 function grokHookScriptPath() {
     return path.join(path.dirname(fileURLToPath(import.meta.url)), "grok-stop-hook.js");
 }
 function claudeHookScriptPath() {
     return path.join(path.dirname(fileURLToPath(import.meta.url)), "claude-stop-hook.js");
 }
+// process.execPath は Homebrew 等では Cellar の版付き実体を指す。長寿命 MCP server の起動後に
+// runtime が更新されるとその実体だけが消え、既に生成済みの hook が exit 127 になる。
+// hook は server と同じ継承 PATH から node を毎回解決し、安定した package script を実行する。
+function nodeHookCommand(hookScript) {
+    return `${shq("node")} ${shq(hookScript)}`;
+}
 function safeStatSize(p) {
     try {
         return fs.statSync(p).size;
@@ -1514,7 +1526,7 @@ function readCodexConfigPins(configPath) {
     };
     return { model: pick("model"), effort: pick("model_reasoning_effort") };
 }
-function managedCodexConfigSummary(configPath, hookTrustBypass) {
+function managedCodexConfigSummary(configPath) {
     let body;
     try {
         body = fs.readFileSync(configPath, "utf8");
@@ -1543,8 +1555,6 @@ function managedCodexConfigSummary(configPath, hookTrustBypass) {
         bits.push(`approval_policy=${approvalPolicy}`);
     if (sandboxMode)
         bits.push(`sandbox_mode=${sandboxMode}`);
-    if (hookTrustBypass)
-        bits.push("hook trust bypass 有効");
     return `managed config: ${bits.join(" / ")}`;
 }
 // Custom agent definitions are configuration, not mutable Codex state. Copy only direct
@@ -1626,27 +1636,9 @@ function createManagedCodexHome(name, launchId, overrides = {}) {
         fs.chmodSync(configDst, 0o600);
     }
     snapshotCodexAgentDefinitions(srcHome, managedHome);
-    const hookScript = codexHookScriptPath();
-    if (!fs.existsSync(hookScript)) {
-        throw new AitermError(`Codex Stop hook wrapper が見つかりません。npm run build を実行してください: ${hookScript}`, 2);
-    }
-    writeJson0600(path.join(managedHome, "hooks.json"), {
-        hooks: {
-            Stop: [
-                {
-                    hooks: [
-                        {
-                            type: "command",
-                            command: `${shq(process.execPath)} ${shq(hookScript)}`,
-                            timeoutSec: 10,
-                            async: false,
-                            statusMessage: null,
-                        },
-                    ],
-                },
-            ],
-        },
-    });
+    // Codex 自身の rollout transcript に task_complete が永続化されるため、完了検出用の
+    // Stop hook は作らない。hook と transcript の二重正本、および hook failure の単一障害点を
+    // ここでなくす。
     return managedHome;
 }
 function createManagedClaudeSettings(name, launchId) {
@@ -1662,7 +1654,7 @@ function createManagedClaudeSettings(name, launchId) {
                     hooks: [
                         {
                             type: "command",
-                            command: `${shq(process.execPath)} ${shq(hookScript)}`,
+                            command: nodeHookCommand(hookScript),
                             timeout: 10,
                         },
                     ],
@@ -1672,6 +1664,52 @@ function createManagedClaudeSettings(name, launchId) {
     });
     return settings;
 }
+function createManagedClaudeMcpConfig(name, launchId) {
+    const home = process.env.HOME?.trim() || os.homedir();
+    const source = path.join(home, ".claude.json");
+    let canonical;
+    try {
+        canonical = fs.realpathSync(source);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new AitermError(`Claude user MCP設定を読めません: ${error.message}`, 2);
+    }
+    let fd;
+    let parsed;
+    try {
+        fd = fs.openSync(canonical, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        const st = fs.fstatSync(fd);
+        if (!st.isFile() || st.uid !== currentUid() || st.size > 16 * 1024 * 1024) {
+            throw new AitermError("Claude user MCP設定の安全検証に失敗しました", 2);
+        }
+        parsed = JSON.parse(fs.readFileSync(fd, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof AitermError)
+            throw error;
+        throw new AitermError(`Claude user MCP設定を読めません: ${error.message}`, 2);
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new AitermError("Claude user MCP設定のtop-level JSONはobjectである必要があります", 2);
+    }
+    const servers = parsed.mcpServers;
+    if (servers === undefined)
+        return null;
+    if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+        throw new AitermError("Claude user MCP設定のmcpServersはobjectである必要があります", 2);
+    }
+    if (Object.keys(servers).length === 0)
+        return null;
+    const destination = agentManagedClaudeMcpConfigPath(name, launchId);
+    writeJson0600(destination, { mcpServers: servers });
+    return destination;
+}
 function realGrokHome() {
     return path.resolve(process.env.GROK_HOME || path.join(process.env.HOME ?? os.homedir(), ".grok"));
 }
@@ -1775,7 +1813,7 @@ function createManagedGrokHome(name, launchId, authPath) {
                     hooks: [
                         {
                             type: "command",
-                            command: `${shq(process.execPath)} ${shq(hookScript)}`,
+                            command: nodeHookCommand(hookScript),
                             timeout: 10,
                         },
                     ],
@@ -2243,6 +2281,7 @@ function createClaudeAgentMetadata(name, cwd, initialPrompt, launchOperationId,
     createEmpty0600NoFollow(eventFile);
     createEmpty0600NoFollow(resultFile);
     const claudeSettings = createManagedClaudeSettings(name, launchId);
+    const claudeMcpConfig = createManagedClaudeMcpConfig(name, launchId);
     const meta = {
         kind: "claude",
         aiterm_session: name,
@@ -2257,6 +2296,7 @@ function createClaudeAgentMetadata(name, cwd, initialPrompt, launchOperationId,
         hook_route: "managed_claude_settings",
         node_platform: process.platform,
         claude_settings: claudeSettings,
+        claude_mcp_config: claudeMcpConfig,
         result_file: resultFile,
     };
     writeAgentMetadata(meta);
@@ -2278,6 +2318,7 @@ function createCodexAgentMetadata(name, cwd, initialPrompt, overrides = {}, writ
         vendor_session_id: null,
         initial_prompt: initialPrompt,
         hook_route: "managed_codex_home",
+        completion_route: "codex_transcript",
         node_platform: process.platform,
         codex_home: codexHome,
     };
@@ -2340,11 +2381,14 @@ function loadAgentMetadata(name) {
     }
     if (m.kind === "claude") {
         const expectedSettings = agentManagedClaudeSettingsPath(name, m.launch_id);
+        const expectedMcpConfig = agentManagedClaudeMcpConfigPath(name, m.launch_id);
         const expectedResult = agentClaudeResultPath(name, m.launch_id);
+        const claudeMcpConfig = m.claude_mcp_config ?? null;
         const launchOperationId = m.launch_operation_id ?? null;
         const launchRequestDigest = m.launch_request_digest ?? null;
         if (m.hook_route !== "managed_claude_settings" ||
             m.claude_settings !== expectedSettings ||
+            (claudeMcpConfig !== null && claudeMcpConfig !== expectedMcpConfig) ||
             m.result_file !== expectedResult ||
             ((launchOperationId === null) !== (launchRequestDigest === null)) ||
             (launchOperationId !== null && !OPERATION_ID_RE.test(launchOperationId)) ||
@@ -2366,6 +2410,7 @@ function loadAgentMetadata(name) {
             hook_route: "managed_claude_settings",
             node_platform: process.platform,
             claude_settings: expectedSettings,
+            claude_mcp_config: claudeMcpConfig === expectedMcpConfig ? expectedMcpConfig : null,
             result_file: expectedResult,
         };
     }
@@ -2385,6 +2430,7 @@ function loadAgentMetadata(name) {
             vendor_session_id: typeof m.vendor_session_id === "string" ? m.vendor_session_id : null,
             initial_prompt: normalizeInitialPromptState(m.initial_prompt),
             hook_route: "managed_codex_home",
+            ...(m.completion_route === "codex_transcript" ? { completion_route: "codex_transcript" } : {}),
             node_platform: process.platform,
             codex_home: expectedHome,
         };
@@ -2508,6 +2554,15 @@ function bindAgentVendorSession(meta, ev) {
 function bindCompletedInitialPrompt(meta) {
     if (meta.initial_prompt !== "pending" && meta.initial_prompt !== "sent")
         return;
+    if (meta.kind === "codex") {
+        const done = latestCodexCompletion(meta);
+        if (!done) {
+            throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了待ちです。${agentWaitGuide(meta.aiterm_session)}`, 2);
+        }
+        bindAgentVendorSession(meta, done);
+        setInitialPromptState(meta, "done");
+        return;
+    }
     if (meta.vendor_session_id) {
         setInitialPromptState(meta, "done");
         return;
@@ -2540,6 +2595,8 @@ function tryLoadAgentMetadata(name) {
     }
 }
 function latestAgentDoneEvent(meta, expectedOperationId = null) {
+    if (meta.kind === "codex")
+        return latestCodexCompletion(meta);
     const size = safeStatSize(meta.event_file);
     if (size === 0)
         return null;
@@ -2594,6 +2651,14 @@ function completedClaudeOperationEvent(meta, operationId) {
 function recoverAgentVendorSession(meta) {
     if (meta.vendor_session_id)
         return;
+    if (meta.kind === "codex") {
+        const transcript = bindCodexTranscriptSession(meta);
+        if (!transcript)
+            return;
+        if (meta.initial_prompt === "pending" && latestCodexCompletion(meta))
+            setInitialPromptState(meta, "done");
+        return;
+    }
     const size = safeStatSize(meta.event_file);
     if (size === 0)
         return;
@@ -2647,6 +2712,116 @@ function findLatestCodexTranscript(codexHome, vendorSessionId) {
     visit(sessionsDir);
     return latestFile;
 }
+function listCodexTranscripts(codexHome) {
+    const sessionsDir = path.join(codexHome, "sessions");
+    const files = [];
+    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);
+            else if (entry.isFile() && entry.name.startsWith("rollout-") && entry.name.endsWith(".jsonl"))
+                files.push(file);
+        }
+    };
+    visit(sessionsDir);
+    // managed CODEX_HOME では root TUI の rollout が最初に作られる。後から同じ home に
+    // sub-agent rollout が増えても root を取り違えないよう、未bind時は最古を選べる順にする。
+    return files.sort();
+}
+function codexTranscriptSessionId(file) {
+    const size = Math.min(safeStatSize(file), AGENT_EVENT_TAIL_BYTES);
+    if (size === 0)
+        return null;
+    const text = readFileRange(file, 0, size).toString("utf8");
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const record = JSON.parse(line);
+            if (record?.type === "session_meta" && typeof record?.payload?.id === "string" && record.payload.id) {
+                return record.payload.id;
+            }
+        }
+        catch {
+            // startup中の未完結行は後のpollで読み直す。
+        }
+    }
+    return null;
+}
+function codexRootTranscript(meta) {
+    if (meta.kind !== "codex" || !meta.codex_home)
+        return null;
+    if (meta.vendor_session_id)
+        return findLatestCodexTranscript(meta.codex_home, meta.vendor_session_id);
+    return listCodexTranscripts(meta.codex_home)[0] ?? null;
+}
+function bindCodexTranscriptSession(meta) {
+    const transcript = codexRootTranscript(meta);
+    if (!transcript)
+        return null;
+    const vendorSessionId = codexTranscriptSessionId(transcript);
+    if (vendorSessionId && !meta.vendor_session_id) {
+        meta.vendor_session_id = vendorSessionId;
+        writeAgentMetadata(meta);
+    }
+    return transcript;
+}
+function codexCompletionEvent(meta, vendorSessionId, record) {
+    if (record?.type !== "event_msg" ||
+        record?.payload?.type !== "task_complete" ||
+        typeof record?.payload?.turn_id !== "string" ||
+        !record.payload.turn_id)
+        return null;
+    return {
+        type: "agent_done",
+        vendor: "codex",
+        aiterm_session: meta.aiterm_session,
+        launch_id: meta.launch_id,
+        vendor_session_id: vendorSessionId,
+        turn_id: record.payload.turn_id,
+        operation_id: null,
+        reason: "Codex transcript task_complete",
+        done_status: "turn_done",
+        stop_hook_active: false,
+        at: typeof record.timestamp === "string" ? record.timestamp : new Date().toISOString(),
+    };
+}
+function latestCodexCompletion(meta) {
+    const transcript = codexRootTranscript(meta);
+    if (!transcript)
+        return null;
+    const vendorSessionId = meta.vendor_session_id ?? codexTranscriptSessionId(transcript);
+    let latest = null;
+    for (const line of readTranscriptLines(transcript)) {
+        if (!line.trim())
+            continue;
+        try {
+            latest = codexCompletionEvent(meta, vendorSessionId, JSON.parse(line)) ?? latest;
+        }
+        catch {
+            // Codexが末尾を書込み中なら、その行は次の観測で完結してから読む。
+        }
+    }
+    return latest;
+}
+function agentCompletionCursor(meta) {
+    if (meta.kind !== "codex")
+        return safeStatSize(meta.event_file);
+    const transcript = bindCodexTranscriptSession(meta);
+    if (meta.completion_route !== "codex_transcript") {
+        meta.completion_route = "codex_transcript";
+        writeAgentMetadata(meta);
+    }
+    return transcript ? safeStatSize(transcript) : 0;
+}
 function transcriptUnavailable() {
     throw new AitermError(`transcript がまだありません。ターン完了後に再取得してください。${agentWaitGuide()}`, 2);
 }
@@ -2927,9 +3102,83 @@ export function agentWaitGuide(session) {
     const cmd = `aiterm-wait --session ${session ?? "<session_id>"} --cursor 0`;
     return `完了通知は ${agentWaitLaunchForm(cmd)} で受ける（親はここで待たない・polling 不要）。receipt の outcome=done を確認してから再取得する。`;
 }
+async function observeCodexDone(meta, timeout, requestedCursor) {
+    const metadataFile = agentMetadataPath(meta.aiterm_session, meta.launch_id);
+    let transcript = codexRootTranscript(meta);
+    const startOffset = requestedCursor ?? (transcript ? safeStatSize(transcript) : 0);
+    let cursor = startOffset;
+    let carry = "";
+    let malformedEvents = 0;
+    let discardLeadingFragment = false;
+    let initializedBoundary = false;
+    const deadline = performance.now() + timeout * 1000;
+    const observation = (outcome, ev = null) => ({
+        schema: "aiterm.agent-wait-result.v1",
+        session_id: meta.aiterm_session,
+        launch_id: meta.launch_id,
+        vendor: "codex",
+        outcome,
+        operation_id: null,
+        vendor_session_id: ev?.vendor_session_id ?? meta.vendor_session_id ?? null,
+        turn_id: ev?.turn_id ?? null,
+        malformed_events: malformedEvents,
+        at: ev?.at ?? null,
+    });
+    for (;;) {
+        if (!fs.existsSync(metadataFile))
+            return observation("closed");
+        transcript ??= codexRootTranscript(meta);
+        if (transcript) {
+            if (!initializedBoundary) {
+                if (cursor > 0) {
+                    const previous = readFileRange(transcript, cursor - 1, cursor).toString("utf8");
+                    discardLeadingFragment = previous !== "\n";
+                }
+                initializedBoundary = true;
+            }
+            const size = safeStatSize(transcript);
+            if (size < cursor) {
+                throw new AitermError("Codex transcript が完了待機中に短くなりました。該当セッションを閉じて起動し直してください。", 2);
+            }
+            if (size - startOffset > CODEX_TRANSCRIPT_INCREMENT_MAX_BYTES) {
+                throw new AitermError("Codex transcript のturn増分が大きすぎます。該当セッションを閉じて起動し直してください。", 2);
+            }
+            if (size > cursor) {
+                carry += readFileRange(transcript, cursor, size).toString("utf8");
+                cursor = size;
+                const parts = carry.split("\n");
+                carry = parts.pop() ?? "";
+                if (discardLeadingFragment && parts.length > 0) {
+                    parts.shift();
+                    discardLeadingFragment = false;
+                }
+                const vendorSessionId = meta.vendor_session_id ?? codexTranscriptSessionId(transcript);
+                for (const line of parts) {
+                    if (!line.trim())
+                        continue;
+                    if (Buffer.byteLength(line, "utf8") > AGENT_EVENT_MAX_BYTES) {
+                        malformedEvents++;
+                        continue;
+                    }
+                    try {
+                        const done = codexCompletionEvent(meta, vendorSessionId, JSON.parse(line));
+                        if (done)
+                            return observation("done", done);
+                    }
+                    catch {
+                        malformedEvents++;
+                    }
+                }
+            }
+        }
+        if (performance.now() >= deadline)
+            return observation(timeout === 0 ? "running" : "timeout");
+        await sleep(AGENT_DONE_POLL_MS);
+    }
+}
 // 外部waiterプロセス用の純リーダー観測。lock・PTY・metadata書込・dispatch状態には一切触れない。
-// event fileのtail規律（未終端行保持・増分上限）はwaitAgentDoneEventと同一だが、
-// vendor_session_idのbind永続化を行わない点だけ意図的に異なる（waiterは観測者であって所有者でない）。
+// Codexはrollout transcript、他vendorはevent fileを増分走査し、vendor_session_idのbind永続化を
+// 行わない（waiterは観測者であって所有者でない）。
 export async function observeAgentDone(name, o = {}) {
     const meta = loadAgentMetadata(name);
     const operationId = o.operation_id == null ? null : validateOperationId(o.operation_id);
@@ -2940,6 +3189,9 @@ export async function observeAgentDone(name, o = {}) {
         throw new AitermError("cursor は0以上の整数byte offsetで指定してください", 2);
     }
     const timeout = o.timeout ?? DEFAULT_AGENT_DONE_TIMEOUT;
+    if (meta.kind === "codex" && meta.completion_route === "codex_transcript") {
+        return observeCodexDone(meta, timeout, o.cursor);
+    }
     const metadataFile = agentMetadataPath(meta.aiterm_session, meta.launch_id);
     // 境界の優先順: dispatch receipt の event_cursor（起動順序に依存しない）→ operation相関
     // （operation_idの一意性で先頭から全走査できる）→ waiter起動時EOF（waiter先行起動が前提）。
@@ -3203,7 +3455,7 @@ export async function sendInitialAgentPrompt(name, text, o = {}) {
             submit_residue: null,
         };
     }
-    const startOffset = safeStatSize(meta.event_file);
+    const startOffset = agentCompletionCursor(meta);
     try {
         if (meta.kind === "claude") {
             prepareSendText(text, { raw: false, force: true });
@@ -3230,7 +3482,7 @@ export function isAgentSession(name) {
     return tryLoadAgentMetadata(name) !== null;
 }
 // v0.16.0: 親をブロックする wait 経路は廃止した。send は ready gate と submit 分離を内蔵した
-// dispatch として即返り、event_cursor（送信直前の event file 境界）を receipt で返す。
+// dispatch として即返り、event_cursor（送信直前のvendor完了正本境界）を receipt で返す。
 // 完了通知は aiterm-wait（--cursor で境界を渡す）、回収は pty_read / claude_turn recover が担う。
 export async function dispatchAgentTurn(name, text, o = {}) {
     assertSessionName(name);
@@ -3241,14 +3493,16 @@ export async function dispatchAgentTurn(name, text, o = {}) {
         throw new AitermError("operation_id はClaude agent sessionだけで使用できます", 2);
     }
     bindCompletedInitialPrompt(meta);
-    if (!meta.vendor_session_id) {
+    // Codexはbind済みのfollow-upでも毎回idleを確認してからtranscript境界を切る。同じcursorへ
+    // 複数turnを帰属させる余地を作らない。他vendorの既存dispatch条件は変えない。
+    if (meta.kind === "codex" || !meta.vendor_session_id) {
         const ready = await waitAgentTuiReady(name, meta, o.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
         if (!ready.ready) {
             throw new AitermError(`agent session '${name}' の ${agentLabel(meta.kind)} TUI が入力受付状態になりません。文字列は送信していません。` +
                 "少し後で pty_read(screen:true) を確認し、TUI が起動済みなら再度 pty_send してください。", 2);
         }
     }
-    const startOffset = safeStatSize(meta.event_file);
+    const startOffset = agentCompletionCursor(meta);
     if (meta.kind === "claude") {
         // durable／anonymousを分岐する前に同じsend preflightを通す。拒否されるpromptの
         // receipt／active markerだけを残して、来ないStopを待つ状態を作らない。
@@ -3445,6 +3699,8 @@ function buildAgentCmd(kind, bin, model, effort, prompt, meta = null) {
     if (kind === "claude") {
         if (meta?.kind === "claude") {
             parts.push("--setting-sources", shq(""), "--settings", shq(meta.claude_settings ?? ""));
+            if (meta.claude_mcp_config)
+                parts.push("--mcp-config", shq(meta.claude_mcp_config));
         }
         if (model)
             parts.push("--model", shq(model));
@@ -3452,8 +3708,6 @@ function buildAgentCmd(kind, bin, model, effort, prompt, meta = null) {
             parts.push("--effort", shq(effort));
     }
     else if (kind === "codex") {
-        if (meta?.kind === "codex")
-            parts.push("--dangerously-bypass-hook-trust");
         // `codex --help` で確認した実在フラグ。read-only 宣言だけはCLI sandboxへ落とし、
         // launcher自身が実効能力壁を作る。パス説明はCodex CLIに同等のallowlist引数がないため宣言のまま残す。
         if (meta?.kind === "codex" && meta.write_scope === "read-only")
@@ -3554,7 +3808,7 @@ function buildAgentLaunchNote(kind, model, effort, meta) {
         (effectiveEffort === "ultra"
             ? "⚠ effort=ultra は max 推論＋proactive 自動委譲 ON（子エージェント自動生成・使用量急増に注意）。"
             : "");
-    const summary = meta?.kind === "codex" && meta.codex_home ? managedCodexConfigSummary(configPath, true) : "";
+    const summary = meta?.kind === "codex" && meta.codex_home ? managedCodexConfigSummary(configPath) : "";
     return (summary ? `${launch}\n${summary}\n` : launch) + writeScopeNote;
 }
 function claudeLaunchRequestDigest({ sessionName, model, effort, cwd, agentDone, }) {

package/dist/index.js

@@ -487,13 +487,13 @@ function registerAgentTool(toolName, kind, desc) {
                 wait_command: eventCursor === null ? null : `aiterm-wait --session ${sid} --cursor ${eventCursor}`,
                 submit_residue: submitResidue,
                 ...(supportsWriteScope && write_scope !== undefined
-                    ? {}
-                    : supportsWriteScope ? {
+                    ? {
                         write_scope,
                         write_scope_enforcement: kind === "codex" && write_scope === "read-only"
                             ? "enforced_read_only"
                             : "declaration_only_unsupported",
-                    } : {}),
+                    }
+                    : {}),
             };
             return {
                 content: [{ type: "text", text: `session_id: ${sid}\n${hint}` }],
@@ -511,6 +511,9 @@ registerAgentTool("claude_agent", "claude", "【Claude Code (Anthropic)】の対
     agentCompletionDesc +
     "Claude の durable turn は claude_turn でも回収できる。");
 registerAgentTool("codex_agent", "codex", "【Codex (OpenAI)】の対話エージェント TUI を永続端末に起動する。実装・レビュー・調査を対話で回す。" +
+    "委譲契約を使う完全な呼び出し例: " +
+    '`codex_agent({"prompt":"<依頼>","model":"gpt-5.6-sol","reasoning_effort":"high",' +
+    '"cwd":"/absolute/path/to/repo","write_scope":"read-only"})`。' +
     "turn は pty_send で送る（自動で非ブロック dispatch になる）。" +
     agentCompletionDesc +
     "model / reasoning_effort を引数で指定可" +

package/dist/runtime-error-store.js

@@ -281,7 +281,7 @@ function validateState(value, maxRecords = 256) {
         records: typed.map((record) => projectRecord(record)),
     };
 }
-function processStartIdentity(pid, platform) {
+function processStartIdentity(pid, platform, timeoutMs = 1000) {
     if (!Number.isInteger(pid) || pid < 1)
         return null;
     if (platform === "linux") {
@@ -298,7 +298,7 @@ function processStartIdentity(pid, platform) {
     if (platform === "win32") {
         const script = "$p=Get-Process -Id $env:AITERMMCP_PROCESS_ID -ErrorAction Stop; $p.StartTime.ToUniversalTime().Ticks";
         const result = spawnSync("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script], {
-            encoding: "utf8", timeout: 1000, maxBuffer: 4096, windowsHide: true,
+            encoding: "utf8", timeout: timeoutMs, maxBuffer: 4096, windowsHide: true,
             env: { ...process.env, AITERMMCP_PROCESS_ID: String(pid) },
         });
         const value = result.status === 0 ? (result.stdout ?? "").trim() : "";
@@ -503,7 +503,8 @@ export class RuntimeErrorStore {
                 || (info.mode & 0o777) !== 0o700)
                 throw new Error("runtime error lock queue のowner/modeが不正です");
         }
-        const startId = processStartIdentity(process.pid, this.platform);
+        const identityTimeoutMs = this.platform === "win32" ? this.windowsAclTimeoutMs : 1000;
+        const startId = processStartIdentity(process.pid, this.platform, identityTimeoutMs);
         if (!startId)
             throw new Error("process start identity を取得できません");
         const owner = { pid: process.pid, start_id: startId, token: randomBytes(16).toString("hex") };
@@ -548,7 +549,7 @@ export class RuntimeErrorStore {
                     }
                     if (name !== `choosing-${current.token}.json`)
                         throw new Error("runtime error choosing entry が不正です");
-                    const identity = processStartIdentity(current.pid, this.platform);
+                    const identity = processStartIdentity(current.pid, this.platform, identityTimeoutMs);
                     const live = identity === current.start_id || (!identity && processExists(current.pid));
                     if (live)
                         hasLiveChoosing = true;
@@ -583,7 +584,7 @@ export class RuntimeErrorStore {
                     }
                     if (!name.endsWith(`-${current.token}.ticket`))
                         throw new Error("runtime error lock ticket が不正です");
-                    const identity = processStartIdentity(current.pid, this.platform);
+                    const identity = processStartIdentity(current.pid, this.platform, identityTimeoutMs);
                     const live = identity === current.start_id || (!identity && processExists(current.pid));
                     if (!live) {
                         try {
@@ -824,13 +825,17 @@ function forceKill(child) {
         catch { /* already exited */ }
         return;
     }
+    // taskkill 自体の起動が混雑した Windows runner で遅れても、deadline を越えた
+    // worker 本体の副作用を許さない。まず Node のハンドルから即時停止し、その後に
+    // taskkill /T で worker が残した子孫だけを回収する。
+    try {
+        child.kill("SIGKILL");
+    }
+    catch { /* already exited */ }
     const killer = spawn("taskkill.exe", ["/pid", String(child.pid), "/T", "/F"], {
         stdio: "ignore", windowsHide: true,
     });
-    killer.once("error", () => { try {
-        child.kill("SIGKILL");
-    }
-    catch { /* already exited */ } });
+    killer.once("error", () => { });
     killer.unref();
 }
 function processExists(pid) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.21.0",
+  "version": "0.21.4",
   "mcpName": "io.github.kitepon-rgb/aiterm-mcp",
   "description": "Persistent tmux terminal MCP that lets Claude Code drive Codex CLI's interactive TUI, including slash commands and $imagegen. Also runs durable PTY sessions for SSH, containers, REPLs, and coding agents.",
   "keywords": [
@@ -52,7 +52,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/clean-build.mjs && tsc",
     "mcpb:build": "npm run build && node scripts/build-mcpb.mjs && npm ci --omit=dev --ignore-scripts --no-audit --no-fund --prefix dist/mcpb-stage/server && npx --yes @anthropic-ai/mcpb@2.1.2 validate dist/mcpb-stage/manifest.json && npx --yes @anthropic-ai/mcpb@2.1.2 pack dist/mcpb-stage dist/aiterm-mcp.mcpb",
     "verify:release-commit": "node scripts/verify-release-commit.mjs",
     "prepublishOnly": "npm run verify:release-commit && npm run build",

package/dist/codex-stop-hook.js

@@ -1,128 +0,0 @@
-#!/usr/bin/env node
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-const LAUNCH_ID_RE = /^[0-9a-f]{32}$/;
-const SESSION_RE = /^[A-Za-z0-9_-]{1,64}$/;
-const MAX_STDIN_BYTES = 1024 * 1024;
-function fail(message) {
-    process.stderr.write(`aiterm codex-stop-hook: ${message}\n`);
-    process.stdout.write(JSON.stringify({ continue: false }) + "\n");
-    process.exit(0);
-}
-function noop() {
-    process.stdout.write(JSON.stringify({ continue: false }) + "\n");
-    process.exit(0);
-}
-function hasAitermEnv() {
-    return !!(process.env.AITERM_AGENT_KIND ||
-        process.env.AITERM_SESSION_ID ||
-        process.env.AITERM_AGENT_SESSION_ID ||
-        process.env.AITERM_AGENT_LAUNCH_ID);
-}
-function uid() {
-    if (typeof process.getuid !== "function")
-        fail("POSIX getuid が使えません");
-    return process.getuid();
-}
-function runtimeStateBase() {
-    const xdg = process.env.XDG_RUNTIME_DIR;
-    if (xdg) {
-        try {
-            if (fs.statSync(xdg).isDirectory())
-                return xdg;
-        }
-        catch {
-            /* XDG_RUNTIME_DIR が壊れている CI/非 login 環境では os.tmpdir() に戻す */
-        }
-    }
-    return os.tmpdir();
-}
-function secureAgentsDir() {
-    const root = path.join(runtimeStateBase(), `aiterm-mcp-${uid()}`);
-    const agents = path.join(root, "agents");
-    const rst = fs.lstatSync(root);
-    if (!rst.isDirectory() || rst.isSymbolicLink() || rst.uid !== uid() || (rst.mode & 0o077) !== 0) {
-        fail(`agent state root が安全ではありません: ${root}`);
-    }
-    const ast = fs.lstatSync(agents);
-    if (!ast.isDirectory() || ast.isSymbolicLink() || ast.uid !== uid() || (ast.mode & 0o077) !== 0) {
-        fail(`agent state dir が安全ではありません: ${agents}`);
-    }
-    return agents;
-}
-function str(v) {
-    return typeof v === "string" ? v : null;
-}
-async function readStdin() {
-    const chunks = [];
-    let total = 0;
-    for await (const chunk of process.stdin) {
-        const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
-        total += b.length;
-        if (total > MAX_STDIN_BYTES)
-            fail("payload が大きすぎます");
-        chunks.push(b);
-    }
-    return Buffer.concat(chunks).toString("utf8");
-}
-function appendEvent(file, event) {
-    const nofollow = fs.constants.O_NOFOLLOW ?? 0;
-    const line = JSON.stringify(event) + "\n";
-    if (Buffer.byteLength(line, "utf8") > 64 * 1024)
-        fail("event line が大きすぎます");
-    const fd = fs.openSync(file, fs.constants.O_CREAT | fs.constants.O_APPEND | fs.constants.O_WRONLY | nofollow, 0o600);
-    try {
-        const st = fs.fstatSync(fd);
-        if (!st.isFile() || st.uid !== uid() || st.nlink !== 1 || (st.mode & 0o077) !== 0) {
-            fail(`event file が安全ではありません: ${file}`);
-        }
-        const written = fs.writeSync(fd, line, undefined, "utf8");
-        if (written < Buffer.byteLength(line, "utf8")) {
-            fs.ftruncateSync(fd, st.size);
-            fail(`event file への書込みが途中で終了しました: ${file}`);
-        }
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-}
-async function main() {
-    if (!hasAitermEnv())
-        noop();
-    const kind = process.env.AITERM_AGENT_KIND;
-    const session = process.env.AITERM_SESSION_ID || process.env.AITERM_AGENT_SESSION_ID || "";
-    const launchId = process.env.AITERM_AGENT_LAUNCH_ID || "";
-    if (kind !== "codex")
-        fail(`AITERM_AGENT_KIND が codex ではありません: ${kind ?? ""}`);
-    if (!SESSION_RE.test(session))
-        fail(`session id が不正です: ${session}`);
-    if (!LAUNCH_ID_RE.test(launchId))
-        fail(`launch id が不正です: ${launchId}`);
-    let payload = {};
-    const input = await readStdin();
-    if (input.trim()) {
-        try {
-            payload = JSON.parse(input);
-        }
-        catch {
-            payload = {};
-        }
-    }
-    const agents = secureAgentsDir();
-    const eventFile = path.join(agents, `${session}.${launchId}.events.jsonl`);
-    appendEvent(eventFile, {
-        type: "agent_done",
-        vendor: "codex",
-        aiterm_session: session,
-        launch_id: launchId,
-        vendor_session_id: str(payload.session_id),
-        turn_id: str(payload.turn_id),
-        reason: str(payload.hook_event_name) ?? "Stop",
-        done_status: "turn_done",
-        stop_hook_active: !!payload.stop_hook_active,
-        at: new Date().toISOString(),
-    });
-    process.stdout.write(JSON.stringify({ continue: false }) + "\n");
-}
-main().catch((e) => fail(e instanceof Error ? e.message : String(e)));