aiterm-mcp 0.29.31 → 0.31.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-09-04
+
+### Fixed
+
+- Claude Codeのturnが529 Overloaded等のAPIエラーで打ち切られるとStop hookが走らず、`aiterm-wait`が永久に未完了を返し続けていた（実被弾 2026-09-03: BellTeamのClaude席で70分の待機）。会話記録（`<config dir>/projects/<cwd slug>/<session-id>.jsonl`）に観測開始後に増えた`isApiErrorMessage:true`の行を読み、新しいoutcome `error`（exit 7、`error`にエラー本文）で返す。
+- Grokの`turn_ended outcome=error`を完了境界として扱わず待ち続けていた。同じくoutcome `error`で返す。Cursorは`turn_ended`のstatusを問わず既に終了を返していたため変更なし。Codexはエラー終了の記録形が実測できておらず未対応。
+
+## [0.30.0] - 2026-09-04
+
+### Added
+
+- `pty_send`（agent dispatch）、`agent_steer`、`agent_launch`に`image`（画像ファイルの絶対パスの配列）を追加した。aitermが本文末尾へ添付行を付け、Claude Code／Codex／Grok／Cursorはいずれも自分のfile読取toolでそのpathを画像として開く（実測 2026-09-04）。呼出し側が入力欄へパスを先打鍵する等のharness別手順を持つ必要を無くす。相対パス・未対応拡張子・不在fileは送信前にtyped errorで拒否し、通常PTY送信とforce送信では指定できない。
+
 ## [0.29.31] - 2026-09-04
 
 ### Fixed
