# AIエージェントから別のコーディングCLIへ安全に委譲するMD 監督役のAIエージェント（Claude Code 等）から、実装役のコーディングCLI（Codex CLI 等）へ Bash 経由でタスクを委譲するときの、**沈黙して死なない**呼び出し方。そのまま読ませれば適用できる粒度で書いてある。委譲そのものの是非ではなく「渡し方」の話。 --- ## 結論（これだけ守れば足りる） 1. **指示は必ずファイルで渡す。argv に置かない** 2. **TTY を渡さない**（stdio を全て pipe にするか、stdin をファイルからリダイレクトする） 3. **上限時間を必ず付ける**（既定30分程度） 4. **出力を `| tail` / `| head` に流さない** 推奨形（ラッパー経由）: ``` node <ツール置き場>/agent-do.mjs --prompt-file <指示ファイル> --cwd <対象パス> --timeout 1800 ``` 直に叩く場合: ``` <コーディングCLI> exec -s workspace-write - < prompt.md ``` --- ## なぜ（実際に起きた事故）委譲が **丸1日（実測 1日00時間57分）hang** し、翌日まで誰も気付かなかった。調べると同型の hang が他に2本（1日 / 19時間）過去セッションから生き残っていた。 **前から起きていたのに気付けていなかった**。死因は委譲先ではなく**呼び出し方**で、 3つ同時に起きていた。 ### 死因1: argv で渡すとシェルが指示文を実行する次の形で渡した: ``` -lc ' exec --sandbox workspace-write "$(cat prompt.md)"' ``` 指示文の中でファイル名やテーブル名をバッククォートで囲んでいたため、それが **コマンド置換として実行**された。実際に届いた指示は: - 「新規ファイル　を1つだけ作成する」＝**作るべきファイル名が消えている** - 参照用に名前を書いただけの既存スクリプトが**起動**し、その標準出力が **指示本文に混入**していた - ログには `command substitution: syntax error near unexpected token` や `<テーブル名>: command not found` が並ぶ `"$(cat f)"` は理屈上は再展開されない。しかし**シェル層が2重になると実際に展開された** （コンテナ/WSL などのランチャー → `-lc` の順で重なるケース）。理屈で安全と判断せず、**シェルを1層も通さない経路**にすること。 ### 死因2: TTY 付きで起動すると stdin 待ちで永久に眠る多くのコーディングCLIは、端末が繋がっていると追加入力を待つ（`Reading additional input from stdin...` 等を出したまま止まる）。 `ps` の `stat` が `Ssl+` になっているのが目印で、末尾の `+` が「TTY のフォアグラウンドプロセスグループ」を意味する。誰も打たないので永遠に終わらない。 ### 死因3: `| tail` でパイプすると進捗が1行も見えないパイプはバッファされるため、完了するまで何も出力されない。 **hang しているのか実行中なのか区別できなくなる**。背景実行してログファイルを直接読むこと。 --- ## 実装（ラッパー側の要点）子プロセス起動時: ```js const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] }); // TTY を渡さない const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeoutSeconds * 1000); child.stdout.on('data', (c) => process.stdout.write(c)); // そのまま流して進捗を見えるようにする child.on('close', (status) => { clearTimeout(timer); resolve({ status: timedOut ? 124 : status }); }); child.stdin.end(prompt); // ← 必ず閉じる。閉じないと相手が待ち続ける ``` - `--prompt-file` を受け、`fs.readFileSync` した中身を指示とする（argv 経由を廃止する） - `--timeout <秒>` を受ける。既定 1800。タイムアウトは exit 124 で区別できるようにする - 「差分が無い＝書き込めていない」といった事後判定をしている場合、 **タイムアウト時はその判定に落とさない**（別の失敗として扱う） --- ## 診断（返ってこない時） ``` ps -eo pid,etime,stat,args | grep '[a-z]*cli-name' ``` - `stat` の末尾に `+` → TTY のフォアグラウンド。入力待ちの hang を疑う - `etime` が時間・日単位 → 明らかに死んでいる。kill してよい - 定期的に見るのではなく、**上限時間で自動的に切れる**ようにしておくのが本筋 --- ## 機械的に強制する（推奨）ルールを文書に書くだけでは守られない。エージェントのフック機構（コマンド実行の直前に割り込める仕組み）で、危険な形を検出して警告する。検出する形: | 検出名 | 条件 | なぜ危険か | |---|---|---| | `shell-wrapped` | `bash -lc` / `sh -c` を経由している | シェル層が増えバッククォート・`$()` が展開される | | `argv-prompt` | `exec` の後に `-`(stdin) も `<`(リダイレクト) も無い | 指示が argv に置かれている | | `backtick-in-argv` | コマンドに `` ` `` か `$(` があり、ファイル/stdin 経由でない | シェルに実行される | | `piped-output` | 出力を `\| tail` / `\| head` に流している | バッファされ hang と区別がつかない | | `no-timeout` | `--timeout` も `timeout <数値>` も無い | 無限待ちを止める上限が無い | **ブロックはせず警告に留める**（正当な例外を殺さないため）。警告文には必ず **正しいコマンドの完成形**を併記する。書き換え先を示さない警告は無視される。 ### 落とし穴: 正しい使い方を罰しないラッパーが既定タイムアウトを内蔵しているなら、**ラッパー利用時は `no-timeout` を鳴らさない**。推奨した使い方で毎回警告が出る gate は、すぐ読まれなくなる。回帰テストで固定しておくこと。 ### 既存の誘導も直す同種のフックやドキュメントが**古い argv 形を例示していないか**を必ず確認する。今回、別のフックが出す推奨コマンドが argv 形（＝事故そのものの形）のままで、ルールを配っても逆方向に誘導し続ける状態だった。 --- ## 検証のしかた **実際に事故ったコマンド文字列をフックに食わせ、検出できることを確認する。** テストケースを想像で書かず、事故の実物を回帰テストにする。最低限のテスト: - 推奨形（ファイル渡し + timeout）→ **何も出力しない** - argv 渡し → 検出する - シェル経由 → 検出する - `| tail` → 検出する - タイムアウト無し（ラッパー未使用時のみ）→ 検出する - 無関係なコマンド / 対象外のツール名 → 何も出力しない - 壊れた入力 → 例外を握りつぶして exit 0（フックが本体を止めない） --- ## 委譲先の生成物は必ずレビューする呼び出し方を直しても、委譲先が指示どおり書くとは限らない。実例: 「必須項目リストから X を外す」と指示したのに、リストに X を残したままフォールバック処理を書き足し、**先に例外が飛ぶので後段が死にコード**になっていた。構文チェックもテストも通るため、読まないと気付けない。 **受け入れ前に必ず:** - 依頼したスコープ外のファイルを触っていないか（差分の**削除行まで**読む） - 指示した条件が本当に反映されているか（「それっぽい実装」で満足しない） - 実際に**動かして**出力を目視する ---