.NET: Python: [Feature]: line-range reads in the harness file tools (`file_access_read_lines` or `offset`/`limit` on `file_access_read`)

[antsok]

Description

Problem

The harness file tools are asymmetric about lines. On the edit side they are line-precise: file_access_replace_lines targets 1-based line numbers, and file_access_grep reports matching_lines with those same numbers (the two share the \n-only, keepends split of _split_lines_keepends, so a grep number always addresses the same line the editor touches). On the read side there is no line access at all: file_access_read takes only file_name and returns the entire content (_ReadFileInput, _file_access.py), and the AgentFileStore.read(path) contract underneath is likewise all-or-nothing.

That leaves a hole in exactly the workflow the line-precise edit tools exist for. The natural point-edit loop is:

1. file_access_grep — find the location (line numbers),
2. see the surrounding lines to write a correct edit,
3. file_access_replace_lines / file_access_replace — make the point edit.

Step 2 has no tool. The model's options are:

• Re-read the whole file — token-expensive on large artifacts, and self-defeating under any tool-result cap: an application that truncates or spools oversized tool results (ours caps them and spills to the store) truncates precisely the large files where partial reads matter most, so the model may never see the region it needs.
• Grep again with a broader pattern — file_access_grep's snippet and matching_lines are anchored to the pattern, not to a requested range; "show me lines 120–160" is not expressible.

Observed effect in production (harness + AG-UI, advisor + headless sub-agents): models told to point-edit fall back to whole-file file_access_read before nearly every replace_lines, and smaller models then skip the read and guess — producing the wrong-line edits the line-precise editor was added to prevent.

Requested

Either shape works; the essential property is numbering parity with grep/replace_lines (same _split_lines_keepends semantics, including the trailing-newline final empty line):

1. New tool file_access_read_lines(file_name, start_line, end_line=None) — 1-based inclusive range, end_line=None → end of file, out-of-range end_line clamps. Returning line-numbered text lets the model feed numbers straight back into file_access_replace_lines.
2. Optional params on the existing read — file_access_read(file_name, start_line=None, end_line=None) (or offset/limit), defaulting to today's whole-file behavior.

Implementation stays inside FileAccessProvider — read the full content via the existing AgentFileStore.read, slice with _split_lines_keepends, no store-protocol change needed. (A store-level partial read would be a separate optimization; the context-window win comes from not returning the whole file to the model.)

A new tool (option 1) composes with the existing surface: disable_write_tools children keep it (it is a read), disable_readonly_tool_approval should govern it exactly like file_access_read, and read_only_tools_auto_approval_rule should match it.

Workaround (application-side, today)

A hand-rolled @tool bound to the same store the provider holds (ats.tools.read_lines.make_read_lines_tool): normalizes paths with the provider's own _normalize_relative_path, splits with _split_lines_keepends (both imported from agent_framework._harness._file_access with fallbacks — private imports this FR would remove), mirrors the provider's read-approval mode, and is wired separately into the advisor and each headless sub-agent. It works, but it reaches into two private helpers to guarantee numbering parity, and every consumer has to remember to wire it beside the provider — exactly the kind of duplication a provider-native range read would remove.

Code Sample

Language/SDK

Python

[antsok]

I would like to offer my contribution. I can provide the implementation for the suggested option 1 file_access_read_lines(file_name, start_line, end_line=None) westey (@westey-m)

[westey-m]

Hi Anton Sokolovskyi (@antsok), sure, happy to see a contribution on this, just for python, or for both python and .net. If the former, I'll port to .net separately.

[antsok]

Hi Anton Sokolovskyi (@antsok), sure, happy to see a contribution on this, just for python, or for both python and .net. If the former, I'll port to .net separately.

Great, westey (@westey-m) . I haven't looked into the .NET part of MAF yet, so can't promise. So, I will take the Python part for sure, but I might be able to do the .Net one too :)

[antsok]

westey (@westey-m) I'm starting on the Python side. A few decisions I'd rather agree up front, since they shape the tool's contract and touch existing FileAccessProvider users.

1. What should file_access_read_lines return?

My preference is line-numbered plain text rather than a structured list:

Lines 12-14 of 'notes.md' (240 lines total):
12    def handler(req):
13        return None
14

Plain text — pros: fewer tokens per call, and that cost lands on every user on every read; same return type as file_access_read, so both read tools behave alike; numbered text is what models see everywhere (cat -n, diffs, stack traces). Cons: not machine-parseable, so hosts that render or post-process tool results get a blob; the format becomes a de-facto contract once agents rely on it.

Structured {line_number, line} like grep — pros: consistent with grep for anyone parsing tool output, and no gutter a model could copy into an edit. Cons: several times the tokens per line for every user on every call, and a second shape for "reading a file" alongside file_access_read's str.

I've weighted the token cost highest since that's the reason the tool exists, but if you expect consumers to render this rather than just feed it to a model, structured is the better call and I'll do that.

2. Should it expose the file's line endings?

There's an existing gap this tool is well placed to close. file_access_grep reports lines with the terminators stripped (split("\n"), then rstrip("\r")), but file_access_replace_lines expects a literal new_line including the terminator — the unit test says as much: "CRLF terminators are preserved when the caller keeps them". So today any agent that greps a CRLF file and edits by line number has no way to know it should write \r\n. It writes \n, and the file quietly drifts to mixed endings. Detecting the style currently requires a whole-file file_access_read — the fallback this issue is trying to remove.

