feat: increase default buffer size to 10MB and improve error messages

- Increase _DEFAULT_MAX_BUFFER_SIZE from 1MB to 10MB to accommodate modern
  MCP tools (e.g., Puppeteer evaluate() with DOM data, large file contents)
- Add warning when buffer reaches 80% capacity to help users debug before
  hitting the limit
- Improve error message with clearer guidance on increasing max_buffer_size
- Enhance documentation for ClaudeAgentOptions.max_buffer_size with examples

Background:
The 1MB default was too small for real-world MCP tool responses. Puppeteer's
evaluate() can return 5-7MB when extracting computed CSS styles from DOM
elements. This caused frequent crashes with 'JSON message exceeded maximum
buffer size' errors.

The max_buffer_size parameter was already configurable but:
1. The 1MB default was too conservative
2. Documentation didn't mention it clearly
3. Users resorted to hackish fixes (modifying site-packages directly)

This change makes the SDK work better out-of-the-box while maintaining
full backwards compatibility. Users can still override via ClaudeAgentOptions.

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -28,7 +28,10 @@ from . import Transport
 
 logger = logging.getLogger(__name__)
 
-_DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024  # 1MB buffer limit
+# Default buffer size increased from 1MB to 10MB to accommodate modern MCP tools
+# that may return large responses (e.g., Puppeteer evaluate() with DOM data,
+# large file contents, etc.). Users can override via ClaudeAgentOptions.max_buffer_size
+_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024  # 10MB buffer limit
 MINIMUM_CLAUDE_CODE_VERSION = "2.0.0"
 
 # Platform-specific command line length limits
@@ -582,11 +585,22 @@ class SubprocessCLITransport(Transport):
                     # Keep accumulating partial JSON until we can parse it
                     json_buffer += json_line
 
-                    if len(json_buffer) > self._max_buffer_size:
-                        buffer_length = len(json_buffer)
+                    buffer_length = len(json_buffer)
+
+                    # Warn when buffer reaches 80% capacity
+                    if buffer_length > self._max_buffer_size * 0.8 and buffer_length <= self._max_buffer_size:
+                        logger.warning(
+                            f"JSON buffer size ({buffer_length:,} bytes) is approaching the limit "
+                            f"({self._max_buffer_size:,} bytes). Consider increasing max_buffer_size "
+                            f"in ClaudeAgentOptions if you encounter buffer overflow errors."
+                        )
+
+                    if buffer_length > self._max_buffer_size:
                         json_buffer = ""
                         raise SDKJSONDecodeError(
-                            f"JSON message exceeded maximum buffer size of {self._max_buffer_size} bytes",
+                            f"JSON message exceeded maximum buffer size of {self._max_buffer_size:,} bytes. "
+                            f"Actual size: {buffer_length:,} bytes. "
+                            f"Increase max_buffer_size in ClaudeAgentOptions to handle larger responses.",
                             ValueError(
                                 f"Buffer size {buffer_length} exceeds limit {self._max_buffer_size}"
                             ),

src/claude_agent_sdk/types.py

@@ -639,7 +639,9 @@ class ClaudeAgentOptions:
     extra_args: dict[str, str | None] = field(
         default_factory=dict
     )  # Pass arbitrary CLI flags
-    max_buffer_size: int | None = None  # Max bytes when buffering CLI stdout
+    max_buffer_size: int | None = None  # Max bytes when buffering CLI stdout (default: 10MB).
+    # Increase this if you use MCP tools that return large responses (e.g., Puppeteer with DOM extraction,
+    # large file contents). Example: max_buffer_size=20*1024*1024 for 20MB limit.
     debug_stderr: Any = (
         sys.stderr
     )  # Deprecated: File-like object for debug output. Use stderr callback instead.