Skip to content

Commit d74b6e1

Browse files
antsokclaude
andcommitted
Python: Finish the removal in the docs and drop a test that now proves nothing
Follow-up to the previous commit, from reading the whole PR diff against main rather than only the files that commit touched. AGENTS.md still told readers that file_access_grep and file_memory_grep verify a store's line numbers and refuse the call on a mismatch, in two separate bullets. That is exactly the claim the previous commit made false, and AGENTS.md is what the next agent working here reads first. test_shipped_stores_are_trusted_and_not_re_read survived because it still passed: it asserts grep does not re-read the file, which is now trivially true for every store rather than a property of the shipped ones. Its docstring and its comment both describe trust that no longer exists. Removed rather than reworded, since the one-pass claim it was pinning is no longer a claim anyone can break. Three descriptions also scoped the verbatim-line promise to "the stores in this package", which was how it had to be phrased while a custom store's text went unchecked. With the contract documented rather than enforced, they now state what implementers are expected to do, matching the same change on the .NET half. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 85ecd6a commit d74b6e1

3 files changed

Lines changed: 8 additions & 33 deletions

File tree

‎python/packages/core/AGENTS.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -120,12 +120,12 @@ agent_framework/
120120

121121
### File Access Harness (`_harness/_file_access.py`)
122122

