external-agent-invocation

name	external-agent-invocation
description	Common procedure and pitfalls for launching another coding agent's CLI (codex / claude / gemini) as a subprocess from the current session. Use before running `codex exec`, `claude -p`, or `gemini -p` — whether a review / second-opinion skill routes here, or the request is ad-hoc such as 「codex に見てもらって」「gemini にも聞いて」「別のエージェントの意見も欲しい」. Covers which CLI to pick, how to pass the target, working-directory and stdin failures that stay silent, and how to make the external agent label severity.
summary	外部エージェントの CLI を子プロセスとして起動するときの共通手順。doc-review-external / code-review-external / sidekick の共通部分の実体。起動したプロセスをバックグラウンドで走らせる場合の落とし穴は background-agent-ops が扱う。

外部エージェント呼び出し

現在のセッションから、別のコーディングエージェントの CLI（codex / claude / gemini）を子プロセスとして起動するときの共通手順。

呼び出し元のスキルはこの手順に従い、自分に固有の部分だけを持つ。この手順に含めないものは次の4つで、これらは呼び出し元が決める。

• 何を渡すか（ファイル / リビジョン範囲 / 自由なテーマ）
• 外部プロセスに修正まで適用させるか
• 終わったあとに何を確認するか
• やり取りを何往復で打ち切るか

呼び出し元スキルを介さない直接の呼び出しでは、この4つを決めるのは自分になる。レビュー目的で決めるときの判断基準（対象の切り方・編集権をどこまで渡すか・ラウンドごとの編集モード）は external-review-operations にある。実装の委譲や意見聴取だけなら不要。

1. オプションの解釈

呼び出し元が受け取った引数を次のように解釈する。呼び出し元ごとに違う解釈をしない。

フラグ	意味
--claude	claude を使う
--gemini	gemini を使う
--codex / 指定なし	codex を使う（既定）
-a / --adversarial	Adversarial Review モード（まず反証を試みさせる）

これらのフラグを取り除いた残りが対象。対象が何を意味するかは呼び出し元が決める。

2. 起動コマンド

CLI	形
codex	codex exec "[指示内容]" < /dev/null
claude	claude --model fable -p "[指示内容]"
gemini	gemini -p "[指示内容]"

• stdin は必ず塞ぐか、ファイルを渡す。ファイル内容を読ませる場合は < /dev/null の代わりに < "[FILE_PATH]" にする。開けたままにすると codex は入力待ちでハングする。
• 指示文が長いときは codex の prompt 引数を省いてファイルから流す（codex exec < "[PROMPT_FILE]"）。引数が無ければ codex は stdin を指示文として読む。クォート事故を避けられ、次節のコマンド置換禁止とも両立する。
• codex に編集させるなら -s workspace-write（既定は編集させない）。書ける範囲は workspace 配下なので、編集対象がそこから外れる場合は --add-dir で足す。
• claude に修正させるかは --permission-mode で決まる。編集まで任せるなら --permission-mode "acceptEdits"、意見だけ聞くなら指定しない（既定のまま）。
• claude を使う場合はモデルを fable に固定する。呼び出し元が別のモデルを必要とする場合だけ上書きする。
• パスにスペースが含まれうるので必ずクォートする。
• 実行前に、なぜそのコマンド・そのツールを選んだかを簡潔に説明する。

起動したプロセスをバックグラウンドで走らせる場合は、background-agent-ops スキルも読むこと。

3. コマンド置換を使わない

$(...) やバッククォートによるコマンド置換を使わない。情報は個別のステップで取得し、リテラルとして次のステップへ渡す。

diff や log を指示文へ埋め込むためにコマンド置換を使いたくなるが、その必要はない。範囲だけをリテラルで渡し、git log -p <範囲> は外部プロセス自身に実行させる。

4. codex の落とし穴

codex は他の2つより起動条件が厳しく、失敗が静かに別の症状へ化ける。

作業ディレクトリはリポジトリ内にする

リポジトリ外（スクラッチ領域等）を cwd にすると "Not inside a trusted directory" で即失敗する（exit 1）。対象ファイル自体はリポジトリ外でも構わないが、実行時の cwd はリポジトリ内であること。

; echo のようなラッパーを挟むと exit 0 に見えてしまうため、出力が数行しかないときはこのエラーを疑う。

cd と同じコマンドに繋がない

cd <リポジトリ外> && ... ; codex exec ... と繋ぐと、cd の副作用で codex が信頼されない cwd から起動し、上記の失敗になる。準備コマンドとは別の単独コマンドとして実行する。

ハングは起動時に見張りを仕込み、判定はプロセス状態で行う

| tail 等でパイプすると入力が閉じるまで出力が出ないため、「出力が無い」ことはハングの根拠にならない。ps で見て、経過時間が長いのに CPU 時間がほぼゼロ（sleeping）ならハング。stdin 待ちが典型だが、stdin を塞いでいても MCP 初期化付近など実行途中で止まる事例がある — stdin 対策済みであることはハングしない根拠にならない。

