fix: Guide stale-schema clients past BestPracticeKey client-side rejection (#1910)

Clients that validate tool arguments client-side (VS Code Copilot Chat compiles AJV validators cached per tool name for the whole window session) can keep rejecting BestPracticeKey with 'must NOT have additional properties' after an in-place server upgrade, because the cached schema predates the parameter and carries additionalProperties: false. The rejection never reaches the server, so the strict-BPS block error is the only server surface that can carry the recovery path. Add a second suggestion naming the client error verbatim and directing a full client reload (VS Code: Developer: Reload Window).

Fixes #1901 root-cause guidance; reporter confirmation pending on the issue.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

src/ha_mcp/strict_bps.py

@@ -8,7 +8,10 @@
 best-practices skill content served by ``ha_get_skill_guide``. The block
 error tells the model exactly how to obtain the key but never the key
 itself, forcing it to actually fetch/read the best practices before
-writing.
+writing. It also pre-arms the model with a recovery hint for clients that
+validate tool calls against a stale cached tool schema and reject the
+``BestPracticeKey`` retry client-side (#1901) — that rejection never
+reaches the server, so it cannot be handled anywhere else.
 
 Strict mode is *effective* only when BOTH ``enable_mandatory_bps`` (the
 parent, #1182) and ``enable_strict_mandatory_bps`` (the child, #1779) are
@@ -161,8 +164,12 @@ def strict_bps_ack_line() -> str:
 def _raise_bps_ack_required_error(name: str) -> NoReturn:
     """Raise the structured block error for a gated write missing the key.
 
-    The message and suggestion tell the model how to obtain the key but
-    never contain the key itself.
+    Neither suggestion ever contains the key itself. The first tells the
+    model how to obtain it; the second pre-arms the model for clients
+    that validate tool arguments against a stale cached tool schema and
+    reject the ``BestPracticeKey`` retry client-side (#1901) — that
+    rejection never reaches the server, so this error is the only server
+    surface that can carry the recovery path.
     """
     reference_file = STRICT_BPS_GATED_TOOLS[name]
     message = (
@@ -178,7 +185,14 @@ def _raise_bps_ack_required_error(name: str) -> NoReturn:
             suggestions=[
                 f"Call ha_get_skill_guide(skill={_HA_BEST_PRACTICES_SKILL_NAME!r}, "
                 f"file={reference_file!r}), read the content, then retry with "
-                f"{STRICT_BPS_KEY_PARAM} set."
+                f"{STRICT_BPS_KEY_PARAM} set.",
+                f"If your client then rejects the retry with a schema-validation "
+                f"error such as 'must NOT have additional properties', it is "
+                f"validating against a stale cached tool schema from an older "
+                f"server version that lacks {STRICT_BPS_KEY_PARAM}. Ask the user "
+                f"to fully reload the client application (VS Code: run "
+                f"'Developer: Reload Window' — restarting the MCP server or "
+                f"resetting cached tools is not enough), then retry.",
             ],
             context={"tool_name": name, "strict_mandatory_bps": True},
         )

tests/src/unit/test_strict_bps.py

@@ -196,6 +196,30 @@ async def test_gated_with_wrong_key_blocked(self, strict_on):
         # scene maps to SKILL.md (its canonical first file).
         assert "SKILL.md" in body["error"]["suggestion"]
 
+    async def test_block_error_guides_stale_schema_clients(self, strict_on):
+        """The block error pre-arms the model for schema-validating clients
+        that reject the BestPracticeKey retry against a stale cached tool
+        schema (#1901). That rejection happens client-side — the call never
+        reaches the server — so this error is the only server surface that
+        can carry the recovery path."""
+        mw = StrictBpsMiddleware()
+        call_next = AsyncMock(return_value="ok")
+        ctx = make_context("ha_config_set_dashboard", {"url_path": "x"})
+        with pytest.raises(ToolError) as excinfo:
+            await mw.on_call_tool(ctx, call_next)
+        raw = excinfo.value.args[0]
+        body = json.loads(raw)
+        suggestions = body["error"]["suggestions"]
+        assert len(suggestions) == 2
+        # The primary suggestion stays the key-recovery call.
+        assert "ha_get_skill_guide" in suggestions[0]
+        stale_hint = suggestions[1]
+        # Names the client-side error verbatim so the model can match it.
+        assert "must NOT have additional properties" in stale_hint
+        assert "Developer: Reload Window" in stale_hint
+        # The key literal must still never appear anywhere in the error.
+        assert STRICT_BPS_ACK_KEY not in raw
+
     async def test_gated_with_correct_key_passes_and_strips_key(self, strict_on):
         mw = StrictBpsMiddleware()
         call_next = AsyncMock(return_value="ok")