ha-mcp-dev 8.4.0.dev2510__tar.gz → 8.4.1.dev2516__tar.gz

{ha_mcp_dev-8.4.0.dev2510/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.1.dev2516}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.0.dev2510
+Version: 8.4.1.dev2516
 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.4.0.dev2510 → ha_mcp_dev-8.4.1.dev2516}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.0.dev2510"
+version = "8.4.1.dev2516"
 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.4.0.dev2510 → ha_mcp_dev-8.4.1.dev2516}/src/ha_mcp/settings_ui/locales/en.json

@@ -114,13 +114,13 @@
     "visibility.entities.help": "One entity_id per line. These stay hidden even without an entity-registry entry.",
     "visibility.entities.denied": "Denied entity IDs",
     "visibility.allowlist.title": "Restrict to an allowlist",
-    "visibility.allowlist.help": "Advanced: when any allowlist field is set the filter inverts – only entities matching an allowlist stay visible, everything else is hidden (including entities added later). Leave all three empty to disable.",
+    "visibility.allowlist.help": "Advanced: when any allowlist field is set, nonmatching entities are hidden (including entities added later). A match overrides category, Home Assistant hidden-state, and Assist filters; denied entity IDs and excluded areas or labels still win. Leave all three empty to disable.",
     "visibility.allowlist.areas": "Allowed areas",
     "visibility.allowlist.labels": "Allowed labels",
     "visibility.allowlist.entities_help": "Allowed entity IDs, one per line.",
     "visibility.allowlist.entities": "Allowed entity IDs",
     "visibility.assist.title": "Respect Assist exposure",
-    "visibility.assist.help": "Hide entities not exposed to Home Assistant's Assist (“conversation”) voice assistant, mirroring the Settings > Voice assistants > Expose list. Adds two websocket reads per search while enabled.",
+    "visibility.assist.help": "Hide entities not exposed to Home Assistant's Assist (“conversation”) voice assistant, mirroring the Settings > Voice assistants > Expose list. Not applied while an allowlist is active; otherwise adds two websocket reads per search.",
     "visibility.assist.only_exposed": "Only show entities exposed to Assist",
     "features.enable_tool_search.label": "Enable tool search",
     "features.enable_tool_search.help": "Replace the full tool catalog with search-based discovery. Reduces idle context by roughly 90%, to about 5K tokens. ⚠️ Do NOT enable this in clients with their own built-in tool search / deferred tools (claude.ai, Claude Desktop, Claude Code) — the two search layers conflict, and the client's built-in tool search is the better choice there; leave this off. Whether tools are deferred depends on your client and model combination: use this when your setup loads the full catalog up front — models without native deferred tools (e.g. Gemini, OpenAI-compatible local models, Claude Haiku), clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI), or smaller context windows. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily. Tools are found via ha_search_tools and executed via categorized proxies (read/write/delete). Requires restart to take effect.",

{ha_mcp_dev-8.4.0.dev2510 → ha_mcp_dev-8.4.1.dev2516}/src/ha_mcp/settings_ui/settings.html

@@ -518,7 +518,7 @@
 
   <section class="a11y-section">
     <h2 class="a11y-section-title" data-i18n="visibility.allowlist.title">Restrict to an allowlist</h2>
-    <p class="a11y-section-help" data-i18n="visibility.allowlist.help">Advanced: when any allowlist field is set the filter inverts – only entities matching an allowlist stay visible, everything else is hidden (including entities added later). Leave all three empty to disable.</p>
+    <p class="a11y-section-help" data-i18n="visibility.allowlist.help">Advanced: when any allowlist field is set, nonmatching entities are hidden (including entities added later). A match overrides category, Home Assistant hidden-state, and Assist filters; denied entity IDs and excluded areas or labels still win. Leave all three empty to disable.</p>
     <label class="visibility-field"><span data-i18n="visibility.allowlist.areas">Allowed areas</span> <input type="text" id="visibility-allow-areas" placeholder="living_room, kitchen"></label>
     <label class="visibility-field"><span data-i18n="visibility.allowlist.labels">Allowed labels</span> <input type="text" id="visibility-allow-labels" placeholder="voice, main_floor"></label>
     <p class="a11y-section-help" data-i18n="visibility.allowlist.entities_help">Allowed entity IDs, one per line.</p>
