Batch File Tools

Single-file reads are already cheaper

Native Read prefixes every line with N\t — the same verbatim-numbered format regardless of whether slicing is used. batch_read places the line range once in the output header, with no per-line markers in any mode.

This applies to every batch_read call including single-file reads with no bundling. 61% of all observed batch_read calls were single-file; they still produced 2.5–2.8× fewer chars per read than the native equivalent.

Bundling scales with codebase size

Both tools accept arrays. When the model bundles multiple files or operations into one call the savings compound on top of the format reduction. Bundling rate scales with codebase size; bundling depth (avg items per bundled call) is consistent across projects.

Read modes and targeting

Native Read with slicing still emits N\t on every returned line. batch_read slices with offset+count emit the range once in the header, achieving the same targeting at lower overhead.

Edit operations

Content-anchored ops match a string; line-addressed ops target a line number from a preceding sliced read header. Two op types have no native equivalent.

17–22% of all edit ops (replace_range + insert_at_line) are only possible via batch_edit. A single-file batch_edit call with multiple ops still cuts round-trips versus one Edit or Write call per change.

Read-before-edit overhead

Native Edit requires a preceding Read to source the old_string anchor — read the file, locate the string, copy it into the call. Correlation analysis across native sessions in the larger codebase shows 46% of native reads to a file were followed by a native edit to the same file. Of those read→edit pairs, 50% occurred within 3 sequential steps, confirming direct setup overhead rather than incidental context gathering.

batch_edit eliminates this coupling. The model can just provide the anchor string without reading the file first. In batch-tool sessions, the same-file read-then-edit sequence drops to 2% of batch_read calls.

Each edit to a known file costs two round-trips with native tools (one read result + one edit result, both appending to context) but costs one round-trip with batch tools.

Anchor failures resolve without re-reads

When a native Edit anchor fails to match, the only recourse is to re-read the file to locate the correct string and retry — a full round-trip for what may be a typo or a minor whitespace difference.

batch_edit applies whitespace-normalized matching before raising an error: tabs, spaces, and collapsed whitespace in the old string are matched against the original file content. If normalized matching also fails, the result includes a nearest_anchor block containing verbatim context around the closest matching region, ready to paste as the corrected old string. The model corrects the anchor and retries in the next turn without re-reading the file.

This matters most in long sessions where files have been modified since the last read: what would be a stale-read error in native tools (requiring a full re-read) is an inline correction in batch tools.

Single-file edits still benefit

Multi-file bundling compounds the savings, but most batch_edit calls target a single file: 74% in the smaller codebase, 57% in the larger. All calls still averaged 2.7× and 3.7× operations per call respectively.

Three changes to one file with native tools means three sequential Edit calls — three round-trips, three result blocks added to context. batch_edit handles all three in one call with one result block. The turn is the same unit of context cost whether it contains one operation or ten.

With vs without batch tools

The table below covers sessions from the larger codebase, split by whether batch tools were active. Task complexity varies between sessions, so this is not a controlled test, but the I/O pattern shift is unambiguous.

Same call budget, 2.4× more I/O work completed. Native Edit — the costliest pattern (read file → extract old_string → call Edit) — dropped 94%. Sessions ran 66% longer, taking on more complex tasks without hitting context limits.

What the output growth reflects

Output tokens per session grew 87% (24,454 → 45,771) with batch tools active. That increase is work completed, not overhead: context budget that native tools spend on delivering file content is instead available for reasoning and code generation. Output is the work the model produces to accomplish a task; input is the overhead required to produce it. Reducing input to only the relevant portions frees space for more output.

Orientation compression and cross-session task merging

Before edits can begin, the model needs to orient: read files, understand structure, build enough context to reason about what to change. With native tools, orientation at session start can fill half the context window just to establish what is there and what needs to be done. While editing, the model also has to Read each file before calling Edit because its view of the file may be stale. Orientation and edit-setup reads are interleaved throughout, consuming context budget continuously.

With batch tools, orientation uses fewer tokens before editing can start, and edits no longer require a preceding read. In the larger codebase after switching to batch tools, each session covered 25.8 equivalent file reads per session vs 19.0 before, in 13 actual calls vs 15 — 36% broader coverage at lower per-call cost.

The downstream effect is that tasks which previously required multiple sessions — each needing the context window to fill before execution could begin — can now complete in one. With more context space available and fewer turns needed per action, the model accomplishes more within a single session.

Lightweight discovery reduces this further. fileinfo mode returns size, line count, last-changed date, and extracted refs[] (imports and file references) without delivering any file content. project-intel-tool returns semantic summaries, roles, and dependency maps across the entire project in one query. Both let the model identify which files are worth reading before any content enters the context window, eliminating blind reads of files that turn out to be irrelevant to the task.

Total native projection vs actual (both codebases combined)

Error rates

Native tool errors increase with codebase size and session length. Batch tool error rates are constant.

Native Edit stale-read errors occur when a file changes between the read and the edit call — a window that grows with session length. batch_edit completes the read and write atomically within the same call, eliminating the window.

Context window impact

Tool results accumulate in the context window with every turn. The reductions above compound:

A 20-file-read, 15-edit session using native tools adds roughly 600k–800k chars of tool results to context. The equivalent session via batch tools adds roughly 250k–300k — freeing 350k–500k chars that extend session length.