codexteer 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.15.0 — 未公開
+
+監督の一時停止、指摘の重複抑制と検証結果の追跡を追加する機能リリースです。
+
+- `supervise <THREAD> [MESSAGE]`と`supervise prompt <THREAD> [MESSAGE]`で、必須の操作テンプレートを保ったまま監督方針を置き換えられます。
+- `supervise status / list / pause / resume / stop`で監督の登録・観測・配送状態を確認し、Codexタスクを止めずに介入を制御できます。
+- `findings`で指摘・解決条件・根拠・メッセージ・checkpointを関連付け、対応申告と検証を区別します。入力や検証結果が変われば再確認を求めます。
+- 同じ指摘の同じrevisionへの重複送信を拒否し、有益・不要・誤り・未評価を集計します。受付不明の送信は自動再送しません。
+- `--agent codex`でCodex CLIを監督役として起動できます。既定はClaudeです。
+- `--connection desktop`で、既存の共有制御ソケットを使った観測専用接続を選べます。送信は既存の`shared`方式を使います。
+- 保存済みCLI・canonical `CODEX_HOME`・監督ID・接続方式を同じ実行コマンドに固定し、古い監督や意図しない接続変更を拒否します。
+
+### 互換性・確認範囲
+
+- 製品バージョンを`0.14.1`から`0.15.0`へ更新します。runtime protocolと既存のcapability契約はv1を維持します。版の不一致だけを理由に接続を拒否しません。
+- 新しい監督制御は0.15.0で生成する監督ID付きコマンドが対象です。以前に保存したCLIとIDなしの手動送信は既存の挙動を維持します。
+- 直接接続はソケットが存在し、対象がロード済みの環境に限ります。Desktop・daemonの再起動や別接続への自動切り替えは行いません。
+- 直接接続のUnixプロトコルは同梱CLI 0.153.4と隔離した合成履歴で検証しています。実Desktopでの直接接続・画面表示・承認継続は未検証です。
+
+## 0.14.1 — 公開済み
+
+`codexteer`名で公開した版です。監督CLIの永続配置と`CODEX_HOME`固定、操作ごとの互換性判定、観測APIの診断を含みます。今回の監督制御・指摘管理・方針上書き・Codex CLI起動・観測専用の直接接続は0.15.0で追加します。

package/README.md

@@ -4,13 +4,13 @@
 
 ## 導入
 
-macOS、Node.js 20以降とnpm、`/Applications/ChatGPT.app`にインストールされたCodex Desktopが必要です。Claudeを監督役にする場合は、PATH上の`claude`でClaude Codeを起動できる状態にします。
+macOS、Node.js 20以降とnpm、`/Applications/ChatGPT.app`にインストールされたCodex Desktopが必要です。監督役に使うClaude CodeまたはCodex CLIを、PATH上の`claude`または`codex`で起動できる状態にします。
 
 ### npxで使う
 
 リポジトリのcloneやグローバルインストールなしで実行できます。npmパッケージ名とCLI名は`codexteer`です。
 
-監督開始時のCLI一式を保存する機能は`0.14.1`以降に対応します。この版のnpm公開前は、次の「ソースから導入する」を使ってください。
+このブランチは次期版`0.15.0`です。npm公開済みの`0.14.1`は利用できますが、監督方針の上書き、停止・再開、指摘管理、Codex CLI起動、Desktopへの観測専用接続は`0.15.0`で追加します。公開前にこれらを使う場合は、このブランチを「ソースから導入する」の手順で導入してください。変更点は[CHANGELOG](CHANGELOG.md)を参照してください。
 
 ```bash
 npx -y codexteer --version
@@ -28,10 +28,10 @@ npx -y codexteer doctor --json
 <details>
 <summary>特定のバージョンで実行する場合（任意）</summary>
 
-不具合の切り分けや、同じ版で監督を開始し直したい場合は、パッケージ名に`@バージョン`を付けられます。次は`0.14.1`を選ぶ例です。
+不具合の切り分けや、同じ版で監督を開始し直したい場合は、パッケージ名に`@バージョン`を付けられます。`0.15.0`の公開後にその版を選ぶ場合は、次のように指定します。
 
 ```bash
-npx -y codexteer@0.14.1 supervise <thread-id> --agent claude
+npx -y codexteer@0.15.0 supervise <thread-id>
 ```
 
 </details>
@@ -63,7 +63,7 @@ codexteer doctor --json
 
 ### codex-steerから移行する
 
-旧npmパッケージは`@vinhphatfsg/codex-steer`です。新しいパッケージの公開後は`npx -y codexteer`を使います。ソースから導入している場合は、新しいコードで`make install-local`を実行すると`codexteer`コマンドを導入できます。既存cloneのリモートURLは`https://github.com/vinhphatfsg/codexteer.git`へ更新してください。
+旧npmパッケージは`@vinhphatfsg/codex-steer`です。現在は`npx -y codexteer`を使います。ソースから導入している場合は、新しいコードで`make install-local`を実行すると`codexteer`コマンドを導入できます。既存cloneのリモートURLは`https://github.com/vinhphatfsg/codexteer.git`へ更新してください。
 
 保存済みの履歴や起動中Desktopとの接続を引き継ぐため、内部の保存先`CODEX_HOME/codex-steer`と通信・診断用JSONの`codex_steer_*`フィールドは維持しています。保存先を手動で移動する必要はありません。改名前から保存済みコピーを使っている監督も、そのコピーを引き続き使えます。
 
@@ -80,23 +80,42 @@ codexteer doctor --json
 以下の`<thread-id>`は対象のタスクIDに置き換えてください。`codex://threads/...`形式のタスクURLも使えます。
 コマンド一覧では`codexteer`と略記します。npxで手動実行する場合は、その部分を`npx -y codexteer`に置き換えてください。
 
