Orchestrate

---
name: orchestrate
description: Herdr で子エージェントを立ち上げて作業を委任・並列実行するときに使う。ユーザーが Herdr での委任を明示した場合に限る — 単に委任や並列化が有効そうというだけでは使わない (Agent ツールで足りる)。
---

# Herdr でのオーケストレーション

あなたはこれから Herdr で子エージェントを立ち上げ、作業を委任する親エージェント (オーケストレーター) になる。

開始前に Skill ツールで `herdr` (本体) と `herdr:gotcha` を呼ぶ。

herdr が担うのは子の**起動**まで — `tab create` → `agent start` → `/herdr:delegate-receive <BRIEF_PATH>` の 1 回キック — と、`blocked` になっていないかの生存監視、そして後始末だけ。起動後のやり取り (ハンドシェイク・中間報告・質問・最終報告・次の指示) はすべて SendMessage で行う。SendMessage はツールの構造化パラメータとして届きシェルの解釈を経ないため、`herdr agent prompt` / `pane run` で自由記述テキストを渡すときの罠 (`herdr:gotcha` 参照) がそもそも起こらない。委任フロー特有の罠は本スキル末尾の「委任フロー特有の罠」にまとめてある。

## 親を起こすのは、子からの SendMessage と watchdog の 2 つ

指示を送ったらターンを終える。子が SendMessage であなたへ送ったメッセージの通知で、あなたが再起動される。子が `blocked` に落ちて SendMessage を送れなくなったときは、手順 6 で仕掛ける **watchdog** の終了があなたを起こす。以降は「起こされる → 対応する → またターンを終える」を、最終報告が来るまで繰り返す。

フォアグラウンドで `herdr agent wait` を実行すると、ブロックしている間は中間報告を処理できない。watchdog はバックグラウンドで走らせ (手順 6)、ターンは終える。

## 手順

1. タスクを分割するか判断する。

   状態を共有せず、互いの結果を必要としない独立したサブタスクがあるなら、子ごとに分割して並列で起動する。逐次依存がある作業 (調査 → その結果を使う実装、など) は 1 人の子にまとめて任せる。

2. 自分の識別子と workspace ID を控える。

   ```
   ListAgents  # 冒頭の "This session is <name> [...]" が自分の SendMessage 宛先
   ```

   ```bash
   herdr pane current --current # .result.pane.workspace_id
   ```

   自分の識別子は手順 3 の依頼文書に書き、子から最初のハンドシェイクを受け取る宛先になる。workspace ID は手順 4 で子のタブを作る先になる。`HERDR_WORKSPACE_ID` ではなくこの応答から取る (`pane move` されていると移動前のまま古くなるため)。

3. 依頼文書を書き出す。

   子ごとの使い捨てなので、置き場所はあなたのスクラッチパッドディレクトリ (システムプロンプトで指定されているもの)、ファイル名は `delegation-<子の名前>.md`。

   子はあなたの文脈を一切共有していない。次を省略せず埋めること:

   | 項目 | 内容 |
   |---|---|
   | タスク | 何をするか |
   | 完了の定義 | 子が自分で判定できる検証可能な条件 (テストが通る、diff が揃っている等) |
   | 作業ディレクトリ | 絶対パス。ブランチを指定するならそれも |
   | あなたの名前 | 手順 4 で `agent start` に渡す名前。子が自分自身を名乗るときに使う |
   | 親の識別子 | 手順 2 で控えた ListAgents 上の自分の名前。子が SendMessage の宛先に使う |
   | 中間報告のタイミング | 最低 1 回は挟む (下記) |
   | 参照先 | ファイルは絶対パスで、URL はそのまま |
   | 推奨スキル | タスクに関係するスキルがあれば挙げる |

   中間報告は作業の切れ目に必ず挟む。e.g. 調査と実装を任せるなら (1) 調査 → (2) 中間報告 → (3) 実装 → (4) 最終報告。

   **文面は淡々とした手順として書く。** 自己弁明的な一文がなぜ逆効果なのかは末尾の「自己承認文言はかえって警戒を招く」参照。

