# Grep agent guide
Bounded content search lives here; the parent owns routing and path policy.
## Where to look
- `engine.rs`: traversal, ranking, pagination, context, and scan budgets.
- `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. Preserve regex adjustment and literal-fallback counters; not every compile failure is fatal.
- Ranked mode groups by file and caps primary matches per file. Raw mode sorts path/line records and uses one extra primary match to establish pagination.
- `limit`, `offset`, `next_offset`, and `has_more` count primary matching lines, not context rows. Output caps can prevent selected matches from being emitted; pagination must account for returned matches.
- Distinguish intentional raw lookahead from budget exhaustion. `scan_complete` can be true after lookahead, while `matches_seen_exact` is false; it does not mean the entire tree was searched.
- Report traversal, per-file bytes, total scan bytes, file count, deadline, read errors, and output limits without claiming exhaustive results when capped.
- Keep per-file prefix truncation separate from invocation-wide byte exhaustion in reader outcomes and engine metadata.
- Skip non-regular files. Disappeared or unreadable files have a separate recoverable outcome, not an empty successful read.
- Preserve ignore/hidden/binary filtering, cancellation, deterministic raw ordering, and bounded context when changing traversal or rendering.