Most long-running agents ship the same 40 lines: watch the token count, call a model to summarize the transcript, splice the summary back in, and pray the exact figures survived. Claude's API now does that server-side. The strategy is compact_20260112 (beta header compact-2026-01-12), and it's the single most direct answer to "my agent's context keeps overflowing" — but it's a different tool from context editing, and it has one billing line that will lie to you if you don't know to look.

What it does#

Add a compaction edit and Claude, when the trigger fires, writes a summary of the conversation so far and emits it as a {"type": "compaction", ...} block. On your next request, the API automatically drops every content block before that compaction block and continues from the summary. You append the full response and keep going — there's no client-side splicing, no history bookkeeping.

resp = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["compact-2026-01-12"],
    messages=messages,
    context_management={"edits": [{
        "type": "compact_20260112",
        "trigger": {"type": "input_tokens", "value": 150_000},  # min 50_000
        "pause_after_compaction": False,
        # "instructions": "Preserve every exact figure, file path, and open task.",
    }]},
)
messages.append({"role": "assistant", "content": resp.content})

The trigger defaults to 150,000 input tokens and must be at least 50,000. Set pause_after_compaction=True and the response comes back with stop_reason: "compaction", letting you inspect (or log) the summary before you resume — useful the first few times, when you want to see what the paraphrase actually kept.

The billing line that hides the cost#

Compaction is a real model call, and it's billed like one. The catch: the top-level input_tokens and output_tokens exclude it. Those numbers reflect only the non-compaction iterations. The summarization pass lands as its own entry in usage.iterations, so to get true cost you have to sum across every entry in that array. Read only the top line and you'll under-count your bill exactly on the long runs where compaction fires most.

When to reach for it — vs context editing#

Compaction is not the same knob as context editing (clear_tool_uses_20250919), and picking the wrong one wastes tokens or loses information. The rule:

You don't have to choose. Both can sit in one edits array: clearing bounds tool spam continuously, compaction handles the dialogue when you approach the limit. Anthropic's own guidance layers them (context editing docs; cookbook), and pairs both with the memory tool for knowledge that has to survive across sessions.

Two things to check before you ship it#

Model support. Per Anthropic's docs, compaction runs on Opus 4.6/4.7/4.8, Opus 5, Sonnet 4.6, Sonnet 5, and Fable 5 (plus the Mythos line). It is not on Sonnet/Opus 4.5 and earlier — an unsupported model simply won't compact, silently. Check your model id first.

Cache. Rewriting the pre-checkpoint history invalidates that cached prefix — compaction busts the cache by construction. It recovers going forward because the summary is itself cacheable, so put a cache_control breakpoint after your system prompt to keep the stable part alive across compactions. It's the same trade context editing makes with its clear_at_least knob: only compress when you'll reclaim enough to pay for the cache write.

The short version: if you're still hand-rolling summarize-and-continue, compact_20260112 deletes that code. Wire the trigger, sum usage.iterations for the real bill, and keep context editing in the same array for the tool spam compaction shouldn't be paraphrasing anyway.