feat: add tool annotations, new hook types, and comprehensive test suite

- Add ToolAnnotations support to MCP tool definitions and decorator
- Add new hook types: Notification, SubagentStart, PermissionRequest with specific output types
- Add Thinking configuration types (ThinkingConfig, ThinkingConfigEnabled/Disabled/Adaptive)
- Always use streaming mode internally to support agents via initialize request
- Add get_mcp_status() method for MCP server connection status
- Improve message parser forward compatibility by skipping unknown message types
- Update bundled CLI version to 0.4.5
- Add trio to dev dependencies
- Expand test suite with comprehensive coverage for streaming, transport, hooks, and types

Generated with Ripperdoc

Co-Authored-By: Ripperdoc

Author: jstzwj

pyproject.toml

@@ -38,6 +38,7 @@ dev = [
     "mypy>=1.0.0",
     "black>=23.0.0",
     "ruff>=0.1.0",
+    "trio>=0.22.0",
 ]
 
 [project.urls]

ripperdoc_agent_sdk/__init__.py

@@ -4,6 +4,8 @@
 from dataclasses import dataclass
 from typing import Any, Generic, TypeVar
 
+from mcp.types import ToolAnnotations
+
 from ._errors import (
     RipperdocSDKError,
     CLIConnectionError,
@@ -30,11 +32,17 @@
     McpSdkServerConfig,
     McpServerConfig,
     Message,
+    NotificationHookInput,
+    NotificationHookSpecificOutput,
     PermissionMode,
+    PermissionRequestHookInput,
+    PermissionRequestHookSpecificOutput,
     PermissionResult,
     PermissionResultAllow,
     PermissionResultDeny,
     PermissionUpdate,
+    PostToolUseFailureHookInput,
+    PostToolUseFailureHookSpecificOutput,
     PostToolUseHookInput,
     PreCompactHookInput,
     PreToolUseHookInput,
@@ -46,10 +54,16 @@
     SdkPluginConfig,
     SettingSource,
     StopHookInput,
+    SubagentStartHookInput,
+    SubagentStartHookSpecificOutput,
     SubagentStopHookInput,
     SystemMessage,
     TextBlock,
     ThinkingBlock,
+    ThinkingConfig,
+    ThinkingConfigAdaptive,
+    ThinkingConfigDisabled,
+    ThinkingConfigEnabled,
     ToolPermissionContext,
     ToolResultBlock,
     ToolUseBlock,
@@ -70,10 +84,14 @@ class SdkMcpTool(Generic[T]):
     description: str
     input_schema: type[T] | dict[str, Any]
     handler: Callable[[T], Awaitable[dict[str, Any]]]
+    annotations: ToolAnnotations | None = None
 
 
 def tool(
-    name: str, description: str, input_schema: type | dict[str, Any]
+    name: str,
+    description: str,
+    input_schema: type | dict[str, Any],
+    annotations: ToolAnnotations | None = None,
 ) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]:
     """Decorator for defining MCP tools with type safety.
 
@@ -130,6 +148,7 @@ def decorator(
             description=description,
             input_schema=input_schema,
             handler=handler,
+            annotations=annotations,
         )
 
     return decorator
@@ -260,6 +279,7 @@ async def list_tools() -> list[Tool]:
                         name=tool_def.name,
                         description=tool_def.description,
                         inputSchema=schema,
+                        annotations=tool_def.annotations,
                     )
                 )
             return tool_list
@@ -318,6 +338,10 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
     "RipperdocAgentOptions",
     "TextBlock",
     "ThinkingBlock",
+    "ThinkingConfig",
+    "ThinkingConfigAdaptive",
+    "ThinkingConfigEnabled",
+    "ThinkingConfigDisabled",
     "ToolUseBlock",
     "ToolResultBlock",
     "ContentBlock",
@@ -335,10 +359,18 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
     "BaseHookInput",
     "PreToolUseHookInput",
     "PostToolUseHookInput",
+    "PostToolUseFailureHookInput",
+    "PostToolUseFailureHookSpecificOutput",
     "UserPromptSubmitHookInput",
     "StopHookInput",
     "SubagentStopHookInput",
     "PreCompactHookInput",
+    "NotificationHookInput",
+    "SubagentStartHookInput",
+    "PermissionRequestHookInput",
+    "NotificationHookSpecificOutput",
+    "SubagentStartHookSpecificOutput",
+    "PermissionRequestHookSpecificOutput",
     "HookJSONOutput",
     "HookMatcher",
     # Agent support
@@ -356,6 +388,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
     "create_sdk_mcp_server",
     "tool",
     "SdkMcpTool",
+    "ToolAnnotations",
     # Errors
     "RipperdocSDKError",
     "CLIConnectionError",

ripperdoc_agent_sdk/_cli_version.py

@@ -1,3 +1,3 @@
 """Bundled Ripperdoc Code CLI version."""
 
-__cli_version__ = "0.4.2"
+__cli_version__ = "0.4.5"

ripperdoc_agent_sdk/_internal/client.py

@@ -1,7 +1,7 @@
 """Internal client implementation."""
 
 from collections.abc import AsyncIterable, AsyncIterator
-from dataclasses import replace
+from dataclasses import asdict, replace
 from typing import Any
 
 from ..types import (
@@ -89,36 +89,58 @@ async def process_query(
                 if isinstance(config, dict) and config.get("type") == "sdk":
                     sdk_mcp_servers[name] = config["instance"]  # type: ignore[typeddict-item]
 
+        # Convert agents to dict format for initialize request
+        agents_dict = None
+        if configured_options.agents:
+            agents_dict = {
+                name: {k: v for k, v in asdict(agent_def).items() if v is not None}
+                for name, agent_def in configured_options.agents.items()
+            }
+
         # Create Query to handle control protocol
-        is_streaming = not isinstance(prompt, str)
+        # Always use streaming mode internally (matching TypeScript SDK)
+        # This ensures agents are always sent via initialize request
         query = Query(
             transport=chosen_transport,
-            is_streaming_mode=is_streaming,
+            is_streaming_mode=True,  # Always streaming internally
             can_use_tool=configured_options.can_use_tool,
             hooks=self._convert_hooks_to_internal_format(configured_options.hooks)
             if configured_options.hooks
             else None,
             sdk_mcp_servers=sdk_mcp_servers,
+            agents=agents_dict,
         )
 
         try:
             # Start reading messages
             await query.start()
 
-            # Initialize if streaming
-            if is_streaming:
-                await query.initialize()
+            # Always initialize to send agents via stdin (matching TypeScript SDK)
+            await query.initialize()
 
-            # Stream input if it's an AsyncIterable
-            if isinstance(prompt, AsyncIterable) and query._tg:
-                # Start streaming in background
-                # Create a task that will run in the background
+            # Handle prompt input
+            if isinstance(prompt, str):
+                # For string prompts, write user message to stdin after initialize
+                # (matching TypeScript SDK behavior)
+                import json
+
+                user_message = {
+                    "type": "user",
+                    "session_id": "",
+                    "message": {"role": "user", "content": prompt},
+                    "parent_tool_use_id": None,
+                }
+                await chosen_transport.write(json.dumps(user_message) + "\n")
+                await chosen_transport.end_input()
+            elif isinstance(prompt, AsyncIterable) and query._tg:
+                # Stream input in background for async iterables
                 query._tg.start_soon(query.stream_input, prompt)
-            # For string prompts, the prompt is already passed via CLI args
 
-            # Yield parsed messages
+            # Yield parsed messages, skipping unknown message types
             async for data in query.receive_messages():
-                yield parse_message(data)
+                message = parse_message(data)
+                if message is not None:
+                    yield message
 
         finally:
             await query.close()

ripperdoc_agent_sdk/_internal/message_parser.py

@@ -21,7 +21,7 @@
 logger = logging.getLogger(__name__)
 
 
-def parse_message(data: dict[str, Any]) -> Message:
+def parse_message(data: dict[str, Any]) -> Message | None:
     """
     Parse message from CLI output into typed Message objects.
 