@@ -528,7 +528,7 @@
 
   <section class="a11y-section">
     <h2 class="a11y-section-title" data-i18n="visibility.assist.title">Respect Assist exposure</h2>
-    <p class="a11y-section-help" data-i18n="visibility.assist.help">Hide entities not exposed to Home Assistant's Assist (&ldquo;conversation&rdquo;) voice assistant, mirroring the Settings &gt; Voice assistants &gt; Expose list. Adds two websocket reads per search while enabled.</p>
+    <p class="a11y-section-help" data-i18n="visibility.assist.help">Hide entities not exposed to Home Assistant's Assist (&ldquo;conversation&rdquo;) voice assistant, mirroring the Settings &gt; Voice assistants &gt; Expose list. Not applied while an allowlist is active; otherwise adds two websocket reads per search.</p>
     <label class="a11y-option"><input type="checkbox" id="visibility-respect-assist"> <span data-i18n="visibility.assist.only_exposed">Only show entities exposed to Assist</span></label>
   </section>
 

{ha_mcp_dev-8.4.0.dev2510 → ha_mcp_dev-8.4.1.dev2516}/src/ha_mcp/tools/tools_search.py

@@ -27,6 +27,7 @@ from ..errors import create_validation_error
 from ..transforms.categorized_search import DEFAULT_PINNED_TOOLS
 from ..utils.entity_membership import normalize_member_entity_ids
 from ..utils.fuzzy_search import apply_hidden_penalty
