ha-mcp-dev 7.14.2.dev2107__tar.gz → 7.14.2.dev2109__tar.gz

{ha_mcp_dev-7.14.2.dev2107/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.2.dev2109}/PKG-INFO

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

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2109}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.14.2.dev2107"
+version = "7.14.2.dev2109"
 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-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2109}/src/ha_mcp/errors.py

@@ -116,6 +116,14 @@ class ErrorCode(StrEnum):
     # backup directory is unusable). Fail-closed: nothing was changed.
     BACKUP_CAPTURE_FAILED = "BACKUP_CAPTURE_FAILED"
 
+    # Entity visibility enforce mode (#2015). A read was refused because the
+    # opt-in visibility filter's enforce mode is active and the request would
+    # surface an entity the filter hides — either the tool's output references a
+    # hidden entity, or the tool's output cannot be scanned (screenshots, sandbox
+    # code). Direct reads of a hidden entity are concealed as ENTITY_NOT_FOUND
+    # instead; this code marks the refuse-on-contact case. No data was returned.
+    ENTITY_VISIBILITY_ENFORCED = "ENTITY_VISIBILITY_ENFORCED"
+
 
 # Default suggestions for common error codes
 DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2109}/src/ha_mcp/llm_exposure.py

@@ -14,9 +14,10 @@ axis from the global enable/disable in the settings UI:
 
 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 @@ from __future__ import annotations
 
 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_NAMESPACE = "ha_mcp"
 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 @@ class LlmExposureMiddleware(Middleware):
         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 @@ class LlmExposureMiddleware(Middleware):
         """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 @@ class LlmExposureMiddleware(Middleware):
                 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

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2109}/src/ha_mcp/policy/handlers.py

@@ -11,6 +11,7 @@ from pydantic import ValidationError
 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})
 
 

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2109}/src/ha_mcp/policy/middleware.py

@@ -35,6 +35,29 @@ PROXY_META_TOOLS = frozenset(
     }
 )
 
+# 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 @@ class PolicyMiddleware(Middleware):
         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:

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2109}/src/ha_mcp/policy/model.py

@@ -16,6 +16,14 @@ PredicateOp = Literal[
     "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":

ha_mcp_dev-7.14.2.dev2109/src/ha_mcp/policy/persistence.py

@@ -0,0 +1,125 @@
+"""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, Rule
+
+logger = logging.getLogger(__name__)
+
+POLICY_FILENAME = "tool_policy.json"
+
+
+def load_policy(data_dir: Path) -> Policy:
+    path = data_dir / POLICY_FILENAME
+    if not path.exists():
+        return Policy()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise ValueError(f"tool_policy.json is not valid JSON: {e}") from e
+    try:
+        return Policy.model_validate(raw)
+    except ValidationError as e:
+        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
+    # caller's payload version != on-disk version).
+    bumped = policy.model_copy(update={"version": policy.version + 1})
+    data_dir.mkdir(parents=True, exist_ok=True)
+    path = data_dir / POLICY_FILENAME
+    fd, tmp_path = tempfile.mkstemp(prefix=f".{POLICY_FILENAME}.", dir=data_dir)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(bumped.model_dump(mode="json"), f, indent=2, sort_keys=True)
+        os.replace(tmp_path, path)
+    except Exception:
+        Path(tmp_path).unlink(missing_ok=True)
+        raise

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2109}/src/ha_mcp/server.py

@@ -249,7 +249,23 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         # 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
+        # enforce is on with an active hide dimension). Must precede the
+        # read-only guard and PolicyMiddleware: a call naming a hidden
+        # entity is concealed as not-found BEFORE it can be stored verbatim
+        # in the approval queue (rendered in the settings UI) or answered
+        # with a read-only/approval response that would confirm existence.
+        self._apply_visibility_inbound_middleware()
 
         # Read Only Mode write blocker (discussion #1569) — always
         # installed, consults the live flag per call. Before
@@ -269,6 +285,11 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         # wraps the final tool surface (including the search proxies).
         self._apply_tool_security_policies()
 
