Structured Native Code Search Protocol (grep_search over Shell grep)

Overview

When searching a codebase for a function, type, or error string ("Where is validateJwtSession defined?"), naive agents execute terminal shell commands (run_command("grep -rn 'validateJwtSession' .")).

Spawning terminal shell grep commands introduces three major inefficiencies:

1. ANSI Formatting & Paging Pollution: Terminal output includes ANSI terminal escape codes, unstructured whitespace wrapping, and pager formatting that clutters the conversation context.
2. Match Flood Overflows: Shell grep has no built-in result cap. If a term matches 2,000 lines across build files, it dumps 50,000+ tokens into context in one shot.
3. Subprocess Spawn Latency: Initializing a shell subprocess takes 400ms+, whereas native IDE search tools execute in 5 milliseconds.

The Structured Native Code Search Protocol enforces the use of the native grep_search tool - returning clean, structured JSON with strict match ceilings and glob filtering.

Shell Subprocess grep -rn vs. Native grep_search Tool