homeassistant-ai · kingpanther13 · May 24, 2026 · May 23, 2026 · May 23, 2026 · May 23, 2026
diff --git a/README.md b/README.md
@@ -312,6 +312,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[FastMCP](https://github.com/jlowin/fastmcp)**: Excellent MCP server framework
 - **[Model Context Protocol](https://modelcontextprotocol.io/)**: Standardized AI-application communication
 - **[Claude Code](https://github.com/anthropics/claude-code)**: AI-powered coding assistant
+- **[PolicyLayer](https://policylayer.com/)**: Argument-path predicate DSL shape (`args.domain in [...]` with `eq`/`in`/`regex`/`contains`/`exists`/...) inspired the per-tool approval rule schema (#966).
 
 ## 👥 Contributors
 
@@ -360,6 +361,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[@drseanwing](https://github.com/drseanwing)** — Progress emission via FastMCP `Context` in long-running tools (#1124); tool-discovery / categorized-search docs (#1123).
 - **[@fnordpig](https://github.com/fnordpig)** — Config subentry support (#1393) and Assist pipeline management tool (#1392).
 - **[@paul43210](https://github.com/paul43210)** — `array_patch` mode in `ha_manage_addon` for atomic GET-modify-POST (#1063).
+- **[@L1AD](https://github.com/L1AD)** — Filed #966 proposing tool security policies; pointed to PolicyLayer's MCP-security work as prior art that inspired the predicate DSL shape.
 
 ---
 

diff --git a/homeassistant-addon-dev/DOCS.md b/homeassistant-addon-dev/DOCS.md
@@ -15,6 +15,7 @@ The dev add-on uses the same configuration as the stable version. See the main a
 | `backup_hint` | Backup strength preference | `normal` |
 | `secret_path` | Custom secret path (optional) | auto-generated |
 | `enable_tool_search` | Replace full tool catalog with search-based discovery (~46K → ~5K tokens). ⚠️ Do NOT enable for Claude Sonnet/Opus — their built-in tool search conflicts with ha-mcp's. Disable one or the other. | `false` |
+| `enable_tool_security_policies` | Gate high-stakes tool calls (lock/alarm control, automation writes, etc.) behind user approval. Guarded calls block until the user clicks Approve in the Tool Security Policies tab of the web UI. Per-tool rules with optional argument conditions are configured in that same tab. | `false` |
 | `enable_yaml_config_editing` *(beta)* | Enables `ha_config_set_yaml` for editing `configuration.yaml` directly. Requires `ha_mcp_tools` custom component. | `false` |
 | `enable_filesystem_tools` *(beta)* | Enables file read/write tools (`ha_list_files`, `ha_read_file`, `ha_write_file`, `ha_delete_file`). Requires `ha_mcp_tools` custom component. | `false` |
 | `enable_custom_component_integration` *(beta)* | Enables `ha_install_mcp_tools` installer tool for the `ha_mcp_tools` custom component. | `false` |

diff --git a/homeassistant-addon-dev/config.yaml b/homeassistant-addon-dev/config.yaml
@@ -24,6 +24,7 @@ image: "ghcr.io/homeassistant-ai/ha-mcp-addon-dev-{arch}"
 options:
   backup_hint: "normal"
   enable_tool_search: false
+  enable_tool_security_policies: false
   enable_yaml_config_editing: false
   enable_code_mode: false
   enable_lite_docstrings: false
@@ -38,6 +39,7 @@ schema:
   backup_hint: list(strong|normal|weak|auto)
   secret_path: str?
   enable_tool_search: bool?
+  enable_tool_security_policies: bool?
   enable_yaml_config_editing: bool?
   enable_code_mode: bool?
   enable_lite_docstrings: bool?

diff --git a/homeassistant-addon-dev/translations/en.yaml b/homeassistant-addon-dev/translations/en.yaml
@@ -28,6 +28,15 @@ configuration:
       OpenAI-compatible models) or with smaller context windows. Tools
       are found via ha_search_tools and executed via categorized proxies
       (read/write/delete). Requires restart to take effect.
+  enable_tool_security_policies:
+    name: Enable Tool Security Policies (advanced)
+    description: >-
+      Gate high-stakes tool calls (lock/alarm control, automation writes,
+      etc.) behind user approval. When a guarded tool is called, the agent
+      tells the user to open the Tool Security Policies tab in the web UI
+      and click Approve before the call proceeds. Per-tool rules with
+      optional argument conditions are configured in the Tool Security
+      Policies tab. Off by default. Requires restart to take effect.
   enable_yaml_config_editing:
     name: Enable YAML config editing (beta)
     description: >-

diff --git a/homeassistant-addon/DOCS.md b/homeassistant-addon/DOCS.md
@@ -272,13 +272,33 @@ Replaces the full tool catalog (~88 tools, ~46K tokens) with search-based discov
 
 Requires add-on restart to take effect.
 
+### enable_tool_security_policies
+
+**Default:** `false`
+
+Gates high-stakes tool calls (lock/alarm control, automation writes, etc.) behind explicit user approval. When a guarded tool is called, the agent is told to ask the user to open the Tool Security Policies tab in the web UI, and the call is held until the user clicks **Approve** there. Per-tool rules — with optional argument conditions — are configured from the same Tool Security Policies tab.
+
+**When to enable:**
+- Shared installations where you want a human in the loop for destructive or security-relevant operations
+- Locks, alarms, and other entities where an LLM mistake has real-world consequences
+- Whenever you want a per-call user-approval prompt before high-stakes operations run (locks, automations, etc.)
+
+**When to leave disabled (default):**
+- Single-user setups where you're comfortable with the LLM acting autonomously
+- You haven't configured any policy rules yet (with no rules, the toggle has no effect — but the runtime cost is small either way)
+
+Off by default. Requires add-on restart to take effect.
+
 **Example Configuration:**
 
 ```yaml
-backup_hint: normal
-secret_path: ""  # Leave empty for auto-generation
+enable_tool_security_policies: true
 ```
 
+Per-tool rules (including argument conditions like `args.domain in ['lock', 'alarm_control_panel']`) are configured from the **Tool Security Policies** tab in the web UI, not from `config.yaml`.
+
+*Inspired by [PolicyLayer](https://policylayer.com/)'s policy DSL shape, originally proposed in [#966](https://github.com/homeassistant-ai/ha-mcp/issues/966) by [@L1AD](https://github.com/L1AD).*
+
 ---
 
 ## Security

diff --git a/homeassistant-addon/config.yaml b/homeassistant-addon/config.yaml
@@ -32,6 +32,7 @@ image: "ghcr.io/homeassistant-ai/ha-mcp-addon-{arch}"
 options:
   backup_hint: "normal"
   enable_tool_search: false
+  enable_tool_security_policies: false
   enable_auto_backup: true
   auto_backup_throttle_minutes: 0
   auto_backup_retain_per_entity: 100
@@ -40,6 +41,7 @@ schema:
   backup_hint: list(strong|normal|weak|auto)
   secret_path: str?
   enable_tool_search: bool?
+  enable_tool_security_policies: bool?
   enable_auto_backup: bool?
   auto_backup_throttle_minutes: int(0,1440)?
   auto_backup_retain_per_entity: int(1,10000)?

diff --git a/homeassistant-addon/start.py b/homeassistant-addon/start.py
@@ -219,6 +219,7 @@ def main() -> int:
     backup_hint = "normal"  # default
     custom_secret_path = ""  # default
     enable_tool_search = False  # default
+    enable_tool_security_policies = False  # default
     enable_yaml_config_editing = False  # default
     enable_filesystem_tools = False  # default
     enable_custom_component_integration = False  # default
@@ -245,6 +246,14 @@ def main() -> int:
             enable_tool_search = (
                 raw_tool_search if isinstance(raw_tool_search, bool) else False
             )
+            raw_tool_security_policies = config.get(
+                "enable_tool_security_policies", False
+            )
+            enable_tool_security_policies = (
+                raw_tool_security_policies
+                if isinstance(raw_tool_security_policies, bool)
+                else False
+            )
             raw_yaml_config = config.get("enable_yaml_config_editing", False)
             enable_yaml_config_editing = (
                 raw_yaml_config if isinstance(raw_yaml_config, bool) else False
@@ -322,6 +331,9 @@ def main() -> int:
     os.environ["HOMEASSISTANT_URL"] = "http://supervisor/core"
     os.environ["BACKUP_HINT"] = backup_hint
     os.environ["ENABLE_TOOL_SEARCH"] = str(enable_tool_search).lower()
+    os.environ["ENABLE_TOOL_SECURITY_POLICIES"] = str(
+        enable_tool_security_policies
+    ).lower()
     os.environ["ENABLE_YAML_CONFIG_EDITING"] = str(enable_yaml_config_editing).lower()
     os.environ["HAMCP_ENABLE_FILESYSTEM_TOOLS"] = str(enable_filesystem_tools).lower()
     os.environ["HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION"] = str(

diff --git a/homeassistant-addon/translations/en.yaml b/homeassistant-addon/translations/en.yaml
@@ -28,6 +28,15 @@ configuration:
       OpenAI-compatible models) or with smaller context windows. Tools
       are found via ha_search_tools and executed via categorized proxies
       (read/write/delete). Requires restart to take effect.
+  enable_tool_security_policies:
+    name: Enable Tool Security Policies (advanced)
+    description: >-
+      Gate high-stakes tool calls (lock/alarm control, automation writes,
+      etc.) behind user approval. When a guarded tool is called, the agent
+      tells the user to open the Tool Security Policies tab in the web UI
+      and click Approve before the call proceeds. Per-tool rules with
+      optional argument conditions are configured in the Tool Security
+      Policies tab. Off by default. Requires restart to take effect.
   enable_auto_backup:
     name: Enable auto-backup of edits
     description: >-

diff --git a/src/ha_mcp/config.py b/src/ha_mcp/config.py
@@ -100,6 +100,13 @@ class Settings(BaseSettings):
     # Dramatically reduces idle context token usage for LLMs.
     enable_tool_search: bool = Field(False, alias="ENABLE_TOOL_SEARCH")
 
+    # Tool security policies middleware — opt-in gate that routes high-stakes
+    # tool calls through a per-tool policy with out-of-band web-UI approval
+    # (issue #966). Disabled by default.
+    enable_tool_security_policies: bool = Field(
+        False, alias="ENABLE_TOOL_SECURITY_POLICIES"
+    )
+
     # Managed YAML config editing — allows ha_config_set_yaml to add,
     # replace, or remove top-level keys in configuration.yaml and package
     # files. Disabled by default; only for YAML-only features with no UI/API path.
@@ -330,6 +337,7 @@ def validate_settings() -> tuple[bool, str | None]:
         "HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION",
         bool,
     ),
+    ("enable_tool_security_policies", "ENABLE_TOOL_SECURITY_POLICIES", bool),
 )
 
 # Override-file location is the same data dir that holds tool_config.json

diff --git a/src/ha_mcp/errors.py b/src/ha_mcp/errors.py
@@ -89,6 +89,13 @@ class ErrorCode(StrEnum):
     SANDBOX_SYNTAX_UNSUPPORTED = "SANDBOX_SYNTAX_UNSUPPORTED"
     SANDBOX_RUNTIME_ERROR = "SANDBOX_RUNTIME_ERROR"
 
+    # Tool security policy gating (#966). The middleware gates a tool
+    # call awaiting user approval, the user denied it, or the policy
+    # file itself failed to load (treated as a fail-closed safety stop).
+    USER_APPROVAL_REQUIRED = "USER_APPROVAL_REQUIRED"
+    USER_DENIED = "USER_DENIED"
+    POLICY_LOAD_FAILED = "POLICY_LOAD_FAILED"
+
 
 # Default suggestions for common error codes
 DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
@@ -240,7 +247,9 @@ def create_error_response(
         }
     """
     # Use provided suggestions or fall back to defaults
-    error_suggestions = suggestions if suggestions else DEFAULT_SUGGESTIONS.get(code, [])
+    error_suggestions = (
+        suggestions if suggestions else DEFAULT_SUGGESTIONS.get(code, [])
+    )
 
     error_dict: dict[str, Any] = {
         "code": code.value,
@@ -331,14 +340,20 @@ def create_validation_error(
     context: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Create a validation error response."""
-    code = ErrorCode.VALIDATION_INVALID_JSON if invalid_json else ErrorCode.VALIDATION_FAILED
+    code = (
+        ErrorCode.VALIDATION_INVALID_JSON
+        if invalid_json
+        else ErrorCode.VALIDATION_FAILED
+    )
     # Build context, prioritizing explicit context but adding parameter if provided
     final_context: dict[str, Any] = {}
     if context:
         final_context.update(context)
     if parameter:
         final_context["parameter"] = parameter
-    return create_error_response(code, message, details, context=final_context if final_context else None)
+    return create_error_response(
+        code, message, details, context=final_context if final_context else None
+    )
 
 
 def create_config_error(

diff --git a/src/ha_mcp/policy/__init__.py b/src/ha_mcp/policy/__init__.py
@@ -0,0 +1 @@
+"""Tool security policies for high-stakes MCP tool calls."""
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		"""Tool security policies for high-stakes MCP tool calls."""