fix: keep file-search count aligned with accessible results

[grtninja]

Summary

• keep file-search count consistent with the number of files the tool actually returns
• keep the SSE file-list payload total consistent with the list actually included in the event
• add focused regression coverage for both the tool result and the UI event packaging

Why

Fixes #594. The current contract can report more file-search results than the tool payload and UI event actually expose, which makes the UI claim files that are not accessible from the returned list.

Validation

• PYTHONPATH=src python -m pytest -q tests\\unit\\test_file_tools.py::test_search_file_count_matches_returned_files
• PYTHONPATH=src python -m pytest -q tests\\unit\\chat\\ui\\test_sse_handler.py -k file_list_limited_to_20

Risk Notes

• narrow result-contract fix only
• no auth, routing, or model behavior changes
• no overlap with the active ChatView/code-index PR surfaces

[kovtcharov]

@claude review PR.

[github-actions]

Claude finished @kovtcharov's task —— View job

---

PR Review: LGTM 🟢

Summary: Clean, minimal fix that correctly aligns count/total fields with the actual returned file lists.

---

Code Review

file_tools.py ✅

• Correctly introduces limited_files = matching_files[:10] and uses it consistently for files, file_list, count, and display_message
• Applied in both the quick search (line 333) and deep search (line 388) code paths
• Comment clarifies intent without being verbose

sse_handler.py ✅

• Same pattern: limited_files = files[:20] before building the event
• total now reflects the actual payload size rather than data.get("count", ...) which could differ
• Clean, minimal change

Tests ✅

• test_search_file_count_matches_returned_files - Good regression test that creates 25 files, ensures 10 are returned, and validates count == 10
• test_file_list_limited_to_20 updated assertion - Properly reflects the new contract

---

🟢 Minor Observations (non-blocking)

1. Loss of "total found" visibility: The UI no longer knows how many files were actually found (e.g., "showing 10 of 25"). If this is desired UX, consider adding a separate total_found or truncated: true field in a follow-up.

2. Test fixture scope: search_file_fn uses scope="module" but modifies global _TOOL_REGISTRY. This works but could cause test coupling if other tests in the same module expect a clean registry. Consider scope="function" for isolation, or document the intentional sharing.

---

Verdict: Approve. The fix is correct, well-tested, and addresses the contract violation described in #594.

[kovtcharov]

Lint is failing on a Black formatting issue — one function signature is too long. Here's the fix:

-def test_search_file_count_matches_returned_files(search_file_fn, tmp_path, monkeypatch):
+def test_search_file_count_matches_returned_files(
+    search_file_fn, tmp_path, monkeypatch
+):

In tests/unit/test_file_tools.py line 759. You can also just run python util/lint.py --black --fix to auto-fix it.