Stating it in the header ((240 lines total, CRLF line endings)) — pros: fixes a silent correctness problem current users already have; removes the last reason to read a whole file before an edit; no change to any existing tool. Cons: a few tokens per call for users who only ever touch LF files; scope beyond what I originally filed.

Leaving it out — pros: strictly literal to the FR, smallest review surface. Cons: CRLF users keep silently converting line endings, and the new tool doesn't help them.

The alternative — having grep report terminators — would change grep's output for everyone, so I'm not proposing it.

3. Should I touch DEFAULT_FILE_ACCESS_INSTRUCTIONS?

This is the only change that alters behaviour for current users, so I'd rather ask than assume. The block already names file_access_ls and file_access_grep to steer tool choice, and adding the grep → read the range → edit loop is likely what makes models reach for the new tool at all.

Updating it — pros: lower token spend for every provider user, because agents stop pulling whole files before point edits; the feature actually gets used. Cons: a few tokens in every request for everyone, and a behaviour change nobody opted into — agents that read whole files today would start reading ranges. Users passing a custom instructions= are unaffected, since it overrides the default entirely.

Leaving it — pros: zero change to existing prompt size or behaviour. Cons: models keep defaulting to whole-file reads, so the problem in the issue persists for default users.

Adding the tool at all — impact on current users

Additive, but not entirely free:

• One more tool definition in every request for every FileAccessProvider consumer
• Anyone using FileAccessProvider.read_only_tools_auto_approval_rule picks it up automatically — I'd add the name to _READ_ONLY_TOOL_NAMES, which both static rules derive from.
• Anyone who hand-rolled an approval rule listing file_access_read / _ls / _grep by string will see the new tool prompt for approval until they add it. Probably worth a release note.
• disable_write_tools consumers get it too, since it's a read.
• No change to AgentFileStore, and no change to any existing tool's signature or behaviour.

On .NET

FileEditor.SplitLinesKeepEnds and the stores' SearchAsync split differently. On any newline-terminated file, grep (Split('\n')) sees a trailing empty line that SplitLinesKeepEnds doesn't produce, so file_access_grep reports a line number file_access_replace_lines rejects as out of range. On "a\nb\n": grep says 3 lines, the editor says 2. Python's test_file_access_grep_line_numbers_are_editable covers exactly this case and passes, because both paths share one helper. Aligning them changes existing .NET line numbers, so it seems like its own issue rather than something to fold in here — want me to open one?

The whole-file-read fallback and the CRLF edits above are both things I've hit running the workaround from the issue in production, rather than hypotheticals. 🙂

[westey-m]

Thanks Anton Sokolovskyi (@antsok), here are some of my opinions. Ultimately, there are untested opinions, and what works most reliably is always preferred. 🙂

1. What should file_access_read_lines return?

Line numbered plain text seems reasonable. I'm not sure that the header Lines 12-14 of 'notes.md' (240 lines total): is that useful, since it just repeats what the input parameters of the tool call was, and that is still available in the chat history.

The potential confusion over the gutter isn't great, but it is possible to update the function tool description to describe the gutter size. We'll need to consider how the gutter works for lines with different sized numbers, e.g. line 1 (1 char) vs line 100 (3 chars). Since this is not for human consumption, a standard 1 character separator might work OK.

If this works well, we can update file_access_grep to match too. (see 3 below, FileAccess is still experimental so changes are OK).

2. Should it expose the file's line endings?

The problem with adding an indicator is that it's not always possible to definitively determine, if the file has mixed line endings. If we return a single blob of text (multiple lines) they would already contain the line endings of those lines, allowing the model to reuse the same though.

However, if you are seeing reliability issues, a best effort approach may make sense, where we output the line ending if consistent, and if not, we can consider outputting all line endings used, or just not mention it. I'm leaning towards not mentioning it when mixed, since it's not super valuable to mention in this case.

3. Should I touch DEFAULT_FILE_ACCESS_INSTRUCTIONS?

FileAccess is still an experimental feature, so breaking changes is acceptable. In fact, they are desirable if they can improve the design before we move out of experimental.

On .NET

Aligning them changes existing .NET line numbers, so it seems like its own issue rather than something to fold in here — want me to open one?

This seems like a small enough change, so fine to address as part of this change.

[antsok]

Thanks westey (@westey-m) - clear.

1. Format and gutter

Plain text, single tab, no padding: 1\talpha, 100\talpha. The number is "digits up to the first tab", same as grep -n. Goes to the tool description.

Header dropped entirely - you're right that it's redundant.

2. Line endings

Keeping the terminators makes your suggestion work as described, and dissolves the mixed-file case rather than working around it - nothing to detect, each line carries its own. No indicator needed.

3. Should file_access_grep come along?

Following your "we can update file_access_grep to match too" - worth doing here, or the fix is half of one. _search_file_content reports line.rstrip("\r") off a split("\n"), so a grep hit carries neither terminator, and a model that greps and edits without calling read_lines in between still converts the file.

Small and local: report the keepends line at _file_access.py:537. Scan loop and snippet offsets untouched, line numbers unchanged.

4. Instructions

Will do. Noted on breaking changes being fine while FileAccess is experimental.

On .NET

I assumed Python and .NET should travel in separate PRs. Please let me know if it should be one.