.NET: [BREAKING] Issue 7571 file access read lines

[Anton Sokolovskyi (antsok)]

Motivation & Context

The harness file tools are line-precise when editing — file_access_replace_lines takes 1-based line numbers and file_access_grep reports them — but all-or-nothing when reading. There is no way to see the lines around a match without reading the whole file, so agents either re-read entire files or edit by a line number they never looked at.

Reading a range only works if grep and the line editor agree on what a line is, and they did not. The stores split on '\n' and stripped '\r'; FileEditor split on '\n', '\r\n' and a lone '\r' and kept terminators. Consequences today:

• On content with lone '\r' terminators, grep's line 1 covers only part of what the model was shown, so editing by that number silently changes the wrong text.
• On a newline-terminated file, grep can report a trailing line number the editor rejects as out of range.
• Because grep strips terminators while NewLine is written verbatim, feeding a grepped line back into replace_lines joins it to the next line.

Description & Review Guide

• What are the major changes?

  1. FileEditor.SplitLinesKeepEnds becomes internal and is used by both stores' SearchAsync, so grep line numbers address the same lines replace_lines edits, by construction.
  2. FileSearchMatch.Line is reported verbatim, terminator included.
  3. New file_access_read_lines tool, rendering <n>\t<line> with everything after the tab verbatim — so a row is already a valid replace_lines new_line.

• What is the impact of these changes?
  Breaking for file_access_grep and file_memory_grep, in three ways: Line values now include terminators; line numbers change on content with a lone '\r' or a trailing newline; and because the whole terminator is stripped before matching, an end-anchored pattern such as match$ now matches on a CRLF line where it could not before, while a pattern targeting a literal '\r' no longer matches the one such a line ends with. The whole surface is [Experimental("MAAI001")]. ApiCompat does not flag any of it — FileEditor is internal and Line keeps its type — so the Release build passing is not evidence of compatibility. ReadLinesToolName is a pure addition and needs no suppression.

  The parity holds for the two stores in this package, not for a custom one: file_access_grep runs through the public AgentFileStore.SearchAsync, whose contract does not prescribe a split, while read_lines and replace_lines split through the internal FileEditor. The XML docs on SplitLinesKeepEnds, FileSearchMatch.Line and ReadLinesAsync now say so. Specifying the split on the store contract would make it enforceable, and is left as a maintainer call.

  file_access_read_lines joins the read-only tool set, so it is exposed under DisableWriteTools and covered by ReadOnlyToolsAutoApprovalRule — the auto-approval doc lists and sample security notes are updated accordingly.

• What do you want reviewers to focus on?
  Whether unifying the splitter is the right call versus leaving grep and the editor divergent, and the per-line snippet offset arithmetic in both stores now that terminators are part of each line. FileSystemAgentFileStoreTests previously asserted no Line values at all, so the six search tests mirrored into it are where that arithmetic is now pinned for the disk-backed store.

Note for parity: Python addresses a trailing empty line on "a\nb\n"; .NET has two lines there, because .NET's line editor never had that phantom line. Each language stays self-consistent, which is what the grep → read → edit round trip depends on.

Related Issue

#7571 — linked without a closing keyword on purpose: the Python half ships in a separate PR, and the issue should stay open until both land. Will change to Closes in the last one.

Contribution Checklist

• The code builds cleanly without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue, and there is no other open PR for this issue
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Pull request overview

Adds line-range reading and aligns .NET grep results with line-editing semantics.

Changes:

• Adds file_access_read_lines.
• Preserves line terminators across grep/read/edit workflows.
• Updates approvals, documentation, and tests.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
InMemoryAgentFileStoreTests.cs	Tests updated grep semantics.
FileEditorTests.cs	Tests splitting and slicing.
FileAccessProviderTests.cs	Tests the new tool and approvals.
HarnessAgentTests.cs	Verifies tool exposure.
InMemoryAgentFileStore.cs	Aligns grep line handling.
FileSystemAgentFileStore.cs	Aligns filesystem grep behavior.
FileSearchMatch.cs	Documents verbatim lines.
FileEditor.cs	Adds shared splitting and slicing.
FileAccessProviderOptions.cs	Documents read-only tool behavior.
FileAccessProvider.cs	Implements file_access_read_lines.
Harness_Step03_DataProcessing/README.md	Updates security guidance.
Claw_Step02_WorkingWithData/README.md	Updates security guidance.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (2)