@@ -126,7 +126,7 @@ def parse_message(data: dict[str, Any]) -> Message:
                     content=content_blocks,
                     model=data["message"]["model"],
                     parent_tool_use_id=data.get("parent_tool_use_id"),
-                    error=data["message"].get("error"),
+                    error=data.get("error"),
                 )
             except KeyError as e:
                 raise MessageParseError(
@@ -177,4 +177,7 @@ def parse_message(data: dict[str, Any]) -> Message:
                 ) from e
 
         case _:
-            raise MessageParseError(f"Unknown message type: {message_type}", data)
+            # Forward-compatible: skip unrecognized message types so newer
+            # CLI versions don't crash older SDK versions.
+            logger.debug("Skipping unknown message type: %s", message_type)
+            return None

ripperdoc_agent_sdk/_internal/query.py

@@ -73,6 +73,7 @@ def __init__(
         hooks: dict[str, list[dict[str, Any]]] | None = None,
         sdk_mcp_servers: dict[str, "McpServer"] | None = None,
         initialize_timeout: float = 60.0,
+        agents: dict[str, dict[str, Any]] | None = None,
     ):
         """Initialize Query with transport and callbacks.
 
@@ -83,13 +84,15 @@ def __init__(
             hooks: Optional hook configurations
             sdk_mcp_servers: Optional SDK MCP server instances
             initialize_timeout: Timeout in seconds for the initialize request
+            agents: Optional agent definitions to send via initialize
         """
         self._initialize_timeout = initialize_timeout
         self.transport = transport
         self.is_streaming_mode = is_streaming_mode
         self.can_use_tool = can_use_tool
         self.hooks = hooks or {}
         self.sdk_mcp_servers = sdk_mcp_servers or {}
