Antigravity CLI (agy) の --print がハングする原因と対処: artifactReviewPolicy
まとめ
- Antigravity CLI (
agy) を--print（非対話）で画像生成に使うと、標準出力が空のまま--print-timeoutすら効かずに固まることがある。 - 真因は設定
artifactReviewPolicyの既定値asks-for-review。生成物（アーティファクト）のレビュー承認をエージェントが待つが、非対話モードには承認する相手がいないので永久に待つ。 ~/.gemini/antigravity-cli/settings.jsonに"artifactReviewPolicy": "always-proceed"を足すと解決する。- 「CLI が不安定」「モデルが重い」と早合点せず、まず設定・公式ドキュメント・ログを見るのが近道だった。
症状
agy --print "<プロンプト>" --model "..." --print-timeout 300s で画像を生成させると、こうなる。
- 標準出力は空のまま。
--print-timeoutを過ぎても終了しない。自分で指定したタイムアウトすら効かない。- 生成物（画像）も出てこない。
厄介なのは、一度だけすんなり成功することもある点だ。おかげで「たまに動く不安定なツール」に見えてしまい、根本原因が覆い隠される。
最初の誤診：「ツールが壊れている」
最初はこう片付けてしまった。重いモデルだから、並行実行が競合したから、CLI が不安定だから。そして生成を諦めて、別経路（API を叩くスクリプト）へ切り替えることを検討した。
だが、症状であるハングを「ツールが壊れている」と結論するのは診断ではない。止まっているなら、”何を待って” 止まっているのかを見ればよかった。
真因：アーティファクトのレビュー承認待ち
手がかりは最初から手元にあった。
- 設定ファイル
~/.gemini/antigravity-cli/settings.json - CLI に同梱されている公式のリファレンス
- changelog
公式リファレンスの設定一覧にこう書いてある。
| キー | 説明 | 既定 |
|---|---|---|
artifactReviewPolicy | エージェントがいつアーティファクトのレビューを求めるか（always-proceed / agent-decides / asks-for-review） | asks-for-review |
toolPermission | ツール実行の確認モード（always-proceed / request-review / strict ほか） | request-review |
既定が asks-for-review。つまりエージェントは画像を生成したあと「これでいい？」と人間のレビューを待つ。TUI（対話）ならそこで承認すれば進むが、--print（非対話）には承認する相手がいない。だから永久に待つ、すなわちハングする。
changelog にも裏付けがあった。
Enabled “always proceeds” mode for subagents to auto approve artifacts, preventing them from hanging when the parent is blocked.
承認待ちでハングするのは、開発側も分かっている挙動だった。答えは手元のドキュメントに載っていたわけだ。
対処
~/.gemini/antigravity-cli/settings.json にポリシーを 1 つ足す。
{
"artifactReviewPolicy": "always-proceed"
}これで生成物の承認待ちをスキップし、非対話でも生成が完了するようになる。
検証
同じプロンプト・同じモデルで、修正前は 7 分待っても 0 出力だった生成が、修正後は 73 秒で画像付きで完走した。”たまに動く” が “必ず動く” に変わり、再現性が出た。
ツール実行そのものの確認である toolPermission も同様に always-proceed にできるが、こちらは「すべてのツールを無確認で実行」に近く影響が広い。画像生成のハングを直すだけなら artifactReviewPolicy で十分だった。
教訓：headless で動かすときは承認ゲートを疑う
エージェント型の CLI は、既定で「危ないこと・確定的なことは人間に確認する」よう作られていることが多い。対話で使う分には安全側で良い設計だが、--print や CI のような headless で回すと、その確認プロンプトが誰にも応答されずに詰まる。
- 非対話で使う前に、レビューや承認まわりの設定（
artifactReviewPolicy、toolPermission、各ツールの--yes相当）を確認する。 - ハングを見たら「壊れている」で片付けず、何を待っているのかをログ・設定・公式ドキュメントで確認する。手元の一次資料を読むだけで解けることは多い。
今回も、諦めて別経路を探すより先に設定を1行見ればよかった、というだけの話だった。同じことをまたやりそうなので、自戒を込めて残しておく。