What does this PR do?

Home Assistant entity discovery currently depends on GET /api/states. Some Home Assistant instances can return HTTP 500 for that endpoint when one integration exposes a state payload that HA cannot serialize for the REST response. When that happens, Hermes cannot list entities at all.

This PR keeps the normal /api/states behavior when it works, but falls back to Home Assistant's template API for 5xx responses. The fallback renders compact state records inside HA so Hermes can still discover entities and preserve domain/area filtering. 4xx errors are intentionally re-raised so auth, permission, and configuration problems remain visible.

Related Issue

No dedicated issue found. This is related to broader Home Assistant tooling robustness work.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• tools/homeassistant_tool.py
  • Reuses one headers dict for Home Assistant REST calls.
  • Catches aiohttp.ClientResponseError from /api/states.
  • Re-raises <500 errors so auth/config failures are not masked.
  • Falls back on >=500 errors to POST /api/template.
  • Uses a fixed Jinja template to render compact state records with entity_id, state, friendly_name, and area.
  • Passes fallback results through the existing _filter_and_summarize() path.
• tests/tools/test_homeassistant_tool.py
  • Adds regression coverage for the 5xx fallback path.
  • Verifies the fallback calls /api/template after /api/states fails.
  • Verifies the template request body.
  • Verifies domain and area filtering still work on fallback results.

How to Test

1. Run the Home Assistant tool tests:

   scripts/run_tests.sh tests/tools/test_homeassistant_tool.py

2. Run lint for the changed files:

   venv/bin/python -m ruff check tools/homeassistant_tool.py tests/tools/test_homeassistant_tool.py

3. Run the Windows compatibility footgun scan for the changed files:

   venv/bin/python scripts/check-windows-footguns.py tools/homeassistant_tool.py tests/tools/test_homeassistant_tool.py

Verified locally:

scripts/run_tests.sh tests/tools/test_homeassistant_tool.py
# 69 tests passed, 0 failed

venv/bin/python -m ruff check tools/homeassistant_tool.py tests/tools/test_homeassistant_tool.py
# All checks passed!

venv/bin/python scripts/check-windows-footguns.py tools/homeassistant_tool.py tests/tools/test_homeassistant_tool.py
# No Windows footguns found

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Linux 6.8.8-4-pve

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Not applicable. This is a backend tool behavior fix covered by tests.