dotnet/src/Microsoft.Agents.AI/Harness/FileStore/FileSystemAgentFileStore.cs:209

• The new newline, line-number, and snippet-offset behavior is tested only against InMemoryAgentFileStore. FileSystemAgentFileStore has its own copied search loop and an existing comprehensive search test suite, so a store-specific regression here would pass. Add equivalent CRLF, lone-CR, trailing-newline, anchored-pattern, and snippet-offset coverage for this implementation.

            // Lines keep their terminators, so these line numbers address the same lines that
            // replace_lines edits and each reported line can be reused as a literal new_line.
            List<string> lines = FileEditor.SplitLinesKeepEnds(fileContent);

dotnet/src/Microsoft.Agents.AI/Harness/FileAccess/FileAccessProvider.cs:326

• The advertised line-number parity is not guaranteed for custom AgentFileStore implementations. file_access_grep delegates to the public AgentFileStore.SearchAsync, whose contract does not define splitting or terminator retention, while this method and replace_lines split independently through an internal-only helper. An existing custom store can therefore return a grep number that reads or edits a different line. Define the required semantics on the public store contract and make a shared implementation available (or centralize line matching above the store) before promising parity.

    [Description("Read part of a file by 1-based inclusive line number; omit endLine to read to the end of the file, and an endLine past the last line is clamped. Line numbers match file_access_grep and file_access_replace_lines. Each line is prefixed with its number and a tab; everything after that tab is verbatim, including the line's own terminator, so it can be reused as a file_access_replace_lines new_line.")]
    private async Task<string> ReadLinesAsync(string fileName, int startLine, int? endLine = null, CancellationToken cancellationToken = default)

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (3)

dotnet/src/Microsoft.Agents.AI/Harness/FileAccess/FileAccessProvider.cs:332

• The generated tool description promises line-number parity unconditionally, contradicting this method's remarks for custom stores. Because this text is sent to the model, a custom store can still trigger the wrong-line edit this change is intended to prevent. Qualify the claim to built-in stores unless AgentFileStore.SearchAsync is given a matching line-splitting contract.

    [Description("Read part of a file by 1-based inclusive line number; omit endLine to read to the end of the file, and an endLine past the last line is clamped. Line numbers match file_access_grep and file_access_replace_lines. Each line is prefixed with its number and a tab; everything after that tab is verbatim, including the line's own terminator, so it can be reused as a file_access_replace_lines new_line.")]

dotnet/src/Microsoft.Agents.AI/Harness/FileAccess/FileAccessProvider.cs:142

• This workflow assumes grep and the editor share line semantics, but FileAccessProvider supports custom AgentFileStore implementations and SearchAsync does not require that split. For such a store, following this instruction can silently edit a different line. Qualify the workflow as applying to the built-in stores, or define the shared line semantics in the public store contract.

This issue also appears on line 332 of the same file.

        - To change part of a file, find the line numbers with `file_access_grep`, read the range around them
          with `file_access_read_lines`, then edit with `file_access_replace_lines`. Reading the whole file
          first is rarely necessary.

dotnet/src/Microsoft.Agents.AI/Harness/FileStore/FileEditor.cs:145

• Both search implementations call this helper for every line before knowing whether it matches. Since each Substring creates another string, searching a newline-heavy large file now allocates a second copy of nearly all its text in addition to the strings from SplitLinesKeepEnds. Return the searchable content length (or terminator length) and use Regex.Match(line, 0, length) so matching excludes the terminator without copying every line.

    internal static string TrimLineTerminator(string line)

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.