aiterm-mcp 0.53.2 → 0.54.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.54.0] - 2026-10-06
+
+### 変更
+
+- `pty_read(agent_transcript:true)`は、回答が空で終わったturnを誤りにせず、`text`が空文字列、`answer_empty`が`true`の
+  結果で返す（ADR 0092）。`aiterm.pty-read-result.v1`へ`answer_empty`を足した（回答がある時は`false`、terminalの読み取りは`null`）。
+  今までは、回答を空で終えただけのturnと、記録の形が変わって回答を読めなくなった時が、同じ
+  「最終 assistant メッセージを特定できませんでした」の誤りになり、呼び出し側が見分けられなかった。
+  Codex（0.160.1）は、道具で用を済ませて回答を空で終えたturnを、`text`が空の`final_answer`として記録に残す。
+  誤りにするのは、回答の場所を記録から見つけられない時だけにした（文面は同じ）。
+
+### 修正
+
+- 親への自動配送で、Codexの子が回答を空で終えると、親へ`AGENT_RESULT_UNAVAILABLE: transcript がまだありません。
+  ターン完了後に再取得してください`が`outcome=error`で届いていた。turnは終わっているので、
+  「子のターンは完了しましたが、回答の本文は空でした。」を`outcome=done`で届ける。Claude Code・Grok・Cursorの子も同じ。
+- Codexの回答の読み取りは、turn ID付きの本文が空の時に、turn IDの無い旧形式の本文（前のturnの物かもしれない）へ
+  落とす作りだった。turn ID付きの本文が記録にあれば、空でもそれを回答とする。今のCodexは旧形式を書かず、
+  実記録で前のturnの回答が返った例は確認していない。
+
 ## [0.53.2] - 2026-10-05
 
 ### 修正
@@ -2215,7 +2235,8 @@ 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.53.2...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.54.0...HEAD
+[0.54.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.53.2...v0.54.0
 [0.53.2]: https://github.com/kitepon/aiterm-mcp/compare/v0.53.1...v0.53.2
 [0.53.1]: https://github.com/kitepon/aiterm-mcp/compare/v0.53.0...v0.53.1
 [0.53.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.52.3...v0.53.0

package/README.ja.md

@@ -209,7 +209,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.53.2** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.54.0** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
@@ -648,7 +648,7 @@ handoff contextを前置きできる。この任意経路は`throughline >= 0.9.
 `THROUGHLINE_BIN`、次に`PATH`から解決し、不在・不正・空のexportはPTY作成前に明示失敗する。
 任意の`throughline_supplement_file`はThroughline 0.10.8以降と`throughline_source_session`を必要とし、Aitermは内容を解釈せずThroughlineへ渡す。
 
-エージェントの回答が画面tailより長ければ、`pty_read({ agent_transcript:true })`で再promptなしに全文回収する。既存の人間向けcontentは診断suffixを維持し、機械呼出し側は`aiterm.pty-read-result.v1`の`structuredContent.text`から回答本文だけを取得する。Claudeはlaunch相関Stop hook、Codexは通常rollout、Grokは最後の実user行以後の最後の空でないassistantメッセージだけ、Cursorはlaunch IDでbindした通常agent transcriptから同じturnを回収する。
+エージェントの回答が画面tailより長ければ、`pty_read({ agent_transcript:true })`で再promptなしに全文回収する。既存の人間向けcontentは診断suffixを維持し、機械呼出し側は`aiterm.pty-read-result.v1`の`structuredContent.text`から回答本文だけを取得する。Claudeはlaunch相関Stop hook、Codexは通常rollout、Grokは最後の実user行以後の最後の空でないassistantメッセージだけ、Cursorはlaunch IDでbindした通常agent transcriptから同じturnを回収する。回答を空で終えたturnは誤りにせず、`text`が空文字列、`answer_empty`が`true`で返すので、回答を読めなかった時と見分けられる。回答の場所を記録から見つけられない時だけ誤りにする。
 
 ### 完了検出（5 層）
 

package/README.md

@@ -223,7 +223,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.53.2** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
+**Status:** actively maintained · current public release **v0.54.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
 
@@ -689,7 +689,7 @@ unchanged. Optional `throughline_supplement_file` is passed unchanged to Through
 `throughline_source_session` and Throughline 0.10.8 or later; Aiterm does not read or classify the supplement. Throughline is resolved through `THROUGHLINE_BIN` and then `PATH`; a missing or invalid
 export fails before the PTY exists instead of silently launching clean.
 
-When an agent's answer is longer than the on-screen tail (pane height ≈ 24 lines), callers recover it in full with `pty_read({ agent_transcript: true })`. It returns the most recently completed turn's final assistant message in plain text with no re-prompting. The existing human-readable content keeps its diagnostic suffix; machine callers read the answer alone from `structuredContent.text` in `aiterm.pty-read-result.v1`. Claude reads the bounded owner-only result captured by the launch-correlated Stop hook and verifies its digest/byte count; it never reads Claude's private transcript. Durable machine callers should use `claude_turn`: `issue` sends once, `recover` never sends, `pending` is distinct from unsafe or malformed state, and only `completed` carries the exact verified `raw_output`. Codex uses the normal rollout transcript's `task_complete.turn_id`; Grok returns the last non-empty assistant message after the last real user row, excluding tool-use preambles; Cursor uses the normal agent transcript bound to the launch ID and current turn. Missing or ambiguous attribution remains an explicit error.
+When an agent's answer is longer than the on-screen tail (pane height ≈ 24 lines), callers recover it in full with `pty_read({ agent_transcript: true })`. It returns the most recently completed turn's final assistant message in plain text with no re-prompting. The existing human-readable content keeps its diagnostic suffix; machine callers read the answer alone from `structuredContent.text` in `aiterm.pty-read-result.v1`. Claude reads the bounded owner-only result captured by the launch-correlated Stop hook and verifies its digest/byte count; it never reads Claude's private transcript. Durable machine callers should use `claude_turn`: `issue` sends once, `recover` never sends, `pending` is distinct from unsafe or malformed state, and only `completed` carries the exact verified `raw_output`. Codex uses the normal rollout transcript's `task_complete.turn_id`; Grok returns the last non-empty assistant message after the last real user row, excluding tool-use preambles; Cursor uses the normal agent transcript bound to the launch ID and current turn. A turn that completed with an empty answer is not an error: `text` is the empty string and `answer_empty` is `true`, so callers can tell it apart from an answer that could not be read. Missing or ambiguous attribution, including an answer that cannot be located in the record, remains an explicit error.
 
 ### Completion detection (5 layers)
 

package/dist/core.js

@@ -2681,6 +2681,8 @@ function agentCompletionCursor(meta) {
 function transcriptUnavailable() {
     throw new AitermError(`transcript がまだありません。ターン完了後に再取得してください。${agentWaitGuide()}`, 2);
 }
+/** 完了したturnの回答が空だった時に、人とAIが読む表示へ出す文。機械はstructuredContentのanswer_emptyを見る。 */
+const AGENT_ANSWER_EMPTY_NOTICE = "このターンは完了しましたが、回答の本文は空でした。";
 function transcriptNotFound(vendor) {
     throw new AitermError(`最終 assistant メッセージを特定できませんでした（harness=${agentHarness(vendor)}, vendor=${vendor}）。screen で確認してください。`, 2);
 }
@@ -2763,7 +2765,8 @@ export async function readAgentTranscriptResult(name, o = {}) {
         throw new AitermError(`operation ${operationId} はまだ完了していません。同じoperation_idで後から再取得してください。${agentWaitGuide(name)}`, 2);
     }
     const turnId = o.completion?.turn_id ?? done?.turn_id ?? null;
-    let text = "";
+    // 各harnessの読み取りは、回答の場所を見つけたら文字列（空でもよい）、見つからなければnullを返す。
+    let text;
     if (meta.kind === "claude") {
         if (!done)
             transcriptUnavailable();
@@ -2780,12 +2783,16 @@ export async function readAgentTranscriptResult(name, o = {}) {
             transcriptUnavailable();
         text = grokTranscriptText(meta, readTranscriptLines, transcriptUnavailable, o.completion?.turn_id);
     }
-    if (!text.trim())
+    // 回答の場所が見つからない時だけ誤りにする。場所があって中身が空白だけのturnは「回答が空」として返す。
+    if (text === null)
         transcriptNotFound(meta.kind);
-    if (o.lines != null)
+    const answerEmpty = !text.trim();
+    if (answerEmpty)
+        text = "";
+    else if (o.lines != null)
         text = text.split("\n").slice(-o.lines).join("\n");
     const rawChars = text.length;
-    const [body, outputMeta] = o.raw ? [text, ""] : reduceOutput(text, name, true);
+    const [body, outputMeta] = answerEmpty || o.raw ? [text, ""] : reduceOutput(text, name, true);
     const transcriptMeta = [
         "agent_transcript",
         `vendor=${meta.kind}`,
@@ -2793,14 +2800,16 @@ export async function readAgentTranscriptResult(name, o = {}) {
         `harness=${agentHarness(meta.kind)}`,
         done?.operation_id ? `operation_id=${done.operation_id}` : null,
         `raw_chars=${rawChars}`,
+        answerEmpty ? "answer_empty=true" : null,
     ].filter(Boolean).join(" ");
     return {
         text: body,
-        display: `${body}\n${outputMeta} [${transcriptMeta}]`,
+        display: `${answerEmpty ? AGENT_ANSWER_EMPTY_NOTICE : body}\n${outputMeta} [${transcriptMeta}]`,
         vendor: meta.kind,
         turn_id: turnId,
         harness: agentHarness(meta.kind),
         raw_chars: rawChars,
+        answer_empty: answerEmpty,
     };
 }
 /** 人間向け互換表示を維持する。機械利用は readAgentTranscriptResult の text を使う。 */

package/dist/harnesses/codex.js

@@ -618,6 +618,9 @@ export function codexMoreReasoningChoice(screen) {
     return null;
 }
 // 回収対象turnの最終assistantメッセージをroot rollout transcriptから抽出する。
+// 回答の場所が記録にあれば、中身が空でも文字列を返す。場所が見つからない時（記録の形が変わった時を含む）はnull。
+// Codexは回答を空で終えたturnも、textが空のfinal_answerをturn ID付きで残す（0.160.1の実記録 2026-10-06。
+// task_completeのlast_agent_messageはnull）。
 export function codexTranscriptText(meta, turnId, readTranscriptLines, transcriptUnavailable, exactCompletion = false) {
     if (!meta.codex_home || !meta.vendor_session_id)
         transcriptUnavailable();
@@ -642,7 +645,7 @@ export function codexTranscriptText(meta, turnId, readTranscriptLines, transcrip
                 if (typeof payload.last_agent_message === "string")
                     return payload.last_agent_message;
                 const text = matching.text();
-                if (text)
+                if (text !== null)
                     return text;
                 transcriptUnavailable();
             }
@@ -650,7 +653,7 @@ export function codexTranscriptText(meta, turnId, readTranscriptLines, transcrip
         transcriptUnavailable();
     }
     const matching = codexTurnAnswer();
-    let finalAnswer = "";
+    let finalAnswer = null;
     for (const line of lines) {
         if (!line.trim())
             continue;
@@ -670,7 +673,9 @@ export function codexTranscriptText(meta, turnId, readTranscriptLines, transcrip
             finalAnswer = payload.message;
         }
     }
-    return matching.text() || finalAnswer;
+    // turnの本文が記録にあれば、空でもそれが回答。agent_message（turn IDの無い旧形式）は別turnの物かもしれないので、
+    // turnの本文が見つからず、かつ空でない時だけ使う。
+    return matching.text() ?? (finalAnswer?.trim() ? finalAnswer : null);
 }
 // turnのassistant本文を集める。Codexは作業途中の報告をphase=commentary、回答をphase=final_answerで残すので、
 // final_answerがあるturnは途中の報告を回答に含めない。phaseの無い旧形式はturnの本文を全部つなぐ。
@@ -691,7 +696,10 @@ function codexTurnAnswer() {
                     finals.push(item.text);
             }
         },
+        // turnのassistant本文が1つも無ければnull（回答の場所が見つからない）。
         text() {
+            if (all.length === 0)
+                return null;
             return (finals.length > 0 ? finals : all).join("\n");
         },
     };

package/dist/harnesses/cursor.js

@@ -245,6 +245,10 @@ export function cursorTranscriptText(meta, readTranscriptLines, transcriptUnavai
         transcriptUnavailable();
     // tool_useで区切った本文の塊を持つ。道具を呼ぶ前の文は作業途中の報告なので、回答は最後の塊だけにする。
     let current = [[]];
+    // 回答の場所が分かるturnか。assistant行があり、そのpartがtextとtool_useだけの時に限る（実記録にあるのはこの2種類）。
+    // 知らないpartがあるturnは、本文がそこへ移ったのかもしれないので「回答が空」とは言わない。
+    let assistantRows = 0;
+    let unknownParts = false;
     let completed = null;
     for (const line of readTranscriptLines(transcript)) {
         if (!line.trim())
@@ -256,22 +260,34 @@ export function cursorTranscriptText(meta, readTranscriptLines, transcriptUnavai
         catch {
             continue;
         }
-        if (record?.role === "user")
+        if (record?.role === "user") {
             current = [[]];
+            assistantRows = 0;
+            unknownParts = false;
+        }
         if (record?.role === "assistant" && Array.isArray(record?.message?.content)) {
+            assistantRows += 1;
             for (const part of record.message.content) {
                 if (part?.type === "text" && typeof part?.text === "string")
                     current.at(-1).push(part.text);
-                else if (part?.type === "tool_use" && current.at(-1).length > 0)
-                    current.push([]);
+                else if (part?.type === "tool_use") {
+                    if (current.at(-1).length > 0)
+                        current.push([]);
+                }
+                else
+                    unknownParts = true;
             }
         }
-        if (record?.type === "turn_ended")
-            completed = current.map((chunk) => [...chunk]);
+        if (record?.type === "turn_ended") {
+            completed = { chunks: current.map((chunk) => [...chunk]), located: assistantRows > 0 && !unknownParts };
+        }
     }
     if (completed === null)
         transcriptUnavailable();
-    return (completed.filter((chunk) => chunk.length > 0).at(-1) ?? []).join("\n");
+    const text = (completed.chunks.filter((chunk) => chunk.length > 0).at(-1) ?? []).join("\n");
+    if (text.trim())
+        return text;
+    return completed.located ? "" : null;
 }
 export function createCursorAgentMetadata(name, cwd, initialPrompt, writeScope, lineage) {
     const launchId = randomBytes(16).toString("hex");

package/dist/harnesses/grok.js

@@ -500,9 +500,12 @@ export function grokTranscriptText(meta, readTranscriptLines, transcriptUnavaila
     const replies = records
         .slice(lastUser + 1, end)
         .filter((record) => record?.type === "assistant" && typeof record?.content === "string")
-        .map((record) => record.content.trim())
-        .filter(Boolean);
-    return replies.at(-1) ?? "";
+        .map((record) => record.content.trim());
+    // contentが文字列のassistant行が1つも無ければnull（回答の場所が見つからない）。
+    // 道具を呼ぶだけの行はcontentが空文字列で残るので、そういう行だけのturnは「回答が空」になる。
+    if (replies.length === 0)
+        return null;
+    return replies.filter(Boolean).at(-1) ?? "";
 }
 export function createGrokAgentMetadata(kind, name, cwd, initialPrompt, authPath, writeScope, lineageContext) {
     const launchId = randomBytes(16).toString("hex");

package/dist/index.js

@@ -413,6 +413,7 @@ registerRemoteAwareTool("pty_read", {
     description: "セッションの出力をトークン削減して読む（既定は前回読取位置からの増分）。" +
         "削減: 制御文字除去 / 反復圧縮 / head+tail 折りたたみ＋復元ヒント＋メタ併記。" +
         "agent_transcript:true は agent session の直近完了ターンの最終 assistant メッセージを公開されたharness記録から平文で返す。" +
+        "回答が空で終わったターンは誤りにせず、空のtextとanswer_empty:trueを返す。" +
         "長い回答が screen tail で切れた時の回収用。",
     inputSchema: {
         session_id: z.string(),
@@ -454,6 +455,12 @@ registerRemoteAwareTool("pty_read", {
         turn_id: z.string().nullable(),
         harness: z.enum(["claude-code", "codex-cli", "grok-cli", "cursor-cli"]).nullable(),
         raw_chars: z.number().int().nonnegative().nullable(),
+        // remote付きは現地の結果をそのまま返す。この項目が無い旧版（0.53.2以前）の結果も通すのでoptional。
+        answer_empty: z
+            .boolean()
+            .nullable()
+            .optional()
+            .describe("agent_transcriptで、完了したturnの回答が空だった時だけtrue（textは空文字列）。回答を読めなかった時は誤りを返す。terminalではnull"),
     },
 }, async ({ session_id, wait, until, until_regex, timeout, screen, full, lines, line_range, raw, rtk, agent_transcript, operation_id }) => {
     try {
@@ -478,6 +485,7 @@ registerRemoteAwareTool("pty_read", {
                     turn_id: result.turn_id,
                     harness: result.harness,
                     raw_chars: result.raw_chars,
+                    answer_empty: result.answer_empty,
                 },
             };
         }
@@ -521,6 +529,7 @@ registerRemoteAwareTool("pty_read", {
                 turn_id: null,
                 harness: null,
                 raw_chars: null,
+                answer_empty: null,
             },
         };
     }

package/dist/parent-delivery.js

@@ -300,7 +300,8 @@ export class ParentDeliveryManager {
                     ...(record.boundary.remote ? { remote: record.boundary.remote } : {}) });
                 if (record.state !== "waiting")
                     return;
-                record.text = answer.text;
+                // 回答を空で終えたturnも完了として届ける。親が完了を知る手段はこの配送だけなので、本文の代わりに知らせを入れる。
+                record.text = answer.text.trim() ? answer.text : "子のターンは完了しましたが、回答の本文は空でした。";
             }
             else {
                 record.text = completion.error ?? completion.rate_limit ?? "子のセッションが閉じられたため、回答はありません。";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.53.2",
+  "version": "0.54.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": [