Claude Opus 5.5のエージェントが途中で止まるのを防ぐ設定

複数の手順からなるタスクをClaude Opus 5.5に無人実行させていると、残りの作業があるのに途中でぴたりと止まることがあります。原因は、Opus 5.5が長いタスクの途中でも進捗をテキストだけの応答で返すことがあり、それが完了時と同じstop_reason: "end_turn"で返ってくる点にあります。対処は、この応答をタスク完了の証拠として扱わないハーネス設計と、早期終了そのものを減らすプロンプト設計の2方向に分かれます。以下では、それぞれを具体的な指示文の例つきで紹介します。

Opus 5.5が「完了しました」と言って実は終わっていない理由

Claude Opus 5.5は複数の手順からなる長いタスクを進めるとき、作業の合間にユーザー向けの進捗更新を返します。無人実行(unattended agentic run)とは、人が都度確認や指示を返さずにエージェントを動かす運用です。

その進捗更新の一部は、ツール呼び出しを伴わないテキストだけの応答として終わり、通常の完了時と同じstop_reason: "end_turn"で返ってきます。end_turnは「モデルの応答がひと区切りついた」ことを示すだけで、タスクが完了したことの証拠ではありません(stop_reasonの種類とエラーとの違いはstop_reasonとエラーの違いにまとめています)。無人実行のループが「end_turn=タスク完了」と単純に判定していると、モデルが途中経過を報告しただけのターンでループが止まり、残りの手順が実行されないまま終わります。

API仕様の側から見ると、stop_reasonの一覧にあるend_turnの説明は「Claudeが応答を自然に終えた」で、対処は「応答を使う」です。ツール呼び出しで終わるtool_use、サーバーツールのループが反復上限に達したpause_turn、max_tokensなどは別の値として返ります。単発の応答なら、これで足ります。長いエージェントループでは、同じ分岐が早期終了の入口になります。

テキストだけで終わるend_turnを「報告」として扱う

最初に直すのは、end_turnを受け取ったあとの判定です。テキストだけで終わるターンを「タスク完了の証拠」ではなく「進捗の報告」として扱い、次の4段で確かめます。順序は、確認の軽いものから並べた一例です。

判定を変えるだけでは、モデルは動き出しません。次のユーザーメッセージを送るところまで実装して、はじめて続行します。以下、段ごとの中身です。

動いている処理があれば、完了を待つ

end_turnで終わったターンの時点で、モデルが起動したバックグラウンドコマンドやサブエージェントが動いていることがあります。この場合は完了扱いにせず、処理が終わるのを待ってから、出力を次のユーザーメッセージとしてモデルに返します。

チェックリストが見るのは、モデルが未完了と申告した項目です。こちらの判断材料は、ハーネスが把握している実行中の処理です。待って出力を次のユーザーメッセージで返さないと、モデルは結果を踏まえた次の判断に進めません。

チェックリストの残りを継続メッセージで返す

タスクの各部分を、to-doツールかファイルでモデル自身に更新させます。ターンが終わった時点で未完了の項目が残り、モデルがブロッカーを述べていなければ、短いユーザーメッセージで続行を促します。公式ガイドの英文例を日本語に直すと次のとおりです。

タスクリストにまだ未完了の項目が残っている。残りの2つのエンドポイントの移行と、そのテストの更新だ。続きに取りかかること。途中で止まる項目があれば、何が妨げになっているかを述べること。

エンドポイント移行を想定した例ですが、型としては3点です。残っている項目を名指しする。続行を指示する。ブロッカーがあれば申告させる。「続けて」の一言より、モデルが何に取りかかればよいかを迷いません。

完了条件を別のモデルに照合させる

完了条件をあらかじめ決めておき、ターンが終わるたびに別の小型モデルへ条件と会話を渡す方式もあります。たとえば「指定した全エンドポイントのテストが通ること」を渡しておけば、小型モデルは会話の履歴を見て、条件を満たしたかどうかを返します。満たしていなければ、その理由が次のユーザーメッセージになります。

チェックリスト方式では、残りの項目を数えるのがモデル自身の更新です。この方式では判定する役が別のモデルになり、そのぶん判定用のリクエストがターンごとに増えます。

自動継続は2〜3回で止める

どちらの方式でも、同じタスクの自動継続は2〜3回までです。本当に行き詰まっている実行を繰り返し再試行させ続けないためで、上限に達したら実行を終え、人が内容を見直せるようにします。

止まってはいないのに何も表示されないとき

早期終了とは別に、ターンは続いているのに画面が静かなまま、という症状もあります。原因も対処も別なので、切り分けてから手を付けます。

進捗の通知はthinkingブロックで届く

Opus 5.5は、ツール呼び出しの合間に、いま分かったことと次にやることを短く書きます。Opus 5ではtextブロックだった合間の文章が、Opus 5.5ではprogress-updateのthinkingブロックで返ります。1回のツール呼び出しの前に付くのは最大1つで、モデルが省くこともあります。

既定のthinking.displayは"omitted"で、このブロックのthinking欄は空です。textブロックだけを描画するクライアントは、長いターンのあいだ無音に見えます。エラーにはならないので、気づきにくい変化です。display: "updates"を指定すると、推論は隠したまま進捗の要約だけが返ります。

通知そのものが減る場合

公式のthinkingのページには、これらのモデルはeffortが高いときや、ツール連鎖が長いときに、進捗の通知を書く回数が減る、とあります。画面に出す設計をそれだけに頼ると、長い実行ほど静かになります。そこで公式ガイドは、ハーネスから催促する方法を挙げています。

display: "updates"を指定したうえで、ツール呼び出しが続いているのに、読めるものが何も出なかったステップ(textブロックもprogress-updateの本文もない)を数えます。公式の例は5回です。その回数に達したら、最新のツール結果の後ろにリマインダーを足します。

