fix: pass AI Config model parameters through to every provider handler

packages/claude-agents/src/launchdarkly_ai_claude_agents/handler.py

@@ -53,6 +53,8 @@
 )
 from launchdarkly_ai_server.agui import TurnEmitter
 from launchdarkly_ai_server.lifecycle import effective_capture_content
+from launchdarkly_ai_server.parameter_forwarding import select_forwarded_parameters
+from launchdarkly_ai_server.utils import model_parameters
 
 from ._version import PACKAGE_NAME, __version__
 from .spans import (
@@ -73,6 +75,94 @@
     tool_display_name,
 )
 
+#: Every field ``ClaudeAgentOptions`` declares, classified by hand into exactly one of: forwarded
+#: (below), handler-owned (``model``, ``allowed_tools``, ``mcp_servers``, ``hooks``, ``tools``,
+#: ``system_prompt``, set by each call site itself), or excluded (below).
+#: ``TestClaudeAgentOptionsAcceptsExactlyTheseFields`` in this package's tests asserts this
+#: classification stays exhaustive as the SDK's own dataclass changes.
+#:
+#: Only model and run settings are forwarded: how the model thinks, how long the run may go, and
+#: what it may spend. Everything that configures the host process the SDK launches (its binary,
+#: environment, working directory, file access, permissions, settings files, plugins, sandbox,
+#: session state) stays under the application's control, never a config's.
+#:
+#: This is the cross-SDK list for Claude Agents (TESTING.md section 1.12), shared with the native
+#: graph through :func:`_options_parameters`.
+#:
+#: The SDK offers no ``temperature``/``top_p``/``top_k``/``max_tokens``/``stop_sequences``/
+#: ``tool_choice``/``metadata``, all of which the LaunchDarkly UI's model parameters panel offers
+#: for other providers; they are dropped like any other key not listed here.
+_CLAUDE_AGENT_OPTIONS_FORWARDED_KEYS = frozenset(
+    {
+        "betas",
+        "effort",
+        "fallback_model",
+        "max_budget_usd",
+        "max_thinking_tokens",
+        "max_turns",
+        "output_format",
+        "thinking",
+    }
+)
+
+#: Forwarded keys whose value must be an object. A config value of any other type is malformed
+#: and dropped rather than passed to ``ClaudeAgentOptions``.
+_CLAUDE_AGENT_OPTIONS_MAPPING_KEYS = frozenset({"output_format", "thinking"})
+
+#: Accepted by ``ClaudeAgentOptions`` but never forwarded, and why:
+#: * ``cli_path``, ``env``, ``cwd``, ``add_dirs``, ``settings``, ``setting_sources``, ``plugins``,
+#:   ``skills``, ``sandbox``, ``user``, ``extra_args``: which binary runs, with what environment,
+#:   as which user, with what files, settings, plugins, and CLI arguments. A config that could set
+#:   these could run code on, or read files from, the host.
+#: * ``permission_mode``, ``permission_prompt_tool_name``, ``can_use_tool``, ``disallowed_tools``,
+#:   ``strict_mcp_config``, ``agents``: what the agent is allowed to do and which tools or
+#:   subagents it gets. The handler wires tools and permissions itself.
+#: * ``resume``, ``session_id``, ``fork_session``, ``continue_conversation``, ``session_store``,
+#:   ``session_store_flush``, ``enable_file_checkpointing``: session state on the host.
+#: * ``stderr``, ``debug_stderr``, ``include_partial_messages``, ``include_hook_events``,
+#:   ``max_buffer_size``, ``load_timeout_ms``: process I/O and transport plumbing, including the
+#:   streamed message shape the handler reads.
+#: * ``task_budget``: not one of the agreed run settings yet; ``max_turns`` and ``max_budget_usd``
+#:   cover run limits.
+#:
+#: Named for the drift test and for review, not read at runtime: the forwarded list above already
+#: leaves these out, so nothing needs to subtract them again.
+_CLAUDE_AGENT_OPTIONS_EXCLUDED_KEYS = frozenset(
+    {
+        "add_dirs",
+        "agents",
+        "can_use_tool",
+        "cli_path",
+        "continue_conversation",
+        "cwd",
+        "debug_stderr",
+        "disallowed_tools",
+        "enable_file_checkpointing",
+        "env",
+        "extra_args",
+        "fork_session",
+        "include_hook_events",
+        "include_partial_messages",
+        "load_timeout_ms",
+        "max_buffer_size",
+        "permission_mode",
+        "permission_prompt_tool_name",
+        "plugins",
+        "resume",
+        "sandbox",
+        "session_id",
+        "session_store",
+        "session_store_flush",
+        "setting_sources",
+        "settings",
+        "skills",
+        "stderr",
+        "strict_mcp_config",
+        "task_budget",
+        "user",
+    }
+)
+
 # ---------------------------------------------------------------------------
 # Tool wiring
 # ---------------------------------------------------------------------------
