fix: parse server_tool_use and advisor_tool_result content blocks (#836)

## Summary

`server_tool_use` and `advisor_tool_result` blocks were silently dropped
by `parse_message`, so messages that only carried a server-side tool
call arrived as `AssistantMessage(content=[])`. This made it impossible
to detect that the advisor (or any other server-side tool) had run from
the assistant stream alone.

This PR surfaces them as two new content block types:

- `ServerToolUseBlock(id, name, input)` — mirrors the existing
`ToolUseBlock` but for server-executed tools like `advisor`,
`web_search`, `web_fetch`.
- `AdvisorToolResultBlock(tool_use_id, content)` — `content` is a raw
dict because the shape varies by outcome (`advisor_result` /
`advisor_redacted_result` / `advisor_tool_result_error`) and callers
need to discriminate.

## Test plan

- 3 new unit tests in `tests/test_message_parser.py` covering the
success, redacted, and server_tool_use cases. Shapes are taken from the
canonical API schema (`anthropic` SDK's `BetaServerToolUseBlock` /
`BetaAdvisorToolResultBlock`).
- All 471 existing tests still pass.
- Verified end-to-end against a live advisor call
(`CLAUDE_CODE_ENABLE_EXPERIMENTAL_ADVISOR_TOOL=1 claude --advisor
opus`): before this change, both blocks arrived as empty
`AssistantMessage(content=[])`; after, `ServerToolUseBlock` and
`AdvisorToolResultBlock` surface with populated fields.
- The `advisor_redacted_result` content variant was exercised live; the
plaintext `advisor_result` variant is covered by a synthetic unit test
only.

Author: mnielan-ant

src/claude_agent_sdk/__init__.py

@@ -104,6 +104,9 @@
     SdkBeta,
     SdkPluginConfig,
     SDKSessionInfo,
+    ServerToolName,
+    ServerToolResultBlock,
+    ServerToolUseBlock,
     SessionKey,
     SessionListSubkeysKey,
     SessionMessage,
@@ -555,6 +558,9 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
     "ThinkingConfigDisabled",
     "ToolUseBlock",
     "ToolResultBlock",
+    "ServerToolName",
+    "ServerToolUseBlock",
+    "ServerToolResultBlock",
     "ContentBlock",
     "ContextUsageCategory",
     "ContextUsageResponse",

src/claude_agent_sdk/_internal/message_parser.py

@@ -12,6 +12,8 @@
     RateLimitEvent,
     RateLimitInfo,
     ResultMessage,
+    ServerToolResultBlock,
+    ServerToolUseBlock,
     StreamEvent,
     SystemMessage,
     TaskNotificationMessage,
@@ -127,6 +129,21 @@ def parse_message(data: dict[str, Any]) -> Message | None:
                                     is_error=block.get("is_error"),
                                 )
                             )
