.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: Line values now include terminators, and line numbers change on content with a lone '\r' or a trailing newline. The whole surface is [Experimental("MAAI001")]. ApiCompat does not flag this — 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.

  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.

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)