Merge origin/main into feat/include-hook-events

Author: qing-ant

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -1,11 +1,13 @@
 """Subprocess transport implementation using Claude Code CLI."""
 
+import atexit
 import json
 import logging
 import os
 import platform
 import re
 import shutil
+import signal
 from collections.abc import AsyncIterable, AsyncIterator
 from contextlib import suppress
 from pathlib import Path
@@ -28,6 +30,22 @@
 _DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024  # 1MB buffer limit
 MINIMUM_CLAUDE_CODE_VERSION = "2.0.0"
 
+# Track live CLI subprocesses so we can terminate them when the parent Python
+# process exits. This mirrors the TypeScript SDK's parent-exit cleanup and
+# prevents orphaned `claude` processes from leaking when callers crash or exit
+# before awaiting close().
+_ACTIVE_CHILDREN: set[Process] = set()
+
+
+def _kill_active_children() -> None:
+    for p in list(_ACTIVE_CHILDREN):
+        with suppress(Exception):
+            p.send_signal(signal.SIGTERM)  # On Windows anyio maps this to terminate()
+    _ACTIVE_CHILDREN.clear()
+
+
+atexit.register(_kill_active_children)
+
 
 class SubprocessCLITransport(Transport):
     """Subprocess transport using Claude Code CLI."""
@@ -319,6 +337,9 @@ def _build_command(self) -> list[str]:
         if self._options.include_hook_events:
             cmd.append("--include-hook-events")
 
+        if self._options.strict_mcp_config:
+            cmd.append("--strict-mcp-config")
+
         if self._options.fork_session:
             cmd.append("--fork-session")
 
@@ -459,6 +480,7 @@ async def connect(self) -> None:
                 env=process_env,
                 user=self._options.user,
             )
+            _ACTIVE_CHILDREN.add(self._process)
 
             if self._process.stdout:
                 self._stdout_stream = TextReceiveStream(self._process.stdout)
@@ -542,23 +564,26 @@ async def close(self) -> None:
         # The subprocess needs time to flush its session file after receiving
         # EOF on stdin. Without this grace period, SIGTERM can interrupt the
         # write and cause the last assistant message to be lost (see #625).
-        if self._process.returncode is None:
-            try:
-                with anyio.fail_after(5):
-                    await self._process.wait()
-            except TimeoutError:
-                # Graceful shutdown timed out — force terminate
-                with suppress(ProcessLookupError):
-                    self._process.terminate()
+        try:
+            if self._process.returncode is None:
                 try:
                     with anyio.fail_after(5):
                         await self._process.wait()
                 except TimeoutError:
-                    # SIGTERM handler blocked — force kill (SIGKILL)
+                    # Graceful shutdown timed out — force terminate
                     with suppress(ProcessLookupError):
-                        self._process.kill()
-                    with suppress(Exception):
-                        await self._process.wait()
+                        self._process.terminate()
+                    try:
+                        with anyio.fail_after(5):
+                            await self._process.wait()
+                    except TimeoutError:
+                        # SIGTERM handler blocked — force kill (SIGKILL)
+                        with suppress(ProcessLookupError):
+                            self._process.kill()
+                        with suppress(Exception):
+                            await self._process.wait()
+        finally:
+            _ACTIVE_CHILDREN.discard(self._process)
 
         self._process = None
         self._stdout_stream = None

src/claude_agent_sdk/types.py

@@ -1542,6 +1542,13 @@ class ClaudeAgentOptions:
     to an MCP config JSON file.
     """
 
+    strict_mcp_config: bool = False
+    """When ``True``, only use MCP servers passed via :attr:`mcp_servers`,
+    ignoring all other MCP configurations the CLI would otherwise load (e.g.
+    project ``.mcp.json``, user/global settings, plugin-provided servers).
+    Maps to the CLI's ``--strict-mcp-config`` flag and matches the TypeScript
+    SDK's ``strictMcpConfig`` option."""
+
     permission_mode: PermissionMode | None = None
     """Permission mode for the session.
 

tests/test_transport.py

@@ -90,6 +90,16 @@ def test_build_command_include_hook_events(self):
         cmd_off = transport_off._build_command()
         assert "--include-hook-events" not in cmd_off
 
+    def test_build_command_strict_mcp_config(self):
+        """Test that --strict-mcp-config is emitted only when enabled."""
+        transport = SubprocessCLITransport(
+            prompt="test", options=make_options(strict_mcp_config=True)
+        )
+        assert "--strict-mcp-config" in transport._build_command()
+
+        transport = SubprocessCLITransport(prompt="test", options=make_options())
+        assert "--strict-mcp-config" not in transport._build_command()
+
     def test_cli_path_accepts_pathlib_path(self):
         """Test that cli_path accepts pathlib.Path objects."""
         from pathlib import Path
@@ -2050,3 +2060,34 @@ async def _test():
                 mock_logger.warning.assert_not_called()
 
         anyio.run(_test)
+
+
+class TestAtexitChildCleanup:
+    """Tests for the atexit handler that terminates orphaned CLI subprocesses."""
+
+    def test_kill_active_children_terminates_process(self) -> None:
+        import sys
+
+        from claude_agent_sdk._internal.transport import subprocess_cli
+
+        async def _test() -> None:
+            proc = await anyio.open_process(
+                [sys.executable, "-c", "import time; time.sleep(30)"]
+            )
+            subprocess_cli._ACTIVE_CHILDREN.add(proc)
+            try:
+                assert proc.returncode is None
+
+                subprocess_cli._kill_active_children()
+
+                assert not subprocess_cli._ACTIVE_CHILDREN
+                with anyio.fail_after(5):
+                    await proc.wait()
+                assert proc.returncode is not None
+            finally:
+                subprocess_cli._ACTIVE_CHILDREN.discard(proc)
+                if proc.returncode is None:
+                    proc.kill()
+                    await proc.wait()
+
+        anyio.run(_test)