warp-delegate

Warp Delegate

あなたはオーケストレーターです。範囲を限定したコーディングタスクを、別の実装担当である Warp Agent CLI に委任し、その成果をレビューして、自分で取り込みます。依頼内容を作成し、判断の責任を持つのはあなたです。実装担当は独自の会話で変更を行い、あなたが検証してコミットします。

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

バイナリは oz であり、warp ではありません

Warp は異なる2つのプログラムを提供していますが、委任に使えるのはそのうち1つだけです。

• oz - Warp Agent CLI です。ヘッドレスでスクリプトから実行できます。oz agent run はローカルディレクトリに対してエージェントを実行します。リレーが使用するのはこちらです。
• warp - 対話型の Warp TUI です。ターミナルデバイスが必要で、プロンプトや出力用のフラグはありません（利用できるオプションは --resume、--auto-approve、--api-key とプロバイダーキー関連のコマンドのみです）。stdin がパイプの場合は Device not configured で終了します。リレー経由では実行できません。

oz がなく warp がインストールされている場合、手元にあるのは CLI ではなく TUI です。

使用しない場合

• タスクがインラインで処理できるほど小さく、委任のオーバーヘッドに見合わない場合。
• oz CLI がインストールされていない、または認証されていない場合。
• サンドボックス化された実装担当、または読み取り専用の実装担当が必要な場合。oz agent run にはサンドボックスも、権限モードも、読み取り専用での実行もありません。自律性と権限を参照してください。
• 作業内容を Warp のサーバーに送信してはならない場合。--no-snapshot を指定しない限り、oz agent run は実行終了時にワークスペースのスナップショットをアップロードします。また、会話はサーバー側に保存されます。

前提条件（最初に一度確認）

1. Warp Agent CLI をインストールします。https://docs.warp.dev/cli/を参照してください。
2. 認証します。oz login を実行するか、CI、コンテナ、またはヘッドレスホストでは WARP_API_KEY を設定します。
3. アカウントに AI クォータがあることを確認します。ログインできるだけでは不十分です。このパッケージ内の他の CLI とは異なります。oz whoami が成功しても、ディスパッチがすべて In order to use Warp's AI features, subscribe to a Warp plan, or bring your own inference. で失敗することがあります。Warp はこれを内部的に QuotaLimit／「AI クォータ不足」として記録するため、これは CLI 固有の権限ではなく、アカウントのクレジットに関する問題です。oz は Warp アプリと同じエージェントハーネスを実行し、同じアカウント、プラン、クレジットを使用します。oz whoami にプランを保有するアカウントが表示されることを確認してください。表示されない場合は、oz logout && oz login で修正できます。それ以外の場合は、プランの AI クレジットが使い切られていないことを確認するか、自分のプロバイダーキーを設定してください。warp --set-provider-api-key <openai|anthropic|google|grok> を実行するか、TUI 内で /api-keys を使用します。独自のキーを使用する場合、有料の Warp プランは必要ありません。
4. oz --version が成功し、oz whoami にユーザーが表示されることを確認します。
5. 対象の Git リポジトリ内で作業するか、--cd にそのリポジトリを指定します。

macOS では、CLI は署名済み Developer ID バイナリとして配布されています。初回実行時は、Gatekeeper によって承認されるまで保留されることがあります。

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

Warp の設定済みデフォルトを使う場合は、--model を省略します。別のモデルを選択するには、oz model list から ID を選び、そのまま渡します。リレーが受け付けるのは英字、数字、および . _ : / - のみなので、別の oz フラグと誤認される値を指定することはできません。

ループ

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

1. 依頼内容を作成する

Warp が参照できるのは、送信したテキストとワークスペース内で確認できる内容だけです。チャット履歴や共有コンテキストはありません。目標、現状、変更する内容、変更しない内容、プロジェクトの実際のゲート、レポートの要件を記載します。コミットしないよう伝えてください。依頼1件につきタスクは1つにします。依頼内容は argv の --prompt の値として渡されるため、ホストプロセスの一覧から見える状態になります。秘密情報は含めず、代わりにワークスペース内のファイルを参照してください。依頼内容の作成を参照してください。

2. ディスパッチ

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

同梱のリレーを使用してください。これは oz agent run --output-format ndjson を実行し、イベントストリームをキャプチャして、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 oz model list>
# use an agent profile:                    add --profile <id>
# label the run:                           add --name <label>
# continue an existing conversation:       add --conversation <id> (delta brief only)
# base the run on a Warp skill:            add --skill <name|repo:name|org/repo:name>
# start MCP servers:                       add --mcp <path-or-inline-json>  (repeatable)
# suppress the workspace snapshot upload:  add --no-snapshot
# 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

このリレーは、子プロセスの cwd と Warp 自身の --cwd の両方でワークスペースを固定します。デフォルトではシステムの一時ディレクトリ配下に成果物を書き込み、コミットは行いません。 references/dispatch-and-poll.md を参照してください。

3. 完了を待つ

codex-background を使う Codex では、元の MCP リクエストを保留状態にします。モデル主導の待機、ステータス確認、ログのポーリングは行いません。中断されたリクエストに再アタッチする場合に限り、delegate_wait を使用してください。

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

進捗表示より、プロセスの状態と作業ツリーを信頼してください。完了とは、プロセスが終了し、result.json が存在する状態です。Warp の報告は result.json の finalMessage フィールドにあります（レポートマーカーの間に stdout にも出力されます）。生のイベントストリームは常に events.jsonl にあります。

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

Warp の最終メッセージとゲート通過の主張は、あくまで主張として扱ってください。

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

フォールバック先となる読み取り専用モードがないため、得られる記録は差分だけです。そして差分に記録されるのは、実行で行われたすべてではなく、その後にワークスペースで git が認識できる内容です。両者ができるだけ一致するよう、クリーンなツリーからディスパッチしてください。 references/review-and-land.md を参照してください。

5. 反映する

実装担当者が作業ツリーを編集し、コミットはオーケストレーターが行います。 ゲートを通過し、差分に問題がないことを確認してからコミットしてください。手直しが必要な場合は、result.json の conversationId を使い、--conversation <id> を指定して差分ブリーフを送信し、その後もう一度レビューしてください。

自律性と権限

oz agent run にはサンドボックスも、権限モードも、読み取り専用モードもありません。ヘッドレス実行では、自身のユーザー権限で読み取り、書き込み、編集、コマンド実行を行い、確認を求めることはありません。CLI にはこの範囲を制限する機能がないため、このリレーには --read-only フラグを用意していません。このフラグを提供すると、実際には存在しない強制機能があるかのように見えてしまうためです。実際に利用できる制御は次のとおりです。

1. ディレクトリで範囲を指定する。 --cd でワークスペースを固定し、リレーはその値を Warp 独自の --cwd に渡します。これは防壁ではなく、あくまで狙いとして扱ってください。oz 0.2026.05.27 では、シェルコマンドは固定したワークスペースで実行されましたが、エージェントのファイルツールは、相対パスのみのパスを $HOME を基準に解決しました。ブリーフでは絶対パスを指定してください。references/writing-the-brief.md を参照してください。
2. 差分を確認する。 touchedFiles は実行後に取得した git status --porcelain の結果です。実行後に Git から確認できるワークツリーの状態であり、エージェントの作業記録ではありません。無視対象のファイルや、実行中に行われて元に戻された編集、リポジトリ外への書き込み（項目 1 を参照）は表示されず、ディスパッチ前から変更されていたものも含まれます。これらを同じ集合にするには、クリーンなツリーからディスパッチしてください。また、差分は入手可能な中で最善の記録として扱い、完全な記録ではないことに留意してください。
3. スナップショットの送信を制御する。 --no-snapshot は Warp のフラグをそのまま渡し、実行終了時のワークスペースのスナップショットがアップロードされないようにします。このフラグを指定しない場合、アップロードは Warp のデフォルト動作です。

--auto-approve は対話型の warp TUI 用であり、oz agent run には関係ありません。

承認モデル

委任するかどうかは人間が決めます。人間が委任した後（「このキューを実行して」「進めて」など）は、検証済みでゲートを通過した作業をコミットすることが合意された契約です。残る制限は 2 つです。吸収せず、表面化する（Warp の設計上の判断、正当化できるものの依頼されていない変更、ブロック要因ではない細かな指摘を報告する）ことと、範囲変更が必要なら停止する（正しく完了するためにブリーフの範囲を超える必要がある場合、権限の範囲を広げずに確認する）ことです。references/review-and-land.md を参照してください。

参考資料

• references/writing-the-brief.md - 構成、報告に関する契約、実際のゲート、argv の受け渡し、差分ブリーフ。
• references/dispatch-and-poll.md - フラグ、成果物、result.json、ポーリング、失敗からの復旧。
• references/review-and-land.md - レビューチェックリスト、コミットの境界、Warp の会話を通じた手直し。
• references/multi-task-queues.md - 順次処理するキュー、制約の引き継ぎ、進捗の追跡、最終的な整合性チェック。