数分以上かかる見込みの呼び出しは、結果待ちに入る前に見張りをバックグラウンドで仕込む（例: sleep 600 後にログ行数と対象プロセスの CPU 時間を測って報告させる）。ハングは静かに起きるため、見張り無しでは発見が人の指摘まで遅れる（52分無進捗の実例）。検知したら原因究明より先に kill して同じ入力で再実行する — 一過性で、再実行が正常に完走する事例が多い。

worktree を作業ディレクトリにしない

git worktree を workdir にすると exit code 134 で異常終了する既知問題がある。worktree 上のブランチを対象にするときも、codex の workdir はメインリポジトリのままにする。

これは「worktree が対象なら codex を諦める」という意味ではない。workdir と対象は別の軸で、次の組み合わせで両立する。

軸	何を指すか
workdir（cwd）	メインリポジトリ。worktree にしない
読む対象	コミットハッシュ範囲。worktree とメインは .git を共有するのでメイン側から到達できる
読み書きするファイル	worktree 配下の絶対パス。メイン側の同名ファイルは別ブランチの中身なので触らせない

この3点を指示文に明記すれば、編集を伴うレビューでも codex のまま通る（.claude/worktrees/ のように worktree がメインリポジトリ配下にあれば -s workspace-write の書き込み範囲にも収まる）。この制約を理由に claude / gemini へ倒さない — CLI の変更は合意済み方針の変更にあたるので、倒したいならユーザへ諮る。

指示文の書き方は次節の worktree の項に従う。

git コマンド自体が失敗し、根拠が静かに現行ファイルへ落ちる

workdir が正しくても、外部プロセスのサンドボックス内で git show / git log -p が異常終了する（codex では exit 134 の実例がある）。前節の worktree 問題と症状が同じでも原因が別で、workdir を直しても消えない。

厄介なのは、外部プロセスがこれをエラーとして返さず、現行ファイル・テスト・ログからの推論へ黙って切り替えて結論を出すこと。結論自体は妥当なことがあるが、根拠は「指定した差分を読んだ結果」ではなくなっている。差分・履歴を見せた前提で依頼したなら、報告を受け取った側でその前提が成立したかを確認し、ユーザへ伝えるときも根拠の出所を明示する。

5. 対象を確定させてから渡す

外部プロセスは自前の索引キャッシュ（context-mode / serena 等）を持つことがある。それが古いスナップショットを指していると、実態と違う前提のまま重大度の高い誤検出を並べてくる。指摘の真偽以前に前提が違うため、受け取った側は全件を照合し直す羽目になる。対象を「今の実態」へ固定してから渡す。

• 未コミットのまま渡さない。対象は先にコミットし、確定したコミットハッシュ範囲（<base>..<head>）で指す。ブランチ名では指さない — 参照先が動く。作業ツリーのまま渡すと、何を見せたのかが後から再現できない。
• 一次情報を見るよう指示文に書く。「索引やキャッシュではなく git show <hash> / git log -p <範囲> / 実ファイルで実態を確認せよ」と明示する。
• worktree が対象なら、どのチェックアウトの話かを明示する。中身への到達はコミットハッシュで足りるが、それだけでは外部プロセスの cwd 解決や索引がメインリポジトリ側へ静かにドリフトする（両者は .git を共有しているため）。workdir はメインのまま置き（前節）、指示文で次の3つを書く。
  • 「作業ディレクトリはメインの checkout で、レビュー対象はそこに入っていない」— 対象が cwd にある前提で読み始めるのを防ぐ
  • 「対象ブランチは <worktree の絶対パス> にある。メインの checkout ではなく、このパスの commit <hash> を見よ」
  • 「実ファイルの読み書きは worktree 配下の絶対パスで行う」— 編集させる場合は編集先としても明示する

6. 対象の位置づけを渡す

指示文には、対象の位置づけ（目的・読者・次工程、探索段階なのか採用直前なのか）を1〜3行で書く。

位置づけを渡さないと、外部プロセスが想定と異なる基準で重大度を判定し、指摘が過剰にも過小にもなる。呼び出しコンテキストから位置づけを特定できない場合はユーザに確認する。

7. 重大度を必ずラベルさせる

外部プロセスの出力をそのまま流すと、重要な指摘と好みの問題が同じ重みで並ぶ。指示文に次の3つを必ず含める。

1. 各指摘に、2段階の重大度ラベルのどちらかを必ず明記させる。ラベルの語は呼び出し元が指定する（採否を判定するレビューなら「ブロック / 非ブロック」、意見聴取なら「重大な懸念 / 参考意見」など）。
2. 上位ラベルに該当する指摘が一つも無い場合は、その旨を明示させる（「ブロックレベルの指摘なし」等）。言及が無いだけの状態と区別できなくなるため、ゼロの明示は省略させない。
3. ユーザへの報告は、冒頭で上位ラベルの指摘があったかを yes/no で言い切る。yes なら該当内容も併記し、no でも「〜なし」と明示する。