transport: drop --debug-to-stderr detection (prep for CLI flag removal) (#860)

The CLI's `--debug-to-stderr` flag is being removed in favor of
`--debug-file` (TS SDK already migrated in
anthropics/claude-cli-internal#30630).

**Unlike the TS SDK, this SDK never set `--debug-to-stderr` internally**
— it only *detected* whether users passed it via `extra_args`, to decide
whether to pipe stderr and feed the deprecated `debug_stderr` file
object. So there is no internal flag-send to switch to `--debug-file`.

This PR:
- Pipes stderr based solely on whether a `stderr` callback is registered
(drops the `"debug-to-stderr" in extra_args` checks).
- Removes the deprecated `debug_stderr` write path (already deprecated;
now unreachable). The field stays on `ClaudeAgentOptions` for source
compat but is no longer read by the transport.
- Updates `examples/stderr_callback_example.py` to not pass
`debug-to-stderr`; points users at `extra_args={"debug-file": "/path"}`
for verbose CLI logs.
- Drops the e2e test that asserted on `[DEBUG]` stderr content (depended
on the flag); the no-debug callback test remains.

**Behavior delta:** users who currently pass
`extra_args={"debug-to-stderr": None}` with only `debug_stderr=` (no
`stderr=` callback) will no longer get debug output written to that file
object. Migration: use the `stderr` callback, or pass
`extra_args={"debug-file": "/path"}` and read the file.

Unblocks step 2 (removing `--debug-to-stderr` from the CLI) without
breaking this SDK's example/e2e on the next CLI release.

Author: timgu0

e2e-tests/test_stderr_callback.py

@@ -5,35 +5,10 @@
 from claude_agent_sdk import ClaudeAgentOptions, query
 
 
-@pytest.mark.e2e
-@pytest.mark.asyncio
-async def test_stderr_callback_captures_debug_output():
-    """Test that stderr callback receives debug output when enabled."""
-    stderr_lines = []
-
-    def capture_stderr(line: str):
-        stderr_lines.append(line)
-
-    # Enable debug mode to generate stderr output
-    options = ClaudeAgentOptions(
-        stderr=capture_stderr, extra_args={"debug-to-stderr": None}
-    )
-
-    # Run a simple query
-    async for _ in query(prompt="What is 1+1?", options=options):
-        pass  # Just consume messages
-
-    # Verify we captured debug output
-    assert len(stderr_lines) > 0, "Should capture stderr output with debug enabled"
-    assert any("[DEBUG]" in line for line in stderr_lines), (
-        "Should contain DEBUG messages"
-    )
-
-
 @pytest.mark.e2e
 @pytest.mark.asyncio
 async def test_stderr_callback_without_debug():
-    """Test that stderr callback works but receives no output without debug mode."""
+    """Test that stderr callback is wired up and receives no output on a clean run."""
     stderr_lines = []
 
     def capture_stderr(line: str):

examples/stderr_callback_example.py

@@ -18,11 +18,10 @@ def stderr_callback(message: str):
         if "[ERROR]" in message:
             print(f"Error detected: {message}")
 
-    # Create options with stderr callback and enable debug mode
-    options = ClaudeAgentOptions(
-        stderr=stderr_callback,
-        extra_args={"debug-to-stderr": None}  # Enable debug output
-    )
+    # Create options with stderr callback. The callback receives any stderr the
+    # CLI emits (warnings, errors). For verbose CLI debug logs, pass
+    # extra_args={"debug-file": "/path/to/log"} and read that file instead.
+    options = ClaudeAgentOptions(stderr=stderr_callback)
 
     # Run a query
     print("Running query with stderr capture...")

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -439,14 +439,8 @@ async def connect(self) -> None:
             if self._cwd:
                 process_env["PWD"] = self._cwd
 
-            # Pipe stderr if we have a callback OR debug mode is enabled
-            should_pipe_stderr = (
-                self._options.stderr is not None
-                or "debug-to-stderr" in self._options.extra_args
-            )
-
-            # For backward compat: use debug_stderr file object if no callback and debug is on
-            stderr_dest = PIPE if should_pipe_stderr else None
+            # Pipe stderr only when the caller registered a callback.
+            stderr_dest = PIPE if self._options.stderr is not None else None
 
             self._process = await anyio.open_process(
                 cmd,
@@ -462,7 +456,7 @@ async def connect(self) -> None:
                 self._stdout_stream = TextReceiveStream(self._process.stdout)
 
             # Setup stderr stream if piped
-            if should_pipe_stderr and self._process.stderr:
+            if stderr_dest is PIPE and self._process.stderr:
                 self._stderr_stream = TextReceiveStream(self._process.stderr)
                 # Start async task to read stderr
                 self._stderr_task_group = anyio.create_task_group()
@@ -505,15 +499,6 @@ async def _handle_stderr(self) -> None:
                 # Call the stderr callback if provided
                 if self._options.stderr:
                     self._options.stderr(line_str)
-
-                # For backward compatibility: write to debug_stderr if in debug mode
-                elif (
-                    "debug-to-stderr" in self._options.extra_args
-                    and self._options.debug_stderr
-                ):
-                    self._options.debug_stderr.write(line_str + "\n")
-                    if hasattr(self._options.debug_stderr, "flush"):
-                        self._options.debug_stderr.flush()
         except anyio.ClosedResourceError:
             pass  # Stream closed, exit normally
         except Exception:

src/claude_agent_sdk/types.py

@@ -1467,7 +1467,7 @@ class ClaudeAgentOptions:
     max_buffer_size: int | None = None  # Max bytes when buffering CLI stdout
     debug_stderr: Any = (
         sys.stderr
-    )  # Deprecated: File-like object for debug output. Use stderr callback instead.
+    )  # Deprecated and no longer read by the transport. Use the stderr callback.
     stderr: Callable[[str], None] | None = None  # Callback for stderr output from CLI
 
     # Tool permission callback