feat: enrich search_files no-match results with directory listing (Closes #1486)

[Lexus2016]

Automated evolution PR for issue #1486.

Summary

When search_files returns zero results (valid pattern, no matches), the agent previously got a bare {total_count: 0} with no actionable info, causing blind retries (#1486: 95 file-not-found events/7d, 27-deep spirals observed).

Changes

• tools/file_tools.py: Added _build_no_match_hint() function that lists what does exist in the search directory (up to 10 entries, dirs first). Enriches the FIRST empty result with a _no_match_hint field containing the directory listing + a mode-specific recovery suggestion. The existing [FIX] search_files spiral cap not holding — 250 sessions, max 27 consecutive, regressed #1372 spiral detection (SWITCH STRATEGY after 3 consecutive misses) is preserved.
• tests/tools/test_file_tools.py: Added TestNoMatchHint class with 11 tests covering: directory listing, file-path handling, nonexistent paths, empty dirs, files vs content search mode, dotfile hiding, first-miss-only hint, spiral directive, and no-hint-when-results-exist.

Verification

• Lint: ruff check passes
• Tests: 11 new + 7 existing search tests all pass (18 total)
• Pre-PR test runner: PASSED

Closes #1486

[Lexus2016]

🤖 Evolution integration — autonomous merge blocked by policy

CI: ✅ fully green | Code review: ✅ passed (not dead code, solves #1486, no regression)

Reason not auto-merged: The deterministic merge gate (scripts/evolution_merge_gate.py) blocked this PR — the 308-line diff (94 impl + 208 tests) exceeds the 200-line autonomous self-merge cap. This is a safety policy, not a quality finding: the change itself looks sound. It needs a human review/sign-off to merge. The gate was not bypassed via --admin.

If a human approves and merges, the next integration cycle will pick up the self-update.

[Lexus2016]

🤖 Evolution Integration — blocked by merge-gate (DIFF_TOO_LARGE)

This PR passed all safety checks:

• ✅ CI fully green (0 fail, 0 pending)
• ✅ Branch evolution/issue-*, MERGEABLE/CLEAN
• ✅ Code review: _build_no_match_hint() has a real call site in search_tool() (not dead code)
• ✅ Mechanism solves [FIX] search_files file-not-found returns bare error — 95 misses/7d, distinct from covered parse-error bucket #1486 (enriches bare {total_count:0} with directory listing)
• ✅ No anti-regression ([FIX] search_files spiral cap not holding — 250 sessions, max 27 consecutive, regressed #1372 spiral detection preserved, tests added)
• ✅ No high-risk paths (only tools/file_tools.py + test file)
• ✅ Test-quality gate: passed
• ✅ Flip gate: N/A (skipped)

Blocked solely by: 308 changed lines exceed the 200-line autonomous self-merge cap. ~210 of those are test code (11 new tests). Leaving for human review per merge-gate policy. The production change is only ~98 lines.

All checks green — ready for manual merge.

[Lexus2016]

Code-review (evolution-integration, 2026-08-01): BLOCKED by autonomous merge gate (DIFF_TOO_LARGE: 248 changed lines > 200-line cap). Needs human review. (CI is fully green, 8 slices + e2e.)