docs: finalize release docs and refresh agent skill

9 files changed, 311 insertions, 50 deletions

diff --git a/website/src/content/docs/ja/agent-automation.mdx b/website/src/content/docs/ja/agent-automation.mdx
new file mode 100644
index 00000000..a6dd041b
--- /dev/null
+++ b/website/src/content/docs/ja/agent-automation.mdx
@@ -0,0 +1,121 @@
+---
+title: エージェント自動化
+description: Herdr のレイアウト、ペイン、エージェントの各プリミティブを使い、スクリプトや別のエージェントからコーディングエージェントを連携させます。
+---
+
+Herdr はコーディングエージェントの自動化レイヤーとして使えます。スクリプトから制御することも、ひとつのエージェントから別のエージェントへ作業を渡し、状態を確認して結果を集めることもできます。重要なのは、目的に合うプリミティブを選ぶことです。
+
+## 3 つのプリミティブ
+
+| プリミティブ | 責務 |
+| --- | --- |
+| レイアウト（`workspace`、`tab`、ペイン構成） | ターミナルの場所を作成し、整理する。 |
+| ペイン | 生のターミナルを制御する。コマンド実行、入力送信、出力読み取り、出力待機を行う。 |
+| エージェント | 認識済みコーディングエージェントを、名前またはペインとライフサイクル状態に基づいて制御する。 |
+
+ペインは、エージェントが入っていなくても存在します。エージェントは、ペイン内で現在実行されていると Herdr が認識したプロセスです。そのため `agent start` には既存のシェルペインが必要で、レイアウトの作成、分割、移動は行いません。
+
+ワークスペースを作成すると最初のタブとルートペインも作られ、タブを作成するとそのルートペインも作られます。最初のプロセスには返されたペイン ID を使い、そのレイアウトに別のターミナルが必要なときだけ分割します。
+
+作成コマンドは JSON を出力します。ID を推測せず、レスポンスから取得してください:
+
+```bash
+created=$(herdr workspace create --cwd ~/project --label api --no-focus)
+pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')
+
+split=$(herdr pane split "$pane_id" --direction right --no-focus)
+review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
+```
+
+`workspace create` は `.result.workspace`、`.result.tab`、`.result.root_pane` を返します。`tab create` は `.result.tab` と `.result.root_pane` を返し、`pane split` は新しいペインを `.result.pane` として返します。
+
+ペインを別のワークスペースへ移動すると、ワークスペース修飾付きのペイン ID が変わります。`pane move` の後は `.result.move_result.pane.pane_id` を使い、以前の値が必要なら `.result.move_result.previous_pane_id` を参照してください。実行中プロセスは起動時の Herdr 環境を保ちますが、以前の `HERDR_PANE_ID` はそのターミナルの別名として残るため、`--current` は引き続き安全に使えます。移動後に始めるコマンドはエージェント名で解決できますが、すでに進行中の待機は `agent_not_running` で終了します。
+
+シェル、テスト、サーバー、CI ウォッチャーなどの通常のターミナルプロセスにはペインコマンドを使います。どのエージェントが動いているか、または状態が `working`、`blocked`、`done`、`idle`、`unknown` のどれかを Herdr に判断させる場合はエージェントコマンドを使います。
+
+## エージェントの識別子と起動
+
+`w1:p2` のようなペイン ID はターミナルの場所を識別します。`reviewer` のようなエージェント名は、そのペインに現在いるエージェントの扱いやすい別名です。名前は `[a-z][a-z0-9_-]{0,31}` に一致し、ライブエージェント間で一意でなければなりません。エージェントが終了、解放、または置換されると別名は消えます。ペイン自体の恒久的な名前ではありません。
+
+エージェントコマンドは、一意なライブ名、または現在そのエージェントをホストしているペイン ID のどちらでも指定できます。
+
+利用可能なシェルペインとは、対話シェルのプロンプトに戻っており、フォアグラウンドをシェル自身が所有し、フォアグラウンドのコマンド、エディタ、エージェントが動いていないペインです。`agent start` の前にプロンプトへ戻してください。
+
+`--kind` は対応済みエージェントとその標準実行ファイルを選びます。対応する kind は `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`maki` です。`--` より後の引数は、その実行ファイルへそのまま渡されます。
+
+`agent start` は、同じターミナルで期待したエージェントを検出し、対話入力の準備ができたと Herdr が判断してから返ります。起動待機はデフォルトで 30 秒です。`--timeout` は 3000 より大きく 300000 以下のミリ秒で指定します。
+
+```bash
+herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
+```
+
+手動で起動したエージェントも自動検出され、ペイン ID で指定できます。人が読みやすい安定した対象名が必要なら名前を付けます:
+
+```bash
+herdr agent get w1:p2
+herdr agent rename w1:p2 reviewer
+```
+
+## 操作面を選ぶ
+
+| 目的 | コマンド |
+| --- | --- |
+| シェルコマンドを実行して送信する | `pane run` |
+| Enter を付けずに文字列を送る | `pane send-text` |
+| ターミナルキーや修飾キーの組み合わせを送る | `pane send-keys` |
+| 文字列や正規表現を待つ | `pane wait-output` |
+| 既存のペインで対応済みエージェントを起動する | `agent start` |
+| プロンプトを送信し、必要なら完了を待つ | `agent prompt` |
+| エージェントの対話 UI にキーを送る | `agent send-keys` |
+| エージェントのライフサイクル状態を待つ | `agent wait` |
+
+`agent prompt` は文字列とエンコード済み Enter を送信し、ターミナルの現在の bracketed paste モードを尊重します。working 中のエージェントにも送信できます。`esc`、`up`、`enter`、`ctrl+c` のような操作には `agent send-keys` を使います。`escape` も `esc` のエイリアスとして使えます。意図的に生のターミナルを操作したい場合は、ペイン入力コマンドを使ってください。
+
+ペイン入力は、現在のプロセスに関係なくターミナルを指定します。エージェント入力はライブエージェントを解決し、そのエージェントがペインを制御しなくなっていれば操作を拒否します。
+
+`agent prompt --wait` はプロンプトをすぐ送信します。エージェントが non-working 状態から始まる場合、Herdr はまず 5 秒以内にライフサイクル変化が観測されることを要求します。状態シーケンスが進まなければ、無期限に待たず `agent_prompt_stalled` を返します。呼び出し側の `--timeout` が 5 秒以下なら、通常の `timeout` エラーを返します。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。エージェントがすでに working の場合、進行中ターンの完了が待機を満たすことがあります。単独の `agent wait` は現在のエージェントを監視し、すでに状態が一致していれば即座に返ります。どちらもデフォルトでは `idle`、`done`、`blocked` を待ちます。複数の正確な状態を許可するには、`--until idle --until done` のように `--until` を繰り返します。`unknown` が必要な場合は `--until unknown` を明示してください。`agent prompt` では `--until` に `--wait` が必要です。
+
+`idle` は、エージェントが入力待ちで、そのタブがフォーカス中の Herdr UI ですでに表示済みであることを示します。`done` は同じ基礎的な idle 状態ですが、バックグラウンド作業が完了してから、そのタブをフォーカスするか `pane focus` / `agent focus` で対象にするまで使われます。CLI で読み取るだけでは表示済みになりません。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するもののライフサイクルを確実に分類できない状態で、成功完了を意味しません。違いが重要なら正確な `--until` を指定してください。
+
+`pane wait-output` はエージェントのライフサイクルを解釈しません。選択したターミナルスナップショットをポーリングし、最初にすぐ検索するため、すでに存在する文字列も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更でき、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。
+
+CLI では、`pane read` と `agent read` のどちらもターミナルテキストを直接出力します。デフォルトは ANSI エスケープを除去した UTF-8 テキストです。ソースに装飾が含まれる場合、`--format ansi` または `--ansi` でエスケープを残します。`detection` ソースは常にプレーンテキストです。recent 系ソースでは、`--lines N` は折り返し解除の前に末尾の N 描画行を選び、省略時は 80 行です。`visible` と `detection` では、省略時にスナップショット全体を返し、指定時は改行で区切られた末尾 N 行を返します。socket API ではテキストを `.result.read.text` に返します。
+
+## 既知の注意点: 代替画面の出力
+
+Claude Code や OpenCode などの全画面エージェントは、ターミナルの代替画面に描画することがあります。代替画面の行は Herdr のホスト側スクロールバックには入りません。応答が表示中のペインを超えると、アプリが表示しなくなった行を `recent` や `recent-unwrapped` で復元することはできません。`--lines` を増やしても、その履歴は取得できません。フォントが大きい場合やペインが小さい場合は、より起こりやすくなります。
+
+エージェントに簡潔な応答を求めるか、ペインを広げる、フォントを小さくする、またはエージェント自身のトランスクリプトやスクロール操作を使ってください。エージェント内でスクロールした後、`--source visible` を使うと、現在描画されているページを読み取れます。
+
+成功した `agent start`、`agent prompt`、`agent wait` は現在のエージェントを `.result.agent` に返します。`pane wait-output` は `.result.pane_id`、`.result.matched_line`、一致したスナップショット `.result.read` を返します。
+
+wait コマンドにはデフォルトのタイムアウトがなく、無期限に待機できます。タイムアウトやサーバーエラーでは JSON エラーを stderr に出して終了コード 1、CLI 構文エラーでは終了コード 2 を返します。
+
+## レシピ
+
+補助エージェントを起動して作業を渡し、その作業が落ち着くまで待ちます:
+
+```bash
+split=$(herdr pane split --current --direction right --no-focus)
+review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
+herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
+herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
+herdr agent read reviewer --source recent-unwrapped --lines 120
+```
+
+エージェントが入力を求めるまで待ち、内容を確認して対話 UI を操作します:
+
+```bash
+herdr agent wait reviewer --until blocked --timeout 120000
+herdr agent read reviewer --source recent-unwrapped --lines 80
+herdr agent send-keys reviewer esc
+```
+
+通常のプロセスを実行し、エージェントとして扱わずに出力を待ちます:
+
+```bash
+herdr pane run w1:p3 "just test --watch"
+herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000
+```
+
+コマンドとオプションの完全な一覧は [CLI リファレンス](/ja/docs/cli-reference/) を参照してください。シェル補完でも同じコマンドツリーを対話的に確認できます。
diff --git a/website/src/content/docs/ja/agent-skill.mdx b/website/src/content/docs/ja/agent-skill.mdx
index 1fc6405d..97d109f7 100644
--- a/website/src/content/docs/ja/agent-skill.mdx
+++ b/website/src/content/docs/ja/agent-skill.mdx
@@ -58,7 +58,7 @@ claude
 
 ## エージェント向けリファレンス
 
-コマンドの完全なガイドはスキルファイル自体にあります。ペイン ID、`pane split`、`pane run`、`pane read`、`wait output`、`wait agent-status`、ワークスペースとタブのコマンド、協調動作のレシピを扱っています。
+コマンドの完全なガイドはスキルファイル自体にあります。ペイン ID、`pane split`、`pane run`、`pane read`、`pane wait-output`、`agent wait`、ワークスペースとタブのコマンド、協調動作のレシピを扱っています。
 
 ソースファイルはこちら:
 
diff --git a/website/src/content/docs/ja/agents.mdx b/website/src/content/docs/ja/agents.mdx
index 1208195c..4b08da69 100644
--- a/website/src/content/docs/ja/agents.mdx
+++ b/website/src/content/docs/ja/agents.mdx
@@ -5,6 +5,8 @@ description: Herdr が何を検出できるか、エージェント状態の仕�
 
 Herdr は複数のコーディングエージェントを同時に動かすために作られています。各エージェントは、シェル、ログ、プロンプト、実行中プロセスをそのまま保った実際のターミナルペインの中にいます。Herdr はどのペインにエージェントがいるかを追跡し、その状態をタブとワークスペースに集約し、すべてのターミナルを手作業で見回る代わりに、注意が必要なペインへ直接ジャンプできるようにします。
 
+スクリプトや別のエージェントから連携させる方法は、[エージェント自動化](/ja/docs/agent-automation/) を参照してください。
+
 ## 対応エージェント
 
 一般的なコーディングエージェントは、追加設定なしで自動検出されます。重要な違いは Herdr がエージェントを見えるかどうかではありません。どのシグナルが `idle`、`working`、`blocked` を決定する権限を持つかです。
@@ -47,7 +49,7 @@ Claude Code、Codex、GitHub Copilot CLI、Droid、Qoder CLI、Cursor Agent CLI
 
 ## VM とサンドボックスラッパー
 
-Linux では、VM、Bubblewrap、`fence` のようなラッパーがホストの `/proc` から実際のエージェントプロセスを隠すことがあります。コマンドに `HERDR_AGENT=<agent>` を設定して (例: `HERDR_AGENT=claude fence -- claude`)、どの既存エージェントのスクリーンマニフェストを使うべきか Herdr に伝えてください。このヒントはそのフォアグラウンドプロセスにスコープされます。継承されるすべてのフォアグラウンドプロセスをそのエージェントとして扱いたいのでない限り、シェルからグローバルに export するのは避けてください。
+Linux と macOS では、ホストから見えるラッパーが実際のエージェントプロセスを Herdr から隠すことがあります。ラッパーのコマンドに `HERDR_AGENT=<agent>` を設定して、どの既存エージェントのスクリーンマニフェストを使うべきか Herdr に伝えてください。たとえば、Linux では `HERDR_AGENT=claude fence -- claude`、macOS では `HERDR_AGENT=claude nono run --profile claude-code -- claude` を実行します。このヒントはそのフォアグラウンドプロセスにスコープされます。VM やコンテナの内部だけで設定しても Herdr からは見えません。また、継承されるすべてのフォアグラウンドプロセスをそのエージェントとして扱いたいのでない限り、グローバルな export は避けてください。
 
 ## blocked 状態
 
@@ -110,7 +112,7 @@ herdr agent rename w1:p1 reviewer
 herdr agent rename reviewer --clear
 ```
 
