[FEATURE] CLI flag or settings.json config for context_management API parameter

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The Anthropic Messages API supports a context_management parameter (beta context-management-2025-06-27) with two server-side strategies:

1. clear_thinking_20251015 — controls thinking block retention (keep all, keep N turns)
2. clear_tool_uses_20250919 — clears stale tool use/result pairs when input tokens exceed a configurable threshold

These strategies let the server selectively prune context without wholesale compaction, preserving recent conversation while reclaiming tokens from stale content.

Currently, there is no way to configure context_management when using Claude Code — neither as a CLI flag, environment variable, nor in settings.json. Users who spawn Claude Code as a subprocess (via the Claude Agent SDK or directly) have no mechanism to pass this API parameter.

Clarification on Existing Issues

• #14450 was about workspace/conversation switching (managing multiple task contexts), which is a UX-level feature. This request is about the API-level context_management parameter that controls server-side content editing.
• #21612 reports a bug where Claude Code sends context_management and the API rejects it — suggesting Claude Code may already use this parameter internally but does not expose configuration to users.

Requested Feature

Allow users to configure context_management JSON via one or more of:

1. settings.json — e.g., a contextManagement key in the settings file
2. CLI flag — e.g., claude --context-management '{"edits": [...]}'
3. Environment variable — e.g., CLAUDE_CONTEXT_MANAGEMENT='{"edits": [...]}'

Example configuration:

{
  "contextManagement": {
    "edits": [
      {"type": "clear_thinking_20251015", "keep": "all"},
      {
        "type": "clear_tool_uses_20250919",
        "trigger": {"type": "input_tokens", "value": 100000},
        "keep": {"type": "tool_uses", "value": 5},
        "clear_at_least": {"type": "input_tokens", "value": 10000}
      }
    ]
  }
}

Use Case

We run an agentic system that spawns Claude Code as a subprocess for each worker task. Each task involves 50+ tool calls (Read, Grep, Glob, Bash, Edit, Write) with Opus-class models and extended thinking enabled. Our architecture is append-only — conversation history grows until compaction.

Being able to configure context_management would allow us to:

• Maximize KV-cache hits: Setting clear_thinking to keep: "all" prevents cache invalidation from thinking block removal (estimated 20–40% cost reduction on cache-eligible turns)
• Reclaim stale tool result tokens: clear_tool_uses could selectively clear 30K–70K tokens of outdated file reads per session while keeping the 5 most recent tool results
• Defer compaction: By keeping context leaner through selective pruning, we can maintain coherent conversation history longer, improving task completion quality

This is particularly impactful for systems using the Claude Agent SDK, which spawns Claude CLI processes and currently has no way to pass context_management config downstream.

Proposed Solution

The simplest path would be a settings.json key that Claude Code reads and includes in its Messages API calls. Since Claude Code already makes the API calls internally, this would require minimal changes — just reading the config and passing it through.