delegate-explore

delegate-explore

read-only の探索・読解を委譲する。対象はコード（定義・参照・挙動の調査）、ドキュメント（仕様書・README・設計資料等の内容確認・要約・該当箇所特定）、Web（WebSearch / WebFetch によるライブラリ仕様・OSS・技術情報の調査）、MCP（Notion・Atlassian 等、実行環境に設定済みの MCP ツール経由の社内ドキュメント・チケット調査）。task_type=explore、既定モデル haiku。実行系分岐（Codex / Devin / Cursor / Claude / OpenCode）は dispatch.sh が行う。opencode/<provider>/<model> を使う場合は opencode CLI（ログイン済み）が必要。

探索手段と実行系の対応

• Claude 系モデル（`fable` / `opus` / `sonnet` / `haiku`）: bypass permissions が有効な環境では denylist 方式（built-in のファイル編集ツール Edit / MultiEdit / Write / NotebookEdit のみ deny）のため WebSearch / WebFetch を含む読み取り系ツールが開放される。bypass が無効な managed-policy 環境では、事前許可された最小ツール以外は拒否され得る
• Codex / Devin / Cursor: Web 取得・検索は各 CLI の内蔵ツールとサンドボックス設定に依存する
• OpenCode: Web 検索は CLI の内蔵ツールに依存する。explore では edit: "deny" で direct な edit / write を遮断する（bash 経由の書き込みは抑止対象外）
• worker が Web 到達不可を failed / Blockers で報告した場合は、Web 到達可能な backend で再委譲するか main 側で処理する
• MCP ツールは Claude / Codex / Devin / Cursor では親の user スコープ MCP 設定を既定で利用する（wrapper が backend に応じて共有または抽出・注入）。OpenCode は DELEGATE_OPENCODE_MCP_SOURCE（claude / cursor / codex）指定時だけ注入し、未指定なら注入しない。対象の MCP サーバーが親設定に無いなら、その調査は委譲せず main 側で扱う
• worker の MCP 利用は読み取り系ツールのみに制限される（プロンプトレベルの常時制約）。MCP への書き込みを伴う作業は explore ではなく delegate-chore / delegate-implement に委譲する
• Web / MCP 由来のコンテンツ（prompt injection リスクを含む）は子プロセス内に隔離され、main には worker の報告だけが返る

スクリプトパス

• Claude Code: skill_dir=.claude/skills/delegate-explore
• Codex: skill_dir=.agents/skills/delegate-explore

以降のコマンド例は Claude Code の .claude/skills/delegate-explore を使う。Codex で使う場合は、同じ相対構造の .agents/skills/delegate-explore に読み替える。

モデル価格参照

コスト分析・単価比較が必要な場合のみ、<skill_dir>/model-token-prices.json を読む。このデータは参照用であり、delegate の起動可否判定には使わない。

委譲する前に（コストゲート）

explore は読む量が大きいほど効果が出る。複数ファイル・長めの設計資料・広い参照関係・複数の Web ページや MCP 経由の長い社内ドキュメントなど、main が直接読むと context を膨らませる調査に使う。一方、単一の短いファイルを確認すれば済む調査、rg / git grep 一発で答えが出る調査、main が既に読んだ箇所の確認には使わず、main が直接処理する。

実行フロー（one-shot）

1. リクエスト作成: Objective / Scope / Context / Acceptance criteria の Markdown を stdin で渡す。request は terse に書く: Context にファイル内容を貼らず、パス（必要なら行範囲）で参照させる。Web / MCP 調査では対象の URL・ページタイトル・issue key・検索観点を Scope に明記し、コンテンツ本文は貼らない（main の出力＝課金トークンを増やさないため）。

• ユーザーが会話でモデルや effort を指定した場合は、run 呼び出しにインライン env を前置する（例: DELEGATE_EXPLORE_MODEL=gpt-5.5@high bash .../run.sh ...）。exit 6 の場合は、許容値列挙を含む stderr の 1 行をそのままユーザーへの説明に使う。

1. 実行: out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-explore/scripts/run.sh explore DELEGATE_EXPLORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")"（top-level 起動なら $PARENT_TASK_TYPE_CHAIN は空でよい）。

