feat: Add debug_stderr parameter for flexible debug output routing

- Add debug_stderr field to ClaudeCodeOptions with sys.stderr as default
- Allows customers to route debug output to files, buffers, or custom streams
- Maintains backward compatibility while providing maximum flexibility
- Only routes debug output when both debug-to-stderr flag and debug_stderr are set

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ashwin-ant

src/claude_code_sdk/_internal/transport/subprocess_cli.py

@@ -4,7 +4,6 @@
 import logging
 import os
 import shutil
-import sys
 from collections.abc import AsyncIterable, AsyncIterator
 from contextlib import suppress
 from pathlib import Path
@@ -181,9 +180,12 @@ async def connect(self) -> None:
             if self._cwd:
                 process_env["PWD"] = self._cwd
 
-            # Only output stderr if customer explicitly requested debug output
+            # Only output stderr if customer explicitly requested debug output and provided a file object
             stderr_dest = (
-                sys.stderr if "debug-to-stderr" in self._options.extra_args else None
+                self._options.debug_stderr
+                if "debug-to-stderr" in self._options.extra_args
+                and self._options.debug_stderr
+                else None
             )
 
             self._process = await anyio.open_process(

src/claude_code_sdk/types.py

@@ -1,5 +1,6 @@
 """Type definitions for Claude SDK."""
 
+import sys
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -250,6 +251,9 @@ class ClaudeCodeOptions:
     extra_args: dict[str, str | None] = field(
         default_factory=dict
     )  # Pass arbitrary CLI flags
+    debug_stderr: Any = (
+        sys.stderr
+    )  # File-like object for debug output when debug-to-stderr is set
 
     # Tool permission callback
     can_use_tool: CanUseTool | None = None