fix: address Gemini review — docs, configurable limits, code cleanup

Security (high):
- Fix misleading docs/translations that said "only through MCP tools"
  — now correctly documents api_get/api_post direct API access
- Add explicit warning on _saved_tools about shared state in
  multi-user modes

Code quality (medium):
- Make max invocations configurable: CODE_MODE_MAX_INVOCATIONS setting
  (was hardcoded _MAX_CALL_TOOL_INVOCATIONS = 100)
- Combine isinstance checks for basic types
- Narrow except Exception to json.JSONDecodeError in api_get/api_post
- Rename kwargs to post_kwargs in _api_post to avoid shadowing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kingpanther13

homeassistant-addon-dev/translations/en.yaml

@@ -40,7 +40,7 @@ configuration:
     description: >-
       Allow AI assistants to write and run custom Python code in a secure
       sandbox when no built-in tool can handle the request. Code runs in
-      an isolated interpreter with no filesystem or network access — the
-      only way to interact with Home Assistant is through registered MCP
-      tools. Includes save/reuse for frequently-used custom tools.
-      Requires restart to take effect.
+      an isolated interpreter with no filesystem or network access.
+      Sandbox code can access the HA REST API directly (api_get/api_post)
+      or call existing MCP tools (call_tool). Includes save/reuse for
+      frequently-used custom tools. Requires restart to take effect.

homeassistant-addon/DOCS.md

@@ -229,7 +229,7 @@ Requires add-on restart to take effect.
 
 **Default:** `false`
 
-Enables the `ha_manage_custom_tool` — a sandboxed "escape hatch" that lets AI agents write and run custom Python code when no existing tool covers the request. Code runs in pydantic-monty, a Rust-based sandbox with no filesystem or network access. The only way to interact with Home Assistant is through registered MCP tools via `call_tool()`.
+Enables the `ha_manage_custom_tool` — a sandboxed "escape hatch" that lets AI agents write and run custom Python code when no existing tool covers the request. Code runs in pydantic-monty, a Rust-based sandbox with no filesystem or network access. Sandbox code can access the HA REST API directly via `api_get()`/`api_post()`, or call existing MCP tools via `call_tool()`.
 
 **Safety guardrails:**
 - Code runs in a sandboxed interpreter (no filesystem, no network, no third-party imports)

homeassistant-addon/translations/en.yaml

@@ -40,7 +40,7 @@ configuration:
     description: >-
       Allow AI assistants to write and run custom Python code in a secure
       sandbox when no built-in tool can handle the request. Code runs in
-      an isolated interpreter with no filesystem or network access — the
-      only way to interact with Home Assistant is through registered MCP
-      tools. Includes save/reuse for frequently-used custom tools.
-      Requires restart to take effect.
+      an isolated interpreter with no filesystem or network access.
+      Sandbox code can access the HA REST API directly (api_get/api_post)
+      or call existing MCP tools (call_tool). Includes save/reuse for
+      frequently-used custom tools. Requires restart to take effect.

src/ha_mcp/config.py

@@ -122,6 +122,7 @@ class Settings(BaseSettings):
         10_485_760, alias="CODE_MODE_MAX_MEMORY"
     )  # 10 MB
     code_mode_max_recursion: int = Field(100, alias="CODE_MODE_MAX_RECURSION")
+    code_mode_max_invocations: int = Field(100, alias="CODE_MODE_MAX_INVOCATIONS")
 
     @model_validator(mode="after")
     def _skills_dependency(self) -> "Settings":

src/ha_mcp/tools/tools_code.py

@@ -27,15 +27,15 @@
 
 logger = logging.getLogger(__name__)
 
-# In-memory cache for saved custom tools (session-scoped, not persistent)
+# In-memory cache for saved custom tools (session-scoped, not persistent).
+# WARNING: This is shared across all clients in the same server process.
+# In multi-user modes (OAuth, HTTP), one user's saved tools are visible to
+# all other users.  Scope to per-session/user before multi-user support.
 _saved_tools: dict[str, dict[str, str]] = {}
 
 # Tools that sandbox code must not call (prevents recursive self-invocation)
 _BLOCKED_TOOLS = frozenset({"ha_manage_custom_tool"})
 
-# Max call_tool invocations per sandbox execution (prevents API flooding)
-_MAX_CALL_TOOL_INVOCATIONS = 100
-
 # Validation for save_as names
 _SAVE_NAME_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]{0,63}$")
 
@@ -48,9 +48,7 @@ def _extract_tool_result(result: Any) -> Any:
     float, bool, list, dict, None), so we must serialize.
     """
     # Already a basic type — pass through
-    if isinstance(result, (str, int, float, bool, type(None))):
-        return result
-    if isinstance(result, dict):
+    if isinstance(result, (str, int, float, bool, type(None), dict)):
         return result
 
     # ToolResult or similar: extract content list
@@ -99,13 +97,13 @@ async def _api_get(endpoint: str) -> Any:
         """GET request to Home Assistant REST API."""
         nonlocal call_count
         call_count += 1
-        if call_count > _MAX_CALL_TOOL_INVOCATIONS:
-            return {"error": f"API call limit exceeded ({_MAX_CALL_TOOL_INVOCATIONS})"}
+        if call_count > settings.code_mode_max_invocations:
+            return {"error": f"API call limit exceeded ({settings.code_mode_max_invocations})"}
         try:
             response = await client.httpx_client.request("GET", endpoint)
             try:
                 return response.json()
-            except Exception:
+            except json.JSONDecodeError:
                 return response.text
         except Exception as exc:
             return {"error": str(exc)[:200]}
@@ -114,16 +112,16 @@ async def _api_post(endpoint: str, data: dict[str, Any] | None = None) -> Any:
         """POST request to Home Assistant REST API."""
         nonlocal call_count
         call_count += 1
-        if call_count > _MAX_CALL_TOOL_INVOCATIONS:
-            return {"error": f"API call limit exceeded ({_MAX_CALL_TOOL_INVOCATIONS})"}
+        if call_count > settings.code_mode_max_invocations:
+            return {"error": f"API call limit exceeded ({settings.code_mode_max_invocations})"}
         try:
-            kwargs: dict[str, Any] = {}
+            post_kwargs: dict[str, Any] = {}
             if data is not None:
-                kwargs["json"] = data
-            response = await client.httpx_client.request("POST", endpoint, **kwargs)
+                post_kwargs["json"] = data
+            response = await client.httpx_client.request("POST", endpoint, **post_kwargs)
             try:
                 return response.json()
-            except Exception:
+            except json.JSONDecodeError:
                 return response.text
         except Exception as exc:
             return {"error": str(exc)[:200]}
@@ -141,12 +139,12 @@ async def _call_tool(tool_name: str, arguments: dict[str, Any]) -> Any:
             }
 
         call_count += 1
-        if call_count > _MAX_CALL_TOOL_INVOCATIONS:
+        if call_count > settings.code_mode_max_invocations:
             return {
                 "success": False,
                 "error": {
                     "message": (
-                        f"call_tool limit exceeded ({_MAX_CALL_TOOL_INVOCATIONS} "
+                        f"call_tool limit exceeded ({settings.code_mode_max_invocations} "
                         f"calls per execution)"
                     )
                 },