aiterm-mcp 0.18.2 → 0.19.1

package/README.ja.md

@@ -22,7 +22,7 @@
 
 **言葉でなく実測で:** このリポジトリ自身の 203 テストで、`pty_read` はコンテキストに載るトークンを生ログの **約 7.1 分の 1** に減らす。しかも pass/fail の判定は畳んでも残る。→ [組み込みシェルツールとの使い分け](#組み込みシェルツールとの使い分け)
 
-12 ツール: 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を、`diagnostics`が安全なfactory readinessを返す。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
+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.18.1 を 2026-07-18 に公開**（0.18.0＋stale案内文言の修理1件）。実運用障害の還流による agent dispatch の hardening:
 全 dispatch／launch receipt に **submit 座礁観測** `submit_residue` を追加
@@ -82,7 +82,7 @@ $ aiterm-wait --session codex1 --cursor <event_cursor>   # exit 0=done / 3=timeo
 | `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?` |
 
-各ベンダーの CLI が導入・認証済みであること（`claude_agent` は `claude`、`codex_agent` は `codex`、Grok 系は `grok`）。バイナリは `CLAUDE_BIN` / `CODEX_BIN` / `GROK_BIN`、各既定path、`PATH` の順で解決する。CLI不在・不正なmodel/effort・実在しない`cwd`はsession作成前に失敗し、残骸を残さない。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ではC-c以外の`pty_key`を拒否する（手動介入は`pty_send`の`force:true`）。中断は`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は通常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`。
 
 エージェント間の隠れたプロトコルは無い。起動したClaude/Codex/Grok/Composerは利用者がattachできるもう1本の永続sessionであり、MCPクライアントが通常のPTY操作で駆動する。
 
@@ -145,7 +145,7 @@ claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
 Claude Code を再起動して、接続を確認:
 
 ```bash
-/mcp        # aiterm が connected・12 ツール公開、と出る
+/mcp        # aiterm が connected・13 ツール公開、と出る
 ```
 
 最初のセッション——4 回の呼び出しで、1 個の永続端末:
@@ -186,7 +186,7 @@ MCP クライアントが aiterm を stdio 越しにプログラムから駆動
 
 ```mermaid
 flowchart LR
-    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · claude_agent · claude_turn · codex_agent<br/>grok_agent · composer_agent · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 12 tools"]
+    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · claude_agent · claude_turn · claude_approval · codex_agent<br/>grok_agent · composer_agent · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 13 tools"]
     S -->|"pty_read<br/>token-reduced"| AI
     S -->|"tmux send-keys<br/>capture-pane"| P["persistent PTYs<br/>tmux · survive restarts"]
     P -->|"ssh · docker · repl"| R["nested<br/>remote · container · REPL"]
@@ -262,12 +262,13 @@ aiterm は同じ核心の洞察——端末を出会いの場にする——を
 | ツール | 役割 | 主な引数 |
 | --- | --- | --- |
 | `pty_open` | 端末を 1 個握り `session_id` を返す | `name?`, `shell="bash"` |
-| `pty_send` | テキスト(コマンド)を送る | `session_id`, `text`, `enter=true`, `wait`, `timeout`, `screen`, `lines`, `operation_id`, `mark`, `force`, `rtk`, `raw` |
+| `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` | セッション一覧 | （なし） |
 | `claude_turn` | 相関済みmanaged Claude operationをdispatch（issue）または回収（recover） | `action`, `session_id`, `operation_id`, `text?` |
+| `claude_approval` | 現在表示中の相関済みmanaged Claude承認UIを検査または応答 | `action`, `session_id`, `operation_id?`, `approval_choice?`, `observed_prompt_digest?` |
 | `diagnostics` | 機械可読 JSON による read-only factory readiness | （なし） |
 
 `diagnostics` は PTY やエージェントを起動しない。パッケージ版、MCP 呼出 readiness、read-only な PTY 一覧要約、bounded runtime-error-store status、任意 vendor launcher の可用性だけを返す。path・環境値・認証情報・コマンド本文・PTY 出力・raw log は意図的に返さない。通常未設定の任意依存は `not_applicable`、安全に確定できない状態は `unverified` と表す。
@@ -307,7 +308,7 @@ consumer は `aiterm-runtime-errors snapshot` を読み、durable ingestion 後
 
 `pty_send` は送信前に破壊的コマンド（`rm -rf /`, `mkfs`, `dd of=/dev/…`, `DROP TABLE` 等）を遮断し（`force: true` で越える）、ESC・ブラケットペースト終端などをサニタイズする。`pty_read` は既定で制御文字を無害化して返す（`raw: true` はバイトをそのまま返す）。これは**サンドボックスではなく tripwire**（[既知の制約](#既知の制約バグではなく仕様)参照）。
 
-1回の `pty_send` が受理する本文はUTF-8で最大64KiB。同一sessionへの送信はaiterm processをまたいで直列化し、chunk同士の混線を防ぐ。macOSでは長いPTY入力の欠落を避けるためUTF-8境界を壊さない256-byte単位でtmux pasteし、Linux/WSLでは上限内を1回でpasteする。agent dispatch の paste はさらに tmux bracketed paste（`paste-buffer -p`）を使う: bracketed paste mode を要求している pane（vendor TUI）へは各 chunk を `ESC[200~/201~` で包んで届け、チャンク投入中のキー解釈による語中文字化け・submit 取り落としを抑える。通常の shell 送信は不変。途中chunkが失敗した場合は部分送信済みであることを明示し、自動でEnterを押さない。送信processの異常終了でlockが残った場合は送信前にfail-closedする。そのsessionを `pty_close` して作り直すか、全sessionを破棄できる場合だけ `pty_kill_all` で安全に掃除する。
+1回の `pty_send` が受理する本文はUTF-8で最大64KiB。同一sessionへの送信はaiterm processをまたいで直列化し、chunk同士の混線を防ぐ。macOSでは長いPTY入力の欠落を避けるためUTF-8境界を壊さない256-byte単位でtmux pasteし、Linux/WSLでは上限内を1回でpasteする。POSIX shellが前面にいる時のsanitize済み複数行は、改行を含まない単一の`eval`入力へ符号化する。shellがscript全体を所有してから先頭行を実行するため、途中で起動したpager／REPLが後続行を対話キーとして奪わない。単一行、`raw:true`、非shell前面は従来どおり直接PTYへpasteする。agent dispatch の paste はさらに tmux bracketed paste（`paste-buffer -p`）を使う: bracketed paste mode を要求している pane（vendor TUI）へは各 chunk を `ESC[200~/201~` で包んで届け、チャンク投入中のキー解釈による語中文字化け・submit 取り落としを抑える。途中chunkが失敗した場合は部分送信済みであることを明示し、自動でEnterを押さない。送信processの異常終了でlockが残った場合は送信前にfail-closedする。そのsessionを `pty_close` して作り直すか、全sessionを破棄できる場合だけ `pty_kill_all` で安全に掃除する。
 
 ## 人が覗く
 

package/README.md

@@ -22,7 +22,7 @@
 
 **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)
 
-Twelve 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, and `diagnostics` for safe factory readiness. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
+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.18.1 was published on 2026-07-18** (v0.18.0 plus one stale-guidance
 message fix). Field-failure hardening for agent
@@ -75,6 +75,8 @@ pty_read(id, { wait: true })       → read the token-reduced output, completion
 
 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).
 
+For a managed 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.
+
 ```text
 codex_agent({ session_name: "codex1", cwd: "/repo",
               prompt: "port test/legacy.py to vitest" })
@@ -95,7 +97,7 @@ One call per model, so the tool name itself tells you which model you get:
 | `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?` |
 
-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. A rejected launch leaves **zero leftover session** behind. 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. Non-interrupt keys are rejected on the managed Claude route; use dispatch, `pty_key("C-c")`, and `pty_close` (`force:true` on `pty_send` is the manual-intervention escape). 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. A rejected launch leaves **zero leftover session** behind. 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 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.
 
@@ -160,7 +162,7 @@ claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
 Restart Claude Code, then verify the connection:
 
 ```bash
-/mcp        # aiterm should show as connected, exposing 12 tools
+/mcp        # aiterm should show as connected, exposing 13 tools
 ```
 
 Your first session — four calls, one persistent terminal:
@@ -201,7 +203,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 · claude_agent · claude_turn · codex_agent<br/>grok_agent · composer_agent · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 12 tools"]
+    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · claude_agent · claude_turn · claude_approval · codex_agent<br/>grok_agent · composer_agent · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 13 tools"]
     S -->|"pty_read<br/>token-reduced"| AI
     S -->|"tmux send-keys<br/>capture-pane"| P["persistent PTYs<br/>tmux · survive restarts"]
     P -->|"ssh · docker · repl"| R["nested<br/>remote · container · REPL"]
@@ -285,6 +287,7 @@ On top of that sits a productized layer a raw tmux bridge doesn't have: **token-
 | `pty_close` | Close idempotently; return `closed` / `already_closed` | `session_id` |
 | `pty_list` | List sessions (agent rows carry `agent=<kind>` metadata) | (none) |
 | `claude_turn` | Issue (dispatch-only) or recover one correlated managed-Claude operation | `action`, `session_id`, `operation_id`, `text?` |
+| `claude_approval` | Inspect or answer the current correlated managed-Claude approval prompt | `action`, `session_id`, `operation_id?`, `approval_choice?`, `observed_prompt_digest?` |
 | `diagnostics` | Read-only factory readiness as machine-readable JSON | (none) |
 
 `diagnostics` never starts a PTY or agent. It reports package version, MCP call readiness, a read-only PTY-list summary, bounded runtime-error-store status, and optional vendor-launcher availability. It deliberately excludes paths, environment values, credentials, command text, PTY output, and raw logs; normal unset optional dependencies are `not_applicable`, while an indeterminate probe is `unverified`.
@@ -335,7 +338,7 @@ As of v0.16 a parent agent **never blocks** on aiterm — there is no wait param
 
 Before sending, `pty_send` blocks destructive commands (`rm -rf /`, `mkfs`, `dd of=/dev/…`, `DROP TABLE`, …) — pass `force: true` to override — and sanitizes ESC / bracketed-paste terminators. `pty_read` neutralizes control characters in what it returns by default (`raw: true` returns the bytes verbatim). This is a **tripwire, not a sandbox** (see [Known constraints](#known-constraints-by-design-not-bugs)).
 
-Each `pty_send` accepts at most 64 KiB of UTF-8 text. Sends to the same session are serialized across aiterm processes so chunks cannot interleave. On macOS, text is pasted through tmux in UTF-8-safe 256-byte chunks to avoid the platform PTY truncation observed with long input; Linux and WSL use one bounded paste. Agent dispatches additionally paste with tmux bracketed paste (`paste-buffer -p`): panes that requested bracketed-paste mode (the vendor TUIs) receive each chunk wrapped in `ESC[200~/201~`, hardening prompt injection against mid-word key-interpretation corruption and dropped submits; ordinary shell sends are unchanged. If a later chunk fails, aiterm reports the partial-send state and does not press Enter automatically. A lock left by a terminated sender fails closed before sending; close and recreate that session (or use `pty_kill_all` when every session is disposable) to clean it up safely.
+Each `pty_send` accepts at most 64 KiB of UTF-8 text. Sends to the same session are serialized across aiterm processes so chunks cannot interleave. On macOS, text is pasted through tmux in UTF-8-safe 256-byte chunks to avoid the platform PTY truncation observed with long input; Linux and WSL use one bounded paste. Sanitized multiline text sent while a POSIX shell is in the foreground is encoded as one newline-free `eval` input: the shell receives the complete script before it runs the first line, so a pager or REPL started mid-script cannot consume later lines as interactive keystrokes. Single-line input, `raw:true`, and non-shell frontends remain direct PTY pastes. Agent dispatches additionally paste with tmux bracketed paste (`paste-buffer -p`): panes that requested bracketed-paste mode (the vendor TUIs) receive each chunk wrapped in `ESC[200~/201~`, hardening prompt injection against mid-word key-interpretation corruption and dropped submits. If a later chunk fails, aiterm reports the partial-send state and does not press Enter automatically. A lock left by a terminated sender fails closed before sending; close and recreate that session (or use `pty_kill_all` when every session is disposable) to clean it up safely.
 
 ## A human can watch
 

package/dist/core.js

@@ -33,6 +33,11 @@ export const DEFAULT_TIMEOUT = 10.0;
 const POLL = 0.25;
 const STABLE_POLLS = 2; // 連続でログサイズ不変ならば静止とみなす回数
 const SHELLS = new Set(["bash", "sh", "zsh", "fish", "dash"]);
+// 通常PTYへ複数行をそのままpasteすると、途中で起動したpager/REPLが後続行を
+// キー入力として消費する。POSIX shell前面では改行を持たないeval 1行へ包み、
+// script全体をshell内部へ取り込んでから実行する。fish等の非POSIX shellや
+// ssh/REPL前面は従来の生pasteを維持する。
+const ATOMIC_MULTILINE_SHELLS = new Set(["bash", "sh", "zsh", "dash"]);
 // mark の sentinel は POSIX シェル構文（; と "$?"）に依存する。これらの非 POSIX 対話シェルが
 // 前面のときは "$?" が正しく展開されず sentinel が壊れるので mark を拒否する（B8）。ssh/docker で
 // リモート POSIX シェルに入っている場合は前面が "ssh"/"docker" 等で本集合に含まれず＝許可される。
@@ -56,6 +61,7 @@ const AGENT_TUI_READY_TIMEOUT_MS = 30_000;
 const AGENT_TUI_READY_POLL_MS = 500;
 const AGENT_TUI_READY_STABLE_SAMPLES = 11;
 const AGENT_TUI_READY_LINES = 45;
+const CLAUDE_APPROVAL_SCREEN_LINES = 80;
 // submit座礁観測（dispatch後にcomposerへ送信textが残存していないかの有界チェック）
 const AGENT_SUBMIT_RESIDUE_DELAY_MS = 250;
 const AGENT_SUBMIT_RESIDUE_POLL_MS = 300;
@@ -306,6 +312,19 @@ function splitPtyText(text) {
         chunks.push(chunk);
     return chunks;
 }
+function quoteForPrintfB(text) {
+    return text
+        .replace(/\\/g, "\\\\")
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t")
+        .replace(/'/g, `'"'"'`);
+}
+function atomicShellMultiline(text) {
+    // POSIX printf %bで元の改行・backslashを復元し、evalは現在shell内で実行する。
+    // command substitutionが末尾LFを落とす点は、pty_sendのsubmitを担うEnterと同値。
+    return `eval "$(command printf '%b' '${quoteForPrintfB(text)}')"`;
+}
 function assertSendTextSize(text, context = "送信文字列") {
     const bytes = Buffer.byteLength(text, "utf8");
     if (bytes > MAX_SEND_BYTES) {
@@ -404,6 +423,12 @@ function agentClaudeOperationPath(name, launchId) {
         throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
     return path.join(agentsDir(), `${name}.${launchId}.claude-operation.json`);
 }
+function agentClaudeApprovalReceiptPath(name, launchId) {
+    assertSessionName(name);
+    if (!LAUNCH_ID_RE.test(launchId))
+        throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
+    return path.join(agentsDir(), `${name}.${launchId}.claude-approval.json`);
+}
 function agentClaudeDispatchReceiptPath(name, launchId, operationId) {
     assertSessionName(name);
     if (!LAUNCH_ID_RE.test(launchId))
@@ -470,6 +495,7 @@ function cleanupAgentState(name) {
                     f.endsWith(".claude-settings.json") ||
                     f.endsWith(".claude-result.json") ||
                     f.endsWith(".claude-operation.json") ||
+                    f.endsWith(".claude-approval.json") ||
                     f.endsWith(".claude-dispatch"))
                     fs.unlinkSync(p);
                 else if (f.endsWith(".codex-home") || f.endsWith(".grok-home") || f.endsWith(".home")) {
@@ -952,6 +978,10 @@ export function send(name, text, o = {}) {
         if (o.mark)
             text = text + `; printf '\\n<<<AITERM_DONE rc=%d>>>\\n' "$?"`;
         assertSendTextSize(text, o.rtk || o.mark ? "変換後の送信文字列" : "送信文字列");
+        const reportedText = text;
+        if (!o.raw && text.includes("\n") && ATOMIC_MULTILINE_SHELLS.has(paneCurrentCommand(name))) {
+            text = atomicShellMultiline(text);
+        }
         if (o.mark) {
             try {
                 fs.writeFileSync(markpath(name), "1"); // waitCompletion に sentinel 完了検出を有効化させる
@@ -1010,7 +1040,7 @@ export function send(name, text, o = {}) {
             }
         }
         // コードポイント数で数える（JS の .length は UTF-16 単位で絵文字等がズレる。Python は len()=コードポイント）。
-        return `sent ${[...text].length} chars to ${name}` + (enter ? " (+Enter)" : "");
+        return `sent ${[...reportedText].length} chars to ${name}` + (enter ? " (+Enter)" : "");
     }
     finally {
         releaseSendLock();
@@ -1863,6 +1893,134 @@ function managedClaudeOperation(name) {
         return undefined;
     return readClaudeOperationMarker(meta);
 }
+function canonicalClaudeApprovalScreen(screen) {
+    return stripControl(screen)
+        .split("\n")
+        .map((line) => line.replace(/^\s*[❯>]\s*/, "").replace(/\s+$/, ""))
+        .join("\n")
+        .trim();
+}
+function parseClaudeApprovalScreen(screen) {
+    const canonical = canonicalClaudeApprovalScreen(screen);
+    const lines = canonical.split("\n");
+    let question = -1;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (lines[i].trim() === "Do you want to proceed?")
+            question = i;
+    }
+    if (question < 0) {
+        throw new AitermError("managed Claudeの承認UIを現在画面で確認できません（Do you want to proceed? がありません）", 2);
+    }
+    const choices = [];
+    const seen = new Set();
+    for (const line of lines.slice(question + 1)) {
+        const match = line.trim().match(/^(\d+)\.\s+(.+?)\s*$/);
+        if (!match)
+            continue;
+        const index = Number(match[1]);
+        const label = match[2];
+        const decision = /^yes$/i.test(label)
+            ? "approve_once"
+            : /^no$/i.test(label)
+                ? "deny"
+                : null;
+        // 「常に許可」等は意図的に公開しない。単発Yes/No以外を自動操作できる契約にしない。
+        if (!decision)
+            continue;
+        if (!Number.isSafeInteger(index) || index < 1 || seen.has(decision)) {
+            throw new AitermError("managed Claudeの承認UI選択肢が一意に解釈できません", 2);
+        }
+        seen.add(decision);
+        choices.push({ decision, index, label });
+    }
+    if (!seen.has("approve_once") || !seen.has("deny")) {
+        throw new AitermError("managed Claudeの承認UIに安全な単発Yes/No選択肢を確認できません", 2);
+    }
+    return {
+        promptDigest: `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`,
+        choices,
+    };
+}
+function assertExpectedClaudeOperation(meta, expectedOperationId) {
+    const active = readClaudeOperationMarker(meta);
+    if (!active)
+        throw new AitermError("managed Claudeに未解決のactive operationがありません", 2);
+    if (active.operationId !== expectedOperationId) {
+        const actual = active.operationId ?? "operation_idなし";
+        const expected = expectedOperationId ?? "operation_idなし";
+        throw new AitermError(`active operationが一致しません（expected=${expected}, actual=${actual}）`, 2);
+    }
+    return active;
+}
+export function runClaudeApproval({ action, session_id: name, operation_id: operationIdInput, approval_choice: approvalChoice, observed_prompt_digest: observedPromptDigest, }) {
+    assertSessionName(name);
+    if (!sessionExists(name))
+        throw new AitermError(`session '${name}' が無い`, 2);
+    const meta = loadAgentMetadata(name);
+    if (meta.kind !== "claude")
+        throw new AitermError("claude_approvalはmanaged Claude agent sessionだけで使用できます", 2);
+    const operationId = operationIdInput == null ? null : validateOperationId(operationIdInput);
+    if (action === "inspect") {
+        if (approvalChoice != null || observedPromptDigest != null) {
+            throw new AitermError("claude_approval inspectにapproval_choice／observed_prompt_digestは指定できません", 2);
+        }
+        assertExpectedClaudeOperation(meta, operationId);
+        const observed = parseClaudeApprovalScreen(captureScreen(name, CLAUDE_APPROVAL_SCREEN_LINES));
+        return {
+            schema: "aiterm.claude-approval-result.v1",
+            action,
+            status: "approval_required",
+            session_id: name,
+            operation_id: operationId,
+            prompt_digest: observed.promptDigest,
+            choices: observed.choices,
+            selected_choice: null,
+            at: new Date().toISOString(),
+        };
+    }
+    if (action !== "respond")
+        throw new AitermError(`claude_approval actionが不正です: ${action}`, 2);
+    if (approvalChoice == null || observedPromptDigest == null) {
+        throw new AitermError("claude_approval respondにはapproval_choiceとobserved_prompt_digestが必要です", 2);
+    }
+    if (!OPERATION_ID_RE.test(observedPromptDigest)) {
+        throw new AitermError("observed_prompt_digestはsha256:<64 lowercase hex>で指定してください", 2);
+    }
+    const releaseSendLock = acquireSessionSendFileLock(name);
+    try {
+        // inspect後にoperationまたは画面が変わっていないことを、入力と同じsend lock内で再検証する。
+        assertExpectedClaudeOperation(meta, operationId);
+        const observed = parseClaudeApprovalScreen(captureScreen(name, CLAUDE_APPROVAL_SCREEN_LINES));
+        if (observed.promptDigest !== observedPromptDigest) {
+            throw new AitermError("承認UIがinspect後に変化しました。再度inspectしてから判断してください", 2);
+        }
+        const choice = observed.choices.find((entry) => entry.decision === approvalChoice);
+        if (!choice)
+            throw new AitermError(`承認UIに${approvalChoice}の安全な選択肢がありません`, 2);
+        const sent = tmux("send-keys", "-t", name, String(choice.index), "Enter");
+        if (sent.code !== 0) {
+            throw new AitermError(`Claude承認入力を送れませんでした: ${sent.stderr.trim() || `code=${sent.code}`}`, 2);
+        }
+        const at = new Date().toISOString();
+        const result = {
+            schema: "aiterm.claude-approval-result.v1",
+            action,
+            status: "submitted",
+            session_id: name,
+            operation_id: operationId,
+            prompt_digest: observed.promptDigest,
+            choices: observed.choices,
+            selected_choice: approvalChoice,
+            at,
+        };
+        // prompt本文は保存せず、相関ID・digest・選択だけをowner-only receiptへ残す。
+        writeJson0600(agentClaudeApprovalReceiptPath(name, meta.launch_id), result);
+        return result;
+    }
+    finally {
+        releaseSendLock();
+    }
+}
 function hasClaudeDispatchReceipt(meta, operationId) {
     const file = agentClaudeDispatchReceiptPath(meta.aiterm_session, meta.launch_id, operationId);
     let st;

package/dist/index.js

@@ -92,7 +92,7 @@ server.registerTool("pty_send", {
         "ホストのバックグラウンドタスクとして実行し、exit時にreceiptのoutcomeで判定する" +
         `（${core.AITERM_WAIT_OUTCOME_NOTE}。ポーリング不要）。` +
         "結果回収は pty_read(agent_transcript:true)、Claude の durable turn は claude_turn を使う。" +
-        "force:true は agent session への手動介入用の素送信。",
+        "force:true は非Claude agent sessionへの手動介入用の素送信。managed Claudeの承認UIはclaude_approvalを使う。",
     inputSchema: {
         session_id: z.string(),
         text: z
@@ -108,7 +108,7 @@ server.registerTool("pty_send", {
         force: z
             .boolean()
             .default(false)
-            .describe("破壊的コマンドゲートを越える。agent session では dispatch せず素送信する（手動介入用）"),
+            .describe("破壊的コマンドゲートを越える。非Claude agent sessionではdispatchせず素送信する。managed Claudeのactive turnには使えない"),
         rtk: z.boolean().default(false).describe("既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）"),
         raw: z.boolean().default(false).describe("送信前サニタイズを無効化"),
     },
@@ -255,7 +255,7 @@ server.registerTool("pty_read", {
     }
 });
 server.registerTool("pty_key", {
-    description: "制御キーを送る（C-c, C-d, Enter, Tab, Up, Down... の別名に対応）。managed Claude sessionではturn相関を守るためC-cだけを許可する。",
+    description: "制御キーを送る（C-c, C-d, Enter, Tab, Up, Down... の別名に対応）。managed Claude sessionではturn相関を守るためC-cだけを許可し、承認UIはclaude_approvalで操作する。",
     inputSchema: {
         session_id: z.string(),
         key: z.string().describe('キー名（例 "C-c", "Enter", "Up"）'),
@@ -338,6 +338,57 @@ server.registerTool("claude_turn", {
         return fail(e);
     }
 });
+server.registerTool("claude_approval", {
+    description: "managed Claudeのactive turn中に表示された権限確認UIを、turn相関を保ったまま検査・応答する専用面。" +
+        "inspectで画面digestと安全な単発Yes/Noだけを取得し、respondは同じoperation・同じdigestが現在も表示中の場合だけ送信する。",
+    inputSchema: {
+        action: z.enum(["inspect", "respond"]),
+        session_id: z.string(),
+        operation_id: z
+            .string()
+            .regex(/^sha256:[0-9a-f]{64}$/)
+            .nullish()
+            .describe("durable operationのID。通常pty_send由来の匿名turnでは省略する"),
+        approval_choice: z.enum(["approve_once", "deny"]).optional().describe("respondだけに指定する"),
+        observed_prompt_digest: z
+            .string()
+            .regex(/^sha256:[0-9a-f]{64}$/)
+            .optional()
+            .describe("直前のinspectが返したdigest。respondだけに指定する"),
+    },
+    outputSchema: {
+        schema: z.literal("aiterm.claude-approval-result.v1"),
+        action: z.enum(["inspect", "respond"]),
+        status: z.enum(["approval_required", "submitted"]),
+        session_id: z.string(),
+        operation_id: z.string().regex(/^sha256:[0-9a-f]{64}$/).nullable(),
+        prompt_digest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+        choices: z.array(z.object({
+            decision: z.enum(["approve_once", "deny"]),
+            index: z.number().int().positive(),
+            label: z.string(),
+        })),
+        selected_choice: z.enum(["approve_once", "deny"]).nullable(),
+        at: z.string(),
+    },
+}, async ({ action, session_id, operation_id, approval_choice, observed_prompt_digest }) => {
+    try {
+        const result = core.runClaudeApproval({
+            action,
+            session_id,
+            operation_id: operation_id ?? null,
+            approval_choice,
+            observed_prompt_digest,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+            structuredContent: { ...result },
+        };
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
 // 対話型エージェント起動ツール（モデルごとに1つ＝ツール名/説明でどのモデルか一目で分かる）。
 // いずれも永続端末に TUI を起動し session_id を返す。以後 pty_read/pty_send で対話操作する。
 const agentModelDesc = (kind) => kind === "claude"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.18.2",
+  "version": "0.19.1",
   "mcpName": "io.github.kitepon-rgb/aiterm-mcp",
   "description": "AI-driven persistent terminal as a local stdio MCP server (tmux-backed). Holds one local PTY; SSH and containers are just commands you send into it. Also launches interactive Claude/Codex/Grok/Composer agent TUIs in a persistent terminal. Token-reducing reads.",
   "keywords": [