Motivation & Context

Two defects, one of which only became visible while fixing the other.

The reading gap (#7571). 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.

Grep and the editor did not agree on what a line is. The stores split on '\n' and stripped '\r'; FileEditor split on '\n', '\r\n' and a lone '\r' and kept terminators. That is not a cosmetic difference:

• 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 stripped terminators while NewLine is written verbatim, feeding a grepped line back into replace_lines joined it to the next line.

The same hole, one level down — and this is new scope since the first version of this PR. Unifying the splitter fixes the two stores in this package, but AgentFileStore.SearchAsync was abstract with no numbering contract at all, while read_lines and replace_lines re-count from ReadAsync. So a custom store could make "line 5" mean two different things, and replace_lines would edit the wrong line — in range, reporting success. FileMemoryProvider had the identical hole.

The previous revision of this PR documented that as a caveat and called it "a maintainer call". @moonbox3 made that call on the Python PR #7669: the rule should live on the contract, not in a doc comment. This PR now mirrors #7669 so both SDKs carry the same contract.

Description & Review Guide

• What are the major changes?

  The reading gap:

  1. FileEditor.SplitLinesKeepEnds becomes internal and is the single definition of a line.
  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.

  The contract, now on the base class:
  4. SplitLines() publishes the split every line_number addresses. Per-SDK by design: it need not match Python, only be consistent here, because a line number never crosses runtimes.
  5. ScanContent() is the numbering primitive. Both shipped stores report through it, which also removes the scan loop that was duplicated between them.
  6. FindMatchingFilesAsync() is a new hook for narrowing to the files worth reading. The regex goes down as a hint with superset semantics — over-returning is harmless because the base re-scans, under-returning loses matches. A backend with a native index overrides it and narrows server-side. Its default is built from ListChildrenAsync, so a store implementing nothing beyond the mandatory members gets aligned numbers for free.
  7. SearchAsync is no longer abstract. It reads and numbers candidates itself, and re-applies the glob and the non-recursive rule, since the hook may over-return.
  8. Overriding SearchAsync stays first-class — a backend that can do the whole job natively should — but then it owns numbering, and nothing checks it at runtime. SearchAsync documents what is owed: LineNumber is a 1-based coordinate into SplitLines of the content ReadAsync returns, ScanContent produces that correctly, and getting it wrong fails silently — the search looks right and a later line edit lands on a line the caller never saw. See focus item 3.
  9. FileLineEdit.ExpectedLine — when supplied, the edit is refused unless the target line still says what the caller saw. Catches splitter drift, a stale line number, and the file changing between read and write.

  Added during review, after the items above:

  10. The tool descriptions now state how lines are counted. @westey-m asked for the case where a model reads a whole file with file_access_read and then edits by line number: it has to count the lines itself, and nothing told it the rule. read, read_lines, replace_lines, grep and the two memory tools now say that lines are terminated by \r\n, \n or a lone \r, that each line keeps its terminator, and that content ending in a terminator has no extra empty line after it. Taken from the cases FileEditorTests already pins rather than from reading the splitter. They also state that the numbers are 1-based, so a model counting lines from a whole-file read knows where to start.
  11. The runtime alignment check was removed. Earlier revisions had both providers re-read every matched file and refuse grep when a store's numbers disagreed with SplitLines. @westey-m's call: that is runtime cost for all users to police implementations that are not per spec, and a spec violation is the implementer's bug. SearchAlignment, BaseSearchResults, ReportsAlignedLineNumbers and DisableSearchAlignmentCheck are gone; the expectation now lives on the members an implementer overrides. A conformance test library is the better answer and is tracked separately as .NET: Add Conformance Test Library for Agent Framework #7931.

• What is the impact of these changes?

  Breaking, in these ways:

  Change	Who notices
  FileSearchMatch.Line includes terminators	anyone consuming grep output
  Line numbers change on lone-'\r' content and on a trailing newline	same
  The whole terminator is stripped before matching, so match$ now matches on a CRLF line where it could not before, and a pattern targeting a literal '\r' no longer matches the one such a line ends with	pattern authors
  SearchAsync is no longer abstract	custom stores (source-compatible; override still works)

  The whole surface is [Experimental("MAAI001")]. ApiCompat does not flag any of it — FileEditor is internal and Line keeps its type — so a passing Release build is not evidence of compatibility. Removing abstract while keeping the member virtual does pass Package Validation; verified by building the package in Release with IsReleased=true.

  Two further changes are not API breaks but do change what the model is told: every line-addressing tool description gains the counting rule, and the expected_line mismatch message no longer echoes the line it found — raised in review as a read oracle where write tools are auto-approved while read tools are not, and applied in 30115b0.

  Cost. None: no tool re-reads a file, and SearchAsync returns its results directly.

  The narrowing hook is not a speed-up and is not sold as one — it is "same speed, now safe". A selectivity sweep against a store doing the whole job in its own SearchAsync:

  selectivity	own SearchAsync	base + hook
  5%	4.15 ms	1.21 ms
  25%	4.40 ms	4.43 ms
  50%	8.91 ms	5.88 ms
  100%	12.72 ms	11.83 ms

  Per-method timings across local disk, in-memory, Azure Blob and Redis show no method-level effect; happy to attach the full table if useful.

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

• What do you want reviewers to focus on?

  1. Whether the contract belongs on AgentFileStore at all — that is the substantive question, and it is a maintainer call being made here rather than assumed.

  2. The superset semantics of FindMatchingFilesAsync. Over-returning is harmless, under-returning silently loses matches. Whether that is documented clearly enough for someone implementing it against a native index.

  3. Whether documentation alone is enough to carry the numbering contract. Earlier revisions tracked "did the base number these?" by tagging the returned list and had the providers verify it; that is removed per change 11 above. What replaces it is the <remarks> on SearchAsync, plus SplitLines and ScanContent being the published primitives an implementer is meant to build on. The open question is whether an implementer overriding SearchAsync will actually read it there, given the failure mode is silent and shows up in someone else's edit.

     This is where the two PRs now diverge. Python: [BREAKING] Add file_access_read_lines and move the line-numbering contract onto AgentFileStore #7669 (Python) still verifies at runtime and was hardened in that direction on 25 Aug. That divergence is not deliberate design — it is one maintainer preference applied to one PR — so it is worth a view on whether Python should follow.

  4. 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.

  Two deliberate divergences from the Python half (Python: [BREAKING] Add file_access_read_lines and move the line-numbering contract onto AgentFileStore #7669):

  • No batching. Both stores already construct the regex with a match timeout, so ReDoS protection is in the engine and there is no thread offload to amortise. Python needs one; this does not.
  • Runtime verification. Python: [BREAKING] Add file_access_read_lines and move the line-numbering contract onto AgentFileStore #7669 keeps it; this PR does not, per focus item 3. Not a design decision either way yet.

  Line-rule parity note: 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 actually depends on.

Related Issue

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

Note that #7571's body still says no store-protocol change is needed; that predates the review discussion above and is no longer accurate for either language.

Contribution Checklist

• The code builds cleanly without any errors or warnings — Release --warnaserror across all five TFMs, Package Validation included
• All unit tests pass, and I have added new tests where possible — 44 new tests, 16 of them in a new AgentFileStoreContractTests
• 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.