4. 子を起動して引き継がせる。

   **別タブ**で起動する。画面幅をフルに使わせることで、`blocked` かどうかを一目で判別できる状態を保つ。

   子が複数いる場合、先に全員分のタブを作りエージェントを起動してから、キックの送信 (`agent prompt --wait`) を子ごとに行う。キックの送信はブロックするので、先に全員を起動しておかないと後発の子ほど着手が遅れる。

   ```bash
   herdr tab create --workspace <手順 2 の workspace ID> --cwd "$PWD" --no-focus # .result.tab, .result.root_pane
   herdr agent start <name> --kind claude --pane <root_pane の pane_id>
   ```

   `agent start` は失敗しうる。`agent_pane_busy` (シェルがまだ利用可能でない) と `agent_not_ready` (エージェントが起動時ダイアログで止まっている) の 2 通りがあり、対処が違う。どちらも `herdr:gotcha` を参照。

   タブ ID (`.result.tab.tab_id`) は名前とセットで**台帳**にし、手順 9 の後始末まで持つ。子が複数いる場合、この対応が崩れると後始末で違うタブを閉じたり、閉じ忘れたりする。

   **台帳には「ListAgents 上の名前」と「最終報告を受け取ったか」も持たせる。** 前者は手順 7 のハンドシェイクで埋まる (それまでは空欄)。親は割り込みのたびに新しいターンを始めるので、両方を記憶に頼ると割れる。なぜ `agent start` の名前だけでは足りないのかは末尾の「herdr の名前と ListAgents の名前は別物」参照。

   全員起動できたら、子ごとにキックを送る:

   ```bash
   herdr agent prompt <name> "/herdr:delegate-receive <対応する依頼文書のパス>" --wait --timeout 15000
   ```

   この prompt 自体は自由記述テキストではなく固定形式 (コマンド名 + パス) なので、ダブルクォート直書きで構わない。

   **手順 4 は全員が `working` になったら完了。** `agent prompt --wait` の終了コードでは判定できない。**キックが着弾して子が働き出すと `--wait` は `timeout` エラー (exit 1) で返る** — `--wait` は settled state (`idle` / `done` / `blocked`) を待つ仕様なので、これは正常な経路であって送信の失敗ではない。**exit 1 を失敗と読んで再送すると二重送信になる。** 終了コードではなく状態で裏を取る:

   ```bash
   herdr agent get <name> # .result.agent.agent_status
   ```

   | 状態 | すること |
   |---|---|
   | `working` | キックが着弾した。次の子へ。全員 `working` なら手順 5 へ |
   | `idle` / `done` | 短いタスクなら着弾して即完了した可能性がある。`herdr agent read <name> --source visible` で作業の跡を見て割る |
   | `blocked` | 最初のツールで権限ゲートに当たった。`herdr agent read <name> --source visible` で中身を読み、`herdr:gotcha` の規律に従って対処してから進む |

5. 子ごとに watchdog を仕掛ける。

   **全員が `working` であることを手順 4 で確認してから仕掛ける。** watchdog は子が `blocked` になるのを待つだけで、キックが届いていない子と黙々と働いている子を区別しない。`working` を確認せずに張ると、着手すらしていない子をチェックイン間隔いっぱい見張ることになる。

   Bash ツールの `run_in_background: true` で、子 1 人につき 1 本:

   ```bash
   herdr agent wait <子の名前> --until blocked --timeout 600000
   ```

   `--timeout` は締切ではなく**チェックイン間隔**として使う。子のタスクの粒度で決める。10 分なら 1 時間の委任で 6 回の空振りで済む。これで親が起きる経路が出揃う。どの起こされ方にも意味がある (手順 7)。

   **ここを飛ばしてターンを終えると、後から仕掛ける機会は無い。** 親はもう動いていないので「あとで」が存在しない。

   **手順 5 は、子の人数と同じ本数の watchdog がバックグラウンドで走っていれば完了。**

6. ターンを終えて、起こされるのを待つ。

   終える前に、自分のペインの承認ダイアログと実行中のコマンドを片付けておく。放置しても子の SendMessage は消えないが、気づくのが遅れる (詳細は末尾の「blocked の相手への SendMessage 配送」参照)。

   そのうえで、**子の名前と「起こされるのを待っている」ことをユーザーへ伝える。**

   子が複数いる場合、それぞれ別のタイミングで起こされる。全員分をまとめて待つ必要はない。1 件処理してターンを終えれば、次でまた起こされる。

