From a1e90f2818318b20f118d2aa16ce7f4956abfa37 Mon Sep 17 00:00:00 2001
From: Kaushik Rajan <kaushi@alumni.ncsu.edu>
Date: Tue, 10 Mar 2026 16:12:21 +0530
Subject: [PATCH] docs: note TypedDict runtime dict behavior in types.py (#623)

TypedDict instances are plain dicts at runtime, but the existing
docstrings don't warn about this. Adds a module-level note and
per-class reminders to prevent AttributeError from dot-access.
---
 src/claude_agent_sdk/types.py | 59 ++++++++++++++++++++++++++++++++---
 1 file changed, 55 insertions(+), 4 deletions(-)

diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index bfe632e5..8ff25fec 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -1,4 +1,13 @@
-"""Type definitions for Claude SDK."""
+"""Type definitions for Claude SDK.
+
+This module contains two kinds of types:
+
+- **@dataclass types** (e.g., ``AgentDefinition``, ``TextBlock``) support attribute
+  access: ``obj.field_name``.
+- **TypedDict types** (e.g., ``ThinkingConfigEnabled``, ``SyncHookJSONOutput``) are
+  plain ``dict`` objects at runtime. Use bracket access: ``obj["field_name"]``,
+  **not** ``obj.field_name`` (which raises ``AttributeError``).
+"""
 
 import sys
 from collections.abc import Awaitable, Callable
@@ -393,6 +402,9 @@ class PermissionRequestHookSpecificOutput(TypedDict):
 class AsyncHookJSONOutput(TypedDict):
     """Async hook output that defers hook execution.
 
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``output["async_"]``, not ``output.async_``.
+
     Fields:
         async_: Set to True to defer hook execution. Note: This is converted to
             "async" when sent to the CLI - use "async_" in your Python code.
@@ -411,6 +423,9 @@ class SyncHookJSONOutput(TypedDict):
     This defines the structure for hook callbacks to control execution and provide
     feedback to Claude.
 
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``output["continue_"]``, not ``output.continue_``.
+
     Common Control Fields:
         continue_: Whether Claude should proceed after hook execution (default: True).
             Note: This is converted to "continue" when sent to the CLI.
@@ -492,7 +507,11 @@ class HookMatcher:
 
 # MCP Server config
 class McpStdioServerConfig(TypedDict):
-    """MCP stdio server configuration."""
+    """MCP stdio server configuration.
+
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``config["command"]``, not ``config.command``.
+    """
 
     type: NotRequired[Literal["stdio"]]  # Optional for backwards compatibility
     command: str
@@ -501,7 +520,11 @@ class McpStdioServerConfig(TypedDict):
 
 
 class McpSSEServerConfig(TypedDict):
-    """MCP SSE server configuration."""
+    """MCP SSE server configuration.
+
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``config["url"]``, not ``config.url``.
+    """
 
     type: Literal["sse"]
     url: str
@@ -509,7 +532,11 @@ class McpSSEServerConfig(TypedDict):
 
 
 class McpHttpServerConfig(TypedDict):
-    """MCP HTTP server configuration."""
+    """MCP HTTP server configuration.
+
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``config["url"]``, not ``config.url``.
+    """
 
     type: Literal["http"]
     url: str
@@ -653,6 +680,9 @@ class SdkPluginConfig(TypedDict):
 class SandboxNetworkConfig(TypedDict, total=False):
     """Network configuration for sandbox.
 
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``config["allowLocalBinding"]``, not ``config.allowLocalBinding``.
+
     Attributes:
         allowUnixSockets: Unix socket paths accessible in sandbox (e.g., SSH agents).
         allowAllUnixSockets: Allow all Unix sockets (less secure).
@@ -686,6 +716,9 @@ class SandboxSettings(TypedDict, total=False):
     This controls how Claude Code sandboxes bash commands for filesystem
     and network isolation.
 
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``settings["enabled"]``, not ``settings.enabled``.
+
     **Important:** Filesystem and network restrictions are configured via permission
     rules, not via these sandbox settings:
     - Filesystem read restrictions: Use Read deny rules
@@ -957,15 +990,33 @@ class SessionMessage:
 
 
 class ThinkingConfigAdaptive(TypedDict):
+    """Adaptive thinking configuration.
+
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``config["type"]``, not ``config.type``.
+    """
+
     type: Literal["adaptive"]
 
 
 class ThinkingConfigEnabled(TypedDict):
+    """Enabled thinking configuration with a token budget.
+
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``config["budget_tokens"]``, not ``config.budget_tokens``.
+    """
+
     type: Literal["enabled"]
     budget_tokens: int
 
 
 class ThinkingConfigDisabled(TypedDict):
+    """Disabled thinking configuration.
+
+    Note: This is a TypedDict. Instances are plain dicts at runtime.
+    Use ``config["type"]``, not ``config.type``.
+    """
+
     type: Literal["disabled"]