feat: pinpoint backslash-escape mistake in python_sandbox errors

[Patch76]

What does this PR do?

Closes #1197.

When an agent emits \" outside a Python string literal in a python_transform, Python's parser reports "unexpected character after line continuation character" — a message that doesn't pinpoint the actual mistake (backslash before quote). format_sandbox_error now detects that exact substring and prepends a specific recovery hint, so agents fix it on the first retry instead of guessing.

Same precedent as #1163 (feat: for python_transform error-UX).

tools_config_scenes.py previously built its own ad-hoc suggestions list instead of calling format_sandbox_error, so the new hint wouldn't reach ha_config_set_scene callers. Migrated to the shared helper in this PR — the user-visible fix is incomplete without it.

Type of change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• 🔧 Maintenance/refactor
• 🧪 Tests only
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest)
• Code follows style guidelines (uv run ruff check)

Future improvements

Checklist

• I have updated documentation if needed

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request improves the developer experience for LLM agents interacting with the python_transform sandbox. By detecting common backslash-escape mistakes that trigger misleading Python parser errors, the system now provides actionable feedback to help agents correct their syntax on the first retry. Additionally, it standardizes error reporting by migrating existing ad-hoc logic to a centralized helper function.

Highlights

• Improved Error UX: Added a specific recovery hint to format_sandbox_error for Python syntax errors caused by incorrect backslash-escaping (e.g., \") outside of string literals.
• Code Migration: Migrated ha_config_set_scene to use the shared format_sandbox_error helper, ensuring consistent error messaging across configuration tools.
• Test Coverage: Added unit tests to verify that the new diagnostic hint is correctly prioritized and that it handles variable-name context appropriately.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request enhances the error feedback mechanism for Python sandbox execution by introducing a specialized error formatter. It updates the ha_config_set_scene tool to utilize format_sandbox_error, which now detects and provides specific guidance for syntax errors related to unexpected line continuation characters—a common issue when agents attempt to escape quotes unnecessarily. The changes include comprehensive unit tests to ensure correct suggestion prioritization and formatting. I have no feedback to provide as no review comments were submitted.

[Patch76]

Implementation Summary

Choices Made:

• Substring match on "line continuation character" in format_sandbox_error — Python 3.13's parser emits this exact phrase consistently for \X (backslash before non-newline) outside a string literal. Tighter than parsing the SyntaxError offset/lineno, and robust to user-input line-number drift.
• insert(0, ...) placement inside the else: branch, BEFORE the existing variable_name != "config" prepend — the variable-name hint stays at index 0 for non-config callers (addons passing variable_name="response"), and the line-continuation hint lands at index 1. Order: target-variable framing first, diagnostic second. Locked in by test_line_continuation_with_response_variable_orders_correctly.
• Scenes migration in the same PR (Boy-Scout) — tools_config_scenes.py was the only outlier among the five safe_execute* callers (dashboards/automations/scripts/addons already route through format_sandbox_error). Without migration, the new hint wouldn't reach ha_config_set_scene — making the user-visible fix incomplete in that path.
• feat: prefix per feat: broaden python_transform AST allowlist + improve error UX #1163 precedent — same file (python_sandbox.py), same class of change ("improve error UX"). Issue [AGENT] Error calling tool server.py:1242 'ha_config_set_dashboard': {... #1197 is bug-labelled, but the change is additive (new suggestion text), not a behaviour-correction. fix: would have been defensible too; the direct precedent decided it.
• Hint text frames the JSON wire layer explicitly — agents commonly assume they need Python-level \" escapes inside python_transform, mirroring JSON wire syntax. The hint reframes this: JSON wire already escapes the quotes; Python source receives the decoded " directly.

Problems Encountered:

• None during implementation.

Suggested Improvements:

• Additional format_sandbox_error recovery hints could be added as similar bug reports surface — unmatched '<bracket>' and expected ':' after dict key are the most likely next patterns. Defer until bug-report evidence rather than guessing at which agent mistakes are common.

[kingpanther13]

Two test gaps worth closing, plus a few small things while you're in there.

Requested changes

1. Scene-tool error path is untested. The migration to format_sandbox_error in ha_config_set_scene is behaviorally unverified — tests/src/e2e/workflows/scenes/test_lifecycle.py is happy-path only. Add a test (e2e or unit-level on the tool) that invokes ha_config_set_scene with a malformed python_transform like 'config["k"] = \"v\"' and asserts the response carries the new hint plus ErrorCode.VALIDATION_FAILED. Without it, the suggestion-shape change (4 → 5 items, ordering) isn't covered at the tool wiring.

2. Negative test for the substring match. TestFormatSandboxError covers the positive case in both orderings but never asserts the hint is absent for unrelated PythonSandboxValidationError messages. If someone later broadens the substring (e.g. to "continuation"), the regression slides through. One assertion added to an existing non-matching test (test_validation_error_uses_validation_phrasing or similar) is enough.

While you're in there

• Hint prose is dense (python_sandbox.py:482-487). 50-word single sentence joined by em-dashes and semicolons; other entries in the same suggestions array are short imperative fragments. Something like "Remove the leading backslash before quotes — write \"foo\" not \\\"foo\\\" in the Python source." reads closer to the rest.
• Drop the Issue #1197 — prefix from the code comment at python_sandbox.py:475 and the two test docstrings at test_python_sandbox.py:731, 758. The bodies stand on their own; the issue tag becomes a dangling pointer once #1197 closes.
• The reformat at tools_config_scenes.py:653-656 is pure black/ruff and unrelated to the feat — fine to keep, just noting it.

Verified the substring "line continuation character" is the canonical CPython phrasing (Python 3.13: emits exactly that for \" outside string literals; legitimate trailing-backslash continuation produces "invalid syntax" instead, so no false-positive risk). Migration preserves the Expression: truncation. No silent failures introduced.

[Patch76]

Round-2 fixes pushed. Walkthrough of each item from the review:

Requested changes

1. Scene-tool error path test. New test_transform_backslash_escape_surfaces_specific_hint in tests/src/unit/test_tools_config_scenes.py invokes tools.ha_config_set_scene(scene_id="test_scene", python_transform='config["entities"]["light.kitchen"] = \\"v\\"', config_hash=seed_hash) and asserts: (a) ToolError raised, (b) error_data["error"]["code"] == "VALIDATION_FAILED", (c) any("backslash" in s.lower() for s in suggestions). Setup mirrors test_transform_runtime_keyerror_surfaces_tool_error, so the call routes through safe_execute → PythonSandboxError → format_sandbox_error → raise_tool_error at tools_config_scenes.py:573-587.

2. Negative substring test. Added assert not any("backslash" in s.lower() for s in suggestions) to test_validation_error_suggestions_point_at_syntax. The test calls format_sandbox_error with PythonSandboxValidationError("Forbidden node type: Try") — message lacks the line-continuation phrase, so the negative branch is genuinely exercised. A future substring broadening (e.g. to "continuation") would fail here.

"While you're in there"

• Hint prose rewrite: replaced with the suggested imperative fragment — 'Remove the leading backslash before quotes — write "foo" not \\"foo\\" in the Python source.'. Updated the three existing "line-continuation" test-assertion substrings to "backslash" so they continue to match the new prose; the parser-emitted "line continuation character" phrase the detector triggers on is unchanged.

• Drop Issue #1197 — prefix: dropped from the code comment in python_sandbox.py and the test docstring in test_python_sandbox.py. The third anchor in the review (test_python_sandbox.py:758) didn't have an Issue #1197 reference — grep confirms only one occurrence existed in the test file before the edit.

• tools_config_scenes.py:653-656 reformat: kept as-is per the "fine to keep, just noting it" call.

Note on test_tools_config_scenes.py formatting

ruff format swept ~50 lines of pre-existing trailing-comma and line-continuation drift in neighbouring blocks while landing the new R1 test (TestEmptySceneIdGuard, TestCategoryValidationGate, TestPythonTransformIdNoneRebind, TestSmartSearchSceneIdFallbackPaths). Same shape as the :653-656 note in the review — pure ruff, unrelated to the feature. Revertable on request.

[kingpanther13]

R1 items all addressed cleanly:

• Scene-tool error path is now exercised end-to-end via test_transform_backslash_escape_surfaces_specific_hint — full routing through safe_execute → PythonSandboxError → format_sandbox_error → raise_tool_error is covered.
• Negative substring assertion in test_validation_error_suggestions_point_at_syntax will flip if the line-continuation detector ever broadens.
• Hint prose is now a tight imperative fragment matching the rest of the suggestions array.
• Issue #1197 — prefix dropped from both anchors that carried it.

Re ruff sweep in test_tools_config_scenes.py: I reviewed every reflow — pure formatter noise (trailing-comma reflows, one list-comprehension/with wrap). No assertions, mocks, or test names altered. Keep as-is.

LGTM.

[github-actions]

🧪 Your changes are now in the dev channel!

Your PR has been merged to master and is available for testing in the dev channel.

Test your changes before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

Found an issue? Please open a new bug report and mention this PR for context.