fix: graceful fallback in claude_agent_sdk query wrapper when PostHog not configured

When PostHog is not configured (no API key), the query() convenience
function now catches the initialization error and falls back to the
plain claude_agent_sdk.query() with a warning log instead of crashing.

The wrapper should be fail-safe — instrumentation is additive and must
never break the underlying SDK call.

Author: andrewm4894

posthog/ai/claude_agent_sdk/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Union
 
 if TYPE_CHECKING:
@@ -17,6 +18,8 @@
 from posthog.ai.claude_agent_sdk.client import PostHogClaudeSDKClient
 from posthog.ai.claude_agent_sdk.processor import PostHogClaudeAgentProcessor
 
+log = logging.getLogger("posthog")
+
 __all__ = [
     "PostHogClaudeAgentProcessor",
     "PostHogClaudeSDKClient",
@@ -113,13 +116,21 @@ async def query(
             print(message)
         ```
     """
-    processor = PostHogClaudeAgentProcessor(
-        client=posthog_client,
-        distinct_id=posthog_distinct_id,
-        privacy_mode=posthog_privacy_mode,
-        groups=posthog_groups,
-        properties={},
-    )
+    from claude_agent_sdk import query as original_query
+
+    try:
+        processor = PostHogClaudeAgentProcessor(
+            client=posthog_client,
+            distinct_id=posthog_distinct_id,
+            privacy_mode=posthog_privacy_mode,
+            groups=posthog_groups,
+            properties={},
+        )
+    except Exception as e:
+        log.warning("PostHog instrumentation disabled: %s — falling back to plain claude_agent_sdk.query()", e)
+        async for message in original_query(prompt=prompt, options=options, transport=transport):
+            yield message
+        return
 
     async for message in processor.query(
         prompt=prompt,

posthog/test/ai/claude_agent_sdk/test_processor.py

@@ -19,6 +19,7 @@
     from posthog.ai.claude_agent_sdk import (
         PostHogClaudeAgentProcessor,
         instrument,
+        query as posthog_query,
     )
 
     CLAUDE_AGENT_SDK_AVAILABLE = True
@@ -580,3 +581,21 @@ async def fake_query_capture(**kwargs):
                 pass
 
         assert captured_options.get("options").include_partial_messages is True
+
+
+class TestQueryGracefulFallback:
+    @pytest.mark.asyncio
+    async def test_falls_back_to_original_query_when_posthog_not_configured(self):
+        result_msg = _make_result()
+        messages_from_sdk = [result_msg]
+
+        with (
+            patch("posthog.ai.claude_agent_sdk.PostHogClaudeAgentProcessor", side_effect=ValueError("API key is required")),
+            patch("claude_agent_sdk.query", side_effect=lambda **kwargs: _fake_query(messages_from_sdk)),
+        ):
+            collected = []
+            async for msg in posthog_query(prompt="Hello", options=ClaudeAgentOptions()):
+                collected.append(msg)
+
+        assert len(collected) == 1
+        assert collected[0] is result_msg