feat: propagate W3C trace context (TRACEPARENT) to CLI subprocess (#821)

## What

If the SDK caller has an active OpenTelemetry span, inject its W3C trace
context into the CLI subprocess env as `TRACEPARENT`/`TRACESTATE`. The
CLI reads these in headless mode and parents its
`claude_code.interaction` spans under the caller's distributed trace.

- Optional: `pip install claude-agent-sdk[otel]` pulls
`opentelemetry-api`. Gracefully no-ops if not installed.
- `setdefault` so `ClaudeAgentOptions(env={"TRACEPARENT": ...})` wins.

## Why

Agent SDK customers see CLI traces as disconnected roots in their
collector. This is the minimal change to enable distributed tracing
end-to-end without adding a `tracer` option (consistent with the
env-var-only config decision).

Relates to #452. This PR does not add in-process SDK spans (#530/#542) —
only context propagation to the CLI.

## Requires

`claude` CLI **≥ v2.1.110** for the propagation to take effect — earlier
versions ignore `TRACEPARENT` (harmless no-op, spans just stay as
roots).

## Proof

- `pytest tests/test_transport.py` — 62 pass (3 new)
- `ruff check` / `ruff format --check` / `mypy src/` — clean

Author: qing-ant

pyproject.toml

@@ -39,6 +39,9 @@ dev = [
     "mypy>=1.0.0",
     "ruff>=0.1.0",
 ]
+otel = [
+    "opentelemetry-api>=1.20.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/anthropics/claude-agent-sdk-python"
@@ -84,6 +87,12 @@ warn_no_return = true
 warn_unreachable = true
 strict_equality = true
 
+[[tool.mypy.overrides]]
+# opentelemetry-api is an optional dependency (the [otel] extra); the
+# import in subprocess_cli.py is guarded by try/except ImportError.
+module = ["opentelemetry", "opentelemetry.*"]
+ignore_missing_imports = true
+
 [tool.ruff]
 target-version = "py310"
 line-length = 88

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -361,6 +361,32 @@ async def connect(self) -> None:
                 "CLAUDE_AGENT_SDK_VERSION": __version__,
             }
 
+            # Propagate active OTEL trace context to the CLI so its spans
+            # parent under the caller's distributed trace. No-op if
+            # opentelemetry-api is not installed or there's no active span.
+            try:
+                from opentelemetry import propagate
+
+                carrier: dict[str, str] = {}
+                propagate.inject(carrier)
+                if "traceparent" in carrier:
+                    # Active span present: scrub stale inherited W3C context
+                    # (CI/k8s ambient env) before writing the fresh values, so
+                    # an inherited TRACESTATE isn't paired with a new
+                    # TRACEPARENT. Explicit ClaudeAgentOptions.env always wins.
+                    # Gate on the traceparent key (not carrier truthiness) so a
+                    # baggage-only / non-W3C carrier doesn't scrub a valid
+                    # inherited TRACEPARENT.
+                    for key in ("TRACEPARENT", "TRACESTATE"):
+                        if key not in self._options.env:
+                            process_env.pop(key, None)
+                    for k, v in carrier.items():
+                        key = k.upper()
+                        if key not in self._options.env:
+                            process_env[key] = v
+            except Exception:  # noqa: BLE001 - best-effort tracing must never break connect()
+                logger.debug("OTEL trace context injection failed", exc_info=True)
+
             # Enable file checkpointing if requested
             if self._options.enable_file_checkpointing:
                 process_env["CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING"] = "true"