-ターゲットにはターミナル ID、一意なエージェント名、検出または報告されたエージェントラベル、レガシーなペイン ID が使えます。
+ターゲットには一意なライブエージェント名、または現在そのエージェントをホストしているペイン ID を使います。ターミナル ID とエージェント kind のラベルだけでは指定できません。
 
 ## カスタムステータスラベル
 
@@ -131,24 +133,6 @@ herdr pane report-metadata w1:p1 \
 
 エージェントサイドバー行では、`terminal_title` または `terminal_title_stripped` も任意で使えます。どちらもデフォルト行には含まれません。前者は安全性のために正規化された最新の OSC 0/2 ターミナルタイトルを表示し、後者は先頭にある認識済みのアクティビティまたはスピナーのグリフ 1 つと、それに続く空白を除去します。これらの値は Herdr サーバーが所有し、コールドリスタートをまたいで保持されません。また、メタデータのタイトルや意味的なエージェント状態から独立しています。そのため、除去後のテキストが同じなら、スピナーのアニメーションで生のタイトルが変わってもペイン更新は発行されません。
 
-## CLI からエージェントを起動する
-
-ターミナルをエージェントターゲットとして扱いたいときは `herdr agent ...` コマンドを使います。エージェントターゲットは `agent list` に表示され、エージェント名で読み取りや入力送信ができ、エージェント状態で wait でき、直接アタッチできます。
-
-スクリプトから Herdr にエージェントを起動します:
-
-```bash
-herdr agent start reviewer --cwd ~/project --split right -- pi
-```
-
-特定のワークスペースやタブに配置することもできます:
-
-```bash
-herdr agent start docs --workspace w1 --tab w1:t1 -- claude
-```
-
-通常のターミナル、サーバー、テスト、シェル、低レベルなターミナル入力には `herdr pane ...` コマンドを使ってください。たとえば `cargo test` には `agent start` ではなく `pane split` と `pane run` を使います。そのターミナルを意図的にエージェントターゲットとして扱うのでない限り。
-
 ## エージェントに直接アタッチする
 
 完全な Herdr UI ではなく、ひとつのエージェントターミナルに現在のターミナルをアタッチします:
