fix(llma): graceful fallback in claude_agent_sdk wrapper

[andrewm4894]

Problem

The posthoganalytics.ai.claude_agent_sdk.query() convenience function crashes with ValueError("API key is required") when PostHog is not configured. This breaks the "drop-in replacement" contract — callers who import the wrapper expecting fail-safe instrumentation get a hard crash instead.

This caused StampHog (PostHog's PR approval agent) to fail on every review after posthoganalytics 7.10.x shipped the ai.claude_agent_sdk module. See PostHog/posthog#53964 for the downstream fix.

The same client or setup() pattern exists across all AI wrappers (openai, anthropic, gemini, langchain, openai_agents) — they would all crash the same way. This PR scopes the fix to claude_agent_sdk only; a broader hardening pass can follow.

Changes

In the query() convenience function, catch initialization errors and fall back to the plain claude_agent_sdk.query() with a warning log. The wrapper is now fail-safe: if PostHog isn't configured, it transparently delegates to the original SDK.

How did you test this code?

Added TestQueryGracefulFallback — patches PostHogClaudeAgentProcessor to raise ValueError and verifies messages are still yielded from the original query.

[github-actions]

posthog-python Compliance Report

Date: 2026-04-09 20:11:09 UTC
Duration: 169ms

✅ All Tests Passed!

0/0 tests passed

---

[greptile-apps]

Vulnerabilities

No security concerns identified. The change adds error handling around PostHog client initialisation and does not alter authentication, data handling, or secret management paths.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: posthog/test/ai/claude_agent_sdk/test_processor.py
Line: 589

Comment:
**`_make_result` is undefined — test will crash with `NameError`**

The helper is named `_make_result_message` (defined at line 94), but the new test calls `_make_result()`. This will raise `NameError: name '_make_result' is not defined` before the assertion is ever reached.

```suggestion
        result_msg = _make_result_message()
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: posthog/ai/claude_agent_sdk/__init__.py
Line: 129-133

Comment:
**Overly broad exception catch — consider narrowing and adding a clarifying comment**

Catching `Exception` will silently swallow any programming error during processor initialisation (e.g. a typo in an argument name, an unexpected import side-effect). The known failure mode is `ValueError` from `setup()` when no API key is configured. Narrowing the guard keeps the fail-safe intent while surfacing real bugs, and an inline comment explains why the fallback exists:

```suggestion
    except (ValueError, RuntimeError) as e:
        # PostHog is not configured (e.g. missing API key); fall back to the
        # plain SDK so callers are never broken by missing instrumentation.
        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
```

**Rule Used:** Add inline comments to clarify the purpose of sign... ([source](https://app.greptile.com/review/custom-context?memory=4d5b48c5-045d-4693-9cd9-4081bb19508b))

**Learnt From**
[PostHog/posthog#32083](https://github.com/PostHog/posthog/pull/32083)

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "chore: bump version to 7.10.4" | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 480bed9877

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".