SubprocessCLITransport.close() hangs indefinitely if subprocess shutdown handler blocks

[xu-jenny]

Bug

SubprocessCLITransport.close() in the Python claude-agent-sdk sends SIGTERM to the Claude Code subprocess, then calls await self._process.wait() with no timeout. If the Claude Code Node.js process catches SIGTERM and runs a shutdown handler that gets stuck (e.g., waiting for an MCP server or subagent to exit), process.wait() blocks forever.

Impact

In our use case (running ~200 parallel Claude Code instances via the SDK), 30% of jobs hung indefinitely — Claude code job finished successfully but the VM stayed hanging because the SDK's transport.close() never returned, causing the entire worker process to hit VM infra timeout.

Suggested fix

Wrap this in close()

  async def close(self) -> None:
      if self._process and self._process.returncode is None:
          self._process.terminate()
          try:
              async with anyio.fail_after(shutdown_timeout):  # e.g. 30s
                  await self._process.wait()
          except TimeoutError:
              self._process.kill()
              await self._process.wait()
      self._process = None

Ideally shutdown_timeout would be configurable via ClaudeAgentOptions (we used 30s successfully).

[qing-ant]

This is a duplicate of #378, which describes the same root cause: close() hangs indefinitely because the subprocess/task group cleanup has no timeout, causing the caller to block forever.

PR #729 addresses this by adding a SIGKILL fallback with a configurable timeout — the same fix pattern suggested here. The SubprocessCLITransport.close() hang described in this issue is the underlying transport-level manifestation of the Query.close() hang in #378 (since Query.close() calls transport.close() internally).

Closing as duplicate. Please follow #378 and PR #729 for progress.

[kcarriedo]

Worth flagging that terminate() → kill() on the single self._process still leaks MCP / subagent descendants. If the Node process spawned an MCP stdio server that itself spawned a child, SIGKILL on the parent leaves the grandchild reparented to PID 1 — still holding ports, file descriptors, and (worst case) still issuing tool calls. The robust fix is to spawn with a fresh process group (os.setsid / start_new_session=True in asyncio.create_subprocess_exec) and on the kill path call os.killpg(pgid, signal.SIGKILL). We hit this exact failure mode building a scheduler around claude and the only thing that reliably reaped everything was a process-group kill.