diff --git a/website/src/content/docs/ja/cli-reference.mdx b/website/src/content/docs/ja/cli-reference.mdx
index 9aa1ebe5..3b96247e 100644
--- a/website/src/content/docs/ja/cli-reference.mdx
+++ b/website/src/content/docs/ja/cli-reference.mdx
@@ -126,6 +126,8 @@ herdr workspace close <workspace_id>
 herdr workspace create --cwd ~/project --label api --no-focus
 ```
 
+ワークスペースは最上位のプロジェクトまたは作業コンテキストです。作成時に最初のタブとルートペインも作られます。JSON レスポンスの `.result.workspace.workspace_id`、`.result.tab.tab_id`、`.result.root_pane.pane_id` から各 ID を取得できます。
+
 ## Worktree
 
 ```bash
@@ -150,6 +152,10 @@ herdr tab rename <tab_id> <label>
 herdr tab close <tab_id>
 ```
 
+タブはワークスペース内の別のターミナルレイアウトです。`--workspace` を省略すると、`tab create` はアクティブなワークスペースを使い、存在しなければ失敗します。JSON レスポンスの `.result.tab.tab_id` と `.result.root_pane.pane_id` から ID を取得できます。
+
+ワークスペースとタブの作成、およびペインの分割は、デフォルトではフォーカスを変えません。`--focus` は新しいレイアウトを選択し、`--no-focus` はデフォルトを明示します。`--cwd` がない場合、新しいターミナルは `terminal.new_cwd` の設定に従い、デフォルトでは元のペインまたはワークスペースを引き継ぎます。各 `--env KEY=VALUE` は新しいルートシェルの環境変数を追加または置換します。
+
 ## ペイン
 
 ```bash
@@ -173,14 +179,20 @@ herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--f
 herdr pane close <pane_id>
 ```
 
+`--current` を受け付けるペインコマンドは、Herdr ペイン内から実行した場合、呼び出し元の `HERDR_PANE_ID` を使います。`pane split` では、明示したペイン ID または `--pane ID` がそのペインを、`--current` が呼び出し元ペインを分割します。対象を省略すると UI でフォーカス中のペインを使います。分割レスポンスでは、新しいペイン ID は `.result.pane.pane_id` にあります。
+
+`pane move` の後続コマンドには `.result.move_result.pane.pane_id` を使います。別ワークスペースへの移動ではワークスペース修飾付きのペイン ID が変わり、以前の値は `.result.move_result.previous_pane_id` に残ります。実行中プロセスの `HERDR_PANE_ID`、`HERDR_TAB_ID`、`HERDR_WORKSPACE_ID` は起動時の値のままですが、Herdr は以前のペイン ID をそのターミナルの別名として保持するため、`--current` を使うペインコマンドは引き続き解決できます。ライブエージェント名もターミナルに追従します。
+
 出力を読む:
 
 ```bash
-herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N]
+herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
 herdr pane read <pane_id> --source visible --ansi
 herdr pane read <pane_id> --source recent-unwrapped --lines 120
 ```
 
+`pane read` は UTF-8 のターミナルテキストを直接出力します。デフォルトでは ANSI エスケープを除去し、ソースに装飾が含まれる場合は `--format ansi` または `--ansi` で保持します。`detection` ソースは常にプレーンテキストです。recent 系ソースでは、`--lines N` は折り返し解除の前に末尾の N 描画行を選び、省略時は 80 行です。`visible` と `detection` では、省略時にスナップショット全体を返し、指定時は改行で区切られた末尾 N 行を返します。`agent read` も同じ出力と行数の動作です。
+
 入力を送る:
 
 ```bash
@@ -191,7 +203,9 @@ herdr pane run <pane_id> <command>
 
 `<key>` は Herdr のキーコンボ構文を使います: `a` のような通常の印字可能キー、`enter`、`tab`、`esc`、`backspace`、`left`、`right`、`up`、`down` のような特殊キー、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` のような修飾キーコード、`f1` のようなファンクションキー、そして `minus`、`plus`、`backtick` のような名前付き記号です。レガシーな `C-c` と `c-c` は `ctrl+c` のエイリアスとして受け付けられます。
 
-`pane run` はテキストと Enter をアトミックに送信します。コマンドには `send-text` + `send-keys Enter` よりこちらを使ってください。
+標準表記は `esc` ですが、`escape` も使えます。
+
+`pane run` は現在の bracketed paste モードを尊重し、テキストと Enter をアトミックに送信します。コマンドには `send-text` + `send-keys Enter` よりこちらを使ってください。個別の送信操作は低レベルのままで、コマンドを送信しません。
 
 カスタムフックからエージェント状態を報告する:
 
@@ -204,8 +218,23 @@ herdr pane report-agent <pane_id> \
   [--seq N] \
   [--agent-session-id ID] \
   [--agent-session-path PATH]
+
+herdr pane report-agent-session <pane_id> \
+  --source ID \
+  --agent LABEL \
+  [--seq N] \
+  [--agent-session-id ID] \
+  [--agent-session-path PATH] \
+  [--session-start-source SOURCE]
+
+herdr pane release-agent <pane_id> \
+  --source ID \
+  --agent LABEL \
+  [--seq N]
 ```
 
+`report-agent-session` はライフサイクル状態を報告せずにネイティブセッション識別子を更新します。`release-agent` は、そのエージェントプロセスが終了したときに、そのソースのライフサイクル権限を終了します。
+
 公式インテグレーションがネイティブセッション参照を報告している場合、`pane get`、`pane list`、`agent get`、`agent list` は読み取り専用の `agent_session` オブジェクトを含みます。ネイティブセッション参照が保存されていない場合、このフィールドは省略されます。
 
 これらのコマンドは、ペインを制御しているフォアグラウンドプロセスの cwd を解決できる場合に `foreground_cwd` を含みます。既存の `cwd` フィールドは、ラベルと follow-cwd 挙動に使われるペイン/ワークスペースの cwd のままです。
@@ -237,23 +266,34 @@ herdr pane report-metadata <pane_id> \
 
 ## エージェント
 
+ペインとエージェントの使い分けや一連の連携例は、[エージェント自動化](/ja/docs/agent-automation/) を参照してください。
+
 ```bash
 herdr agent list
 herdr agent get <target>
 herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
-herdr agent send <target> <text>
+herdr agent send-keys <target> <key> [key ...]
+herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
 herdr agent rename <target> <name>|--clear
 herdr agent focus <target>
-herdr agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
+herdr agent wait <target> [--until STATUS]... [--timeout MS]
 herdr agent attach <target> [--takeover]
-herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
+herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
 herdr agent explain <target> [--json|--verbose]
 herdr agent explain --file PATH --agent LABEL [--json|--verbose]
 ```
 