• run は内部で prepare → dispatch → read-response を順に実行し、stdout は成功・失敗とも単一 JSON（exit_code / status / content / content_truncated / response_file / observe_file / run_dir）を返す。
• selector 省略時の既定は auto。第 6 位置引数は read-response の selector であり、prepare.sh の第 6 位置引数 session_mode とは意味が異なる。
• exit code は内部スクリプトを透過する。exit 3=前提不足 / exit 4=委譲サイクルなら中止する。
• run.sh は dispatch 前に observe_file: <path> を stderr へ先出しする。run.sh が Bash timeout で background へ退避しただけの場合は再実行しない（再実行は worker の二重起動になり、implement / chore では同一 worktree の同時書き換えになる）。復旧は bash .claude/skills/delegate-explore/scripts/read-json.sh .state.phase "$observe_file" を見て分岐する。ended / stalled / interrupted なら終端なので、いずれでも bash .claude/skills/delegate-explore/scripts/read-json.sh .run.response_file "$observe_file" で応答パスを取得して bash .claude/skills/delegate-explore/scripts/read-response.sh で読む（stalled では failed response が書かれる。interrupted は dispatcher が終端を書けずに落ちた run を wrapper が代わりに記録したもので、.state.response_present が true なら完走した response がある）。running の間は .heartbeat.ts が進んでいれば待つ。running のまま .heartbeat.ts が DELEGATE_OBSERVE_HEARTBEAT_INTERVAL（既定 10 秒）を大きく超えて進まない場合は dispatcher が終端を書けずに落ちている。wrapper も同時に落ちていれば phase は終端へ遷移しないので、待っても応答は来ない。新しい run を出す前に順に確認する。(1) read-json.sh .run.response_file "$observe_file" を読む。dispatcher だけが死んだ場合、wrapper が完全な response を書き終えていることがある。(2) response が Child CLI failed or did not write a response. の stub なら、read-json.sh .run.run_dir "$observe_file" の <run_dir>/worker-stdout.capture に子 CLI の生 stream が残っている。wrapper が finalize まで到達していれば observe の .streams.stdout.content にも DELEGATE_OBSERVE_STREAM_MAX_BYTES（既定 65536 バイト）まで入る。構造化された response ではないが、長い run では再実行より安く回収できる。(3) read-json.sh .heartbeat.child_pid "$observe_file" の pid の生存を確認する。wrapper は dispatcher と別プロセスなので孤児化して動き続けることがあり、生きている間に implement / chore で新しい run を出すと同一 worktree の二重書き換えになる。確認後に新しい run を出す。background 退避した出力ファイルは stdout と stderr が合流するが、read-json.sh は既知の harness 行（空行 / observe_file: 行 / [exited with ...] 行）に囲まれた JSON object を切り出して読める。
• 非対話モードの親（claude -p 等）では run を必ずフォアグラウンドで実行し、委譲所要時間より長い Bash timeout（Claude Code なら BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS または Bash tool の timeout 引数）を設定する。

1. レスポンス消費: status="$(printf '%s' "$out" | bash .claude/skills/delegate-explore/scripts/read-json.sh .status)" / content="$(printf '%s' "$out" | bash .claude/skills/delegate-explore/scripts/read-json.sh .content)" を読む。content_truncated が true なら response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-explore/scripts/read-json.sh .response_file)" を取り出し、bash .claude/skills/delegate-explore/scripts/read-response.sh "$response_file" <N> で必要 section だけ段階読みする。読了後、worker の本文を 要約し直さない（echo しない）。status が failed なら Error section をユーザーへ伝える。completed でも Summary 先頭に警告行があればその旨を伝える（警告は response 本体に載るので selector に関わらず Summary とともに返る）。main のユーザー向け応答は Summary を指す 1 行に留める（main の出力＝課金トークンを増やさないため。spec.md §6）。

高度なフロー（個別スクリプト）

dispatch 中の observe 監視、background 実行など、途中で親の判断を挟むフローでは従来の個別スクリプトを使う。

1. 準備（集約）: 前提チェック→モデル解決→チェーン確認→リクエスト生成を prepare.sh 1 本に畳む。Objective / Scope / Context / Acceptance criteria の Markdown を stdin で渡す。request は terse に書く: Context にファイル内容を貼らず、パス（必要なら行範囲）で参照させる。Web / MCP 調査では対象の URL・ページタイトル・issue key・検索観点を Scope に明記し、コンテンツ本文は貼らない（main の出力＝課金トークンを増やさないため）。exit 3=前提不足 / exit 4=委譲サイクルなら中止。