123-
- **`AgentFileStore`** - Abstract async store backing the file-access harness. Implementations expose `write`, `read`, `delete`, `list_children`, `file_exists`, `search`, and `create_directory` over forward-slash relative paths. `list_children` returns the direct children (files and subdirectories, subdirectories first) as `FileStoreEntry` instances; `search` accepts a keyword-only `recursive` flag (default `False`) and, when `recursive=True`, walks all descendants and returns `file_name` values relative to the search directory. The line-numbering contract lives on the base class: `split_lines` publishes the `\n`-only keepends split that every `line_number` addresses, `scan_content` is the numbering primitive both shipped stores report through, and `search` is now **concrete** — it asks the overridable `find_matching_files` hook which files to consider (superset semantics; a backend with a native index overrides it and prunes server-side) and then reads and numbers them itself. A store may still override `search` outright, but then it owns numbering, and `file_access_grep`/`file_memory_grep` verify its line numbers against `split_lines` and refuse the whole call on a mismatch rather than let an edit land on the wrong line.
123+
- **`AgentFileStore`** - Abstract async store backing the file-access harness. Implementations expose `write`, `read`, `delete`, `list_children`, `file_exists`, `search`, and `create_directory` over forward-slash relative paths. `list_children` returns the direct children (files and subdirectories, subdirectories first) as `FileStoreEntry` instances; `search` accepts a keyword-only `recursive` flag (default `False`) and, when `recursive=True`, walks all descendants and returns `file_name` values relative to the search directory. The line-numbering contract lives on the base class: `split_lines` publishes the `\n`-only keepends split that every `line_number` addresses, `scan_content` is the numbering primitive both shipped stores report through, and `search` is now **concrete** — it asks the overridable `find_matching_files` hook which files to consider (superset semantics; a backend with a native index overrides it and prunes server-side) and then reads and numbers them itself. A store may still override `search` outright, but then it owns numbering: it must report `line_number` as a 1-based coordinate into `split_lines` of the content `read` returns. Nothing checks that at run time, so a store that numbers differently makes a later edit land on the wrong line silently.
124124
- **`InMemoryAgentFileStore`** - Dict-backed store suitable for tests and lightweight scenarios.
125125
- **`FileSystemAgentFileStore`** - Disk-backed store rooted under a configurable directory. Enforces relative-path normalization, root containment, and rejects symlink/reparse-point segments to prevent escape.
126-
- **`FileSearchResult`** / **`FileSearchMatch`** - `SerializationMixin` DTOs returned by `search`, carrying the matching file name, a context snippet, and the matching lines with 1-based line numbers. The stores in this package report each matching line verbatim, including its own terminator, so it can be reused as a `file_access_replace_lines` `new_line`; the pattern itself is matched against the line with its whole terminator removed, so `^`/`$` anchor to the line's text on a CRLF file as they already did on an LF one. A custom store populates these DTOs from its own `search` and is not held to either property by the base contract.
126+
- **`FileSearchResult`** / **`FileSearchMatch`** - `SerializationMixin` DTOs returned by `search`, carrying the matching file name, a context snippet, and the matching lines with 1-based line numbers. Implementers should report each matching line verbatim, including its own terminator, so it can be reused as a `file_access_replace_lines` `new_line`; the pattern itself is matched against the line with its whole terminator removed, so `^`/`$` anchor to the line's text on a CRLF file as they already did on an LF one. A custom store populates these DTOs from its own `search`; the verbatim text is a recommendation, but the line number is not — it must address `split_lines`.
127127
- **`FileStoreEntry`** - `SerializationMixin` DTO returned by `list_children`, carrying an entry `name` and `type` (`"file"` or `"directory"`).
128-
- **`FileAccessProvider`** - `ContextProvider` that adds shared file-access tools (`file_access_write`, `file_access_read`, `file_access_read_lines`, `file_access_delete`, `file_access_ls`, `file_access_grep`, `file_access_replace`, `file_access_replace_lines`) plus default usage instructions to each invocation. `file_access_ls` enumerates direct children (both files and subdirectories) as `{name, type}` entries with an optional `glob_pattern`, so the agent can walk the tree level by level; `file_access_grep` searches recursively from an optional base `directory` and returns relative `file_name` paths, scoped via an `fnmatch` `glob_pattern` (where `*` crosses `/`, e.g. `*.md`, `reports/*`). `file_access_replace` substitutes `old_string` with `new_string` (failing if not found, or if multiple matches and `replace_all` is false); `file_access_replace_lines` replaces whole 1-based lines with literal text (each `new_line` includes its own trailing newline; an empty `new_line` deletes the line, including its line break). `file_access_read_lines` returns a 1-based inclusive line range, one line per row as `<line_number>\t<line>`; `end_line` may be omitted to read to the end of the file, and an `end_line` past the last line clamps to it. Everything after the tab is verbatim, including the line's own terminator (which therefore doubles as the row separator), so a row's text can be fed straight back as a `file_access_replace_lines` `new_line` without losing a `\r\n`. Its line numbering comes from the same `_split_lines_keepends` split as `file_access_replace_lines` and as the stores in this package, so with one of those a number reported by grep addresses the same line in all three tools, including the trailing empty line of a newline-terminated file; grep itself runs through `AgentFileStore.search`, which must number by the same split but does not inherit it, so a store overriding `search` owns its numbering and the providers verify it, refusing results that do not line up. All tools are registered with `approval_mode="always_require"` by default, so every file operation needs host approval. Pass `disable_write_tools=True` to advertise only the read-only tools. To run unattended you can disable approval at the source with `disable_readonly_tool_approval=True` (read, read_lines, ls, grep) and/or `disable_write_tool_approval=True` (write, delete, replace, replace_lines), which register the affected tools with `approval_mode="never_require"`; alternatively, keep approval on and pass one of the static auto-approval rules to `ToolApprovalMiddleware` (via `auto_approval_rules`): `FileAccessProvider.read_only_tools_auto_approval_rule` approves only the read-only tools (read, read_lines, ls, grep), while `FileAccessProvider.all_tools_auto_approval_rule` approves every file-access tool including the write tools. Both rules reject any call carrying a `server_label` so they stay scoped to this provider's local tools and never auto-approve a same-named hosted tool. The tool names are also exposed as class constants (`WRITE_TOOL_NAME`, `READ_TOOL_NAME`, `READ_LINES_TOOL_NAME`, `DELETE_TOOL_NAME`, `LS_TOOL_NAME`, `GREP_TOOL_NAME`, `REPLACE_TOOL_NAME`, `REPLACE_LINES_TOOL_NAME`). Unlike `MemoryContextProvider`, the store is intentionally shared across sessions and agents.
128+
- **`FileAccessProvider`** - `ContextProvider` that adds shared file-access tools (`file_access_write`, `file_access_read`, `file_access_read_lines`, `file_access_delete`, `file_access_ls`, `file_access_grep`, `file_access_replace`, `file_access_replace_lines`) plus default usage instructions to each invocation. `file_access_ls` enumerates direct children (both files and subdirectories) as `{name, type}` entries with an optional `glob_pattern`, so the agent can walk the tree level by level; `file_access_grep` searches recursively from an optional base `directory` and returns relative `file_name` paths, scoped via an `fnmatch` `glob_pattern` (where `*` crosses `/`, e.g. `*.md`, `reports/*`). `file_access_replace` substitutes `old_string` with `new_string` (failing if not found, or if multiple matches and `replace_all` is false); `file_access_replace_lines` replaces whole 1-based lines with literal text (each `new_line` includes its own trailing newline; an empty `new_line` deletes the line, including its line break). `file_access_read_lines` returns a 1-based inclusive line range, one line per row as `<line_number>\t<line>`; `end_line` may be omitted to read to the end of the file, and an `end_line` past the last line clamps to it. Everything after the tab is verbatim, including the line's own terminator (which therefore doubles as the row separator), so a row's text can be fed straight back as a `file_access_replace_lines` `new_line` without losing a `\r\n`. Its line numbering comes from the same `_split_lines_keepends` split as `file_access_replace_lines` and as the stores in this package, so with one of those a number reported by grep addresses the same line in all three tools, including the trailing empty line of a newline-terminated file; grep itself runs through `AgentFileStore.search`, which must number by the same split but does not inherit it, so a store overriding `search` owns its numbering and nothing verifies it at run time. All tools are registered with `approval_mode="always_require"` by default, so every file operation needs host approval. Pass `disable_write_tools=True` to advertise only the read-only tools. To run unattended you can disable approval at the source with `disable_readonly_tool_approval=True` (read, read_lines, ls, grep) and/or `disable_write_tool_approval=True` (write, delete, replace, replace_lines), which register the affected tools with `approval_mode="never_require"`; alternatively, keep approval on and pass one of the static auto-approval rules to `ToolApprovalMiddleware` (via `auto_approval_rules`): `FileAccessProvider.read_only_tools_auto_approval_rule` approves only the read-only tools (read, read_lines, ls, grep), while `FileAccessProvider.all_tools_auto_approval_rule` approves every file-access tool including the write tools. Both rules reject any call carrying a `server_label` so they stay scoped to this provider's local tools and never auto-approve a same-named hosted tool. The tool names are also exposed as class constants (`WRITE_TOOL_NAME`, `READ_TOOL_NAME`, `READ_LINES_TOOL_NAME`, `DELETE_TOOL_NAME`, `LS_TOOL_NAME`, `GREP_TOOL_NAME`, `REPLACE_TOOL_NAME`, `REPLACE_LINES_TOOL_NAME`). Unlike `MemoryContextProvider`, the store is intentionally shared across sessions and agents.
129129

