Context editingでthinking blockとtool resultを併用する順序

edits配列の並び順で結果が変わる

Context editingでtool result clearingとthinking block clearingを併用するとき、context_management.edits配列の並び順に制約があります。clear_thinking_20251015を先頭に置き、clear_tool_uses_20250919を後に続けます。この順序は公式ドキュメントが明記する必須要件で、逆にすると意図した通りに動きません。

2つの戦略はどちらも会話履歴からコンテンツを間引く点で似ていますが、対象が違います。tool result clearingは古いツール実行結果(ファイル内容や検索結果など)を消し、thinking block clearingはextended thinking使用時の思考ブロックを消します。ツールを多用しながら長い思考を挟むエージェントでは、両方が同時に肥大化するため、片方だけでは頭打ちになります。

各戦略の基本設定を先に押さえる

併用の前提として、2つの戦略それぞれの基本パラメータを確認します。

clear_thinking_20251015はkeepパラメータで残す範囲を決めます。{type: "thinking_turns", value: N}でN以上前の思考ブロックを消し、"all"を指定するとすべて保持します。既定値はモデルによって異なり、Opus 4.5以降とSonnet 4.6以降は全ターンを保持、それより前のOpus/Sonnetと全Haikuは直近ターンのみです。FableとMythosの系列はすべて全ターン保持が既定です。複数のモデル階層をまたいで同じコードを動かす場合、既定値に頼らずkeepを明示するのが安全です。

clear_tool_uses_20250919はtriggerとkeepの2つが軸になります。triggerはinput_tokensかtool_usesで閾値を指定でき、既定は10万トークンです。keepは保持する直近のツール実行ペア数で、既定は3件。加えてclear_at_leastで「最低これだけ消せないなら発動しない」という下限を設定でき、プロンプトキャッシュを崩す価値があるかどうかの判断に使えます。

併用時の実装

両戦略を1つのリクエストで組み合わせる例です。clear_thinking_20251015を配列の先頭に置きます。

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-5",
        "max_tokens": 16000,
        "messages": [{"role": "user", "content": "最新の量子誤り訂正の進展を検索して要約して"}],
        "tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking_20251015",
                    "keep": {"type": "thinking_turns", "value": 2}
                },
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {"type": "input_tokens", "value": 50000},
                    "keep": {"type": "tool_uses", "value": 5}
                }
            ]
        }
    }'

この例では、直近2ターン分の思考ブロックを残しつつ、入力トークンが5万を超えた時点でツール実行結果を直近5件まで間引きます。thinking clearingが先に評価されるため、tool result clearingが動く時点ではすでに古い思考ブロックが取り除かれた状態のコンテキストに対して処理が走ります。

web_search併用の例のように、ツールを何度も呼び出しながら検索結果を要約させるワークフローでは、ツール実行結果とその過程の思考ブロックが同時に積み上がります。片方だけをクリアする設定にすると、もう片方が肥大化したままになり、結局トークン消費が頭打ちになりません。2つのtriggerとkeepを独立に調整できる設計なので、ツール結果は積極的に間引きつつ思考の連続性は多めに残す、といった非対称な運用も組み立てられます。

トークンカウントへの反映を確認する

適用結果はレスポンスのcontext_management.applied_editsに戦略ごとに個別で出力されます。thinking clearingならcleared_thinking_turnsとcleared_input_tokens、tool clearingならcleared_tool_usesとcleared_input_tokensが別々のエントリとして並びます。1つのオブジェクトに合算されるわけではなく、戦略単位で内訳が見える設計です。

事前にどれだけ削減されるかを見積もるなら、/v1/messages/count_tokensエンドポイントがcontext_managementを受け付けます。リクエストに同じedits設定を渡すと、レスポンスのinput_tokensが適用後の値、context_management.original_input_tokensが適用前の値として返ります。差分を取れば、本番リクエストを送る前に削減量を把握できます。

サーバーサイドで完結し、クライアントの履歴は変わらない

両戦略ともAPIリクエストがClaudeに届く前にサーバー側で適用されます。アプリケーション側で保持している会話履歴のコピーを、クリアされた版に同期させる必要はありません。ローカルでは常に完全な履歴を管理し続けられます。

