aiterm-mcp 0.31.2 → 0.33.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.33.0] - 2026-09-09
+
+### Added
+
+- `pty_list`の構造化結果と明示した非秘密環境変数の照会、`pty_observe`によるpane／harnessの生存、native process identity、状態、token hint、画面・CPU活動の観測を追加した。
+- 通常PTYにも`AITERM_SESSION_ID`を注入し、`pty_open`の`env_vars`で帰属情報を継承できる。古いtmuxの環境注入も製品内で扱う。
+- `agent_approval`でCodexのcommand／MCP承認をinspectし、digestへ束縛した単発許可・拒否を送れる。
+- `agent_launch`へ`trust_project`、起動準備の`startup`、初手の`initial_prompt` receiptを追加した。promptなしでも明示したproject信頼に基づく既知の起動準備を完了する。
+
+### Fixed
+
+- Grokの通信失敗＋Waiting表示、Codexの過去の承認画面を稼働状態と誤認しない。初手は実行表示または相関した完了で開始を確認する。
+- Codexの設定読込失敗でCLIが終了した後、残った起動画面へpromptを送る問題を修理した。送信前にharnessの生存を確認し、未送信の構造化エラーで返す。
+- `mark:true`でheredoc終端へsentinelを連結して構文を壊す問題を修理した。
+
+## [0.32.0] - 2026-09-09
+
+### Added
+
+- `aiterm-setup`を追加した。公式package managerによる依存準備、MCP経由の端末実行、検出したClaude Code・Codex・Grok・Cursorへの登録と確認を製品が所有する。対応外・未検出・失敗は公開JSONで区別する。
+
+### Fixed
+
+- Windowsでスラッシュ区切りのcwdを指定したGrok／Composerの完了通知と回答を取得できない問題を修正した。Grok CLIと同じ絶対パスへ正規化して両方の記録を読む。
+- Grok／Composerの次turn開始後に、途中の回答を前turnの完了ID付きで返す問題を修正した。
+- psmuxの最低版を実際のpsmux版数で検証し、winget導入直後の既存PATHからも公式配置を解決する。
+- Windowsでrelease中のnpm起動がENOENTになる問題を修正し、起動元npmのJS入口をNodeで呼ぶ。
+
 ## [0.31.2] - 2026-09-08
 
 ### Fixed