130130
### File Memory Harness (`_harness/_file_memory.py`)
131131

‎python/packages/core/agent_framework/_harness/_file_access.py‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -390,9 +390,9 @@ def __init__(self, line_number: int, line: str) -> None:
390390
391391
Args:
392392
line_number: The 1-based line number where the match was found.
393-
line: The matching line. The stores in this package report it verbatim,
394-
terminator included; a custom :meth:`AgentFileStore.search` is not
395-
bound to that by the base contract.
393+
line: The matching line. Implementers should report it verbatim, terminator
394+
included, so it can be reused as a replacement line; unlike
395+
``line_number``, that is a recommendation rather than a requirement.
396396
"""
397397
if line_number < 1:
398398
raise ValueError("line_number must be a positive integer.")
@@ -1902,9 +1902,8 @@ async def file_access_grep(
19021902
Leave empty or omit to search all files.
19031903
Returns matching results whose file_name values are paths relative to the store root
19041904
(directly usable with file_access_read), along with snippets and matching lines with line numbers.
1905-
For the stores in this package each matching line is verbatim, including its own line
1906-
terminator, so it can be reused as a file_access_replace_lines new_line; a custom store is
1907-
not bound to report it verbatim, though its line numbers must address the same lines.
1905+
Each matching line is reported verbatim, including its own line terminator, so it can be
1906+
reused as a file_access_replace_lines new_line.
19081907
Line numbers count lines split on \n only, with a final empty line when content ends in a
19091908
newline.
19101909
The regex_pattern must be 256 characters or fewer.

‎python/packages/core/tests/core/test_harness_file_access.py‎

Lines changed: 0 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1645,30 +1645,6 @@ async def test_grep_accepts_an_override_that_uses_the_published_primitive(
16451645
assert payload[0]["matching_lines"][0]["line_number"] == 3
16461646

16471647

1648-
async def test_shipped_stores_are_trusted_and_not_re_read(
1649-
chat_client_base: SupportsChatGetResponse,
1650-
monkeypatch: pytest.MonkeyPatch,
1651-
) -> None:
1652-
"""Verification must be skipped for the stores shipped here, so grep stays one pass."""
1653-
store = InMemoryAgentFileStore()
1654-
await store.write("cfg.txt", "alpha\nkeep me\n")
1655-
reads: list[str] = []
1656-
original_read = InMemoryAgentFileStore.read
1657-
1658-
async def counting_read(self: InMemoryAgentFileStore, path: str) -> str | None:
1659-
reads.append(path)
1660-
return await original_read(self, path)
1661-
1662-
# Counted on the class: an instance attribute shadowing ``read`` is untrusted in its own
1663-
# right, so instrumenting the instance would measure the override, not the shipped store.
1664-
monkeypatch.setattr(InMemoryAgentFileStore, "read", counting_read)
1665-
tools = await _prepare_access_tools(chat_client_base, store=store)
1666-
grep = _tool_by_name(tools, FileAccessProvider.GREP_TOOL_NAME)
1667-
await grep.invoke(arguments={"regex_pattern": "keep me"})
1668-
1669-
assert reads == []
1670-
1671-
16721648
# endregion
16731649

16741650
# region expected_line write guard

0 commit comments

Comments
 (0)