anthropics / anthropics/claude-agent-sdk-python

[FEATURE] Add context_management (clear_thinking + clear_tool_uses) as first-class ClaudeAgentOptions parameter

Aperta
#581 3 commenti 3 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
Python
Stelle
8.1k
Fork
1.3k
Merge medio
2g 31m
PR unite (30g)
1

Descrizione

## Feature Request

### Problem

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

1. **`clear_thinking_20251015`** — manages thinking blocks (keep all, keep N turns, or use default)
2. **`clear_tool_uses_20250919`** — clears stale tool use/result pairs when input tokens exceed a threshold

These are distinct from the server-side compaction feature (`compact-2026-01-12`, covered by #570). Where compaction summarizes and replaces the entire conversation, `context_management` edits selectively prune specific content types while preserving the rest of the conversation intact.

Currently, `ClaudeAgentOptions` has no parameter for `context_management`, so SDK users cannot configure these strategies.

### Relationship to Existing Issues

- **#443** requests configurable `clear_thinking` — this issue expands that to the full `context_management` config including `clear_tool_uses`
- **#570** requests `context_management.edits` support for the compaction beta — this issue covers the separate `context-management-2025-06-27` beta for selective content editing

### Requested Behavior

Add a `context_management` parameter to `ClaudeAgentOptions` that accepts the full `context_management` JSON config and passes it through to the Messages API. Example:

```python
options = ClaudeAgentOptions(
model="claude-sonnet-4-20250514",
max_thinking_tokens=16000,
betas=["context-management-2025-06-27"],
context_management={
"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 worker system where each task involves 50+ tool calls (Read, Grep, Glob, Bash, Edit, Write). We use Opus-class models with extended thinking enabled, and our architecture is append-only (prompts grow monotonically until compaction).

Without `context_management`:
- Stale tool results (file reads from early in the session) accumulate 50K–100K tokens of context that is no longer relevant
- Default `clear_thinking` behavior (keep last 1 turn) causes KV-cache misses when thinking blocks are cleared, forcing expensive cache re-creation
- Our only option is wholesale compaction at 80% context, which loses all conversation history

With `context_management`:
- `clear_thinking` with `keep: "all"` would maximize KV-cache hits across our long sessions (estimated 20–40% cost reduction on cache-eligible turns)
- `clear_tool_uses` would selectively reclaim 30K–70K tokens per session by clearing stale tool results while keeping the 5 most recent
- This defers compaction, maintaining coherent conversation history for longer and improving task completion quality

### Implementation Notes

Since the SDK wraps the Claude CLI, this likely requires:
1. Adding `context_management` to `ClaudeAgentOptions`
2. Passing it through as a CLI argument or environment variable to the underlying `claude` process
3. The CLI itself would need to forward it to the Messages API

Alternatively, if `extra_args` could support complex JSON config passthrough, that would be a viable interim solution.

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.