aiterm-mcp 0.18.1 → 0.19.0

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` と表す。

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,9 @@ 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.
 
 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.
 
@@ -158,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:
@@ -199,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"]
@@ -283,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`.

package/dist/core.js

@@ -56,6 +56,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;
@@ -404,6 +405,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 +477,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")) {
@@ -1505,6 +1513,40 @@ function managedCodexConfigSummary(configPath, hookTrustBypass) {
         bits.push("hook trust bypass 有効");
     return `managed config: ${bits.join(" / ")}`;
 }
+// Custom agent definitions are configuration, not mutable Codex state. Copy only direct
+// agents/*.toml entries into the per-launch home so role discovery matches the source home while
+// sessions/cache remain isolated. Source symlinks are resolved and their contents are snapshotted;
+// the managed home never points back to the source definition.
+function snapshotCodexAgentDefinitions(srcHome, managedHome) {
+    const srcDir = path.join(srcHome, "agents");
+    let srcDirSt;
+    try {
+        srcDirSt = fs.statSync(srcDir);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return;
+        throw e;
+    }
+    if (!srcDirSt.isDirectory()) {
+        throw new AitermError(`Codex agents が directory ではありません: ${srcDir}`, 2);
+    }
+    const names = fs.readdirSync(srcDir).filter((name) => name.endsWith(".toml")).sort();
+    if (!names.length)
+        return;
+    const dstDir = path.join(managedHome, "agents");
+    fs.mkdirSync(dstDir, { mode: 0o700 });
+    fs.chmodSync(dstDir, 0o700);
+    for (const name of names) {
+        const src = path.join(srcDir, name);
+        const resolved = fs.realpathSync(src);
+        const st = fs.statSync(resolved);
+        if (!st.isFile()) {
+            throw new AitermError(`Codex agent definition が通常ファイルではありません: ${src}`, 2);
+        }
+        writeText0600(path.join(dstDir, name), fs.readFileSync(resolved, "utf8"));
+    }
+}
 function createManagedCodexHome(name, launchId, overrides = {}) {
     const srcHome = realCodexHome();
     let srcSt;
@@ -1549,6 +1591,7 @@ function createManagedCodexHome(name, launchId, overrides = {}) {
         fs.writeFileSync(configDst, configOut, { mode: 0o600 });
         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);
@@ -1828,6 +1871,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.1",
+  "version": "0.19.0",
   "mcpName": "io.github.kitepon-rgb/aiterm-mcp",
   "description": "AI-driven persistent terminal as a local stdio MCP server (tmux-backed). Holds one local PTY; SSH and containers are just commands you send into it. Also launches interactive Claude/Codex/Grok/Composer agent TUIs in a persistent terminal. Token-reducing reads.",
   "keywords": [