ただしClaude Fable 5.1では挙動が一段階丁寧になっています。サーバーサイドのcontext managementが思考ブロックを無効化することはありませんが、クライアント側で過去のターンを編集すると、それ以降のすべてのアシスタントターンの思考ブロックが無効になり得ます。2026年8月31日以降に作成されたアカウントでは、無効化されたブロックを含むリクエストは明示的にドロップを選択しない限り拒否されます。thinking block clearingを併用する設計では、この無効化条件に触れないよう、クライアント側で過去のユーザーターンを書き換える処理を避けるのが安全です。Claude Codeでのthinking blockの不整合エラーも、無効化された思考ブロックをそのまま再送したときに起きる近縁の問題です。

compaction(サーバーサイド)との使い分け

Context editingの2戦略は、どちらも「特定の種類のコンテンツを選んで消す」細粒度の制御です。これに対してサーバーサイドのcompactionは会話全体を1つの要約に置き換える、粗粒度の仕組みです。公式ドキュメントは長時間実行の会話管理においてサーバーサイドcompactionを第一の選択肢として案内しており、tool result clearingとthinking block clearingは「消す対象を細かく制御したい特定のシナリオ」向けの位置付けです。ツール結果は消すが思考の文脈だけは連続性を保ちたい、といった要件がある場合に、この2戦略の併用が効いてきます。長時間エージェントにおけるコンテキスト管理の全体設計はEffective context engineeringでも扱っています。

適用範囲とexclude_tools

Context editingはMessages APIのbetaヘッダーcontext-management-2025-06-27を付けたリクエストに対して動く機能で、サポート対象モデルで利用できます。Messages APIを直接呼ぶ実装で有効になる機能である点は押さえておきます。

tool result clearingにはexclude_toolsというパラメータもあり、指定した名前のツールは実行結果もツール呼び出しパラメータもクリア対象から除外できます。認証情報を返すツールや、後続の処理で必ず参照する集計結果を返すツールなど、消えると困るツールを守りたいときに使います。thinking block clearingと併用する構成では、exclude_toolsで重要なツール結果を保護しつつ、思考ブロック側はkeepのターン数で連続性を調整する、という役割分担が組みやすくなります。

もう一つ、clear_tool_inputsという設定も用意されています。既定では実行結果(出力)だけを消し、ツール呼び出し時に渡した入力パラメータは残りますが、これを有効にすると入力パラメータ側もクリア対象に含められます。検索クエリや長いファイルパスなど、入力側にも長大なテキストが乗るツールを多用する構成では、出力だけでなく入力もまとめて間引く選択肢として押さえておくと、exclude_toolsとの組み合わせ設計の幅が広がります。

併用でハマりやすい点

• 配列の順序ミス: clear_tool_uses_20250919を先に書いてしまうと、公式の必須要件に反した状態になります。併用する2件を配列に足すときは、必ずthinking clearingが先頭にあるかを見直します
• betaヘッダーの付け忘れ: 両戦略ともcontext-management-2025-06-27ヘッダーが無いと有効になりません。単体のtool result clearingで動作確認したコードにthinking clearingを足したとき、ヘッダーの更新を忘れがちです
• クリアした情報の消失: tool result clearingは古い情報を単に間引くだけなので、後で必要になる情報まで消えることがあります。長時間のエージェントで情報を残したい場合は、クリアされる前にmemory toolへ書き出す設計と組み合わせる方が安全です
• keepの単位の取り違え: tool result clearingのkeepはツール実行のペア数、thinking block clearingのkeepはアシスタントターン数と、同じ名前のパラメータでも数える単位が違います。片方の感覚でもう片方の値を決めると、想定より多く残ったり早く消えたりします

よくある質問

edits配列の順序を逆にするとどうなるか

公式ドキュメントはclear_thinking_20251015を先頭に置く制約を明記していますが、逆順にした場合の具体的な挙動(エラーになるか、意図しない適用順になるか)は公式ページに記載がありません。制約に従い、先頭に置く前提で実装するのが確実です。

3つ以上の戦略を同時に併用できるか

公式ドキュメントが示しているedits配列の例はthinking block clearingとtool result clearingの2件までです。3件目以降の組み合わせパターンは公式ページに具体例が無いため、本記事では2件併用の順序制約に絞って扱っています。