ha-mcp-dev 8.7.0.dev3045__tar.gz → 8.7.0.dev3050__tar.gz

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.7.0.dev3045"
+version = "8.7.0.dev3050"
 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.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.7.0.dev3045"
+version = "8.7.0.dev3050"
 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.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/config_meta.py

@@ -75,6 +75,8 @@ class Setting:
     range: tuple[float, float] | None = None
     off_value: int | None = None
     choices: tuple[str, ...] | None = None
+    # Free text whose line breaks matter; the UI edits it in a textarea.
+    multiline: bool = False
     # An env value that does not parse or is out of range logs a warning and
     # gives the default, instead of failing the settings validation.
     lenient: bool = False

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/config_registry.py

@@ -19,6 +19,7 @@ from ha_mcp.config_settings import Settings
 
 __all__ = [
     "ADDON_SYNCED_ADVANCED_FIELDS",
+    "ADVANCED_MULTILINE",
     "ADVANCED_RESTART_REQUIRED",
     "ADVANCED_SETTINGS_FIELDS",
     "BACKUP_OVERRIDE_FIELDS",
@@ -244,6 +245,11 @@ _ADVANCED_SETTINGS_CHOICES: dict[str, tuple[str, ...]] = {
     if setting.choices is not None
 }
 
+# Advanced string fields edited as multi-line text (renders as <textarea>).
+ADVANCED_MULTILINE: frozenset[str] = frozenset(
+    name for name, _field, setting in _settings_of("advanced") if setting.multiline
+)
+
 # Advanced fields that take effect only after a restart of the MCP server.
 ADVANCED_RESTART_REQUIRED: frozenset[str] = frozenset(
     name

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/config_settings.py

@@ -280,6 +280,20 @@ class Settings(BaseSettings):
         Setting(surface="advanced", section="tools_surface", restart_required=True),
     ] = Field("all", alias="ENABLED_TOOL_MODULES")
 
+    # Free text appended to the MCP server instructions, so every client
+    # connecting to this installation gets the same user-defined guidance
+    # (e.g. where household notes live). Empty adds nothing.
+    custom_instructions: Annotated[
+        str,
+        Setting(
+            surface="advanced",
+            section="tools_surface",
+            app=_ALL_FLAVORS,
+            restart_required=True,
+            multiline=True,
+        ),
+    ] = Field("", alias="HAMCP_CUSTOM_INSTRUCTIONS")
+
     # Dashboard partial update tools (python_transform, find_card)
     # These are token-efficient alternatives to full config replacement.
     # Disable when using clients with programmatic tool use (future).

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/server.py

@@ -19,16 +19,19 @@ from pydantic import Field
 from .config import _PACKAGE_VERSION, get_global_settings
 from .errors import ErrorCode, create_error_response
 from .http_transport import HttpTransportFastMCP as FastMCP
+from .server_instructions import (
+    build_skills_instructions,
+    compose_instructions,
+    skill_tool_hidden,
+)
 from .server_lifespan import server_lifespan
 from .server_tool_text import (
-    ISSUE_FILING_INSTRUCTIONS,
     LITE_DOCSTRING_DESTINATIONS,
     LITE_DOCSTRINGS,
-    READ_ONLY_INSTRUCTIONS,
     SEARCH_KEYWORDS,
     SEARCH_TOOL_DESCRIPTION,
+    SKILL_TOOL_NAME,
     SKILL_USE_BEFORE_KEYWORDS,
-    TOOL_DISCOVERY_INSTRUCTIONS,
 )
 from .tools.helpers import raise_tool_error
 from .tools.tool_hints import read_only_hints
@@ -46,12 +49,6 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-# Name of the consolidated skill tool. Defined as a module
-# constant so settings UI, instructions, tests, and pinning all agree on
-# one canonical string. 18 chars — well under the 40-char cap that
-# Cloudflare's MCP portal enforces (#1121).
-SKILL_TOOL_NAME = "ha_get_skill_guide"
-
 # Names this tool replaced in #1134. Appended to the catalog description
 # so agents trained on the prior catalog (or pasting old instructions)
 # see the redirect inside the tool itself, not just via BM25 keyword
@@ -319,147 +316,18 @@ class HomeAssistantSmartMCPServer:
 
         return get_skills_dir()
 
-    def _skill_tool_hidden(self) -> bool:
-        """True when ha_get_skill_guide will be absent from the catalog.
-
-        The tool is user- or env-disableable only while strict-BPS mode
-        is off (#1886) — apply_tool_visibility strips the disable
-        otherwise. Consulted at instruction-build time so the skills
-        header doesn't direct clients to a tool that is not being
-        served. Fails toward False (mention the tool): a wrong mention
-        costs one unknown-tool error, a wrong omission hides the only
-        non-resource access path.
-        """
-        try:
-            from .settings_ui._persistence import effective_tool_config
-            from .settings_ui._tools_meta import effective_mandatory_tools
-
-            states = effective_tool_config().get("tools", {})
-            return states.get(
-                SKILL_TOOL_NAME
-            ) == "disabled" and SKILL_TOOL_NAME not in effective_mandatory_tools(
-                self.settings
-            )
-        except Exception:
-            logger.debug("skill-tool visibility lookup failed", exc_info=True)
-            return False
-
     def _build_instructions(self) -> str:
         """Compose the server instructions sent in the MCP initialize response."""
-        sections: list[str] = []
-        skills = self._build_skills_instructions()
-        if skills:
-            sections.append(skills)
-
-        # Surface Read Only Mode in the startup instructions so clients
-        # that show server instructions warn the model up front. Startup
-        # state only — live flips are covered by the structured
-        # READ_ONLY_MODE call errors and the ha_get_overview field.
-        if self.settings.read_only_mode:
-            sections.append(READ_ONLY_INSTRUCTIONS)
-        sections.append(ISSUE_FILING_INSTRUCTIONS)
-        return "\n\n".join(sections)
+        return compose_instructions(self._build_skills_instructions(), self.settings)
 
     def _build_skills_instructions(self) -> str | None:
-        """Build server instructions from bundled skill frontmatter.
-
-        Reads the description field from each SKILL.md's YAML frontmatter
-        and includes it as-is in the server instructions. The description
-        is authored for LLM consumption and should not be parsed or
-        restructured by code.
-
-        Returns None when no skills directory or no parseable skills are
-        present, leaving instructions unchanged from the default (None).
-        """
-        skills_dir = self._get_skills_dir()
-        if not skills_dir:
-            return None
-
-        try:
-            entries = sorted(skills_dir.iterdir())
-        except OSError as e:
-            logger.warning("Could not read skills directory %s: %s", skills_dir, e)
-            return None
-
-        skill_blocks: list[str] = []
-        for skill_dir in entries:
-            main_file = skill_dir / "SKILL.md"
-            if not skill_dir.is_dir() or not main_file.exists():
-                continue
-
-            block = self._build_skill_block(skill_dir.name, main_file)
-            if block:
-                skill_blocks.append(block)
-
-        if not skill_blocks:
-            return None
-
-        if self._skill_tool_hidden():
-            # The user disabled the skill tool (possible only outside
-            # strict-BPS mode, #1886) — directing clients to it would
-            # steer them into a tool that is not in the catalog. Their
-            # stated fallback is a local skills install.
-            access_method = (
-                "Read the skill via MCP resources (resources/read with the "
-                "skill:// URI) — if you can read these instructions, you "
-                "should be able to access resources as well. If for any "
-                "reason you cannot access MCP resources, refer to your "
-                "locally installed copy of these skills instead (the "
-                f"{SKILL_TOOL_NAME} fallback tool is disabled on this "
-                "server)."
-            )
-        else:
-            access_method = (
-                "Read the skill via MCP resources (resources/read with the "
-                "skill:// URI) — if you can read these instructions, you "
-                "should be able to access resources as well. If for any "
-                f"reason you cannot access MCP resources, call {SKILL_TOOL_NAME}() "
-                "with no arguments as a fallback: it returns SKILL.md, then "
-                "pass file='<path>' for a reference file. If you can access "
-                "resources normally, do "
-                "not waste time or tokens on that tool."
-            )
-
-        header = (
-            "IMPORTANT: This server provides best-practice skills that MUST "
-            "be consulted before performing matching actions. "
-            "Read the SKILL.md for the matching skill "
-            "\u2014 it contains a Reference Files table that maps tasks to "
-            "specific reference files. You MUST read the referenced files "
-            "that match your current task before proceeding. "
-            "Do NOT load all reference files upfront "
-            "\u2014 only the ones the table directs you to.\n\n"
-            f"How to access: {access_method}\n"
+        """The skills section of the instructions, or None without skills."""
+        return build_skills_instructions(
+            self._get_skills_dir(), self.settings, skill_tool_hidden(self.settings)
         )
 
-        instructions = header + "\n".join(skill_blocks)
-
-        # Append tool search instructions when enabled
-        if self.settings.enable_tool_search:
-            instructions += TOOL_DISCOVERY_INSTRUCTIONS.format(
-                pinned=", ".join(DEFAULT_PINNED_TOOLS)
-            )
-
-        return instructions
-
     _parse_skill_frontmatter = staticmethod(parse_skill_frontmatter)
 
-    def _build_skill_block(self, skill_name: str, main_file: Path) -> str | None:
-        """Build an instruction block for a single skill.
-
-        Reads the description field from YAML frontmatter and includes it
-        verbatim. The description is designed for LLM consumption and
-        contains its own trigger conditions and symptom indicators.
-        """
-        frontmatter = self._parse_skill_frontmatter(main_file)
-        if not frontmatter:
-            return None
-
-        description = frontmatter["description"]
-        uri = f"skill://{skill_name}/SKILL.md"
-
-        return f"\n### Skill: {skill_name} ({uri})\n{description.strip()}"
-
     def _apply_settings_visibility(self) -> None:
         """Apply persisted tool visibility from ``tool_config.json``.
 
@@ -1089,32 +957,6 @@ class HomeAssistantSmartMCPServer:
         else:
             logger.warning(message, *args)
 
-    def _list_bundled_skills(
-        self, skills_dir: Path
-    ) -> list[tuple[str, Path, dict[str, Any]]]:
-        """Return parsed (name, dir, frontmatter) triples for valid bundled skills.
-
-        Skips entries that aren't directories, lack ``SKILL.md``, or whose
-        frontmatter doesn't parse. Sorted by directory name for stable
-        ordering across clients.
-        """
-        try:
-            entries = sorted(skills_dir.iterdir())
-        except OSError as e:
-            logger.warning("Could not read skills directory %s: %s", skills_dir, e)
-            return []
-
-        skills: list[tuple[str, Path, dict[str, Any]]] = []
-        for skill_dir in entries:
-            main_file = skill_dir / "SKILL.md"
-            if not skill_dir.is_dir() or not main_file.exists():
-                continue
-            frontmatter = self._parse_skill_frontmatter(main_file)
-            if not frontmatter:
-                continue
-            skills.append((skill_dir.name, skill_dir, frontmatter))
-        return skills
-
     def _register_skill_guide_tool(self, skills_dir: Path | None) -> int:
         """Register the ``ha_get_skill_guide`` tool unconditionally.
 

ha_mcp_dev-8.7.0.dev3050/src/ha_mcp/server_instructions.py

@@ -0,0 +1,141 @@
+"""The instructions the server sends in the MCP initialize response.
+
+Sections, in order: the bundled best-practice skills with how to read them
+(plus the tool-search note when that mode is on), the Read Only Mode
+warning, the issue-filing rule, and the installation owner's
+``custom_instructions``. The skills header and access fallbacks are
+defined here; the notices come from ``server_tool_text``.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .server_tool_text import (
+    ISSUE_FILING_INSTRUCTIONS,
+    READ_ONLY_INSTRUCTIONS,
+    SKILL_TOOL_NAME,
+    TOOL_DISCOVERY_INSTRUCTIONS,
+)
+from .transforms import DEFAULT_PINNED_TOOLS
+from .utils.skill_loader import list_skills
+
+if TYPE_CHECKING:
+    from .config_settings import Settings
+
+logger = logging.getLogger(__name__)
+
+OWNER_HEADING = "## Instructions from this installation's owner"
+
+_SKILLS_HEADER = (
+    "IMPORTANT: This server provides best-practice skills that MUST "
+    "be consulted before performing matching actions. "
+    "Read the SKILL.md for the matching skill "
+    "— it contains a Reference Files table that maps tasks to "
+    "specific reference files. You MUST read the referenced files "
+    "that match your current task before proceeding. "
+    "Do NOT load all reference files upfront "
+    "— only the ones the table directs you to.\n\n"
+    "How to access: {access_method}\n"
+)
+
+_RESOURCE_ACCESS = (
+    "Read the skill via MCP resources (resources/read with the "
+    "skill:// URI) — if you can read these instructions, you "
+    "should be able to access resources as well. "
+)
+
+# The user disabled the skill tool (possible only outside strict-BPS mode,
+# #1886) — directing clients to it would steer them into a tool that is not
+# in the catalog. Their stated fallback is a local skills install.
+_LOCAL_SKILLS_FALLBACK = (
+    "If for any reason you cannot access MCP resources, refer to your "
+    "locally installed copy of these skills instead (the "
+    f"{SKILL_TOOL_NAME} fallback tool is disabled on this server)."
+)
+
+_SKILL_TOOL_FALLBACK = (
+    f"If for any reason you cannot access MCP resources, call {SKILL_TOOL_NAME}() "
+    "with no arguments as a fallback: it returns SKILL.md, then "
+    "pass file='<path>' for a reference file. If you can access "
+    "resources normally, do not waste time or tokens on that tool."
+)
+
+
+def skill_tool_hidden(settings: Settings) -> bool:
+    """True when ha_get_skill_guide will be absent from the catalog.
+
+    The tool is user- or env-disableable only while strict-BPS mode
+    is off (#1886) — apply_tool_visibility strips the disable
+    otherwise. Consulted at instruction-build time so the skills
+    header doesn't direct clients to a tool that is not being
+    served. Fails toward False (mention the tool): a wrong mention
+    costs one unknown-tool error, a wrong omission hides the only
+    non-resource access path.
+    """
+    try:
+        from .settings_ui._persistence import effective_tool_config
+        from .settings_ui._tools_meta import effective_mandatory_tools
+
+        states = effective_tool_config(settings).get("tools", {})
+        return states.get(
+            SKILL_TOOL_NAME
+        ) == "disabled" and SKILL_TOOL_NAME not in effective_mandatory_tools(settings)
+    except Exception:
+        logger.debug("skill-tool visibility lookup failed", exc_info=True)
+        return False
+
+
+def skill_block(skill_name: str, description: str) -> str:
+    """One skill's entry: its resource URI and its LLM-authored description."""
+    uri = f"skill://{skill_name}/SKILL.md"
+    return f"\n### Skill: {skill_name} ({uri})\n{description.strip()}"
+
+
+def build_skills_instructions(
+    skills_dir: Path | None, settings: Settings, tool_hidden: bool
+) -> str | None:
+    """Build the skills section from each bundled SKILL.md's frontmatter.
+
+    The description field is authored for LLM consumption and included
+    as-is, never parsed or restructured by code. Returns None when there is
+    no skills directory or no parseable skill; the instructions then start
+    with the notices.
+    """
+    skills = list_skills(skills_dir) if skills_dir else []
+    if not skills:
+        return None
+
+    fallback = _LOCAL_SKILLS_FALLBACK if tool_hidden else _SKILL_TOOL_FALLBACK
+    header = _SKILLS_HEADER.format(access_method=_RESOURCE_ACCESS + fallback)
+    instructions = header + "\n".join(
+        skill_block(name, frontmatter["description"])
+        for name, _dir, frontmatter in skills
+    )
+
+    if settings.enable_tool_search:
+        instructions += TOOL_DISCOVERY_INSTRUCTIONS.format(
+            pinned=", ".join(DEFAULT_PINNED_TOOLS)
+        )
+
+    return instructions
+
+
+def compose_instructions(skills: str | None, settings: Settings) -> str:
+    """Join the skills section with the startup notices and the owner's text."""
+    sections = [skills] if skills else []
+    # Surface Read Only Mode in the startup instructions so clients
+    # that show server instructions warn the model up front. Startup
+    # state only — live flips are covered by the structured
+    # READ_ONLY_MODE call errors and the ha_get_overview field.
+    if settings.read_only_mode:
+        sections.append(READ_ONLY_INSTRUCTIONS)
+    sections.append(ISSUE_FILING_INSTRUCTIONS)
+    custom = settings.custom_instructions.strip()
+    if custom:
+        # Length only: the text itself is the owner's and may be personal.
+        logger.info("custom_instructions active (%d characters)", len(custom))
+        sections.append(f"{OWNER_HEADING}\n{custom}")
+    return "\n\n".join(sections)

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/server_tool_text.py

@@ -1,12 +1,19 @@
 """Static text the server publishes about its tools.
 
 Holds the search tool description, the BM25 keyword boosts, the lite
-docstring variants with their destinations, and the skill keyword block.
-``HomeAssistantSmartMCPServer`` exposes each one as a class attribute.
+docstring variants with their destinations and the skill keyword block,
+which ``HomeAssistantSmartMCPServer`` exposes as class attributes, plus the
+skill tool's name and the instruction notices ``server_instructions`` uses.
 """
 
 from __future__ import annotations
 
+# Name of the consolidated skill tool. Defined as a module constant so the
+# tool registration, the instructions, the mandatory-tool set, the default
+# pins and the tests agree on one canonical string. 18 chars — well under
+# the 40-char cap that Cloudflare's MCP portal enforces (#1121).
+SKILL_TOOL_NAME = "ha_get_skill_guide"
+
 # Description for the unified search tool
 SEARCH_TOOL_DESCRIPTION = (
     "Search ALL Home Assistant tools by ENGLISH keyword. Each hit is "

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/settings_ui/_handlers_advanced.py

@@ -88,7 +88,7 @@ def _advanced_field_row(
         _ADVANCED_SETTINGS_SENTINELS,
         OAUTH_MODE_TOKEN,
     )
-    from ..config_registry import ADVANCED_RESTART_REQUIRED
+    from ..config_registry import ADVANCED_MULTILINE, ADVANCED_RESTART_REQUIRED
 
     origin = _origin_for_advanced_field(env_name, overrides=overrides)
     value: Any = getattr(settings, fname, None)
@@ -122,6 +122,8 @@ def _advanced_field_row(
     choices = _ADVANCED_SETTINGS_CHOICES.get(fname)
     if choices is not None:
         row["choices"] = list(choices)
+    if fname in ADVANCED_MULTILINE:
+        row["multiline"] = True
     return row
 
 

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/settings_ui/_tools_meta.py

@@ -18,6 +18,7 @@ import logging
 from collections.abc import Iterable
 from typing import TYPE_CHECKING, Any, NamedTuple, NotRequired, TypedDict
 
+from ..server_tool_text import SKILL_TOOL_NAME
 from ..transforms import categorize_capability
 
 if TYPE_CHECKING:
@@ -116,7 +117,7 @@ MANDATORY_TOOLS: set[str] = {
 # _save_feature_flags) so each direction of the conflict gets an
 # actionable error.
 BPS_MANDATORY_TOOLS: set[str] = {
-    "ha_get_skill_guide",
+    SKILL_TOOL_NAME,
 }
 
 

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/settings_ui/locales/de.json

@@ -472,6 +472,8 @@
     "advanced.dashboard_screenshot_engine_url.help": "Basis-URL der Screenshot-Engine. Lasse leer für Supervisor-Auto-Discovery. Wirkt sofort.",
     "advanced.enable_websocket.label": "WebSocket aktivieren",
     "advanced.enable_websocket.help": "WebSocket-Zustandsüberwachung. Das Deaktivieren fällt auf Polling zurück und beeinträchtigt viele Tools.",
+    "advanced.custom_instructions.label": "Eigene Server-Anweisungen",
+    "advanced.custom_instructions.help": "Text, den jeder verbundene KI-Assistent als Teil der MCP-Server-Anweisungen erhält – zum Beispiel, wo Notizen zum Haushalt liegen und wann sie gelesen oder aktualisiert werden sollen. Auch Teil des Prompts von Home-Assistant-Sprachassistenten (Assist), die dieses Toolset nutzen. Gedacht für Hinweise, die alle deine Clients auf einmal erreichen sollen; halte ihn kurz und ohne Geheimnisse. Leer lassen, um nichts hinzuzufügen. Erfordert einen Neustart; Clients sehen die Änderung nach dem erneuten Verbinden.",
     "advanced.enabled_tool_modules.label": "Aktivierte Tool-Module",
     "advanced.enabled_tool_modules.help": "Kommagetrennte Modulnamen oder 'all'.",
     "advanced.enable_dashboard_partial_tools.label": "Dashboard-Partial-Update-Tools",

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/settings_ui/locales/en.json

@@ -472,6 +472,8 @@
     "advanced.dashboard_screenshot_engine_url.help": "Base URL of the screenshot engine. Leave blank for Supervisor auto-discovery. Applies immediately.",
     "advanced.enable_websocket.label": "Enable WebSocket",
     "advanced.enable_websocket.help": "WebSocket state monitoring. Disabling falls back to polling and degrades many tools.",
+    "advanced.custom_instructions.label": "Custom server instructions",
+    "advanced.custom_instructions.help": "Text sent to every AI assistant that connects, as part of the MCP server instructions — for example where household notes are kept and when to read or update them. Also part of the prompt of Home Assistant conversation agents (Assist) that use this toolset. Use it for guidance that should reach all your clients at once; keep it short and free of secrets. Leave empty to add nothing. Requires restart; clients see the change when they reconnect.",
     "advanced.enabled_tool_modules.label": "Enabled tool modules",
     "advanced.enabled_tool_modules.help": "Comma-separated module names, or 'all'.",
     "advanced.enable_dashboard_partial_tools.label": "Dashboard partial-update tools",

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/settings_ui/settings_js/08_advanced.js

@@ -136,6 +136,8 @@ function renderAdvancedSection(containerId, fields) {
         (f.max !== undefined ? `max="${f.max}" ` : '') +
         (f.type === 'float' ? 'step="0.1" ' : '') +
         (f.editable ? '' : 'disabled') + '>';
+    } else if (f.multiline) {
+      controlHtml = `<textarea rows="4" name="adv:${escapeHtml(f.field)}" data-adv-field="${escapeHtml(f.field)}" aria-labelledby="label-adv-${escapeHtml(f.field)}" ${f.editable ? '' : 'disabled'}>${escapeHtml(String(f.value ?? ''))}</textarea>`;
     } else {
       // str
       controlHtml = `<input type="text" name="adv:${escapeHtml(f.field)}" data-adv-field="${escapeHtml(f.field)}" aria-labelledby="label-adv-${escapeHtml(f.field)}" value="${escapeHtml(String(f.value ?? ''))}" ${f.editable ? '' : 'disabled'}>`;

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/tools/bug_report_config.py

@@ -40,6 +40,12 @@ def collect_config_toggles(settings: Settings) -> dict[str, Any]:
             [item for item in raw.split(",") if item.strip()]
         )
 
+    # Presence only: the text is the owner's and may be personal.
+    custom = getattr(settings, "custom_instructions", "")
+    toggles["custom_instructions_set"] = bool(
+        isinstance(custom, str) and custom.strip()
+    )
+
     toggles.update(_tool_config_diagnostics(settings))
     return toggles
 

{ha_mcp_dev-8.7.0.dev3045 → ha_mcp_dev-8.7.0.dev3050}/src/ha_mcp/tools/tools_dev.py

@@ -164,7 +164,8 @@ def _apply_policy_guard_row_locks(fname: str, row: dict[str, Any]) -> None:
     see ``editable: true`` on rows whose set/reset the guards refuse:
     ``enable_tool_security_policies`` while access is off, and
     ``dev_tools_security_policy_access`` plus
-    ``enable_security_policy_tool`` always (web UI / env var only).
+    ``enable_security_policy_tool`` and ``custom_instructions`` always
+    (web UI / env var only).
     A row that is ALREADY non-editable (env-pinned) keeps its plain env
     story: the pin refuses the write before these guards would, and
     stamping a policy reason there would misdirect the fix toward the
@@ -181,7 +182,7 @@ def _apply_policy_guard_row_locks(fname: str, row: dict[str, Any]) -> None:
             row["editable"] = False
             row["locked_reason"] = "web_ui_or_env_only"
         row["value"] = _security_policy_access_enabled()
-    elif fname == "enable_security_policy_tool":
+    elif fname in _HUMAN_ONLY_SETTINGS:
         if row["editable"]:
             row["editable"] = False
             row["locked_reason"] = "web_ui_or_env_only"
@@ -215,48 +216,46 @@ def _require_security_policy_access(operation: str) -> None:
     )
 
 
+# Settings dev tools may never write, in either direction, with the refusal
+# message and where a human changes them instead.
+_HUMAN_ONLY_SETTINGS: dict[str, tuple[str, str]] = {
+    "enable_security_policy_tool": (
+        "it registers ha_manage_security_policy, which can rewrite the tool "
+        "security policies gating the agent.",
+        "Change it in the web settings UI (Tool Security Policies tab) or via "
+        "the ENABLE_SECURITY_POLICY_TOOL env var.",
+    ),
+    "dev_tools_security_policy_access": (
+        "it is the toggle governing their own access to tool security policies.",
+        "Change it in the web settings UI (Server Settings tab, Developer "
+        "section) or via the HAMCP_DEV_SECURITY_POLICY_ACCESS env var.",
+    ),
+    "custom_instructions": (
+        "its text is sent to every connected agent as server instructions.",
+        "Change it in the web settings UI (Server Settings tab, Advanced) or "
+        "via the HAMCP_CUSTOM_INSTRUCTIONS env var.",
+    ),
+}
+
+
 def _guard_security_policy_setting(setting: str) -> None:
     """Gate set/reset of the settings that define the dev tools' leash.
 
-    ``dev_tools_security_policy_access`` is refused unconditionally — even
-    with access ON — so the agent can neither grant itself policy access
-    nor revoke it; that toggle belongs to the web settings UI and the env
-    var alone. ``enable_security_policy_tool`` gets the same unconditional
-    refusal: it registers ha_manage_security_policy, which can rewrite the
-    policies gating the agent, and its toggle belongs to the Tool Security
-    Policies tab (issue #2148) — a dev-tools write would reach the same
-    end state as unbuckling the leash, one restart later.
-    ``enable_tool_security_policies`` is the whole gating engine's master
-    switch, so writing it needs access.
+    ``_HUMAN_ONLY_SETTINGS`` are refused even with access ON: the agent may
+    neither grant nor revoke its own policy access, nor register
+    ha_manage_security_policy (#2148; the same end state as unbuckling the
+    leash, one restart later), nor rewrite the text steering every agent.
+    ``enable_tool_security_policies`` is the gating engine's master switch,
+    so writing it needs access.
     """
-    if setting == "enable_security_policy_tool":
-        raise_tool_error(
-            create_error_response(
-                ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
-                "'enable_security_policy_tool' cannot be changed by dev "
-                "tools: it registers ha_manage_security_policy, which can "
-                "rewrite the tool security policies gating the agent.",
-                context={"setting": setting},
-                suggestions=[
-                    "Change it in the web settings UI (Tool Security "
-                    "Policies tab) or via the ENABLE_SECURITY_POLICY_TOOL "
-                    "env var.",
-                ],
-            )
-        )
-    if setting == "dev_tools_security_policy_access":
+    if setting in _HUMAN_ONLY_SETTINGS:
+        reason, where = _HUMAN_ONLY_SETTINGS[setting]
         raise_tool_error(
             create_error_response(
                 ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
-                "'dev_tools_security_policy_access' cannot be changed by dev "
-                "tools: it is the toggle governing their own access to tool "
-                "security policies.",
+                f"'{setting}' cannot be changed by dev tools: {reason}",
                 context={"setting": setting},
-                suggestions=[
-                    "Change it in the web settings UI (Server Settings tab, "
-                    "Developer section) or via the "
-                    "HAMCP_DEV_SECURITY_POLICY_ACCESS env var.",
-                ],
+                suggestions=[where],
             )
         )
     if setting == "enable_tool_security_policies":