fix(pydantic_ai): allowlist kwargs pass-through, drop eager message reshape (#610)

## Summary

Aligns the pydantic_ai integration with
`.agents/skills/sdk-integrations/SKILL.md`, following the same pattern
as #606 (openai), #608 (openrouter), and #604/#603/#594
(anthropic/livekit/litellm/mistral). Audit turned up two issues:

- **Denylist metadata pass-through (real leak vector).**
`_build_agent_input_and_metadata` and
`_build_direct_model_input_and_metadata` did `for key, value in
kwargs.items(): if key not in [...]: input_data[key] = value` — every
non-`deps` / non-`{model,messages}` kwarg landed in span input. That
flowed `usage` (a mutable counter), `event_stream_handler` (a callable),
`infer_name`, `instrument`, and anything pydantic_ai adds in future SDK
versions straight into telemetry. `deps` (user's app-level container —
commonly holds API keys / DB connections) was the sole excluded key on
the agent path; on the direct-model path there was no exclusion at all.

Replaced with per-surface allowlist tuples (`_AGENT_INPUT_ALLOWLIST`,
`_DIRECT_MODEL_INPUT_ALLOWLIST`) covering the known kwargs across
`Agent.run` / `run_sync` / `run_stream` / `run_stream_events` /
`to_cli_sync` and `direct.model_request*`. Explicitly excludes `deps`,
`usage`, `event_stream_handler`, `infer_name`, `instrument`.

- **Eager message reshaping dropping fields.** `_shape_message` /
`_shape_content_part` / `_shape_model_response` reshaped every message
into shallow dicts via a hard-coded field allowlist (`_MESSAGE_FIELDS`,
`_PART_FIELDS`, `_RESPONSE_FIELDS`) even when no binary content needed
materialization. That dropped real pydantic_ai v2 fields —
`instructions`, `run_id`, `conversation_id`, `metadata`, `state`,
`provider_details`, `outcome`, ... — and burned CPU rebuilding dicts
that `bt_safe_deep_copy` (which already handles dataclasses + Pydantic
models) would produce anyway at log time.

Added `_has_binary_leaf` walker; the four shape helpers now
short-circuit to the raw object when no binary is present. Reshape (and
its field allowlist) only runs when a binary attachment actually needs
materialization.

Also:
- Extracted `_shape_toolset(ts)` from a nested 20-line block inside
`_build_agent_input_and_metadata`.
- Trimmed docstrings/comments that just restated the helper name. Kept
the ones explaining non-obvious *why* (portal-thread context
propagation, wrapper-vs-leaf token ownership, 1.78.0 ToolManager alias,
`_system_prompts` private-API access).
- Hoisted `import inspect` from inside `_shape_type` to module top.

## Test plan

- [x] **No new mocks/fakes.** All provider-behavior coverage stays on
the existing `@pytest.mark.vcr` cassette-backed tests.
- [x] **No cassette re-recording.** HTTP behavior unchanged; only
in-process input/shape logic was touched.
- [x] `nox -s "test_pydantic_ai_integration(latest)"` — 68/68 pass
(`pydantic-ai==2.13.0`)
- [x] `nox -s "test_pydantic_ai_integration(1.10.0)"` — 68/68 pass
(min-supported matrix version)
- [x] `nox -s "test_pydantic_ai_wrap_openai(latest)"` — green
- [x] `nox -s "test_pydantic_ai_logfire(latest)"` — 1/1 pass

Two new tests pin the security invariant:
- `test_agent_input_kwargs_are_allowlisted` — asserts `deps` / `usage` /
`event_stream_handler` / `infer_name` never land in span input;
allowlisted kwargs (`instructions`, `usage_limits`, `retries`,
`conversation_id`, `metadata`) do.
- `test_direct_model_request_kwargs_are_allowlisted` — asserts
`instrument` never leaks; `model_settings` / `model_request_parameters`
do.

One existing test replaced:
`test_v2_message_and_response_fields_are_shaped` →
`test_shape_message_and_response_pass_through_when_no_binary` — the old
test was locking in the reshape that was losing v2 fields.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- sfk:created-approved-by -->
Created by abhijeet

<!-- sfk:slack-thread -->
[Slack
thread](https://starfolkai.slack.com/archives/C0AQDETAVT3/p1784659060950489?thread_ts=1784659060.950489&cid=C0AQDETAVT3)

---------

Co-authored-by: Starfolk <noreply@starfolk.ai>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: 3 people

py/src/braintrust/integrations/pydantic_ai/patchers.py

@@ -84,8 +84,6 @@ class _AgentResolveModelSelectionPatcher(FunctionWrapperPatcher):
 
 
 class AgentPatcher(CompositeFunctionWrapperPatcher):
-    """Patch Pydantic AI agent entrypoints for tracing."""
-
     name = "pydantic_ai.agent"
     sub_patchers = (
         _AgentRunPatcher,
@@ -152,10 +150,7 @@ class StreamedResponseSyncStartProducerPatcher(FunctionWrapperPatcher):
 
 class _ToolManagerExecuteFunctionToolPatcher(FunctionWrapperPatcher):
     name = "pydantic_ai.tool_manager.execute_function_tool"
-    # Regression compatibility note: pydantic_ai 1.78.0 moved ToolManager out
-    # of the private ``pydantic_ai._tool_manager`` module into
-    # ``pydantic_ai.tool_manager``. ``pydantic_ai._agent_graph.ToolManager`` is
-    # a stable alias in both the old and new layouts, so patch that seam.
+    # pydantic_ai 1.78.0 relocated ToolManager; `_agent_graph.ToolManager` is a stable alias.
     target_module = "pydantic_ai._agent_graph"
     target_path = "ToolManager._execute_function_tool_call"
     wrapper = _tool_manager_execute_function_tool_wrapper
@@ -191,11 +186,7 @@ def wrap_agent(Agent: Any) -> Any:
 
 
 class ModelClassesPatcher(ClassScanPatcher):
-    """Deprecated compatibility fallback for model subclass scanning.
-
-    Normal setup now wraps resolved models via ``Agent._get_model`` and
-    ``pydantic_ai.direct._prepare_model`` instead of relying on subclass scans.
-    """
+    """Deprecated fallback; normal setup wraps models via `Agent._get_model` and `_prepare_model`."""
 
     name = "pydantic_ai.models"
     priority: ClassVar[int] = 200

py/src/braintrust/integrations/pydantic_ai/test_pydantic_ai_integration.py

@@ -709,25 +709,28 @@ def test_direct_model_request_sync(memory_logger, direct):
 @pytest.mark.vcr
 @pytest.mark.asyncio
 async def test_direct_model_request_with_settings(memory_logger, direct):
-    """Test that model_settings appears in input for direct API calls."""
+    """Test that model_settings appears in input for direct API calls, and that the
+    non-allowlisted `instrument` kwarg (telemetry routing config) does not leak."""
     assert not memory_logger.pop()
 
     messages = [ModelRequest(parts=[UserPromptPart(content="Say hello")])]
     custom_settings = ModelSettings(max_tokens=50, temperature=0.7)
 
     start = time.time()
-    result = await direct.model_request(model=MODEL, messages=messages, model_settings=custom_settings)
+    result = await direct.model_request(
+        model=MODEL,
+        messages=messages,
+        model_settings=custom_settings,
+        # Does not affect the outbound HTTP request; must be dropped from span input.
+        instrument=False,
+    )
     end = time.time()
 
-    # Verify result
     assert result.parts
 
-    # Check spans
     spans = memory_logger.pop()
-    # Direct API calls may create 1 or 2 spans depending on model wrapping
     assert len(spans) >= 1
 
-    # Find the direct API span
     direct_span = next((s for s in spans if s["span_attributes"]["name"] == "model_request"), None)
     assert direct_span is not None
 
@@ -739,10 +742,11 @@ async def test_direct_model_request_with_settings(memory_logger, direct):
     assert settings["max_tokens"] == 50
     assert settings["temperature"] == 0.7
 
-    # Verify model_settings is NOT in metadata
     assert "model_settings" not in direct_span["metadata"], "model_settings should NOT be in metadata"
 
-    # Verify metadata still has model and provider
+    # Security invariant: `instrument` is telemetry-routing config, not user input.
+    assert "instrument" not in direct_span["input"]
+
     assert direct_span["metadata"]["model"] == "gpt-4o-mini"
     assert direct_span["metadata"]["provider"] == "openai"
 
@@ -1103,22 +1107,29 @@ async def test_agent_with_message_history(memory_logger):
 @pytest.mark.vcr
 @pytest.mark.asyncio
 async def test_agent_with_custom_settings(memory_logger):
-    """Test Agent with custom model settings."""
+    """Test Agent with custom model settings, and that non-allowlisted kwargs
+    (`infer_name`, `usage`) do not leak into span input."""
+    from pydantic_ai.usage import RunUsage
+
     assert not memory_logger.pop()
 
     agent = Agent(MODEL)
 
     start = time.time()
-    result = await agent.run("Say hello", model_settings=ModelSettings(max_tokens=20, temperature=0.5, top_p=0.9))
+    result = await agent.run(
+        "Say hello",
+        model_settings=ModelSettings(max_tokens=20, temperature=0.5, top_p=0.9),
+        # Neither affects the outbound HTTP request; both must be dropped from span input.
+        infer_name=False,
+        usage=RunUsage(),
+    )
     end = time.time()
 
     assert result.output
 
-    # Check spans - should now have parent agent_run + nested chat span
     spans = memory_logger.pop()
     assert len(spans) >= 2, f"Expected at least 2 spans (agent_run + chat), got {len(spans)}"
 
-    # Find agent_run span
     agent_span = next(
         (
             s
@@ -1135,6 +1146,11 @@ async def test_agent_with_custom_settings(memory_logger):
     assert settings["max_tokens"] == 20
     assert settings["temperature"] == 0.5
     assert settings["top_p"] == 0.9
+
+    # Security invariant: non-allowlisted kwargs must not leak into span input.
+    assert "infer_name" not in agent_span["input"]
+    assert "usage" not in agent_span["input"]
+
     _assert_metrics_are_valid(agent_span["metrics"], start, end)
 
 
@@ -2370,33 +2386,25 @@ def request_stream(self, *args, **kwargs):
     assert not [warning for warning in caught if issubclass(warning.category, DeprecationWarning)]
 
 
-def test_v2_message_and_response_fields_are_shaped():
+def test_shape_message_and_response_pass_through_when_no_binary():
+    # No binary content -> return the object unchanged so Braintrust's dataclass/Pydantic
+    # serializer preserves every field (including new v2 fields like state, provider_name,
+    # run_id, conversation_id, metadata, ...). Reshaping was dropping those.
     from types import SimpleNamespace
 
     from braintrust.integrations.pydantic_ai.tracing import _shape_message, _shape_model_response
 
     message = SimpleNamespace(kind="request", state="complete", parts=["hello"])
-    assert _shape_message(message)["state"] == "complete"
+    assert _shape_message(message) is message
 
     response = SimpleNamespace(
         kind="response",
         state="complete",
         model_name="gpt-4o-mini",
         provider_name="openai",
-        provider_url="https://api.openai.com/v1/responses",
-        finish_reason="stop",
-        run_id="run-123",
-        conversation_id="conv-123",
         parts=["done"],
     )
-
-    shaped = _shape_model_response(response)
-    assert shaped["state"] == "complete"
-    assert shaped["provider_name"] == "openai"
-    assert shaped["provider_url"] == "https://api.openai.com/v1/responses"
-    assert shaped["finish_reason"] == "stop"
-    assert shaped["run_id"] == "run-123"
-    assert shaped["conversation_id"] == "conv-123"
+    assert _shape_model_response(response) is response
 
 
 def test_v2_model_provider_inference():