◉ANTIGRAVITY LABEN
記事一覧/Agents & Manager
◈ Agents & Manager/2026-08-17中級

サブエージェントが完了せず止まるとき、親側の未承認アーティファクトを先に確認する

サブエージェントに任せた工程が朝まで終わっていない。原因が子ではなく親の承認待ちだったときの切り分け方を、ログから滞留を洗い出す短いスクリプトと、公式ドキュメントにある承認の仕組み、自動承認をどこで止めるかの判断とあわせてまとめました。

サブエージェント4承認ログ個人開発127エージェント運用22

夜のうちにリリース前の確認をエージェントへ渡して、朝に結果を見ます。個人開発でアプリを何本も抱えていると、この回し方に頼る日が増えます。工程を分けてサブエージェントへ委ねれば、寝ている間に一巡してくれるはずでした。

その朝、画面はまだ動いている顔をしていました。スピナーは回っていて、エラーも出ていません。ただ、最後の出力の時刻が 30 分以上前で止まっていました。

サブエージェント側のログを開いて、原因を探しました。異常な行は見当たりません。モデルもツールも、待っているだけです。

見るべき場所を間違えていました。止まっていたのは子ではなく、親のほうでした。そう気づいたのは、子のログを 30 分近く読み込んだあとです。同じ朝を迎えた方が数分で「親か子か」を見分け、次の夜に同じ止まり方をしないよう、そのとき組み直した手順を書き残します。

承認を待っているのが親なら、子はどれだけ健全でも進めません

サブエージェントが親から委譲を受けて走るとき、生成したアーティファクトの扱いは親の側に返る——私の環境で観察した限りでは、そう見えました。公式の説明を確認できた挙動ではない点はご承知おきください。その親が別の確認ダイアログを出したまま止まっていると、子から戻ってきた承認要求は処理される順番が回ってきません。

子のログには「待っている」以外の情報が出ません。エラーではないので、タイムアウトも発火しないことがあります。結果として、誰にも気づかれないまま朝まで残ります。

公式ドキュメント(サブエージェントの説明ページ)によると、サブエージェントのツール呼び出しに許可が必要なとき、その要求は「メイン UI かサブエージェントのパネルに自動で上がってくる」仕組みです。承認待ちの子がいるときは、Alt+J で次の承認待ちのサブエージェントの詳細へ移動でき、Ctrl+K で保留中の承認をその場で通せます。v2.23.0(2026 年 10 月)では、配下のサブエージェントが承認を待っている会話にサイドバーで印が付くようになりました。つまり、承認待ちは画面のどこかには出ています。ただ、夜のうちに誰も見ていなければ、その表示は誰にも届きません。

ショートカットや表示の位置はバージョンで変わることがあります。ここに書いたのは 2026 年 11 月時点(アプリ v2.32 系)で公式の説明と照らした内容です。お使いの版では、キーボードショートカットの一覧で確かめていただければと思います。

同じ「終わらない」でも、フックの待ち方に起因するものは切り分けの順序が違います。そちらはフックの待ち方が 2.6.0 で変わりました。終わらないターンを切り分ける手順に分けて書いています。今回扱うのは、フックを使っていなくても起きるほうです。

朝いちばんの 5 分で確かめる順番

ログを開く前に、画面だけで分かることがあります。私はいま、次の順で見ています。

  1. サイドバーの印: 承認待ちの印が付いている会話があるか。親の会話に付いていれば、配下のどこかが待っています
  2. Alt+J で移る先: 押して最初に開くのがどのサブエージェントか。移った先の要求内容が、そのまま最初の手がかりです
  3. 最後の出力の時刻: スピナーではなく、最後に本文やツール結果が出た時刻。30 分以上動いていなければ、待っていると見なします
  4. 親の会話の末尾: 親自身が確認ダイアログを出していないか。ここを見落とすと、健全な子のログを読み続けることになります

この 4 つで決まらないとき、あるいは階層が深くて画面で追いきれないときに、次のスクリプトを使います。

滞留している会話をログから洗い出す

目視で追うのは、階層が二段を超えたところで無理になります。私はログを機械的に走らせて、承認要求を出したまま次のイベントが来ていない会話と、その「根元」を出すようにしました。

次のスクリプトは、ログの各行に会話の識別子(conversation_id)、親の識別子、log_uri、ツール名が入っている前提で書いています。これらの項目名は私が自分のログ出力に合わせて決めたもので、公式が公開しているスキーマではありません。手元のログの形が違えば、読み替えてください。親子の突き合わせが勘ではなく識別子でできる、という考え方だけを持ち帰っていただければ十分です。

先に、自分のログに実際どのイベント名が出ているかを確かめてください。イベント名もバージョンで変わります。

# types.py — 手元のログにどの type が出ているかを数える
import json, sys, collections
 
c = collections.Counter()
for line in sys.stdin:
    line = line.strip()
    if not line:
        continue
    try:
        ev = json.loads(line)
    except json.JSONDecodeError:
        continue
    c[ev.get("type", "(type なし)")] += 1
 
for k, v in c.most_common():
    print(f"{v:>5}  {k}")

ここで得た名前を、次のスクリプトの判定に入れます。承認要求を記録し、解決または結果が来たら消します。最後まで残ったものが滞留です。そのうえで、親を辿って「承認待ちのまま残っているいちばん上の会話」を根元として出します。

#!/usr/bin/env python3
"""stream-json の行を読み、承認待ちのまま止まっている会話と、その根元を洗い出す。"""
import json, sys
from datetime import datetime, timezone
 
PENDING = {}   # conversation_id -> (時刻, 待っているツール名)
LAST    = {}   # conversation_id -> 最終イベント時刻(ハートビートを含む)
PARENT  = {}   # 子 conversation_id -> 親 conversation_id
LOGURI  = {}   # conversation_id -> log_uri
 
def ts(v):
    return datetime.fromisoformat(v.replace("Z", "+00:00"))
 
for line in sys.stdin:
    line = line.strip()
    if not line:
        continue
    try:
        ev = json.loads(line)
    except json.JSONDecodeError:
        continue    # 途中で切れた行は捨てる。走行中のログでは普通に起きます
 
    sub = ev.get("subagent_info") or {}
    cid = sub.get("conversation_id") or ev.get("conversation_id")
    if not cid or "timestamp" not in ev:
        continue
    if sub.get("log_uri"):
        LOGURI[cid] = sub["log_uri"]
    if sub.get("parent_conversation_id"):
        PARENT[cid] = sub["parent_conversation_id"]
 
    t = ts(ev["timestamp"])
    LAST[cid] = t
 
    kind = ev.get("type")
    if kind == "approval_request":
        PENDING[cid] = (t, (ev.get("tool_info") or {}).get("name", "unknown"))
    elif kind in ("approval_resolved", "result"):
        PENDING.pop(cid, None)
 
def root_blocker(cid):
    """親を辿り、承認待ちのまま残っているいちばん上の会話を返す。"""
    top, seen = cid, {cid}
    while PARENT.get(top) in PENDING and PARENT[top] not in seen:
        top = PARENT[top]
        seen.add(top)
    return top
 
now = max(LAST.values()) if LAST else datetime.now(timezone.utc)
rows = sorted(
    ((round((now - t).total_seconds()), cid, tool,
      PARENT.get(cid, "-"), root_blocker(cid), LOGURI.get(cid, "-"))
     for cid, (t, tool) in PENDING.items()),
    reverse=True,
)
 
if not rows:
    print("承認待ちで滞留している会話はありません")
    sys.exit(0)
 
print(f"{'wait_s':>7}  {'conversation_id':<16} {'tool':<11} {'parent':<16} {'root':<16} log_uri")
for sec, cid, tool, par, root, uri in rows:
    print(f"{sec:>7}  {cid:<16} {tool:<11} {par:<16} {root:<16} {uri}")
 
roots = sorted({r[4] for r in rows})
print("\n→ 先に開く会話: " + ", ".join(roots))
sys.exit(1)   # 滞留ありは 1。朝の定期実行で通知の条件に使えます

前の版では、滞留の一覧を出すところで止めていました。根元を出すようにしたのは、孫まで滞留した朝に、一覧の 3 行をどれから開くかでまた迷ったからです。並びの順位ではなく、根元の列を見れば開く会話が一つに決まります。

冒頭の朝と同じ形のログ(親・子・孫の三段)を作り、Python 3.10.12 で流すと次の出力になりました。

 wait_s  conversation_id  tool        parent           root             log_uri
   2029  conv-parent-01   write_file  -                conv-parent-01   -
   1978  conv-child-a     write_file  conv-parent-01   conv-parent-01   file:///logs/conv-child-a.jsonl
   1940  conv-grand-a1    run_command conv-child-a     conv-parent-01   file:///logs/conv-grand-a1.jsonl

→ 先に開く会話: conv-parent-01

