# Grep agent guide
This engine performs bounded content search; the parent owns tool routing and path settings.
## Where to look
- `engine.rs`: traversal, ranking, pagination, context, and budget accounting.
- `matcher.rs`: case-sensitive regex compilation, syntax adjustments, and literal fallback.
- `reader.rs`: bounded regular-file reads and recoverable file races.
- `mod.rs`: provider content and scan metadata.
- `../tests/grep_search.rs`: tool-level pagination and output-cap regressions.
## Local contracts
- Patterns use OR semantics. Invalid regex syntax can be adjusted or fall back to a literal; preserve the adjustment/fallback counters rather than treating every compile failure as fatal.
- Ranked mode groups by file and caps primary matches per file. Raw mode orders path/line records and uses one extra primary match to establish pagination.
- Pagination counts primary matching lines, not context rows; preserve that distinction in `limit`, `offset`, `next_offset`, and the `has_more` flag.
- Report budget-limited scans separately from an intentional raw-pagination stop. Do not claim an exhaustive result when traversal, bytes, time, or output was capped.
- The reader distinguishes per-file prefix truncation from invocation-wide byte exhaustion. Preserve both signals in the engine.
- Non-regular files are skipped; disappeared/unreadable files have a separate recoverable outcome. Do not turn these into empty successful reads.
- Keep ignore/hidden/binary filtering, cancellation, deterministic raw ordering, and bounded context covered when changing traversal or rendering.