-エージェントターゲットには、ターミナル ID、一意なエージェント名、検出または報告されたエージェントラベル、レガシーなペイン ID が使えます。名前とラベルはエージェントのアイデンティティです。ターミナル ID とレガシーペイン ID は低レベルな逃げ道です。
+エージェントターゲットは、一意なライブエージェント名、または現在そのエージェントをホストしているペイン ID です。ターミナル ID とエージェント kind のラベルだけでは指定できません。`agent start` で起動するエージェントには名前が必須で、手動で起動したエージェントは名前なしのままペイン ID で指定します。
+
+`agent start` は既存の利用可能なシェルペインを起動対象にします。対話シェル自身がフォアグラウンドを所有し、フォアグラウンドのコマンド、エディタ、エージェントが動いていない必要があります。トポロジーは別に作成します。名前はライブエージェント間で一意で、`[a-z][a-z0-9_-]{0,31}` に一致する必要があります。対応する kind は `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`maki` です。名前は現在のペイン占有者に属し、そのエージェントの終了、release、置換で消えます。一時的に検出できないだけでは消えません。
 
-`agent read` は解決されたターミナルストリームを読みます。`agent send` はそのストリームにリテラルのテキストを書き込みます。`agent get`、`agent focus`、`agent wait`、`agent attach` は、解決されたターミナルがエージェントのアイデンティティを持つことを要求します。`agent rename` はそのアイデンティティを割り当てられます。
+start は、期待したエージェントが同じターミナルを所有し、対話入力の準備ができてから返ります。デフォルトの起動タイムアウトは 30000 ミリ秒で、明示する値は 3000 より大きく 300000 以下でなければなりません。
+
+`agent prompt` は現在の bracketed paste モードを尊重し、working 中でもテキストとエンコード済み Enter をアトミックに送信します。`--wait` を使う場合、non-working 状態から送信したプロンプトは 5 秒以内に観測可能なライフサイクル変化を起こす必要があり、変化がなければ Herdr は `agent_prompt_stalled` を返します。呼び出し側のタイムアウトが 5 秒以下なら、通常の `timeout` エラーを維持します。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。すでに working の場合、進行中ターンの完了が待機を満たすことがあります。`--until` は一致状態を絞り込み、`--wait` なしでは拒否されます。単独の `agent wait` は現在の状態が一致すれば即座に返ります。どちらもデフォルトは `idle`、`done`、`blocked` です。
+
+`idle` は入力待ちで、そのタブがフォーカス中の Herdr UI ですでに表示済みの状態です。`done` は同じ基礎的な idle 状態ですが、表示していないバックグラウンド作業が完了したときに使われます。そのタブをフォーカスするか `pane focus` / `agent focus` で対象にすると表示済みになりますが、CLI で読み取るだけでは変わりません。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するものの確実に分類できない状態で、作業の成功を意味しません。
+
+`agent send-keys` は `enter`、`up`、`esc`、`ctrl+c` などの論理キーを送ります。Herdr は 1 バイトも書き込む前に全キーを検証します。`agent read` は解決されたターミナルストリームを読み、`agent rename` は検出済みエージェントに名前を付けます。
 
 `agent explain` は、スクリーン検出が使うのと同じ下部バッファの検出スナップショットの分類を実行中のサーバーに依頼します。そのためライブの出力はサーバーのアクティブなマニフェストキャッシュを反映します。これは `agent.explain` ソケットメソッドを使うので、Herdr のアップグレード後にライブ explain を使う前に、サーバーを再起動するか更新済みサーバーへハンドオフしてください。保存済みフィクスチャをローカルで説明するには `--file PATH --agent LABEL` を使います。デフォルトの出力には、エージェント、最終状態、マニフェストのソースとバージョン、リージョンの証拠付きでマッチしたルール、そしてフォールバック・スキップ・警告の理由が表示されます。`--verbose` を付けると、可視の証拠フラグ、キャッシュされたリモートバージョン、ローカルオーバーライドのシャドーイング、リモート更新状況、マッチャーとリージョンの証拠付きの評価済みルール全リストが表示されます。issue の報告やテストには `--json` を付けてください。
 
@@ -270,21 +310,19 @@ herdr terminal title clear
 ダイレクトアタッチからは `ctrl+b q` でデタッチします。リテラルの `ctrl+b` は `ctrl+b ctrl+b` で送ります。
 `terminal title clear` は Herdr のデフォルトの外側ターミナルウィンドウタイトルを復元します。
 
-## Wait
+## 出力待機
 
 ペインの出力を待つ:
 
 ```bash
-herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]
+herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]
 ```
 
-ペインのエージェント状態を待つ:
+通常のコマンドやサーバーには `pane wait-output` を使います。コーディングエージェントには `agent wait` を使います。
 
-```bash
-herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]
-```
+`pane wait-output` は選択したスナップショットを最初にすぐ検索するため、すでに存在する出力も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更できます。`--match` は 1 行内のリテラル部分文字列を検索し、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。
 
-通常のコマンドやサーバーには `wait output` を使います。コーディングエージェントには `wait agent-status` を使います。
+`pane wait-output`、`agent wait`、`agent prompt --wait` は、`--timeout` を省略すると無期限に待ちます。タイムアウトまたはサーバーエラーは JSON として stderr に出力され、終了コード 1 になります。CLI 使用法のエラーは終了コード 2 です。
 
 ## インテグレーション
 
@@ -389,6 +427,8 @@ herdr plugin pane close <pane_id>
 | `recent-unwrapped` | ソフト折り返しなしの直近のスクロールバック。ログに最適。 |
 | `detection` | エージェントのスクリーン検出が使う下部バッファのスナップショット。 |
 
+この表は読み取り時の意味です。`pane wait-output` に限り、`recent` と `recent-unwrapped` はどちらも recent の折り返し前スナップショットを検索し、デフォルト表記は `recent` です。
+
 ## 環境変数
 
 | 変数 | 目的 |
diff --git a/website/src/content/docs/ja/configuration.mdx b/website/src/content/docs/ja/configuration.mdx
index 4a875220..0eba298d 100644
--- a/website/src/content/docs/ja/configuration.mdx
+++ b/website/src/content/docs/ja/configuration.mdx
@@ -295,6 +295,18 @@ Space の行では、次の組み込みトークンを使えます:
 
 トークンは設定された順序で描画されます。Herdr は通常、隣接する値を ` · ` で区切り、`state_icon` の後には空白を 1 つ入れます。値がない場合、その値と区切りは表示されません。すべてのトークンに値がない行は表示されません。各レイアウトは最大 16 行、各行は最大 16 トークンです。
 
+トークンエントリにはインラインのスタイルテーブルも使えます:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", { token = "workspace", bold = false }, "tab"],
+  [{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }],
+]
+```
+
+`fg` は厳密な `#RGB` または `#RRGGBB`、`bold` と `dim` は真偽値です。省略したフィールドはコンテキストのスタイルを保持し、明示的な `false` はその修飾を解除します。スタイルは 1 つの出現箇所だけに適用されます。`fg` を指定した `git_status` では、既定の緑/赤ではなく ahead と behind の両方が同じ色になります。区切りと行の背景は変更されません。
+
 `row_gap` は、Agent パネルと Space パネルごとに、エントリ間の空白行数を指定します。デフォルトは `0` で、エントリを詰めて表示します。以前の間隔に戻すには `1` に設定します。`rows` で定義したコンテンツ行の間隔には影響しません。連続するインデントされた worktree の子は、1 つの Space グループとして詰めて表示されます。
 
 既知のエージェントについて Agent の完全なレイアウトを上書きするには、`rows_by_agent` を使います:
@@ -334,7 +346,9 @@ herdr pane report-metadata <pane_id> \
   --token summary="reviewing authentication"
 ```
 
-カスタム Space トークンには、同じ方法で `herdr workspace report-metadata` を使います。報告されていないカスタムトークンは表示されません。メタデータの報告元が提供できるのは値だけで、行やスタイルは選べません。値のクリア、シーケンス、有効期限については、[CLI リファレンス: report metadata](/docs/cli-reference/#panes)を参照してください。
+カスタム Space トークンには、同じ方法で `herdr workspace report-metadata` を使います。報告されていないカスタムトークンは表示されません。
+
+メタデータの報告元が提供できるのは値だけで、スタイルはローカルのサイドバー設定で管理します。上限、クリア、シーケンス、有効期限については、[CLI リファレンス: report metadata](/docs/cli-reference/#panes)を参照してください。
 
 サイドバーの行設定は、展開されたデスクトップサイドバーにだけ適用されます。折りたたみ表示とモバイル表示はコンパクトなレイアウトを保ちます。
 
diff --git a/website/src/content/docs/ja/integrations.mdx b/website/src/content/docs/ja/integrations.mdx
index de80ab39..fe4e41b1 100644
--- a/website/src/content/docs/ja/integrations.mdx
+++ b/website/src/content/docs/ja/integrations.mdx
@@ -76,7 +76,7 @@ Herdr はバンドルされた拡張を次の場所に書き込みます:
 ~/.pi/agent/extensions/herdr-agent-state.ts
 ```
 
-`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts` に書き込みます。extensions ディレクトリはあらかじめ存在している必要があります。アンインストールはその拡張ファイルだけを削除します。
+`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts` に書き込みます。Pi の agent ディレクトリが存在する場合、Herdr は extensions ディレクトリを作成します。アンインストールはその拡張ファイルだけを削除します。
 
 ## OMP
 
@@ -92,7 +92,7 @@ Herdr はバンドルされた拡張を次の場所に書き込みます:
 ~/.omp/agent/extensions/herdr-omp-agent-state.ts
 ```
 
-`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts` に書き込みます。extensions ディレクトリはあらかじめ存在している必要があります。アンインストールはその拡張ファイルだけを削除します。
+`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts` に書き込みます。OMP の agent ディレクトリが存在する場合、Herdr は extensions ディレクトリを作成します。アンインストールはその拡張ファイルだけを削除します。
 
 OMP インテグレーションは、Herdr のソケット API を通じてエージェントラベル `omp`、ライフサイクル状態、ネイティブセッション識別を報告します。`omp` 実行ファイルのネイティブプロセス検出は不要で、Herdr はサーバー再起動後に `omp --resume=<session>` で OMP ペインを resume できます。
 
diff --git a/website/src/content/docs/ja/plugins.mdx b/website/src/content/docs/ja/plugins.mdx
index 426c8e62..db5342cd 100644
--- a/website/src/content/docs/ja/plugins.mdx
+++ b/website/src/content/docs/ja/plugins.mdx
@@ -74,6 +74,9 @@ command = ["npm", "ci"]
 command = ["npm", "run", "build"]
 platforms = ["linux", "macos"]
 
+[[startup]]
+command = ["node", "dist/restore.js"]
+
 [[actions]]
 id = "apply"
 title = "Apply layout"
@@ -110,10 +113,10 @@ ASCII の英字、数字、コロン、アンダースコア、ハイフンが�
 一意な名前が必要なとき、Herdr はアクション id を `plugin.id.action` の形に修飾します。
 
 プラグインが動作する場所は `platforms = ["linux", "macos", "windows"]` で宣言します。
-ビルドコマンド、アクション、イベントフック、ペイン、リンクハンドラーも独自の
-`platforms` を宣言でき、項目レベルの platforms はトップレベルのリストを
-上書きします。トップレベルの `platforms` がないローカルプラグインは警告付きで
-リンクされます。
+ビルドコマンド、スタートアップフック、アクション、イベントフック、ペイン、
+リンクハンドラーも独自の `platforms` を宣言でき、項目レベルの platforms は
+トップレベルのリストを上書きします。トップレベルの `platforms` がないローカル
+プラグインは警告付きでリンクされます。
 
 `command` の値は argv 配列です。Herdr はこれをシェル経由で実行しないため、
 コマンド自身がシェルを起動しない限りシェル展開はありません。言語固有の挙動は
@@ -192,6 +195,11 @@ herdr plugin log list --plugin example.layout
 ビルドコマンドを実行し、チェックアウトを Herdr 管理のプラグインデータの下に保存して
 登録します。非対話的なインストールには `--yes` を使ってください。GitHub 管理の
 プラグインを再インストールすると、その管理チェックアウトが置き換えられます。
+インストール済みおよびリンク済みのプラグインと、その有効・無効の状態は現在の
+ユーザー全体で共有され、すべての Herdr セッションから利用できます。Herdr サーバーが
+動作していないときでも `plugin install` と `plugin link` で登録できます。
+Herdr 0.7.3 の名前付きセッションだけにインストールしたプラグインは、再度 install
+または link してください。既存のプラグイン設定と状態はそのまま残ります。
 ローカルにリンクされたプラグインへの上書きインストールは拒否されます。先に
 ローカルプラグインを unlink または uninstall してください。`plugin install` と
 `plugin link` はプラグインの設定・状態ディレクトリを作成し、
@@ -226,6 +234,23 @@ Herdr のソケット環境変数は受け取りません。プラグインの�
 `bun`、`lua` といった必要なシステムツールをドキュメントに書いてください。Herdr は
 ビルドの失敗を報告しますが、足りないツールチェーンをインストールすることはありません。
 
+## スタートアップフック
+
+`[[startup]]` コマンドは、Herdr がセッションを復元し、API ソケットの準備が整った後に、
+有効なプラグインごとに一度実行されます。ライブハンドオフで新しいサーバーが引き継いだ
+ときにも再実行されますが、クライアントの接続、設定の再読み込み、プラグインの link や
+enable では実行されません。Herdr はこれらを非同期で開始し、完了を通常のプラグイン
+コマンドログに記録します。スタートアップの失敗でサーバーが停止することはありません。
+
+スタートアップフックは一度限りの初期化コマンドであり、監視されるデーモンではありません。
+フックはプラグインが所有する状態を復元し、必要な Herdr API を呼び出して終了してください。
+たとえば宣言型の Agent ビューを `HERDR_PLUGIN_STATE_DIR` に保存し、スタートアップフックで
+読み込んで再適用できます。
+
+スタートアップフックは通常のランタイムプラグイン環境と
+`HERDR_PLUGIN_EVENT=startup` を受け取ります。インストールプレビューには、自動実行される
+コードを確認できるよう、すべてのスタートアップコマンドが表示されます。
+
 ## コマンドと環境
 
 ランタイムコマンドは、プラグインディレクトリを作業ディレクトリとして実行されます。
@@ -233,8 +258,9 @@ Herdr は `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV=1`、
 `HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、
 `HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_CONTEXT_JSON`、そして利用可能なら
 `HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID` を注入します。アクション
