grok-delegate

Grok Delegate

Git の所有権チェックで拒否された信頼済みリポジトリに対して、リレーは --trust-git-root <exact-worktree-root> をサポートしています。このオプトイン設定が影響するのはリレーの Git チェックのみで、Git の永続的な 設定や Grok の権限は変更されません。ディスパッチとポーリングを参照してください。

あなたはオーケストレーターです。このスキルを使うと、範囲を限定したコーディングタスクを別の 実装担当である Grok Build CLI（grok）に任せ、その成果をレビューして自分で取り込めます。あなたが依頼内容を作成し、判断の責任を担います。Grok は明示された自律性プロファイルに従ってコードを記述し、あなたが検証してコミットします。

ここで説明する内容は、特定のオーケストレーターエージェントに依存しません。この一連の流れに必要なのは、シェルコマンドの実行とファイルの読み取りだけなので、Claude Code、Cursor、選択したモデルを使う OpenCode、または同等のエージェントで同じように機能します。（Claude Code と Cursor 向けに設計されています。他のオーケストレーターも設計上は対象ですが、まだ実証されていないものとして扱ってください。）

使用しない場合

• タスクが小さく、その場で実行できる場合 — 委任のオーバーヘッドに見合いません。
• grok CLI がインストールされていない、認証されていない、またはアカウントが Grok Build ベータへのアクセス権を持っていない場合。
• 自分でコードを書きたい場合、または実装担当による作業を行わずにレビューだけを依頼したい場合。

前提条件（一度だけ確認）

1. grok version が成功すること。成功しない場合は、 npm i -g @xai-official/grok を使って任意のプラットフォームにインストールするか（xAI の公式 Grok CLI ドキュメントにあるインストーラーを使用する方法もあります）、認証します（grok login、ヘッドレスホストでは grok login --device-auth、または XAI_API_KEY を設定します）。
2. PATH 上にある grok を確認します。 command -v grok で使用中のバイナリが、grok version でそのバージョンがわかります。リレーは実行したバージョンを result.json に記録するため、古いバイナリを使った場合は後から確認できます。
3. 対象の Git リポジトリ内にいること（または --cd でそのリポジトリを指定すること）。

一連の流れ

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

1. 依頼内容を書く

Grok が参照できるのは、送信したテキストのみです。オーケストレーターとのチャット履歴や共有コンテキストはありません。タスクに必要な内容はすべて依頼に含めます。目標、現在の状態、変更する内容、変更せずに残す内容、プロジェクトで実際に使用されているゲートコマンド（リポジトリの CLAUDE.md／AGENTS.md／Makefile から確認し、推測しないでください）、およびレポートの要件を記載します。Grok にはコミットしないこと（コミットするのはあなたです）を伝えます。依頼 1 件につきタスクは 1 つにします。詳しいガイダンスとテンプレートについては、依頼内容の書き方を参照してください。

2. 委任

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

同梱のヘルパーを使って、概要を Grok に送信します。このヘルパーは grok -p をラップし、実行結果を取得して、 構造化された result.json を書き込みます。つまり、あなたがすることは「コマンドを実行し、ファイルを読む」だけです。（以下の <skill-dir> は、このスキルがインストールされているディレクトリ、つまり SKILL.md を含むフォルダーです。スキルを読み込んだディレクトリです。Claude Code では、スキルの読み込み時に「Base directory for this skill」として表示されます。他のオーケストレーターでは同じディレクトリを使ってください。どこに配置されたかわからない場合は、find ~ -name relay.mjs -path '*grok-delegate*' を実行し、その親ディレクトリを指定してください。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis; best-effort — verify touchedFiles): add --read-only
# continue the previous Grok session:       add --resume-last  (send only the delta brief)
# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
# see all options:                          node .../relay.mjs --help

ヘルパーは、書き込み可能な（workspace-write）自律性プロファイルをデフォルトで使用します。つまり、--always-approve と --sandbox workspace を指定し、成果物を一時ディレクトリに書き込むため、レビュー対象のリポジトリはクリーンな状態に保たれます。 コミットは決して行いません。手順 5 を参照してください。仕組み、フラグ、result.json の形式については、 references/dispatch-and-poll.md を参照してください。

3. 完了を待つ

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

ヘルパーは Grok が完了するまで処理をブロックします。そのため、利用しているオーケストレーターの機能を使って実行し、戻ってきたら再開してください。

• Claude Code： Bash 呼び出しを run_in_background: true で実行してください。完了すると通知されます。
• プレーンシェル／その他のエージェント： 短いタスクではフォアグラウンドで実行し、長いタスクではバックグラウンドで実行して 結果ファイルをポーリングしてください。bash/zsh（Git Bash/WSL を含む）では … & を使い、その他のシェルでは同等の機能を使います（PowerShell では Start-Job、cmd では start /b）。result.json が存在し、status が記録されたら実行は完了です。（実行前の使用エラー（引数が不正、または概要が空など）の場合は、代わりにコード 2 で終了し、stderr にメッセージを出力して、結果ファイルは書き込みません。そのため、終了コードも確認してください。grok バイナリが見つからない場合はコード 127 で終了しますが、grok_unavailable ステータスを含む result.json は書き込みます。）

進捗トラッカーよりも実際の状態を信頼してください。result.json が書き込まれ、プロセスが終了した時点で実行は完了です。 ステータス行ではなく、作業ツリーを確認してください。実装担当者の完全なレポートは、result.json の finalMessage フィールドにあります（レポートマーカーの間に、stdout にも全文が出力されます）。

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

Grok の result.json には、独自の要約とゲートの通過に関する主張が含まれています。再検証してください。鵜呑みにしてはいけません。

• プロジェクトのゲートを自分で再実行してください（手順 1 のテスト／lint／ビルドコマンド）。「ゲートを通過した」という報告を決して鵜呑みにしてはいけません。
• 概要に照らして差分を確認してください。 Grok は依頼されたことだけを行い、余計なこと（スコープの逸脱）も不足もありませんか？確認の出発点として、結果の touchedFiles を使ってください。
• 利用可能であれば、インストール済みの関連ガードスキル（guard-skills の clean-code-guard、test-guard など）を差分に対して実行してください。このスキルが作業を行い、それらのスキルが評価します。
• スキーマ／マイグレーションの変更は往復で検証し、削除の場合は参照が残っていないか grep で確認してください。

チェックリストの全文は references/review-and-land.md を参照してください。

5. 反映する

コミットするのはオーケストレーターです。 ゲートを通過し、差分に問題がないことを確認してから、次の手順に進んでください。

• 検証済みの作業を、内容が明確なメッセージを付けて自分でコミットしてください。
• 修正が必要な場合は、タスク全体を言い直さず、差分の概要を --resume-last で送信し、もう一度レビューしてください。

自律性モデル

Grok のデフォルトの権限モードは ask であり、ヘッドレスパイプでは承認プロンプトで処理が停止します。そのため、リレーでは常に自律性を明示的に設定します。

リレーフラグ	Grok に渡される設定	使用する場面
(デフォルト)	--always-approve --sandbox workspace	通常の実装 — 書き込み先は作業ツリー内に限定されます
--read-only	--sandbox read-only --always-approve	レビュー／診断 — カーネルによって適用されるサンドボックスですが、完全ではありません（以下の注意事項を参照）
--full-access	--always-approve --sandbox off	タスクで制限のないツールが必要な場合に、明示的にオプトインします

--always-approve だけを指定すると、すべてのツール（書き込み、シェル、ネットワーク）が承認されます。これは、ワークスペース内の書き込みだけを許可する設定よりも、制限のない状態に近いものです。--sandbox workspace と組み合わせることで、デフォルト設定の安全性が保たれます。--full-access は、人間から求められた場合にのみ使用してください。

--read-only はカーネルによって適用されますが、完全ではありません。 grok 1.0.25 の読み取り専用サンドボックス（macOS では Seatbelt、Linux では Landlock）は、grok 独自の書き込み／search_replace ツールとシェルのリダイレクトを EPERM で拒否するため、--always-approve が自動承認するのはサンドボックス内のツールだけです。ただし、このプロファイルは完全ではありません。/tmp、/var/tmp、~/.grok/ への書き込みは引き続き許可されるため、これらのパス内にあるリポジトリは保護されません。また、macOS では子プロセスのネットワークアクセスは制限されません。必ず後から touchedFiles を確認してください。保証となるのはフラグではなく差分です。リレーでは、解析済みの git porcelain を比較し、すでに変更が加えられていた Git から見えるパスについて、作業ツリー上の識別情報とインデックスエントリのフィンガープリントを取得することで、報告用の検知機能を自動化しています。いずれかのシグナルで変更が確認された場合、readOnlyViolation は true になります。検出範囲が完全で、変更が検出されなかった場合は false になります。検出範囲が不完全な場合は null になります。無視されるパス、サブモジュール内部、完全に元に戻された変更、並行変更の帰属は対象外のままです。そのため、保証となるのは引き続き差分のレビューです。

認可モデル

委任は、人間がオプトインするものです。いったん委任が承認されたら（「このキューを実行して」「進めて」）、検証済みでゲートを通過した作業をコミットすることが合意された契約です。それが委任の目的そのものです。この権限には2つの制限があります。表に出し、抱え込まない（Grok の設計上の判断、正当化はできても依頼されていない方向転換、ブロックしない細かな指摘は、黙ってそのままにせず報告します）こと、そしてスコープが変わる場合は停止する（正しく完了するために依頼の範囲を超える必要がある場合は、権限を独断で拡大せず、確認を求めます）ことです。詳細はreferences/review-and-land.mdを参照してください。

参考資料

• references/writing-the-brief.md — Grok が人の確認なしで実行できるよう、ブリーフを作成する方法：構成、XML ブロック、レポートの契約、実際のゲートコマンドの埋め込み。
• references/dispatch-and-poll.md — relay.mjs のフラグ、result.json の契約、オーケストレーターごとのバックグラウンド実行、実行が不調な場合の復旧方法。
• references/review-and-land.md — レビューチェックリスト、コミットの境界、--resume-last を使った手直しのサイクル。
• references/multi-task-queues.md — 順次キューの実行方法：制約の引き継ぎ、進捗の追跡、実行終了時の整合性チェック。