Add compact search_file tool with local and remote filesystem support

[ADD-SP]

Summary

• Add the search_file tool for grouped, compact filesystem search results.
• Support local and remote execution through the exec-server filesystem APIs.

Historical replay indicates that search_file can replace approximately 73% of independent file searches while reducing their model-visible output by 26% on average.

Historical impact analysis

To estimate the impact of search_file, local Codex rollout history was replayed against the compact formatter. The analysis used ceil(UTF-8 bytes / 4) as the token approximation and excluded the current development session.

Corpus and replaceability

Metric	Result
History range	2026-07-15 – 2026-08-27
Sessions analyzed	571
User turns	6,491
Rollout data scanned	4.51 GB
Commands mentioning a search utility	55,730
Independent file-search calls	8,053
Confirmed replaceable with search_file	5,867
Replaceability among independent searches	72.9%
Calls with reliably replayable output	5,492
Measurable share of compatible calls	93.6%

An independent file search is a tool call containing one search operation without build/test/Git commands, dynamic shell control flow, command substitution, or result-processing pipelines such as awk, cut, xargs, or wc.

Model-visible output reduction

Metric	Existing shell search	search_file	Improvement
Aggregate output	6,989,018 tokens	5,164,965 tokens	1,824,053 tokens saved
Aggregate reduction	—	—	26.1%
Average saving per call	—	—	332 tokens
Median saving per call	—	—	44 tokens
P75 saving per call	—	—	286 tokens
P90 saving per call	—	—	1,075 tokens
Calls producing smaller output	—	—	70.8%

Savings by operation

Operation	Estimated output reduction
File listing	34.3%
Content search	26.0%

Path-prefix grouping and removal of shell wrapper output accounted for approximately 86.6% of the savings. The 300-character excerpt limit accounted for the remaining 13.4%.

No measured call depended on the 1,000-result limit or the 10K-token output limit to produce these savings; the measured reduction came from the compact representation itself rather than lossy truncation.

The remaining independent searches primarily used context flags such as -A/-B/-C, dynamic paths or shell globs, filename/count-only output modes, or traversal semantics not represented by the initial tool. Including straightforward grep, find, and fd translations gives an estimated coverage ceiling of approximately 84%, while 72.9% is the conservative directly confirmed result.

Because tool outputs remain in conversation history until compaction, their reduction also lowers repeated input context. Historical replay estimated 157.5M fewer repeated input tokens before tool-schema overhead, or approximately 60.2M–69.1M net tokens when the tool is enabled only in relevant sessions.

These figures measure model context size rather than billing impact: approximately 98.2% of historical input tokens were cached.