-### Claude CodeにCodexの監視とステアリングを任せる
+### Claude Code・Codex CLIに監視とステアリングを任せる
 
 上の導入を済ませ、監視したいCodexタスクのIDまたはURLをコピーします。別のターミナルの対象プロジェクトのディレクトリから、導入方法に合う方を実行してください。
 
 ```bash
 # npxで起動する場合
-npx -y codexteer supervise <thread-id> --agent claude
+npx -y codexteer supervise <thread-id>
 
 # ソースから導入した場合
-codexteer supervise <thread-id> --agent claude
+codexteer supervise <thread-id>
 ```
 
 対象IDを埋め込んだ監督プロンプトでClaudeを[対話起動](https://code.claude.com/docs/en/cli-reference#cli-commands)します。端末の標準入出力をそのまま使い、起動後もClaudeへ追加の指示を入力できます。
 
+Codex CLIを監督役にする場合は、`--agent codex`を指定します。省略時はClaudeです。モデルなどのエージェント側の引数は`--`の後ろへ渡します。
+
+```bash
+codexteer supervise <thread-id> --agent codex
+npx -y codexteer supervise <thread-id> "テストと差分を確認してください。" --agent codex
+codexteer supervise <thread-id> --agent codex -- --model <model>
+codexteer supervise prompt <thread-id> --agent codex
+```
+
+監督方針を変える場合は、対象IDの後ろにメッセージを一つの引数として渡します。npx経由でも同じ書式です。
+
+```bash
+codexteer supervise <thread-id> "セキュリティの問題だけを私へ報告し、Codexへは送信しないでください。"
+```
+
+本文は、必須の共通テンプレートと監督方針を組み合わせて生成します。メッセージを省略すると、ユーザーの目的・制約の範囲で必要最小限の介入と結果確認を行い、簡潔に報告する標準方針を使います。指定すると、その標準方針全体を指定文に置き換えます。対象ID、CLIの実行コマンド、`help`・`read`・`watch`の操作、送信時の確認、停止手順はどちらにも含まれます。監視だけを指定した場合は、送信例を介入の許可として扱わないよう指示します。
+
+上書きは今回の生成・起動だけに適用し、次回の既定設定や保存したCLIには書き込みません。改行・空白・プレースホルダーに見える文字も指定文のまま本文に含めます。空文字・空白だけのメッセージはエラーです。呼び出し元のシェルで一つの引数として引用してください。`$`やバッククォートを文字として含めるときは、シェルが展開しない引用方法を使ってください。
+
 両方とも、起動したCLI本体と依存を`CODEX_HOME/codex-steer/runtimes/<version>-<sha256>`へ検証して保存し、そのコピーへの実行コマンドを監督プロンプトに埋め込みます。監督役に渡す切り替えオプションは不要です。npxのキャッシュが新版に更新された場合や、ソース導入先を`git pull`・削除した場合も、開始済みの監督は保存した内容を使い続けます。
 
-実行コマンドには、生成時に検証した`CODEX_HOME`の実体パスも埋め込みます。貼り付け先の環境変数が未設定・別設定でも、生成元の接続先と履歴を使います。同じPCで使い、監督中は保存したコピーを保持してください。新しいCLIや別のプロファイルに切り替えるときは、その環境から監督を起動し直すか、プロンプトを生成し直します。同じ版・同じ内容のコピーは検証して再利用し、内容が変われば別の保存先を作ります。既存のコピーは自動削除・上書きしません。
+実行コマンドには、生成時に検証した`CODEX_HOME`の実体パス、監督ごとの`--supervisor` ID、選択した`--connection`も埋め込みます。先頭の指定とオプションを全て保持してください。貼り付け先の環境変数が未設定・別設定でも、生成元の接続先と履歴を使います。同じPCで使い、監督中は保存したコピーを保持してください。新しいCLIや別のプロファイルに切り替えるときは、その環境から監督を起動し直すか、プロンプトを生成し直します。同じ版・同じ内容のコピーは検証して再利用し、内容が変われば別の保存先を作ります。既存のコピーは自動削除・上書きしません。
 
 Node本体はコピーせず、開始時の実体への絶対パスとNodeバージョンの検査を各コマンドに含めます。元のNodeは保持してください。バージョンが変われば`NODE_VERSION_MISMATCH`で操作を止めます。同じバージョンのNodeの改変や共有ライブラリまで固定するものではありません。保存先やNodeが使えなくなった場合は介入を止め、理由を報告するよう指示します。
 
@@ -105,7 +124,8 @@ Node本体はコピーせず、開始時の実体への絶対パスとNodeバー
 モデルなどClaude側の起動引数は、`--`の後ろへ渡します。
 
 ```bash
-codexteer supervise <thread-id> --agent claude -- --model <model> --effort <level>
+codexteer supervise <thread-id> -- --model <model> --effort <level>
+codexteer supervise <thread-id> "テスト失敗を優先して監督してください。" -- --model <model>
 ```
 
 同じPCで既にClaudeを起動している場合は、監督役（オーケストレーター）向けのプロンプトを出力し、そのセッションに貼り付けても使えます。
@@ -116,22 +136,96 @@ npx -y codexteer supervise prompt <thread-id>
 
 # ソースから導入した場合
 codexteer supervise prompt <thread-id>
+
+# 同じ監督方針で本文だけを生成する場合
+codexteer supervise prompt <thread-id> "セキュリティの問題だけを私へ報告し、Codexへは送信しないでください。"
 ```
 
-直接起動と本文だけの出力は、同じ保存・検証・生成処理を使います。`supervise prompt`もCLI一式を保存してから本文を出力します。監督手順は`codexteer help monitor`と共通で、生成プロンプト中の`doctor`・`read`・`watch`・`send`等の例には同じ実行コマンドを使います。監督役には、ヘルプ中の`codexteer`表記も指定された実行コマンドに置き換えるよう指示します。
+直接起動と本文だけの出力は、同じ保存・検証・生成処理を使います。生成するたびに監督IDは変わります。`--json`は`data.supervisor`に`session_id`・`owner`・`connection`も返します。`supervise prompt`もCLI一式を保存してから本文を出力します。共通テンプレートの操作手順は`codexteer help monitor`と同じで、ヘルプを読んでも上書き前の標準方針は追加されません。生成プロンプト中の`doctor`・`read`・`watch`・`send`等の例には同じ実行コマンドを使います。監督役には、ヘルプ中の`codexteer`表記も指定された実行コマンドに置き換えるよう指示します。
 
 1. 接続を診断し、対象タスクの最新の依頼・制約・進捗、有効な指示と対応待ちの履歴を確認する。
 2. 差分を読み切ったcursorから観測を続ける。[Monitorツール](https://code.claude.com/docs/en/tools-reference#monitor-tool)が使えれば`watch --stream`、使えなければ短い`watch`を繰り返す。接続状態の通知を読み、復帰待ちの間は介入を控える。
-3. 過剰設計・スコープ逸脱・より小さな修正の余地を判断し、必要なら最新の差分を読み切ってから`send --based-on`で介入する。同じ指摘が対応中なら結果を待つ。
+3. 選択した監督方針に従って観測する。方針で送信が許され、介入する場合は`help send`を確認し、最新の差分を読み切り、安定したkeyで`findings create`を行ってから`send --finding <id> --based-on <cursor>`を使う。同じ指摘が対応中なら結果を待つ。
 4. 送信したmessage_idを保持し、受付・対応報告・検証結果を区別して追う。`unknown`は`history check`で照合し、自動再送しない。
-5. 介入内容・確認結果・未確認事項を短く報告する。停止指示を受けたら、自分のMonitor/watchと追加送信を止める。
+5. 選択した監督方針に従って報告する。停止指示を受けたら、自分のMonitor/watchと追加送信を止める。
 
-このプロンプトは、ユーザーの最新の目的・制約の範囲内で監督と介入を委任します。その範囲の介入に毎回の確認は不要です。目的・制約が不明な場合や要件自体を変える必要がある場合は確認します。監督の委任だけで停止中タスクを再開したり、承認・質問へ代理回答したりはしません。単発送信では、ユーザーが指定した宛先・内容を使います。
+標準方針は、ユーザーの最新の目的・制約の範囲内で監督と介入を委任します。その範囲の介入に毎回の確認は不要です。上書き時の観測の観点・介入の判断基準・報告方法は指定文に従います。どちらの場合も、目的・制約が不明な場合や要件自体を変える必要がある場合は確認します。監督の委任だけで停止中タスクを再開したり、承認・質問へ代理回答したりはしません。単発送信では、ユーザーが指定した宛先・内容を使います。
 
-停止するときは、同じClaudeセッションで「監視とステアリングを停止して」と伝えてください。Codexの作業自体は継続します。監督はCLIとOSの既存の権限設定に従います。
+停止するときは、次の`supervise stop`を実行できます。監督エージェントのプロセス自体も終了する場合は、そのセッションへ「監視とステアリングを停止して」と伝えてください。Codexの作業自体は継続します。監督はCLIとOSの既存の権限設定に従います。
 
 IDのコピーを省く場合は、Claudeに`codexteer threads list --desktop-only --json`で候補を表示してもらい、対象を選ぶこともできます。同じプロジェクトに複数のタスクがある場合、Claudeの起動場所だけでは監視対象を特定できません。
 
+### 監督状態の確認・一時停止・停止
+
+ユーザーの端末から、生成元と同じ`CODEX_HOME`で実行します。
+
+```bash
+codexteer supervise status <thread-id> --json
+codexteer supervise list --json
+codexteer supervise pause <thread-id>
+codexteer supervise resume <thread-id>
+codexteer supervise stop <thread-id>
+```
+
+| 操作・状態 | 動作 |
+|---|---|
+| `active` | 登録済み。CLIで観測した時刻・接続状態を別に確認する |
+| `pause` / `paused` | 監督ID付きの送信を止め、観測は続ける |
+| `resume` | 同じ監督の介入を再開する |
+| `stop` / `stopped` | その監督の以後の観測・送信を拒否する。Codexタスクは止めない |
+
+`status`は所有者、最後のCLI観測と経過時間、接続状態、最後の配送、未解決の指摘を返します。`active`や観測時刻だけでAIの読了・継続監視を証明するものではありません。直接起動ではlauncherの生存確認も表示し、コピーした本文では`launcher_alive: null`です。
+
+直接起動はエージェントを起動する前に登録し、終了時に停止を記録します。本文だけの生成では未登録で、貼り付け先が本文中の`supervise register`を実行して開始します。一つのタスクに一つの監督を登録でき、競合は`SUPERVISOR_CONFLICT`になります。異常終了などで残った登録は、`status`で確認して明示的に`stop`してから開始し直してください。停止済みIDや古い本文で再開はできません。同じ本文の再登録で一時停止が解除されることもありません。
+
+送信中の`pause`/`stop`は`RECORD_BUSY`で失敗します。配送結果を確認して制御を再実行し、成功するまでは停止したと扱わないでください。監督役が自分で`resume`したり、生成コマンドから`--supervisor`を外して回避したりしないよう、必須テンプレートにも指示します。
+
+この制御は新しい監督ID付きコマンドに適用します。以前の版で開始した監督、IDなしの手動送信、同じOSユーザーが実行する任意のコードを隔離する機能ではありません。監督IDは秘密情報ではなく、古いセッションや操作の競合を検出する識別子です。
+
+### 指摘・解決条件・介入の評価を追う
+
+```bash
+codexteer findings create <thread-id> --key timeout --title "待機の終了条件" --condition "指定時間で終了する回帰テストが通る" --evidence src/monitor.mjs --based-on <cursor> --json
+codexteer findings list <thread-id> --json
+codexteer findings show <thread-id> <finding-id> --json
+codexteer send <thread-id> "終了条件を確認してください" --finding <finding-id> --based-on <cursor> --json
+codexteer findings resolve <thread-id> <finding-id> --checkpoint <checkpoint-id> --note "指定時間で終了することをテストで確認" --json
+codexteer findings evaluate <thread-id> <finding-id> --rating useful --reason "対象の不具合を再現して修正できた" --json
+codexteer findings stats <thread-id> --json
+```
+
+監督役は各行の`codexteer`を生成された実行コマンドへ置き換えます。監督ID付きの送信では`--finding`と`--based-on`が必須です（`instructions retract`はfinding不要）。通常の手動送信には追加オプションを要求しません。
+
+同じタスクの同じ`key`は既存IDを再利用します。そのrevisionに受付済み・受付不明の送信があれば、本文が違っていても`DUPLICATE_INTERVENTION`で拒否します。明確な`not_sent`だけは再試行でき、プレビューは予約しません。意味の似た別keyを自動検出する機能ではないため、同じ指摘に新しいkeyを作らないでください。
+
+新しい根拠や要件があれば`findings reopen`を使います。根拠または解決条件の変更と理由が必要で、cursorが進んだだけでは再介入できません。ユーザーの新たな要件は解決条件へ反映します。受付不明の送信は先に`history check`で確認し、`not_observed`だけで未配送と決めつけません。
+
+```bash
+codexteer findings reopen <thread-id> <finding-id> --condition "時間切れとキャンセルの両方で終了する" --reason "ユーザーがキャンセル対応を追加した" --based-on <cursor> --json
+codexteer findings dismiss <thread-id> <finding-id> --reason "既存の実装が条件を満たしていた" --json
+```
+
+配送、対応申告、解決判断は別に記録します。`history mark --status applied`の後も指摘は`awaiting_verification`です。解決には現在有効なcheckpointと、条件を満たしたと判断した根拠が必要です。解決時のrun IDと入力ハッシュを記録し、入力・最新run・成果物が変わると`needs_review`として未解決一覧に戻します。テストの成功だけで指摘の妥当性や設計の正しさを自動認定しません。
+
+評価は`useful`（有益）・`unnecessary`（不要）・`incorrect`（誤り）、未評価は`unrated`です。`stats`は現在のrevisionを1件として未送信候補も含め、評価済み件数と未評価件数を分けます。`useful_fraction`の母数は評価済み件数で、0件なら`null`です。介入の因果効果を証明する数値ではありません。詳細は`help findings`を参照してください。
+
+### 通常起動したDesktopを再起動せずに観測する
+
+Desktopが共有ローカルdaemonを使っていて、`CODEX_HOME/app-server-control/app-server-control.sock`が存在する環境では、観測専用の直接接続を選べます。
+
+```bash
+codexteer --connection desktop doctor --thread <thread-id> --json
+codexteer --connection desktop read <thread-id> --include-output --json
+codexteer --connection desktop watch <thread-id> --stream --json
+codexteer supervise <thread-id> --agent codex --connection desktop
+```
+
+既定の`--connection shared`は従来の`desktop start`で用意するwrapperです。`desktop`を選ぶと、既存ソケットの所有者・権限・同一性と、対象がロード済みであることを確認します。ソケットがなければ`DESKTOP_CONNECTION_UNAVAILABLE`、対象が未ロードなら`DESKTOP_THREAD_NOT_LOADED`で止まります。通常起動なら必ず使えるわけではありません。daemonの起動・再起動、設定変更、暗黙のタスク再開、別runtimeへの自動切り替えは行いません。
+
+直接接続で使えるのは観測です。送信・新規ターン・撤回送信・UI送信は`DESKTOP_READ_ONLY`で拒否します。送信は既存のshared方式を明示して使ってください。生成する監督プロンプトも接続方式を保持し、desktopでは観測専用の手順を使います。`doctor`は読み取り成功から送信・画面表示・承認継続の対応を推測しません。
+
+詳細は`help connection`を参照してください。今回の開発環境にはこのソケットがなく、実Desktopへの直接接続は未検証です。読み取り・エンドポイント検査・送信拒否は隔離したUnixソケットの模擬サーバーで検証しています。同梱Codex CLI 0.153.4を一時プロファイルとローカルの偽モデルで動かし、実際のUnix接続から合成履歴を読む検証も通過しました（`npm run test:connection`）。実Desktopの画面表示・承認継続の確認とは区別しています。
+
 ### タスクを探して送信する
 
 ```bash
@@ -177,7 +271,7 @@ codexteer watch <thread-id> --stream --json
 
 以下は用途別のコマンド一覧です。`<...>`は実際の値に置き換えてください。`<cursor>`は`read`・`status`・`watch`の結果、`<message-id>`は`send`・`history list`、`<checkpoint-id>`は`checkpoint capture`・`checkpoint list`、`<token>`は`resource acquire`の結果から取得します。
 
-対話起動の`supervise <thread-id> --agent claude`を除き、各コマンドに`--json`を付けるとJSONで結果を返します。`supervise prompt`もJSONに対応します。別コマンドを実行する`run`や監督役の起動では、codexteer側のオプションを区切りの`--`より前に置いてください。
+対話起動の`supervise <thread-id> [MESSAGE]`を除き、各コマンドに`--json`を付けるとJSONで結果を返します。`supervise prompt`もJSONに対応します。別コマンドを実行する`run`や監督役の起動では、codexteer側のオプションを区切りの`--`より前に置いてください。
 
 #### ヘルプ・バージョン
 
@@ -202,20 +296,22 @@ codexteer --version
 #### 監督役の起動
 
 ```bash
-codexteer supervise <thread-id> --agent claude
-codexteer supervise <thread-id> --agent claude -- --model <model> --effort <level>
+codexteer supervise <thread-id>
+codexteer supervise <thread-id> "監督方針を指定するメッセージ"
+codexteer supervise <thread-id> "監督方針を指定するメッセージ" --agent claude -- --model <model> --effort <level>
+codexteer supervise <thread-id> "監督方針を指定するメッセージ" --agent codex -- --model <model>
 codexteer help supervise
 ```
 
-`--agent`は必須で、現在の対応値は`claude`です。PATH上の実行ファイルを、現在の作業ディレクトリ・環境変数・標準入力・標準出力・標準エラーを引き継いで起動します。シェルのaliasやfunctionは使いません。
+`--agent`の対応値は`claude`と`codex`です。省略すると`claude`を使います。選択したエージェントのPATH上の実行ファイルを、現在の作業ディレクトリ・環境変数・標準入力・標準出力・標準エラーを引き継いで起動します。シェルのaliasやfunctionは使いません。
 
-最初の`--`以降は対象エージェントの引数です。順序・空文字・空白・改行を保ち、codexteer側では解釈もシェルでの再展開もしません。例えば区切り後の`--help`・`--version`・`--json`もClaudeへ渡します。呼び出し元のシェルで必要な引用は付けてください。
+最初の`--`以降は対象エージェントの引数です。上書きメッセージはその前に置きます。順序・空文字・空白・改行を保ち、codexteer側では解釈もシェルでの再展開もしません。例えば区切り後の`--help`・`--version`・`--json`も選択したエージェントへ渡します。呼び出し元のシェルで必要な引用は付けてください。
 
-追加引数の後ろには、Claude側の区切り`--`と、`supervise prompt`と同じ生成処理による監督プロンプトを一つの引数として付加します。追加引数の意味や組み合わせの妥当性はClaudeが判断します。
+追加引数の後ろには、エージェント側の区切り`--`と、`supervise prompt`と同じ生成処理による監督プロンプトを一つの引数として付加します。追加引数の意味や組み合わせの妥当性は選択したエージェントが判断します。
 
-不正なID形式、`--agent`の不足・未対応値、区切り前の未知の引数では起動しません。Claudeが未導入・実行不可などの起動失敗は標準エラーに理由を表示し、終了コード1です。Desktopの接続と対象タスクの存在は、起動した監督役が最初に確認します。
+不正なID形式、空のメッセージ、`--agent`の値不足・未対応値、区切り前の未知・過剰な引数では起動しません。選択したエージェントが未導入・実行不可などの起動失敗は標準エラーに理由を表示し、終了コード1です。Desktopの接続と対象タスクの存在は、起動した監督役が最初に確認します。
 
-通常終了ではClaudeの終了コードを返します。`SIGINT`・`SIGTERM`・`SIGHUP`は起動したClaudeへ転送し、シグナル終了時は`128 + シグナル番号`を返します。対話出力を引き継ぐため、この起動形式では`--json`は非対応です。ヘルプは`help supervise --json`、本文だけの取得は`supervise prompt <thread-id> --json`を使ってください。
+通常終了では選択したエージェントの終了コードを返します。`SIGINT`・`SIGTERM`・`SIGHUP`は起動したエージェントへ転送し、シグナル終了時は`128 + シグナル番号`を返します。対話出力を引き継ぐため、この起動形式では`--json`は非対応です。ヘルプは`help supervise --json`、本文だけの取得は`supervise prompt <thread-id> --json`を使ってください。
 
 #### 監督役（オーケストレーター）向けのプロンプトを取得
 
@@ -226,6 +322,9 @@ codexteer supervise prompt <thread-id>
 # タスクURLからも生成可能
 codexteer supervise prompt codex://threads/<thread-id>
 
+# 標準の監督方針を置き換えて本文を生成
+codexteer supervise prompt <thread-id> "監督方針を指定するメッセージ"
+
 # JSONで対象IDと本文を取得
 codexteer supervise prompt <thread-id> --json
 
@@ -233,7 +332,7 @@ codexteer supervise prompt <thread-id> --json
 codexteer help supervise prompt
 ```
 
-`supervise prompt`は、Claudeなどの監督役（オーケストレーター）へ渡す初期プロンプトを生成します。対象IDと引数を検証し、CLI一式を内容ハッシュ別の保存先へ配置・検証してから、正規化したIDと保存先を本文へ埋め込みます。保存・検証に失敗した場合は本文を出力せず、直接起動の場合もClaudeを起動しません。Desktopの起動・接続、履歴取得、送信、Claudeの起動は行いません。タスクの存在と接続は監督開始時に確認します。本文には観測・根拠付き介入・結果確認・停止までの手順を含みます。
+`supervise prompt`は、ClaudeやCodexなどの監督役（オーケストレーター）へ渡す初期プロンプトを生成します。対象IDと引数を検証し、CLI一式を内容ハッシュ別の保存先へ配置・検証してから、正規化したIDと保存先を本文へ埋め込みます。保存・検証に失敗した場合は本文を出力せず、直接起動の場合も監督エージェントを起動しません。Desktopの起動・接続、履歴取得、送信、監督エージェントの起動は行いません。タスクの存在と接続は監督開始時に確認します。本文には観測・根拠付き介入・結果確認・停止までの手順を含みます。
 
 各コマンドは開始時のNodeと保存したCLIの絶対パスを使うため、本文を貼り付ける先のPATHに`codexteer`がなくても実行できます。先頭の`CODEX_HOME='…'`で生成元のプロファイルを指定します。相対パスやシンボリックリンクで指定していたホームも、検証した実体への絶対パスを使います。空白や引用符を含むパスはシェル引数として引用します。本文に埋め込むパスに改行等の制御文字があれば、本文を出力する前に`SUPERVISION_PATH_UNSAFE`で拒否します。`CODEX_HOME`指定・引用・`--require-node-version`を含め、実行コマンドをそのまま使ってください。別のPCや別のプロファイルを監督する場合は、そこで本文を生成し直してください。
 
@@ -248,9 +347,9 @@ codexteer help supervise prompt
     "prompt": "対象IDと保存したCLIの実行コマンドを含む監督プロンプト本文…",
     "deployment": {
       "codex_home": "/Users/me/.codex",
-      "directory": "/Users/me/.codex/codex-steer/runtimes/0.14.1-<sha256>",
-      "wrapper_path": "/Users/me/.codex/codex-steer/runtimes/0.14.1-<sha256>/bin/codexteer-wrapper.mjs",
-      "version": "0.14.1",
+      "directory": "/Users/me/.codex/codex-steer/runtimes/0.15.0-<sha256>",
+      "wrapper_path": "/Users/me/.codex/codex-steer/runtimes/0.15.0-<sha256>/bin/codexteer-wrapper.mjs",
+      "version": "0.15.0",
       "sha256": "<sha256>",
       "reused": false
     },
@@ -259,7 +358,7 @@ codexteer help supervise prompt
 }
 ```
 
-IDが不正な場合や引数が不足・過剰な場合は終了コード1です。通常は標準エラーへ理由を出し、本文は出力しません。`--json`では標準出力に`{"ok":false,"error":{"message":"理由"}}`を返します。起動に使う本文の生成には`--json`を付けないでください。
+IDが不正な場合、引数が不足・過剰な場合、メッセージが空文字・空白だけの場合は終了コード1です。通常は標準エラーへ理由を出し、本文は出力しません。`--json`では標準出力に`{"ok":false,"error":{"message":"理由"}}`を返します。空のメッセージでは`error.code`に`INVALID_SUPERVISION_POLICY`も返します。起動に使う本文の生成には`--json`を付けないでください。
 
 Codex CLIでも、`steer_prompt=$(codexteer supervise prompt <thread-id>) && codex "$steer_prompt"`のように初期プロンプトを渡せます。生成プロンプトには、Monitorが使えない場合の短い`watch`による手順と、監督AI自身の送信元名を使う案内を含みます。
 

package/docs/distribution.md

@@ -1,17 +1,19 @@
 # 配布と永続実行
 
 パッケージ名は `codexteer`、CLI名は `codexteer`、ライセンスはMITです。
-旧npmパッケージは`@vinhphatfsg/codex-steer`です。GitHubリポジトリの改名はnpmパッケージを公開・改名する操作ではなく、`codexteer`は新しいパッケージとして公開します。公開時は`npm whoami`でnpm側のユーザーを確認してください。
+旧npmパッケージは`@vinhphatfsg/codex-steer`です。`codexteer@0.14.1`は公開済みで、このブランチは次期版`0.15.0`を準備します。GitHubのPR作成・マージはnpm公開を行う操作ではありません。公開時は`npm whoami`でnpm側のユーザーを確認してください。
 `package.json` は `private` を持たず、`publishConfig` でnpm公式レジストリへのpublic公開を指定しています。公開可能な設定であることと、実際に公開済みであることは別です。
 
 公開後の基本的な実行形式は次のとおりです。通常はバージョン指定なしで使えます。監督開始後は保存したCLIを使い続けるため、監督中の一貫性を保つために版を明示する必要はありません。起動側と操作側の製品バージョンも、必要な通信仕様が対応していれば異なっていても使えます。
-この例は現在公開済みであることを示すものではありません。`-y` はnpmの取得確認を省略します。
+以下の新しい監督機能をnpxで使うには0.15.0の公開が必要です。公開前はこのブランチをソースから導入してください。`-y` はnpmの取得確認を省略します。
 
 ```text
 npx -y codexteer desktop start
 npx -y codexteer doctor --thread <thread-id> --json
-npx -y codexteer supervise <thread-id> --agent claude
+npx -y codexteer supervise <thread-id>
+npx -y codexteer supervise <thread-id> "監督方針を指定するメッセージ"
 npx -y codexteer supervise prompt <thread-id>
+npx -y codexteer supervise prompt <thread-id> "監督方針を指定するメッセージ"
 npx -y codexteer read <thread-id> --json
 npx -y codexteer send <thread-id> "message" --json
 ```
@@ -25,9 +27,13 @@ CLIはDesktopを自動終了しません。
 
 `0.14.1`以降の`supervise`と`supervise prompt`は、開始時のCLI本体と依存を内容ハッシュ別の永続配置へコピーし、その保存先を使う実行コマンドを本文に埋め込みます。npxで取得したパッケージもソースのチェックアウトも、同じ保存・検証・生成処理を使います。起動経路を推測する環境変数や切り替えオプションは不要です。本文の生成処理自体も保存したCLI一式から読み込みます。
 
+両形式で対象IDの後ろに任意の`MESSAGE`を一つの引数として渡せます。省略時は保存したCLIの標準方針を使い、指定時は標準方針全体をその文に置き換えます。必須の共通テンプレートは保存したCLIから常に生成し、対象・実行コマンド・操作時の確認を保ちます。指定文は生成・起動ごとの入力で、永続配置のファイルやマニフェストへ書き込まず、内容ハッシュにも含めません。同じCLIなら異なる方針でも保存先を検証して再利用します。空文字・空白だけの文は保存処理前に`INVALID_SUPERVISION_POLICY`で拒否します。本文の文字列はテンプレートやシェルとして評価しません。
+
+直接起動の`supervise`はClaudeを既定にし、`--agent claude`の明示と`--agent codex`にも対応します。監督方針は最初の`--`より前、エージェント側の起動引数はその後ろへ置いてください。
+
 監督役の`doctor`・`read`・`watch`・`send`等はこのコピーを使います。パスはシェル引数として引用し、空白・引用符・コマンド置換に見える文字も文字列として扱います。本文に埋め込むパスに改行や制御文字があれば、`SUPERVISION_PATH_UNSAFE`で拒否します。ヘルプの`codexteer`表記も、監督役には指定された実行コマンドに置き換えるよう指示します。
 
-`supervise prompt`も読み取り専用ではなく、IDと引数の検証後にCLI一式の保存・再利用の検証を行ってから本文を出力します。保存・検証に失敗した場合は部分的な本文を出力せず、直接起動の場合もClaudeを起動しません。Desktopへの接続・設定変更・履歴取得・送信は行いません。`--json`には対象IDと本文に加えて`data.deployment`（元のホームを示す`codex_home`・保存先・版・ハッシュ・再利用の有無）と`data.node`（Nodeの実体パス・版）を返します。ヘルプの表示は保存処理を行いません。
+`supervise prompt`も読み取り専用ではなく、IDと引数の検証後にCLI一式の保存・再利用の検証を行ってから本文を出力します。保存・検証に失敗した場合は部分的な本文を出力せず、直接起動の場合もエージェントを起動しません。Desktopへの接続・設定変更・履歴取得・送信は行いません。`--json`には対象IDと本文に加えて`data.deployment`（元のホームを示す`codex_home`・保存先・版・ハッシュ・再利用の有無）、`data.node`（Nodeの実体パス・版）、`data.supervisor`（session_id・owner・connection）を返します。ヘルプの表示は保存処理を行いません。
 
 本文は同じPC向けです。全コマンドの先頭に`CODEX_HOME='…'`を埋め込み、配置時に検証したホームの実体パスへ固定します。生成時に`CODEX_HOME`が未設定なら、既定の`~/.codex`の実体パスを使います。相対パスやシンボリックリンクも絶対パスに解決するため、貼り付け先の作業ディレクトリや`CODEX_HOME`が異なっても、生成元のruntimeと履歴を使います。別のプロファイルを監督する場合は、そこで本文を生成し直してください。
 
@@ -47,12 +53,12 @@ CLIとnpmパッケージは`codexteer`へ変更しました。起動ファイル
 
 履歴・チェックポイント・resourceロック・永続配置の保存先`CODEX_HOME/codex-steer`、配置目録`.codex-steer-runtime.json`、IPCの親ディレクトリ`/private/tmp/codex-steer-<uid>`、通信・診断用JSONの`codex_steer_*`フィールドは旧名を維持します。履歴の移動や稼働中runtimeの置き換えをせず、旧パッケージとの間でも従来の操作別互換性チェックを使います。診断に旧パッケージ名との差が表示されても、それだけで操作を拒否しません。
 
-既存の保存済みコピーは変更・削除しません。新しいCLI・npm名と起動ファイル名は配布物の内容ハッシュに含まれるため、同じ`0.14.1`でも旧名の配布物とは別のコピーになります。
+既存の保存済みコピーは変更・削除しません。新しいCLI・npm名と起動ファイル名は配布物の内容ハッシュに含まれるため、同じ製品バージョンでも旧名の配布物とは別のコピーになります。
 
 ## 配布物
 
 `package.json` の `files` で `bin`、`src`、必要なAppleScript、音源、配布ドキュメントを指定します。
-README、MIT LICENSE、package.jsonに加え、依存する `ws` とそのライセンスを `bundleDependencies` で同梱します。
+README、CHANGELOG、MIT LICENSE、package.jsonに加え、依存する `ws` とそのライセンスを `bundleDependencies` で同梱します。
 実行時に追加の依存をネットワークから取得しません。install/postinstall/prepare/prepackフックは使用しません。
 テスト、開発用スクリプト、`.codex`、ログ、認証情報は配布対象に含めません。
 
@@ -150,13 +156,14 @@ npm run check
 npm test
 npm run test:package
 npm run test:protocol
+npm run test:connection
 ```
 
 `test:package` は実際のtarballを作り、同梱内容・実行権限を確認して、隔離した空のnpmキャッシュからオフラインでインストールします。
 公開を禁止する`private`フィールドがないこと、CLIの`bin`が正規化済みのパスであることも確認します。さらに資格情報を渡さず、外部公開できない接続先・offline・dry-runでnpmの公開準備を検証し、自動補正の警告がなく、テストするtarballと内容ハッシュが一致することを確認します。npmのdry-runは`EPRIVATE`の判定を省略するため、dry-runの成功だけで公開可能とは判断しません。
 リポジトリ外でCLIを実行し、模擬runtimeに対する異なる版でのread/send、機能単位の拒否、キャッシュ削除後の永続配置を検証します。
 改名後のCLIから旧パッケージ名のruntimeへread/sendできることと、旧名の保存先にある履歴を変更せずに読めることも確認します。
-npxから模擬Claudeを起動して保存したCLIへの参照を確認し、同じ本文を別プロセスへ貼り付けた場合も検証します。元のキャッシュの更新・削除後も保存した版を使い、模擬runtimeへのread/sendを継続できることを確認します。単体テストでは同じ版のソース変更、別の版への更新、保存済みコピーの改変、Nodeバージョンの不一致も検証します。監督側のPATHに別のCLIがある場合やCLIがない場合を含み、実際のClaudeやモデルは起動しません。
+npxから模擬Claudeと模擬Codexを起動して保存したCLIへの参照を確認し、同じ本文を別プロセスへ貼り付けた場合も検証します。元のキャッシュの更新・削除後も保存した版を使い、模擬runtimeへのread/sendを継続できることを確認します。単体テストでは同じ版のソース変更、別の版への更新、保存済みコピーの改変、Nodeバージョンの不一致も検証します。監督側のPATHに別のCLIがある場合やCLIがない場合を含み、実際のエージェントやモデルは起動しません。
 `test:protocol` は実際の同梱CLIと模擬Desktopを使います。実ユーザーのタスクへの送信やDesktopの停止は行いません。
 実際のnpm公開には、アカウントとパッケージの公開権限確認、公開版の確定とユーザーからの公開指示が必要です。
 
@@ -164,7 +171,7 @@ npxから模擬Claudeを起動して保存したCLIへの参照を確認し、
 
 レビュー・検証を終えた版を、npm側の公開権限を持つアカウントで公開します。手動公開には2FAを有効にしたアカウントを使ってください。
 
-公開済みのパッケージ名とバージョンの組み合わせは再公開できません。旧パッケージ`@vinhphatfsg/codex-steer@0.14.0`は変更せず、今回の配布物は`codexteer@0.14.1`として公開します。削除しても同じ名前・版番号の組み合わせを再利用できません。[npm publishの仕様](https://docs.npmjs.com/cli/v11/commands/npm-publish/)
+公開済みのパッケージ名とバージョンの組み合わせは再公開できません。既存の`codexteer@0.14.1`は変更せず、今回の配布物は`codexteer@0.15.0`として準備します。公開は別途実行します。削除しても同じ名前・版番号の組み合わせを再利用できません。[npm publishの仕様](https://docs.npmjs.com/cli/v11/commands/npm-publish/)
 
 ```bash
 npm login
@@ -173,14 +180,32 @@ npm run test:package
 npm publish --access public
 ```
 
-公開後は、公開した版と起動コマンドの登録を確認します。次は0.14.1を公開した場合の例です。
+公開後は、公開した版と起動コマンドの登録を確認します。次は0.15.0を公開した場合の例です。
 
 ```bash
-npm view codexteer@0.14.1 version bin --json
-npx -y codexteer@0.14.1 --version
+npm view codexteer@0.15.0 version bin --json
+npx -y codexteer@0.15.0 --version
 ```
 
 `EPRIVATE`はリポジトリの`package.json`に公開禁止設定が残っていることを示します。`--access public`はその禁止を解除しません。
 `bin`のパスは`bin/codexteer.mjs`とし、先頭に`./`を付けません。npm 11.6.2では先頭の`./`を正規化する際に「invalid and removed」という警告が出ますが、この場合の実装は`bin`を保持しています。警告を避けるため、正規化済みの表記を配布元から使います。
 
 参考: [npmのfilesとbundleDependencies](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/)、[npm exec/npxのキャッシュ](https://docs.npmjs.com/cli/v11/commands/npm-exec/)、[パッケージの公開](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages/)。
+
+## 監督状態・指摘と接続方式
+
+ここからの監督制御、指摘管理、Codex CLI起動、接続方式の選択は0.15.0で追加します。保存済みCLIの機能自体は0.14.1から利用できます。製品の機能追加に伴うminor更新であり、runtime protocolと既存capabilityのv1契約は維持します。
+
+保存したCLIへのコマンドは、canonical CODEX_HOME、Node guard、`--supervisor <session-id>`、`--connection shared|desktop`を一緒に保持します。各プロンプト生成は新しいIDを発行しますが、生成だけでは登録しません。直接起動はエージェント起動前に登録し、終了時に停止します。コピーした本文は最初のregisterで開始します。
+
+同じホームの`codex-steer/supervisors`はタスク別の制御、`supervisor-observations`はセッション別の最終CLI観測、`findings`は指摘・解決条件・revision・評価を保存します。既存のstoreと同じ所有者専用のディレクトリ0700・ファイル0600を使い、シンボリックリンクや不適切な所有者・権限を拒否します。観測と制御を別レコードにし、readの完了でpause/stopを上書きしません。
+
+送信とpause/stopはタスクの監督ロック、指摘の変更と送信履歴はタスクのメッセージロックで直列化します。処理中の競合は`RECORD_BUSY`で明示し、未知の受付結果を自動再送しません。送信受付後に監督状態の書き込みだけが失敗した場合は、配送結果とIDを維持して`supervision_update_required: true`を返します。これは再送の指示ではありません。
+
+生成した新しい監督ID付きコマンドだけが制御対象です。以前の保存済みCLIやIDなしの手動コマンドは既存の挙動を維持します。同じOSユーザーの別プロセスや任意コードに対する認証・隔離ではありません。状態activeは登録を示し、観測時刻はCLIの取得結果であってAIの読了の証明ではありません。
+
+指摘の重複はkeyとrevisionで判定します。cursorだけではrevisionを進めず、新しい根拠か解決条件の変更と理由を要求します。URLは参照だけ、ファイル根拠は送信直前に再照合します。解決のnoteは明示的な判断で、checkpointのrun・入力・成果物の整合性と区別します。評価は未送信候補を含む現在revisionの集計です。操作例と制約はREADME、`help findings`、`help supervise`に記載しています。
+
+`--connection desktop`は既存の`CODEX_HOME/app-server-control/app-server-control.sock`へ読み取り専用で接続します。ホームは所有者一致かつgroup/other書込不可、制御ディレクトリとソケットは所有者専用に限定します。接続前後・各API要求でendpointを検査し、ロード済み対象だけを読み取ります。明示的な選択であり、自動検出による接続切り替え・daemon起動・Desktop再起動はしません。送信機能の診断は`unsupported`、`source: observation-only`です。実機での送信・UI表示・承認継続は未検証のまま残します。
+
+開発用の`npm run test:connection`は、Desktop同梱CLIを一時プロファイルのUnixソケットで起動し、ローカル偽モデルで作った合成履歴の読み取りを確認します。実Desktopへの接続・設定変更や外部モデル利用は行いません。`npm run test:protocol`は既存wrapper・偽Desktopとの送信と承認経路、`npm run test:package`は実tarball・オフラインnpx・偽Claude/Codexの起動と、別CODEX_HOME・キャッシュ削除後の観測/送信・pause/resume・重複拒否を確認します。これらの隔離検証から実Desktopの表示や直接接続での承認往復まで保証するものではありません。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexteer",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Send steering messages to running Codex Desktop threads from a terminal.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "check": "node scripts/check-syntax.mjs",
     "test": "node --test",
     "test:protocol": "node scripts/probe-app-server.mjs",
+    "test:connection": "node scripts/probe-desktop-connection.mjs",
     "benchmark:read": "node scripts/benchmark-read.mjs",
     "test:package": "node scripts/test-package.mjs"
   },
@@ -29,6 +30,7 @@
     "src/*.mjs",
     "scripts/*.applescript",
     "assets/send-pururu.wav",
+    "CHANGELOG.md",
     "docs/distribution.md"
   ],
   "bundleDependencies": [