しばらくユーザーに連絡していない。いま何をしているかを一言で伝えてから、作業を続けること。

これは公式ガイドの英文リマインダーを日本語に直したものです。付け方に決まりがあります。

• ターン限定のシステムメッセージ(role: "system"にclear_at: "next_user_message")として、ツール結果の後ろに足します。ベータ機能で、mid-conversation-system-clear-at-2026-08-21のbetaヘッダーが要ります。
• 古いリマインダーは消さず、そのまま残します。後ろに新しいユーザーメッセージ(tool_resultだけのものを含む)が来ると描画されなくなり、入力トークンにも数えられません。履歴を書き換えないので、プロンプトキャッシュも後続のthinkingブロックも有効なままです。
• それでも静かなら、リマインダーは2〜3回で打ち切ります。

{
  "role": "system",
  "clear_at": "next_user_message",
  "content": "しばらくユーザーに連絡していない。いま何をしているかを一言で伝えてから、作業を続けること。"
}

Anthropicの検証では、エージェント的なコーディングのタスクで、長い無音区間が出たタスクの割合がおよそ半分になり、コストへの測定できる変化はなかったとされています。

システムプロンプトに終了条件を追加する

ここまでの継続メッセージはハーネス側の対処です。早期終了そのものの頻度を減らすなら、システムプロンプトに、避けたい終了の型を具体的に名指しする指示を加える方法もあります。

Opus 5.5は「次の一手を予告する要約で終える」のような、避けたい終了の型を名指しされると応答しやすいモデルです。「ユーザーの入力なしには前に進めない場合」のように、止まってよい型も併せて示すと効果が上がります。

公式ガイドは、完全放置のハーネス向けの指示文を英文で1つ挙げています。日本語に直すと次のようになります。そのまま使うのではなく、自分のアプリケーションに合わせて調整する出発点として示されたものです。

これは、作業を任せているユーザーからの恒常的な指示で、あなたのターンの終え方に関するものだ。ツール呼び出しを含まないメッセージを返すとターンは終わり、続行を求められるまで作業は止まる。ユーザーはこれまで、頼んだ作業が残っているのにターンが終わる場面を4つの型で見てきており、そのどれも望んでいない。
1つ目は、済んだ作業の長い要約を書き、最後に次の手順を予告して終えるが、ツール呼び出しがないので次の作業が始まらない型だ。
2つ目は、ユーザーが望まなければ続けると申し出て、返ってくる見込みのない返事を待って止まる型だ。
3つ目は、あなた自身の見立てでも残りの作業を止めていない判断事項を、ユーザー向けに並べる型だ。
4つ目は、ターンが長くなったことやマイルストーンを終えたことを理由に、ここで報告するのがよいと判断する型だ。
状況メモは歓迎するし、未決事項へのあなたの推奨も歓迎する。ただし次のツール呼び出しと同じメッセージに入れ、ユーザーの答えに依存しない作業はそのまま進めること。
ユーザーに進路変更を促したり、待つと申し出たりしている自分に気づいたら、その部分を消して次の作業に移ること。
ユーザーが望む停止は、ユーザーなしでは何も進められない場合と、あなたを止めているものが意図的に保護されている場合だけだ。
この指示は、危険な操作や破壊的な操作に確認を求める決まりを上書きしない。

displayの指定は、thinkingの設定にこう書きます。Opus 5.5は適応型の思考が前提なので、typeはadaptiveです。

"thinking": {
  "type": "adaptive",
  "display": "updates"
}

クライアントでのブロックの描画は、移行ガイドの「ツール呼び出しの合間のテキスト」の節に手順があります。非空のthinkingブロックを、対応するtool_useブロックの前に出し、ブロックはほかの内容と一緒に変更せずに返します。

Claude Codeで無人実行を組むときの関連設定

Claude CodeをCLIで無人実行する場合、Messages APIを直接呼ぶハーネスとは実装の層が異なりますが、狙いは重なります。公式の環境変数の一覧で、関係するものは3つです。

1行目は、リモートのセッション一覧のような、状態を見張るホストが途中で「入力待ち」と表示するのを避ける設定です。v2.1.269以降の既定では、バックグラウンドエージェントやワークフローの実行中は、ターンが終わっても実行中の状態が続きます。0にすると、ターンの終わりごとにidleを報告します。バックグラウンドのシェルコマンドは、開発サーバーのようなものを含め、この状態を保持しません。詳しくはCLAUDE_CODE_BG_TASKS_REPORT_RUNNINGで非対話セッションの状態報告を切り替えるで扱っています。

2行目はCLAUDE_AUTO_BACKGROUND_TASKSが有効なときに働きます。CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDSが未設定なら、催促は出ません。設定の手順はClaude Codeでサブエージェントの確認間隔を設定するにあります。

終わった項目を後から確かめるなら、/tasksが現在のセッションのバックグラウンド処理を、完了したサブエージェントまで含めて一覧にします。使い方はClaude Codeの/tasksコマンドでサブエージェントの完了を確認するで、サブエージェントに何をどう報告させるかの設計はClaude Codeのエージェント設計パターンの報告フォーマットの章が参考になります。

まとめ

無人実行で止まるときは、まずend_turnをタスク完了の証拠にしている分岐を疑います。残項目が数えられる実行ならチェックリストと継続メッセージを、完了条件が言葉にできる実行なら別のモデルでの照合を足し、どちらも2〜3回で打ち切ります。

画面が静かなだけなら、止まっているのではなく通知が届いていない可能性があります。thinking.displayの設定とクライアントの描画を先に見ます。システムプロンプトへの追加指示は完全放置のハーネス向けで、確認ステップを残す必要のあるアプリには入れません。