Because your application owns the messages array, "editing context" comes in two flavors: changes you make yourself on the client, and a server-side beta feature — officially named context editing — where the API prunes for you. Most teams end up using both.
Client-side editing: what's safe and what isn't
Between turns you are free to drop old exchanges, shorten verbose tool results, or redact content that shouldn't persist (a customer's card number that appeared in a tool result has no business riding along for fifty more turns). But three rules are enforced by the API:
- Never touch thinking blocks in the latest assistant message. Modifying, reordering, or filtering
thinking/redacted_thinkingblocks before resending returns a 400 — they are protected by cryptographic signature verification. Pass them back exactly as received. (When switching to a different model mid-conversation, stripping prior thinking blocks entirely is the recommended move.) - Keep tool_use and tool_result paired. A
tool_resultblock must answer atool_useblock from the preceding assistant message. When injecting or rewriting tool results, keep the IDs matched and send all results for a turn together in a single user message; report failures with"is_error": truerather than deleting the exchange. - Expect cache invalidation. Prompt caching is a strict prefix match, so editing any early message invalidates every cache breakpoint after that byte. Edit at the tail, or accept a one-time cache rebuild when you redact history.
Server-side context editing: let the API prune for you
The managed alternative ships two strategies under context_management.edits, with beta header anthropic-beta: context-management-2025-06-27, and works on all supported Claude models:
| Strategy | What it clears | Key defaults |
|---|---|---|
clear_tool_uses_20250919 | Old tool results (optionally tool inputs too) | Triggers at 100,000 input tokens; keeps the 3 most recent tool uses |
clear_thinking_20251015 | Older thinking blocks | Model-specific; newer models keep all thinking by default |
context_management={"edits": [{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 80000},
"keep": {"type": "tool_uses", "value": 5},
"exclude_tools": ["read_policy_doc"], # never cleared
"clear_at_least": {"type": "input_tokens", "value": 10000},
}]}The crucial property: editing happens server-side before the prompt reaches Claude. Your client keeps its full, unmodified history and re-sends it as usual — no synchronization logic, no risk of corrupting your own records. Responses report what happened in context_management.applied_edits (fields like cleared_tool_uses and cleared_input_tokens; in streaming this arrives in the final message_delta). Two configuration details: when combining both strategies, clear_thinking_20251015 must be listed first in the array, and clear_at_least exists because clearing invalidates the cached prefix at the clearing point — make each invalidation clear enough tokens to be worth it.
You can also preview the effect: the count_tokens endpoint accepts context_management (with the beta flag) and returns both the post-edit input_tokens and context_management.original_input_tokens.
Choosing between the approaches
Client-side editing gives you exact control and is the only way to redact — server-side clearing reduces what the model sees, but your compliance story may require the sensitive content gone from your own stores too. Server-side editing wins for agentic loops that accumulate bulky tool results, where "keep the last N tool uses" is exactly the policy you want and you'd rather not maintain pruning code. For summarize-rather-than-delete, see compaction — the two are separate features and separate betas. Context editing is beta on all five platforms (Claude API, Claude Platform on AWS, Bedrock, Vertex AI, Foundry).
Where to go next
Pair this with context compaction and the memory tool for long-running agents, and see prompt cache mechanics to understand the invalidation costs of every edit.