homeassistant-ai
diff --git a/‎src/ha_mcp/llm_exposure.py‎
Lines changed: 67 additions & 6 deletions b/‎src/ha_mcp/llm_exposure.py‎
Lines changed: 67 additions & 6 deletions
diff --git a/‎src/ha_mcp/policy/handlers.py‎
Lines changed: 24 additions & 18 deletions b/‎src/ha_mcp/policy/handlers.py‎
Lines changed: 24 additions & 18 deletions
diff --git a/‎src/ha_mcp/policy/middleware.py‎
Lines changed: 24 additions & 1 deletion b/‎src/ha_mcp/policy/middleware.py‎
Lines changed: 24 additions & 1 deletion
diff --git a/‎src/ha_mcp/policy/model.py‎
Lines changed: 11 additions & 0 deletions b/‎src/ha_mcp/policy/model.py‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎src/ha_mcp/policy/persistence.py‎
Lines changed: 83 additions & 1 deletion b/‎src/ha_mcp/policy/persistence.py‎
Lines changed: 83 additions & 1 deletion
diff --git a/‎src/ha_mcp/server.py‎
Lines changed: 27 additions & 1 deletion b/‎src/ha_mcp/server.py‎
Lines changed: 27 additions & 1 deletion
@@ -14,9 +14,10 @@
 
 The single source of truth travels **in-band**: :class:`LlmExposureMiddleware`
 stamps every ``tools/list`` entry with
-``_meta.ha_mcp = {"llm_api_exposed": bool, "pinned": bool}`` so the component
-(one more loopback MCP client) filters on data that can never drift from the
-server's settings, with zero extra round-trips. Stamping re-reads the
+``_meta.ha_mcp = {"llm_api_exposed": bool, "pinned": bool, "policy": {...}}``
+so the component (one more loopback MCP client) filters on data that can never
+drift from the server's settings, with zero extra round-trips. The ``policy``
+block reports the serving server's gating state (#1990 — see META_POLICY_KEY). Stamping re-reads the
 persisted settings behind a short coalescing cache (2s TTL), so settings-UI
 changes apply on the agent's next conversation turn without a restart.
 
@@ -31,7 +32,7 @@
 
 import logging
 import time
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from typing import TYPE_CHECKING, Any
 
 from fastmcp.server.middleware import Middleware
@@ -50,6 +51,15 @@
 META_EXPOSED_KEY = "llm_api_exposed"
 META_PINNED_KEY = "pinned"
 
+# Serving-server policy/identity block stamped alongside the per-tool keys
+# (#1990). A client (or a debugging agent) reading tools/list can see the
+# ACTUAL gating state of the server answering this connection — configured
+# flag, live middleware, and rule count — plus the deployment mode. Without
+# this, a client pointed at a different server than the one the user
+# configured rules on fails silently: calls execute ungated and nothing
+# anywhere says "this server has zero rules".
+META_POLICY_KEY = "policy"
+
 # Key in tool_config.json holding the user's per-tool overrides
 # ({tool_name: bool}). Sparse on purpose: only tools the user explicitly
 # flipped are stored, so tools added by future releases keep getting their
