pi-delegate

Pi Delegate

あなたはオーケストレーターです。範囲を限定したコーディングタスクを、別の実装担当者である Pi コーディングエージェント CLI に委任し、その成果をレビューして、自分で取り込みます。ブリーフを作成し、判断の責任を負うのはあなたです。実装担当者は独自のセッションで変更を加え、あなたが検証してコミットします。

このループに必要なのはシェルコマンドとファイルアクセスだけなので、同等のオーケストレーターであればどれでも実行できます。

使用しない場合

• タスクがインラインで実行できるほど小さい場合。委任のオーバーヘッドに見合いません。
• pi CLI がインストールされていない、または認証されていない場合。
• サンドボックス化された実装担当者が必要な場合。Pi にはサンドボックスも権限モードもありません。--read-only はツールの利用範囲を制限しますが、書き込み可能な実行ではプロンプトなしに処理が実行されます。

前提条件（一度確認）

1. npm install -g @earendil-works/pi-coding-agent で pi をインストールします。
2. 認証します。サブスクリプションプロバイダーの場合は pi 内で /login を実行し、API キープロバイダーの場合は API キーの環境変数または pi の認証ファイルを使用します。
3. pi --version が成功することを確認します。
4. 対象の git リポジトリ内で作業するか、--cd でそのリポジトリを指定します。

モデルを選択する（任意）

--model を省略すると、pi で設定されているデフォルトが使用されます。別のモデルを選ぶには、pi --list-models から選択し、明示的な ID または <provider>/<model-id> や sonnet:high のようなパターンを渡します。リレーが受け付けるのは英字、数字、および . _ : / - のみです（値は Windows 上でシェルに渡されるため）。そのため、* を含む glob パターンは転送されません。

ループ

タスクごとに次の 5 つのステップを実行します。ステップ 1、4、5 には判断が必要で、2 と 3 は機械的な手順です。

1. ブリーフを作成する

Pi が参照できるのは、送信したテキストとワークスペース内で確認できる情報だけです。チャット履歴や共有コンテキストは参照できません。目標、現在の状態、変更する内容、変更せずに残す内容、プロジェクトで実際に適用されるゲート、および報告の形式を含めます。Pi にはコミットしないよう指示します。ブリーフ 1 つにつきタスクは 1 つにします。Pi はワークスペースおよびその親ディレクトリから AGENTS.md／CLAUDE.md のコンテキストファイルを自動で読み込むため、リポジトリの指示をインラインで記載しなくても伝えられます。references/writing-the-brief.md を参照してください。

2. ディスパッチする

Codex でバックグラウンド作業をオーケストレーションする場合は、まず別の codex-background サポートユーティリティをインストールして設定します。その MCP ツールまたはレジストリが見つからない場合は停止して、セットアップが必要であることを報告してください。モデルにポーリングを任せる方法へ黙って切り替えてはいけません。その後、以下のシェルの例の代わりに、登録済みの delegate_run MCP ツールを 1 回呼び出します。 構造化された共通引数、変更しないプロバイダーフラグ、および runId による再接続については、そのスキルに従ってください。完了するまでリクエストを保留にし、その後、このスキルのレビューと取り込みの手順に進みます。その他のオーケストレーターは、以下のシェルワークフローを使用します。

同梱のリレーを使用します。リレーはブリーフを標準入力から pi --mode json に渡し、JSON イベントストリームを取得して result.json に書き込みます。<skill-dir> は、この SKILL.md が格納されているインストール済みフォルダーです。

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# choose a model:                          add --model <id from pi --list-models>
# choose a provider:                       add --provider <name>
# read-only run (review/diagnosis):        add --read-only
# trust project .pi resources:             add --approve
# resume the most recent session:          add --resume-last  (delta brief only)
# resume a specific session:               add --session <id> (delta brief only)
# hard time limit (watchdog):              add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
# see all options:                         node .../relay.mjs --help

子プロセスの作業ディレクトリによって、ワークスペースが固定されます。デフォルトではリレーはシステムの一時ディレクトリに成果物を書き込み、コミットは行いません。references/dispatch-and-poll.md を参照してください。

3. 完了を待つ

codex-background を使用する Codex は、元の MCP リクエストを保留状態に保ちます。モデルによるスリープ、ステータスのポーリング、ログのポーリングは行いません。中断されたリクエストに再接続する場合にのみ delegate_wait を使用します。

リレーは pi が終了するまでブロックします。オーケストレーターのバックグラウンドコマンド機能で実行するか、シェルでバックグラウンド実行して result.json をポーリングします。実行前の使用方法エラーは終了コード 2 となり、結果は書き込まれません。pi が見つからない場合は終了コード 127 となり、status: "pi_unavailable" が書き込まれます。

進捗表示よりも、プロセスの状態と作業ツリーを信頼してください。プロセスが終了し、result.json が存在すれば完了です。Pi の完全なレポートは result.json の finalMessage フィールドにあります（レポートマーカーの間に、標準出力にも全文が出力されます）。

4. レビュー - 自己申告を鵜呑みにしない

pi の最終メッセージとゲートに関する主張は、あくまで主張として扱います。

• プロジェクトのゲートを自分で再実行します。
• touchedFiles から始めて、ブリーフに照らして差分を確認します。
• インストールされている場合は、関連するガードスキルを実行します。
• マイグレーションを往復で検証し、削除や名前変更の後に参照が残っていないか grep で確認します。

references/review-and-land.md を参照してください。

5. コミットする

実装担当者が作業ツリーを編集し、オーケストレーターがコミットします。 ゲートに合格し、差分に問題がないことを確認してからコミットしてください。手直しが必要な場合は、--resume-last または --session <id> を指定して差分ブリーフを送り、その後、再度レビューします。

自律性と権限

pi にはサンドボックスも権限モードもありません。 デフォルトのヘッドレス実行では、プロンプトなしで読み取り、書き込み、編集、シェルコマンドの実行を行います。制御手段は次のとおりです。

1. --read-only を指定すると、pi が呼び出せるツールが、組み込み、拡張機能、カスタムツールを問わず --tools read,grep,find,ls に制限されます。インストール済みの拡張機能のコードは、引き続きユーザーのホスト権限で実行されます。
2. リレーはデフォルトで --no-approve を渡すため、プロジェクトの .pi 設定、拡張機能、スキルは信頼されないままです。ユーザーが信頼するリポジトリに対して明示的に許可する場合は、--approve を指定します。
3. 変更内容の記録は touchedFiles と差分です。実行のたびにこれらを確認してください。

承認モデル

委任は、人間が選択して行うものです。「このキューを実行して」「続行して」などの指示があった場合、検証済みでゲートに合格した作業をコミットすることが、合意された約束となります。ただし、次の 2 つの制限があります。隠さず報告すること（pi の設計上の判断、妥当ではあるものの依頼されていない対応、作業を妨げない細かな指摘を報告する）と、スコープが変わる場合は止めること（正しく完了するためにブリーフの範囲を超える必要があるなら、権限を拡大するのではなく確認を求める）です。references/review-and-land.md を参照してください。

参考資料

• references/writing-the-brief.md - 構成、報告の合意事項、実際のゲート、stdin による受け渡し、差分ブリーフ。
• references/dispatch-and-poll.md - フラグ、成果物、result.json、ポーリング、障害からの復旧。
• references/review-and-land.md - レビューチェックリスト、コミットの境界、pi セッションを通じた手直し。
• references/multi-task-queues.md - 順次キュー、制約の引き継ぎ、進捗管理、最後の整合性確認。