fix(flows): reject a malformed step_values directive

step_values is consumed as a directive, so a malformed one was invisible
to ignored-key reporting: an outer value that is not an object, or a list
entry that is not one, applied nothing and still returned success. Two of
the four malformed shapes warned; the other two were silent.

validate_step_values runs at the top of both walkers, before any step is
driven, and raises ToolError per the repo's tool-failure rule rather than
warning — a malformed directive is caller error, not a degraded result.
Valid shapes are unchanged: a dict entry, or a list of dicts for a step
the flow presents more than once.

Found by CodeRabbit review on #2256.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012d29UJTiH4Uy2Pm37SBPtr

Author: kingpanther13

src/ha_mcp/tools/config_entry_flow_form.py

@@ -841,6 +841,52 @@ def _consume_all_remaining_keys(
     return form_data
 
 
+def validate_step_values(config: dict[str, Any]) -> None:
+    """Reject a malformed ``step_values`` directive before the walk starts.
+
+    The reserved key is consumed as a directive, so a malformed one is invisible
+    to ignored-key reporting: the walk would complete, report success, and have
+    applied nothing the caller asked for. A caller error is a tool-level
+    failure, so it raises rather than warns (CodeRabbit review, issue #2254).
+
+    Accepted: a dict of ``step_id -> entry``, where an entry is a dict of field
+    values, or a LIST of such dicts consumed one per encounter of that step.
+    """
+    directive = config.get(_PER_STEP_VALUES_KEY)
+    if directive is None:
+        return
+
+    example = "{'<step_id>': {'<field>': <value>}}"
+    if not isinstance(directive, dict):
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"'{_PER_STEP_VALUES_KEY}' must be an object keyed by step id, "
+                f"got {type(directive).__name__}",
+                suggestions=[f"Pass {_PER_STEP_VALUES_KEY}={example}."],
+                context={_PER_STEP_VALUES_KEY: directive},
+            )
+        )
+
+    for step_id, entry in directive.items():
+        entries = entry if isinstance(entry, list) else [entry]
+        bad = [item for item in entries if not isinstance(item, dict)]
+        if bad:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"'{_PER_STEP_VALUES_KEY}[{step_id!r}]' must be an object "
+                    "of field values, or a list of them for a step the flow "
+                    f"presents more than once — got {type(bad[0]).__name__}",
+                    suggestions=[
+                        f"Pass {_PER_STEP_VALUES_KEY}={example}, or a list of "
+                        "those objects to supply one per encounter.",
+                    ],
+                    context={"step_id": step_id, "entry": entry},
+                )
+            )
+
+
 @contextmanager
 def _step_values_applied(
     remaining_config: dict[str, Any],

src/ha_mcp/tools/config_entry_flow_walker.py

@@ -24,6 +24,7 @@
     _handle_form_step,
     _ReuseState,
     _success_warnings,
+    validate_step_values,
 )
 from .config_entry_flow_menu import (
     _flow_step_budget,
@@ -854,6 +855,7 @@ async def _handle_flow_steps(
     """
     if submit_fn is None:
         submit_fn = client.submit_config_flow_step
+    validate_step_values(config)
     remaining_config = dict(config)
     current_step = initial_step
     last_menu_choice: str | None = None
@@ -1102,6 +1104,7 @@ async def _handle_config_subentry_flow_steps(
     resubmits the step's own value for every declared field the caller named
     no key for, so a partial patch stops wiping the rest of the subentry.
     """
+    validate_step_values(config)
     remaining_config = dict(config)
     current_step = initial_step
     last_menu_choice: str | None = None

tests/src/unit/test_flow_options_preserve.py

@@ -30,6 +30,7 @@
     _handle_form_step,
     _ignored_keys_warnings,
     _ReuseState,
+    validate_step_values,
 )
 from ha_mcp.tools.config_entry_flow_walker import (
     ReconfigureStatus,
@@ -1229,6 +1230,59 @@ def test_a_schemaless_step_does_not_submit_the_reserved_key(self) -> None:
         assert payload == {"host": "10.0.0.5"}
 
 
+class TestStepValuesValidation:
+    """A malformed directive raises rather than silently applying nothing."""
+
+    @pytest.mark.parametrize(
+        "directive",
+        ["oops", 42, ["init"]],
+        ids=["string", "number", "list"],
+    )
+    def test_a_non_object_directive_is_rejected(self, directive: Any) -> None:
+        with pytest.raises(ToolError) as exc_info:
+            validate_step_values({"step_values": directive})
+        assert "must be an object keyed by step id" in str(exc_info.value)
+
+    @pytest.mark.parametrize(
+        "entry",
+        ["TX", 42, ["TX"], [{"a": 1}, "TX"]],
+        ids=["string", "number", "list-of-string", "list-with-bad-tail"],
+    )
+    def test_a_non_object_entry_is_rejected(self, entry: Any) -> None:
+        with pytest.raises(ToolError) as exc_info:
+            validate_step_values({"step_values": {"init": entry}})
+        assert "must be an object of field values" in str(exc_info.value)
+
+    @pytest.mark.parametrize(
+        "config",
+        [
+            {"province": "BY"},
+            {"step_values": {"init": {"province": "TX"}}},
+            {"step_values": {"init": [{"province": "TX"}, {"province": "NY"}]}},
+            {"step_values": {}},
+        ],
+        ids=["absent", "dict-entry", "list-entry", "empty-directive"],
+    )
+    def test_valid_shapes_pass(self, config: dict[str, Any]) -> None:
+        validate_step_values(config)
+
+    async def test_the_walker_rejects_before_driving_any_step(self) -> None:
+        """It must raise before a single step is submitted."""
+        submit_fn = AsyncMock()
+
+        with pytest.raises(ToolError):
+            await _handle_flow_steps(
+                client=None,
+                flow_id="flow-2254",
+                initial_step=_workday_options_step(),
+                config={"days_offset": 3, "step_values": {"init": "TX"}},
+                submit_fn=submit_fn,
+                keep_current_values=True,
+            )
+
+        submit_fn.assert_not_awaited()
+
+
 class TestEmptyFormsGuidance:
     """The empty-forms error must point at the right mistake."""