親は 2,029 秒、子は 1,978 秒、孫は 1,940 秒。差はそれぞれ 1 分足らずです。子も孫も、自分の要求を出してからほぼずっと、上の段に足を止められていたことになります。終了コードは 1 でした。

親の承認だけを解決した行を足して流し直すと、出力はこう変わります。

 wait_s  conversation_id  tool        parent           root             log_uri
   2048  conv-child-a     write_file  conv-parent-01   conv-child-a     file:///logs/conv-child-a.jsonl
   2010  conv-grand-a1    run_command conv-child-a     conv-child-a     file:///logs/conv-grand-a1.jsonl

→ 先に開く会話: conv-child-a

ここが、私がいちばん取り違えていたところです。親を片づければ全部が流れると思っていましたが、子は子で自分の要求を出したまま残ります。根元が一段下りるだけです。三段すべてを解決した行を足すと「承認待ちで滞留している会話はありません」と出て、終了コードは 0 に戻りました。子だけを再実行しても、この状態は解けません。

書き込み中のログに対しても、そのまま流せます。コピーを指すか、末尾を流し込んでください。途中で切れた最終行は捨てられるので、走行中でも止まりません。終了コードを 0 と 1 で分けてあるので、朝の定期実行に組み込んで、1 のときだけ通知を出す使い方もできます。

このスクリプトがあえて見ていないものにも触れておきます。ハートビートは、作業が進んでいなくても最終イベントの時刻を新しくします。上のログでも、親は 18:35 にハートビートを出しています。「直近に動きがある」だけでは判断材料になりません。ここで滞留と数えるのは、解決されていない承認要求だけです。

なお、ここで流したログは、上の前提に合わせて私が自分で組み立てたものです。数値は実際にスクリプトを走らせて得た値ですが、製品の本番実行から採取した記録ではありません。

症状から手を入れる場所を決める

まず確認しておきたいのは、サブエージェントが親の許可スコープとサンドボックス設定を引き継ぐという点です(公式のサブエージェントの説明より)。子が通れない操作は、親の設定を見直すことで解消できる場合があります。

承認ルールが原因の停止でなければ、手順は単純です。根元から順に承認ダイアログを片づければ、子は続きから進みます。止まっていたのが順番待ちだけだったなら、朝の 30 分はそこで戻ってきます。

深さも関係します。v2.6.0(2026 年 8 月 7 日)で、サブエージェントを止めると孫以下のネストした子とそのバックグラウンド処理まで止まるようになりました。止めるときの影響範囲が深さに及ぶ以上、止まっている原因も深さごとに識別子で辿れたほうが安全です。

症状滞留スクリプトの出方確かめ方手を入れる場所
子だけが止まり、親は動いている子のみ滞留。root が子自身Alt+J で移った先の要求内容を読む子の要求を判断する。ツール権限を見直す
親子が同時に止まっている親と子が近い秒数で並び、root が親親の会話の末尾にダイアログが残っていないか見る親の承認を先に解決し、続けて子を解決する
孫以降で止まる三段以上が並び、root がいちばん上を指すroot を解決して再実行し、root が一段下りるか見るroot から一段ずつ解決する
同じ確認が何度も出る滞留は出るが秒数が短く入れ替わる同じツール名が繰り返し並ぶか見る承認ルールの一致条件を見直す
スピナーは回るが何も出ない「滞留なし」と出る最終イベントがハートビートだけか確かめる承認以外の原因(フック・ネットワーク)を疑う

最後の行は、このスクリプトの守備範囲の外です。滞留なしと出たのに止まっているなら、承認の問題ではありません。その場合は冒頭で触れたフックの記事の切り分けへ進んでください。

よくある誤解

「スピナーが回っていれば、作業は進んでいる」と思っていました。 実際には、承認待ちの間もスピナーやハートビートは動き続けることがあります。私が見るのは最後の出力の時刻と、解決されていない承認要求だけです。

「止まった子を再実行すれば直る」も、よく聞く誤解です。 上の実測のとおり、親が承認待ちのままなら子をやり直しても同じ場所で待ちます。再実行は、それまでの子の作業を捨てるぶんだけ損です。

「親の自動承認を広げれば、子も止まらなくなる」は、半分だけ正しい見方です。 子は親の許可スコープを引き継ぐので、止まる回数は確かに減ります。ただ、それは「人が判断する場面」を夜のうちに手放すことでもあります。止まらなくなることと、止まるべき場面で止まることは別の話です。

自動承認をどこで止めるか

