No Ls Bash Listing

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

┌─────────────────────────────────────────────────────────────┐
│                 Directory Listing Comparison                │
│                                                             │
│  Shell Subprocess `ls -la` (185 Tokens / 450ms):            │
│  drwxr-xr-x  14 asus  staff   448 Aug 22 17:50 .            │
│  drwxr-xr-x   6 asus  staff   192 Aug 22 16:30 ..           │
│  -rw-r--r--   1 asus  staff  1645 Aug 22 17:45 README.md    │
│  -rw-r--r--   1 asus  staff  5006 Aug 22 17:48 rule.md      │
│  ↳ 185 tokens billed on Unix permissions and timestamps     │
│                                                             │
│  Native `list_dir` Tool (42 Tokens / 1ms - 77.3% Cut!):     │
│  {"name":"README.md","sizeBytes":"1645"}                    │
│  {"name":"rule.md","sizeBytes":"5006"}                      │
│  ↳ 42 clean tokens, instant cross-platform parsing          │
└─────────────────────────────────────────────────────────────┘

The 3 Architectural Advantages of Native list_dir

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. CROSS-PLATFORM DETERMINISM: Identical JSON output on Windows & Linux   │
│ 2. SUB-MILLISECOND VELOCITY: Direct memory/inode access (Zero PTY spawns) │
│ 3. ZERO PERMISSION NOISE: Eliminates UID, GID, and rwx permission strings │
└───────────────────────────────────────────────────────────────────────────┘

Tool Invocation Standard

When listing files in a target directory:

{
  "DirectoryPath": "c:/Users/ASUS/Documents/Newfolder/Antigravity/Major AI Skills/src",
  "toolAction": "Listing source directory contents",
  "toolSummary": "Directory Listing"
}

Benchmark Comparison

Listing 50 files across 10 project subdirectories:

Agent Operational Directive

MANDATORY: Agents must NEVER run ls, dir, or Get-ChildItem via terminal execution tools (run_command). Always call the dedicated native list_dir tool for filesystem exploration.