aiterm-mcp 0.20.3 → 0.21.0

package/README.ja.md

@@ -135,6 +135,8 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 同じ primitive が別エージェントの TUI を宿す。4 つの起動ツールが、Claude/Codex/Grok/Composer の対話 TUI を新しい永続端末の中に起動し、`session_id` を返す。既存の人間向けtextに加えて`aiterm.agent-launch-result.v1` structured receiptも返すため、durable callerは表示文字列を解析せずsession handleを取得できる。以後は同じ `pty_read` / `pty_send` で継続操作する。**起動は常に managed**（aiterm 所有の Stop hook 付き）で、agent session への `pty_send` は非ブロックの **dispatch** になり `event_cursor` 入り receipt を即返す。完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` をホストのバックグラウンドタスクとして実行し、exit 時に receipt の `outcome` で判定する（exit 0=done / 3=timeout=未完了・既定600秒 / 4=closed。親はブロックもポーリングもしない）。起動時 `prompt` を渡した launch は structured receipt にコピペ可能な `wait_command` と `event_cursor`、そして `submit_residue` 観測を含む（true=prompt が composer に未 submit で残存している疑い＝案内に従い画面確認から復旧 / false=残存観測せず・成立の保証ではない / null=対象外）。dispatch receipt にも同じ観測が付く。durable machine callerは`claude_turn({ action:"issue"|"recover", session_id, operation_id, ... })`を使い、人間向けerror文字列を解析せず`accepted`／`pending`／`completed`／`unknown`を判定できる。recoveryは再送せず、検証済み完了だけがexact `raw_output`を持つ。通常の`pty_send`／`pty_read`は対話callerと人間向けに維持する。`C-c`後もmarkerを保持し、Stopが来なければsessionをcloseする。`claude_agent` と `codex_agent` の初回 `prompt` は ready gate 経由で送信して待たずに返る（Grok/Composer は argv 渡し）。手動でキー操作したい場合は `pty_open` で素の端末を開き vendor CLI を自分で起動する。
 
+`codex_agent`・`grok_agent`・`composer_agent`は任意の`write_scope`（`"read-only"`または書込み許可パスの説明）も受ける。指定値はlaunch receipt・session metadata・`pty_list`へ保存する。Codexの`write_scope:"read-only"`だけは実効能力壁であり、aitermがCLIの`--sandbox read-only`を付ける。Grok/Composerには対応する対話起動sandboxがなく、Codexにもパス説明をallowlistへ変換するフラグがないため、それらは強制済みと偽らず`write_scope_enforcement:"declaration_only_unsupported"`を返す。`write_scope`を省略した起動は従来どおりである。
+
 ```text
 codex_agent({ session_name: "codex1", cwd: "/repo",
               prompt: "port test/legacy.py to vitest" })

package/README.md

@@ -145,6 +145,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).
 
+`codex_agent`, `grok_agent`, and `composer_agent` also accept an optional `write_scope`: either `"read-only"` or a human-readable description of writable paths. A supplied value is retained in the launch receipt, session metadata, and `pty_list`. For Codex, `write_scope: "read-only"` is an effective boundary: aiterm adds the CLI's `--sandbox read-only` flag. Grok/Composer have no corresponding interactive-launch sandbox, and Codex has no path-description allowlist flag; those cases return `write_scope_enforcement: "declaration_only_unsupported"` rather than claiming enforcement. Omitting `write_scope` preserves prior behavior.
+
 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

package/dist/core.js