@@ -1540,7 +1553,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.29.31...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.0...HEAD
+[0.31.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.30.0...v0.31.0
+[0.30.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.31...v0.30.0
 [0.29.31]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.30...v0.29.31
 [0.29.30]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.29...v0.29.30
 [0.29.29]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.28...v0.29.29

package/README.ja.md

@@ -153,7 +153,7 @@ runtime-error store は canonical dotagents config の `collection.enabled: true
 場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
 Publishing）で公開し、GitHub Release が Official MCP Registry を再登録します。
 
-**状態:** 開発継続中 · 現行公開版 **v0.29.31** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.31.0** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
@@ -189,6 +189,8 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 `aiterm.agent-launch-result.v1`は正規`harness`を返し、旧`provider`は互換fieldとして残す。同じ`harness`はagent dispatch、`aiterm-wait`、`agent_configure`、`pty_list`のagent行にも載り、旧vendor／provider／agent fieldは互換用に残る。Codexは通常rollout、Grok CLIは通常session event、Claudeはlaunch固有Stop hook、Cursorは通常agent transcript末尾の`turn_ended`を完了正本に使う。`pty_send`は非ブロックdispatchで、vendor別完了境界を表すopaqueな整数`event_cursor`を返し、完了通知は`aiterm-wait`を親のターンを塞がない別processで受ける。Cursorのsubmitキーはadapterが現行CLIのextended keyboard protocolへ変換する。送信textがCursorのcomposerへ残った場合は成功receiptを返さず失敗する。
 
+`agent_launch`・`pty_send`（agent dispatch）・`agent_steer`は任意の`image`（画像ファイルの絶対パスの配列。png/jpg/jpeg/gif/webp）を受ける。aitermが本文末尾へ添付行を付け、どのharnessも自分のfile読取toolでそのpathを画像として開く。呼出し側はharness別の添付手順を覚えない。不正なpathは送信前に拒否する。
+
 `agent_launch`は任意の`write_scope`も受ける。Codex／Grokのread-onlyは`--sandbox read-only`、Cursorは公式`--mode ask`で実効化する。path説明は同等CLI引数がないためdeclaration-only。
 
 ```text
@@ -199,7 +201,7 @@ agent_launch({ harness: "codex-cli", session_name: "codex1", cwd: "/repo",
                                     → { session_id: "codex1", … }   # Codex が永続端末で稼働開始
 pty_read("codex1", { screen: true })   → 何をしているか読む（トークン削減）
 pty_send("codex1", "also fix the imports it broke")   # 非ブロックdispatch＝event_cursor入りreceipt
-$ aiterm-wait --session codex1 --cursor <event_cursor>   # exit 0=done / 3=timeout(未完了) / 4=closed。回収は pty_read(agent_transcript:true)
+$ aiterm-wait --session codex1 --cursor <event_cursor>   # exit 0=done / 3=timeout(未完了) / 4=closed / 7=error(APIエラー等でturn打ち切り)。回収は pty_read(agent_transcript:true)
                                     → 操舵し、Codex の次の入力境界で返る
 ```
 

package/README.md

@@ -169,7 +169,7 @@ 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.29.31** · 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.31.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
 
@@ -211,6 +211,8 @@ The same primitive hosts another agent's TUI. `agent_launch` starts a selected e
 
 The human-readable launch text is accompanied by an `aiterm.agent-launch-result.v1` structured receipt containing the canonical `harness`; the old `provider` field remains for compatibility. The same `harness` is carried by agent dispatch, `aiterm-wait`, `agent_configure`, and agent rows in `pty_list`, while their old vendor/provider/agent fields remain compatibility fields. Codex completion comes from its normal durable rollout transcript, Grok CLI from its normal session events, Claude Code from a launch-specific Stop hook settings addition, and Cursor from its normal agent transcript's terminal `turn_ended` record. Sending to any agent session is a non-blocking **dispatch** — the call returns immediately with an opaque, harness-specific integer `event_cursor`, and completion arrives via [`aiterm-wait`](#completion-push-for-parent-agents-aiterm-wait). The Cursor adapter translates submit into the current CLI's extended keyboard protocol. If submitted text remains in Cursor's composer, its dispatch fails instead of returning a successful receipt.
 
+`agent_launch`, `pty_send` (agent dispatch), and `agent_steer` accept an optional `image`: an array of absolute paths to image files (png/jpg/jpeg/gif/webp). Aiterm appends an attachment block to the prompt, and every harness opens the path with its own file-reading tool and sees the image; the caller never learns harness-specific attachment tricks. Invalid paths are rejected before anything is sent.
+
 `agent_launch` accepts an optional `write_scope`: either `"read-only"` or a human-readable description of writable paths. Codex/Grok use `--sandbox read-only`; Cursor uses its official read-only `--mode ask`. A path description remains declaration-only because these CLI launch surfaces provide no equivalent path allowlist flag.
 
 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.
@@ -224,7 +226,7 @@ agent_launch({ harness: "codex-cli", session_name: "codex1", cwd: "/repo",
 pty_read("codex1", { screen: true })   → read what it's doing (token-reduced)
 pty_send("codex1", "also fix the imports it broke")
                                     → non-blocking dispatch; receipt carries event_cursor
-$ aiterm-wait --session codex1 --cursor <event_cursor>   # never in the parent's foreground; exit 0=done, 3=timeout (not done), 4=closed
+$ aiterm-wait --session codex1 --cursor <event_cursor>   # never in the parent's foreground; exit 0=done, 3=timeout (not done), 4=closed, 7=error (turn aborted by an API error)
 pty_read("codex1", { agent_transcript: true })           → collect the full answer
 ```
 

package/dist/aiterm-wait-cli.js

@@ -2,7 +2,7 @@
 // aiterm-wait — agent turn 完了eventの純リーダー観測CLI。
 // 完了/timeout/close を1行のJSON receiptで返してexitする。lock・PTY・dispatch状態には一切触れない。
 // 親AIホストのバックグラウンドタスクとして起動し、exitを「観測終了の通知」として使う。
-// exit≠完了: exit code は outcome を映す（0=done / 5=running=未完了 / 3=timeout=未完了 / 4=closed / 6=rate_limited=harness利用上限 / 1=エラー）。
+// exit≠完了: exit code は outcome を映す（0=done / 5=running=未完了 / 3=timeout=未完了 / 4=closed / 6=rate_limited=harness利用上限 / 7=error=turnがエラー終了 / 1=waiter自身のエラー）。
 // --timeout 0 は待たずに一度だけ観測する照会で、未完了は running（timeout と混同させない）。
 // receipt の outcome が正で、done 以外は未完了。timeout の既定は core の DEFAULT_AGENT_DONE_TIMEOUT（600秒）。
 import { fileURLToPath } from "node:url";
@@ -75,6 +75,7 @@ const OUTCOME_EXIT_CODES = {
     timeout: 3,
     closed: 4,
     rate_limited: 6,
+    error: 7,
 };
 export async function main(argv) {
     const cmd = parseArgs(argv);

package/dist/core.js

@@ -18,7 +18,7 @@ import { isWin, SOCKDIR, tmuxCommand, sendPsmuxPayload, loadPtyBufferChunk, past
 import { sleep, currentUid, runtimeStateBase, safeStatSize, readFileRange, writeJson0600, createEmpty0600, shq, LAUNCH_ID_RE, AGENT_DONE_POLL_MS, AGENT_EVENT_MAX_BYTES, assertSessionName, agentsDir, agentEventPath, agentMetadataPath, writeAgentMetadata, AGENT_EVENT_TAIL_BYTES, agentLabel, agentHarness, subagentInstruction, agentLineageFields, } from "./agent-shared.js";
 import { GROK_MODEL_DEFAULTS, realGrokHome, resolveAndValidateGrokAuth, assertGrokModelAvailable, grokEventsTranscript, latestGrokCompletion, observeGrokDone, buildGrokAgentCmd, grokLaunchNote, grokEnvTokens, grokTuiReady, GROK_COMPOSER_MARKER_RE, grokFooterHasConfiguration, grokTranscriptText, createGrokAgentMetadata, } from "./harnesses/grok.js";
 import { bindCodexTranscriptSession, latestCodexCompletion, observeCodexDone, buildCodexAgentCmd, codexLaunchNote, codexTuiReady, codexLaunchBlockingDialog, CODEX_COMPOSER_MARKER_RE, codexModelChoice, codexEffortChoice, codexMoreReasoningChoice, codexTranscriptText, createCodexAgentMetadata, } from "./harnesses/codex.js";
-import { OPERATION_ID_RE, CLAUDE_RESULT_MAX_BYTES, CLAUDE_EFFORTS, agentManagedClaudeSettingsPath, agentClaudeResultPath, agentClaudeOperationPath, agentClaudeApprovalReceiptPath, agentClaudeDispatchReceiptPath, validateOperationId, readClaudeResultText, assertClaudeAuthenticationReady, buildClaudeAgentCmd, claudeLaunchNote, claudeTuiReady, CLAUDE_COMPOSER_MARKER_RE, createClaudeAgentMetadata, } from "./harnesses/claude.js";
+import { OPERATION_ID_RE, CLAUDE_RESULT_MAX_BYTES, CLAUDE_EFFORTS, agentManagedClaudeSettingsPath, agentClaudeResultPath, agentClaudeOperationPath, agentClaudeApprovalReceiptPath, agentClaudeDispatchReceiptPath, validateOperationId, readClaudeResultText, assertClaudeAuthenticationReady, buildClaudeAgentCmd, claudeLaunchNote, claudeTuiReady, CLAUDE_COMPOSER_MARKER_RE, createClaudeAgentMetadata, claudeSessionTranscriptPath, claudeApiErrorFromLine, } from "./harnesses/claude.js";
 import { bindCursorTranscriptSession, cursorTurnBoundary, latestCursorCompletion, observeCursorDone, cursorTranscriptText, assertCursorAuthenticationReady, assertCursorModelAvailable, buildCursorAgentCmd, cursorPromptWithLineage, createCursorAgentMetadata, cursorLaunchNote, cursorEffortNavigation, cursorTuiReady, CURSOR_SUBMIT_SEQUENCE, CURSOR_COMPOSER_CONTENT_MARKER_RE, validateCursorModelEffort, } from "./harnesses/cursor.js";
 import { resolveAgentBin, resolveThroughlineBin, runThroughlineHandoffContext, isWindowsNativeExecutable, agentBinForPaneShell, resolveWinPaneShell } from "./agent-resolver.js";
 export { AitermError } from "./errors.js";
@@ -2251,7 +2251,7 @@ function assertInitialPromptNotPendingForSend(name, force) {
         `${agentWaitGuide(name)}完了後に再度 pty_send するか、手動介入が必要な場合だけ force:true を明示してください。`, 2);
 }
 // aiterm-wait の exit 契約（CLI と各所の案内文で共有する正）。exit≠完了: outcome が done の時だけ完了。
-export const AITERM_WAIT_OUTCOME_NOTE = `exit 0=done / 3=timeout（既定${DEFAULT_AGENT_DONE_TIMEOUT}秒・未完了） / 4=closed。receiptのoutcomeが正で、done以外は未完了`;
+export const AITERM_WAIT_OUTCOME_NOTE = `exit 0=done / 3=timeout（既定${DEFAULT_AGENT_DONE_TIMEOUT}秒・未完了） / 4=closed / 7=error（harnessの記録でturnがAPIエラー等で打ち切られた。結果は無い）。receiptのoutcomeが正で、done以外は未完了`;
 function quoteWindowsProcessArgument(value) {
     if (value !== "" && !/[\s"]/u.test(value))
         return value;
@@ -2393,7 +2393,12 @@ export async function observeAgentDone(name, o = {}) {
     let cursor = startOffset;
     let carry = "";
     let malformedEvents = 0;
-    const observation = (outcome, ev = null, rateLimit = null) => ({
+    // Claudeの会話記録はこの観測開始時点の末尾から先だけを読む。過去turnのAPIエラー行を今回の
+    // 終了と誤認しないため。dispatch直後に待機を始める親（receiptのwait_process）を前提にする。
+    const transcriptFile = claudeSessionTranscriptPath(meta);
+    let transcriptCursor = transcriptFile ? safeStatSize(transcriptFile) : 0;
+    let transcriptCarry = "";
+    const observation = (outcome, ev = null, rateLimit = null, apiError = null) => ({
         schema: "aiterm.agent-wait-result.v1",
         session_id: meta.aiterm_session,
         launch_id: meta.launch_id,
@@ -2404,8 +2409,9 @@ export async function observeAgentDone(name, o = {}) {
         vendor_session_id: ev?.vendor_session_id ?? meta.vendor_session_id ?? null,
         turn_id: ev?.turn_id ?? null,
         malformed_events: malformedEvents,
-        at: ev?.at ?? null,
+        at: ev?.at ?? apiError?.at ?? null,
         rate_limit: rateLimit,
+        error: apiError?.text ?? null,
     });
     for (;;) {
         if (!fs.existsSync(metadataFile))
@@ -2431,6 +2437,24 @@ export async function observeAgentDone(name, o = {}) {
             if (scanned.event)
                 return observation("done", scanned.event);
         }
+        if (transcriptFile && fs.existsSync(transcriptFile)) {
+            const transcriptSize = safeStatSize(transcriptFile);
+            if (transcriptSize < transcriptCursor) {
+                transcriptCursor = 0;
+                transcriptCarry = "";
+            }
+            if (transcriptSize > transcriptCursor) {
+                transcriptCarry += readFileRange(transcriptFile, transcriptCursor, transcriptSize).toString("utf8");
+                transcriptCursor = transcriptSize;
+                const lines = transcriptCarry.split("\n");
+                transcriptCarry = lines.pop() ?? "";
+                for (const line of lines) {
+                    const apiError = claudeApiErrorFromLine(line);
+                    if (apiError)
+                        return observation("error", null, null, apiError);
+                }
+            }
+        }
         // timeout=0 は「待たずに一度だけ見る」照会＝未完了は失敗ではなく running。
         // 1秒以上を指定した待機の未完了は従来どおり timeout で、待ち方の意味は変えない。
         {
@@ -3049,6 +3073,37 @@ export function __testCodexConfigureChoices(screen, model, effort) {
 // v0.16.0: 親をブロックする wait 経路は廃止した。send は ready gate と submit 分離を内蔵した
 // dispatch として即返り、event_cursor（送信直前のharness完了正本境界）を receipt で返す。
 // 完了通知は aiterm-wait（--cursor で境界を渡す）、回収は pty_read / claude_turn recover が担う。
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+/**
+ * 画像添付。Claude Code／Codex／Grok／Cursorの4 harnessは、本文に書かれた画像ファイルの絶対パスを
+ * 自分のfile読取toolで開いて画像として見る（実測 2026-09-04: 赤青の試験画像を全harnessが正しく答えた）。
+ * 入力欄へパスを先打鍵する等のharness別操作は不要であり、呼出し側にharnessの癖を覚えさせない。
+ * 添付の表現とpath検査はこの1箇所だけが所有する。検査は外部入力（呼出し側が渡すpath）の境界。
+ */
+export function attachImages(text, images) {
+    if (!images || images.length === 0)
+        return text;
+    const lines = images.map((image, index) => {
+        if (typeof image !== "string" || !path.isAbsolute(image)) {
+            throw new AitermError(`image[${index}] は画像ファイルの絶対パスで指定してください: ${String(image)}`, 2);
+        }
+        if (!IMAGE_EXTENSIONS.has(path.extname(image).toLowerCase())) {
+            throw new AitermError(`image[${index}] の拡張子に対応していません（png/jpg/jpeg/gif/webp）: ${image}`, 2);
+        }
+        let st;
+        try {
+            st = fs.statSync(image);
+        }
+        catch {
+            throw new AitermError(`image[${index}] が読めません: ${image}`, 2);
+        }
+        if (!st.isFile())
+            throw new AitermError(`image[${index}] はfileではありません: ${image}`, 2);
+        return `[aiterm 添付画像 ${index + 1}/${images.length}] ${image}`;
+    });
+    const body = text.trim().length > 0 ? text : "添付画像を確認してください。";
+    return `${body}\n\n${lines.join("\n")}\n添付画像は上のファイルを読んで確認する。`;
+}
 export async function dispatchAgentTurn(name, text, o = {}) {
     assertSessionName(name);
     const meta = loadAgentMetadata(name);

package/dist/harnesses/claude.js

@@ -2,6 +2,7 @@
 // core 所有のサービス（transcript 不在エラー）は引数で注入し、
 // 依存方向を core → harnesses → agent-shared の一方向に保つ。
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
@@ -216,3 +217,45 @@ export function createClaudeAgentMetadata(name, cwd, initialPrompt, launchOperat
     writeAgentMetadata(meta);
     return meta;
 }
+// ---------------------------------------------------------------- APIエラー終了の検知（会話記録）
+// Claude CodeはAPIエラー（529 Overloaded等）でturnを打ち切る時、Stop hookを走らせない。
+// 代わりに会話記録（<config dir>/projects/<cwd slug>/<session-id>.jsonl）へ
+// `type:"assistant", isApiErrorMessage:true, apiErrorStatus:<code>` の1行を書く（実測 2026-09-03、
+// BellTeamのチャイム席で70分の待機を生んだ529）。完了eventだけを待つと永久に running になるため、
+// dispatch後に増えた記録行からこの印を読み、outcome=error として親へ返す。
+export function claudeConfigDir() {
+    return process.env.CLAUDE_CONFIG_DIR ?? path.join(process.env.HOME ?? os.homedir(), ".claude");
+}
+// Claude Codeのproject slug: cwdの英数字以外を1文字ずつ "-" にする（実測: "/Users/kite/.throughline-x" → "-Users-kite--throughline-x"）。
+export function claudeProjectSlug(cwd) {
+    return cwd.replace(/[^a-zA-Z0-9]/g, "-");
+}
+export function claudeSessionTranscriptPath(meta) {
+    if (meta.kind !== "claude" || !meta.vendor_session_id)
+        return null;
+    return path.join(claudeConfigDir(), "projects", claudeProjectSlug(meta.cwd ?? process.cwd()), `${meta.vendor_session_id}.jsonl`);
+}
+export function claudeApiErrorFromLine(line) {
+    if (!line.trim())
+        return null;
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (record?.type !== "assistant" || record?.isApiErrorMessage !== true)
+        return null;
+    const content = record?.message?.content;
+    const text = typeof content === "string"
+        ? content
+        : Array.isArray(content)
+            ? content.map((part) => (typeof part?.text === "string" ? part.text : "")).join("")
+            : "";
+    const status = record?.apiErrorStatus;
+    return {
+        text: text.trim() || (status != null ? `API Error: ${String(status)}` : "API Error"),
+        at: typeof record?.timestamp === "string" ? record.timestamp : null,
+    };
+}

package/dist/harnesses/codex.js

@@ -272,6 +272,7 @@ export async function observeCodexDone(meta, timeout, requestedCursor, detectRat
         malformed_events: malformedEvents,
         at: ev?.at ?? null,
         rate_limit: rateLimit,
+        error: null,
     });
     for (;;) {
         if (!fs.existsSync(metadataFile))

package/dist/harnesses/cursor.js

@@ -202,6 +202,7 @@ export async function observeCursorDone(meta, timeout, requestedCursor, detectRa
         malformed_events: malformedEvents,
         at: ev?.at ?? null,
         rate_limit: rateLimit,
+        error: null,
     });
     for (;;) {
         if (!fs.existsSync(metadataFile))

package/dist/harnesses/grok.js

@@ -81,7 +81,7 @@ export function grokEventsTranscript(meta) {
 export function grokCompletionEvent(meta, record) {
     if ((meta.kind !== "grok" && meta.kind !== "composer") ||
         record?.type !== "turn_ended" ||
-        (record?.outcome !== "completed" && record?.outcome !== "cancelled"))
+        (record?.outcome !== "completed" && record?.outcome !== "cancelled" && record?.outcome !== "error"))
         return null;
     const turnId = typeof record?.ts === "string" || typeof record?.ts === "number" ? String(record.ts) : null;
     return {
@@ -93,7 +93,9 @@ export function grokCompletionEvent(meta, record) {
         turn_id: turnId,
         operation_id: null,
         reason: `Grok transcript turn_ended:${record.outcome}`,
-        done_status: "turn_done",
+        // Grok CLIはAPIエラー等でturnを打ち切る時も turn_ended を書き、outcome だけが error になる
+        // （実測: 手元の events.jsonl に outcome=error が17件）。完了と同じ境界だが結果は無い。
+        done_status: record.outcome === "error" ? "turn_error" : "turn_done",
         stop_hook_active: false,
         at: typeof record?.ts === "string" ? record.ts : new Date().toISOString(),
     };
@@ -166,6 +168,7 @@ export async function observeGrokDone(meta, timeout, requestedCursor, detectRate
         malformed_events: malformedEvents,
         at: ev?.at ?? null,
         rate_limit: rateLimit,
+        error: ev?.done_status === "turn_error" ? ev.reason : null,
     });
     for (;;) {
         if (!fs.existsSync(metadataFile))
@@ -204,7 +207,7 @@ export async function observeGrokDone(meta, timeout, requestedCursor, detectRate
                     try {
                         const done = grokCompletionEvent(meta, JSON.parse(line));
                         if (done)
-                            return observation("done", done);
+                            return observation(done.done_status === "turn_error" ? "error" : "done", done);
                     }
                     catch {
                         malformedEvents++;

package/dist/index.js

@@ -136,6 +136,11 @@ server.registerTool("pty_send", {
             .describe("非Claude agent sessionでは自動dispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない"),
         rtk: z.boolean().default(false).describe("既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）"),
         raw: z.boolean().default(false).describe("送信前サニタイズを無効化"),
+        image: z
+            .array(z.string())
+            .optional()
+            .describe("添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）。agent session への dispatch だけで使え、" +
+            "harness別の添付手順はaitermが吸収する。通常PTY送信やforce送信では指定できない"),
     },
     outputSchema: {
         schema: z.literal("aiterm.pty-send-result.v1"),
@@ -152,7 +157,7 @@ server.registerTool("pty_send", {
         // dispatch前に行った pane 入力の回復（"fg" / "fg_stopped" / "stty_raw"）。通常送信では省略（additive）。
         pane_input_recovery: z.array(z.string()).optional(),
     },
-}, async ({ session_id, text, enter, mark, force, rtk, raw }) => {
+}, async ({ session_id, text, enter, mark, force, rtk, raw, image }) => {
     try {
         if (!force && core.isAgentSession(session_id)) {
             if (enter === false)
@@ -161,7 +166,7 @@ server.registerTool("pty_send", {
                 throw new Error("agent session への dispatch は mark:true と併用できません");
             if (rtk)
                 throw new Error("agent session への dispatch は rtk:true と併用できません");
-            const receipt = await core.dispatchAgentTurn(session_id, text, { raw });
+            const receipt = await core.dispatchAgentTurn(session_id, core.attachImages(text, image), { raw });
             const waitProcess = core.agentWaitProcess(receipt.session_id, receipt.event_cursor);
             return {
                 content: [
@@ -186,6 +191,9 @@ server.registerTool("pty_send", {
                 },
             };
         }
+        if (image && image.length > 0) {
+            throw new Error("image は agent session への dispatch（forceなし）だけで使えます。通常PTY送信では本文にpathを書いてください");
+        }
         const out = core.send(session_id, text, { enter, mark, force, rtk, raw });
         return {
             content: [{ type: "text", text: out }],
@@ -212,6 +220,7 @@ server.registerTool("agent_steer", {
     inputSchema: {
         session_id: z.string(),
         text: z.string().describe("現在のターンへ追加する文字列。UTF-8で最大64KiB"),
+        image: z.array(z.string()).optional().describe("添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）"),
     },
     outputSchema: {
         schema: z.literal("aiterm.agent-steer.v1"),
@@ -221,9 +230,9 @@ server.registerTool("agent_steer", {
         harness: z.enum(["codex-cli", "grok-cli"]),
         delivery: z.enum(["steered", "idle"]),
     },
-}, async ({ session_id, text }) => {
+}, async ({ session_id, text, image }) => {
     try {
-        const receipt = await core.steerAgentTurn(session_id, text);
+        const receipt = await core.steerAgentTurn(session_id, core.attachImages(text, image));
         return {
             content: [{ type: "text", text: `${receipt.delivery} ${receipt.session_id}` }],
             structuredContent: receipt,
@@ -547,13 +556,14 @@ const agentEnvironmentDesc = `通常CLIと同じHOME・cwd・project/user/local
     `delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。`;
 async function launchAgent(kind, args) {
     const supportsWriteScope = kind !== "claude";
-    const { prompt, throughline_source_session, throughline_supplement_file, model, reasoning_effort, env_vars, cwd, session_name, launch_operation_id, write_scope } = args;
+    const { prompt, image, throughline_source_session, throughline_supplement_file, model, reasoning_effort, env_vars, cwd, session_name, launch_operation_id, write_scope } = args;
     try {
         if (!supportsWriteScope && write_scope !== undefined) {
             throw new core.AitermError("claude-code harnessはwrite_scopeに対応していません。指定を外してください", 2);
         }
+        const initialPrompt = image && image.length > 0 ? core.attachImages(prompt ?? "", image) : prompt ?? undefined;
         const [sid, hint, eventCursor, submitResidue] = await core.openAgentWithInitialPrompt(kind, {
-            prompt: prompt ?? undefined,
+            prompt: initialPrompt,
             throughline_source_session,
             throughline_supplement_file,
             model: model ?? undefined,
@@ -663,6 +673,7 @@ server.registerTool("agent_launch", {
     inputSchema: {
         harness: z.enum(["claude-code", "codex-cli", "grok-cli", "cursor-cli"]).describe("agent loop・session・hook・transcript・認証を所有する実行基盤"),
         prompt: z.string().nullish().describe("起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る"),
+        image: z.array(z.string()).optional().describe("初手プロンプトへ添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）"),
         throughline_source_session: z.string().min(1).optional().describe("同一端末のThroughline sessionから読み取り専用contextを初手へ注入する"),
         throughline_supplement_file: z.string().min(1).optional().describe("Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path"),
         model: z.string().nullish().describe("harnessが選ぶモデル。provider名ではなくlive catalog上のmodel ID"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.29.31",
+  "version": "0.31.0",
   "mcpName": "io.github.kitepon/aiterm-mcp",
   "description": "Persistent terminal MCP with one harness-based launcher for Claude Code, Codex CLI, Grok CLI, and Cursor Agent CLI, plus durable PTYs for SSH, containers, and REPLs.",
   "keywords": [