homeassistant-ai
diff --git a/‎homeassistant-addon/DOCS.md‎
Lines changed: 1 addition & 1 deletion b/‎homeassistant-addon/DOCS.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎site/src/data/tools.json‎
Lines changed: 27 additions & 6 deletions b/‎site/src/data/tools.json‎
Lines changed: 27 additions & 6 deletions
diff --git a/‎src/ha_mcp/client/rest_client.py‎
Lines changed: 16 additions & 3 deletions b/‎src/ha_mcp/client/rest_client.py‎
Lines changed: 16 additions & 3 deletions
diff --git a/‎src/ha_mcp/errors.py‎
Lines changed: 27 additions & 2 deletions b/‎src/ha_mcp/errors.py‎
Lines changed: 27 additions & 2 deletions
diff --git a/‎src/ha_mcp/policy/evaluator.py‎
Lines changed: 148 additions & 0 deletions b/‎src/ha_mcp/policy/evaluator.py‎
Lines changed: 148 additions & 0 deletions
@@ -631,7 +631,7 @@ The add-on provides 88+ MCP tools for controlling Home Assistant:
 - `ha_search` — Search for entities (lights, sensors, switches, climate, etc.) by name, domain, or area — AND inside automation/script/scene/helper/dashboard configurations — in one call.
 
 ### Service & Device Control
-- `ha_bulk_control` — Manage multiple entity actions in one request.
+- `ha_bulk_control` — Manage explicit operations or one deterministic structural bulk action.
 - `ha_call_event` — Execute a custom event on the Home Assistant event bus.
 - `ha_call_service` — Execute Home Assistant services to control entities and trigger automations.
 - `ha_get_operation_status` — Get the status of one or more device operations with real-time WebSocket verification.
 
@@ -2988,20 +2988,41 @@
   {
     "name": "ha_bulk_control",
     "title": "Bulk Control",
-    "description": "Manage multiple entity actions in one request.\n\nWhen NOT to use: use ``ha_call_service`` for one service call targeting a\ngroup or for service-specific payloads that do not fit device actions.\n\nUse this when one request should apply actions to multiple independent\nentities. Optional item parameters carry brightness, temperature, position,\nor other action data.\n\nCaveats: put every target in ``operations`` and call the tool once. Parallel\nexecution is the default, and invalid items are reported without aborting\nvalid operations in the same batch. A batch in which every item fails\nvalidation dispatches nothing and fails the call.",
+    "description": "Manage explicit operations or one deterministic structural bulk action.\n\nWhen NOT to use: use ``ha_call_service`` for service-specific payloads or\nbackend-native group targeting, and ``ha_search`` for fuzzy name discovery.\n\nUse selector mode with exact area or floor IDs when exclusions must be\napplied after recursively expanding generic aggregate membership.\n\nCaveats: selector mode resolves a frozen visible leaf set before dispatch;\nit is not transactional, so Home Assistant may still report per-leaf failures.\nSet ``dry_run`` to preview the resolved set without changing state.",
     "inputSchema": {
       "properties": {
         "operations": {
-          "type": "Annotated[list[SkipValidation[BulkControlOperation]], JSON_STRING_COERCION, Field(description=\"All entity operations to execute in this single tool call. Each item requires entity_id and action. Use action='off', not service='turn_off'; do not include domain or service. Example: [{'entity_id': 'light.hall', 'action': 'off'}, {'entity_id': 'light.cave', 'action': 'off'}]\")]"
+          "type": "Annotated[list[SkipValidation[BulkControlOperation]], JSON_STRING_COERCION, Field(description=\"Explicit entity operations. Use this or selector, never both. Each item requires exact entity_id and action. Use action='off', not service='turn_off'.\")]"
         },
         "parallel": {
           "type": "bool",
           "default": true
+        },
+        "selector": {
+          "type": "Annotated[SkipValidation[BulkControlSelector] | None, JSON_STRING_COERCION, Field(description='Optional exact structural scope using domain plus area_ids and/or floor_ids, with optional exclude_entity_ids.')]",
+          "default": null
+        },
+        "action": {
+          "type": "Annotated[str | None, Field(description='One device action applied to every resolved leaf.')]",
+          "default": null
+        },
+        "parameters": {
+          "type": "Annotated[dict[str, Any] | None, JSON_STRING_COERCION, Field(description='Optional action parameters for selector mode.')]",
+          "default": null
+        },
+        "timeout_seconds": {
+          "type": "Annotated[float | None, Field(ge=0, le=60, allow_inf_nan=False, strict=True)]",
+          "default": null
+        },
+        "validate_first": {
+          "type": "Annotated[bool, Field(strict=True)]",
+          "default": true
+        },
+        "dry_run": {
+          "type": "Annotated[bool, Field(strict=True)]",
+          "default": false
         }
-      },
-      "required": [
-        "operations"
-      ]
+      }
     },
     "annotations": {
       "openWorldHint": false,
 
@@ -409,13 +409,26 @@ async def get_config(self) -> dict[str, Any]:
         return await self._request("GET", "/config")
 
     async def get_states(self) -> list[dict[str, Any]]:
-        """Get all entity states."""
+        """Get all entity states.
+
+        Raises ``HomeAssistantConnectionError`` when the response isn't the
+        JSON array ``/states`` always returns on success -- including
+        ``_request``'s own empty-dict fallback for an unparseable body.
+        Silently returning ``[]`` here would let a genuine fetch failure
+        masquerade as "this instance has zero entities", which no real,
+        running Home Assistant instance produces; callers that need to
+        verify something against the live entity set (e.g. a bulk-control
+        safety check) would otherwise treat that failure as "verified,
+        nothing to worry about" instead of "could not verify".
+        """
         logger.debug("Fetching all entity states")
         result = await self._request("GET", "/states")
         if isinstance(result, list):
             return result
-        else:
-            return []
+        raise HomeAssistantConnectionError(
+            f"Home Assistant /states returned an unexpected response shape: "
+            f"{type(result).__name__}"
+        )
 
     async def get_entity_state(self, entity_id: str) -> dict[str, Any]:
         """
 
@@ -100,6 +100,16 @@ class ErrorCode(StrEnum):
     USER_DENIED = "USER_DENIED"
     POLICY_LOAD_FAILED = "POLICY_LOAD_FAILED"
 
+    # Distinct from POLICY_LOAD_FAILED above: the policy file itself loaded
+    # fine, but this call's own arguments were too deeply nested to
+    # evaluate against it safely (see normalize_stringified_containers'
+    # RecursionError handling in middleware.py). A different failure with a
+    # different, caller-shaped remedy ("reduce the nesting depth and
+    # retry") -- sharing POLICY_LOAD_FAILED would make the two
+    # indistinguishable to anything grouping on the code (a dashboard, an
+    # operator grepping logs after "my policy broke").
+    POLICY_ARGS_TOO_DEEPLY_NESTED = "POLICY_ARGS_TOO_DEEPLY_NESTED"
+
     # Read Only Mode (discussion #1569). A write operation was blocked
     # because the server-wide Read Only Mode toggle is on.
     READ_ONLY_MODE = "READ_ONLY_MODE"
@@ -210,6 +220,10 @@ class ErrorCode(StrEnum):
         "Check documentation for required fields",
         "Ensure all required parameters are provided",
     ],
+    ErrorCode.VALIDATION_FAILED: [
+        "Check the parameter values and format against the tool documentation",
+        "Review the message and details fields for the specific constraint that failed",
+    ],
     ErrorCode.VALIDATION_INVALID_JSON: [
         "Ensure the parameter is valid JSON",
         "Check for syntax errors in JSON",
@@ -310,10 +324,21 @@ def create_connection_error(
     details: str | None = None,
     timeout: bool = False,
     context: dict[str, Any] | None = None,
+    suggestions: list[str] | None = None,
 ) -> dict[str, Any]:
-    """Create a connection error response."""
+    """Create a connection error response.
+
+    ``suggestions`` overrides ``DEFAULT_SUGGESTIONS[CONNECTION_FAILED/TIMEOUT]``
+    (network/URL/connectivity checks) for a caller whose failure is
+    CONNECTION_FAILED-shaped (unavailable, not the caller's fault to fix by
+    editing input) but not actually a network problem — e.g. malformed local
+    registry data or an unloadable local config file, where "check your
+    HOMEASSISTANT_URL" is not an actionable next step.
+    """
     code = ErrorCode.CONNECTION_TIMEOUT if timeout else ErrorCode.CONNECTION_FAILED
-    return create_error_response(code, message, details, context=context)
+    return create_error_response(
+        code, message, details, suggestions=suggestions, context=context
+    )
 
 
 # Authentication-error suggestions for Home Assistant add-on installs. On the
 
@@ -6,6 +6,7 @@
 from enum import StrEnum
 from typing import Any
 
+from ..tools.util_helpers import loads_if_json_container_str
 from .model import Policy, Predicate, Rule
 
 logger = logging.getLogger(__name__)
@@ -16,6 +17,82 @@ class Verdict(StrEnum):
     REQUIRE_APPROVAL = "require_approval"
 
 
+def normalize_stringified_containers(value: Any) -> Any:
+    """Recursively parse JSON-encoded object/array strings into real containers.
+
+    Some MCP client stacks (Claude Desktop stdio among them — see
+    ``tools/util_helpers.py``'s ``JSON_STRING_COERCION``) pass model-emitted
+    stringified objects through unrepaired, e.g. sending
+    ``{"selector": "{\\"domain\\": \\"light\\"}"}`` instead of a nested
+    object. Pydantic's ``JSON_STRING_COERCION`` ``BeforeValidator`` repairs
+    this, but only when the tool's own parameter validation runs — INSIDE
+    ``call_next``, after policy evaluation. ``iter_path_values`` only
+    descends into ``dict``/``list``, so a still-stringified value makes a
+    predicate targeting a nested field (``args.selector.domain``,
+    ``args.operations.*.entity_id``) silently yield nothing: no rule
+    matches, and — for ``ha_bulk_control`` — ``args.get("selector")`` still
+    sees a truthy string, so the selector fail-safe's own dynamic-call
+    detection still fires, but nothing inside it can be inspected either.
+    Applying the same repair here, once, before evaluation and hashing,
+    closes that gap for both plain predicate rules and the fail-safe, and
+    makes ``compute_args_hash`` key on the same logical value regardless of
+    which wire shape the client sent.
+
+    Malformed JSON that merely looks like a container is left as the raw
+    string (not raised): policy evaluation is not the place to surface a
+    JSON syntax error — the tool's own validation does that, with a
+    properly attributed parameter name.
+
+    Deeply-nested INPUT (real nested dicts/lists in the caller's own
+    ``args`` -- NOT a stringified container decoding into deep nesting;
+    ``loads_if_json_container_str`` already absorbs ``json.loads``'s own
+    ``RecursionError``, so a still-stringified value can never reach this
+    function's own recursion at all) can exceed the interpreter's
+    recursion limit and raise ``RecursionError`` here. Unlike the
+    malformed-JSON case, this is deliberately NOT swallowed: silently
+    returning the unrepaired value would let this security gate evaluate
+    (and hash) unnormalized args and, for a rule scoped to a nested
+    selector-inspectable field, silently ALLOW a call that should have
+    required approval -- the identical "fail open on a degraded gate"
+    mistake ``PolicyMiddleware.on_call_tool`` already refuses to make for
+    a corrupt policy file. The caller (``on_call_tool``) is responsible
+    for catching this and failing the call closed with a structured,
+    logged error, matching that same precedent.
+    """
+    return _normalize_stringified_containers(value)
+
+
+def _normalize_stringified_containers(value: Any) -> Any:
+    """Unbounded recursive worker for ``normalize_stringified_containers``.
+
+    Split out so the public function's ``RecursionError`` guard wraps a
+    single top-level call instead of needing a try/except at every
+    recursive frame.
+    """
+    if isinstance(value, str):
+        try:
+            return loads_if_json_container_str(value)
+        except ValueError:
+            return value
+    if isinstance(value, dict):
+        return {key: _normalize_stringified_containers(v) for key, v in value.items()}
+    if isinstance(value, list):
+        return [_normalize_stringified_containers(v) for v in value]
+    return value
+
+
+def has_dynamic_selector_targets(name: str, args: dict[str, Any]) -> bool:
+    """Return whether identical arguments can resolve to different targets later.
+
+    Single source of truth for the ``ha_bulk_control`` selector-mode predicate:
+    both ``PolicyMiddleware`` (approval-sharing/remembering gates) and
+    ``evaluate()`` below (the operations fail-safe) must agree on exactly
+    which calls are "dynamic", or a future rename/extension of this check in
+    one place silently stops applying to the other.
+    """
+    return name == "ha_bulk_control" and args.get("selector") is not None
+
+
 def iter_path_values(args: dict[str, Any], path: str) -> Iterator[Any]:
     """Yield every value the dotted path resolves to.
 
@@ -142,7 +219,65 @@ def find_matching_rule(
     return None
 
 
+def _predicate_reaches_operations(path: str) -> bool:
+    """Whether ``path`` can walk into ``args.operations`` under ``iter_path_values``.
+
+    ``operations`` sits directly under ``args``, so only the first two
+    segments after stripping the implicit ``args`` prefix matter. A literal
+    ``operations`` first segment obviously reaches it. A leading ``*`` reaches
+    it too — a wildcard segment fans out over EVERY value at that level (see
+    ``iter_path_values``), landing on the `operations` list value exactly as
+    readily as any other top-level key — but ``operations`` is a *list*, so a
+    literal segment right after that wildcard (e.g. ``domain`` in
+    ``args.*.domain``) can only ever match a *dict* value at that level (like
+    ``selector``) — ``walk()`` requires ``isinstance(cur, dict)`` for a
+    literal head, so it silently yields nothing against a list and can never
+    reach an operation row. Only a SECOND wildcard (``args.*.*...``, as in
+    ``args.*.*.entity_id``) or no further segment at all (bare ``args.*``,
+    which yields the raw ``operations`` list value itself) can actually reach
+    into the list. Any other concrete first segment (e.g. ``selector``) can
+    only ever address selector-inspectable fields and is precisely excluded.
+    """
+    parts = path.split(".")
+    if parts and parts[0] == "args":
+        parts = parts[1:]
+    if not parts:
+        return False
+    if parts[0] == "operations":
+        return True
+    return parts[0] == "*" and (len(parts) == 1 or parts[1] == "*")
+
+
+def _rule_needs_resolved_operations(rule: Rule) -> bool:
+    """Whether ``rule`` inspects fields only known after selector resolution.
+
+    A selector-mode ``ha_bulk_control`` call carries ``args.selector``, not
+    ``args.operations`` — the leaf targets don't exist yet, they're resolved
+    inside the tool after this middleware runs. A rule predicate that can
+    reach ``args.operations`` (exact, prefixed, or via a leading wildcard —
+    see ``_predicate_reaches_operations``) can therefore never get a fair
+    match attempt against a selector call and needs the fail-safe below. A
+    rule whose predicates only ever address selector-inspectable fields
+    (e.g. ``args.selector.domain``) already got a fair, precise match
+    attempt in ``find_matching_rule`` and must not be broadened into an
+    unconditional gate.
+    """
+    return any(_predicate_reaches_operations(p.path) for p in rule.when)
+
+
 def evaluate(tool_name: str, args: dict[str, Any], policy: Policy) -> Verdict:
+    """Decide whether one tool call requires approval under ``policy``.
+
+    A normal rule match (``find_matching_rule``) decides most calls. Two
+    fail-safes broaden approval beyond an exact predicate match, each only
+    when the operator has SOME rule that could plausibly apply: an
+    unmatched ``ha_call_service`` ``ws_command`` call (no ``domain``/
+    ``service`` args for a domain/service-keyed rule to match), and an
+    ``ha_bulk_control`` selector call whose matching rule needs fields
+    (``args.operations.*``) that don't exist yet at gate time, resolved
+    only later inside the tool. See the fail-safe blocks below for the
+    full reasoning behind each.
+    """
     if find_matching_rule(tool_name, args, policy) is not None:
         return Verdict.REQUIRE_APPROVAL
     # ha_call_service exposes a raw WebSocket escape hatch (``ws_command``) that
@@ -163,4 +298,17 @@ def evaluate(tool_name: str, args: dict[str, Any], policy: Policy) -> Verdict:
         and any(rule.tool_name in ("ha_call_service", "*") for rule in policy.rules)
     ):
         return Verdict.REQUIRE_APPROVAL
+    # Structural selectors are resolved inside the tool, after this middleware.
+    # A pre-existing rule that inspects args.operations.* therefore cannot inspect
+    # the eventual leaf targets. Fail safe only for rules that actually depend on
+    # that unresolved data — a rule fully expressed over selector-inspectable
+    # fields (e.g. args.selector.domain) already had its precise shot at matching
+    # above, and broadening it here would defeat a deliberately conditional rule
+    # (a rule scoped to selector.domain == "lock" must not gate a "light" call).
+    if has_dynamic_selector_targets(tool_name, args) and any(
+        rule.tool_name in ("ha_bulk_control", "*")
+        and _rule_needs_resolved_operations(rule)
+        for rule in policy.rules
+    ):
+        return Verdict.REQUIRE_APPROVAL
     return Verdict.ALLOW