@@ -1570,7 +1598,9 @@ prototype (preserved under `prototype/python/` as the porting source and referen
   `ubuntu-latest` for Node 18/20/22, publishing to npm on `v*` tags with
   provenance.
 
-[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.2...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.33.0...HEAD
+[0.33.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.32.0...v0.33.0
+[0.32.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.2...v0.32.0
 [0.31.2]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.1...v0.31.2
 [0.31.1]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.0...v0.31.1
 [0.31.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.30.0...v0.31.0

package/README.ja.md

@@ -28,6 +28,24 @@
 
 ## MCPクライアントへ導入
 
+検出したClaude Code・Codex・Grok・Cursorのユーザー設定へ登録する標準入口:
+
+```bash
+npm install -g aiterm-mcp@latest
+aiterm-setup --json
+```
+
+`aiterm-setup`は端末の依存準備、MCP経由の端末実行、登録と読戻しまでを一回で行う。
+WindowsはwingetでPowerShell 7・Git for Windows・psmux、macOSはHomebrewでtmux、
+Ubuntu／Debianはsudoとaptでtmuxを準備する。必要な公式package managerと実行権限は事前に必要。
+他のLinuxでも既存tmuxを利用できるが、自動導入は`unsupported`で停止する。
+既存設定の他サーバーを保持し、JSON設定は変更前の`.aiterm-backup`を残す。
+結果の`status`は`ready`／`unsupported`／`failed`。未検出のAIは`not_detected`とし、全AI未検出は成功にしない。
+登録先はglobal packageのNodeとMCP入口の絶対パスで、npm一時cacheやsource checkoutは登録しない。
+更新後も同じ入口を実行し、MCP clientを再起動する。npm install自体はユーザー設定を変更しない。
+公開JSONは`schema: "aiterm.setup-result.v1"`、全体の`status`、端末の`backend`、
+AI別の`integrations`を持つ。失敗時は`reason_code`を付け、終了コードはreadyなら0、それ以外は2となる。
+
 cloneもビルドも不要。どのクライアントでも公開パッケージを次のコマンドで起動する:
 
 ```bash
@@ -94,7 +112,7 @@ diagnostics、recovery、update、releaseを所有します。このREADMEと[
 
 **言葉でなく実測で:** 記録済み203テストのベンチマークでは、`pty_read` はコンテキストに載るトークンを生ログの **約 7.1 分の 1** に減らす。しかも pass/fail の判定は畳んでも残る。→ [組み込みシェルツールとの使い分け](#組み込みシェルツールとの使い分け)
 
-16ツール: 6つのPTYツール、正規のagent起動入口`agent_launch`、実行中のCodex／Grokを誘導する`agent_steer`、移行用の旧4alias、`agent_configure`、`claude_turn`、`claude_approval`、`diagnostics`。backendはPOSIXのtmux／Windows nativeのpsmuxなので、MCPサーバやAIクライアントが再起動してもsessionは生き残る。
+18ツール: 7つのPTYツール、正規のagent起動入口`agent_launch`、実行中のCodex／Grokを誘導する`agent_steer`、移行用の旧4alias、`agent_configure`、`agent_approval`、`claude_turn`、`claude_approval`、`diagnostics`。backendはPOSIXのtmux／Windows nativeのpsmuxなので、MCPサーバやAIクライアントが再起動してもsessionは生き残る。
 
 **v0.28.0では実行基盤harnessとmodelを分離した。** harnessはagent loop・認証・hook・session・transcriptを所有し、modelはその上で選ぶ。Cursor Agent CLIでGPT／Claude／Grokを選んでも完了契約はCursor方式のまま。Composerは別harnessではなく、`harness:"grok-cli", model:"grok-composer-2.5-fast"`で表す。旧4起動ツールは同じ実装へ流れる互換alias。
 
@@ -153,13 +171,13 @@ runtime-error store は canonical dotagents config の `collection.enabled: true
 場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
 Publishing）で公開し、GitHub Release が Official MCP Registry を再登録します。
 
-**状態:** 開発継続中 · 現行公開版 **v0.31.2** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.33.0** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
 npm packageが単独配布の正本であり、dotagentsは介在しません。global installは
-`npm install -g aiterm-mcp@latest`で更新します。巻き戻す時は
-`npm install -g "aiterm-mcp@<known-good-version>"`のように既知の正常versionを明示し、MCP clientを再起動します。
+`npm install -g aiterm-mcp@latest`で更新し、`aiterm-setup --json`を再実行します。巻き戻す時は
+`npm install -g "aiterm-mcp@<known-good-version>"`のように既知の正常versionを明示します。setupを持つ版では同じ入口を再実行し、MCP clientを再起動します。
 `npx`設定では`aiterm-mcp@latest`へ変えると更新でき、`aiterm-mcp@<version>`へ変えると固定・巻き戻し
 できます。downgrade前に[変更履歴](CHANGELOG.md)でstate／schema互換を確認してください。maintainer向けの
 公開物とreleaseの巻き戻しは、製品所有の[release手順](docs/RELEASE.md)を正とします。
@@ -197,7 +215,7 @@ Grok／Composerの無人起動は公式`--trust`で指定された作業フォ
 
 Grok／Composerがread-only sandboxの適用を拒否した場合、prompt送信時に`GROK_SANDBOX_STARTUP_FAILED`とCLIの原因を返す。例えばhookのパスにシンボリックリンクがあるとGrok CLIは起動を拒否する。設定の管理元で原因を修正し、対象sessionを`pty_close`して起動し直す。Aitermはsandboxを解除したりhookをコピーしたりしない。
 
-この判定はGrok専用アダプターが所有し、同じCLIを使うComposerにも適用する。初回prompt付きの`agent_launch`と通常の`pty_send`で、入力受付待ち中に拒否を検出すると未送信のエラーを返す。promptなしの`agent_launch`は起動要求を返すため、その応答だけでは入力受付済みと判断しない。実装の責務分担は[DESIGN](docs/DESIGN.md#failure-and-recovery)を参照。
+この判定はGrok専用アダプターが所有し、同じCLIを使うComposerにも適用する。初回prompt付きの`agent_launch`と通常の`pty_send`で、入力受付待ち中に拒否を検出すると未送信のエラーを返す。promptなし・`trust_project`指定なしの起動応答は入力受付を保証しない。`trust_project:true`では入力受付まで確認し、`startup.status`を返す。Grokのprivacy notice起動設定も同アダプターが所有する。実装の責務分担は[DESIGN](docs/DESIGN.md#failure-and-recovery)を参照。
 
 ```text
 agent_launch({ harness: "codex-cli", session_name: "codex1", cwd: "/repo",
@@ -293,10 +311,10 @@ Throughline自体が不要である。
 
 ## 最初の実行（約60秒）
 
-Claude Code を再起動して、接続を確認:
+`aiterm-setup --json`が`ready`になったら、利用するMCP clientを再起動して接続を確認する。Claude Codeの場合:
 
 ```bash
-/mcp        # aiterm が connected・16 ツール公開、と出る
+/mcp        # aiterm が connected・18 ツール公開、と出る
 ```
 
 最初のセッション——4 回の呼び出しで、1 個の永続端末:
@@ -337,7 +355,7 @@ MCP クライアントが aiterm を stdio 越しにプログラムから駆動
 
 ```mermaid
 flowchart LR
-    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · agent_launch · agent_steer · agent_configure · claude_turn · claude_approval<br/>旧launcher alias · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 16 tools"]
+    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · pty_observe · agent_launch · agent_steer · agent_configure · agent_approval · claude_turn · claude_approval<br/>旧launcher alias · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 18 tools"]
     S -->|"pty_read<br/>token-reduced"| AI
     S -->|"tmux / psmux<br/>send · capture"| P["persistent PTYs<br/>再起動を跨ぐ"]
     P -->|"ssh · docker · repl"| R["nested<br/>remote · container · REPL"]
@@ -409,15 +427,48 @@ aiterm は同じ核心の洞察——端末を出会いの場にする——を
 
 ## ツール
 
+### セッション観測と起動準備
+
+`pty_open`の既定shellはPOSIXでbash、WindowsでPowerShell 7。通常PTYとagentの内側では
+`AITERM_SESSION_ID`で自分のsessionを識別できる。`env_vars`はMCP processから継承する名前の配列で、
+`pty_list({ env_keys: ["JOB_OWNER"] })`は指定した非秘密キーだけを`environment`へ返す。未設定値はnull。
+一覧の`aiterm.pty-list-result.v1`は`observed_at`と`sessions`を持ち、各行に`session_id`、`current_command`、
+`attached`、`width`、`height`、`harness`、`environment`を返す。従来のtextも維持する。
+
+`pty_observe({ session_id, cursor? })`は`aiterm.pty-observe-result.v1`で`exists`、`observed_at`、
+`state`（busy／idle／blocked／dead／missing／unknown）、`reason`、`pane_alive`、`harness_alive`を返す。
+`pane_process`と`harness_process`は別のidentityで、`process_identity`はagentならharness、通常PTYなら
+一意な子process group leader、子がなければpaneを指す。identityは`pid`、`process_group_id`、
+`started_identity`、`argv_digest`を持ち、特定不能はnull。WindowsのPIDはnative PIDで、process groupはnull。
+開始識別はPOSIXの`LC_ALL=C ps lstart`、WindowsのUTC ISOミリ秒、argv digestはSHA-256のhexである。
+
+`activity.cursor`を次の照会へ渡すと、`output_changed`と`cpu_delta_seconds`を返す。初回と再作成後はnull。
+`cpu_seconds`は現在のsubtreeの累積値で、区間中にprocessが消えた場合、増分は観測できた分だけとなり
+`cpu_delta_complete=false`を付ける。`background_cpu_seconds`、`background_cpu_delta_seconds`、
+`background_cpu_delta_complete`はpane開始から60秒以降に生成された子孫だけの同じ観測で、起動時MCPを除外する。
+`token_hint`は画面の直近token表示値またはnull。画面本文や生argvを解析する必要はない。
+
+`agent_launch({ harness, cwd, trust_project: true })`はpromptなしでも既知のworkspace・project hooks・MCP初期同意を
+進め、入力受付とharness生存を確認して`startup.status="ready"`を返す。指定なしのpromptなし起動は`not_checked`。
+初手の`initial_prompt.status`は`not_requested`／`not_sent`／`submitted_unconfirmed`／`started`を区別する。
+未送信・未確認の失敗もsession付きstructuredContentを保持する。未確認のpromptを再送せず、返ったcursorで観測する。
+
+Codexの実行中承認は`agent_approval({ action: "inspect", session_id })`の`prompt`と`choices`を確認し、
+`respond`へ`observed_prompt_digest`と`approval_choice`（`approve_once`／`deny`）を渡す。
+未知・変更済みのdialogは`status="blocked"`と`isError:true`で返し、入力しない。恒久許可は扱わない。
+Claudeの相関済み承認は既存の`claude_approval`を使う。
+
 | ツール | 役割 | 主な引数 |
 | --- | --- | --- |
-| `pty_open` | 端末を 1 個握り `session_id` を返す | `name?`, `shell="bash"` |
+| `pty_open` | 端末を1個開き`session_id`を返す | `name?`, `shell?`, `env_vars?` |
 | `pty_send` | テキストを送る。agent sessionでは非ブロックdispatchとして`event_cursor`を返す | `session_id`, `text`, `enter=true`, `mark`, `force`, `rtk`, `raw` |
 | `pty_read` | 出力を削減して読む（既定は増分） | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk`, `agent_transcript`, `operation_id` |
 | `pty_key` | 制御キーを送る | `session_id`, `key`（`C-c`/`Enter`/`Up`…） |
 | `pty_close` | 冪等に閉じ、`closed` / `already_closed`を返す | `session_id` |
-| `pty_list` | セッション一覧（agent行は正規`harness=<id>`と互換`agent=<kind>`を含む） | （なし） |
-| `agent_launch` | harnessとmodelを別軸で選ぶ正規agent起動入口 | `harness`, `prompt?`, `model?`, `reasoning_effort?`, `cwd?`, `write_scope?`, `throughline_source_session?`, `throughline_supplement_file?` |
+| `pty_list` | textと構造化したsession一覧、明示した非秘密環境変数の照会 | `env_keys?` |
+| `pty_observe` | pane／harnessの生存、native process identity、状態と活動 | `session_id`, `cursor?` |
+| `agent_launch` | harnessとmodelを別軸で選ぶ正規agent起動入口 | `harness`, `prompt?`, `model?`, `reasoning_effort?`, `cwd?`, `write_scope?`, `trust_project?`, `env_vars?`, `throughline_source_session?`, `throughline_supplement_file?` |
+| `agent_approval` | Codexの現在の承認を検査し、単発許可・拒否を送る | `action`, `session_id`, `approval_choice?`, `observed_prompt_digest?` |
 | `agent_steer` | 実行中のCodex／Grok turnへtextを差し込む。idleなら送信せず`idle`を返す | `session_id`, `text` |
 | `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` | deprecated互換alias | 旧launcher引数 |
 | `agent_configure` | 起動中のClaude／Codex／Grok／Composer／Cursorを再起動せずmodel／effort変更 | `session_id`, `model?`, `reasoning_effort?` |
@@ -504,9 +555,9 @@ npm test           # build してから node:test 回帰スイート（tmux ま
 npm link           # ローカルで `aiterm-mcp` を PATH に
 ```
 
-開発中は変更に直結するfocused testを先にローカルで実行します。GitHub Actionsはpushごとにself-hostedの
-`linux-workstation` 1環境で試験を回し、Windows固有ファイルを触った変更だけ`windows-native`を加え、
-3環境（`macos-native`、`linux-workstation`、`windows-native`）の全テストは週1回の健康診断だけで回します。
+開発中は変更に直結する試験を先に実行する。GitHub Actionsは共通実装・CI自身・未分類の変更をMac・Linux・Windowsで検証し、
+Windows固有だけの変更はLinuxとWindowsを選ぶ。版番号だけの変更はLinuxの配布情報・pack確認、文書だけなら文書検査を行う。
+試験内容とOSの選択、週次・手動実行の範囲は[公開手順](docs/RELEASE.md)に従う。
 `npm run release -- <version>`がversion同期・commit・tag・GitHub Releaseを一回で行い、tag起点のnpm公開は
 tagged commitが`origin/main`の祖先であることだけを確認して、他のCI結果を待ちません。
 
@@ -514,10 +565,11 @@ tagged commitが`origin/main`の祖先であることだけを確認して、他
 
 ## 試す
 
-1 コマンド、clone もビルドも不要:
+公開packageを導入して、検出したAIへ登録する。cloneやビルドは不要:
 
 ```bash
-claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+npm install -g aiterm-mcp@latest
+aiterm-setup --json
 ```
 
 aiterm が、あなたの AI に別のエージェントへ仕事を渡させたなら——あるいはトークンの往復を 1 回でも省けたなら——**[リポジトリに star](https://github.com/kitepon/aiterm-mcp)** を。他の人に見つけてもらう一番安い方法です。

package/README.md

@@ -28,6 +28,24 @@ Built and maintained by [Quo at kitepon.dev](https://kitepon.dev/en).
 
 ## Install in your MCP client
 
+検出したClaude Code・Codex・Grok・Cursorのユーザー設定へ登録する標準入口:
+
+```bash
+npm install -g aiterm-mcp@latest
+aiterm-setup --json
+```
+
+`aiterm-setup`は端末の依存準備、MCP経由の端末実行、登録と読戻しまでを一回で行う。
+WindowsはwingetでPowerShell 7・Git for Windows・psmux、macOSはHomebrewでtmux、
+Ubuntu／Debianはsudoとaptでtmuxを準備する。必要な公式package managerと実行権限は事前に必要。
+他のLinuxでも既存tmuxを利用できるが、自動導入は`unsupported`で停止する。
+既存設定の他サーバーを保持し、JSON設定は変更前の`.aiterm-backup`を残す。
+結果の`status`は`ready`／`unsupported`／`failed`。未検出のAIは`not_detected`とし、全AI未検出は成功にしない。
+登録先はglobal packageのNodeとMCP入口の絶対パスで、npm一時cacheやsource checkoutは登録しない。
+更新後も同じ入口を実行し、MCP clientを再起動する。npm install自体はユーザー設定を変更しない。
+公開JSONは`schema: "aiterm.setup-result.v1"`、全体の`status`、端末の`backend`、
+AI別の`integrations`を持つ。失敗時は`reason_code`を付け、終了コードはreadyなら0、それ以外は2となる。
+
 No clone or build is required. Each client launches the published package with:
 
 ```bash
@@ -96,7 +114,7 @@ Aiterm and is not a runtime dependency.
 
 **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)
 
-Sixteen tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal; one canonical **agent launcher**, `agent_launch`, which selects `claude-code`, `codex-cli`, `grok-cli`, or `cursor-cli` as the execution harness; `agent_steer` for an active Codex or Grok turn; four deprecated launcher aliases kept for migration; `agent_configure`; `claude_turn`; `claude_approval`; and `diagnostics`. The backend is **tmux on POSIX and psmux on native Windows**, so sessions survive even if the MCP server or the AI client restarts.
+Eighteen tools: seven **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` / `pty_observe` — to open, drive, read, and observe one persistent terminal; one canonical **agent launcher**, `agent_launch`, which selects `claude-code`, `codex-cli`, `grok-cli`, or `cursor-cli` as the execution harness; `agent_steer` for an active Codex or Grok turn; four deprecated launcher aliases kept for migration; `agent_configure`; `agent_approval`; `claude_turn`; `claude_approval`; and `diagnostics`. The backend is **tmux on POSIX and psmux on native Windows**, so sessions survive even if the MCP server or the AI client restarts.
 
 **v0.28.0 separates the execution harness from the model.** The harness owns the agent loop, authentication, hooks, session, and transcript; `model` is what that harness runs. Cursor Agent CLI can therefore select GPT, Claude, or Grok without changing the completion contract from Cursor hooks to another harness's. Grok Composer is a Grok CLI model preset, not another harness: use `harness: "grok-cli", model: "grok-composer-2.5-fast"`. The old four launcher tools are thin compatibility aliases over the same implementation.
 
@@ -169,13 +187,13 @@ collection is off by default and performs no network I/O. It ships via
 tag-triggered CI with npm provenance (OIDC Trusted Publishing); the GitHub
 Release re-registers the Official MCP Registry entry.
 
-**Status:** actively maintained · current public release **v0.31.2** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
+**Status:** actively maintained · current public release **v0.33.0** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
 
 ### Update and rollback
 
 The npm package is the standalone distribution; dotagents is not involved. For a global install,
-update with `npm install -g aiterm-mcp@latest`. To roll back, install a known-good immutable version,
-for example `npm install -g "aiterm-mcp@<known-good-version>"`, then restart the MCP client. For an `npx` configuration,
+update with `npm install -g aiterm-mcp@latest` and `aiterm-setup --json`. To roll back, install a known-good immutable version,
+for example `npm install -g "aiterm-mcp@<known-good-version>"`, then restart the MCP client. setupを持つ版では再起動前に`aiterm-setup --json`を再実行する。For an `npx` configuration,
 use `aiterm-mcp@latest` to update or replace it with `aiterm-mcp@<version>` to pin or roll back.
 Check the [CHANGELOG](CHANGELOG.md) for state/schema compatibility before downgrading. Maintainer
 release and artifact rollback are specified in the product-owned [release procedure](docs/RELEASE.md).
@@ -219,7 +237,7 @@ Grok／Composerの無人起動は公式`--trust`で指定された作業フォ
 
 Grok／Composerがread-only sandboxの適用を拒否した場合、prompt送信時に`GROK_SANDBOX_STARTUP_FAILED`とCLIの原因を返す。hookパスのシンボリックリンクなど、CLIが示した原因を設定の管理元で修正し、対象sessionを`pty_close`して起動し直す。Aitermはsandboxを解除したりhookをコピーしたりしない。
 
-この判定はGrok専用アダプターが所有し、同じCLIを使うComposerにも適用する。初回prompt付きの`agent_launch`と通常の`pty_send`で、入力受付待ち中に拒否を検出すると未送信のエラーを返す。promptなしの`agent_launch`は起動要求を返すため、その応答だけでは入力受付済みと判断しない。実装の責務分担は[DESIGN](docs/DESIGN.md#failure-and-recovery)を参照。
+この判定はGrok専用アダプターが所有し、同じCLIを使うComposerにも適用する。初回prompt付きの`agent_launch`と通常の`pty_send`で、入力受付待ち中に拒否を検出すると未送信のエラーを返す。promptなし・`trust_project`指定なしの起動応答は入力受付を保証しない。`trust_project:true`では入力受付まで確認し、`startup.status`を返す。Grokのprivacy notice起動設定も同アダプターが所有する。実装の責務分担は[DESIGN](docs/DESIGN.md#failure-and-recovery)を参照。
 
 For a correlated Claude turn stopped at `Do you want to proceed?`, use `claude_approval(action: "inspect", ...)` to capture the active operation and SHA-256 screen digest, review the displayed command, then call `respond` with that exact digest and either `approve_once` or `deny`. The relay rechecks the operation and screen under the send lock, never exposes arbitrary input or permanent approval, keeps the active marker intact, and records a prompt-free owner-only receipt. `pty_send(force: true)` does not bypass this boundary.
 
@@ -323,10 +341,10 @@ The only edits to the captures above are the two `⋮` lines (a long head/tail r
 
 ## First run (≈60 seconds)
 
-Restart Claude Code, then verify the connection:
+`aiterm-setup --json`が`ready`になったら、利用するMCP clientを再起動して接続を確認する。Claude Codeの場合:
 
 ```bash
-/mcp        # aiterm should show as connected, exposing 16 tools
+/mcp        # aiterm should show as connected, exposing 18 tools
 ```
 
 Your first session — four calls, one persistent terminal:
@@ -367,7 +385,7 @@ The terminal is real and shared, so a human *can* jump in ([A human can watch](#
 
 ```mermaid
 flowchart LR
-    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · agent_launch · agent_steer · agent_configure · claude_turn · claude_approval<br/>legacy launcher aliases · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 16 tools"]
+    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · pty_observe · agent_launch · agent_steer · agent_configure · agent_approval · claude_turn · claude_approval<br/>legacy launcher aliases · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 18 tools"]
     S -->|"pty_read<br/>token-reduced"| AI
     S -->|"tmux / psmux<br/>send · capture"| P["persistent PTYs<br/>survive restarts"]
     P -->|"ssh · docker · repl"| R["nested<br/>remote · container · REPL"]
@@ -441,15 +459,50 @@ On top of that sits a productized layer a raw tmux bridge doesn't have: **token-
 
 ## Tools
 
+### Session observation and startup
+
+`pty_open` defaults to bash on POSIX and PowerShell 7 on Windows. Ordinary terminals and agents receive
+`AITERM_SESSION_ID`. Pass environment-variable names in `env_vars` to inherit ownership information from the MCP process.
+`pty_list({ env_keys: ["JOB_OWNER"] })` returns only the requested non-secret values in `environment`; missing values are null.
+Its `aiterm.pty-list-result.v1` receipt contains `observed_at` and `sessions`, whose entries include `session_id`,
+`current_command`, `attached`, `width`, `height`, `harness`, and `environment`. Existing text remains available.
+
+`pty_observe({ session_id, cursor? })` returns `aiterm.pty-observe-result.v1` with `exists`, `observed_at`, `state`
+(busy/idle/blocked/dead/missing/unknown), `reason`, `pane_alive`, and `harness_alive`. `pane_process` and `harness_process`
+are separate identities. `process_identity` selects the harness for agents, or the unique child process-group leader
+for an ordinary terminal, using the pane when no child leader exists. An identity contains `pid`, `process_group_id`,
+`started_identity`, and `argv_digest`; unresolved identities are null. Windows PIDs are native and its process-group field
+is null. Start identity uses POSIX `LC_ALL=C ps lstart` or Windows UTC ISO milliseconds; the argv digest is SHA-256 hex.
+
+Pass `activity.cursor` into the next observation to obtain `output_changed` and `cpu_delta_seconds`; first observations and
+recreated panes return null differences. `cpu_seconds` is the current subtree's cumulative CPU. If a process disappeared
+between observations, the delta covers only observed increments and `cpu_delta_complete` is false.
+`background_cpu_seconds`, `background_cpu_delta_seconds`, and `background_cpu_delta_complete` apply the same measurement
+only to descendants created at least 60 seconds after the pane, excluding startup MCP processes. `token_hint` is the latest
+displayed token count or null. Callers do not need raw argv or pane-text parsing.
+
+`agent_launch({ harness, cwd, trust_project: true })` completes known workspace, project-hook, and project-MCP startup
+consent even without a prompt, then verifies input readiness and harness liveness before returning `startup.status="ready"`.
+A prompt-free launch without this option retains `startup.status="not_checked"`. `initial_prompt.status` distinguishes
+`not_requested`, `not_sent`, `submitted_unconfirmed`, and `started`. Failure responses retain structured session information.
+Do not resend an unconfirmed prompt; observe or wait using its returned cursor.
+
+For a live Codex approval, inspect with `agent_approval({ action: "inspect", session_id })`, review `prompt` and `choices`,
+then respond with `observed_prompt_digest` and `approval_choice` (`approve_once` or `deny`). Unknown or changed dialogs return
+`status="blocked"` and `isError:true` without sending input. Permanent approval is not exposed. Correlated Claude approvals
+continue to use `claude_approval`.
+
 | Tool | Role | Key args |
 | --- | --- | --- |
-| `pty_open` | Grab one terminal, return a `session_id` | `name?`, `shell="bash"` |
+| `pty_open` | Open one terminal and return a `session_id` | `name?`, `shell?`, `env_vars?` |
 | `pty_send` | Send text; on an agent session this is a non-blocking **dispatch** returning an `event_cursor` | `session_id`, `text`, `enter=true`, `mark`, `force`, `rtk`, `raw` |
 | `pty_read` | Read output, token-reduced (incremental by default) | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk`, `agent_transcript`, `operation_id` |
 | `pty_key` | Send a control key | `session_id`, `key` (`C-c`/`Enter`/`Up`…) |
 | `pty_close` | Close idempotently; return `closed` / `already_closed` | `session_id` |
-| `pty_list` | List sessions (agent rows carry canonical `harness=<id>` plus compatibility `agent=<kind>`) | (none) |
-| `agent_launch` | Canonical agent launch; harness and model are independent | `harness`, `prompt?`, `model?`, `reasoning_effort?`, `cwd?`, `write_scope?`, `throughline_source_session?`, `throughline_supplement_file?` |
+| `pty_list` | Text and structured session list, with explicitly requested non-secret environment values | `env_keys?` |
+| `pty_observe` | Pane/harness liveness, native process identity, state, and activity | `session_id`, `cursor?` |
+| `agent_launch` | Canonical agent launch; harness and model are independent | `harness`, `prompt?`, `model?`, `reasoning_effort?`, `cwd?`, `write_scope?`, `trust_project?`, `env_vars?`, `throughline_source_session?`, `throughline_supplement_file?` |
+| `agent_approval` | Inspect a Codex approval and submit a one-time approval or denial | `action`, `session_id`, `approval_choice?`, `observed_prompt_digest?` |
 | `agent_steer` | Inject text into the active Codex or Grok turn; return `idle` without sending when no turn is active | `session_id`, `text` |
 | `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` | Deprecated compatibility aliases | legacy launcher arguments |
 | `agent_configure` | Change model/effort in a running Claude, Codex, Grok, Composer, or Cursor session without restarting it | `session_id`, `model?`, `reasoning_effort?` |
@@ -550,10 +603,10 @@ npm test           # build, then the node:test regression suite (requires tmux o
 npm link           # put `aiterm-mcp` on PATH locally
 ```
 
-Development uses focused local tests first. GitHub Actions runs the suite on the self-hosted
-`linux-workstation` runner for every push, adds `windows-native` only when Windows-specific files change,
-and runs all three runners (`macos-native`, `linux-workstation`, `windows-native`) once a week as a health
-check. `npm run release -- <version>` syncs the version, commits, tags, and publishes the GitHub Release in
+開発中は変更に直結する試験を先に実行する。GitHub Actionsは共通実装・CI自身・未分類の変更をMac・Linux・Windowsで検証し、
+Windows固有だけの変更はLinuxとWindowsを選ぶ。版番号だけの変更はLinuxの配布情報・pack確認、文書だけなら文書検査を行う。
+試験内容とOSの選択、週次・手動実行の範囲は[公開手順](docs/RELEASE.md)に従う。
+`npm run release -- <version>` syncs the version, commits, tags, and publishes the GitHub Release in
 one command; tag-triggered npm publishing checks only that the tagged commit is on `origin/main` and does not
 wait for another CI run. The native
 Windows runner needs psmux ≥ 3.3.8 and Git for Windows on its PATH, and must run as an
@@ -564,10 +617,11 @@ Logic lives in `src/core.ts` (tmux control, reduction, completion detection, saf
 
 ## Try it
 
-One command, no clone, no build:
+公開packageを導入して、検出したAIへ登録する。cloneやビルドは不要:
 
 ```bash
-claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+npm install -g aiterm-mcp@latest
+aiterm-setup --json
 ```
 
 If aiterm let your AI hand a task to another agent — or saved you a round-trip of tokens — **[star the repo](https://github.com/kitepon/aiterm-mcp)**. It's the cheapest way to help others find it.