fix(bulk): make selector mode actually reachable after a group-safety rejection

Live-tested (2026-08-23): the group-safety rejection correctly blocked the
dangerous batch, but the calling model then failed 6+ times trying to
recover via selector mode and gave up entirely -- a net worse outcome than
before, even though the dangerous action was correctly prevented. Root
cause was two separate, pre-existing gaps the model hit hard once the
operations-mode escape hatch was no longer available:

1. It put exclude_entity_ids as a top-level argument instead of nested
   inside selector, and the rejection message only said "use selector mode
   with exclude_entity_ids" with no worked example to correct that.
2. It passed area display names (from ha_search's friendly area_names, and
   a floor's display name) as area_ids, which must be exact HA registry
   IDs -- the "unknown area_ids" error never said so, or how to find the
   real ones.

Both error messages now show a concrete, correctly-shaped example and point
to ha_list_floors_areas (the existing tool for exact area_id/floor_id
lookup) instead of just naming the problem. Message-only changes, no
behavior change to the group-safety check itself -- it continues to block
the exact batch shape confirmed live to cascade into an excluded entity.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: swissmo

src/ha_mcp/tools/bulk_selector.py

@@ -445,12 +445,23 @@ def _select_area_ids(
     unknown_areas = sorted(set(area_ids) - set(areas))
     unknown_floors = sorted(set(floor_ids) - floors)
     if unknown_areas or unknown_floors:
+        # A caller that only has display names (e.g. from ha_search's
+        # friendly area_names, or a floor's display name) will otherwise
+        # retry with the same wrong value indefinitely -- area_ids/floor_ids
+        # are exact HA registry IDs (usually a lowercase, underscored slug
+        # like "living_room"), not the names shown in the UI, and nothing
+        # else in this error says where to find the real ones.
         details = []
         if unknown_areas:
             details.append(f"unknown area_ids: {', '.join(unknown_areas)}")
         if unknown_floors:
             details.append(f"unknown floor_ids: {', '.join(unknown_floors)}")
-        raise BulkSelectorValidationError("; ".join(details))
+        raise BulkSelectorValidationError(
+            "; ".join(details) + ". area_ids/floor_ids must be exact Home "
+            "Assistant registry IDs, not display names shown in the UI or "
+            "returned as ha_search's 'area_names' -- call ha_list_floors_areas "
+            "to look up the exact area_id/floor_id for each area or floor."
+        )
     selected = set(area_ids)
     selected.update(
         area_id for area_id, row in areas.items() if row.get("floor_id") in floor_ids

src/ha_mcp/tools/tools_service.py

@@ -281,8 +281,12 @@ async def _reject_operations_group_member_conflicts(
             "it from the group's own action. Target ONLY the group, or "
             "ONLY the specific member(s) you want affected, never both in "
             "the same call. To act on most of a group while excluding "
-            "specific members, use ha_bulk_control's selector mode with "
-            "exclude_entity_ids instead.",
+            "specific members, use selector mode instead: exclude_entity_ids "
+            "goes INSIDE selector, not as a top-level argument, e.g. "
+            '{"selector": {"domain": "light", "area_ids": ["<area_id>"], '
+            '"exclude_entity_ids": ["<entity_to_skip>"]}, "action": "off"}. '
+            "area_ids/floor_ids must be exact registry IDs (call "
+            "ha_list_floors_areas to look them up), not display names.",
             parameter="operations",
         )
     )

tests/src/unit/test_bulk_selector.py

@@ -1046,3 +1046,28 @@ async def test_invalid_structural_ids_fail_closed(
             timeout_seconds=None,
             validate_first=True,
         )
+
+
+@pytest.mark.asyncio
+async def test_unknown_area_id_message_points_to_the_lookup_tool() -> None:
+    """A caller with only a display name (e.g. ha_search's friendly
+    ``area_names``, or a floor's display name) retries with the same wrong
+    value forever unless told area_ids/floor_ids are a different, exact
+    registry ID and where to find it -- confirmed live: a caller that
+    passed display names ("Cave", "Couloir Sous-Sol") as ``area_ids`` hit
+    this exact error four times in a row with no path to recovery.
+    """
+    client = SelectorClient(states=[_state("light.one")], entities=[])
+
+    with pytest.raises(
+        BulkSelectorValidationError,
+        match=r"exact Home Assistant registry IDs.*ha_list_floors_areas",
+    ):
+        await resolve_bulk_selector(
+            client,
+            {"domain": "light", "area_ids": ["Couloir Sous-Sol"]},
+            action="off",
+            parameters=None,
+            timeout_seconds=None,
+            validate_first=True,
+        )

tests/src/unit/test_ha_bulk_control_selector.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
@@ -259,6 +260,13 @@ async def test_operations_mode_rejects_group_and_member_in_same_batch() -> None:
     Operations mode has no ``exclude_entity_ids`` to express that intent,
     so the omission alone never protected it; the only safe response is to
     reject the whole batch rather than silently dispatch it.
+
+    Also confirmed live: the rejection message alone was not enough. The
+    calling model retried four times with a broken selector call --
+    ``exclude_entity_ids`` at the top level (it belongs inside ``selector``)
+    and area *display names* where exact ``area_id`` registry values were
+    required -- and never recovered. The message must show a concrete,
+    correctly-shaped example, not just name selector mode.
     """
     device_tools = MagicMock()
     device_tools.bulk_device_control = AsyncMock(return_value={"success": True})
@@ -293,9 +301,17 @@ async def test_operations_mode_rejects_group_and_member_in_same_batch() -> None:
         # caller's (unenforceable, in this mode) attempt to exclude it.
     ]
 
-    with pytest.raises(ToolError, match="group/aggregate entity"):
+    with pytest.raises(ToolError) as exc_info:
         await tools.ha_bulk_control(operations, False)
 
+    message = json.loads(str(exc_info.value))["error"]["message"]
+    assert "group/aggregate entity" in message
+    # The worked example must show exclude_entity_ids nested INSIDE
+    # selector -- not as a sibling argument, which is the exact mistake
+    # observed live.
+    assert '"selector": {"domain": "light"' in message
+    assert '"exclude_entity_ids"' in message
+    assert "ha_list_floors_areas" in message
     device_tools.bulk_device_control.assert_not_awaited()