+        # Entity visibility enforce mode, OUTBOUND half (#2015) — added LAST
+        # so it is innermost: its result scan sees the raw tool output before
+        # any other middleware transforms it.
+        self._apply_visibility_outbound_middleware()
+
     def _get_skills_dir(self) -> Path | None:
         """Return the bundled skills directory if it exists.
 
@@ -1008,6 +1029,25 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         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
 
@@ -1125,6 +1165,35 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
 
         self.mcp.add_middleware(StrictBpsMiddleware(list_tools=_list_all_tools))
 
+    def _apply_visibility_inbound_middleware(self) -> None:
+        """Install the enforce-mode INBOUND (conceal/refuse) middleware (#2015).
+
+        Always installed — self-no-ops at call time (loads the visibility
+        config per request and passes through unless enforce is on with an
+        active hide dimension), so a settings-UI toggle applies live in
+        standalone-HTTP/embedded mode like ``read_only_mode``. It needs the HA
+        client to fetch the registry/states for the hidden-set computation;
+        inject the lazy client accessor so no eager connection is made at
+        startup. Ordering (before read-only/policy) is owned by the caller.
+        """
+        from .visibility.enforcement import VisibilityInboundEnforcement
+
+        self.mcp.add_middleware(
+            VisibilityInboundEnforcement(get_client=lambda: self.client)
+        )
+
+    def _apply_visibility_outbound_middleware(self) -> None:
+        """Install the enforce-mode OUTBOUND (result-scan) middleware (#2015).
+
+        Same always-installed/self-no-op contract as the inbound half; the
+        caller registers it last so it is innermost and scans raw tool output.
+        """
+        from .visibility.enforcement import VisibilityOutboundEnforcement
+
+        self.mcp.add_middleware(
+            VisibilityOutboundEnforcement(get_client=lambda: self.client)
+        )
+
     # Shared action-phrased keyword block for retrieval. Some MCP clients
     # (Claude Code, others) rank candidate tools by token-overlap between
     # the user's natural-language query and each tool's `description`

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2109}/src/ha_mcp/settings_ui/_handlers_backups.py

@@ -244,32 +244,42 @@ async def _delete_backups_bulk(
     )
 
 
-async def _get_backup_config(
-    server: HomeAssistantSmartMCPServer | None, _: Request
-) -> JSONResponse:
-    """Return live auto-backup config + per-field origin + editable flag.
-
-    Per-field origin/editable matrix (see ``config.get_backup_setting_origin``):
-    - ``addon``: editable — POST routes through Supervisor.
-    - ``env``: read-only — env var wins; user must unset to edit.
-    - ``file``/``default``: editable — POST writes the override file.
+def backup_config_fields() -> list[dict[str, Any]]:
+    """Auto-backup fields with per-field value/origin/editable.
+
+    Shared by the HTTP ``_get_backup_config`` handler and the
+    ``ha_dev_manage_settings`` developer tool so the two never drift.
+    Origin/editable matrix (see ``config.get_backup_setting_origin``):
+    ``addon`` editable (Supervisor), ``env`` read-only, ``file``/``default``
+    editable (override file).
     """
     settings = get_global_settings()
-    addon_mode = is_running_in_addon()
-    fields = []
+    fields: list[dict[str, Any]] = []
     for field_name, env_name, _ftype in BACKUP_OVERRIDE_FIELDS:
         origin = get_backup_setting_origin(env_name)
-        editable = origin in ("addon", "file", "default")
         fields.append(
             {
                 "field": field_name,
                 "env_var": env_name,
                 "value": getattr(settings, field_name),
                 "origin": origin,
-                "editable": editable,
+                "editable": origin in ("addon", "file", "default"),
             }
         )
-    return JSONResponse({"success": True, "is_addon": addon_mode, "fields": fields})
+    return fields
+
+
+async def _get_backup_config(
+    server: HomeAssistantSmartMCPServer | None, _: Request
+) -> JSONResponse:
+    """Return live auto-backup config + per-field origin + editable flag."""
+    return JSONResponse(
+        {
+            "success": True,
+            "is_addon": is_running_in_addon(),
+            "fields": backup_config_fields(),
+        }
+    )
 
 
 # Inclusive bounds for the integer auto-backup fields; a field absent here
@@ -414,36 +424,15 @@ async def _save_backup_config_addon(
     )
 
 
-async def _save_backup_config(
-    server: HomeAssistantSmartMCPServer | None, request: Request
-) -> JSONResponse:
-    """Persist auto-backup config edits and publish to the live process.
+def _apply_backup_config_file(clean: dict[str, Any]) -> JSONResponse:
+    """Standalone/file-mode branch of ``apply_backup_config``.
 
-    Routing:
-    - Addon mode: POST ``/addons/self/options`` and return
-      ``restart_required=True`` (see ``_save_backup_config_addon``).
-    - Standalone (file) mode: refuse any field that's pinned by an env var
-      (process or ``.env``) — return 409 with the offending names so the UI
-      can refresh and show the read-only banner. Editable fields merge into
-      ``<data_dir>/backup_settings.json`` and a Settings cache reset
-      publishes them immediately, hence ``restart_required=False``.
+    Refuse any field pinned by an env var (process or ``.env``) — 409 with
+    the offending names so the UI can refresh and show the read-only banner.
+    Editable fields merge into ``<data_dir>/backup_settings.json`` and a
+    Settings cache reset publishes them immediately, hence
+    ``restart_required=False``.
     """
-    try:
-        payload = await request.json()
-    except (ValueError, json.JSONDecodeError):
-        return _bad_request("Invalid JSON body")
-    clean, err = _validate_backup_payload(payload)
-    if err is not None:
-        return _bad_request(err)
-
-    if is_running_in_addon():
-        # ``is_running_in_addon()`` checks SUPERVISOR_TOKEN — the
-        # ``_save_backup_config_addon`` helper called below also catches the
-        # missing-token ``RuntimeError`` from ``make_supervisor_httpx_client``
-        # as defense-in-depth.
-        return await _save_backup_config_addon(server, clean)
-
-    # Standalone (file) mode — refuse to override env-pinned fields.
     rejected = _filter_env_pinned_backup_fields(clean)
     if rejected:
         return JSONResponse(
@@ -483,6 +472,51 @@ async def _save_backup_config(
     )
 
 
+async def apply_backup_config(
+    server: HomeAssistantSmartMCPServer | None, clean: dict[str, Any]
+) -> JSONResponse:
+    """Route already-validated auto-backup fields to their persistence path.
+
+    Addon mode POSTs to Supervisor (``_save_backup_config_addon``);
+    standalone/file mode merges the override file (``_apply_backup_config_file``).
+    Shared core of the HTTP save handler (``_save_backup_config``) and the
+    ``ha_dev_manage_settings`` developer tool so both take identical
+    addon-vs-file routing and env-pin rejection — ``clean`` must already be
+    validated by ``_validate_backup_payload``.
+    """
+    if is_running_in_addon():
+        # ``is_running_in_addon()`` checks SUPERVISOR_TOKEN — the
+        # ``_save_backup_config_addon`` helper also catches the missing-token
+        # ``RuntimeError`` from ``make_supervisor_httpx_client`` as
+        # defense-in-depth.
+        return await _save_backup_config_addon(server, clean)
+    # Same write-guard treatment as tool_config/tool_policy: the RMW is
+    # synchronous (safe in-process), but the guard's file lock keeps a
+    # writer in another process from interleaving with it.
+    from ..utils.config_write_lock import config_write_guard
+
+    async with config_write_guard():
+        return _apply_backup_config_file(clean)
+
+
+async def _save_backup_config(
+    server: HomeAssistantSmartMCPServer | None, request: Request
+) -> JSONResponse:
+    """Persist auto-backup config edits and publish to the live process.
+
+    Parses and validates the request body, then delegates the addon-vs-file
+    routing to ``apply_backup_config`` (shared with the developer tool).
+    """
+    try:
+        payload = await request.json()
+    except (ValueError, json.JSONDecodeError):
+        return _bad_request("Invalid JSON body")
+    clean, err = _validate_backup_payload(payload)
+    if err is not None:
+        return _bad_request(err)
+    return await apply_backup_config(server, clean)
+
+
 def build_backups_handlers(
     server: HomeAssistantSmartMCPServer | None,
 ) -> dict[str, Any]: