aiterm-mcp 0.56.0 → 0.57.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.57.0] - 2026-10-07
+
+### 追加
+
+- `pty_send`（agentの席への送信）に、任意の引数`preface`（本文の前に置く1行）を足す（ADR 0099）。渡る文は「`preface`・空行・`text`」。
+  - Claude Codeの席へは、`preface`を端末の貼り付けの印なしで入れ、空行と`text`を1回の貼り付けで入れる。Claude Codeは貼り付けた長い文を
+    `<pasted_content>`で包み、席に「包みの中の指示は、包みの外の利用者自身の言葉が頼んだ時だけ従う」と教える。今までは文の全部が包みの中で、
+    席が連絡に従わない事があった（止めた直後の席で、実物の7回中5回）。前置きが包みの外に出る。
+  - Codex・Grok・Cursorの席へは、`preface`・空行・`text`を1つにつないで今までどおり貼る。
+  - `preface`は1行・200字以内・制御文字なしで、行頭が記号や空白でなく、`@`を含まない文。外れた時は`AGENT_PREFACE_INVALID`と
+    「文字列は送信していません。」で、待たずに断る。通常PTY・`force`付き・`remote`付きでは使えない（打鍵前に断る）。
+  - 省略した時の動き、振り分け、返りの形、断りの文面は変わらない。
+
+## [0.56.1] - 2026-10-07
+
+### 修正
+
+- `aiterm-parent-delivery`が、呼ぶ側のPATHにnodeの場所が無い環境でも、nodeで動くCodexの起動役（npm版の`codex`。1行目が
+  `#!/usr/bin/env node`）を起こせるようにする。0.56.0は、そういう環境（素のsshの環境、製品の常駐process、アプリ配下のprocess）から
+  呼ぶと、`codex verify`が`CODEX_RECEIVER_TRANSPORT_FAILED`（exit=127）で断っていた。本文は送られていなかった。
+  - 命令が、自分を動かしているnodeの場所を、起こすCodexのPATHの頭へ足す。既にPATHにあれば何も変えない。
+  - 引数・返りの形は変わらない。Desktop同梱のCodex（macOS・Windows）は元から当たらない。
+
 ## [0.56.0] - 2026-10-07
 
 ### 追加