便利さと引き換えに、承認をひとつ手放す変更です。私はここを一律には決めませんでした。

やり方夜のうちに進む範囲朝に残る判断向いている作業
すべて手動で承認最初の承認要求まですべて初めて任せる工程・権限の範囲が読めない工程
成果物の出る先で線を引いて自動承認作業ディレクトリの中に閉じた処理外へ出るもの・署名・資格情報夜に回す定型の確認やビルド前の下書き
すべて自動で承認最後までなし(事後の確認だけ)壊れても捨てられる使い捨ての環境

私が選んでいるのは真ん中です。夜に任せてよいのは、朝に捨てて作り直せるものだけ。 判断に迷う工程は、この一文に照らして決めています。

線を引いたのは、成果物が出る先です。作業ディレクトリの中に閉じた生成物であれば、自動承認にしています。読み取りと解析、下書きの生成、比較用の一時ファイル。壊れても捨てて作り直せます。

私自身、ひとりで作っている以上、誤った成果物を止めてくれる第二の目がありません。その役目を、この線引きに肩代わりしてもらっています。

一方で、リポジトリの外へ出るもの、署名や配信に関わるもの、資格情報を触るものは、朝の自分に判断を残しました。夜のうちに片づく気持ちよさより、朝に取り返しがつくことのほうを取っています。

判断が難しいのは、承認ルールの一致条件が思ったより広い場合です。自動承認の範囲を決めたつもりでも、ルールの書き方によっては意図より広く通ってしまいます。私はここで一度痛い目を見ていて、その棚卸しの手順は何にも一致しないつもりの1行が、全コマンドを承認していましたにまとめました。自動承認を広げる前に、いま通っている範囲を確かめておくほうが安全です。

承認待ちを解いたあとに当たること

根元を解決して流れ出したあと、次に当たりやすいのは二つです。

一つは、同じ確認がまた出て、また止まることです。一致条件の問題であることが多く、Antigravity の許可ダイアログが何度も表示される・「常に許可」が効かないときの診断と解決の手順で確かめられます。

もう一つは、そもそも夜の工程をここまで深く分けるべきだったか、という問いです。三段のサブエージェントは、止まったときに解く手間も三段になります。並列や多段にする前の判断は、Orchestrator・/swarm・/run-workflow を作業の形で選び分けるに書きました。私は、承認待ちが二回続いた工程は一段浅くできないかを見直すようにしています。

明日の朝のために置いておくもの

止まった朝に慌てないための備えは、三つで足ります。

  1. 滞留スクリプトを、実行ログの出力先と同じ場所に置きます。朝いちばんに走らせるだけで、開く会話が一つに決まります
  2. ログに含まれる log_uri を控える運用にします。滞留した子のログへ、探さずに飛べます
  3. 自動承認の範囲を、成果物の出る先で書き出しておきます。判断を毎回やり直さずに済みます

止まっている場所を最初に取り違えると、健全なほうのログを 30 分読むことになります。私はそれをやりました。次の朝は、まず root の列を見てください。

まずは今夜、滞留スクリプトを置く場所を一つ決めてみていただければと思います。明日の朝、最初に開くのが根元の会話になるだけで、止まった朝の景色はずいぶん変わります。

シェア

お読みいただきありがとうございます

Antigravity Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ(¥150)で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

◈ Agents & Manager2026-11-14
通ったはずのエージェントの PR が翌週また直されていた。マージ後14日で残った行を git blame で数える
エージェントの PR はレビューを通りやすいのに、マージ後すぐ同じ箇所が書き直されることがあります。コミットが足した行のうち14日後にも残っている割合を git blame で数えるスクリプトと、日付の並びで数字がずれる落とし穴、止める位置の決め方をまとめました。
◈ Agents & Manager2026-10-25
空き容量 11MB で無人ジョブが止まりました。du が数えたのは 59MB だけで、残りの約 9GB は見えない場所にありました
エージェントを無人で走らせる前に、書き込み先の空きを測って止める bash スクリプト 2 本の全文です。du と df の数字が噛み合わない理由と、自分では片付けられない空き不足の見分け方も書きました。
◈ Agents & Manager2026-10-24
pipefail を足したら、通るはずの検査が赤になりました。出力が 8 KB を超えた日から起きる誤検知と、終了コードの確かめ方
pipefail を足すと、通るはずの検査が赤になることがあります。出力が 8 KB を超えると起きる誤検知を 1,122 本のリポジトリで再現し、ファイル経由の実行ラッパーとカナリアまでを残します。