Python: [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 grep match before editing them, so a model either re-reads the whole file (expensive, and truncated by host result caps on exactly the large files where a partial read matters) or skips the read and guesses at the line, which is the wrong-line edit the line-precise editor exists to prevent.

A second, related gap surfaced while implementing this. file_access_grep reported each match with its terminator stripped, while file_access_replace_lines takes new_line literally. An agent that grepped a CRLF file and edited by line number had
no way to know it should write \r\n, so the edit silently converted that line - and the only way to detect the file's line-ending style was a whole-file read, the very fallback this change removes.

Description & Review Guide

• What are the major changes?

file_access_read_lines(file_name, start_line, end_line=None) reads a 1-based inclusive range. Omit end_line to read to the end of the file; an end_line past the last line clamps to the last line, while an out-of-range start_line is reported. Rows are <line_number>\t<line>, and everything after the tab is verbatim, including the line's own terminator — which therefore doubles as the row separator - so a row's text feeds straight back into file_access_replace_lines without losing a \r\n.

Line numbering comes from _split_lines_keepends, the same split used by grep and replace_lines, so a number maps to the same line in all three tools, including the trailing empty line of a newline-terminated file.

file_access_grep now reports matches verbatim on the same contract. The pattern is still matched against the line without its trailing \n, so ^ and $ anchor per line as before, and snippet offsets and line numbers are unchanged.

DEFAULT_FILE_ACCESS_INSTRUCTIONS gains a clause teaching the grep → read the range edit loop, which is what makes models reach for the new tool rather than defaulting to whole-file reads.

• What is the impact of these changes?

The new tool is read-only. It joins _READ_ONLY_TOOL_NAMES, so both static auto-approval rules cover it with no new approval logic; it follows disable_readonly_tool_approval, and it stays advertised under disable_write_tool. Consumers get one more tool definition per request; anyone using read_only_tools_auto_approval_rule picks it up automatically, while anyone with a hand-rolled rule listing the read-only tools by name will see it prompt for approval
until they add it.

The breaking part is grep: matching_lines[].line now carries its terminator, and FileSearchMatch.line changes meaning with it. file_memory_grep inherits the same behaviour, since it shares the store search. The instruction changes alter injected
prompt text for consumers on the default; anyone passing their own instructions= is unaffected. There is no change to AgentFileStore and no change to any other tool's signature or behaviour.

• What do you want reviewers to focus on?

Whether the grep alignment belongs in this PR or should be split out - it is a separate commit so it can be dropped. And the verbatim-terminator contract itself, since that is what the tool's usefulness rests on.

Related Issue

#7571

Deliberately linked without a closing keyword: this covers the Python half only, and the .NET port follows in a separate PR. Please leave the issue open until that lands. 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 (see Related Issue above).
• 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 reads to Python harness file tools while preserving line-number and terminator semantics.

Changes:

• Adds file_access_read_lines with approval integration.
• Changes grep matches to retain line terminators.
• Adds tests and documentation.

Reviewed changes

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

Show a summary per file

File	Description
python/samples/02-agents/harness/README.md	Documents the new auto-approved tool name.
python/samples/02-agents/harness/build_your_own_claw/README.md	Updates security guidance.
python/packages/core/tests/core/test_harness_file_access.py	Tests range reads, terminators, and approvals.
python/packages/core/AGENTS.md	Documents new behavior and API.
python/packages/core/agent_framework/_harness/_file_access.py	Implements range reads and grep changes.

---

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

[Copilot]

Pull request overview

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

Suppressed comments (2)

python/packages/core/agent_framework/_harness/_file_access.py:524

• This also changes which grep results match: previously content.split("\n") searched a CRLF line as "...\r", whereas this removes both terminator characters. Patterns such as match$ therefore start matching CRLF files, and patterns targeting \r stop matching, despite the PR description saying matching remains as before. Either remove only \n to preserve the old behavior, or explicitly document this additional breaking change and its impact.

        scanned = line.removesuffix("\n").removesuffix("\r")

python/packages/core/agent_framework/_harness/_file_access.py:243

• The element-count phrase was dropped, leaving “means the result has trailing … yields” grammatically incomplete. Restore the count clause so the split contract is readable.

    line in the others and stays in range. Splitting solely on ``\n`` (a trailing
    ``\r`` stays attached to the line) means the result has
    trailing ``\n`` yields a final empty (editable) line, and empty content yields a
    single empty line. ``"".join(...)`` reproduces ``content`` verbatim.