@@ -153,9 +163,17 @@ class LlmExposureMiddleware(Middleware):
     is hidden or altered for regular MCP clients.
     """
 
-    def __init__(self) -> None:
-        """Initialize the short-lived settings cache."""
+    def __init__(self, policy_live: Callable[[], bool] | None = None) -> None:
+        """Initialize the short-lived settings cache.
+
+        ``policy_live`` reports whether the gating middleware/queue are
+        actually wired on this server (they only wire at startup); the
+        stamp carries it so "configured but not enforcing until restart"
+        is visible on the wire.
+        """
         self._cache: tuple[float, dict[str, bool], set[str]] | None = None
+        self._policy_live = policy_live
+        self._policy_cache: tuple[float, dict[str, Any]] | None = None
 
     def _current_settings(self) -> tuple[dict[str, bool], set[str]]:
         """Return (overrides, pinned) with a short TTL over the file reads."""
@@ -192,6 +210,47 @@ def _current_settings(self) -> tuple[dict[str, bool], set[str]]:
         self._cache = (now, overrides, pinned)
         return overrides, pinned
 
+    def _policy_block(self) -> dict[str, Any]:
+        """Serving-server policy/identity block (TTL-cached like the overrides).
+
+        Best-effort: a failure to read settings or the policy file stamps
+        conservative values (enabled=False / rules=0) rather than breaking
+        tools/list — the block is diagnostic metadata, not enforcement.
+        """
+        now = time.monotonic()
+        if (
+            self._policy_cache is not None
+            and now - self._policy_cache[0] < _OVERRIDES_TTL_SECONDS
+        ):
+            return self._policy_cache[1]
+        from ._version import is_embedded, is_running_in_addon
+
+        block: dict[str, Any] = {
+            "enabled": False,
+            "live": bool(self._policy_live()) if self._policy_live else False,
+            "rules": 0,
+            "deployment": (
+                "embedded"
+                if is_embedded()
+                else ("addon" if is_running_in_addon() else "standalone")
+            ),
+        }
+        try:
+            from .config import get_global_settings
+
+            block["enabled"] = bool(get_global_settings().enable_tool_security_policies)
+        except Exception:
+            logger.debug("policy stamp: settings read failed", exc_info=True)
+        try:
+            from .policy.persistence import load_policy
+            from .utils.data_paths import get_data_dir
+
+            block["rules"] = len(load_policy(get_data_dir()).rules)
+        except Exception:
+            logger.debug("policy stamp: policy read failed", exc_info=True)
+        self._policy_cache = (now, block)
+        return block
+
     async def on_list_tools(
         self,
         context: MiddlewareContext[mt.ListToolsRequest],
@@ -200,6 +259,7 @@ async def on_list_tools(
         """Stamp ``_meta.ha_mcp`` on every tool in the list result."""
         tools = await call_next(context)
         overrides, pinned = self._current_settings()
+        policy_block = self._policy_block()
 
         stamped: list[Tool] = []
         for tool in tools:
@@ -209,6 +269,7 @@ async def on_list_tools(
                 tool.name, tool.tags or set(), overrides
             )
             namespace[META_PINNED_KEY] = tool.name in pinned
+            namespace[META_POLICY_KEY] = policy_block
             meta[META_NAMESPACE] = namespace
             stamped.append(tool.model_copy(update={"meta": meta}))
         return stamped
@@ -11,6 +11,7 @@
 from starlette.requests import Request
 from starlette.responses import JSONResponse
 
+from ..utils.config_write_lock import config_write_guard
 from .approval_queue import ApprovalQueue
 from .model import Policy
 from .persistence import load_policy, save_policy
@@ -86,24 +87,29 @@ async def _put_config(
     # Optimistic concurrency: reject if the on-disk version moved
     # between this caller's GET and PUT. Returns the current policy
     # so the client can rebase if it wants to retry.
-    current = load_policy(data_dir)
-    if new_policy.version != current.version:
-        return JSONResponse(
-            {
-                "error": "policy version mismatch — reload before saving",
-                "current_version": current.version,
-                "current_policy": current.model_dump(mode="json"),
-            },
-            status_code=409,
-        )
-    save_policy(data_dir, new_policy)
-    # Drop the remember-cache only when rules actually changed.
-    # Editing just wait_seconds / approval_ttl_minutes shouldn't
-    # invalidate in-flight remembered approvals; only a rule change
-    # could make a previously-approved call now want a different
-    # outcome.
-    if current.rules != new_policy.rules:
-        queue.clear_remember_cache()
+    # Serialize the version-check + save against the developer tool
+    # (set_policy / set_tool) AND against other processes (the stdio
+    # sidecar runs this same handler in its own process) so a concurrent
+    # writer can't slip between the read and the write and lose an update.
+    async with config_write_guard():
+        current = load_policy(data_dir)
+        if new_policy.version != current.version:
+            return JSONResponse(
+                {
+                    "error": "policy version mismatch — reload before saving",
+                    "current_version": current.version,
+                    "current_policy": current.model_dump(mode="json"),
+                },
+                status_code=409,
+            )
+        save_policy(data_dir, new_policy)
+        # Drop the remember-cache only when rules actually changed.
+        # Editing just wait_seconds / approval_ttl_minutes shouldn't
+        # invalidate in-flight remembered approvals; only a rule change
+        # could make a previously-approved call now want a different
+        # outcome.
+        if current.rules != new_policy.rules:
+            queue.clear_remember_cache()
     return JSONResponse({"saved": True, "version": new_policy.version + 1})
 
 
 
@@ -35,6 +35,29 @@
     }
 )
 
+# ha_dev_manage_server actions that MANAGE the approval queue itself.
+# Gating these deadlocks by construction: with a wildcard (or
+# ha_dev_manage_server) rule in place, an MCP-only "approve" call would
+# itself require approval — creating a second pending entry instead of
+# deciding the first, so nothing can ever be approved through the tool.
+# Only the queue-management actions are exempt; update_source / restart
+# remain gateable like any other high-stakes action.
+_APPROVAL_MANAGEMENT_TOOL = "ha_dev_manage_server"
+_APPROVAL_MANAGEMENT_ACTIONS = frozenset({"list_pending", "approve", "deny"})
+
+
+def _is_approval_management(name: str, args: dict[str, Any]) -> bool:
+    """True for dev-tool calls that manage the approval queue itself."""
+    return (
+        name == _APPROVAL_MANAGEMENT_TOOL
+        and args.get("action") in _APPROVAL_MANAGEMENT_ACTIONS
+    )
+
+
+def _passes_ungated(name: str, args: dict[str, Any]) -> bool:
+    """Calls that must bypass gating: proxy meta-tools + queue management."""
+    return name in PROXY_META_TOOLS or _is_approval_management(name, args)
+
 
 class PolicyMiddleware(Middleware):
     """Gate tool calls against a Policy, blocking with progress heartbeats."""
@@ -78,7 +101,7 @@ async def on_call_tool(
         name = context.message.name
         args = context.message.arguments or {}
 
-        if name in PROXY_META_TOOLS:
+        if _passes_ungated(name, args):
             return await call_next(context)
 
         if evaluate(name, args, policy) != Verdict.REQUIRE_APPROVAL:
 
@@ -16,6 +16,14 @@
     "eq", "neq", "in", "not_in", "regex", "contains", "exists", "gt", "lt"
 ]
 
+# Schema generation of the persisted policy file. Version 2 = ANY-match
+# condition semantics (PR #1993): each UI condition is its own rule; a rule's
+# predicates AND together (a condition with sub-parameters). Files WITHOUT the
+# marker were written under the pre-#1993 editor, which packed every condition
+# into one AND-ed rule — ``persistence.migrate_policy_any_semantics`` splits
+# those once at startup and stamps the file.
+POLICY_SCHEMA_VERSION = 2
+
 
 class Predicate(BaseModel):
     """Single condition on a tool call's arguments (e.g. args.domain in [...])."""
