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

edits配列の先頭にはthinking clearingを置く

Context editingでtool result clearingとthinking block clearingを併用するとき、context_management.edits配列の並び順に制約があります。clear_thinking_20251015を先頭に置き、clear_tool_uses_20250919を後に続けます。公式ドキュメントは「複数の戦略を使うときはclear_thinking_20251015を先頭に列挙する」と明示しています。

ツールを多用しながら長い思考を挟むエージェントでは、両方が同時に肥大化します。片方だけをクリアしても、もう片方がコンテキストを占め続けます。Context editingのページが扱う戦略は2種類です。

サーバーサイドのcompactionもcompact_20260112として同じeditsに載せられますが、会話全体を要約する別の仕組みです。

各戦略の基本設定

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

thinking clearingのkeepは{type: "thinking_turns", value: N}の形で、直近Nターン分の思考ブロックを残します。Nは0より大きい値で、"all"なら全部残します。既定値はモデルによって異なり、Opus 4.5以降とSonnet 4.6以降は全ターンを保持、それより前のOpus/Sonnetと全Haikuは直近1ターンのみです。FableとMythosの系列はすべて全ターン保持が既定です。

1つのターンには、ツール呼び出しやinterleaved thinkingによって複数の思考ブロックが含まれることがあります。keepが数えるのはブロックの数ではなくアシスタントのターン数です。

tool clearingはtriggerとkeepが軸です。triggerはinput_tokensかtool_usesで閾値を指定します。clear_at_leastは「最低これだけ消せないなら戦略を適用しない」という下限で、プロンプトキャッシュを崩す価値があるかどうかの判断に使います。

複数のモデル階層をまたいで同じコードを動かすなら、既定値に頼らずkeepを明示してください。公式ドキュメントも同じ使い方を勧めています。

併用時の実装

両戦略を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 "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-5-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}
                }
            ]
        }
    }'

thinking clearingが効くのは、thinkingを有効にしたリクエストです。上の例は設定の並びを示すためにそのパラメータを省いています。

この例は、直近2ターン分の思考ブロックを残しつつ、入力トークンが5万を超えた時点でツール実行結果を直近5件まで間引きます。2つのtriggerとkeepは独立しているので、ツール結果は積極的に間引きつつ思考の連続性は多めに残す、といった非対称な運用も組めます。

順序の取り違えを送信前に弾く

公式は先頭に置くことを要件とするだけで、逆順のときの応答は定めていません。試しに本番へ送るより、リクエストJSONを組み立てた側で検査するほうが安全です。editsをあとから足していく実装では、ツール側の設定が先に入りがちです。

次のコマンドは、jqでリクエストJSON(req.json)の順序を検査し、崩れていれば並べ替えます。ツール側を先に書いたreq.jsonで手元実行した出力です。

# thinking clearing が先頭かを検査(先頭なら true)
jq -e '.context_management.edits | map(.type) | index("clear_thinking_20251015") == 0' req.json
# false(終了コード 1)
 
# thinking clearing を先頭に寄せて、順序を表示
jq -c '.context_management.edits |= sort_by(.type != "clear_thinking_20251015")
  | .context_management.edits | map(.type)' req.json
# ["clear_thinking_20251015","clear_tool_uses_20250919"]

sort_byは同じキーの要素の相対順を保つので、同じ種類を複数並べていても崩れません。検査コマンドの終了コードをCIやラッパー関数に組み込めば、順序ミスがAPIに届く前に止まります。

削減量を事前に試算し、適用結果で確かめる

トークンカウントのページ(token-counting)は、入力としてシステムプロンプト・ツール・画像・PDFを挙げていますが、context_managementには触れていません。この指定の説明があるのはContext editingのページ側です。count_tokensでeditsを渡すときも、betaヘッダーを付けます。

count_tokensには、サーバーツールを含むリクエストを受け付けない制限があります。Web検索・Web fetch・コード実行・ツール検索といったサーバーツールやMCP connectorを含むと、invalid_request_errorが返ります。前節の例のようにweb_search_20250305を使う構成では、試算用のリクエストからそれらを外します。本番での削減量は、applied_editsで確かめます。

キャッシュとコンテキストの空きのどちらを優先するか

削減の頻度を上げるほどキャッシュヒット率は下がります。公式ドキュメントは、thinkingのkeepをキャッシュ性能とコンテキスト枠の空きのどちらを優先するかで決めるよう案内しています。キャッシュを優先するならkeepを大きく(または"all")し、空きを優先するなら小さくします。

tool側は、消すたびにキャッシュ書き込みコストが発生します。そのぶん、続くリクエストは新しいプレフィックスを再利用できます。毎回わずかしか消せない設定だと、書き込みコストだけが積み上がります。clear_at_leastはこの対策で、下限に届かない場合は戦略そのものが適用されません。

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

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

Claude Fable 5.1・Opus 5.5・Sonnet 5.5では、サーバーサイドのcontext managementが思考ブロックを無効化しません。ただし、クライアント側で過去のターンを編集すると、それ以降のすべてのアシスタントターンの思考ブロックが無効になり得ます。

2026年8月31日以降に作成されたアカウントでは、無効化されたブロックを含むリクエストは、明示的にドロップを選ばない限り拒否されます。thinking clearingを併用する設計では、クライアント側で過去のターンを書き換える処理を避けるのが無難です。Claude Codeでのthinking blockの不整合エラーも、無効化された思考ブロックをそのまま再送したときに起きる近縁の問題です。

compactionとの使い分け

Context editingの2戦略は、特定の種類のコンテンツを選んで消す細粒度の制御です。サーバーサイドのcompactionは、会話全体を1つの要約に置き換える粗粒度の仕組みです。公式ドキュメントは長時間実行の会話管理でサーバーサイドcompactionを第一の選択肢とし、2戦略は消す対象を細かく制御したい場面向けとしています。ツール結果は消すが思考の文脈だけは連続性を保ちたい、という要件なら、2戦略の併用が合います。

TypeScriptとRubyのSDKにもtool_runner向けの要約機能(compaction_control)があります。ただし非推奨で、将来のバージョンで削除されます。Python SDKはv1.0で削除済みです。tool runnerでも、サーバーサイドのcompaction(compact_20260112)を使います。長時間エージェントのコンテキスト管理の全体設計はEffective context engineeringでも扱っています。

適用範囲とexclude_tools

Context editingはMessages APIのbetaヘッダーcontext-management-2025-06-27を付けたリクエストで動き、サポート対象の全Claudeモデルで使えます。

tool result clearingのexclude_toolsに名前を挙げたツールは、実行結果もツール呼び出しも、クリアされません。認証情報を返すツールや、後続の処理で必ず参照する集計結果を返すツールを守りたいときに使います。thinking clearingとの併用では、重要なツール結果はexclude_toolsで守り、思考側はkeepのターン数で連続性を調整する、という役割分担になります。

もう一つのclear_tool_inputsは、既定ではfalseです。そのままだと実行結果だけが消え、ツール呼び出しの入力パラメータは残ります。trueにすると入力側もクリア対象になります。検索クエリや長いファイルパスのように、入力側にも長いテキストが乗るツールを多用する構成で効きます。

併用でハマりやすい点