fix: expand ~ in fs tools, accept absolute glob patterns, add find_files

Spiral-fix triggered by 2026-04-27 GraphRecursionError(50): the agent
tried to locate a file under ~/code/Orbit-Daily, but read_file/ls/grep/
glob_files all passed tilde paths through unchanged, and Path.glob
rejects absolute patterns ("Non-relative patterns are unsupported"),
so the model burned its budget on manual ls tree-walking.

- expanduser on read_file, ls, grep, glob_files (write_file's sandbox
boundary intentionally still rejects absolute/escape paths).
- glob_files now uses stdlib glob.glob(recursive=True), which handles
absolute patterns and ** natively.
- New find_files tool shells out to unix `find -name` (30s timeout,
capped results) for fast deep search by filename.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/lilith_agent/tools/__init__.py

@@ -11,6 +11,7 @@ from lilith_agent.tools.files import (
     ls as _ls,
     grep as _grep,
     glob_files as _glob_files,
+    find_files as _find_files,
     write_file as _write_file
 )
 from lilith_agent.tools.todos import (
@@ -91,6 +92,11 @@ def build_tools(cfg: Config) -> list[BaseTool]:
         """Find files matching a glob pattern (e.g., '**/*.csv')."""
         return _glob_files(pattern)
 
+    @tool
+    def find_files(name: str, root: str = ".", max_results: int = 200) -> str:
+        """Locate files by name under `root` using unix `find` (fast deep search). Use this instead of walking with `ls` when looking for a known filename in a large tree."""
+        return _find_files(name, root=root, max_results=max_results)
+
     @tool
     def write_file(path: str, content: str) -> str:
         """Persist text to a file the user can open afterwards.
@@ -190,6 +196,7 @@ def build_tools(cfg: Config) -> list[BaseTool]:
         ls,
         grep,
         glob_files,
+        find_files,
         write_file,
         write_todos,
         mark_todo_done,

src/lilith_agent/tools/files.py

@@ -1,4 +1,6 @@
-import fnmatch
+import glob as _glob
+import os
+import subprocess
 from pathlib import Path
 from typing import Optional
 
@@ -54,7 +56,7 @@ def read_file(
     Reads a file with optional line-based chunking.
     Used to prevent context overflow for large files.
     """
-    p = Path(path)
+    p = Path(os.path.expanduser(path))
     if not p.exists():
         return f"ERROR: File {path} does not exist."
     if not p.is_file():
@@ -102,7 +104,7 @@ def read_file(
 
 def ls(path: str = ".") -> str:
     """List contents of a directory."""
-    p = Path(path)
+    p = Path(os.path.expanduser(path))
     if not p.exists():
         return f"ERROR: Path {path} does not exist."
     if not p.is_dir():
@@ -120,7 +122,7 @@ def ls(path: str = ".") -> str:
 
 def grep(pattern: str, path: str, ignore_case: bool = True) -> str:
     """Search for a pattern in a file and return matching lines with line numbers."""
-    p = Path(path)
+    p = Path(os.path.expanduser(path))
     if not p.exists():
         return f"ERROR: File {path} does not exist."
     
@@ -144,21 +146,43 @@ def grep(pattern: str, path: str, ignore_case: bool = True) -> str:
 
 def glob_files(pattern: str, root_dir: str = ".") -> str:
     """Find files matching a glob pattern."""
-    p = Path(root_dir)
+    pattern = os.path.expanduser(pattern)
+    root_dir = os.path.expanduser(root_dir)
     try:
-        # Use rglob for recursive search if pattern starts with **/
-        if pattern.startswith("**/"):
-            matches = list(p.rglob(pattern[3:]))
+        if os.path.isabs(pattern):
+            matches = _glob.glob(pattern, recursive=True)
         else:
-            matches = list(p.glob(pattern))
-            
+            matches = _glob.glob(pattern, root_dir=root_dir, recursive=True)
+
         if not matches:
             return "No files found matching the pattern."
-        return "\n".join(str(m) for m in sorted(matches))
+        return "\n".join(sorted(matches))
     except Exception as e:
         return f"ERROR globbing {pattern}: {e}"
 
 
+def find_files(name: str, root: str = ".", max_results: int = 200) -> str:
+    """Locate files by name under `root` using unix `find`. Fast deep search."""
+    root = os.path.expanduser(root)
+    if not Path(root).exists():
+        return f"ERROR: Path {root} does not exist."
+    try:
+        result = subprocess.run(
+            ["find", str(root), "-name", name],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        lines = [ln for ln in result.stdout.splitlines() if ln]
+        if not lines:
+            return "No files found."
+        return "\n".join(lines[:max_results])
+    except subprocess.TimeoutExpired:
+        return "ERROR: find timed out (>30s)."
+    except Exception as e:
+        return f"ERROR: {e}"
+
+
 def write_file(path: str, content: str) -> str:
     """Write content to a file inside the sandboxed write root.
 

tests/test_files.py

@@ -1,10 +1,20 @@
 from __future__ import annotations
 
+import os
 from pathlib import Path
 
 import pytest
 
-from lilith_agent.tools.files import _resolve_safe_write_path, set_write_root, write_file
+from lilith_agent.tools.files import (
+    _resolve_safe_write_path,
+    find_files,
+    glob_files,
+    grep,
+    ls,
+    read_file,
+    set_write_root,
+    write_file,
+)
 
 
 def test_relative_path_inside_root_is_allowed(tmp_path: Path):
@@ -50,3 +60,65 @@ def test_write_file_outside_root_returns_error_without_writing(tmp_path: Path):
     result = write_file(str(target), "hello")
     assert result.startswith("ERROR")
     assert not target.exists()
+
+
+def test_ls_expands_tilde(monkeypatch, tmp_path: Path):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    (tmp_path / "marker.txt").write_text("x")
+    out = ls("~")
+    assert "marker.txt" in out
+
+
+def test_read_file_expands_tilde(monkeypatch, tmp_path: Path):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    (tmp_path / "note.md").write_text("hello goddess")
+    out = read_file("~/note.md")
+    assert "hello goddess" in out
+
+
+def test_grep_expands_tilde(monkeypatch, tmp_path: Path):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    (tmp_path / "lore.txt").write_text("The She\nDemiurge\n")
+    out = grep("She", "~/lore.txt")
+    assert "The She" in out
+
+
+def test_glob_files_expands_tilde(monkeypatch, tmp_path: Path):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    (tmp_path / "a.lol").write_text("")
+    (tmp_path / "sub").mkdir()
+    (tmp_path / "sub" / "b.lol").write_text("")
+    out = glob_files("~/**/*.lol")
+    assert "a.lol" in out
+    assert "b.lol" in out
+
+
+def test_glob_files_accepts_absolute_pattern(tmp_path: Path):
+    (tmp_path / "莉莉丝女神.lol").write_text("")
+    (tmp_path / "deep").mkdir()
+    (tmp_path / "deep" / "莉莉丝女神.lol").write_text("")
+    out = glob_files(f"{tmp_path}/**/莉莉丝女神.lol")
+    assert "莉莉丝女神.lol" in out
+    assert "deep" in out
+
+
+def test_find_files_locates_by_name(tmp_path: Path):
+    (tmp_path / "a").mkdir()
+    (tmp_path / "a" / "target.txt").write_text("")
+    (tmp_path / "b").mkdir()
+    (tmp_path / "b" / "other.md").write_text("")
+    out = find_files("target.txt", str(tmp_path))
+    assert "target.txt" in out
+    assert "other.md" not in out
+
+
+def test_find_files_expands_tilde(monkeypatch, tmp_path: Path):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    (tmp_path / "needle.lol").write_text("")
+    out = find_files("needle.lol", "~")
+    assert "needle.lol" in out
+
+
+def test_find_files_missing_root_errors(tmp_path: Path):
+    out = find_files("anything", str(tmp_path / "does_not_exist"))
+    assert out.startswith("ERROR")