ha-mcp-dev 8.6.0.dev2887__tar.gz → 8.6.0.dev2889__tar.gz

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2887
+Version: 8.6.0.dev2889
 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-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/pyproject.toml

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

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2887"
+version = "8.6.0.dev2889"
 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.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/config_registry.py

@@ -457,12 +457,12 @@ ADDON_SYNCED_ADVANCED_FIELDS: tuple[str, ...] = (
 )
 
 
-# Auto-backup runtime-editable fields (#1288 web UI editor). Each entry
+# Backup runtime-editable fields (#1288 web UI editor). Each entry
 # is (field_name, env_var_name, python_type). The web UI's
 # /api/settings/backups/config GET/POST endpoints iterate this tuple to
 # advertise per-field origin (env / addon / file / default) and to
 # validate incoming writes. Keep aligned with the matching ``Settings``
-# fields above — adding a fourth runtime-editable setting means a new
+# fields above — adding a runtime-editable setting means a new
 # tuple entry plus matching addon ``config.yaml`` schema mirror.
 BACKUP_OVERRIDE_FIELDS: tuple[BackupOverrideField, ...] = (
     BackupOverrideField("enable_auto_backup", "ENABLE_AUTO_BACKUP", bool),
@@ -478,6 +478,8 @@ BACKUP_OVERRIDE_FIELDS: tuple[BackupOverrideField, ...] = (
         "HAMCP_AUTO_BACKUP_CALENDAR_LOOKAHEAD_DAYS",
         int,
     ),
+    BackupOverrideField("enable_snapshot_actions", "ENABLE_SNAPSHOT_ACTIONS", bool),
+    BackupOverrideField("backup_read_only", "BACKUP_READ_ONLY", bool),
     BackupOverrideField("enable_snapshot_delete", "ENABLE_SNAPSHOT_DELETE", bool),
     BackupOverrideField(
         "snapshot_delete_min_age_days", "SNAPSHOT_DELETE_MIN_AGE_DAYS", int

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/config_settings.py

@@ -425,6 +425,11 @@ class Settings(BaseSettings):
         7, ge=1, le=365, alias="HAMCP_AUTO_BACKUP_CALENDAR_LOOKAHEAD_DAYS"
     )
 
+    # Human-managed controls for explicit backup tool operations. Automatic
+    # pre-edit capture follows enable_auto_backup independently.
+    enable_snapshot_actions: bool = Field(True, alias="ENABLE_SNAPSHOT_ACTIONS")
+    backup_read_only: bool = Field(False, alias="BACKUP_READ_ONLY")
+
     # Snapshot-tarball deletion gate (#1861). Off by default: an agent
     # deleting a full HA snapshot is categorically riskier than the
     # lightweight `edits`-scope auto-backups (which already delete freely),

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/settings_ui/_handlers_tools.py

@@ -25,6 +25,8 @@ from ._tools_meta import (
     BPS_MANDATORY_TOOLS,
     _get_tool_metadata,
     gate_is_beta,
+    ignored_disabled_tools,
+    tool_config_warnings,
 )
 
 if TYPE_CHECKING:
@@ -87,11 +89,10 @@ def _bps_locked_tools() -> list[str]:
         if not (settings.enable_mandatory_bps and settings.enable_strict_mandatory_bps):
             return []
     except Exception:
-        logger.warning(
+        logger.exception(
             "settings lookup failed while computing BPS-locked tools; "
             "locking %s conservatively",
             ", ".join(sorted(BPS_MANDATORY_TOOLS)),
-            exc_info=True,
         )
     return sorted(BPS_MANDATORY_TOOLS)
 
@@ -114,6 +115,21 @@ def _stub_gate_is_beta(tool: dict[str, Any]) -> bool:
     return bool(declared)
 
 
+def _ignored_disable_diagnostics(config: dict[str, Any]) -> dict[str, Any]:
+    """Allow the Tools page to retain its conservative BPS lock on lookup errors."""
+    from ..config import get_global_settings
+
+    try:
+        settings = get_global_settings()
+        return {
+            "ignored_disabled_tools": ignored_disabled_tools(config, settings),
+            "tool_config_warnings": tool_config_warnings(config, settings),
+        }
+    except Exception:
+        logger.exception("Failed to read settings for mandatory-disable diagnostics")
+        return {"ignored_disabled_tools": None, "tool_config_warnings": None}
+
+
 def _env_pinned_conflicts(
     states: dict[str, str], env_pinned: dict[str, str]
 ) -> list[str]:
@@ -189,6 +205,7 @@ async def _get_tools(
             "tools": tools,
             "states": states,
             "env_pinned": pinned,
+            **_ignored_disable_diagnostics(config),
             "read_only_exempt": sorted(READ_ONLY_EXEMPT_TOOLS),
             "llm_api": llm_effective,
             "llm_api_overrides": llm_overrides,

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/settings_ui/_tools_meta.py

@@ -138,6 +138,39 @@ def effective_mandatory_tools(settings: Settings) -> set[str]:
     return set(MANDATORY_TOOLS)
 
 
+def ignored_disabled_tools(config: dict[str, Any], settings: Settings) -> list[str]:
+    """Return mandatory tools whose requested disable state is ignored."""
+    mandatory = effective_mandatory_tools(settings)
+    return sorted(
+        name
+        for name, state in config.get("tools", {}).items()
+        if state == "disabled" and name in mandatory
+    )
+
+
+def mandatory_disable_warning(name: str) -> str:
+    """Explain the ignored request, including the strict BPS dependency."""
+    warning = (
+        f"Ignoring disabled_tools entry '{name}': "
+        "this tool is mandatory and remains enabled."
+    )
+    if name in BPS_MANDATORY_TOOLS:
+        warning += (
+            " Strict best-practices mode (enable_strict_mandatory_bps) is on "
+            "and publishes its acknowledgment key only through it. "
+            "Turn strict mode off first to disable the tool."
+        )
+    return warning
+
+
+def tool_config_warnings(config: dict[str, Any], settings: Settings) -> list[str]:
+    """Share mandatory disable warnings across startup, settings, and reports."""
+    return [
+        mandatory_disable_warning(name)
+        for name in ignored_disabled_tools(config, settings)
+    ]
+
+
 # Tools created by FastMCP transforms (not registered through
 # local_provider). No transform-generated tools are currently in use —
 # ``ha_get_skill_guide`` is registered the normal way and is visible
@@ -400,19 +433,8 @@ def apply_tool_visibility(
         disabled_names.add("ha_config_set_yaml")
 
     mandatory = effective_mandatory_tools(settings)
-    stripped_bps = disabled_names & mandatory & BPS_MANDATORY_TOOLS
-    if stripped_bps:
-        # The save handlers reject this combination, but env seeds and
-        # hand-edited tool_config.json bypass them — keep the tool on and
-        # say why, rather than silently locking out every strict-gated
-        # write (the acknowledgment key is published only through it).
-        logger.warning(
-            "Keeping %s enabled despite a disable entry: strict "
-            "best-practices mode (enable_strict_mandatory_bps) is on and "
-            "publishes its acknowledgment key only through it. Turn "
-            "strict mode off first to disable the tool.",
-            ", ".join(sorted(stripped_bps)),
-        )
+    for warning in tool_config_warnings(config, settings):
+        logger.warning("%s", warning)
     disabled_names -= mandatory
 
     if disabled_names:

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/settings_ui/locales/en.json

@@ -234,6 +234,7 @@
     "tools.notes.beta_disabled": "Beta. Set {setting} in the dev app (add-on) config or matching environment variable (see docs/beta.md).",
     "tools.notes.env_pinned": "Pinned by {variable}. Unset the environment variable to edit here.",
     "tools.notes.bps_locked": "Locked while Strict best-practices mode is on. Turn that setting off first to disable this tool.",
+    "tools.notes.mandatory_disabled_ignored": "Disable request ignored: this tool is mandatory and remains enabled.",
     "tools.notes.read_only_off": "Off. Read Only Mode is on; write tools are disabled.",
     "tools.notes.read_only_partial": "Read Only Mode: write operations of this tool are blocked; read operations stay available.",
     "tools.llm_api.label": "LLM API",
@@ -253,6 +254,10 @@
     "tools.read_only.save_failed": "Read Only Mode change did not save. The server still has the previous value.",
     "backup.fields.enable_auto_backup.label": "Auto-backup edits",
     "backup.fields.enable_auto_backup.help": "Capture a snapshot before every wrapped write or destructive tool call.",
+    "backup.fields.enable_snapshot_actions.label": "Allow full HA snapshot actions",
+    "backup.fields.enable_snapshot_actions.help": "Allow AI assistants to manage full Home Assistant snapshots through ha_manage_backup and the equivalent backup services and commands in ha_call_service. Turning this off blocks every snapshot action, including listing. Snapshot deletion is only available through ha_manage_backup and also requires Allow snapshot deletion. Edit backups and human actions in this page remain available.",
+    "backup.fields.backup_read_only.label": "Make backup management read-only",
+    "backup.fields.backup_read_only.help": "Allow AI assistants to list, view, and diff edit backups, and list full HA snapshots when snapshot actions are enabled. Block manual backup create, restore (including edit restores), and delete, including the equivalent backup services and commands in ha_call_service. Automatic pre-edit backups continue. Human actions in this page remain available.",
     "backup.fields.auto_backup_throttle_minutes.label": "Throttle (minutes)",
     "backup.fields.auto_backup_throttle_minutes.help": "Per-entity throttle. 0 = every write; N > 0 = at most one backup per N minutes. Range 0–1440.",
     "backup.fields.auto_backup_retain_per_entity.label": "Retain per entity",
@@ -495,6 +500,10 @@
     "addon.enable_security_policy_tool.name": "Let AI agents edit tool security policies",
     "addon.enable_security_policy_tool.description": "Registers the ha_manage_security_policy tool, which lets connected AI agents read and rewrite the tool security policies — including removing approval gates. Off by default. Independent of the Tool Security Policies option above: this controls who can edit the rules, not whether they are enforced. The tool cannot see or decide pending approvals. To keep a human in the loop, gate the tool before enabling it: switch on \"security gated\" for Manage Security Policy in the Tools tab of the web UI. Requires restart to take effect.",
     "addon.enable_auto_backup.name": "Enable auto-backup of edits",
+    "addon.enable_snapshot_actions.name": "Allow full HA snapshot actions",
+    "addon.enable_snapshot_actions.description": "Allow AI assistants to manage full Home Assistant snapshots through ha_manage_backup(scope='snapshot') and the equivalent backup services and commands in ha_call_service. Turning this off blocks every snapshot action, including listing, while edit backups remain available. Snapshot deletion is only available through ha_manage_backup, also requires enable_snapshot_delete, and its protections still apply. On by default. Change this option or use the web Settings UI Backups tab; requires restart in the app.",
+    "addon.backup_read_only.name": "Make backup management read-only",
+    "addon.backup_read_only.description": "Restrict ha_manage_backup to listing, viewing, and diffing edit backups, and listing full HA snapshots when snapshot actions are enabled. Blocks manual backup create, restore (including edit restores), and delete, including the equivalent backup services and commands in ha_call_service. Automatic pre-edit backups continue, and human actions in the web Settings UI remain available. Off by default; requires restart in the app.",
     "addon.enable_auto_backup.description": "Captures a per-entity snapshot before every wrapped write/destructive MCP tool call (automation, script, scene, helper, dashboard, dashboard resource, label, category, group, zone, area, calendar, todo, entity, device, integration, and sibling remove/delete tools). The auto-backup throttle bounds how often that happens: 0 (default) captures on every such call, N>0 at most one snapshot per N minutes per entity. Snapshots are saved as YAML files under /data/ha_mcp_backups/ (override via HAMCP_BACKUP_DIR) and listed, restored, or deleted via the Backups tab in the web settings UI or via ha_manage_backup(scope='edits', ...). For those domains the capture is best-effort — a failure logs a WARNING and the write proceeds. The file and raw-YAML tools are the exception: ha_write_file, ha_delete_file and ha_config_set_yaml treat the snapshot as a precondition, so a write through them is refused while this is off, and a failed capture blocks it. On by default; unchecking opts out of the best-effort captures and takes the file and raw-YAML tools out of service with them. Requires restart to take effect.",
     "addon.auto_backup_throttle_minutes.name": "Auto-backup throttle (minutes)",
     "addon.auto_backup_throttle_minutes.description": "Per-entity throttle window. 0 (default) captures a snapshot on every wrapped write. N>0 captures at most one snapshot per N minutes per entity. Range 0–1440.",

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/settings_ui/settings_js/01_i18n_state.js

@@ -204,6 +204,7 @@ let toolEnvPinned = {};
 // Server-side saves reject the conflict too — this lock is the
 // courteous UI half.
 let bpsLockedTools = new Set();
+let ignoredDisabledTools = new Set();
 // Conversation-agent LLM API exposure (#1745). toolLlm mirrors the
 // server-computed EFFECTIVE value per tool (user override, else the
 // deny-by-default for beta/dev/restart tools); toolLlmOverrides holds

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/settings_ui/settings_js/02_tools_restart.js

@@ -33,6 +33,7 @@ async function loadTools() {
   toolStates = data.states || {};
   toolEnvPinned = data.env_pinned || {};
   bpsLockedTools = new Set(data.bps_locked_tools || []);
+  ignoredDisabledTools = new Set(data.ignored_disabled_tools || []);
   toolLlm = data.llm_api || {};
   toolLlmOverrides = data.llm_api_overrides || {};
   llmApiAvailable = !!data.llm_api_available;

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/settings_ui/settings_js/03_render_save.js

@@ -16,7 +16,7 @@ function isReadOnlyForcedOff(t) {
   const ann = t.annotations || {};
   if (ann.readOnlyHint === true) return false;
   if (READ_ONLY_EXEMPT.has(t.name)) return false;
-  if (MANDATORY.includes(t.name)) return false;
+  if (MANDATORY.includes(t.name) || bpsLockedTools.has(t.name)) return false;
   return true;
 }
 
@@ -81,11 +81,11 @@ function render() {
       !isReadOnlyForcedOff(t));
     const anyEnabled = toggleable.some(t => getState(t.name) !== 'disabled');
     const groupEnabled = tools.filter(t => {
+      if (MANDATORY.includes(t.name) || bpsLockedTools.has(t.name)) return true;
       if (isReadOnlyForcedOff(t)) return false;
       if (toolEnvPinned[t.name]) return toolEnvPinned[t.name] !== 'disabled';
       const s = getState(t.name);
-      return MANDATORY.includes(t.name) || bpsLockedTools.has(t.name) ||
-        (!t.disabled_by && s !== 'disabled');
+      return !t.disabled_by && s !== 'disabled';
     }).length;
 
     // Master-switch checked state. Normally it mirrors "any toggleable tool
@@ -168,8 +168,8 @@ function render() {
       const isFeatureGated = disabledBy !== null;
       // env_pinned: "disabled" | "pinned" | undefined — operator-level lock
       // via DISABLED_TOOLS / PINNED_TOOLS env vars. When set, all inputs are
-      // disabled and a banner names the env var. Takes precedence over
-      // isMandatory / isFeatureGated for the lock calculation.
+      // disabled and a banner names the env var. Mandatory tools stay on
+      // regardless, while the requested state remains intact for saves.
       const envPinKind = toolEnvPinned[t.name]; // "disabled" | "pinned" | undefined
       const isEnvPinned = !!envPinKind;
       const envPinVar = envPinKind === 'disabled' ? 'DISABLED_TOOLS' :
@@ -185,22 +185,18 @@ function render() {
       const roForcedOff = isReadOnlyForcedOff(t);
       const roExemptActive = readOnlyState.enabled && READ_ONLY_EXEMPT.has(t.name);
 
-      total++;
-      if (roForcedOff) disabledCount++;
-      else if (isEnvPinned) {
-        if (envPinKind === 'disabled') disabledCount++;
-        else { enabledCount++; pinnedCount++; }
-      } else if (isFeatureGated) disabledCount++;
-      else if (state === 'disabled') disabledCount++;
-      else if (state === 'pinned') { enabledCount++; pinnedCount++; }
-      else enabledCount++;
-
-      const isEnabled = roForcedOff ? false : (isEnvPinned
+      const isEnabled = isMandatory || (roForcedOff ? false : (isEnvPinned
         ? (envPinKind !== 'disabled')
-        : (isFeatureGated ? false : (isMandatory || state !== 'disabled')));
-      const isPinned = roForcedOff ? false : (isEnvPinned
+        : (isFeatureGated ? false : state !== 'disabled')));
+      const isPinned = isMandatory ? (DEFAULT_PINNED.includes(t.name) || state === 'pinned' || envPinKind === 'pinned') : (roForcedOff ? false : (isEnvPinned
         ? (envPinKind === 'pinned')
-        : (isFeatureGated ? false : (isMandatory || state === 'pinned' || DEFAULT_PINNED.includes(t.name))));
+        : (isFeatureGated ? false : (state === 'pinned' || DEFAULT_PINNED.includes(t.name)))));
+      total++;
+      if (!isEnabled) disabledCount++;
+      else {
+        enabledCount++;
+        if (isPinned) pinnedCount++;
+      }
       const lockEnabled = roForcedOff || isEnvPinned || isMandatory || isFeatureGated;
       const lockPinned = roForcedOff || isEnvPinned || isMandatory || isFeatureGated || !isEnabled;
       // The security gate is a policy RULE keyed by tool name, so it can be
@@ -250,7 +246,16 @@ function render() {
                 )
           }</div>`
         : '';
-      const envPinnedNote = isEnvPinned
+      const ignoredDisable = isMandatory && (ignoredDisabledTools.has(t.name) ||
+        state === 'disabled' || envPinKind === 'disabled');
+      const ignoredDisableNote = ignoredDisable
+        ? `<div class="feature-locked-note">${escapeHtml(tr(
+            'tools.notes.mandatory_disabled_ignored',
+            {},
+            'Disable request ignored: this tool is mandatory and remains enabled.'
+          ))}</div>`
+        : '';
+      const envPinnedNote = isEnvPinned && !ignoredDisable
         ? `<div class="feature-locked-note">${tHtml(
             'tools.notes.env_pinned',
             {variable: `<code>${escapeHtml(envPinVar)}</code>`},
@@ -297,6 +302,7 @@ function render() {
         (desc ? `<div class="tool-desc">${escapeHtml(desc)}</div>` : '') +
         gatedNote +
         envPinnedNote +
+        ignoredDisableNote +
         bpsLockedNote +
         readOnlyNote +
         `</div>` +
@@ -581,4 +587,3 @@ function applyToolSearch() {
 document.getElementById('search').addEventListener('input', applyToolSearch);
 
 document.getElementById('restartBtn').addEventListener('click', restartAddon);
-

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/settings_ui/settings_js/04_backups.js

@@ -3,6 +3,14 @@ let backupEntries = [];
 let backupConfigFields = [];
 
 const BACKUP_FIELD_LABELS = {
+  enable_snapshot_actions: {
+    label: 'Allow full HA snapshot actions',
+    help: 'Allow AI assistants to manage full Home Assistant snapshots through ha_manage_backup. Turning this off blocks every snapshot action, including listing. Snapshot deletion also requires Allow snapshot deletion. Edit backups and human actions in this page remain available.',
+  },
+  backup_read_only: {
+    label: 'Make backup management read-only',
+    help: 'Allow AI assistants to list, view, and diff edit backups, and list full HA snapshots when snapshot actions are enabled. Block manual backup create, restore (including edit restores), and delete. Automatic pre-edit backups continue. Human actions in this page remain available.',
+  },
   enable_auto_backup: {
     label: 'Auto-backup edits',
     help: 'Capture a snapshot before every wrapped write/destructive tool call.',
@@ -636,4 +644,3 @@ document.getElementById('modalBackdrop').addEventListener('click', (e) => {
 });
 
 document.getElementById('stopSidecarBtn').addEventListener('click', stopSidecar);
-

{ha_mcp_dev-8.6.0.dev2887 → ha_mcp_dev-8.6.0.dev2889}/src/ha_mcp/tools/backup.py

@@ -43,6 +43,15 @@ from ..client.rest_client import (
 from ..client.websocket_client import HomeAssistantWebSocketClient, get_websocket_client
 from ..config import get_global_settings
 from ..errors import ErrorCode, create_error_response
+from .backup_access import (
+    gate_backup_combo as _gate_combo,
+)
+from .backup_access import (
+    require_backup_access,
+)
+from .backup_access import (
+    require_backup_param as _require,
+)
 from .component_api import (
     component_supports,
     get_component_caps,
@@ -1563,60 +1572,6 @@ async def _execute_snapshot_delete(
     }
 
 
-# Valid (scope, action) combinations. Anything outside this set is
-# rejected with a structured VALIDATION_INVALID_PARAMETER error.
-_VALID_COMBOS: set[tuple[str, str]] = {
-    ("snapshot", "create"),
-    ("snapshot", "list"),
-    ("snapshot", "restore"),
-    ("snapshot", "delete"),
-    ("edits", "create"),
-    ("edits", "list"),
-    ("edits", "view"),
-    ("edits", "diff"),
-    ("edits", "restore"),
-    ("edits", "delete"),
-}
-
-
-def _gate_combo(scope: str, action: str) -> None:
-    """Reject (scope, action) combinations that do not exist.
-
-    Strong gating defends against the LLM accidentally routing "restore
-    my automation" through ``(snapshot, restore)`` (which would restart
-    HA). The error response lists every legal combo so the LLM can
-    self-correct on the next call.
-    """
-    if (scope, action) in _VALID_COMBOS:
-        return
-    raise_tool_error(
-        create_error_response(
-            ErrorCode.VALIDATION_INVALID_PARAMETER,
-            f"Invalid combination: scope={scope!r}, action={action!r}",
-            context={"scope": scope, "action": action},
-            suggestions=[
-                "Valid combinations: "
-                + ", ".join(sorted(f"({s},{a})" for s, a in _VALID_COMBOS)),
-                "scope='snapshot' is for full HA tarball backups (heavy, restart on restore)",
-                "scope='edits' is for per-entity auto-backups produced by write tools (lightweight)",
-            ],
-        )
-    )
-
-
-def _require(param_name: str, value: Any, scope: str, action: str) -> Any:
-    """Validate a required parameter for the picked (scope, action) cell."""
-    if value is None or (isinstance(value, str) and not value.strip()):
-        raise_tool_error(
-            create_error_response(
-                ErrorCode.VALIDATION_INVALID_PARAMETER,
-                f"{param_name!r} is required for scope={scope!r}, action={action!r}",
-                context={"scope": scope, "action": action, "missing_param": param_name},
-            )
-        )
-    return value
-
-
 def register_backup_tools(
     mcp: "FastMCP", client: HomeAssistantClient, **kwargs: Any
 ) -> None:
@@ -1659,6 +1614,8 @@ refused if: the target is a scheduled/automatic backup; it's younger than
 newest snapshot remaining. These guarantee at least one recovery point always
 survives an agent's own mistakes.
 
+**Human-managed backup controls:** `enable_snapshot_actions=false` (ENABLE_SNAPSHOT_ACTIONS) blocks every snapshot action, including listing. `backup_read_only=true` (BACKUP_READ_ONLY) allows edits list/view/diff and snapshot list when snapshots are enabled; it blocks explicit create/restore/delete in both scopes. Automatic pre-edit capture still follows `enable_auto_backup`. A human must change these controls in the Backups tab, app configuration, or environment; developer tools cannot change them. Global and connection Read Only Mode still restrict writes.
+
 **`enable_auto_backup` and `scope="edits"`:** the automatic-on-write capture (every wrapped tool call) is gated by `enable_auto_backup=true` — if the listing is empty, check the toggle (web settings UI or `ENABLE_AUTO_BACKUP=true` env var). The explicit `(edits, create)` action bypasses the toggle since the request is explicit; `list` / `view` / `restore` / `delete` operate on whatever's already on disk regardless of the toggle's current state.
 
 **Template filters:** `edits.create` accepts a Template entity ID and returns its stable config-entry ID as `entity_id`. Use that returned ID for `edits.list` and bulk `edits.delete`; those filters do not resolve entity aliases. After recreation, the restore result reports the replacement config-entry ID and `entity_id_mapping` separately.
@@ -1776,6 +1733,8 @@ survives an agent's own mistakes.
     ) -> dict[str, Any]:
         """Polymorphic backup tool. See the tool description for the routing matrix."""
         _gate_combo(scope, action)
+        settings = get_global_settings()
+        require_backup_access(settings, scope, action)
 
         if scope == "snapshot":
             return await _dispatch_snapshot_action(
@@ -1791,7 +1750,6 @@ survives an agent's own mistakes.
             )
 
         # scope == "edits"
-        settings = get_global_settings()
         mgr = get_backup_manager(client, settings)
         return await _dispatch_edits_action(
             mgr,