fix: block registry-disable on automation/script entities (#794) (#796)

Prevents ha_set_entity(enabled=False) from being used on automation.*
and script.* entities. Registry-disabling removes entities from the HA
state machine entirely, hiding them from the UI and making them
unqueryable until re-enabled AND reloaded — a destructive side effect
that agents are unlikely to intend.

The error message directs agents to use the correct domain services
(automation.turn_off / script.turn_off) which disable without removing.

Also updates the enabled parameter description and docstring to warn
about the destructive nature of registry-level disable for all entities.

Closes #794

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kingpanther13

site/src/data/tools.json

@@ -920,7 +920,7 @@
   {
     "name": "ha_set_entity",
     "title": "Set Entity",
-    "description": "Update entity properties in the entity registry.\n\nAllows modifying entity metadata such as area assignment, display name,\nicon, enabled/disabled state, visibility, aliases, labels, and voice\nassistant exposure in a single call.\n\nBULK OPERATIONS:\nWhen entity_id is a list, only labels and expose_to parameters are supported.\nOther parameters (area_id, name, icon, enabled, hidden, aliases) require single entity.\n\nLABEL OPERATIONS:\n- label_operation=\"set\" (default): Replace all labels with the provided list. Use [] to clear.\n- label_operation=\"add\": Add labels to existing ones without removing any.\n- label_operation=\"remove\": Remove specified labels from the entity.\n\nUse ha_search_entities() or ha_get_device() to find entity IDs.\nUse ha_config_get_label() to find available label IDs.\n\nEXAMPLES:\nSingle entity:\n- Assign to area: ha_set_entity(\"sensor.temp\", area_id=\"living_room\")\n- Rename: ha_set_entity(\"sensor.temp\", name=\"Living Room Temperature\")\n- Set labels: ha_set_entity(\"light.lamp\", labels=[\"outdoor\", \"smart\"])\n- Add labels: ha_set_entity(\"light.lamp\", labels=[\"new_label\"], label_operation=\"add\")\n- Remove labels: ha_set_entity(\"light.lamp\", labels=[\"old_label\"], label_operation=\"remove\")\n- Clear labels: ha_set_entity(\"light.lamp\", labels=[])\n- Expose to Alexa: ha_set_entity(\"light.lamp\", expose_to={\"cloud.alexa\": True})\n\nBulk operations:\n- Set labels on multiple: ha_set_entity([\"light.a\", \"light.b\"], labels=[\"outdoor\"])\n- Add labels to multiple: ha_set_entity([\"light.a\", \"light.b\"], labels=[\"new\"], label_operation=\"add\")\n- Expose multiple to Alexa: ha_set_entity([\"light.a\", \"light.b\"], expose_to={\"cloud.alexa\": True})\n\nNOTE: To rename an entity_id (e.g., sensor.old -> sensor.new), use ha_rename_entity() instead.",
+    "description": "Update entity properties in the entity registry.\n\nAllows modifying entity metadata such as area assignment, display name,\nicon, enabled/disabled state, visibility, aliases, labels, and voice\nassistant exposure in a single call.\n\nBULK OPERATIONS:\nWhen entity_id is a list, only labels and expose_to parameters are supported.\nOther parameters (area_id, name, icon, enabled, hidden, aliases) require single entity.\n\nLABEL OPERATIONS:\n- label_operation=\"set\" (default): Replace all labels with the provided list. Use [] to clear.\n- label_operation=\"add\": Add labels to existing ones without removing any.\n- label_operation=\"remove\": Remove specified labels from the entity.\n\nUse ha_search_entities() or ha_get_device() to find entity IDs.\nUse ha_config_get_label() to find available label IDs.\n\nEXAMPLES:\nSingle entity:\n- Assign to area: ha_set_entity(\"sensor.temp\", area_id=\"living_room\")\n- Rename: ha_set_entity(\"sensor.temp\", name=\"Living Room Temperature\")\n- Set labels: ha_set_entity(\"light.lamp\", labels=[\"outdoor\", \"smart\"])\n- Add labels: ha_set_entity(\"light.lamp\", labels=[\"new_label\"], label_operation=\"add\")\n- Remove labels: ha_set_entity(\"light.lamp\", labels=[\"old_label\"], label_operation=\"remove\")\n- Clear labels: ha_set_entity(\"light.lamp\", labels=[])\n- Expose to Alexa: ha_set_entity(\"light.lamp\", expose_to={\"cloud.alexa\": True})\n\nBulk operations:\n- Set labels on multiple: ha_set_entity([\"light.a\", \"light.b\"], labels=[\"outdoor\"])\n- Add labels to multiple: ha_set_entity([\"light.a\", \"light.b\"], labels=[\"new\"], label_operation=\"add\")\n- Expose multiple to Alexa: ha_set_entity([\"light.a\", \"light.b\"], expose_to={\"cloud.alexa\": True})\n\nNOTE: To rename an entity_id (e.g., sensor.old -> sensor.new), use ha_rename_entity() instead.\n\nENABLED/DISABLED WARNING:\nSetting enabled=False performs a **registry-level disable** — the entity is completely\nremoved from the Home Assistant state machine and hidden from the UI. It will NOT appear\nin state queries, dashboards, or automations until re-enabled AND the integration is\nreloaded. This is NOT the same as \"turning off\" an entity.\n\nFor automations and scripts, enabled=False is blocked. Use these instead:\n- ha_call_service(\"automation\", \"turn_off\", entity_id=\"automation.xxx\")\n- ha_call_service(\"script\", \"turn_off\", entity_id=\"script.xxx\")",
     "inputSchema": {
       "properties": {
         "entity_id": {
@@ -939,7 +939,7 @@
           "default": null
         },
         "enabled": {
-          "type": "Annotated[bool | str | None, Field(description='True to enable the entity, False to disable it. Single entity only.', default=None)]",
+          "type": "Annotated[bool | str | None, Field(description='True to enable the entity, False to disable it. Single entity only. WARNING: Setting enabled=False is a registry-level disable — it completely removes the entity from the state machine and hides it from the UI. A reload or restart is required to restore it after re-enabling. NOT allowed for automation or script entities — use automation.turn_off / script.turn_off via ha_call_service() instead.', default=None)]",
           "default": null
         },
         "hidden": {

src/ha_mcp/tools/tools_entities.py

@@ -341,7 +341,14 @@ async def ha_set_entity(
         enabled: Annotated[
             bool | str | None,
             Field(
-                description="True to enable the entity, False to disable it. Single entity only.",
+                description=(
+                    "True to enable the entity, False to disable it. Single entity only. "
+                    "WARNING: Setting enabled=False is a registry-level disable — it completely "
+                    "removes the entity from the state machine and hides it from the UI. "
+                    "A reload or restart is required to restore it after re-enabling. "
+                    "NOT allowed for automation or script entities — use automation.turn_off / "
+                    "script.turn_off via ha_call_service() instead."
+                ),
                 default=None,
             ),
         ] = None,
@@ -431,6 +438,16 @@ async def ha_set_entity(
         - Expose multiple to Alexa: ha_set_entity(["light.a", "light.b"], expose_to={"cloud.alexa": True})
 
         NOTE: To rename an entity_id (e.g., sensor.old -> sensor.new), use ha_rename_entity() instead.
+
+        ENABLED/DISABLED WARNING:
+        Setting enabled=False performs a **registry-level disable** — the entity is completely
+        removed from the Home Assistant state machine and hidden from the UI. It will NOT appear
+        in state queries, dashboards, or automations until re-enabled AND the integration is
+        reloaded. This is NOT the same as "turning off" an entity.
+
+        For automations and scripts, enabled=False is blocked. Use these instead:
+        - ha_call_service("automation", "turn_off", entity_id="automation.xxx")
+        - ha_call_service("script", "turn_off", entity_id="script.xxx")
         """
         try:
             # Parse entity_id - determine if bulk operation
@@ -491,6 +508,42 @@ async def ha_set_entity(
                     )
                 )
 
+            # Block registry-disable on automation and script entities.
+            # Registry-disabling (enabled=False) removes the entity from the HA
+            # state machine entirely, making it invisible in the UI and
+            # unqueryable via state APIs until re-enabled AND the integration is
+            # reloaded.  For automations and scripts the correct way to
+            # "disable" them is via their domain services (automation.turn_off /
+            # script.turn_off) which simply prevent them from running while
+            # keeping them visible and manageable.
+            if enabled is not None:
+                try:
+                    _enabled_check = coerce_bool_param(enabled, "enabled")
+                except ValueError:
+                    _enabled_check = None  # will be caught by _update_single_entity
+
+                if _enabled_check is False:
+                    blocked = [
+                        eid for eid in entity_ids
+                        if eid.split(".")[0] in ("automation", "script")
+                    ]
+                    if blocked:
+                        _domain = blocked[0].split(".")[0]
+                        _service_hint = f"{_domain}.turn_off"
+                        raise_tool_error(create_error_response(
+                            ErrorCode.VALIDATION_INVALID_PARAMETER,
+                            f"Cannot registry-disable {_domain} entities with ha_set_entity(enabled=False). "
+                            f"This removes the entity from the state machine and hides it from the UI "
+                            f"until it is re-enabled AND the {_domain}s are reloaded. "
+                            f"Use ha_call_service('{_domain}', 'turn_off', entity_id='{blocked[0]}') instead "
+                            f"to disable it without removing it.",
+                            suggestions=[
+                                f"Use {_service_hint} to disable the {_domain} (keeps it visible and manageable)",
+                                f"Use {_domain}.turn_on to re-enable it later",
+                                "ha_set_entity(enabled=False) is for registry-level disable — it fully hides the entity",
+                            ],
+                        ))
+
             # Parse list parameters if provided as strings
             parsed_aliases = None
             if aliases is not None:

tests/src/unit/test_tools_entities.py

@@ -1091,3 +1091,141 @@ async def test_bulk_label_add_operation(self, mock_mcp, mock_client):
 
         assert result["success"] is True
         assert result["succeeded_count"] == 2
+
+
+class TestHaSetEntityRegistryDisableGuardrail:
+    """Test that registry-disable (enabled=False) is blocked for automations and scripts."""
+
+    @pytest.fixture
+    def mock_mcp(self):
+        """Create a mock MCP server."""
+        mcp = MagicMock()
+        self.registered_tools = {}
+
+        def tool_decorator(*args, **kwargs):
+            def wrapper(func):
+                self.registered_tools[func.__name__] = func
+                return func
+            return wrapper
+
+        mcp.tool = tool_decorator
+        return mcp
+
+    @pytest.fixture
+    def mock_client(self):
+        """Create a mock Home Assistant client."""
+        client = MagicMock()
+        client.send_websocket_message = AsyncMock()
+        return client
+
+    @pytest.fixture
+    def set_entity_tool(self, mock_mcp, mock_client):
+        """Register tools and return the ha_set_entity function."""
+        register_entity_tools(mock_mcp, mock_client)
+        return self.registered_tools["ha_set_entity"]
+
+    @pytest.mark.asyncio
+    async def test_disable_automation_blocked(self, set_entity_tool, mock_client):
+        """enabled=False on automation entity should raise ToolError."""
+        with pytest.raises(ToolError) as exc_info:
+            await set_entity_tool(entity_id="automation.test", enabled=False)
+
+        error_text = str(exc_info.value)
+        assert "automation" in error_text.lower()
+        assert "turn_off" in error_text
+        # Ensure no WebSocket call was made
+        mock_client.send_websocket_message.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_disable_script_blocked(self, set_entity_tool, mock_client):
+        """enabled=False on script entity should raise ToolError."""
+        with pytest.raises(ToolError) as exc_info:
+            await set_entity_tool(entity_id="script.my_script", enabled=False)
+
+        error_text = str(exc_info.value)
+        assert "script" in error_text.lower()
+        assert "turn_off" in error_text
+        mock_client.send_websocket_message.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_disable_automation_string_false_blocked(self, set_entity_tool, mock_client):
+        """enabled='false' (string) on automation entity should also be blocked."""
+        with pytest.raises(ToolError) as exc_info:
+            await set_entity_tool(entity_id="automation.morning", enabled="false")
+
+        error_text = str(exc_info.value)
+        assert "automation" in error_text.lower()
+        assert "turn_off" in error_text
+        mock_client.send_websocket_message.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_disable_automation_string_capital_false_blocked(self, set_entity_tool, mock_client):
+        """enabled='False' (capital F, common from Python agents) should also be blocked."""
+        with pytest.raises(ToolError) as exc_info:
+            await set_entity_tool(entity_id="automation.evening", enabled="False")
+
+        error_text = str(exc_info.value)
+        assert "automation" in error_text.lower()
+        assert "turn_off" in error_text
+        mock_client.send_websocket_message.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_disable_automation_single_element_list_blocked(self, set_entity_tool, mock_client):
+        """enabled=False on single-element list ['automation.test'] should also be blocked."""
+        with pytest.raises(ToolError) as exc_info:
+            await set_entity_tool(entity_id=["automation.test"], enabled=False)
+
+        error_text = str(exc_info.value)
+        assert "automation" in error_text.lower()
+        assert "turn_off" in error_text
+        mock_client.send_websocket_message.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_enable_automation_allowed(self, set_entity_tool, mock_client):
+        """enabled=True on automation entity should be allowed (re-enabling is fine)."""
+        mock_client.send_websocket_message = AsyncMock(
+            return_value={
+                "success": True,
+                "result": {
+                    "entity_entry": {
+                        "entity_id": "automation.test",
+                        "name": None,
+                        "original_name": "Test",
+                        "icon": None,
+                        "area_id": None,
+                        "disabled_by": None,
+                        "hidden_by": None,
+                        "aliases": [],
+                        "labels": [],
+                    }
+                },
+            }
+        )
+
+        result = await set_entity_tool(entity_id="automation.test", enabled=True)
+        assert result["success"] is True
+
+    @pytest.mark.asyncio
+    async def test_disable_other_domain_allowed(self, set_entity_tool, mock_client):
+        """enabled=False on non-automation/script entities should still work."""
+        mock_client.send_websocket_message = AsyncMock(
+            return_value={
+                "success": True,
+                "result": {
+                    "entity_entry": {
+                        "entity_id": "sensor.temperature",
+                        "name": None,
+                        "original_name": "Temperature",
+                        "icon": None,
+                        "area_id": None,
+                        "disabled_by": "user",
+                        "hidden_by": None,
+                        "aliases": [],
+                        "labels": [],
+                    }
+                },
+            }
+        )
+
+        result = await set_entity_tool(entity_id="sensor.temperature", enabled=False)
+        assert result["success"] is True