ha-mcp-dev 8.3.0.dev2413__tar.gz → 8.3.0.dev2415__tar.gz

{ha_mcp_dev-8.3.0.dev2413/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2415}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.3.0.dev2413
+Version: 8.3.0.dev2415
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.3.0.dev2413 → ha_mcp_dev-8.3.0.dev2415}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2413"
+version = "8.3.0.dev2415"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.3.0.dev2413 → ha_mcp_dev-8.3.0.dev2415}/src/ha_mcp/dashboard_screenshot/capture.py

@@ -855,15 +855,12 @@ async def capture_dashboard_images(
     preset's native orientation. ``full_page`` is a compatibility alias for
     requesting the engine's native ``WIDTHxauto`` viewport.
 
-    The batch used to be bracketed by a :class:`ThemeGuard` that restored the
-    engine user's saved frontend theme when a cold render changed it (issue
-    #1909). That bracket is currently disabled (#1991): upstream Puppet no
-    longer dispatches ``settheme`` on cold renders, so there is nothing to undo.
-    The guard construction and the ``client`` / ``capture_warnings`` plumbing
-    are retained so the bracket can be re-enabled by uncommenting the
-    snapshot/restore calls if a future engine regression reintroduces the write;
-    while disabled ``capture_warnings`` simply stays empty and never affects the
-    captures themselves.
+    Each batch is bracketed by a :class:`ThemeGuard`, which reads the engine
+    user's saved frontend theme before and after rendering. It never writes:
+    when the render changed the theme it reports the previous value through
+    ``capture_warnings`` so the agent can restore it with the write-annotated
+    ``ha_manage_theme``, keeping this path honestly read-only (#1909, #1991).
+    Guard failures are non-fatal.
     """
     path = _validate_dashboard_path(dashboard_path)
     options = validate_capture_parameters(
@@ -888,16 +885,14 @@ async def capture_dashboard_images(
     mime_type = _MIME_TYPES[options.image_format]
     captures: list[DashboardImageCapture] = []
 
-    # ThemeGuard bracket — currently DISABLED (#1991). Stock Puppet used to
-    # dispatch a theme write into the authenticated frontend on cold renders,
-    # which Home Assistant persisted to the engine user's real profile (#1909);
-    # ha-mcp snapshotted before and restored after to undo it. Upstream Puppet
-    # has since fixed the cold-render settheme dispatch, so the bracket is no
-    # longer needed. The guard is still constructed (and the snapshot/restore
-    # calls kept below, commented out) so it can be re-enabled by uncommenting
-    # if a future engine regression reintroduces the write.
+    # ThemeGuard bracket. Puppet's settheme dispatch persists onto the engine
+    # token user's profile and syncs to that user's live sessions (#1909).
+    # Both reads here; the guard reports the change rather than undoing it, so
+    # this tool issues no writes and stays read-only (#1991). Armed for every
+    # capture, not just themed ones: the upstream fix that would spare the
+    # no-parameter case is unreleased as of Puppet 2.6.0.
     guard = ThemeGuard.for_capture(engine_target.addon_credential, client)
-    # await guard.take_snapshot()
+    await guard.take_snapshot()
     batch_error: ToolError | None = None
     try:
         async with httpx.AsyncClient(
@@ -977,7 +972,7 @@ async def capture_dashboard_images(
         # and its outcome can be attached to the error payload below.
         batch_error = exc
     finally:
-        # await guard.restore()  # ThemeGuard bracket disabled (#1991) — see above.
+        await guard.detect_change()
         if capture_warnings is not None:
             capture_warnings.extend(guard.warnings)
 

ha_mcp_dev-8.3.0.dev2415/src/ha_mcp/dashboard_screenshot/theme_guard.py

@@ -0,0 +1,501 @@
+"""Detect when the screenshot engine changes the engine user's saved theme.
+
+Puppet dispatches Home Assistant's ``settheme`` event on cold-browser
+renders. Its ``dark`` query flag is presence-based, so "not requested"
+reaches the frontend as an explicit "light". Home Assistant persists that
+selection server-side per user (``frontend/set_user_data``, key ``"theme"``)
+and syncs it to every session of the user whose long-lived token the engine
+runs with, so a screenshot flips that user's real web and mobile UI (#1909).
+
+Upstream stopped the dispatch for renders requesting nothing
+(balloob/home-assistant-addons#89), but by its own title only for that case,
+and it is unreleased as of Puppet 2.6.0 -- so on current releases every
+render writes.
+
+**This guard never writes.** It reads the saved theme before the batch and
+again afterwards, and when the render changed it, reports the previous value
+so the agent can restore it with ``ha_manage_theme`` -- a tool correctly
+annotated as a write. That keeps the screenshot and dashboard-get tools
+honestly ``readOnlyHint: True`` (#1991, PR #2014) while still surfacing the
+damage. Because nothing is written, concurrent batches cannot corrupt each
+other and no serialization is needed.
+
+Pointing the engine at its own dedicated Home Assistant user avoids the
+problem outright: the write then lands on an account nobody looks at.
+
+Credential resolution mirrors engine discovery:
+
+- **HA OS / Supervised** -- the Puppet add-on's own ``access_token`` and
+  ``home_assistant_url`` options, taken from the Supervisor add-on info that
+  engine discovery already fetches. The token lives only in process memory
+  and is never logged or returned.
+- **Docker / standalone / OAuth / embedded** -- ha-mcp's direct Home
+  Assistant credentials, which match whenever the engine runs with a token
+  for the same user (the common single-user setup).
+- Anything else -- detection stays inactive and captures behave as before.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import json
+import logging
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .._version import is_running_in_addon
+
+if TYPE_CHECKING:
+    from ..client.websocket_client import HomeAssistantWebSocketClient
+
+logger = logging.getLogger(__name__)
+
+THEME_USER_DATA_KEY = "theme"
+
+# Sentinel: None is a legitimate stored theme value, so it cannot mean "unset".
+_UNSET: Any = object()
+
+# Where Puppet reaches Home Assistant when its ``home_assistant_url`` option
+# is unset — the Supervisor-internal alias, mirrored from the add-on default.
+DEFAULT_ENGINE_HA_URL = "http://homeassistant:8123"
+
+# Hosts the Supervisor-internal / loopback routes use. Cleartext to these
+# never leaves the host or its container network, which SECURITY.md names as
+# the trusted zone for standard mode. Cleartext to anything else would put the
+# engine account's bearer token on the wire for an on-path attacker, so it is
+# refused rather than sent.
+_LOCAL_HOSTS = frozenset(
+    {"homeassistant", "localhost", "supervisor", "127.0.0.1", "::1", "[::1]"}
+)
+
+
+def _read_only_mode() -> bool:
+    """Whether server Read Only Mode is on. Never raises.
+
+    Read through a helper so the report has one seam: Read Only Mode blocks
+    set_engine_theme at call time while captures keep running, so the remedy
+    must know about it.
+    """
+    try:
+        from ..config import get_global_settings
+
+        return bool(get_global_settings().read_only_mode)
+    except Exception:  # pragma: no cover - settings must never break a read
+        return False
+
+
+def _refusal_reason(url: str) -> str | None:
+    """Why ``url`` must not carry the engine token, or None when it may.
+
+    The two refusals are distinct and must say so. An unsupported scheme is
+    refused because the transport maps ONLY https to wss and everything else
+    to cleartext ws -- so wss://homeassistant and the ALLOWED
+    http://homeassistant produce the identical wire URL, and calling that
+    "cleartext to a remote host" is simply wrong. "Use https://" is also not
+    available advice for a Supervisor-internal endpoint.
+    """
+    from urllib.parse import urlparse
+
+    scheme = urlparse(url).scheme
+    if not _refuses_cleartext(url):
+        return None
+    if scheme not in ("http", "https"):
+        return (
+            f"refusing an engine URL with the unsupported scheme {scheme!r} "
+            f"({url}): the WebSocket transport maps only https to wss and "
+            "every other scheme to cleartext ws, so this would not be "
+            "encrypted. Use http:// for a local endpoint or https:// "
+            "otherwise."
+        )
+    return (
+        "refusing to send the screenshot engine's token in cleartext to a "
+        f"remote host ({url}); use https://"
+    )
+
+
+def _refuses_cleartext(url: str) -> bool:
+    """True when ``url`` must not carry the engine token."""
+    from urllib.parse import urlparse
+
+    parsed = urlparse(url)
+    # Allowlist, not a denylist. The transport maps ONLY https to wss and
+    # everything else to ws (websocket_client.py), so a wss:// engine URL --
+    # the spelling that looks secure and is natural to type for a WebSocket
+    # endpoint -- is silently downgraded to cleartext. Keying on "not http"
+    # waved exactly that through while refusing the honest http:// spelling
+    # of the same mistake. The Supervisor accepts any scheme
+    # (home_assistant_url is a bare str in Puppet's config.yaml) and
+    # addon_credential_from_options passes it through unvalidated, so this is
+    # the place the two rules have to agree.
+    if parsed.scheme == "https":
+        return False
+    if parsed.scheme != "http":
+        return True
+    host = (parsed.hostname or "").lower()
+    if host in _LOCAL_HOSTS or host.endswith(".local"):
+        return False
+    # Private ranges stay on the local network, the documented trusted zone --
+    # but ONLY as real IP literals. A DNS name that merely looks like one
+    # ("10.attacker.example") resolves wherever its owner points it, so string
+    # prefix matching would hand the token to an external host.
+    try:
+        address = ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return True
+    return not (address.is_private or address.is_loopback or address.is_link_local)
+
+
+_RESTORE_HINT = (
+    "the engine token's user can re-select their theme under Profile > "
+    "General in the Home Assistant UI"
+)
+
+# The engine returns the image as soon as the render settles, but the
+# frontend's settheme handler saves the user data asynchronously — with a
+# very low wait_ms the write can land after the HTTP response. Wait this
+# long before the post-capture read so it observes the engine's write
+# instead of racing it (a stale read would compare equal, skip the
+# restore, and let the late write survive).
+RESTORE_SETTLE_SECONDS = 1.0
+
+# The guard runs before the engine is contacted and must never eat the
+# caller's MCP timeout window; send_command otherwise waits 30s by default.
+COMMAND_TIMEOUT_SECONDS = 5.0
+
+# COMMAND_TIMEOUT_SECONDS only bounds a command once the socket is open and
+# authenticated. An unreachable endpoint or a bad token stalls in connect/auth
+# instead, before the engine is ever contacted, so the whole session is bounded
+# too.
+SESSION_TIMEOUT_SECONDS = 10.0
+
+# Cleanup runs shielded so a cancellation cannot abort the close mid-flight,
+# but shielded work still has to be bounded or a blocked disconnect() would
+# extend the session past SESSION_TIMEOUT_SECONDS. The shielded task keeps
+# running in the background when this bound expires; we just stop waiting.
+CLOSE_TIMEOUT_SECONDS = 2.0
+
+
+@dataclass(frozen=True, slots=True)
+class EngineCredential:
+    """Home Assistant URL + token that authenticate as the engine's user.
+
+    Deliberately carries only the two values the theme guard needs, so the
+    engine add-on's raw Supervisor options (a secret-bearing dict) never
+    cross module boundaries. The token must never be logged or surfaced in
+    responses.
+    """
+
+    url: str
+    token: str
+    verify_ssl: bool | None = None
+
+
+def addon_credential_from_options(
+    addon_options: Mapping[str, Any] | None,
+) -> EngineCredential | None:
+    """Extract the engine user's credential from Puppet add-on options."""
+    if not addon_options:
+        return None
+    token = str(addon_options.get("access_token") or "").strip()
+    if not token:
+        return None
+    url = str(addon_options.get("home_assistant_url") or "").strip()
+    return EngineCredential(url=url or DEFAULT_ENGINE_HA_URL, token=token)
+
+
+def _client_credential(client: Any) -> EngineCredential | None:
+    """Fall back to ha-mcp's own direct Home Assistant credential.
+
+    Only meaningful outside add-on mode: the Supervisor proxy authenticates
+    as the Supervisor system user, whose frontend profile is unrelated to
+    the engine token's user, so protecting it would be a silent no-op.
+    Embedded mode is deliberately NOT excluded — there the HA core container
+    carries ``SUPERVISOR_TOKEN`` but the server is a plain admin client with
+    a real user token, exactly what this fallback needs.
+    """
+    if is_running_in_addon():
+        return None
+    base_url = str(getattr(client, "base_url", "") or "").strip()
+    token = str(getattr(client, "token", "") or "").strip()
+    if not base_url.startswith(("http://", "https://")) or not token:
+        return None
+    # Carry the client's own TLS setting: a direct client built with
+    # verify_ssl=False (self-signed HA) must not fall back to the global
+    # default, or every session fails and no change is ever detected.
+    verify_ssl = getattr(client, "verify_ssl", None)
+    return EngineCredential(
+        url=base_url,
+        token=token,
+        verify_ssl=verify_ssl if isinstance(verify_ssl, bool) else None,
+    )
+
+
+@dataclass
+class ThemeGuard:
+    """Per-capture-batch snapshot/restore of the engine user's saved theme.
+
+    ``credential`` and ``warnings`` are the public contract; the snapshot
+    pair is internal lifecycle state driven only by :meth:`take_snapshot`
+    and :meth:`restore`.
+    """
+
+    credential: EngineCredential | None
+    warnings: list[str] = field(default_factory=list)
+    _snapshot: Any = None
+    _snapshot_taken: bool = False
+    changed_from: Any = None
+    # False when the credential is ha-mcp's own rather than the engine's own
+    # token: it MAY be the same Home Assistant user (the common single-user
+    # setup) but that cannot be established, so the report says so.
+    credential_is_engine: bool = True
+
+    @classmethod
+    def for_capture(
+        cls,
+        addon_credential: EngineCredential | None,
+        client: Any,
+    ) -> ThemeGuard:
+        """Resolve the engine user's credential for one capture batch."""
+        credential = addon_credential or _client_credential(client)
+        # Only the add-on's own token provably belongs to the engine. The
+        # client fallback MAY be the same user (the common single-user setup)
+        # but that cannot be established, so the report says so rather than
+        # implying the engine account was the one observed.
+        provably_engine = addon_credential is not None
+        if credential is None:
+            logger.debug(
+                "Dashboard theme guard inactive: no engine credential is "
+                "discoverable in this deployment"
+            )
+        return cls(credential=credential, credential_is_engine=provably_engine)
+
+    @asynccontextmanager
+    async def _session(self) -> AsyncIterator[HomeAssistantWebSocketClient]:
+        """Yield a short-lived authenticated WebSocket as the engine user."""
+        from ..client.websocket_client import HomeAssistantWebSocketClient
+
+        assert self.credential is not None
+        refusal = _refusal_reason(self.credential.url)
+        if refusal is not None:
+            raise ConnectionError(refusal)
+        ws = HomeAssistantWebSocketClient(
+            self.credential.url,
+            self.credential.token,
+            verify_ssl=self.credential.verify_ssl,
+        )
+        # The bound lives HERE, at the single construction site, rather than at
+        # each caller: _session is the only place a session carrying the engine
+        # credential is built, so a future entry point inherits the deadline
+        # along with the cleartext refusal instead of having to remember it.
+        # It spans connect, auth and the caller's body -- an unreachable
+        # endpoint stalls in connect, before the engine is ever contacted.
+        #
+        # connect() is INSIDE the try: the deadline cancels via CancelledError,
+        # a BaseException, so leaving it outside skipped disconnect() entirely
+        # and stranded the socket plus its background reader task.
+        try:
+            async with asyncio.timeout(SESSION_TIMEOUT_SECONDS):
+                if not await ws.connect():
+                    reason = ws.last_connect_error
+                    detail = f": {reason}" if isinstance(reason, str) else ""
+                    raise ConnectionError(
+                        f"could not authenticate to {self.credential.url}{detail}"
+                    )
+                yield ws
+        finally:
+            # Best-effort: a real failure to close must not mask the original
+            # exception (including the cancellation that triggered cleanup).
+            # Owned explicitly: a bare shield leaves the inner task pending
+            # after a timeout or cancellation, still holding the socket and
+            # able to raise late with nobody to receive it.
+            close = asyncio.ensure_future(ws.disconnect())
+            try:
+                # shield: we are frequently here *because* of a cancellation
+                # (SESSION_TIMEOUT_SECONDS). A bare await would be cancelled
+                # at once and the socket would never actually close.
+                await asyncio.wait_for(
+                    asyncio.shield(close), timeout=CLOSE_TIMEOUT_SECONDS
+                )
+            except (Exception, TimeoutError) as close_error:
+                logger.debug(
+                    "Ignoring error while closing the theme-guard session: %s",
+                    close_error,
+                )
+            finally:
+                if not close.done():
+                    close.cancel()
+                # Retrieve the outcome so a late failure never surfaces as an
+                # orphaned "exception was never retrieved" warning.
+                await asyncio.gather(close, return_exceptions=True)
+
+    @staticmethod
+    async def _fetch_theme(ws: HomeAssistantWebSocketClient) -> Any:
+        """Read the persisted ``theme`` frontend user-data value (may be None)."""
+        response = await ws.send_command(
+            "frontend/get_user_data",
+            key=THEME_USER_DATA_KEY,
+            _wait_timeout=COMMAND_TIMEOUT_SECONDS,
+        )
+        payload = response.get("result") if isinstance(response, dict) else None
+        return payload.get("value") if isinstance(payload, dict) else None
+
+    async def _read_theme(self) -> Any:
+        """One bounded read of the engine user's saved theme."""
+        async with self._session() as ws:
+            return await self._fetch_theme(ws)
+
+    async def take_snapshot(self) -> None:
+        """Record the saved theme before the engine renders. Never raises."""
+        if self.credential is None:
+            return
+        try:
+            self._snapshot = await self._read_theme()
+            self._snapshot_taken = True
+        except Exception as exc:
+            logger.warning(
+                "Could not read the screenshot engine user's saved theme "
+                "before rendering: %s",
+                exc,
+            )
+            self.warnings.append(
+                "Could not read the screenshot engine user's saved frontend "
+                f"theme before rendering; if the render changed it, {_RESTORE_HINT}."
+            )
+
+    async def detect_change(self) -> None:
+        """Report -- never repair -- a theme the render changed. Never raises.
+
+        Writing the value back here would make the screenshot tools issue
+        ``frontend/set_user_data``, which is exactly what disqualifies them
+        from ``readOnlyHint: True``. Instead the previous value is surfaced
+        as a warning naming the write-annotated tool that can restore it.
+        """
+        if not self._snapshot_taken or self.credential is None:
+            return
+        try:
+            # Puppet's settheme dispatch happens during page navigation, but
+            # the frontend's resulting user-data write is asynchronous -- let
+            # it land before reading (see RESTORE_SETTLE_SECONDS).
+            await asyncio.sleep(RESTORE_SETTLE_SECONDS)
+            current = await self._read_theme()
+        except Exception as exc:
+            logger.warning(
+                "Could not re-read the screenshot engine user's saved theme "
+                "after rendering: %s",
+                exc,
+            )
+            self.warnings.append(
+                "Could not check whether the screenshot render changed the "
+                "saved frontend theme of the engine token's user; "
+                f"{_RESTORE_HINT}."
+            )
+            return
+        if current == self._snapshot:
+            return
+        self.changed_from = self._snapshot
+        # A never-configured baseline is restored as {} rather than null:
+        # live frontend sessions ignore a null subscription push (they stay
+        # flipped until reload), while an empty settings object re-applies
+        # default/auto behavior immediately and means the same thing on the
+        # next frontend boot.
+        restore_value = self._snapshot if self._snapshot is not None else {}
+        logger.info(
+            "Screenshot render changed the engine user's saved theme "
+            "(was %s, now %s); reporting for agent-side restore",
+            self._snapshot,
+            current,
+        )
+        # Order matters: report the condition that actually governs. The
+        # identity block is unconditional -- with a fallback credential the
+        # restore is refused whether or not Read Only Mode is on -- while the
+        # read-only block lifts when the flag is turned off. Testing
+        # read-only first told a reader in BOTH states to turn the flag off,
+        # advice that unblocks nothing when the credential is unproven.
+        if not self.credential_is_engine:
+            remedy = (
+                "This was observed with ha-mcp's own Home Assistant "
+                "credential rather than the engine's own token, so ha-mcp "
+                "cannot confirm which account it belongs to and will not act "
+                "on it. Restore it from that account's own session: Profile "
+                "> General in the Home Assistant UI."
+            )
+        elif _read_only_mode():
+            remedy = (
+                "Server Read Only Mode is on, so ha-mcp will not restore "
+                "it: captures keep running there, but every theme write is "
+                "blocked at call time. Restore it from that account's own "
+                "session, Profile > General in the Home Assistant UI, or "
+                "turn Read Only Mode off first."
+            )
+        else:
+            remedy = (
+                "To restore it, call ha_manage_theme(action="
+                f"'set_engine_theme', value={json.dumps(restore_value)}, "
+                f"expected_current={json.dumps(current)}) -- that guard "
+                "re-checks the stored theme immediately before writing and "
+                "skips the write if it changed."
+            )
+        self.warnings.append(
+            "The screenshot engine changed the saved frontend theme of the "
+            "account its token belongs to, which also changes that account's "
+            "live web and mobile sessions. This tool is read-only and will "
+            f"not change it back. {remedy} To stop this happening at all, "
+            "give the screenshot engine its own Home Assistant user and "
+            "long-lived token, so its writes land on an account nobody "
+            "looks at."
+        )
+
+
+async def read_engine_theme(credential: EngineCredential) -> Any:
+    """Read the engine user's saved ``theme`` frontend user-data value."""
+    guard = ThemeGuard(credential=credential)
+    return await guard._read_theme()
+
+
+class ThemeChangedError(RuntimeError):
+    """The saved theme is not what the caller expected to overwrite."""
+
+    def __init__(self, actual: Any) -> None:
+        super().__init__("saved theme no longer matches expected_current")
+        self.actual = actual
+
+
+async def write_engine_theme(
+    credential: EngineCredential,
+    value: Any,
+    expected_current: Any = _UNSET,
+    *,
+    force: bool = False,
+) -> None:
+    """Write the engine user's saved ``theme`` frontend user-data value.
+
+    Only reached through ``ha_manage_theme``, which is annotated as a write.
+    Unless ``force`` is set the stored value is re-read
+    immediately before the write and the write is skipped on a mismatch. This
+    is best-effort, not atomic: ``frontend/set_user_data`` is an unconditional
+    ``async_set_item`` with no version or etag, so Home Assistant offers
+    nothing to compare against server-side and a change landing between the
+    re-read and the write is not caught. What it does catch is what actually
+    happens -- a delayed restore against a theme the user has since changed,
+    and a misresolved credential, whose account's theme will not match either.
+    """
+    guard = ThemeGuard(credential=credential)
+
+    async def _write() -> None:
+        async with guard._session() as ws:
+            if not force:
+                current = await ThemeGuard._fetch_theme(ws)
+                expected = None if expected_current is _UNSET else expected_current
+                if current != expected:
+                    raise ThemeChangedError(current)
+            await ws.send_command(
+                "frontend/set_user_data",
+                key=THEME_USER_DATA_KEY,
+                value=value,
+                _wait_timeout=COMMAND_TIMEOUT_SECONDS,
+            )
+
+    await _write()

{ha_mcp_dev-8.3.0.dev2413 → ha_mcp_dev-8.3.0.dev2415}/src/ha_mcp/read_only.py

@@ -153,6 +153,19 @@ def _updates_write(args: dict[str, Any]) -> str | None:
     return f"action={action!r}"
 
 
+def _theme_write(args: dict[str, Any]) -> str | None:
+    # Reads (allowed): listing installed themes and inspecting the screenshot
+    # engine account's saved per-user theme. The latter has no pure-read
+    # duplicate anywhere, and it is exactly what a caller needs in Read Only
+    # Mode: captures still make the engine persist a theme and still warn about
+    # it, so the value must stay inspectable even when restoring it is blocked.
+    # Both writes -- the backend default ('set') and the engine-account restore
+    # ('set_engine_theme') -- stay blocked. A missing action fails closed.
+    if args.get("action") in ("list", "get_engine_theme"):
+        return None
+    return f"action={args.get('action')!r}"
+
+
 def _radio_write(args: dict[str, Any]) -> str | None:
     action = args.get("action")
     # Reads (allowed): per-node diagnostics, the integration/network summary,
@@ -195,6 +208,11 @@ def _radio_write(args: dict[str, Any]) -> str | None:
 # against the real registered catalog at PR time, so the two sets
 # cannot drift apart silently.
 READ_ONLY_EXEMPT_TOOLS: dict[str, ReadOnlyExemption] = {
+    "ha_manage_theme": ReadOnlyExemption(
+        _theme_write,
+        "listing installed themes (action='list') and reading the screenshot "
+        "engine account's saved theme (action='get_engine_theme')",
+    ),
     "ha_manage_backup": ReadOnlyExemption(
         _backup_write,
         "listing, viewing, and diffing per-edit backups (scope='edits', "

{ha_mcp_dev-8.3.0.dev2413 → ha_mcp_dev-8.3.0.dev2415}/src/ha_mcp/tools/tools_dashboard_screenshot.py

@@ -196,16 +196,20 @@ class DashboardScreenshotTools:
             str | None,
             Field(
                 description="Installed Home Assistant frontend theme name, "
-                "applied to this render. The engine user's saved theme "
-                "preference is restored after the capture (best effort)."
+                "applied to this render. The engine persists this on the "
+                "engine account's profile; this tool reports the change in "
+                "warnings but does not undo it (see ha_manage_theme "
+                "action='set_engine_theme')."
             ),
         ] = None,
         dark_mode: Annotated[
             bool,
             Field(
                 description="Render the requested theme in dark mode, applied "
-                "to this render. The engine user's saved theme preference is "
-                "restored after the capture (best effort)."
+                "to this render. The engine persists this on the engine "
+                "account's profile; this tool reports the change in warnings "
+                "but does not undo it (see ha_manage_theme "
+                "action='set_engine_theme')."
             ),
         ] = False,
         language: Annotated[