@@ -1230,6 +1230,7 @@ export function listSessions() {
             const agent = [
                 `agent=${meta.kind}`,
                 "agent_done=true",
+                meta.write_scope === undefined ? null : `write_scope=${JSON.stringify(meta.write_scope)}`,
                 meta.vendor_session_id ? `vendor_session_id=${meta.vendor_session_id}` : null,
             ]
                 .filter(Boolean)
@@ -2261,7 +2262,7 @@ function createClaudeAgentMetadata(name, cwd, initialPrompt, launchOperationId,
     writeAgentMetadata(meta);
     return meta;
 }
-function createCodexAgentMetadata(name, cwd, initialPrompt, overrides = {}) {
+function createCodexAgentMetadata(name, cwd, initialPrompt, overrides = {}, writeScope) {
     const launchId = randomBytes(16).toString("hex");
     const eventFile = agentEventPath(name, launchId);
     createEmpty0600NoFollow(eventFile);
@@ -2273,6 +2274,7 @@ function createCodexAgentMetadata(name, cwd, initialPrompt, overrides = {}) {
         event_file: eventFile,
         created_at: new Date().toISOString(),
         cwd,
+        ...(writeScope === undefined ? {} : { write_scope: writeScope }),
         vendor_session_id: null,
         initial_prompt: initialPrompt,
         hook_route: "managed_codex_home",
@@ -2282,7 +2284,7 @@ function createCodexAgentMetadata(name, cwd, initialPrompt, overrides = {}) {
     writeAgentMetadata(meta);
     return meta;
 }
-function createGrokAgentMetadata(kind, name, cwd, initialPrompt, authPath) {
+function createGrokAgentMetadata(kind, name, cwd, initialPrompt, authPath, writeScope) {
     const launchId = randomBytes(16).toString("hex");
     const eventFile = agentEventPath(name, launchId);
     createEmpty0600NoFollow(eventFile);
@@ -2294,6 +2296,7 @@ function createGrokAgentMetadata(kind, name, cwd, initialPrompt, authPath) {
         event_file: eventFile,
         created_at: new Date().toISOString(),
         cwd,
+        ...(writeScope === undefined ? {} : { write_scope: writeScope }),
         vendor_session_id: null,
         initial_prompt: initialPrompt,
         hook_route: "managed_grok_home",
@@ -2355,6 +2358,7 @@ function loadAgentMetadata(name) {
             event_file: expectedEvent,
             created_at: typeof m.created_at === "string" ? m.created_at : "",
             cwd: typeof m.cwd === "string" ? m.cwd : null,
+            ...(typeof m.write_scope === "string" ? { write_scope: m.write_scope } : {}),
             vendor_session_id: typeof m.vendor_session_id === "string" ? m.vendor_session_id : null,
             initial_prompt: normalizeInitialPromptState(m.initial_prompt),
             launch_operation_id: launchOperationId,
@@ -2377,6 +2381,7 @@ function loadAgentMetadata(name) {
             event_file: expectedEvent,
             created_at: typeof m.created_at === "string" ? m.created_at : "",
             cwd: typeof m.cwd === "string" ? m.cwd : null,
+            ...(typeof m.write_scope === "string" ? { write_scope: m.write_scope } : {}),
             vendor_session_id: typeof m.vendor_session_id === "string" ? m.vendor_session_id : null,
             initial_prompt: normalizeInitialPromptState(m.initial_prompt),
             hook_route: "managed_codex_home",
@@ -2400,6 +2405,7 @@ function loadAgentMetadata(name) {
         event_file: expectedEvent,
         created_at: typeof m.created_at === "string" ? m.created_at : "",
         cwd: typeof m.cwd === "string" ? m.cwd : null,
+        ...(typeof m.write_scope === "string" ? { write_scope: m.write_scope } : {}),
         vendor_session_id: typeof m.vendor_session_id === "string" ? m.vendor_session_id : null,
         initial_prompt: normalizeInitialPromptState(m.initial_prompt),
         hook_route: "managed_grok_home",
@@ -3448,6 +3454,10 @@ function buildAgentCmd(kind, bin, model, effort, prompt, meta = null) {
     else if (kind === "codex") {
         if (meta?.kind === "codex")
             parts.push("--dangerously-bypass-hook-trust");
+        // `codex --help` で確認した実在フラグ。read-only 宣言だけはCLI sandboxへ落とし、
+        // launcher自身が実効能力壁を作る。パス説明はCodex CLIに同等のallowlist引数がないため宣言のまま残す。
+        if (meta?.kind === "codex" && meta.write_scope === "read-only")
+            parts.push("--sandbox", "read-only");
         // model/effort は CLI 引数で明示（config 継承より優先）。agent_done 時は managed home 側
         // config.toml も同値で上書き済み（applyCodexConfigOverrides）。
         if (model)
@@ -3516,12 +3526,17 @@ function agentLabel(kind) {
 // model_reasoning_effort）が対話子へ波及する構造のため、引数・端末config継承・CLI既定の
 // どれで起動したかを起動時点で可視化し、実効 effort=ultra は proactive 自動委譲 ON を警告する。
 function buildAgentLaunchNote(kind, model, effort, meta) {
+    const writeScopeNote = meta?.write_scope === undefined
+        ? ""
+        : kind === "codex" && meta.write_scope === "read-only"
+            ? `\n能力宣言: write_scope=${JSON.stringify(meta.write_scope)}。Codex CLIへ --sandbox read-only を付与し、書込みを実効禁止。`
+            : `\n能力宣言: write_scope=${JSON.stringify(meta.write_scope)}。${kind === "grok" || kind === "composer" ? "このCLIには起動sandbox機構がないため" : "パス単位のsandbox allowlistに対応するCLI引数がないため"}宣言の記録のみ（構造的unsupported）。`;
     if (kind === "claude") {
-        return `起動設定: model=${model ?? "CLI既定"} effort=${effort ?? "CLI既定"}。`;
+        return `起動設定: model=${model ?? "CLI既定"} effort=${effort ?? "CLI既定"}。${writeScopeNote}`;
     }
     if (kind !== "codex") {
         return (`起動設定: model=${model ?? GROK_MODEL_DEFAULTS[kind]}（${model ? "引数" : "ツール既定"}）。` +
-            "reasoning effort は対話 TUI 非対応＝未指定で起動。");
+            "reasoning effort は対話 TUI 非対応＝未指定で起動。" + writeScopeNote);
     }
     const configPath = meta?.kind === "codex" && meta.codex_home
         ? path.join(meta.codex_home, "config.toml")
@@ -3540,7 +3555,7 @@ function buildAgentLaunchNote(kind, model, effort, meta) {
             ? "⚠ effort=ultra は max 推論＋proactive 自動委譲 ON（子エージェント自動生成・使用量急増に注意）。"
             : "");
     const summary = meta?.kind === "codex" && meta.codex_home ? managedCodexConfigSummary(configPath, true) : "";
-    return summary ? `${launch}\n${summary}\n` : launch;
+    return (summary ? `${launch}\n${summary}\n` : launch) + writeScopeNote;
 }
 function claudeLaunchRequestDigest({ sessionName, model, effort, cwd, agentDone, }) {
     const canonical = JSON.stringify({
@@ -3582,6 +3597,7 @@ export function openAgent(kind, opts = {}) {
             throw new AitermError("model が空文字です（省略するか有効なモデル名を指定してください）", 2);
     }
     const effort = opts.reasoning_effort ?? null;
+    const writeScope = opts.write_scope;
     if (effort && kind === "claude" && !CLAUDE_EFFORTS.has(effort)) {
         throw new AitermError("Claude Code の reasoning_effort は low/medium/high/xhigh/max のいずれかです", 2);
     }
@@ -3690,8 +3706,8 @@ export function openAgent(kind, opts = {}) {
             ? kind === "claude"
                 ? createClaudeAgentMetadata(sid, cwd, opts.prompt ? "pending" : "none", launchOperationId, launchRequestDigest)
                 : kind === "codex"
-                    ? createCodexAgentMetadata(sid, cwd, opts.prompt ? "pending" : "none", { model, effort })
-                    : createGrokAgentMetadata(kind, sid, cwd, opts.prompt ? "pending" : "none", grokAuthPath)
+                    ? createCodexAgentMetadata(sid, cwd, opts.prompt ? "pending" : "none", { model, effort }, writeScope)
+                    : createGrokAgentMetadata(kind, sid, cwd, opts.prompt ? "pending" : "none", grokAuthPath, writeScope)
             : null;
         if (meta)
             agentMetadataNegativeCache.delete(sid);
@@ -3754,6 +3770,7 @@ export async function openAgentWithInitialPrompt(kind, opts = {}) {
             prompt,
             agent_done: true,
             launch_operation_id: opts.launch_operation_id ?? null,
+            write_scope: opts.write_scope,
         });
         // argv prompt（grok/composer）は composer を経由しないため submit 座礁観測の対象外。
         return [sid, hint, prompt ? 0 : null, null];
@@ -3766,6 +3783,7 @@ export async function openAgentWithInitialPrompt(kind, opts = {}) {
         prompt: null,
         agent_done: true,
         launch_operation_id: opts.launch_operation_id ?? null,
+        write_scope: opts.write_scope,
     });
     try {
         const initial = await sendInitialAgentPrompt(sid, prompt, {

package/dist/index.js

@@ -420,6 +420,19 @@ const agentCompletionDesc = `起動して投げたら投げっぱなしでよい
     `結果回収は pty_read(agent_transcript:true)。`;
 function registerAgentTool(toolName, kind, desc) {
     const correlatedLaunchSchema = {};
+    const supportsWriteScope = kind === "codex" || kind === "grok" || kind === "composer";
+    const writeScopeInputSchema = supportsWriteScope
+        ? {
+            write_scope: z.string().min(1).optional().describe("能力宣言。read-only、または書込みを許可するパスの説明文字列。Codexのread-onlyだけはCLI sandboxで実効禁止する"),
+        }
+        : {};
+    const writeScopeOutputSchema = supportsWriteScope
+        ? {
+            // write_scope省略時は既存launch receiptを完全に保つため両fieldを出さない。
+            write_scope: z.string().optional(),
+            write_scope_enforcement: z.enum(["enforced_read_only", "declaration_only_unsupported"]).optional(),
+        }
+        : {};
     if (kind === "claude") {
         correlatedLaunchSchema.launch_operation_id = z
             .string()
@@ -437,6 +450,7 @@ function registerAgentTool(toolName, kind, desc) {
             reasoning_effort: z.string().nullish().describe(agentEffortDesc(kind)),
             cwd: z.string().nullish().describe("作業ディレクトリ（対象リポのルート等・任意）"),
             session_name: z.string().nullish().describe("セッション名（省略で自動採番）"),
+            ...writeScopeInputSchema,
             ...correlatedLaunchSchema,
         },
         outputSchema: {
@@ -451,8 +465,9 @@ function registerAgentTool(toolName, kind, desc) {
             // 初回prompt dispatch後のsubmit座礁観測（additive）。true=composerに残存を確認（submit未成立の疑い）/
             // false=残存を観測せず（submit成立の保証ではない）/ null=promptなし・argv prompt・判定不能。
             submit_residue: z.boolean().nullable(),
+            ...writeScopeOutputSchema,
         },
-    }, async ({ prompt, model, reasoning_effort, cwd, session_name, launch_operation_id }) => {
+    }, async ({ prompt, model, reasoning_effort, cwd, session_name, launch_operation_id, write_scope }) => {
         try {
             const [sid, hint, eventCursor, submitResidue] = await core.openAgentWithInitialPrompt(kind, {
                 prompt: prompt ?? undefined,
@@ -461,6 +476,7 @@ function registerAgentTool(toolName, kind, desc) {
                 cwd: cwd ?? undefined,
                 session_name: session_name ?? undefined,
                 launch_operation_id: launch_operation_id ?? undefined,
+                ...(supportsWriteScope ? { write_scope } : {}),
             });
             const structured = {
                 schema: "aiterm.agent-launch-result.v1",
@@ -470,6 +486,14 @@ function registerAgentTool(toolName, kind, desc) {
                 event_cursor: eventCursor,
                 wait_command: eventCursor === null ? null : `aiterm-wait --session ${sid} --cursor ${eventCursor}`,
                 submit_residue: submitResidue,
+                ...(supportsWriteScope && write_scope !== undefined
+                    ? {}
+                    : supportsWriteScope ? {
+                        write_scope,
+                        write_scope_enforcement: kind === "codex" && write_scope === "read-only"
+                            ? "enforced_read_only"
+                            : "declaration_only_unsupported",
+                    } : {}),
             };
             return {
                 content: [{ type: "text", text: `session_id: ${sid}\n${hint}` }],

package/package.json

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