+        self._agents = agents
 
         # Control protocol state
         self.pending_control_responses: dict[str, anyio.Event] = {}
@@ -144,10 +147,12 @@ async def initialize(self) -> dict[str, Any] | None:
                         hooks_config[event].append(hook_matcher_config)
 
         # Send initialize request
-        request = {
+        request: dict[str, Any] = {
             "subtype": "initialize",
             "hooks": hooks_config if hooks_config else None,
         }
+        if self._agents:
+            request["agents"] = self._agents
 
         # Use longer timeout for initialize since MCP servers may take time to start
         response = await self._send_control_request(
@@ -443,8 +448,9 @@ async def _handle_sdk_mcp_request(
                 if handler:
                     result = await handler(request)
                     # Convert MCP result to JSONRPC response
-                    tools_data = [
-                        {
+                    tools_data = []
+                    for tool in result.root.tools:  # type: ignore[union-attr]
+                        tool_data: dict[str, Any] = {
                             "name": tool.name,
                             "description": tool.description,
                             "inputSchema": (
@@ -455,8 +461,11 @@ async def _handle_sdk_mcp_request(
                             if tool.inputSchema
                             else {},
                         }
-                        for tool in result.root.tools  # type: ignore[union-attr]
-                    ]
+                        if tool.annotations:
+                            tool_data["annotations"] = tool.annotations.model_dump(
+                                exclude_none=True
+                            )
+                        tools_data.append(tool_data)
                     return {
                         "jsonrpc": "2.0",
                         "id": message.get("id"),
@@ -517,6 +526,10 @@ async def _handle_sdk_mcp_request(
                 "error": {"code": -32603, "message": str(e)},
             }
 
+    async def get_mcp_status(self) -> dict[str, Any]:
+        """Get current MCP server connection status."""
+        return await self._send_control_request({"subtype": "mcp_status"})
+
     async def interrupt(self) -> None:
         """Send interrupt control request."""
         await self._send_control_request({"subtype": "interrupt"})