Structured Native File Listing Protocol (list_dir over Shell ls/dir)

Overview

When exploring project directories, naive agents frequently spawn terminal subshells to execute Unix or Windows listing commands (run_command("ls -la") or run_command("dir")).

Executing shell ls/dir commands causes three major system degradations:

1. Unstructured Output & Token Waste: ls -la emits Unix file permissions, UID/GID owner strings, link counts, and timestamps (-rwxr-xr-x 1 root staff 4096 Aug 22 17:50), wasting 75% of tokens on metadata irrelevant to software engineering tasks.
2. Heavy Subprocess Latency: Spawning an interactive subshell (PowerShell/Bash) takes 300 to 800 milliseconds, whereas native IDE filesystem APIs execute in sub-millisecond memory calls.
3. Cross-Platform Failure Modes: Hardcoding ls -la fails or produces formatting errors when running on Windows PowerShell environments.

The Structured Native File Listing Protocol directs agents to use native list_dir tools, returning compact, structured JSON payloads directly from the IDE's virtual filesystem.

Shell ls -la Dump vs. Structured list_dir Payload