Interactive PTY transport (TUI question handling + API-traffic enrichment)

examples/pty_interactive.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Demonstrates the SDK driving the interactive Claude Code CLI over a PTY.
+
+Since v-next, the SDK launches the *interactive* CLI attached to a
+pseudo-terminal instead of the headless ``stream-json`` pipe. This is an
+internal implementation detail -- the public ``query()`` / ``ClaudeSDKClient``
+API is unchanged -- so this example looks like any other.
+
+Run it on a machine where you are already logged in to Claude Code::
+
+    python examples/pty_interactive.py
+"""
+
+import anyio
+
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ClaudeSDKClient,
+    ResultMessage,
+    TextBlock,
+    query,
+)
+
+
+async def one_shot() -> None:
+    """A single prompt via the one-shot ``query()`` helper."""
+    print("=== one-shot query() ===")
+    async for message in query(prompt="Reply with a single word: pong"):
+        if isinstance(message, AssistantMessage):
+            for block in message.content:
+                if isinstance(block, TextBlock):
+                    print(f"Claude: {block.text.strip()}")
+        elif isinstance(message, ResultMessage):
+            print(f"(done in {message.duration_ms} ms)")
+    print()
+
+
+async def multi_turn() -> None:
+    """A persistent interactive session with several turns."""
+    print("=== multi-turn ClaudeSDKClient ===")
+    options = ClaudeAgentOptions()
+    async with ClaudeSDKClient(options=options) as client:
+        for prompt in (
+            "Say the word 'apple' and nothing else.",
+            "Now say the word 'banana' and nothing else.",
+        ):
+            await client.query(prompt)
+            async for message in client.receive_response():
+                if isinstance(message, AssistantMessage):
+                    for block in message.content:
+                        if isinstance(block, TextBlock):
+                            print(f"Claude: {block.text.strip()}")
+    print()
+
+
+async def main() -> None:
+    await one_shot()
+    await multi_turn()
+
+
+if __name__ == "__main__":
+    anyio.run(main)

pyproject.toml

@@ -42,6 +42,11 @@ dev = [
 otel = [
     "opentelemetry-api>=1.20.0",
 ]
+pty-introspect = [
+    # Terminal emulator used by PtyCLITransport.detect_question() to
+    # reconstruct the rendered screen and parse blocking TUI dialogs.
+    "pyte>=0.8.1",
+]
 examples = [
     # Backend clients for the SessionStore reference adapters under
     # examples/session_stores/. The corresponding tests importorskip on
@@ -101,6 +106,12 @@ strict_equality = true
 module = ["opentelemetry", "opentelemetry.*"]
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+# pyte is an optional dependency (the [pty-introspect] extra) and ships no type
+# stubs; the imports in pty_cli.py / pty_question.py are guarded by try/except.
+module = ["pyte", "pyte.*"]
+ignore_missing_imports = true
+
 [tool.ruff]
 target-version = "py310"
 line-length = 88

src/claude_agent_sdk/_internal/client.py

@@ -22,7 +22,7 @@
 )
 from .session_store_validation import validate_session_store_options
 from .transport import Transport
-from .transport.subprocess_cli import SubprocessCLITransport
+from .transport.pty_cli import PtyCLITransport
 
 
 class InternalClient:
@@ -124,7 +124,7 @@ async def _process_query_inner(
         if transport is not None:
             chosen_transport = transport
         else:
-            chosen_transport = SubprocessCLITransport(
+            chosen_transport = PtyCLITransport(
                 prompt=prompt,
                 options=configured_options,
             )