Merge branch 'pr-854' into addon-repo

Author: kingpanther13

homeassistant-addon-dev/config.yaml

@@ -21,12 +21,14 @@ options:
   enable_skills_as_tools: false
   enable_tool_search: false
   enable_yaml_config_editing: false
+  enable_code_mode: false
 schema:
   backup_hint: list(strong|normal|weak|auto)
   secret_path: str?
   enable_skills: bool?
   enable_skills_as_tools: bool?
   enable_tool_search: bool?
   enable_yaml_config_editing: bool?
+  enable_code_mode: bool?
 ports:
   9583/tcp: 9583

homeassistant-addon-dev/translations/en.yaml

@@ -35,3 +35,12 @@ configuration:
       like homeassistant, http, and recorder are blocked. A backup is
       created before every edit. Use for YAML-only features that have no
       UI or API alternative. Requires restart to take effect.
+  enable_code_mode:
+    name: Enable custom tool sandbox
+    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.
+      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

@@ -225,6 +225,30 @@ Replaces the full tool catalog (~92 tools, ~46K tokens) with search-based discov
 
 Requires add-on restart to take effect.
 
+### enable_code_mode
+
+**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. 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)
+- `destructiveHint=True` — MCP clients prompt for confirmation before execution
+- AI must provide a justification explaining why no existing tool works
+- Configurable time (30s), memory (10MB), and recursion (100) limits
+- Rate limited to 100 tool calls per execution
+- Cannot recursively invoke itself
+
+**When to enable:**
+- You need an "escape hatch" for operations not covered by the 92+ built-in tools
+- You trust the AI agent's judgment on when to write custom code
+
+**When to leave disabled (default):**
+- Standard use cases covered by existing tools
+- You want to restrict the AI to pre-built tools only
+
+Requires add-on restart to take effect.
+
 **Example Configuration:**
 
 ```yaml

homeassistant-addon/config.yaml

@@ -27,13 +27,15 @@ options:
   enable_skills_as_tools: false
   enable_tool_search: false
   enable_yaml_config_editing: false
+  enable_code_mode: false
 schema:
   backup_hint: list(strong|normal|weak|auto)
   secret_path: str?
   enable_skills: bool?
   enable_skills_as_tools: bool?
   enable_tool_search: bool?
   enable_yaml_config_editing: bool?
+  enable_code_mode: bool?
 # Add-on exposes HTTP port for MCP communication (fixed internal port)
 ports:
   9583/tcp: 9583

homeassistant-addon/start.py

@@ -110,6 +110,7 @@ def main() -> int:
     enable_skills_as_tools = False  # default
     enable_tool_search = False  # default
     enable_yaml_config_editing = False  # default
+    enable_code_mode = False  # default
 
     if config_file.exists():
         try:
@@ -125,6 +126,8 @@ def main() -> int:
             enable_tool_search = raw_tool_search if isinstance(raw_tool_search, bool) else False
             raw_yaml_config = config.get("enable_yaml_config_editing", False)
             enable_yaml_config_editing = raw_yaml_config if isinstance(raw_yaml_config, bool) else False
+            raw_code_mode = config.get("enable_code_mode", False)
+            enable_code_mode = raw_code_mode if isinstance(raw_code_mode, bool) else False
         except Exception as e:
             log_error(f"Failed to read config: {e}, using defaults")
 
@@ -140,6 +143,7 @@ def main() -> int:
     os.environ["ENABLE_SKILLS_AS_TOOLS"] = str(enable_skills_as_tools).lower()
     os.environ["ENABLE_TOOL_SEARCH"] = str(enable_tool_search).lower()
     os.environ["ENABLE_YAML_CONFIG_EDITING"] = str(enable_yaml_config_editing).lower()
+    os.environ["ENABLE_CODE_MODE"] = str(enable_code_mode).lower()
 
     # Validate Supervisor token
     supervisor_token = os.environ.get("SUPERVISOR_TOKEN")

homeassistant-addon/translations/en.yaml

@@ -35,3 +35,12 @@ configuration:
       like homeassistant, http, and recorder are blocked. A backup is
       created before every edit. Use for YAML-only features that have no
       UI or API alternative. Requires restart to take effect.
+  enable_code_mode:
+    name: Enable custom tool sandbox
+    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.
+      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.

pyproject.toml

@@ -31,6 +31,7 @@ dependencies = [
     "truststore==0.10.4",
     "websockets==16.0",
     "cryptography==46.0.6",
+    "pydantic-monty==0.0.9",
 ]
 
 [project.urls]
@@ -75,6 +76,8 @@ explicit_package_bases = true
 module = [
     "fastmcp.*",
     "jq",
+    "pydantic_monty",
+    "pydantic_monty.*",
 ]
 ignore_missing_imports = true
 

src/ha_mcp/config.py

@@ -112,6 +112,18 @@ class Settings(BaseSettings):
     # files. Disabled by default; only for YAML-only features with no UI/API path.
     enable_yaml_config_editing: bool = Field(False, alias="ENABLE_YAML_CONFIG_EDITING")
 
+    # Code Mode — sandboxed Python execution via pydantic-monty.
+    # Provides an "escape hatch" tool (ha_manage_custom_tool) that lets LLMs write
+    # custom one-off Python code when no existing tool covers the request.
+    # Disabled by default due to the inherent risk of LLM-generated code.
+    enable_code_mode: bool = Field(False, alias="ENABLE_CODE_MODE")
+    code_mode_max_duration: float = Field(30.0, alias="CODE_MODE_MAX_DURATION")
+    code_mode_max_memory: int = Field(
+        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":
         """Auto-enable skills (resources) when skills-as-tools is on.

src/ha_mcp/server.py

@@ -424,6 +424,10 @@ def _apply_tool_search(self) -> None:
         # Build the always_visible list
         pinned = list(self._PINNED_TOOLS)
 
+        # Pin code mode tool so it gets individual permission gating
+        if self.settings.enable_code_mode:
+            pinned.append("ha_manage_custom_tool")
+
         # Pin ResourcesAsTools and skill guidance tools if skills-as-tools is enabled
         if self.settings.enable_skills_as_tools:
             pinned.extend(["list_resources", "read_resource"])