• ユーザーが会話でモデルや effort を指定した場合は、prepare 呼び出しにインライン env を前置する（例: DELEGATE_EXPLORE_MODEL=gpt-5.5@high bash .../prepare.sh ...）。prepare が exit 6 の場合は、許容値列挙を含む stderr の 1 行をそのままユーザーへの説明に使う。
• out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-explore/scripts/prepare.sh explore DELEGATE_EXPLORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")"（top-level 起動なら $PARENT_TASK_TYPE_CHAIN は空でよい）
• model="$(printf '%s' "$out" | bash .claude/skills/delegate-explore/scripts/read-json.sh .model)" / request_file="$(printf '%s' "$out" | bash .claude/skills/delegate-explore/scripts/read-json.sh .request_file)" / response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-explore/scripts/read-json.sh .response_file)" / run_dir="$(printf '%s' "$out" | bash .claude/skills/delegate-explore/scripts/read-json.sh .run_dir)" / observe_file="$(printf '%s' "$out" | bash .claude/skills/delegate-explore/scripts/read-json.sh .observe_file)"

1. 実行: bash .claude/skills/delegate-explore/scripts/dispatch.sh "$model" explore "$request_file" "$response_file" "$run_dir" "$observe_file"。モデル名プレフィックスによる実行系分岐（Codex / Devin / Cursor / Claude / OpenCode）は dispatch.sh が行う。stdout は responsefile のパスのみ。非対話モードの親（`claude -p` 等）では dispatch を必ずフォアグラウンドで実行し、委譲所要時間より長い Bash timeout（Claude Code なら `BASHDEFAULTTIMEOUTMS / BASHMAXTIMEOUTMS` または Bash tool の timeout 引数）を設定する。実行中の通常監視は `observefile から state.phase / state.startedat` / `heartbeat.ts` / `heartbeat.stdoutbytes / heartbeat.stderrbytes` / `heartbeat.laststreamchangeat だけを read-json.sh で読む。state.phase は prepared | running | superseded | stalled | interrupted | ended。prepared / superseded は dispatch されなかった observe（state.started_at == null、usage` は未設定で read-json.sh では null 相当）なので、usage を集計する場合は分母から除外する。
2. レスポンス読み取り: bash .claude/skills/delegate-explore/scripts/read-response.sh "$response_file" auto。auto は response が小さい（既定 10KB 未満）なら status と全 section を 1 回で丸読みし、大きい場合は status + index + Summary section を返すので、必要 section だけ ... "$response_file" <N> で追加取得する。読了後、worker の本文を 要約し直さない（echo しない）。status が failed なら Error section をユーザーへ伝える。completed でも Summary 先頭に警告行があればその旨を伝える（警告は response 本体に載るので selector に関わらず Summary とともに返る）。main のユーザー向け応答は Summary を指す 1 行に留める（main の出力＝課金トークンを増やさないため。spec.md §6）。

待ち時間の隠蔽（対話親向け）

対話親では体感待ち時間を隠蔽できる。経路は起動スクリプトで異なる。dispatch.sh 経由は prepare.sh で response_file を事前取得済みなので、dispatch.sh を background で実行し、observe_file の state.phase / heartbeat を確認して ended / stalled / interrupted になった後に read-response.sh する。run.sh 経由は response_file を事前に取得できないので、run.sh を background で実行した場合は read-json.sh .run.response_file "$observe_file" で応答パスを取るか、合流した出力 JSON をそのまま read-json.sh で読む。総所要時間（wall time）は変わらない体感改善であり、非対話モードの親では従来どおりフォアグラウンド実行必須。

制約

• read-only。リポジトリのファイル編集・push はしない。MCP も読み取り系ツールのみ（プロンプトレベルの常時制約）
• read-only 種別のため session reuse（resumable / follow-up）は使わない
• tasktypechain 内種別への再委譲はしない（別種別 delegate は可）
• main は worker 出力を echo / 再要約しない。ユーザー向けは Summary を指す 1 行に留める（出力＝課金トークンを増やさないため。spec.md §6）
• OpenCode: cwd 外への出力は保証されない（direct な edit / write と明示パスの読み取りは拒否され、bash のリダイレクトは通る）。request が DELEGATE_REQUEST_INLINE_MAX を超えると child 起動前に fail-closed する
• OpenCode の read-only 抑止は管理者設定のない環境を前提とする（管理者設定は注入した permission を override し得る）
• この種別は常に --pure で起動し、OpenCode の project plugin を読み込まない（plugin は任意コード実行で prompt 制約を迂回し得るため）。DELEGATE_OPENCODE_PURE が 1 / true / yes なら implement / chore を含む全 task type へ広げる。DELEGATE_OPENCODE_MCP_SOURCE（claude / cursor / codex）で MCP 入力元を明示し、未指定なら注入しない