[FEATURE] Allow opting into additional anthropic-beta headers (e.g. token-efficient-tools-2025-02-19)

[ThomazRossito]

Summary

ClaudeAgentOptions.betas is typed as list[SdkBeta] where
SdkBeta = Literal["context-1m-2025-08-07"], so the SDK currently
rejects any other beta flag. This blocks opting into Anthropic beta
features that ship only as HTTP headers, such as
token-efficient-tools-2025-02-19.

Enabling that header reduces output tokens on tool-use workloads by
up to ~14% (per the Anthropic token-efficient tools announcement),
which is material for agent systems that make many tool calls per turn.

Current behavior (SDK 0.1.61)

from claude_agent_sdk import ClaudeAgentOptions
# types.py
# SdkBeta = Literal["context-1m-2025-08-07"]
ClaudeAgentOptions(betas=["token-efficient-tools-2025-02-19"])  # type error

extra_args: dict[str, str | None] passes CLI flags to the bundled
Claude CLI, not HTTP headers, so it is not a workaround.

Proposal

One of:

1. Loosen SdkBeta to Literal["context-1m-2025-08-07", ...] | str
   and pass unknown values through as anthropic-beta header entries.
2. Add extra_headers: dict[str, str] to ClaudeAgentOptions that
   the SDK forwards to anthropic.Anthropic (or the Bedrock/Vertex
   equivalents), so users can set {"anthropic-beta": "token-efficient-tools-2025-02-19"}
   explicitly.

Option 2 is more general and would also unblock the use cases in
related issues (e.g. #626 cache-control injection on Bedrock).

Use case

In a multi-agent system with ~13 specialist agents, each turn can make
5-20 tool calls. Reducing output tokens 10-14% per tool-use turn is a
meaningful cost saving. Opt-in via header is the documented Anthropic
surface; we just need the SDK to let it through.

Environment

• claude-agent-sdk==0.1.61 (also reproduces on 0.1.63)
• Python 3.12