@@ -504,6 +594,18 @@ def _raise_if_run_failed(message: Any) -> None:
     )
 
 
+def _options_parameters(config: AiConfigRep) -> dict[str, Any]:
+    """The config's ``model.parameters`` that become ``ClaudeAgentOptions`` fields: only
+    :data:`_CLAUDE_AGENT_OPTIONS_FORWARDED_KEYS`, with malformed object values dropped. The handler
+    and the native graph both call this, so they forward the same keys.
+    """
+    return select_forwarded_parameters(
+        model_parameters(config),
+        _CLAUDE_AGENT_OPTIONS_FORWARDED_KEYS,
+        mapping_keys=_CLAUDE_AGENT_OPTIONS_MAPPING_KEYS,
+    )
+
+
 def _build_query_options(
     config: AiConfigRep,
     system_prompt: str | None,
@@ -514,7 +616,9 @@ def _build_query_options(
     **extra: Any,
 ) -> ClaudeAgentOptions:
     all_allowed = [*mcp_allowed_tools, *native_tool_names]
+    params = _options_parameters(config)
     kwargs: dict[str, Any] = {
+        **params,
         "model": config["model"]["name"],
         "allowed_tools": all_allowed if all_allowed else [],
         "mcp_servers": {TOOL_MCP_NAME: tool_mcp} if tool_mcp else {},

packages/claude-agents/src/launchdarkly_ai_claude_agents/native_graph.py

@@ -37,6 +37,7 @@
 
 from launchdarkly_ai_claude_agents.handler import (
     _build_hooks,
+    _options_parameters,
     _raise_if_run_failed,
     build_prompt,
     build_query_prompt,
@@ -158,7 +159,10 @@ async def _run_query(
 
     hooks = _build_hooks(native_tool_map)
 
+    params = _options_parameters(node.config)
+
     options = ClaudeAgentOptions(
+        **params,
         # Explicitly set the available built-in tools (empty list disables all).
         # When no native tools are needed, disable built-in tools so Claude
         # cannot call WebSearch/Bash/etc. and get stuck waiting for permission

packages/claude-agents/tests/test_handler.py

@@ -21,6 +21,7 @@
 import pytest
 from claude_agent_sdk import (
     AssistantMessage,
+    ClaudeAgentOptions,
     ResultMessage,
     StreamEvent,
     SystemMessage,
@@ -43,6 +44,12 @@
     partition_tools,
 )
 from launchdarkly_ai_server import ConversationIdSpanProcessor, conversation_id
+from tests.forwarding_spec import (
+    CLAUDE_AGENTS,
+    candidate_keys,
+    probe_forwarded_keys,
+)
+from tests.never_forwarded import NEVER_FORWARDED_BAG, find_leaks
 
 # ---------------------------------------------------------------------------
 # A real tracer provider, reset between tests
@@ -1606,6 +1613,125 @@ async def test_ld_span_attributes_land_on_root_only(
         assert [e.name for e in root().events] == ["feature_flag"]
 
 
+class TestModelParametersForwarding:
+    async def _run_and_capture_options(
+        self, config: dict[str, Any], monkeypatch: pytest.MonkeyPatch
+    ) -> Any:
+        captured: dict[str, Any] = {}
+
+        async def _query(**kwargs: Any) -> AsyncIterator[Any]:
+            captured["options"] = kwargs["options"]
+            yield assistant_message()
+            yield result_message()
+
+        monkeypatch.setattr(handler_mod, "query", _query)
+        await create_claude_agents_handler()(config, "q")
+        return captured["options"]
+
+    async def test_max_turns_from_config_reaches_options(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        config = {
+            **BASE_CONFIG,
+            "model": {**BASE_CONFIG["model"], "parameters": {"max_turns": 3}},
+        }
+        options = await self._run_and_capture_options(config, monkeypatch)
+        assert options.max_turns == 3
+
+    async def test_config_cannot_override_model_or_system_prompt(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        config = {
+            **BASE_CONFIG,
+            "model": {
+                **BASE_CONFIG["model"],
+                "parameters": {
+                    "model": "not-the-real-model",
+                    "system_prompt": "not-the-real-prompt",
+                },
+            },
+        }
+        options = await self._run_and_capture_options(config, monkeypatch)
+        assert options.model == BASE_CONFIG["model"]["name"]
+        assert options.system_prompt != "not-the-real-prompt"
+
+    async def test_unset_when_no_parameters(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        options = await self._run_and_capture_options(BASE_CONFIG, monkeypatch)
+        assert options.max_turns is None
+
+    async def test_ui_keys_the_sdk_rejects_are_dropped_without_raising(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """``ClaudeAgentOptions`` has no ``temperature``/``top_p``/``top_k``/``max_tokens``/
+        ``stop_sequences``/``tool_choice``/``metadata`` fields, all of which the LaunchDarkly UI's
+        model parameters panel offers for other providers. Forwarding one unfiltered raises
+        ``TypeError`` before any request is made; the filter must drop them instead.
+        """
+        config = {
+            **BASE_CONFIG,
+            "model": {
+                **BASE_CONFIG["model"],
+                "parameters": {
+                    "temperature": 0.2,
+                    "top_p": 0.5,
+                    "top_k": 10,
+                    "max_tokens": 256,
+                    "stop_sequences": ["STOP"],
+                    "tool_choice": "auto",
+                    "metadata": {"user_id": "u1"},
+                    "max_turns": 3,
+                },
+            },
+        }
+        options = await self._run_and_capture_options(config, monkeypatch)
+        assert options.max_turns == 3
+        for rejected in (
+            "temperature",
+            "top_p",
+            "top_k",
+            "max_tokens",
+            "stop_sequences",
+            "tool_choice",
+            "metadata",
+        ):
+            assert not hasattr(options, rejected) or getattr(options, rejected) is None
+
+    async def test_no_never_forwarded_key_reaches_the_query_options(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Every credential, endpoint, request-injection, remote-tool, and host-process key,
+        including the real ``ClaudeAgentOptions`` fields ``cli_path``, ``env``, ``cwd``,
+        ``add_dirs``, ``permission_mode`` and ``can_use_tool``, is dropped on the way to
+        ``query``; the agreed run setting still lands."""
+        config = {
+            **BASE_CONFIG,
+            "model": {
+                **BASE_CONFIG["model"],
+                "parameters": {**NEVER_FORWARDED_BAG, "max_turns": 2},
+            },
+        }
+        options = await self._run_and_capture_options(config, monkeypatch)
+        assert options.max_turns == 2
+        assert not find_leaks(options)
+
+    async def test_temperature_top_p_and_max_turns_run_without_type_error(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A realistic combination of UI-offered keys must not raise, and the one real field
+        (``max_turns``) must still land."""
+        config = {
+            **BASE_CONFIG,
+            "model": {
+                **BASE_CONFIG["model"],
+                "parameters": {"temperature": 0.3, "top_p": 0.8, "max_turns": 5},
+            },
+        }
+        options = await self._run_and_capture_options(config, monkeypatch)
+        assert options.max_turns == 5
+
+
 class TestFinishReasonMapping:
     async def test_tool_use_maps_to_tool_calls(
         self, monkeypatch: pytest.MonkeyPatch
@@ -2395,6 +2521,92 @@ async def _query(**kwargs: Any) -> AsyncIterator[Any]:
         assert tool.end_time is not None
 
 
+#: ``ClaudeAgentOptions`` fields the handler fills with fresh objects on every call (hook
+#: closures, the tool MCP server), so they differ between calls whatever the config says. Every
+#: config-settable field is still compared.
+_PER_CALL_FIELDS = frozenset({"hooks", "mcp_servers"})
+
+
+def _comparable(options: Any) -> dict[str, Any]:
+    import dataclasses
+
+    return {
+        f.name: getattr(options, f.name)
+        for f in dataclasses.fields(options)
+        if f.name not in _PER_CALL_FIELDS
+    }
+
+
+class TestForwardsExactlyTheCrossSdkList:
+    """Probes ``invoke`` and ``stream`` one key at a time: the keys that change the
+    ``ClaudeAgentOptions`` handed to ``query`` are exactly the cross-SDK Claude Agents list, on
+    both paths."""
+
+    @staticmethod
+    def _candidates() -> frozenset[str]:
+        import dataclasses
+
+        return candidate_keys(
+            (f.name for f in dataclasses.fields(ClaudeAgentOptions)), CLAUDE_AGENTS
+        )
+
+    @staticmethod
+    def _config(parameters: dict[str, Any]) -> dict[str, Any]:
+        return {
+            **BASE_CONFIG,
+            "model": {**BASE_CONFIG["model"], "parameters": parameters},
+        }
+
+    def _patch_query(self, monkeypatch: pytest.MonkeyPatch) -> dict[str, Any]:
+        captured: dict[str, Any] = {}
+
+        async def _query(**kwargs: Any) -> AsyncIterator[Any]:
+            captured["options"] = kwargs["options"]
+            yield assistant_message()
+            yield result_message()
+
+        monkeypatch.setattr(handler_mod, "query", _query)
+        return captured
+
+    async def test_invoke(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        captured = self._patch_query(monkeypatch)
+        h = create_claude_agents_handler()
+
+        async def call(parameters: dict[str, Any]) -> object:
+            await h(self._config(parameters), "q")
+            return _comparable(captured["options"])
+
+        assert await probe_forwarded_keys(self._candidates(), call) == CLAUDE_AGENTS
+
+    async def test_stream(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        captured = self._patch_query(monkeypatch)
+        h = create_claude_agents_handler()
+
+        async def call(parameters: dict[str, Any]) -> object:
+            await _collect(await h.stream(self._config(parameters), "q"))
+            return _comparable(captured["options"])
+
+        assert await probe_forwarded_keys(self._candidates(), call) == CLAUDE_AGENTS
+
+
+class TestMalformedObjectValuesAreDropped:
+    def test_thinking_and_output_format_that_are_not_objects_are_dropped(self) -> None:
+        from launchdarkly_ai_claude_agents.handler import _options_parameters
+
+        params = _options_parameters(
+            {
+                "model": {
+                    "parameters": {
+                        "thinking": "adaptive",
+                        "output_format": "json",
+                        "max_turns": 3,
+                    }
+                }
+            }
+        )
+        assert params == {"max_turns": 3}
+
+
 async def test_a_builtin_tool_result_is_not_marked_failed(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None: