docs: clarify search_files newline regex behavior

[andressommerhoff]

Summary

• Clarifies that search_files content search is line-oriented.
• Warns not to include \n in regex patterns, even inside alternation.
• Points users to the context option for inspecting neighboring lines instead.

Background

This was drafted by Hermes at Andres' request after Hermes hit a real failure while working on the QS project from WSL on Windows: search_files failed to find text that was present in a file when the regex alternation included a newline alternative, while direct grep found the text. Removing only the \n alternative made search_files work again.

Test Plan

• python -m py_compile tools/file_tools.py

[andressommerhoff]

Follow-up from the QS/WSL reproduction: I’m concerned that putting this caveat in the tool schema may pollute the prompt with a narrow exception. I’m going to work on a functional fix instead, likely in the search content path, so Hermes only gets a clear warning when it actually attempts to use a newline pattern with search_files.

[tonydwb]

Code Review Summary

Verdict: Approved

Docs-only change clarifying search_files newline regex behavior. 1-line diff, no concerns.

---

Reviewed by Hermes Agent

[andressommerhoff]

Updated with a follow-up commit instead of force-pushing.

This now replaces the schema-only note with a functional fix:

• Restores the original search_files schema description.
• Adds a SearchResult warning field.
• In _search_content(), detects zero-result searches involving newline regex patterns and explains that search_files is line-oriented and does not call rg with -U/--multiline.
• Keeps literal backslash+n searches (even backslashes, e.g. \n) from warning.

Validation:

• venv/bin/python -m pytest tests/tools/test_search_error_guard.py -q => 25 passed
• QS/WSL manual reproduction: the problematic Tipo:\n OR now returns 0 results with a warning; valid single-line patterns still find Tipo: at line 3054.

[teknium1]

Merged via PR #49944 (docs salvage cluster 2). Your commit was cherry-picked onto current main with your authorship preserved in git log — rebase-merged so it lands under your name. Thanks for the contribution!