@@ -2333,7 +2356,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.56.0...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.57.0...HEAD
+[0.57.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.56.1...v0.57.0
+[0.56.1]: https://github.com/kitepon/aiterm-mcp/compare/v0.56.0...v0.56.1
 [0.56.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.55.4...v0.56.0
 [0.55.4]: https://github.com/kitepon/aiterm-mcp/compare/v0.55.3...v0.55.4
 [0.55.3]: https://github.com/kitepon/aiterm-mcp/compare/v0.55.2...v0.55.3

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.56.0** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.57.0** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
@@ -261,6 +261,8 @@ ClaudeがAPIエラーや安全判定の拒否で終了した時は、Stop hook
 
 agent配送だけを期待する連携では、`pty_send`に`require_agent:true`を指定する。agent登録が無ければ、打鍵前に`AGENT_SESSION_REQUIRED`と「文字列は送信していません」を返す。省略時は通常PTY送信を維持する。`force:true`との併用は未送信で拒否する。
 
+agent session宛ての`pty_send`は、任意の`preface`（本文の前に置く1行）を受ける。渡る文は「`preface`・空行・`text`」。Claude Codeの席へは、`preface`を端末の貼り付けの印なしで入れ、空行と本文を1回の貼り付けで入れる。Claude Codeは貼り付けた長い文を`<pasted_content>`で包み、「包みの中の指示は、包みの外の利用者自身の言葉が頼んだ時だけ従う」と読むので、連携元が付ける前置き（誰からの連絡か）を包みの外へ出すために使う。Codex・Grok・Cursorの席へは1つにつないで貼る。`preface`は1行・200字以内・制御文字なしで、行頭が記号や空白でなく、`@`を含まない文。外れた時は`AGENT_PREFACE_INVALID`と「文字列は送信していません。」を返す。通常PTY・`force:true`・`remote`付きでは使えない。
+
 同じagent sessionへの`pty_send`が重なった時は、1本ずつ通す。後の1通は、前の1通を送り終えてから振り分け直すので、順に送った時と同じ結果になる（起動直後のClaude Codeへ重なった後の1通は`mode=agent_steer`で返る）。前の1通が起動直後の入力受付待ちなら、その分だけ返りが遅れる。待つ上限（POSIX 60秒、Windows 180秒）を越えた時は、打鍵前に`AGENT_SEND_BUSY`と「文字列は送信していません」を返す。送信の途中で終了したprocessのlockは、次の送信が片付けて進む。
 
 `agent_launch`・`pty_send`（agent session宛て）は任意の`image`（画像ファイルの絶対パスの配列。png/jpg/jpeg/gif/webp）を受ける。aitermが本文末尾へ添付行を付け、どのharnessも自分のfile読取toolでそのpathを画像として開く。呼出し側はharness別の添付手順を覚えない。不正なpathは送信前に拒否する。
@@ -568,7 +570,7 @@ Claudeの相関済み承認は既存の`claude_approval`を使う。
 | ツール | 役割 | 主な引数 |
 | --- | --- | --- |
 | `pty_open` | 端末を1個開き`session_id`を返す | `name?`, `shell?`, `env_vars?` |
-| `pty_send` | テキストを送る。agent sessionでは子のturnが実行中なら現在のturnへ差し込み（`agent_steer`）、それ以外は非ブロックdispatchとして`event_cursor`を返す（`agent_dispatch`）。差し込みでGrokが待ち行列へ入れない時とCursorの入力欄に残った時は失敗する | `session_id`, `text`, `enter=true`, `mark`, `force`, `require_agent=false`, `rtk`, `raw` |
+| `pty_send` | テキストを送る。agent sessionでは子のturnが実行中なら現在のturnへ差し込み（`agent_steer`）、それ以外は非ブロックdispatchとして`event_cursor`を返す（`agent_dispatch`）。差し込みでGrokが待ち行列へ入れない時とCursorの入力欄に残った時は失敗する | `session_id`, `text`, `enter=true`, `mark`, `force`, `require_agent=false`, `preface`, `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` |

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.56.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).
+**Status:** actively maintained · current public release **v0.57.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
 
@@ -282,6 +282,8 @@ The same primitive hosts another agent's TUI. `agent_launch` starts a selected e
 
 Set `require_agent:true` on `pty_send` when the integration requires agent delivery. If the agent registration is missing, Aiterm refuses before sending any text and returns `AGENT_SESSION_REQUIRED` with an explicit unsent message. The default preserves ordinary PTY sends; combining it with `force:true` is rejected before sending.
 
+`pty_send` to an agent session accepts an optional `preface`: one line placed before the text, so the message reads "`preface`, blank line, `text`". For a Claude Code session Aiterm enters the `preface` without the terminal's paste markers and pastes the blank line and the text in one paste. Claude Code wraps long pasted text in `<pasted_content>` and follows instructions inside it only where the user's own words outside the tags ask it to, so this keeps an integration's header (who the message is from) outside the wrapper. For Codex, Grok and Cursor sessions the three parts are joined and pasted as before. The `preface` must be a single line of at most 200 characters with no control characters, must not start with a symbol or whitespace, and must not contain `@`; otherwise Aiterm returns `AGENT_PREFACE_INVALID` and "文字列は送信していません。" before sending anything. It cannot be used with ordinary PTY sends, `force:true`, or `remote`.
+
 Overlapping `pty_send` calls to the same agent session are handled one at a time. A later call picks its route only after the earlier one has been sent, so the result matches calls made in sequence (a call that overlaps the first send to a freshly started Claude Code session returns `mode=agent_steer`). It returns later by however long the earlier call waits for the session to accept input. If its turn does not come within the limit (60 seconds on POSIX, 180 seconds on Windows), Aiterm refuses before sending any text and returns `AGENT_SEND_BUSY` with an explicit unsent message. A lock left by a process that exited mid-send is cleared by the next send.
 
 `agent_launch` and `pty_send` (to an agent session) 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.
@@ -606,7 +608,7 @@ continue to use `claude_approval`.
 | Tool | Role | Key args |
 | --- | --- | --- |
 | `pty_open` | Open one terminal and return a `session_id` | `name?`, `shell?`, `env_vars?` |
-| `pty_send` | Send text. On an agent session Aiterm picks the route when it sends: if the child's turn is running, it steers the text into that turn (`agent_steer`); otherwise it is a non-blocking **dispatch** returning an `event_cursor` (`agent_dispatch`). Steering fails when Grok does not queue the text or Cursor leaves it in the composer | `session_id`, `text`, `enter=true`, `mark`, `force`, `require_agent=false`, `rtk`, `raw` |
+| `pty_send` | Send text. On an agent session Aiterm picks the route when it sends: if the child's turn is running, it steers the text into that turn (`agent_steer`); otherwise it is a non-blocking **dispatch** returning an `event_cursor` (`agent_dispatch`). Steering fails when Grok does not queue the text or Cursor leaves it in the composer | `session_id`, `text`, `enter=true`, `mark`, `force`, `require_agent=false`, `preface`, `rtk`, `raw` |
 | `pty_read` | Read output, token-reduced (incremental by default) | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk`, `agent_transcript`, `operation_id` |
 | `pty_key` | Send a control key | `session_id`, `key` (`C-c`/`Enter`/`Up`…) |
 | `pty_close` | Close idempotently; return `closed` / `already_closed` | `session_id` |

package/dist/core.js

@@ -762,6 +762,38 @@ export function openSession(name, shell = "bash", envVars = []) {
     }
     return [nm, attachHint(nm)];
 }
+export const AGENT_PREFACE_MAX_CHARS = 200;
+// 行頭のASCII記号と空白は、入力欄が命令として読む（Claude Codeの`/`・`!`・`#`・`?`など）。`@`は文中でも候補の枠を開く。
+const AGENT_PREFACE_LEADING_SYMBOL_RE = /^[\s!-\/:-@\[-`{-~]/u;
+const AGENT_PREFACE_CONTROL_RE = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/u;
+/**
+ * `pty_send`の`preface`（本文の前に置く1行）を、打鍵の前に確かめる。印なしで入れる文は入力欄がそのまま読むので、
+ * 入力欄が命令として読む形を通さない。外れた時は何も送らずに断る。
+ */
+export function assertAgentPreface(preface) {
+    const reason = typeof preface !== "string" || preface.length === 0 ? "空です"
+        : AGENT_PREFACE_CONTROL_RE.test(preface) ? "改行か制御文字を含んでいます"
+            : [...preface].length > AGENT_PREFACE_MAX_CHARS ? `${AGENT_PREFACE_MAX_CHARS}字を越えています`
+                : AGENT_PREFACE_LEADING_SYMBOL_RE.test(preface) ? "行頭が記号か空白です"
+                    : /\s$/u.test(preface) ? "行末が空白です"
+                        : preface.includes("@") ? "@ を含んでいます"
+                            : null;
+    if (reason) {
+        throw new AitermError(`AGENT_PREFACE_INVALID: prefaceが${reason}。1行・${AGENT_PREFACE_MAX_CHARS}字以内・制御文字なしで、` +
+            "行頭が記号や空白でなく、@ を含まない文にしてください。文字列は送信していません。", 2);
+    }
+    return preface;
+}
+/**
+ * 前置きつきの送信文を、harnessごとの形へ分ける。Claude Codeは前置きを印なしで入れ、空行と本文を貼る。
+ * Codex・Grok・Cursorは貼り付けを包まないので、前置き・空行・本文を1つにつないで貼る（渡る文は前置きなしの時と同じ並び）。
+ */
+function splitAgentPreface(kind, preface, text) {
+    if (preface == null)
+        return { body: text };
+    assertAgentPreface(preface);
+    return kind === "claude" ? { typedPreface: preface, body: `\n\n${text}` } : { body: `${preface}\n\n${text}` };
+}
 function prepareSendText(text, o) {
     if (!o.raw)
         text = text.replace(PASTE_MARKERS_RE, "").replace(ANSI_RE, "").replace(CTRL_RE, "");
@@ -823,17 +855,18 @@ export function send(name, text, o = {}) {
         }
         // POSIX tmuxはUTF-8安全な256byte pasteへ分割する。Windows psmuxは認証済み
         // server commandでpayload全体を単一SendBytesへ変換し、別processとの交差を構造的に防ぐ。
-        if (isWin) {
-            const sent = sendPsmuxPayload(true, name, text, !!o.bracketedPaste);
-            if (sent.code !== 0) {
-                throw new AitermError(`psmuxのPTY送信に失敗しました: ${sent.stderr.trim() || `code=${sent.code}`}`, 2);
+        const writePty = (payload, bracketedPaste, what) => {
+            if (isWin) {
+                const sent = sendPsmuxPayload(true, name, payload, bracketedPaste);
+                if (sent.code !== 0) {
+                    throw new AitermError(`psmuxのPTY送信に失敗しました${what}: ${sent.stderr.trim() || `code=${sent.code}`}`, 2);
+                }
+                return;
             }
-        }
-        else {
             // tmuxの`paste-buffer -p`はchunkごとに包むため使わない。Claude Codeは貼り付け1回ごとに
             // 画像pathを探すので、chunk境界でpathが切れて画像を落とし、行もずれた（2026-10-01、
             // 画像4枚付きの約500byte）。全体を1回だけ包み、中身はchunkのまま流す。
-            const chunks = splitPtyText(o.bracketedPaste ? `\x1b[200~${text}\x1b[201~` : text);
+            const chunks = splitPtyText(bracketedPaste ? `\x1b[200~${payload}\x1b[201~` : payload);
             const pasteSupportsNoSanitize = pasteBufferSupportsNoSanitizeFlag();
             const bufferBase = `aiterm-${process.pid}-${randomBytes(8).toString("hex")}`;
             for (let i = 0; i < chunks.length; i += 1) {
@@ -844,7 +877,7 @@ export function send(name, text, o = {}) {
                 const loaded = loadPtyBufferChunk(true, bufferName, chunks[i]);
                 if (loaded.code !== 0) {
                     tmuxCleanup("delete-buffer", "-b", bufferName);
-                    throw new AitermError(`tmux bufferへの送信準備に失敗しました` +
+                    throw new AitermError(`tmux bufferへの送信準備に失敗しました${what}` +
                         `（chunk ${i + 1}/${chunks.length}）: ${loaded.stderr.trim() || `code=${loaded.code}`}.${partial}`, 2);
                 }
                 const pasteArgs = pasteBufferBaseArgs();
@@ -854,14 +887,30 @@ export function send(name, text, o = {}) {
                 const pasted = tmux(...pasteArgs);
                 if (pasted.code !== 0) {
                     tmuxCleanup("delete-buffer", "-b", bufferName);
-                    throw new AitermError(`tmux bufferのPTY送信に失敗しました` +
+                    throw new AitermError(`tmux bufferのPTY送信に失敗しました${what}` +
                         `（chunk ${i + 1}/${chunks.length}）: ${pasted.stderr.trim() || `code=${pasted.code}`}.${partial}`, 2);
                 }
                 if (i + 1 < chunks.length) {
                     Atomics.wait(PTY_PASTE_PAUSE_BUFFER, 0, 0, PTY_PASTE_CHUNK_PAUSE_MS);
                 }
             }
+        };
+        if (o.typedPreface !== undefined) {
+            // 前置きは貼り付けの印なしで入れる。本文は続けて貼る。前置きだけが入って本文が失敗した時は、入力欄に前置きが残る。
+            writePty(o.typedPreface, false, "（前置き）");
+            Atomics.wait(PTY_PASTE_PAUSE_BUFFER, 0, 0, PTY_PASTE_CHUNK_PAUSE_MS);
+            try {
+                writePty(text, !!o.bracketedPaste, "");
+            }
+            catch (error) {
+                if (error instanceof AitermError) {
+                    throw new AitermError(`${error.message} 前置きはPTYに入力済みでEnterは未送信です。再送前に入力を確認・消去してください。`, error.code);
+                }
+                throw error;
+            }
         }
+        else
+            writePty(text, !!o.bracketedPaste, "");
         if (enter) {
             const entered = tmux("send-keys", "-t", name, "Enter");
             if (entered.code !== 0) {
@@ -4259,9 +4308,10 @@ async function dispatchAgentTurnInLock(name, text, o) {
     const startOffset = agentCompletionCursor(meta);
     // promptなしで起動したCursorは、最初のdispatch時点ではtranscriptとの相関markerをまだ持たない。
     // その1回だけlaunch contextを加え、以後はbind済みconversationへ通常textだけを送る。
+    const prefaced = splitAgentPreface(meta.kind, o.preface, text);
     const dispatchText = meta.kind === "cursor" && !meta.vendor_session_id
-        ? `${subagentInstruction(meta)}\n\n${text}`
-        : text;
+        ? `${subagentInstruction(meta)}\n\n${prefaced.body}`
+        : prefaced.body;
     prepareSendText(dispatchText, { raw: o.raw });
     await o.before_send?.({ session_id: name, launch_id: meta.launch_id, vendor: meta.kind,
         harness: agentHarness(meta.kind), event_cursor: startOffset, operation_id: operationId });
@@ -4284,6 +4334,7 @@ async function dispatchAgentTurnInLock(name, text, o) {
         rtk: false,
         preserveAgentOperation: meta.kind === "claude",
         bracketedPaste: true,
+        typedPreface: prefaced.typedPreface,
     });
     // Cursorの冷間起動ではbracketed pasteの反映が250msを超えることがある。本文がcomposerへ
     // 現れた実測をsubmit条件にし、未反映のままEnterだけを失う競合を作らない。
@@ -4354,6 +4405,9 @@ export function __testSteerQueued(kind, screen) {
 export async function sendAgentMessage(name, text, o = {}) {
     assertSessionName(name);
     loadAgentMetadata(name);
+    // 前置きは、順番待ちにも入力受付の待ちにも入る前に確かめる（外れた時に待たせない）。
+    if (o.preface != null)
+        assertAgentPreface(o.preface);
     return withAgentSendLock(name, () => sendAgentMessageInLock(name, text, o));
 }
 async function sendAgentMessageInLock(name, text, o) {
@@ -4374,9 +4428,9 @@ async function sendAgentMessageInLock(name, text, o) {
     if (running && meta.kind === "cursor" && latestCursorCompletion(meta, readTranscriptLines) !== null)
         running = false;
     if (running) {
-        return steerRunningTurn(name, meta, text, { raw: o.raw, pane_input_recovery: paneInputRecovery });
+        return steerRunningTurn(name, meta, text, { raw: o.raw, pane_input_recovery: paneInputRecovery, preface: o.preface });
     }
-    return dispatchAgentTurnInLock(name, text, { raw: o.raw, before_send: o.before_send, pane_input_recovery: paneInputRecovery });
+    return dispatchAgentTurnInLock(name, text, { raw: o.raw, before_send: o.before_send, pane_input_recovery: paneInputRecovery, preface: o.preface });
 }
 /**
  * 実行中turnへ追加の指示を渡す。各harnessの標準操作だけを使い、完了境界は1つに保つ。
@@ -4395,6 +4449,8 @@ async function steerRunningTurn(name, meta, text, o) {
         harness: agentHarness(meta.kind),
         pane_input_recovery: o.pane_input_recovery,
     };
+    const prefaced = splitAgentPreface(meta.kind, o.preface, text);
+    text = prefaced.body;
     prepareSendText(text, { raw: o.raw });
     // Claudeのoperation相関は変えない。差し込みは実行中turnの一部であり、新しいturnを予約しない。
     const preserveAgentOperation = meta.kind === "claude";
@@ -4406,6 +4462,7 @@ async function steerRunningTurn(name, meta, text, o) {
         rtk: false,
         preserveAgentOperation,
         bracketedPaste: true,
+        typedPreface: prefaced.typedPreface,
     });
     if (meta.kind === "cursor") {
         const visible = await waitCursorPromptVisible(name, text);

package/dist/index.js

@@ -209,6 +209,9 @@ function remoteToolHandler(name) {
 async function sendRemote(target, args, extra) {
     if (args.image && args.image.length > 0)
         throw new core.AitermError("REMOTE_IMAGE_UNSUPPORTED: 別端末への画像添付には未対応です", 2);
+    // 現地が古い版だと、知らない引数として前置きだけが黙って落ちる。届く形を確かめられるまで通さない。
+    if (args.preface !== undefined)
+        throw new core.AitermError("REMOTE_PREFACE_UNSUPPORTED: 別端末へのprefaceには未対応です。文字列は送信していません。", 2);
     const key = deliveryKey(args.session_id, target);
     const delivery = args.force ? null : await deliveryForRequest(extra, true);
     // 終わった依頼の回答は送る前に保存する。実行中の依頼は残る。現地が差し込みを選べばその依頼が回答を受け取る。
@@ -289,6 +292,8 @@ registerRemoteAwareTool("pty_send", {
         NON_BLOCKING_RULE +
         "自動配送以外の結果回収は pty_read(agent_transcript:true)、Claude の durable turn は claude_turn を使う。" +
         "require_agent:true はagent登録が無いsessionへ打鍵せず、AGENT_SESSION_REQUIREDで未送信を返す。" +
+        "preface はagent sessionへの送信で本文の前に置く1行。Claude Codeの席では貼り付けの印なしで入れ、本文だけを貼る" +
+        "（前置きが貼り付けの包みの外へ出る）。他のharnessでは前置き・空行・本文を1つで貼る。" +
         "force:true は非Claude agent sessionへの手動介入用の素送信。aiterm相関付きClaudeの承認UIはclaude_approvalを使う。",
     inputSchema: {
         session_id: z.string(),
@@ -308,6 +313,13 @@ registerRemoteAwareTool("pty_send", {
             .default(false)
             .describe("非Claude agent sessionでは自動dispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない"),
         require_agent: z.boolean().default(false).describe("agent登録が無いsessionは打鍵前に拒否する。force:trueとは併用できない"),
+        preface: z
+            .string()
+            .optional()
+            .describe("agent session への送信（forceなし）で、本文の前に置く1行。送る文は「preface・空行・text」の並びになる。" +
+            "Claude Codeの席ではprefaceを貼り付けの印なしで入れ、textだけを貼る。Codex／Grok／Cursorの席では1つで貼る。" +
+            "1行・200字以内・制御文字なしで、行頭が記号や空白でなく、@ を含まない文。外れた時と通常PTY送信・force送信・remote付きでは、" +
+            "打鍵前に拒否する"),
         rtk: z.boolean().default(false).describe("既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）"),
         raw: z.boolean().default(false).describe("送信前サニタイズを無効化"),
         image: z
@@ -332,7 +344,7 @@ registerRemoteAwareTool("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, require_agent, rtk, raw, image }, extra) => {
+}, async ({ session_id, text, enter, mark, force, require_agent, rtk, raw, image, preface }, extra) => {
     let delivery = null;
     try {
         if (require_agent && force) {
@@ -342,6 +354,12 @@ registerRemoteAwareTool("pty_send", {
         if (require_agent && !agentSession) {
             throw new Error(`AGENT_SESSION_REQUIRED: session '${session_id}' のagent登録がありません。文字列は送信していません。`);
         }
+        if (preface !== undefined) {
+            if (!agentSession) {
+                throw new Error("preface は agent session への送信（forceなし）だけで使えます。文字列は送信していません。");
+            }
+            core.assertAgentPreface(preface);
+        }
         if (agentSession) {
             if (enter === false)
                 throw new Error("agent session への dispatch は enter:false と併用できません（手動介入は force:true）");
@@ -350,7 +368,7 @@ registerRemoteAwareTool("pty_send", {
             if (rtk)
                 throw new Error("agent session への dispatch は rtk:true と併用できません");
             delivery = await deliveryForRequest(extra);
-            const receipt = await core.sendAgentMessage(session_id, core.attachImages(text, image), { raw, before_send: delivery?.before_send });
+            const receipt = await core.sendAgentMessage(session_id, core.attachImages(text, image), { raw, before_send: delivery?.before_send, preface });
             if (receipt.schema === "aiterm.agent-steer.v1") {
                 return {
                     content: [

package/dist/parent-delivery-cli.js

@@ -119,6 +119,22 @@ async function deliveryState(target, delivery) {
         return { state, hook, turn_id: turn, queued: null, queue_error: typeof code === "string" ? code : "CODEX_QUEUE_UNREADABLE" };
     }
 }
+/**
+ * 起こすCodexが、この命令を動かしているnodeを見つけられるPATHを返す。
+ * npm版のCodexは`#!/usr/bin/env node`の起動役で、呼ぶ側のPATHにnodeの場所が無いと起きない（exit 127）。製品の常駐processや
+ * アプリ配下のprocessは、PATHが細い事がある（2026-10-07、素のsshの環境からの呼び出しで起きた）。
+ * nodeの場所がPATHに無い時だけ頭へ足す。既にあれば、並びも中身も変えない。
+ */
+export function pathWithNode(env, node = process.execPath, platform = process.platform) {
+    const windows = platform === "win32";
+    // Windowsの環境変数名は大文字小文字を区別しない（`Path`で入っている事が多い）。
+    const key = Object.keys(env).find(name => windows ? name.toLowerCase() === "path" : name === "PATH") ?? "PATH";
+    const delimiter = windows ? ";" : ":";
+    const directory = (windows ? path.win32 : path.posix).dirname(node);
+    const current = env[key] ?? "";
+    const listed = current.split(delimiter).some(part => windows ? part.toLowerCase() === directory.toLowerCase() : part === directory);
+    return { key, value: listed ? current : current ? `${directory}${delimiter}${current}` : directory };
+}
 /** この命令の場所と版。製品側の入口（aiterm-steer-delivery）が、呼べる相手かどうかを確かめるのに使う。 */
 export function providerDescription() {
     return { version: pkg.version, node: process.execPath, cli: fileURLToPath(import.meta.url) };
@@ -170,6 +186,8 @@ function isDirectExecution() {
 }
 if (isDirectExecution()) {
     try {
+        const found = pathWithNode(process.env);
+        process.env[found.key] = found.value;
         process.stdout.write(JSON.stringify({ ok: true, schema: PARENT_DELIVERY_SCHEMA, ...(await runParentDelivery(process.argv.slice(2))) }) + "\n");
     }
     catch (error) {

package/docs/DESIGN.md

@@ -57,6 +57,11 @@ agent配送だけを期待する連携元は`pty_send(require_agent:true)`を指
 `AGENT_SESSION_REQUIRED`と「文字列は送信していません」を返す。未送信を確定してから対象sessionを復旧できる。
 省略時の通常PTY送信は維持し、`force:true`との併用は打鍵前に拒否する。
 
+agentの席への`pty_send`は、任意の`preface`（本文の前に置く1行）を受ける（ADR 0099）。Claude Codeの席へは、`preface`を貼り付けの印なしで入れ、
+空行と本文を1回の貼り付けで入れる。貼り付けた長い文をClaude Codeが`<pasted_content>`で包んでも、前置きは包みの外に出る。
+ほかのharnessの席へは1つにつないで貼る。`preface`は入力欄がそのまま読むので、1行・200字以内・制御文字なし・行頭が記号や空白でない・
+`@`を含まない文だけを通し、外れた時は打鍵前に断る。
+
 `pty_observe`は存在、pane／harnessの生存、画面状態と理由、native process identityを分ける。
 PIDは開始識別子・argv digestと組にし、paneとharnessを同一視しない。特定できないidentityはnull。
 同じlaunchに属するnpm shimとnative本体は、中間の非候補processも含めた祖先関係から一つの起動として扱う。

package/package.json

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