-コマンドは加えて `HERDR_PLUGIN_ACTION_ID` を受け取ります。イベントフックは
-`HERDR_PLUGIN_EVENT` と `HERDR_PLUGIN_EVENT_JSON` を、ペインコマンドは
+コマンドは加えて `HERDR_PLUGIN_ACTION_ID` を受け取ります。スタートアップフックと
+イベントフックは `HERDR_PLUGIN_EVENT`（スタートアップフックでは `startup`）を受け取り、
+イベントフックはさらに `HERDR_PLUGIN_EVENT_JSON` を、ペインコマンドは
 `HERDR_PLUGIN_ENTRYPOINT_ID` を受け取ります。
 
 `HERDR_PLUGIN_ROOT` は、インストールまたはリンクされたプラグインディレクトリです。
diff --git a/website/src/content/docs/ja/session-state.mdx b/website/src/content/docs/ja/session-state.mdx
index 6b349159..2567fc3f 100644
--- a/website/src/content/docs/ja/session-state.mdx
+++ b/website/src/content/docs/ja/session-state.mdx
@@ -93,6 +93,8 @@ Herdr が resume するのは、現行の公式 Herdr インテグレーショ�
 
 これはスナップショット復元、ペイン履歴リプレイ、エージェントネイティブのセッション復元とは異なります。ハンドオフは現在のプロセスを生かし続けようとします。他の経路は、古いサーバーが停止した後に状態を再構築します。
 
+ハンドオフが保護するのは、ペインの PTY とプロセス、エージェントの識別情報と永続メタデータ、交換後のサーバーに必要なプラグイン/セッション状態など、サーバーが所有する長寿命のセッション状態です。交換境界をまたぐ一時的な協調状態は保持しません。処理中の CLI/API リクエスト、wait、購読ストリーム、クライアントソケット、ペイン間メッセージは中断される可能性があるため、クライアントは再接続して再試行してください。
+
 ライブハンドオフは実験的機能で、オプトインです:
 
 ```bash
diff --git a/website/src/content/docs/ja/socket-api.mdx b/website/src/content/docs/ja/socket-api.mdx
index 975336ca..8995dbae 100644
--- a/website/src/content/docs/ja/socket-api.mdx
+++ b/website/src/content/docs/ja/socket-api.mdx
@@ -36,7 +36,7 @@ herdr api schema --output herdr-api.schema.json
 - ワークスペースの作成、一覧、フォーカス、名前変更、クローズ
 - タブの作成、一覧、フォーカス、名前変更、クローズ
 - ペインの一覧、調査、分割、入れ替え、フォーカス、リサイズ、名前変更、読み取り、クローズ、入力送信
-- CLI ヘルパーを通じたエージェントの一覧、調査、読み取り、送信、名前変更、フォーカス、起動、アタッチ
+- CLI ヘルパーを通じたエージェントの一覧、調査、読み取り、プロンプト、待機、名前変更、フォーカス、起動、アタッチ
 - フックやプラグインからのカスタムエージェント状態の報告
 - イベントの購読と、出力や状態変化の待機
 - 組み込みインテグレーションのインストールとアンインストール
@@ -77,7 +77,7 @@ herdr pane split w1:p1 --direction right --ratio 0.333
 エージェントを待つ:
 
 ```bash
-herdr wait agent-status w1:p1 --status done
+herdr agent wait w1:p1 --until done
 ```
 
 ペインの出力を読む:
@@ -102,12 +102,12 @@ herdr pane read w1:p2 --source recent --lines 50
 | ペイン | `pane.split`、`pane.swap`、`pane.move`、`pane.zoom`、`pane.layout`、`pane.process_info`、`pane.neighbor`、`pane.edges`、`pane.focus_direction`、`pane.resize`、`pane.list`、`pane.current`、`pane.get`、`pane.rename`、`pane.send_text`、`pane.send_keys`、`pane.send_input`、`pane.read`、`pane.graphics.info`、`pane.graphics.set`、`pane.graphics.clear`、`pane.graphics.stream`、`pane.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` |
 | ポップアップ | `popup.close` |
 | レイアウト | `layout.export`、`layout.apply`、`layout.set_split_ratio` |
-| エージェント | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send`、`agent.rename`、`agent.focus`、`agent.start` |
+| エージェント | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send_keys`、`agent.prompt`、`agent.wait`、`agent.rename`、`agent.focus`、`agent.start` |
 | イベント | `events.subscribe`、`events.wait` |
 | インテグレーション | `integration.install`、`integration.uninstall` |
 | プラグイン | `plugin.link`、`plugin.list`、`plugin.unlink`、`plugin.enable`、`plugin.disable`、`plugin.action.list`、`plugin.action.invoke`、`plugin.log.list`、`plugin.pane.open`、`plugin.pane.focus`、`plugin.pane.close` |
 
-一部の CLI コマンドは、これらのメソッドの便利ラッパーです。たとえば `herdr agent wait` は、エージェントターゲットを解決してからペインのエージェント状態イベントを購読します。
+`agent.wait` はサーバー所有でイベント駆動です。解決したペイン占有者に固定されるため、置換されたエージェントが待機を満たすことはありません。`agent.prompt` は `until` と `timeout_ms` を持つ省略可能な `wait` オブジェクトを受け付けます。これにより、プロンプト送信と待機開始を 1 つのリクエストで行い、別々の呼び出し間の競合を避けられます。
 
 `session.snapshot` は、独自のローカルランタイムキャッシュを持つクライアント向けに、一度限りのブートストラップスナップショットを返します。レスポンスには、バージョン/プロトコルメタデータ、フォーカス中のワークスペース/タブ/ペイン id、ワークスペース、タブ、ペイン、タブレイアウト、エージェントの各レコードが含まれます。これは購読ではありません。取得後はリソースイベントを購読し、そのイベントでローカルキャッシュを更新してください。再接続後やキャッシュが古い可能性がある場合は、`session.snapshot` を再度呼び出します。ワークスペースレコードには、関連付けられた worktree の出自情報も含まれます。リポジトリ全体の worktree 検出には引き続き `worktree.list` を使います。
 
@@ -297,6 +297,80 @@ Worktree メソッドは Git チェックアウトを Herdr ワークスペー�
 
 worktree コマンドはライフサイクルイベントも発行します。`worktree.create` は `workspace.created`、`tab.created`、`pane.created`、`worktree.created` を発行します。`worktree.open` は `worktree.opened` を発行し、新しい Herdr ワークスペースを開いた場合はワークスペース/タブ/ペインの作成イベントも発行します。`worktree.remove` は `worktree.removed` を発行し、リンクされたワークスペースがまだ開いている場合は `workspace.closed` も発行します。
 
+## エージェントビューのクエリ
+
+`agent.view.set` は、組み込みの Agents ビューに一つの一時的な宣言型プロジェクションを
+設定します。エージェントの情報や現在の UI コンテキストが変わるたびに再評価されます。
+展開・折りたたみサイドバー、モバイルの Agents リスト、マウスターゲット、番号付き
+フォーカス、前後のエージェントへの移動順を制御します。`agent.list`、通知、検出、
+グローバルな要対応件数は変更しません。
+
+現在表示中の Space にいるエージェント、または別の場所で対応が必要なエージェントを
+表示し、要対応度と直近の状態遷移で並べ替える例です:
+
+```json
+{
+  "id": "view_set",
+  "method": "agent.view.set",
+  "params": {
+    "source": "plugin:example.agent-views",
+    "label": "focus",
+    "filter": {
+      "op": "any",
+      "filters": [
+        {
+          "op": "eq",
+          "field": "workspace_id",
+          "value": {"context": "current_workspace_id"}
+        },
+        {
+          "op": "in",
+          "field": "status",
+          "values": ["blocked", "done"]
+        }
+      ]
+    },
+    "sort": [
+      {"field": "attention", "order": "desc"},
+      {"field": "state_change_seq", "order": "desc"}
+    ]
+  }
+}
+```
+
+フィルターノードの `op` には `all`、`any`、`not`、`eq`、`in`、`exists` を使います。
+組み込みフィールドは `status`、`workspace_id`、`tab_id`、`pane_id`、`agent`、
+`seen`、`state_change_seq` です。プラグインが報告したペインメタデータを絞り込むには、
+フィールドとして `{"token":"name"}` を使います。値には文字列、真偽値、符号なし整数、
+またはコンテキストオブジェクトを指定できます。コンテキスト値は
+`current_workspace_id` と `current_tab_id` で、対応する ID フィールドとの比較にだけ
+使えます。有効な status は `idle`、`working`、`blocked`、`done`、`unknown` です。
+`done` は idle かつ未確認の状態を表します。
+
+ソートフィールドは `workspace_order`、`tab_order`、`pane_order`、`attention`、
+`status`、`agent`、`seen`、`state_change_seq`、または `{"token":"name"}` です。
+ソートは安定しており、指定順に評価され、`asc` または `desc` を受け付けます。値がない
+項目は値がある項目の後に残ります。`sort` を省略すると既存の
+`ui.agent_panel_sort` ポリシーが有効です。カスタムソートは設定を書き換えず、一時的に
+そのポリシーを置き換えます。
+
+`source` は所有者を識別します。プラグインは `plugin:<HERDR_PLUGIN_ID>` を使います。
+所有元のプラグインが存在しないか無効な場合、Herdr は設定を拒否します。他の呼び出し元は
+独自の非 `plugin:` source を使えます。設定に成功すると以前のビューはアトミックに
+置き換えられます。ビューは clear または置換されるか、所有プラグインが disable、unlink、
+uninstall されるか、サーバーが終了するまで有効です。永続的な動作が必要なプラグインは、
+クエリを `HERDR_PLUGIN_STATE_DIR` に保存し、`[[startup]]` フックから再適用してください。
+
+無条件で clear するか、指定した source がまだ所有している場合だけ clear できます:
+
+```json
+{"id":"view_clear","method":"agent.view.clear","params":{}}
+{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}
+```
+
+source が一致しない場合、アクティブなビューは変わりません。set と clear のレスポンスは
+`type: "agent_view"` で、`active`、`source`、任意の `label` を報告します。
+
 ## プラグイン API
 
 プラグイン API は、実行可能なワークフローツールのための初期のホスト面です。プラグインは `herdr-plugin.toml` マニフェストを持つパッケージです。マニフェストは、共有可能なアクション、イベントフック、ターミナルペインのエントリーポイント、リンクハンドラーを宣言します。アクションとペインはマニフェスト専用です。ランタイムでのアクション登録とランタイムでの argv ペイン作成は v1 の範囲外です。
@@ -589,8 +663,8 @@ herdr pane read w1:p1 --source detection
 エージェントとスクリプトの協調には wait を使います。
 
 ```bash
-herdr wait agent-status w1:p1 --status done
-herdr wait agent-status w1:p1 --status blocked
+herdr agent wait w1:p1 --until done
+herdr agent wait w1:p1 --until blocked
 ```
 
 エージェントの wait は、任意のコマンドの完了ではなく意味的な状態を観測します。