+from ..visibility.model import VisibilityWire, wire_has_allowlist_dimensions
 from ..visibility.resolver import (
     device_registry_needed_for_visibility,
     load_hidden_set,
@@ -1321,6 +1322,11 @@ def _merge_component_visibility_warnings(
             response,
             [w for w in component_visibility_warnings if isinstance(w, str)],
         )
+    elif component_visibility_warnings is not None:
+        logger.warning(
+            "component visibility_warnings ignored: expected a list, got %s",
+            type(component_visibility_warnings).__name__,
+        )
 
 
 async def _scrub_component_config_buckets(
@@ -2396,13 +2402,15 @@ class SearchTools:
         # hidden entities through the fast path. The ``search_visibility``
         # capability closes that: a component that advertises it accepts the raw
         # hide config (``VisibilityConfig.to_wire``) as the ``visibility`` param
-        # and excludes hidden entities before its own counts/pagination, exactly
-        # as the legacy path does — so a visibility-active install can still take
-        # the fast path. Without the capability an active filter stays on the
-        # legacy path; with no active filter the plain ``search`` route runs with
-        # no ``visibility`` param (old components keep working). ``ha_get_overview``
-        # needs no analogous gate — it re-applies the filter server-side over the
-        # component's raw slices. Checked only when the component would otherwise
+        # and excludes hidden entities before its own counts/pagination. The
+        # ``search_visibility_allowlist_authorization`` capability adds the
+        # ``allowlist_authorization`` wire key, which opts the component into the
+        # revised allowlist precedence; without it an active allowlist falls back
+        # to legacy (see ``_resolve_component_search_visibility``). With no active
+        # filter, the plain ``search`` route runs without a ``visibility`` param,
+        # so old components
+        # keep working. ``ha_get_overview`` needs no analogous gate — it reapplies
+        # the filter over the component's raw slices. Checked only when it would
         # serve, so the common (no-component / filter-off) install pays nothing.
         if (
             req.query_text
@@ -2429,7 +2437,7 @@ class SearchTools:
 
     async def _resolve_component_search_visibility(
         self, caps: Any
-    ) -> tuple[bool, dict[str, Any] | None]:
+    ) -> tuple[bool, VisibilityWire | None]:
         """Decide the ha_search route under the entity-visibility gate.
 
         Returns ``(route_component, visibility_param)`` for a caller that has
@@ -2437,13 +2445,21 @@ class SearchTools:
 
         - filter inactive → ``(True, None)``: the plain component search, no
           ``visibility`` param (parity with a pre-``search_visibility`` component).
-        - filter active + ``search_visibility`` capability + config serialized →
-          ``(True, <wire dict>)``: the component applies the hide dimensions
-          in-process.
-        - filter active without the capability, or the config could not be loaded
-          → ``(False, None)``: the legacy path applies the filter server-side
-          before the counts/pagination (fail-closed to legacy on a bad config,
-          matching ``visibility_state_and_wire``'s fail-closed pairing).
+        - filter active + ``search_visibility`` + config serialized:
+          - component also advertises ``search_visibility_allowlist_authorization``
+            → ``(True, <wire dict + allowlist_authorization: True>)``. The key opts
+            the component into the revised rule (an allow match authorizes past
+            category, HA-hidden, and Assist filters). It is never sent to a
+            component lacking the capability: that component's strict schema would
+            reject it, and the key's absence is what keeps a newer component on the
+            legacy precedence the released server still applies in its own
+            outbound scan.
+          - no allowlist dimensions → ``(True, <wire dict>)``: the nine-key wire;
+            with no allow dimensions the two precedences agree.
+          - allowlist active without the capability → ``(False, None)``.
+        - config could not be loaded → ``(False, None)``: the legacy path applies
+          the filter server-side before the counts/pagination (fail-closed to
+          legacy, matching ``visibility_state_and_wire``'s fail-closed pairing).
 
         ``visibility_state_and_wire`` loads the config once for both the active
         gate and its wire form, instead of the active check and the wire fetch
@@ -2452,16 +2468,21 @@ class SearchTools:
         active, visibility = await visibility_state_and_wire()
         if not active:
             return True, None
-        if component_supports(caps, "search_visibility") and visibility is not None:
-            return True, visibility
-        return False, None
+        if not component_supports(caps, "search_visibility") or visibility is None:
+            return False, None
+        if component_supports(caps, "search_visibility_allowlist_authorization"):
+            authorized: VisibilityWire = {**visibility, "allowlist_authorization": True}
+            return True, authorized
+        if wire_has_allowlist_dimensions(visibility):
+            return False, None
+        return True, visibility
 
     async def _ha_search_via_component(
         self,
         req: _ResolvedSearch,
         ctx: Context | None,
         *,
-        visibility: dict[str, Any] | None = None,
+        visibility: VisibilityWire | None = None,
         caps: Any = None,
     ) -> dict[str, Any] | None:
         """Serve ha_search from the component; ``None`` ⇒ run the legacy path.
@@ -2540,7 +2561,7 @@ class SearchTools:
         req: _ResolvedSearch,
         ctx: Context | None,
         *,
-        visibility: dict[str, Any] | None,
+        visibility: VisibilityWire | None,
     ) -> dict[str, Any] | None:
         """Serve a ``dashboard``-including request from both legs (issue #2289).
 
@@ -2636,7 +2657,7 @@ class SearchTools:
     async def _send_component_search(
         self,
         req: _ResolvedSearch,
-        visibility: dict[str, Any] | None = None,
+        visibility: VisibilityWire | None = None,
         *,
         dashboard_split: bool = False,
     ) -> dict[str, Any]:

{ha_mcp_dev-8.4.0.dev2510 → ha_mcp_dev-8.4.1.dev2516}/src/ha_mcp/visibility/enforcement.py

@@ -17,9 +17,14 @@ escape hatch — "refuse on contact":
   (a template, an automation body, a service target list), or whose *output* would
   surface one, is refused with a generic ``ENTITY_VISIBILITY_ENFORCED`` error that
   never names the matched id.
-  The whole result is refused rather than token-redacted because adjacent values
-  may still be the hidden entity's data, and generic mutation could corrupt an
-  arbitrary tool schema or diagnostic payload.
+  Generic results are refused rather than token-redacted because adjacent values
+  may still be the hidden entity's data and mutation could corrupt an arbitrary
+  schema. The bounded exception is a JSON ``ha_get_state`` result for a visible
+  entity: fields, mapping keys, list items, or related records that name hidden
+  entities are omitted (a whole ``attributes`` mapping when any of its content
+  does, since attribute values derive from the related entity), a warning naming
+  the omitted paths is added, and the result is scanned again. Non-JSON,
+  un-warnable, or still-matching state output is refused.
 - **Unscannable surfaces are refused wholesale** while enforce is active — sandbox
   code execution and screenshot/pixel output can read arbitrary state that no text
   scan can attribute to an entity.
@@ -50,7 +55,8 @@ import re
 import time
 from collections.abc import Callable
 from contextvars import ContextVar
-from typing import TYPE_CHECKING, Any, NoReturn
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, NamedTuple, NoReturn
 
 from fastmcp.exceptions import ToolError
 from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
@@ -89,8 +95,10 @@ _DASHBOARD_TOOL = "ha_config_get_dashboard"
 _DASHBOARD_SET_TOOL = "ha_config_set_dashboard"
 _CUSTOM_TOOL = "ha_manage_custom_tool"
 
-# Tool deliberately outside the visibility barrier unless the operator opts in.
+# Diagnostic tool deliberately outside the visibility barrier unless opted in.
 _REPORT_ISSUE_TOOL = "ha_report_issue"
+# State reads have a shape-bounded scrub exception before the outbound scan.
+_STATE_TOOL = "ha_get_state"
 
 _SANDBOX_REASON = (
     "'{name}' executes sandbox code that can read arbitrary Home Assistant state, "
@@ -104,6 +112,30 @@ _FAIL_CLOSED_REASON = (
     "The entity visibility data could not be loaded, so enforce mode fails closed "
     "rather than risk leaking a restricted entity."
 )
+_STATE_CONTENT_WARNING_PREFIX = "Entity Visibility enforce mode omitted "
+_STATE_CONTENT_WARNING_MAX_PATHS = 10
+
+
+def _state_content_warning(paths: list[str]) -> str:
+    """The ha_get_state omission warning, naming the omitted JSON paths.
+
+    Paths never contain a hidden entity_id: a whole ``attributes`` mapping is
+    reported as one path, and a hidden mapping key is reported as
+    ``<parent>.<hidden key>``.
+    """
+    shown = ", ".join(paths[:_STATE_CONTENT_WARNING_MAX_PATHS])
+    extra = len(paths) - _STATE_CONTENT_WARNING_MAX_PATHS
+    if extra > 0:
+        shown += f" and {extra} more"
+    return (
+        f"{_STATE_CONTENT_WARNING_PREFIX}{shown} because it referenced entities "
+        "hidden by the entity visibility filter. If something you expected is "
+        "missing, review the Entity Visibility section of the ha-mcp settings UI "
+        "(the rules are described under 'Entity visibility enforce mode' in "
+        "SECURITY.md)."
+    )
+
+
 _CONFIG_LOAD_FAILED_REASON = (
     "The entity visibility config (entity_visibility.json) could not be loaded and "
     "no previously loaded config is available, so the server cannot determine "
@@ -179,9 +211,7 @@ def _iter_strings(value: Any) -> Any:
             yield from _iter_strings(item)
 
 
-def _scan_value(
-    value: Any, hidden: set[str], regex: re.Pattern[str] | None
-) -> tuple[str | None, bool]:
+def _scan_value(value: Any, matcher: _HiddenMatcher) -> tuple[str | None, bool]:
     """Return ``(first_exact_hidden_id, any_embedded_hidden_id)`` over nested strings.
 
     A string that equals a hidden id exactly drives concealment; a string that
@@ -191,10 +221,10 @@ def _scan_value(
     exact: str | None = None
     embedded = False
     for text in _iter_strings(value):
-        if text in hidden:
+        if matcher.exact(text):
             if exact is None:
                 exact = text
-        elif regex is not None and regex.search(text):
+        elif matcher.embeds(text):
             embedded = True
     return exact, embedded
 
@@ -212,6 +242,30 @@ def _build_hidden_regex(hidden: set[str]) -> re.Pattern[str] | None:
     return re.compile(rf"(?<![a-z0-9_])(?:{alternation})(?![a-z0-9_])", re.IGNORECASE)
 
 
+@dataclass(frozen=True)
+class _HiddenMatcher:
+    """The enforced hidden set together with the boundary regex compiled from it.
+
+    Built only through :meth:`from_hidden`, so ``regex`` is ``None`` exactly when
+    ``hidden`` is empty and every scan sees a consistent pair.
+    """
+
+    hidden: frozenset[str]
+    regex: re.Pattern[str] | None
+
+    @classmethod
+    def from_hidden(cls, hidden: set[str]) -> _HiddenMatcher:
+        return cls(frozenset(hidden), _build_hidden_regex(hidden))
+
+    def exact(self, text: str) -> bool:
+        """Whether ``text`` is a hidden entity_id."""
+        return text in self.hidden
+
+    def embeds(self, text: str) -> bool:
+        """Whether ``text`` is, or embeds, a hidden entity_id (exact included)."""
+        return self.regex is not None and self.regex.search(text) is not None
+
+
 def _serialize_result(result: ToolResult) -> str:
     """Flatten a tool result's text content and structured content for scanning."""
     parts: list[str] = []
@@ -228,6 +282,171 @@ def _serialize_result(result: ToolResult) -> str:
     return "\n".join(parts)
 
 
+# Sentinel returned for a hidden-naming string value or a mapping whose
+# ``entity_id`` is hidden; its enclosing mapping/sequence omits that value. At the
+# top level it reaches ``_scrub_state_representation``, which treats the
+# representation as un-warnable.
+_DROP_HIDDEN_REFERENCE = object()
+# A visible entity's ``attributes`` mapping carries values derived from related
+# entities (a person's coordinates come from its device trackers), so any hidden
+# reference inside it drops the whole mapping rather than the naming field.
+_ATTRIBUTES_KEY = "attributes"
+
+
+def _scrub_hidden_references(
+    value: Any, matcher: _HiddenMatcher, path: str
+) -> tuple[Any, list[str]]:
+    """Return a scrubbed JSON-shaped value and the JSON paths it omitted."""
+    if isinstance(value, str):
+        if matcher.embeds(value):
+            return _DROP_HIDDEN_REFERENCE, [path]
+        return value, []
+
+    if isinstance(value, dict):
+        return _scrub_hidden_mapping(value, matcher, path)
+
+    if isinstance(value, (list, tuple)):
+        return _scrub_hidden_sequence(value, matcher, path)
+
+    return value, []
+
+
+def _scrub_hidden_mapping(
+    value: dict[Any, Any], matcher: _HiddenMatcher, path: str
+) -> tuple[Any, list[str]]:
+    entity_id = value.get("entity_id")
+    if isinstance(entity_id, str) and matcher.embeds(entity_id):
+        return _DROP_HIDDEN_REFERENCE, [path]
+
+    scrubbed_dict: dict[Any, Any] = {}
+    omitted: list[str] = []
+    for key, item in value.items():
+        child_path = f"{path}.{key}" if path else str(key)
+        if isinstance(key, str) and matcher.embeds(key):
+            omitted.append(f"{path}.<hidden key>" if path else "<hidden key>")
+            continue
+        scrubbed_item, item_omitted = _scrub_hidden_references(
+            item, matcher, child_path
+        )
+        if key == _ATTRIBUTES_KEY and isinstance(item, dict) and item_omitted:
+            omitted.append(child_path)
+            continue
+        omitted.extend(item_omitted)
+        if scrubbed_item is _DROP_HIDDEN_REFERENCE:
+            continue
+        scrubbed_dict[key] = scrubbed_item
+    return scrubbed_dict, omitted
+
+
+def _scrub_hidden_sequence(
+    value: list[Any] | tuple[Any, ...], matcher: _HiddenMatcher, path: str
+) -> tuple[list[Any], list[str]]:
+    scrubbed_list: list[Any] = []
+    omitted: list[str] = []
+    for index, item in enumerate(value):
+        scrubbed_item, item_omitted = _scrub_hidden_references(
+            item, matcher, f"{path}[{index}]"
+        )
+        omitted.extend(item_omitted)
+        if scrubbed_item is _DROP_HIDDEN_REFERENCE:
+            continue
+        scrubbed_list.append(scrubbed_item)
+    return scrubbed_list, omitted
+
+
+def _add_state_content_warning(value: Any, warning: str) -> bool:
+    """Attach the omission warning, or return False when the shape cannot carry it."""
+    if not isinstance(value, dict):
+        return False
+    warnings = value.get("warnings")
+    if warnings is None:
+        value["warnings"] = [warning]
+        return True
+    if not isinstance(warnings, list):
+        return False
+    if warning not in warnings:
+        warnings.append(warning)
+    return True
+
+
+class _ScrubAttempt(NamedTuple):
+    """One JSON representation's scrub outcome.
+
+    ``value`` is the scrubbed copy (warning attached) only when ``warnable`` is
+    true; otherwise it is the untouched original, retained so the outbound scan
+    still sees the hidden reference. ``warnable`` is vacuously true when
+    ``omissions`` is zero.
+    """
+
+    value: Any
+    omissions: int
+    warnable: bool
+
+
+class _ScrubTally(NamedTuple):
+    """Committed omissions plus representations that could not carry a warning."""
+
+    omissions: int
+    mutated_representations: int
+    unwarnable_representations: int
+
+
+def _scrub_state_representation(value: Any, matcher: _HiddenMatcher) -> _ScrubAttempt:
+    """Scrub one JSON value, retaining its original unless a warning can attach."""
+    scrubbed, omitted = _scrub_hidden_references(value, matcher, "")
+    if not omitted:
+        return _ScrubAttempt(value, 0, True)
+    if scrubbed is _DROP_HIDDEN_REFERENCE or not _add_state_content_warning(
+        scrubbed, _state_content_warning(omitted)
+    ):
+        return _ScrubAttempt(value, len(omitted), False)
+    return _ScrubAttempt(scrubbed, len(omitted), True)
+
+
+def _scrub_state_result(result: ToolResult, matcher: _HiddenMatcher) -> _ScrubTally:
+    """Scrub ha_get_state JSON representations while preserving a warning.
+
+    A representation is replaced only when its top-level shape can carry the
+    generic omission warning. Otherwise the original is retained and counted in
+    ``unwarnable_representations`` so the caller refuses the result rather than
+    silently returning filtered content.
+    """
+    omissions_total = 0
+    mutated_representations = 0
+    unwarnable_representations = 0
+    structured = getattr(result, "structured_content", None)
+    if structured is not None:
+        attempt = _scrub_state_representation(structured, matcher)
+        if attempt.omissions and attempt.warnable:
+            result.structured_content = attempt.value
+            omissions_total += attempt.omissions
+            mutated_representations += 1
+        elif attempt.omissions:
+            unwarnable_representations += 1
+
+    for block in getattr(result, "content", None) or []:
+        text_value = getattr(block, "text", None)
+        if not isinstance(text_value, str):
+            continue
+        try:
+            parsed = json.loads(text_value)
+        except json.JSONDecodeError:
+            continue
+        attempt = _scrub_state_representation(parsed, matcher)
+        if attempt.omissions and attempt.warnable:
+            block.text = json.dumps(attempt.value)
+            omissions_total += attempt.omissions
+            mutated_representations += 1
+        elif attempt.omissions:
+            unwarnable_representations += 1
+
+    return _ScrubTally(
+        omissions_total,
+        mutated_representations,
+        unwarnable_representations,
+    )
+
+
 def _tool_error_text(exc: ToolError) -> str:
     """The scannable text of a tool-raised error (its JSON payload args)."""
     return "\n".join(str(arg) for arg in (getattr(exc, "args", None) or ()))
@@ -416,9 +635,7 @@ class _VisibilityEnforcementBase(Middleware):
             return None
         return config
 
-    async def _hidden_and_regex(
-        self, config: VisibilityConfig
-    ) -> tuple[set[str], re.Pattern[str] | None]:
+    async def _hidden_matcher(self, config: VisibilityConfig) -> _HiddenMatcher:
         """Resolve the hidden set + regex through the module-shared cache."""
         return await _hidden_cache.get(config, self._get_client())
 
@@ -462,11 +679,11 @@ class VisibilityInboundEnforcement(_VisibilityEnforcementBase):
             _raise_enforced(effective_name, reason)
 
         try:
-            hidden, regex = await self._hidden_and_regex(config)
+            matcher = await self._hidden_matcher(config)
         except VisibilityDataUnavailable:
             _raise_enforced(effective_name, _FAIL_CLOSED_REASON)
 
-        self._scan_inbound(effective_name, name, args, hidden, regex)
+        self._scan_inbound(effective_name, name, args, matcher)
         return await call_next(context)
 
     def _scan_inbound(
@@ -474,8 +691,7 @@ class VisibilityInboundEnforcement(_VisibilityEnforcementBase):
         name: str,
         outer_name: str,
         args: dict[str, Any],
-        hidden: set[str],
-        regex: re.Pattern[str] | None,
+        matcher: _HiddenMatcher,
     ) -> None:
         """Conceal on an exact hidden-id argument; refuse on an embedded one."""
         exact: str | None = None
@@ -483,8 +699,8 @@ class VisibilityInboundEnforcement(_VisibilityEnforcementBase):
         if current_tool_name(outer_name) in CALL_PROXY_META_TOOLS:
             inner = _unwrap_proxy_call(args)
             if inner is not None:
-                exact, embedded = _scan_value(inner[1], hidden, regex)
-        raw_exact, raw_embedded = _scan_value(args, hidden, regex)
+                exact, embedded = _scan_value(inner[1], matcher)
+        raw_exact, raw_embedded = _scan_value(args, matcher)
         exact = exact or raw_exact
         embedded = embedded or raw_embedded
         if exact is not None:
@@ -512,11 +728,11 @@ class VisibilityOutboundEnforcement(_VisibilityEnforcementBase):
         if config is None:
             return await call_next(context)
         try:
-            _hidden, regex = await self._hidden_and_regex(config)
+            matcher = await self._hidden_matcher(config)
         except VisibilityDataUnavailable:
             _raise_enforced(effective_name, _FAIL_CLOSED_REASON)
         return await self._call_and_scan_outbound(
-            effective_name, context, call_next, regex
+            effective_name, context, call_next, matcher
         )
 
     async def _call_and_scan_outbound(
@@ -524,19 +740,38 @@ class VisibilityOutboundEnforcement(_VisibilityEnforcementBase):
         name: str,
         context: MiddlewareContext,
         call_next: CallNext,
-        regex: re.Pattern[str] | None,
+        matcher: _HiddenMatcher,
     ) -> Any:
         """Run the tool; refuse if its output (or a tool error) names a hidden id."""
         try:
             result = await call_next(context)
         except ToolError as exc:
-            if regex is not None and regex.search(_tool_error_text(exc)):
+            if matcher.embeds(_tool_error_text(exc)):
                 logger.info("visibility enforce: refused tool error from %s", name)
                 _raise_enforced(name, _outbound_reason(name))
             raise
-        if regex is not None and regex.search(_serialize_result(result)):
+        scrub_tally = _ScrubTally(0, 0, 0)
+        if name == _STATE_TOOL:
+            scrub_tally = _scrub_state_result(result, matcher)
+            if scrub_tally.unwarnable_representations:
+                # A retained original still names a hidden id; refuse here rather
+                # than rely on the scan below catching it.
+                logger.info(
+                    "visibility enforce: ha_get_state scrub could not attach its "
+                    "omission warning to %d JSON representation(s); refused",
+                    scrub_tally.unwarnable_representations,
+                )
+                _raise_enforced(name, _outbound_reason(name))
+        if matcher.embeds(_serialize_result(result)):
             logger.info("visibility enforce: refused result from %s", name)
             _raise_enforced(name, _outbound_reason(name))
+        if scrub_tally.mutated_representations:
+            logger.info(
+                "visibility enforce: scrubbed %d omission(s) across %d "
+                "ha_get_state JSON representation(s)",
+                scrub_tally.omissions,
+                scrub_tally.mutated_representations,
+            )
         return result
 
 
@@ -601,41 +836,37 @@ class _HiddenSetCache:
 
     def __init__(self) -> None:
         self._lock = asyncio.Lock()
-        self._hidden: set[str] | None = None
-        self._regex: re.Pattern[str] | None = None
+        self._matcher: _HiddenMatcher | None = None
         self._key: str | None = None
         self._expiry = 0.0
 
-    async def get(
-        self, config: VisibilityConfig, client: Any
-    ) -> tuple[set[str], re.Pattern[str] | None]:
+    async def get(self, config: VisibilityConfig, client: Any) -> _HiddenMatcher:
         key = _config_cache_key(config)
         now = time.monotonic()
         async with self._lock:
-            if self._hidden is not None and self._key == key and now < self._expiry:
-                return self._hidden, self._regex
+            if self._matcher is not None and self._key == key and now < self._expiry:
+                return self._matcher
             try:
                 hidden = await _refresh_hidden_set(config, client)
             except Exception:
-                if self._hidden is not None and self._key == key:
+                if self._matcher is not None and self._key == key:
                     logger.warning(
                         "visibility enforce: hidden-set refresh failed; using "
                         "last-known-good set",
                         exc_info=True,
                     )
-                    return self._hidden, self._regex
+                    return self._matcher
                 logger.warning(
                     "visibility enforce: hidden-set refresh failed with no "
                     "last-known-good for this config; failing closed",
                     exc_info=True,
                 )
                 raise VisibilityDataUnavailable("hidden set unavailable") from None
-            regex = _build_hidden_regex(hidden)
-            self._hidden = hidden
-            self._regex = regex
+            matcher = _HiddenMatcher.from_hidden(hidden)
+            self._matcher = matcher
             self._key = key
             self._expiry = now + _CACHE_TTL_SECONDS
-            return hidden, regex
+            return matcher
 
 
 _hidden_cache = _HiddenSetCache()
@@ -664,10 +895,10 @@ async def active_hidden_regex(client: Any) -> re.Pattern[str] | None:
             and config_has_active_hide_dimensions(config)
         ):
             return None
-        _hidden, regex = await _hidden_cache.get(config, client)
+        matcher = await _hidden_cache.get(config, client)
     except Exception:
         return None
-    return regex
+    return matcher.regex
 
 
 def scrub_records(