Feature: Expose advisor_20260301 on AgentDefinition

Allow sub-agents declared via `ClaudeAgentOptions(agents={...})` to be configured with the `advisor_20260301` server-side tool (shipped April 9, 2026). Currently the advisor tool is only configurable via the raw `anthropic` SDK with the `advisor-tool-2026-03-01` beta header — it cannot be attached to an `AgentDefinition`.

## Use case

We're building a system with nested sub-agents: a top-level orchestrator delegates to specialized sub-agents via `agents={}`, and we want each specialized sub-agent to run as a Sonnet executor with an Opus advisor consulted at decision points. Anthropic's published benchmarks for this pattern show ~73% cost reduction vs. Opus-solo with comparable quality, which is the main reason we want it.

We want the entire hierarchy inside the Agent SDK (rather than dropping to raw `anthropic` for the leaf agents) so we keep Hooks, Tool Search, `output_format` json_schema coercion, OTEL trace propagation, and per-sub-agent cost telemetry.

## What's missing

`AgentDefinition.tools` accepts client-side tool names (MCP tools, `Read`, `Grep`, etc.). It doesn't expose configuration for server-side beta tools that take parameters at request-declaration time, nor a way to set per-sub-agent beta headers.

## Proposed API

Two shapes — happy with either.

### Option A — Typed fields

```python
AgentDefinition(
description="...",
prompt="...",
model="sonnet",
tools=["Read", "mcp__svc__do_thing"],
server_tools=[
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-4-7",
"max_uses": 5,
"caching": {"type": "ephemeral", "ttl": "5m"},
}
],
betas=["advisor-tool-2026-03-01"],
)
```

### Option B — Escape hatch

```python
AgentDefinition(
...,
extra_request_params={
"tools": [{"type": "advisor_20260301", ...}],
"betas": ["advisor-tool-2026-03-01"],
},
)
```

Less type-safe, unblocks any future server-side tool. Could be a stopgap.

## Why this matters

Without this, current options are all bad:

1. **Hybrid**: top-level orchestrator uses `agents={}`, leaf sub-agents drop to raw `anthropic` behind a wrapper. Loses Hooks, Tool Search, and `StructuredOutput` coercion exactly where we need them most.
2. **Skip the advisor pattern**: lose the documented ~73% cost reduction. (Our current temporary choice.)
3. **All raw SDK**: discard `agents={}` entirely. Loses every SDK-managed primitive.

A few behaviors we found prototyping that would benefit from being inside the SDK rather than worked around:

- **Echo filtering**: in multi-turn loops mixing client-side tools and the advisor server-tool, `server_tool_use` and `advisor_tool_result` blocks must be stripped from echoed assistant turns or the next request returns 400 (input schema is narrower than output schema for these blocks).
- **Token accounting**: advisor tokens live in `usage.iterations[]`, not top-level `usage`. SDK-managed cost telemetry would handle this transparently.
- **`StructuredOutput` coercion**: the SDK's `output_format` json_schema mechanism reliably enforces JSON-shaped output. Free-form-via-prompt JSON does not when the loop also includes advisor consultations (we observed prose output despite explicit JSON instructions in 1/1 of integrated tests). Native advisor support would let us keep the SDK's coercion while adding advisor consultation.

## Acceptance criteria (suggested)

- `AgentDefinition` exposes server-side tool configuration (Option A or B)
- `betas` settable per-sub-agent without leaking to the parent
- Advisor token usage surfaced in `ResultMessage.usage.iterations[]` accessible to the parent
- Hooks (`PreToolUse`, `PostToolUse`) fire on advisor invocations with `name == "advisor"` distinguishable
- Documentation example

## Anything I can help with

We have a raw-SDK prototype exercising the advisor tool in a multi-turn loop with both client-side and server-side tools. Happy to share the wire-format gotchas, test cases, or the prototype itself if useful.

## Environment

- `claude-agent-sdk` 0.1.65+
- `anthropic` 0.75.0
- Models: `claude-sonnet-4-6` (executor), `claude-opus-4-7` (advisor) — pair validated, no 400