ha-mcp-dev 9.0.0.dev3198__tar.gz → 9.0.0.dev3202__tar.gz

{ha_mcp_dev-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.0.0.dev3198
+Version: 9.0.0.dev3202
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.0.dev3198"
+version = "9.0.0.dev3202"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.0.dev3198"
+version = "9.0.0.dev3202"
 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-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/src/ha_mcp/settings_ui/locales/en.json

@@ -103,7 +103,7 @@
     "visibility.boundary": "Without enforce mode (below), this is noise reduction, not access control: a hidden entity is still returned by a direct read of its entity_id and still appears in automation, dashboard, and template content. Do not rely on the filter alone as a security boundary.",
     "visibility.enabled": "Enable entity visibility filter",
     "visibility.enforce.title": "Enforce mode",
-    "visibility.enforce.help": "Extends the filter from decluttering search and overview to every tool read except ha_report_issue by default. A direct read of a hidden entity returns “not found”, and a content read that would surface one is refused. The report-tool exception is controlled below. Best-effort concealment against incidental exposure, not a hardened security boundary.",
+    "visibility.enforce.help": "Extends the filter from decluttering search and overview to every tool read except ha_report_issue by default. A direct read of a hidden entity returns “not found”, and a content read that would surface one is refused. The report-tool exception is controlled below. Best-effort concealment against incidental exposure, not a hardened security boundary. It can also refuse more than needed: a read that only shares a hidden script, scene or automation’s key or ID may be refused too.",
     "visibility.enforce.only_enforced": "Make hidden entities unreadable across tool reads (except issue reports by default)",
     "visibility.enforce.report_issue_help": "While this is off, ha_report_issue and all of its diagnostic output—including logs—stay outside enforce mode on every call, even when visibility data is healthy or unavailable. Turn it on to scan and refuse that tool like other reads.",
     "visibility.enforce.restrict_report_issue": "Apply enforce mode to ha_report_issue",

ha_mcp_dev-9.0.0.dev3202/src/ha_mcp/tools/config_file_visibility.py

@@ -0,0 +1,53 @@
+"""Enforce-mode guard for config-file reads (``ha_read_file``, ``ha_config_get_yaml``).
+
+The component's ``read_file`` service applies ``tail_lines`` and ``yaml_path``
+itself, and a slice can start anywhere inside a hidden block, so the decision is
+made on the whole file: while enforce mode hides a script, scene or automation,
+each YAML target is read in full first and the call is refused when that file
+defines a hidden item. That costs one extra read per file, only in enforce mode.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterable
+from typing import Any
+
+from ..visibility.config_files import defines_hidden_item, is_yaml_path
+from .tools_filesystem import call_mcp_tools_service
+from .util_helpers import unwrap_service_response
+
+
+async def refuse_reading_hidden_definitions(
+    client: Any, tool_name: str, paths: Iterable[str]
+) -> None:
+    """Refuse the call when any YAML file in ``paths`` defines a hidden item.
+
+    A file the full read cannot return is left to the real read, which reports
+    the same failure. A transport error propagates rather than letting the
+    sliced read run unchecked.
+    """
+    from ..visibility.enforcement import (
+        active_identifier_aliases,
+        refuse_hidden_config_file,
+    )
+
+    aliases = await active_identifier_aliases(client)
+    if aliases is None or not (aliases.script_services or aliases.storage_keys):
+        return
+    targets = [path for path in paths if is_yaml_path(path)]
+    responses = await asyncio.gather(
+        *(
+            call_mcp_tools_service(client, "read_file", {"path": path})
+            for path in targets
+        )
+    )
+    for path, response in zip(targets, responses, strict=True):
+        body = unwrap_service_response(response) if isinstance(response, dict) else {}
+        content = body.get("content")
+        # Off the event loop: the embedded server shares Home Assistant's loop,
+        # and a large file's pure-Python parse would stall it.
+        if isinstance(content, str) and await asyncio.to_thread(
+            defines_hidden_item, path, content, aliases
+        ):
+            refuse_hidden_config_file(tool_name)

{ha_mcp_dev-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/src/ha_mcp/tools/tools_config_automations.py

@@ -70,6 +70,7 @@ from .helpers import (
 )
 from .reference_validator import validate_config_references
 from .tool_hints import read_only_hints, write_hints
+from .util_helpers import list_visible_registry_ids
 from .ws_waiters import (
     verify_entity_removed,
     wait_for_automation_entity_by_unique_id,
@@ -1596,33 +1597,6 @@ class AutomationConfigTools:
         )
         return response
 
-    async def _list_automation_entity_ids(self) -> list[str]:
-        """Best-effort list of automation entity_ids (up to 10) from the entity registry.
-
-        Used to populate ``available_automation_ids`` in RESOURCE_NOT_FOUND
-        error context. Returns an empty list on any failure — caller treats
-        absence as "no IDs to report" rather than failing the structured
-        error raise. The 10-entry cap lives here (not at the callers) so a
-        new call site can't accidentally bloat the error payload.
-        """
-        try:
-            result = await self._client.send_websocket_message(
-                {"type": "config/entity_registry/list"}
-            )
-        except Exception as e:  # noqa: BLE001
-            logger.debug("Failed to list automation entity_ids from registry: %s", e)
-            return []
-        entries = result.get("result", []) if isinstance(result, dict) else result
-        if not isinstance(entries, list):
-            return []
-        return [
-            entry["entity_id"]
-            for entry in entries
-            if isinstance(entry, dict)
-            and isinstance(entry.get("entity_id"), str)
-            and entry["entity_id"].startswith("automation.")
-        ][:10]
-
     async def _guard_alias_replacement(
         self, identifier: str, config: dict[str, Any]
     ) -> str | None:
@@ -1670,7 +1644,7 @@ class AutomationConfigTools:
         ``ha_config_remove_automation``). Populates
         ``available_automation_ids`` (up to 10) from the entity registry.
         """
-        available_ids = await self._list_automation_entity_ids()
+        available_ids = await list_visible_registry_ids(self._client, "automation")
         raise_tool_error(
             create_error_response(
                 ErrorCode.RESOURCE_NOT_FOUND,

{ha_mcp_dev-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/src/ha_mcp/tools/tools_config_scripts.py

@@ -60,6 +60,7 @@ from .helpers import (
 )
 from .reference_validator import validate_config_references
 from .tool_hints import read_only_hints, write_hints
+from .util_helpers import list_visible_registry_ids
 from .ws_waiters import verify_entity_removed, wait_for_entity_registered
 
 logger = logging.getLogger(__name__)
@@ -254,36 +255,6 @@ class ConfigScriptTools:
             response.setdefault("warnings", []).extend(cat_warnings)
         return response
 
-    async def _list_script_entity_ids(self) -> list[str]:
-        """Best-effort list of bare script IDs (up to 10) from the entity registry.
-
-        Returns the bare storage keys (e.g. ``morning_routine``), stripping
-        the ``script.`` entity_id prefix — ``ha_config_get_script`` /
-        ``ha_config_set_script`` / ``ha_config_remove_script`` all take the
-        bare form, so the entity_id prefix would force callers to strip it
-        before retry. Returns an empty list on any failure — caller treats
-        absence as "no IDs to report" rather than failing the structured
-        error raise. The 10-entry cap lives here (not at the callers) so a
-        new call site can't accidentally bloat the error payload.
-        """
-        try:
-            result = await self._client.send_websocket_message(
-                {"type": "config/entity_registry/list"}
-            )
-        except Exception as e:  # noqa: BLE001
-            logger.debug("Failed to list script entity_ids from registry: %s", e)
-            return []
-        entries = result.get("result", []) if isinstance(result, dict) else result
-        if not isinstance(entries, list):
-            return []
-        return [
-            entry["entity_id"][len("script.") :]
-            for entry in entries
-            if isinstance(entry, dict)
-            and isinstance(entry.get("entity_id"), str)
-            and entry["entity_id"].startswith("script.")
-        ][:10]
-
     async def _raise_script_not_found(self, script_id: str) -> None:
         """Raise a structured RESOURCE_NOT_FOUND ToolError for a missing script.
 
@@ -293,7 +264,9 @@ class ConfigScriptTools:
         ``ha_config_remove_script``). Populates ``available_script_ids``
         (up to 10 bare IDs) from the entity registry.
         """
-        available_ids = await self._list_script_entity_ids()
+        available_ids = await list_visible_registry_ids(
+            self._client, "script", bare=True
+        )
         raise_tool_error(
             create_error_response(
                 ErrorCode.RESOURCE_NOT_FOUND,

{ha_mcp_dev-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/src/ha_mcp/tools/tools_filesystem.py

@@ -702,17 +702,17 @@ class FilesystemTools:
         EXAMPLE: ha_read_file(path="packages/alert2.yaml", yaml_path="alert2")
         """
         try:
-            # Check if custom component is available
-            await _assert_mcp_tools_available(self._client)
+            from .config_file_visibility import refuse_reading_hidden_definitions
 
-            # Build service data
+            await _assert_mcp_tools_available(self._client)
+            await refuse_reading_hidden_definitions(
+                self._client, "ha_read_file", [path]
+            )
             service_data: dict[str, Any] = {"path": path}
             if tail_lines is not None:
                 service_data["tail_lines"] = tail_lines
             if yaml_path is not None:
                 service_data["yaml_path"] = yaml_path
-
-            # Call the custom component service
             result = await call_mcp_tools_service(
                 self._client,
                 "read_file",

{ha_mcp_dev-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/src/ha_mcp/tools/tools_yaml_read.py

@@ -27,6 +27,7 @@ from ha_mcp._vendor.fastmcp.exceptions import ToolError
 from ha_mcp._vendor.fastmcp.tools import tool
 
 from ..errors import ErrorCode, create_error_response
+from .config_file_visibility import refuse_reading_hidden_definitions
 from .helpers import (
     exception_to_structured_error,
     log_tool_usage,
@@ -441,6 +442,9 @@ class YamlReadTools:
             # Strictness is a property of each target, not of the request, so
             # the resolver reports which targets were named rather than expanded.
             targets, resolve_warnings = await _resolve_target_files(self._client, file)
+            await refuse_reading_hidden_definitions(
+                self._client, "ha_config_get_yaml", [target for target, _ in targets]
+            )
 
             extra: dict[str, Any] = {"include_parsed": True} if include_parsed else {}
             # The reads are independent, so fan them out rather than paying N

{ha_mcp_dev-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/src/ha_mcp/tools/util_helpers.py

@@ -335,3 +335,40 @@ def is_connection_error_message(error_msg: Any) -> bool:
     """
     lowered = str(error_msg).lower()
     return any(sig in lowered for sig in WS_CONNECTION_SIGNATURES)
+
+
+async def list_visible_registry_ids(
+    client: Any, domain: str, *, bare: bool = False
+) -> list[str]:
+    """Best-effort list of up to 10 visible ``domain`` entity IDs from the registry.
+
+    Populates the ``available_*_ids`` hint of a RESOURCE_NOT_FOUND error. With
+    ``bare`` the ``<domain>.`` prefix is stripped, for tools that take the bare
+    storage-key form. Entities hidden by enforce mode are dropped so the hint
+    neither leaks a hidden ID nor trips the outbound scan. Returns an empty list
+    on any failure: the caller treats absence as "no IDs to report" rather than
+    failing the structured error raise. The cap lives here so a new call site
+    can't bloat the error payload.
+    """
+    from ..visibility.enforcement import active_hidden_entity_ids
+
+    try:
+        result = await client.send_websocket_message(
+            {"type": "config/entity_registry/list"}
+        )
+    except Exception as e:  # noqa: BLE001
+        logger.debug("Failed to list %s entity_ids from registry: %s", domain, e)
+        return []
+    entries = result.get("result", []) if isinstance(result, dict) else result
+    if not isinstance(entries, list):
+        return []
+    hidden = await active_hidden_entity_ids(client)
+    prefix = f"{domain}."
+    return [
+        entity_id.removeprefix(prefix) if bare else entity_id
+        for entry in entries
+        if isinstance(entry, dict)
+        and isinstance(entity_id := entry.get("entity_id"), str)
+        and entity_id.startswith(prefix)
+        and entity_id not in hidden
+    ][:10]

ha_mcp_dev-9.0.0.dev3202/src/ha_mcp/visibility/config_files.py

@@ -0,0 +1,103 @@
+"""Hidden script, scene and automation definitions in Home Assistant config files.
+
+``scripts.yaml`` is keyed by storage key and ``scenes.yaml`` / ``automations.yaml``
+list items by config ``id`` (Core's ``SCRIPT_CONFIG_PATH`` / ``SCENE_CONFIG_PATH``
+/ ``AUTOMATION_CONFIG_PATH``), and a package or ``configuration.yaml`` defines
+them under a ``script:`` / ``scene:`` / ``automation:`` section. A hidden body in
+such a file never spells out its entity_id, so the entity scan cannot see it.
+
+Only those definition positions count: a helper or dashboard key that merely
+shares a hidden script's key is not a definition and stays readable.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from typing import Any
+
+import yaml  # type: ignore[import-untyped]
+
+from .identifier_aliases import IdentifierAliases
+
+_ROOT_FILE_DOMAINS = {
+    "scripts.yaml": "script",
+    "scenes.yaml": "scene",
+    "automations.yaml": "automation",
+}
+# Home Assistant also reads ``<domain> <label>:`` sections (``automation old:``).
+_SECTION_KEY = re.compile(r"^(script|scene|automation)(?: .+)?$")
+_YAML_SUFFIXES = (".yaml", ".yml")
+
+
+class _TagTolerantLoader(yaml.SafeLoader):
+    """SafeLoader that neutralizes HA tags (``!include``, ``!secret``) to None."""
+
+
+_TagTolerantLoader.add_multi_constructor("!", lambda _loader, _suffix, _node: None)
+
+
+def is_yaml_path(path: str) -> bool:
+    return path.casefold().endswith(_YAML_SUFFIXES)
+
+
+def defines_hidden_item(path: str, content: str, aliases: IdentifierAliases) -> bool:
+    """Whether a config file's full ``content`` defines a hidden item.
+
+    An unparseable file is judged by whether its text contains a hidden key at
+    all, failing closed rather than letting a broken file through unchecked.
+    """
+    try:
+        document = yaml.load(content, Loader=_TagTolerantLoader)
+    except yaml.YAMLError:
+        return _mentions_hidden_key(content, aliases)
+    # The component normalizes the path the same way before reading it, so
+    # ``.//scripts.yaml`` and ``www/../scripts.yaml`` are ``scripts.yaml``.
+    root_domain = _ROOT_FILE_DOMAINS.get(posixpath.normpath(path.strip()))
+    if root_domain is not None and _section_defines_hidden(
+        root_domain, document, aliases
+    ):
+        return True
+    return _any_section_defines_hidden(document, aliases)
+
+
+def _any_section_defines_hidden(value: Any, aliases: IdentifierAliases) -> bool:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            match = _SECTION_KEY.match(key) if isinstance(key, str) else None
+            if match and _section_defines_hidden(match.group(1), item, aliases):
+                return True
+            if _any_section_defines_hidden(item, aliases):
+                return True
+    elif isinstance(value, list):
+        return any(_any_section_defines_hidden(item, aliases) for item in value)
+    return False
+
+
+def _section_defines_hidden(
+    domain: str, section: Any, aliases: IdentifierAliases
+) -> bool:
+    if domain == "script":
+        return isinstance(section, dict) and any(
+            isinstance(key, str) and key.casefold() in aliases.script_services
+            for key in section
+        )
+    items = section if isinstance(section, list) else [section]
+    config_ids = aliases.storage_keys.get(domain, frozenset())
+    return any(
+        isinstance(item, dict)
+        and isinstance(item.get("id"), str | int)
+        and str(item["id"]) in config_ids
+        for item in items
+    )
+
+
+def _mentions_hidden_key(content: str, aliases: IdentifierAliases) -> bool:
+    keys = set(aliases.script_services)
+    keys |= aliases.storage_keys.get("scene", frozenset())
+    keys |= aliases.storage_keys.get("automation", frozenset())
+    folded = content.casefold()
+    return any(
+        re.search(rf"(?<![\w-]){re.escape(key.casefold())}(?![\w-])", folded)
+        for key in keys
+    )

{ha_mcp_dev-9.0.0.dev3198 → ha_mcp_dev-9.0.0.dev3202}/src/ha_mcp/visibility/enforcement.py

@@ -55,7 +55,7 @@ import re
 import time
 from collections.abc import Callable
 from contextvars import ContextVar
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, NamedTuple, NoReturn
 
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
@@ -70,6 +70,12 @@ from ..renamed_tools import current_tool_name
 from ..tool_dispatch import CALL_PROXY_META_TOOLS
 from ..tools.helpers import raise_tool_error
 from . import resolver
+from .identifier_aliases import (
+    IdentifierAliases,
+    build_identifier_aliases,
+    hidden_identifier_argument,
+    result_reveals_hidden,
+)
 from .model import VisibilityConfig
 from .resolver import (
     VisibilityDataUnavailable,
@@ -140,6 +146,10 @@ def _state_content_warning(paths: list[str]) -> str:
     )
 
 
+_CONFIG_FILE_REASON = (
+    "The file defines a script, scene or automation restricted by the entity "
+    "visibility filter."
+)
 _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 "
@@ -248,18 +258,25 @@ def _build_hidden_regex(hidden: set[str]) -> re.Pattern[str] | None:
 
 @dataclass(frozen=True)
 class _HiddenMatcher:
-    """The enforced hidden set together with the boundary regex compiled from it.
+    """The enforced hidden set, its identifier aliases and the boundary regex.
 
-    Built only through :meth:`from_hidden`, so ``regex`` is ``None`` exactly when
-    ``hidden`` is empty and every scan sees a consistent pair.
+    ``identifier_aliases`` holds the bare keys that address a hidden script,
+    scene or automation (see ``identifier_aliases``). The regex matches the
+    hidden entity_ids plus the alias terms that run a hidden script without
+    naming it. Built only through :meth:`from_hidden`, so ``regex`` is ``None``
+    exactly when ``hidden`` is empty and every scan sees one consistent view.
     """
 
     hidden: frozenset[str]
     regex: re.Pattern[str] | None
+    identifier_aliases: IdentifierAliases = field(hash=False)
 
     @classmethod
-    def from_hidden(cls, hidden: set[str]) -> _HiddenMatcher:
-        return cls(frozenset(hidden), _build_hidden_regex(hidden))
+    def from_hidden(
+        cls, hidden: set[str], aliases: IdentifierAliases
+    ) -> _HiddenMatcher:
+        terms = hidden | aliases.embedded_terms()
+        return cls(frozenset(hidden), _build_hidden_regex(terms), aliases)
 
     def exact(self, text: str) -> bool:
         """Whether ``text`` is a hidden entity_id."""
@@ -286,6 +303,22 @@ def _serialize_result(result: ToolResult) -> str:
     return "\n".join(parts)
 
 
+def _result_payloads(result: ToolResult) -> list[Any]:
+    """A tool result's structured content and text blocks, JSON-parsed if possible."""
+    payloads: list[Any] = []
+    structured = getattr(result, "structured_content", None)
+    if structured is not None:
+        payloads.append(structured)
+    for block in getattr(result, "content", None) or []:
+        text = getattr(block, "text", None)
+        if isinstance(text, str):
+            try:
+                payloads.append(json.loads(text))
+            except json.JSONDecodeError:
+                payloads.append(text)
+    return payloads
+
+
 # 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
@@ -640,7 +673,7 @@ class _VisibilityEnforcementBase(Middleware):
         return config
 
     async def _hidden_matcher(self, config: VisibilityConfig) -> _HiddenMatcher:
-        """Resolve the hidden set + regex through the module-shared cache."""
+        """Resolve the hidden set, aliases and regex through the module-shared cache."""
         return await _hidden_cache.get(config, self._get_client())
 
 
@@ -687,6 +720,16 @@ class VisibilityInboundEnforcement(_VisibilityEnforcementBase):
         except VisibilityDataUnavailable:
             _raise_enforced(effective_name, _FAIL_CLOSED_REASON)
 
+        bare = hidden_identifier_argument(
+            effective_name, effective_args, matcher.identifier_aliases
+        )
+        if bare is not None:
+            logger.info(
+                "visibility enforce: concealed hidden entity addressed by bare "
+                "identifier in %s call",
+                effective_name,
+            )
+            _conceal_as_not_found(bare)
         self._scan_inbound(effective_name, name, args, matcher)
         return await call_next(context)
 
@@ -766,7 +809,9 @@ class VisibilityOutboundEnforcement(_VisibilityEnforcementBase):
                     scrub_tally.unwarnable_representations,
                 )
                 _raise_enforced(name, _outbound_reason(name))
-        if matcher.embeds(_serialize_result(result)):
+        if matcher.embeds(_serialize_result(result)) or result_reveals_hidden(
+            _result_payloads(result), matcher.identifier_aliases
+        ):
             logger.info("visibility enforce: refused result from %s", name)
             _raise_enforced(name, _outbound_reason(name))
         if scrub_tally.mutated_representations:
@@ -779,7 +824,7 @@ class VisibilityOutboundEnforcement(_VisibilityEnforcementBase):
         return result
 
 
-async def _refresh_hidden_set(config: VisibilityConfig, client: Any) -> set[str]:
+async def _refresh_hidden_set(config: VisibilityConfig, client: Any) -> _HiddenMatcher:
     """Fetch registry/states (+device registry when needed) and resolve strictly.
 
     Mirrors the search seam's fetches. Any fetch error, or a strict resolver
@@ -820,7 +865,9 @@ async def _refresh_hidden_set(config: VisibilityConfig, client: Any) -> set[str]
     hidden, _warnings = await load_hidden_set(
         fetched[1], fetched[0], client, device_result, strict=True
     )
-    return hidden
+    return _HiddenMatcher.from_hidden(
+        hidden, build_identifier_aliases(hidden, fetched[1])
+    )
 
 
 class _HiddenSetCache:
@@ -851,7 +898,7 @@ class _HiddenSetCache:
             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)
+                matcher = await _refresh_hidden_set(config, client)
             except Exception:
                 if self._matcher is not None and self._key == key:
                     logger.warning(
@@ -866,7 +913,6 @@ class _HiddenSetCache:
                     exc_info=True,
                 )
                 raise VisibilityDataUnavailable("hidden set unavailable") from None
-            matcher = _HiddenMatcher.from_hidden(hidden)
             self._matcher = matcher
             self._key = key
             self._expiry = now + _CACHE_TTL_SECONDS
@@ -876,18 +922,11 @@ class _HiddenSetCache:
 _hidden_cache = _HiddenSetCache()
 
 
-async def active_hidden_regex(client: Any) -> re.Pattern[str] | None:
-    """Return the hidden-set regex while enforce mode is active, else ``None``.
+async def _active_matcher(client: Any) -> _HiddenMatcher | None:
+    """The shared matcher while enforce mode is active; ``None`` otherwise or on error.
 
-    Collection-read surfaces (the ha_search config-body branches, legacy and
-    component) call this to OMIT records referencing a hidden entity before the
-    response reaches the middleware's outbound scan — which would otherwise
-    refuse the whole call on contact, turning the issue-#2015 "collection reads
-    omit" contract into a wholesale refusal. ``client`` is the CALLER's live
-    client, used only if the shared cache needs a refresh (the middleware's
-    inbound gate for the request in flight normally primed it already).
-    Fail-soft to ``None`` on any load/data error: the fail-closed policy is
-    owned by the middleware's call gates, not by this best-effort scrub seam.
+    Fail-soft: the fail-closed policy is owned by the middleware's call gates,
+    not by the best-effort tool-side scrubs that call this.
     """
     try:
         config = await asyncio.to_thread(
@@ -899,10 +938,45 @@ async def active_hidden_regex(client: Any) -> re.Pattern[str] | None:
             and config_has_active_hide_dimensions(config)
         ):
             return None
-        matcher = await _hidden_cache.get(config, client)
+        return await _hidden_cache.get(config, client)
     except Exception:  # noqa: BLE001
         return None
-    return matcher.regex
+
+
+async def active_hidden_entity_ids(client: Any) -> frozenset[str]:
+    """The enforced hidden entity_ids, empty while enforce mode is inactive.
+
+    Tools that list entity IDs in a genuine error (``available_script_ids``)
+    drop these so the list neither leaks a hidden ID nor trips the outbound scan.
+    """
+    matcher = await _active_matcher(client)
+    return matcher.hidden if matcher is not None else frozenset()
+
+
+async def active_identifier_aliases(client: Any) -> IdentifierAliases | None:
+    """The hidden items' identifier aliases while enforce mode is active."""
+    matcher = await _active_matcher(client)
+    return matcher.identifier_aliases if matcher is not None else None
+
+
+def refuse_hidden_config_file(tool_name: str) -> NoReturn:
+    """Refuse a config-file read whose file defines a hidden item."""
+    _raise_enforced(tool_name, _CONFIG_FILE_REASON)
+
+
+async def active_hidden_regex(client: Any) -> re.Pattern[str] | None:
+    """Return the hidden-set regex while enforce mode is active, else ``None``.
+
+    Collection-read surfaces (the ha_search config-body branches, legacy and
+    component) call this to OMIT records referencing a hidden entity before the
+    response reaches the middleware's outbound scan — which would otherwise
+    refuse the whole call on contact, turning the issue-#2015 "collection reads
+    omit" contract into a wholesale refusal. ``client`` is the CALLER's live
+    client, used only if the shared cache needs a refresh (the middleware's
+    inbound gate for the request in flight normally primed it already).
+    """
+    matcher = await _active_matcher(client)
+    return matcher.regex if matcher is not None else None
 
 
 def scrub_records(