agentlane/ docs
On this page

find

find_tool() exposes a find tool for file search by glob pattern.

Parameters:

  1. pattern: str
  2. path: str | None = None
  3. limit: int = 1000

Permissions

find resolves path from its captured cwd in the selected filesystem and checks ToolOperation.SEARCH_FILES before directory validation or traversal. A denied request returns:

permission denied: find is not allowed for `/workspace/private`

The bundled side-effect approval policy does not request approval for searches. A custom policy may still return require_approval, in which case the tool uses the configured approval_callback=.

approval required: find requires application approval for `/workspace` before execution

Example tool result:

Search directory: /workspace
README.md
docs/notes.md

Pattern semantics

Patterns use path-aware glob matching backed by wcmatch.glob. The matcher is compiled with GLOBSTAR | DOTMATCH | BRACE | IGNORECASE | FORCEUNIX, which means:

  • ** matches zero or more directory segments. Use **/ for recursive matches (*.py is not recursive — it matches only top-level files).
  • {a,b} brace expansion is supported (**/*.{ts,tsx}).
  • Matching is case-insensitive on every platform. This keeps results consistent across Linux (case-sensitive) and macOS / Windows (case-insensitive) filesystems.
  • Dotfiles (.env, .gitignore, etc.) are included unless ignored.
  • Only files are returned, never directories.
  • Leading ./ and / are stripped from the pattern, so /src/*.py and ./src/*.py both behave like src/*.py.

Examples:

**/*.py
**/*.{ts,tsx}
src/**/*.spec.ts

Search root, ordering, and traversal

By default path is the configured cwd. Result paths are relative to the resolved Search directory shown in the output. To read a result from another search directory, combine that directory and the result name. For example, Search directory: /library/docs with result guide.md gives the read path /library/docs/guide.md. The search does not change the read tool’s cwd.

Results are sorted by modification time, newest first, with ties broken alphabetically. This mirrors the ordering used by editor file pickers and is the most useful default for “what changed recently?” queries.

Symlinked directories are not followed during traversal. This avoids cycles and prevents pattern matching from escaping the search directory through symlinks.

find respects .gitignore files from the search root up to the nearest repository boundary and always skips .git/.

No-match and truncation

When no files match, the result includes the resolved search directory:

Search directory: /workspace
No files matched.

When more files match than the caller-provided limit (and limit is below the 1000 maximum), the result reports the total count and how to recover:

N files matched; returned first <limit>. Refine the pattern or raise `limit` (max 1000).

When the caller-provided limit is at or above the 1000 maximum and there are still more matches, the result tells the model the cap was hit:

N files matched; returned first 1000 (maximum). Refine the pattern or narrow `path`.

When the byte cap is reached, the result reports:

Output truncated at 51200 bytes; refine the pattern or narrow `path`.

The tool returns clear text errors for empty patterns, empty paths, invalid limits, and paths that do not resolve to a directory.

Injected Storage

Pass reader=storage with read, listing, and metadata capabilities. Paths use the reader’s namespace and cwd defaults to its root. Mounted readers accept rooted virtual paths; their displayed search directory is canonical and rooted. Plain injected readers retain relative POSIX syntax. Local and supplied filesystems use the same traversal, ignore matching, and result limits. Results sort by DirectoryEntry.modified_time, newest first; missing timestamps count as zero. Ties sort alphabetically. Directory symlinks are not followed. Permission requests use SEARCH_FILES with logical paths. See File I/O interfaces.

Traversal skips missing, non-directory, and permission-denied entries. Other listing failures return failed to find files; they do not produce empty or partial success results.