[Tool] Add GrepTool - content search across files using ripgrep

[omatheusmesmo]

Motivation

The agent has no way to search file contents by regex pattern. Finding where a function is defined, locating configuration keys, or searching for a string across a codebase requires running grep via ShellTool, which is slower and less structured.

All three reference projects use ripgrep as the backend.

What the tool should do

Search file contents using regex patterns, returning matching lines with file paths and line numbers.

Reference implementations

opencode (TypeScript)

• Powered by ripgrep for fast native search
• Parameters: pattern (regex), path (directory/file), include (file glob filter), limit
• Relative path output
• Truncation indicator when results are capped

hermes-agent (Python)

• Uses ripgrep (rg) when available, falls back to grep
• Content search (regex) or file listing mode
• Path-grouped compact output for many matches
• Pagination support

openclaw (TypeScript)

• Automatic ripgrep download via ensureTool()
• Respects .gitignore
• Parameters: pattern, path, glob, ignoreCase, literal, context (context lines), limit (default 100)

Requirements

1. Regex search - Full regex syntax support
2. File glob filter - Optional include pattern (e.g. *.java)
3. Path targeting - Search in specific directory or file
4. Case insensitive mode - Optional flag
5. Literal mode - Optional flag to disable regex (search exact string)
6. Context lines - Show N lines before/after each match
7. Limit - Max number of results (default 100)
8. Respect .gitignore - Skip ignored files
9. Workspace confinement - Must respect workspace root

Suggested location

client/runtime/src/main/java/dev/omatheusmesmo/qlawkus/tool/shell/GrepTool.java

Dependencies

• ripgrep (rg) binary preferred, fall back to system grep

Config properties

• qlawkus.shell.grep.enabled (boolean, default true)
• qlawkus.shell.grep.max-results (int, default 100)
• qlawkus.shell.grep.prefer-ripgrep (boolean, default true)