@@ -103,6 +111,9 @@ class Policy(BaseModel):
     approval_ttl_minutes: int = Field(default=5, ge=1, le=60)
     rules: list[Rule] = Field(default_factory=list)
     version: int = Field(default=0, ge=0)
+    # ANY-match schema marker (see POLICY_SCHEMA_VERSION). Detection of
+    # unmigrated files reads the RAW json (this default would mask it).
+    schema_version: int = Field(default=POLICY_SCHEMA_VERSION, ge=1)
 
     @model_validator(mode="after")
     def _wait_must_be_less_than_ttl(self) -> "Policy":
 
@@ -1,13 +1,16 @@
 """Atomic load/save for tool_policy.json (mirrors tool_config.json pattern in settings_ui/__init__.py)."""
 
 import json
+import logging
 import os
 import tempfile
 from pathlib import Path
 
 from pydantic import ValidationError
 
-from .model import Policy
+from .model import Policy, Rule
+
+logger = logging.getLogger(__name__)
 
 POLICY_FILENAME = "tool_policy.json"
 
@@ -26,6 +29,85 @@ def load_policy(data_dir: Path) -> Policy:
         raise ValueError(f"tool_policy.json failed schema validation: {e}") from e
 
 
+def migrate_policy_any_semantics(data_dir: Path) -> bool:
+    """One-time migration of a pre-ANY policy file (PR #1993). Returns True on write.
+
+    The pre-#1993 editor packed every UI condition into ONE rule with the
+    predicates AND-ed ("require approval when ALL conditions match"). The
+    editor now writes one rule per condition and the UI reads "ANY condition
+    matches" — so an untouched old file would silently enforce AND while the
+    UI claims ANY. This splits every multi-predicate rule of an UNSTAMPED
+    file into one single-predicate rule each (the explicit, documented
+    breaking change: old AND conditions become OR, the more-restrictive
+    direction) and stamps ``schema_version`` so the migration never re-runs —
+    post-upgrade multi-predicate rules (a condition with AND-ed
+    sub-parameters, hand-authored or via future UI) are left intact.
+
+    Detection reads the RAW json: the Policy model defaults
+    ``schema_version`` to current, which would mask an unstamped file.
+    Missing or corrupt files are left alone (load_policy surfaces corruption).
+
+    The whole read-split-save runs under ``config_file_lock()`` so a
+    concurrent writer in another process (the stdio settings sidecar) can't
+    interleave with the migration's read-modify-write. The blocking lock is
+    taken inline: this runs once during server construction, before anything
+    is served. The sync entry points construct pre-loop; OAuth/OIDC construct
+    on a just-started ``asyncio.run`` loop (``_run_oauth_server`` /
+    ``_run_oidc_server``) where the sync constructor cannot await — but no
+    other task is scheduled on that loop yet, so a held lock can only delay
+    startup, never stall a served client.
+    """
+    from ..utils.config_write_lock import config_file_lock
+
+    with config_file_lock(data_dir):
+        return _migrate_policy_any_semantics_locked(data_dir)
+
+
+def _migrate_policy_any_semantics_locked(data_dir: Path) -> bool:
+    path = data_dir / POLICY_FILENAME
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return False
+    except (OSError, json.JSONDecodeError):
+        logger.warning("policy migration: cannot read %s; leaving as-is", path)
+        return False
+    if not isinstance(raw, dict) or raw.get("schema_version") is not None:
+        return False
+    try:
+        policy = Policy.model_validate(raw)
+    except ValidationError:
+        logger.warning("policy migration: %s failed validation; leaving as-is", path)
+        return False
+    new_rules: list[Rule] = []
+    split = 0
+    for rule in policy.rules:
+        if len(rule.when) > 1:
+            split += 1
+            new_rules.extend(
+                Rule(
+                    tool_name=rule.tool_name,
+                    when=[predicate],
+                    remember_minutes=rule.remember_minutes,
+                )
+                for predicate in rule.when
+            )
+        else:
+            new_rules.append(rule)
+    save_policy(data_dir, policy.model_copy(update={"rules": new_rules}))
+    logger.info(
+        "Migrated %s to ANY-match condition semantics: split %d multi-condition "
+        "rule(s) into one rule per condition (%d -> %d rules) and stamped "
+        "schema_version. Conditions that previously ALL had to match now EACH "
+        "gate on their own.",
+        path,
+        split,
+        len(policy.rules),
+        len(new_rules),
+    )
+    return True
+
+
 def save_policy(data_dir: Path, policy: Policy) -> None:
     # Bump version on every save so optimistic-concurrency callers can
     # detect mid-flight edits (PUT /api/policy/config 409s when the
 