+                        case "server_tool_use":
+                            content_blocks.append(
+                                ServerToolUseBlock(
+                                    id=block["id"],
+                                    name=block["name"],
+                                    input=block["input"],
+                                )
+                            )
+                        case "advisor_tool_result":
+                            content_blocks.append(
+                                ServerToolResultBlock(
+                                    tool_use_id=block["tool_use_id"],
+                                    content=block["content"],
+                                )
+                            )
 
                 return AssistantMessage(
                     content=content_blocks,

src/claude_agent_sdk/types.py

@@ -889,7 +889,54 @@ class ToolResultBlock:
     is_error: bool | None = None
 
 
-ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+ServerToolName = Literal[
+    "advisor",
+    "web_search",
+    "web_fetch",
+    "code_execution",
+    "bash_code_execution",
+    "text_editor_code_execution",
+    "tool_search_tool_regex",
+    "tool_search_tool_bm25",
+]
+
+
+@dataclass
+class ServerToolUseBlock:
+    """Server-side tool use block (e.g. advisor, web_search, web_fetch).
+
+    These are tools the API executes server-side on the model's behalf, so they
+    appear in the message stream alongside regular `tool_use` blocks but the
+    caller never needs to return a result. `name` is a discriminator — branch
+    on it to know which server tool was invoked.
+    """
+
+    id: str
+    name: ServerToolName
+    input: dict[str, Any]
+
+
+@dataclass
+class ServerToolResultBlock:
+    """Result block returned for a server-side tool call.
+
+    Mirrors `ToolResultBlock`'s shape. `content` is the raw dict from the
+    API, opaque to this layer — callers that care about a specific server
+    tool's result schema can inspect `content["type"]`.
+    """
+
+    tool_use_id: str
+    content: dict[str, Any]
+
+
+ContentBlock = (
+    TextBlock
+    | ThinkingBlock
+    | ToolUseBlock
+    | ToolResultBlock
+    | ServerToolUseBlock
+    | ServerToolResultBlock
+)
 
 
 # Message types

tests/test_message_parser.py

@@ -8,6 +8,8 @@
     AssistantMessage,
     RateLimitEvent,
     ResultMessage,
+    ServerToolResultBlock,
+    ServerToolUseBlock,
     SystemMessage,
     TaskNotificationMessage,
     TaskProgressMessage,
@@ -274,6 +276,93 @@ def test_parse_assistant_message_with_thinking(self):
         assert isinstance(message.content[1], TextBlock)
         assert message.content[1].text == "Here's my response"
 
+    def test_parse_assistant_message_with_server_tool_use(self):
+        """server_tool_use blocks (e.g. advisor, web_search) are preserved.
+
+        Previously these were dropped, leaving an empty content list on
+        messages that only contained a server tool call.
+        """
+        data = {
+            "type": "assistant",
+            "message": {
+                "content": [
+                    {
+                        "type": "server_tool_use",
+                        "id": "srvtoolu_01ABC",
+                        "name": "advisor",
+                        "input": {},
+                    },
+                ],
+                "model": "claude-sonnet-4-5",
+            },
+        }
+        message = parse_message(data)
+        assert isinstance(message, AssistantMessage)
+        assert len(message.content) == 1
+        assert isinstance(message.content[0], ServerToolUseBlock)
+        assert message.content[0].id == "srvtoolu_01ABC"
+        assert message.content[0].name == "advisor"
+        assert message.content[0].input == {}
+
+    def test_parse_assistant_message_with_server_tool_result(self):
+        """Server-side tool result blocks (e.g. advisor) surface with their raw content dict.
+
+        `content` is passed through as a dict since its shape is tool-specific
+        (advisor emits advisor_result / advisor_redacted_result /
+        advisor_tool_result_error; other server tools use different shapes).
+        """
+        data = {
+            "type": "assistant",
+            "message": {
+                "content": [
+                    {
+                        "type": "advisor_tool_result",
+                        "tool_use_id": "srvtoolu_01ABC",
+                        "content": {
+                            "type": "advisor_result",
+                            "text": "Consider edge cases around empty input.",
+                        },
+                    },
+                ],
+                "model": "claude-sonnet-4-5",
+            },
+        }
+        message = parse_message(data)
+        assert isinstance(message, AssistantMessage)
+        assert len(message.content) == 1
+        result_block = message.content[0]
+        assert isinstance(result_block, ServerToolResultBlock)
+        assert result_block.tool_use_id == "srvtoolu_01ABC"
+        assert result_block.content == {
+            "type": "advisor_result",
+            "text": "Consider edge cases around empty input.",
+        }
+
+    def test_parse_assistant_message_with_redacted_advisor_result(self):
+        """External API users get advisor output as an encrypted blob in the content dict."""
+        data = {
+            "type": "assistant",
+            "message": {
+                "content": [
+                    {
+                        "type": "advisor_tool_result",
+                        "tool_use_id": "srvtoolu_01ABC",
+                        "content": {
+                            "type": "advisor_redacted_result",
+                            "encrypted_content": "EuYDCioIDhgC...",
+                        },
+                    },
+                ],
+                "model": "claude-sonnet-4-5",
+            },
+        }
+        message = parse_message(data)
+        assert isinstance(message, AssistantMessage)
+        result_block = message.content[0]
+        assert isinstance(result_block, ServerToolResultBlock)
+        assert result_block.content["type"] == "advisor_redacted_result"
+        assert result_block.content["encrypted_content"] == "EuYDCioIDhgC..."
+
     def test_parse_assistant_message_with_usage(self):
         """Per-turn usage is preserved on AssistantMessage.