「Agent terminated early」の対処 — Claude Codeのサブエージェント中断エラー

Agent terminated early due to an API error: <error detail> — Claude Codeでサブエージェントを走らせているときにこう出たら、そのサブエージェントのAPIリクエストが回復不能な形で失敗し、タスクを終える前に止まったことを意味します。コロンの後ろに続く詳細が原因を特定する手がかりです。

「Agent terminated early」の意味

このエラーは、サブエージェントのAPIリクエストが終端的に失敗し、タスクを完了できないまま終わったことを示します。使用量上限への到達や、サーバーエラーでリトライを使い切ったことが典型的な原因です。

表示されるのはClaude Code v2.1.199以降です。それより前は専用のエラー表示がなく、APIエラーのテキストがサブエージェントの成果物としてClaudeに渡っていました。エラーで止まったことに気づけないまま処理が進む失敗の仕方です。v2.1.199以降は、失敗が失敗として返ります。

コロン以降の詳細で原因を切り分ける

エラーメッセージのコロンより後ろに、実際に失敗した理由が続きます。この詳細は、公式のエラーリファレンスにある他の項目の見出しとそのまま対応しています。

詳しい切り分けはClaude rate limitエラーの対処で扱っています。Claude Codeの全体像を先に知りたい場合は、そちらから読むと用語がつながります。

使用量上限系は、種類によって逃げ道が違います。セッション上限と週次上限は全モデルで共有なので、モデルを切り替えても回復しません。Opus上限とSonnet上限はそのモデルファミリーだけが対象で、/modelでファミリー外のモデルに替えれば作業を続けられます。ただしモデルごとにプロンプトキャッシュが別なので、切り替え直後の1回は会話全体を読み直します。

週次の枠は、1回の大きな作業でも尽きます。ワークフローの大量の同時実行のような一度の集中的な作業では、週次の枠がセッション枠のリセット前に尽きることがあります。

フォアグラウンドとバックグラウンドで挙動が違う

同じAPIエラーでも、サブエージェントがフォアグラウンドかバックグラウンドかで、Claudeが受け取る情報が変わります。

フォアグラウンドの「テキストがあれば部分出力」には前段があります。応答が途中で切れ、その時点の部分応答にテキストがありツール呼び出しがない場合、Claude Codeはサブエージェントに続きを促して実行を続けます。これは対話セッションでも同じです。促しを使い切ってはじめて、エラーで終わる扱いになります。

v2.1.199だけは例外で、ツール呼び出しのみで止まったサブエージェントが、打ち切りの注記だけを含む空の部分結果を返していました。それ以降のバージョンでは、この形も「Agent terminated early due to an API error」で終わります。

失敗したサブエージェントは/tasksに残らない

このエラーで終わったサブエージェントを、あとから/tasksで探しても出てきません。成功して完了したバックグラウンドのサブエージェントは、完了扱いで/tasksのリストに30秒残り、詳細ビューも開いたままです。失敗したもの、自分で止めたものはリストから外れます。

画面下のサブエージェントパネルでは、バックグラウンドのサブエージェントの行の扱いが逆向きです。成功した行はすぐ消えてフッターに「/tasks to see subagents」が30秒出ます。失敗した行はその場で30秒残り、選択してxを押せば先に消せます。

中断したサブエージェントを再開する

原因が解消したら、最初からやり直す必要はありません。次の流れで進めます。

SendMessageの再開は、完了したサブエージェントと、ClaudeがTaskStopツールで止めたサブエージェントに効きます。自分で/tasksからxで止めたサブエージェントは自動では再開されず、Claudeが送ったメッセージは拒否されます。パネルにその行が残っているあいだなら、自分でトランスクリプトに入力して再開でき、以後はClaudeからの再開も効きます。

もうひとつ、再開できない型があります。組み込みのExploreとPlanは一度きりの実行で、エージェントIDを返さないため、Claudeは再開できません。これらが途中で落ちたときは、general-purposeかカスタムのサブエージェントで再実行します。

再開が効かない場合は、名前の再利用も疑います。v2.1.199以降は、名前が会話の中で同じサブエージェントを指し続けているかを確認し、別のエージェントが同じ名前を取っていれば送信を拒否します。拒否のエラーには、いまその名前が指す先が書かれます。以前のサブエージェントがまだ動いているなら、スポーン時に受け取ったエージェントIDで宛先を指定します。この確認は現在の会話の範囲で働き、/clearでリセットされます。

サブエージェントの設計や並列実行の考え方はClaude Code Sub-agents完全ガイドにまとめています。エラーメッセージが導入された経緯はClaude Code v2.1.199のリリースノートで確認できます。

止まりにくくする3つの手段と、効かない範囲

再発を減らす手段は3つありますが、それぞれ守備範囲が違います。設定したのに止まったときは、そのエラーが守備範囲の外にないかを見ます。

フォールバックモデルは、v2.1.247以降、サブエージェントにも効きます。それより前は、チェーンが対象とする失敗でもサブエージェントが終了していました。チェーンが対象とする失敗にサブエージェントが当たると、Claude Codeは受け付けてくれる最初のモデルに切り替え、サブエージェントはエラーで終わらず作業を続けます。チェーンはカンマ区切りで並べ、3モデルまでです。

claude --fallback-model sonnet,haiku

v2.1.287のclaude --helpでは、このオプションは「デフォルトのモデルが過負荷または利用不可のときに、指定したモデルへ自動でフォールバックする。カンマ区切りで順に試す。各ユーザーターンの冒頭で主モデルを試し直す」と説明されています。切り替えはそのターンだけで、次のメッセージでは主モデルから再開します。毎回設定したくなければ、settingsのfallbackModelに配列で書きます。

コロン以降が429系や使用量上限なら、フォールバックを設定していてもこのエラーで止まります。

無人運用では、リトライの監視が効きます。

export CLAUDE_CODE_RETRY_WATCHDOG=1

これを設定すると、失敗にせず5分を上限に間隔を広げながら再試行し続けます。応答にレート制限のリセット時刻が付いていれば、リセットまで待ちます。使用量上限に当たったセッションは、残りの時間を待ち切る動きになります。

一方で、標準速度のリクエストが「支出上限に達した」または「利用クレジットが尽きた」という429を返したときは、すぐに失敗します。ゲートウェイ側の支出上限が定期的にリセットされる場合も同じです。v2.1.239より前は、これも延々と再試行していました。

監視を有効にしていれば、サーバーエラー・タイムアウト・接続断のような他の一時的なエラーも、v2.1.199以降は既定の再試行回数が300回に上がります。バックオフの合計は約3時間です。CLAUDE_CODE_MAX_RETRIESを明示した場合も、15回の上限が外れます。環境変数の一覧はClaude Code環境変数リファレンスにあります。

対話セッションで使用量上限に当たったときは、別の逃げ道があります。claude.aiのサブスクリプションでサインインしていれば、v2.1.234以降はセッションを開いたまま待ち、リセット後に中断したタスクを自動で続けます。待機中は「Usage limit reached」と、続行する時刻を示す行が画面下に出ます。待機後に失敗したサブエージェントの続きが要るときは、あらためて再開を頼みます。この自動続行は/configの「Continue automatically at usage limit」でオフにでき、待機中はEscか/rate-limit-optionsで取り消せます。

よくある質問

「Concurrent subagent limit reached」とは違いますか

違います。「Concurrent subagent limit reached」は、同時に動くサブエージェントが既定の20を超えたときに出るエラーで、APIエラーではなく同時実行数の上限そのものです。Claudeには再試行しないよう伝えるエラーが返ります。v2.1.217以降、この上限はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで変更でき、ultracode使用中のセッションでは適用されません。「Agent terminated early due to an API error」はAPIリクエストの失敗が原因で、原因の層がまったく別です。

まとめ

コロン以降の詳細が使用量上限なら、待つかモデルファミリーを替える。サーバーエラーならフォールバックかリトライの設定が効く。レート制限と課金のエラーには、フォールバックは効かない。この3分岐を先に決めてから、サブエージェントの再開に進むのが最短です。