@@ -249,7 +249,14 @@ def _initialize_server(self) -> None:
         # what it offers to Home Assistant conversation agents on it.
         from .llm_exposure import LlmExposureMiddleware
 
-        self.mcp.add_middleware(LlmExposureMiddleware())
+        # policy_live: whether the gating middleware/queue actually wired at
+        # startup — stamped so a client can distinguish "configured" from
+        # "enforcing" on the very connection it is using (#1990).
+        self.mcp.add_middleware(
+            LlmExposureMiddleware(
+                policy_live=lambda: getattr(self, "approval_queue", None) is not None
+            )
+        )
 
         # Entity visibility enforce mode, INBOUND half (#2015) — always
         # installed, consults the live config per request (no-op unless
@@ -1022,6 +1029,25 @@ def _apply_tool_security_policies(self) -> None:
         UI take effect immediately without restart and without a stale
         in-memory cache.
         """
+        # One-time ANY-match schema migration (PR #1993) runs even when
+        # policies are disabled, so the file already matches the editor's
+        # ANY semantics whenever the user turns the feature on. Never
+        # blocks startup.
+        try:
+            from .policy.persistence import migrate_policy_any_semantics
+            from .utils.data_paths import get_data_dir as _get_data_dir
+
+            migrate_policy_any_semantics(_get_data_dir())
+        except Exception:
+            logger.error(
+                "tool_policy.json ANY-match migration failed; continuing. The "
+                "file may still carry pre-ANY semantics: multi-condition rules "
+                "will gate only when ALL conditions match, while the policy "
+                "editor presents them as ANY-match. Fix the file (or re-save "
+                "the policy in the settings UI) and restart.",
+                exc_info=True,
+            )
+
         if not self.settings.enable_tool_security_policies:
             return