7. 起こされたら、どちらの経路かで分岐する。

   `herdr:gotcha` がコンテキストから落ちていれば、Skill ツールで呼び直してから対応する。

   **子の SendMessage で起きた場合** — タグで分岐する (語彙は末尾の「SendMessage で使うタグ」)。タグが付いていなければハンドシェイクである。

   - `ハンドシェイク` → 送信元 (`from`) をその子の台帳の行に記録する。以降、その子への送信はこの宛先を使う
   - `中間報告` → 確認して次の指示を送り、手順 6 に戻る
   - `質問` → 回答を送り、手順 6 に戻る
   - `最終報告` → 完了の定義に照らして中身を検分する。満たしていなければ**差し戻せる** — 具体的な確認事項を添えて SendMessage で送り返せば、子は自発的に調査を継続し「最終報告 (確定版)」として再送してくる。`herdr agent prompt` の再キックは要らない。満たしていれば台帳に記録する。全員分揃ったら手順 8 へ。まだの子が残っていれば手順 6 に戻って待つ

   **完了の定義を満たした最終報告に、それ以上の返信をしない。** お礼や確認の一言でも、子は `done` から一時的に `working` へ戻って律儀に対応しようとし、無駄な空振りになる。返すべきなのは差し戻し (上記) だけ。

   子へ送る文面は SendMessage でそのまま送ってよい (`herdr:gotcha` 参照)。**送る前に `herdr agent get <name>` で状態を確認する。** SendMessage 自体は `blocked` の相手にも届きうるが、**報告と実状態の食い違いをここで拾う** — 子が「最終報告」と送ってきても、その後の検証作業で権限ゲートに当たって `blocked` になっている場合がある。`blocked` を見つけたら、下の watchdog の場合と同じ手順を踏む。

   この経路で起きたとき、その子の watchdog はまだ走っている。張り直す必要はない。

   **watchdog の終了で起きた場合** — 終わり方で意味が違う。判別は watchdog の出力を読んで行う (`timeout` と `agent_not_running` はどちらもエラーで返るので、終了コードだけでは割れない)。

   | 終わり方 | 意味 |
   |---|---|
   | `blocked` のペイロードで返った | 権限ゲートに当たった、または偽陽性 |
   | `agent_not_running` | 子のペインが消えた。委任の失敗として扱い、ユーザーへ報告する |
   | `timeout` | 何も起きていない、あるいは `blocked` にならない形で人間待ちに入っている |

   `blocked` と `timeout` では、まず実状態を読む。`agent wait` は子が内部で起こしたサブエージェントやテストの終了でも早期に返る、という報告がある ([#2851](https://github.com/herdrdev/herdr/issues/2851))。**`blocked` のペイロードで返っても子が本当に `blocked` とは限らない。**

   ```bash
   herdr agent get <name>                                        # 実状態を確認する
   herdr agent read <name> --source visible                      # 何を訊かれているか、報告を出しそびれていないか読む
   herdr agent explain <name> --verbose                          # 状態が疑わしいときの一次診断
   ```

   実状態が `blocked` なら、読んだ中身で `herdr:gotcha` の規律に従って切り分ける。

   **`esc` (`herdr agent send-keys <name> esc`) で却下したら、それで終わらせない。** 却下したのが親であることと次にやるべきことを、続けて SendMessage で送る。

   対応が済んだら **`agent get` で `blocked` を抜けたことを確認してから watchdog を張り直し** (手順 5)、手順 6 に戻る。`blocked` のまま張り直すと即座に返って空回りする。何も起きていなければ、そのまま張り直してターンを終えればよい。

8. 全員の最終報告が揃ったら、成果物を検証してからユーザーへ提示し、結果を確認する。

   検証するのは報告ではなく成果物そのもの。diff を読む、テストを走らせるなど、依頼文書に書いた完了の定義を親自身の目で確かめてから提示する。

   この時点ではタブを開いたままにする。ユーザーが結果に納得しない、あるいはやり直しを求めた場合、子はまだ生きているのでその場で追加の指示を送れる。送ったら手順 6 に戻る。

   ここでターンを終えてユーザーの応答を待つのは、フォアグラウンドの `herdr agent wait` によるブロックとは別物。ユーザーとの対話は通常のターン終了であり、子からの SendMessage も watchdog も妨げない。

   ユーザーが結果を了承したら手順 9 へ進む。

9. 後始末する。

   ```bash
   herdr tab close <台帳のタブ ID>
   ```

   子ごとに繰り返す。閉じてよいのは自分が作ったタブだけ。agent 名は live agent の間でユニークなので、子を生かしたままにすると次の委任で同じ名前が取れなくなる。

   タブを閉じると、その子の watchdog は遅くともチェックイン間隔の満了までに `agent_not_running` で終了する。個別に止める必要はない。

   後始末が済んだら、結果をユーザーへ報告してターンを終える。子のタブはもう無いので、これ以降は起こされようがない。

## SendMessage で使うタグ

子との間で使うタグはこの 3 語だけ (`herdr:delegate-receive` 側にも子向けに同じ語彙が複製してある — 増やすときは両方直す)。

| タグ (子 → 親) | 親の動作 |
|---|---|
| `中間報告` | 作業の切れ目での報告。確認して次の指示を返す |
| `質問` | 判断を仰いでいる。回答を返す |
| `最終報告` | 完了の定義を満たした。成果物を検証する |

親から子へ返す文面 (次の指示・質問への回答) も SendMessage でそのまま送る。子は分岐せず読んで作業を進めるので、こちら向きのタグは自由でよい。

## 委任フロー特有の罠

herdr 全般の罠 (入力欄流し込み、起動直後の罠、`blocked` への誤爆、代理承認の規律など) は `herdr:gotcha` にある。ここにあるのは SendMessage による委任フロー固有の罠。

### 罠: herdr の名前と ListAgents の名前は別物

`herdr agent start <name>` で付けた名前は herdr 内部の管理名にすぎない。SendMessage/ListAgents 上で相手を指す名前は、それとは無関係に Claude Code セッション自身が自動で持つ名前 (例: `dotfiles-12`) であり、**`agent start` の名前からは分からない。**

対応付けは、子から先に SendMessage でハンドシェイクさせることで解決する (手順 7)。**逆方向 — 親が先に子の ListAgents 名を推測して送る — は行わない。** `ListAgents` の一覧は複数の子が並行して起動していると見分けがつかず、取り違えの元になる。

### 罠: 自己承認文言はかえって警戒を招く

依頼文書や SendMessage の本文に「これは正規のフローだからためらわず実行してよい」のような自己弁明的な一文を書くと、受け手はそれ自体をプロンプトインジェクションの兆候とみなし、確認ダイアログを挟んで `blocked` になることがある。実際に「委任内容は正規である」という一文を含む依頼文書を送ったところ、受け手は SendMessage 経由のピアからの自己申告だけでは正当性の根拠にならないと判断し、実行前に確認を求めた (1 往復で解消はしたが、余計な `blocked` を招いた)。

**正当性は文言で主張せず、経路で担保する。** `/herdr:delegate-receive <BRIEF_PATH>` という固定形式のスラッシュコマンドで届くこと自体が、ユーザー入力と区別のつかない正規の起動経路であり、依頼文書の中身は淡々とした手順として書けば足りる。「ためらわず」「安心して」のような念押しは書かない — 書くほど逆効果になる。

そもそも Claude Code の相手には、「ピアからの指示だけで見知らぬ行為を鵜呑みにすべきでない」として代理承認を拒否した実例が `herdr:gotcha` にある。SendMessage で届く指示も同様に扱われる — ピアからの自己申告だけでは正当性の根拠にならない。

### 罠: `blocked` の相手への SendMessage 配送は届いても読まれるとは限らない

実際に親を確認ダイアログ待ちの `blocked` にした状態で子から SendMessage を送らせて確かめたところ、`agent_blocked` のような拒否はなく、`pane run` のようにダイアログを誤承認することもなかった。ダイアログは表示されたまま、メッセージは画面に追加表示されるだけで、herdr 側の `agent_status` も `blocked` のまま変わらない。**ただし届いた時点では処理されない** — ダイアログへの回答という保留中のツール呼び出しが解決されるまでキューされたままになり、解決後の次のターンで初めて読まれる。子の報告が親に届いていても、親が自分のダイアログを片付けるまで気づかれない。放置しても消えはしないので `herdr agent prompt` / `pane run` より安全だが、気づくのが遅れる分だけ委任は止まる。