Skip to content

Commit 87d4d0a

Browse files
authored
Python: feat(core): add session-scoped file access isolation (microsoft#8542)
* feat(core): add session-scoped mode to FileAccessProvider Add an opt-in session_scoped mode (with an optional explicit scope) that confines file-access tool operations to a working folder derived from the session id via the shared _storage_key_segment derivation under the file-access-specific "~access-" prefix, mirroring FileMemoryProvider. The mode fails closed (ValueError) when neither a scope nor a session id is available, creates the session folder in before_run, appends a session-isolation note to the tool instructions, and logs the derived folder at debug level. All eight tools route store calls through a single _session_path helper; ls/grep treat an empty directory as the session root and grep results stay session-relative. Default mode is byte-for-byte unchanged. Adds seven regression tests, including the COLLIDING_IDENTIFIERS attack strings parametrization, fail-closed coverage, scope override, and shared-store default regression. All harness file-access tests pass; the only full-suite failure is the pre-existing test_feature_stage.py::test_feature_id_allows_lowercase_values on main. Addresses microsoft#8539. * feat(core): wire file_access_session_scoped through create_harness_agent Expose the FileAccessProvider session-scoped mode from create_harness_agent via a new file_access_session_scoped flag (default False, preserving shared-store semantics), threaded through _assemble_context_providers and synchronized across the .pyi stub and the package AGENTS.md file-access section. Adds a pass-through regression test. Addresses microsoft#8539. * docs(core): describe scoped file access isolation relative to the workspace The session-scoped instruction suffix claimed files are never visible to other sessions, which is wrong when an explicit scope intentionally shares a workspace across sessions. Rephrase the suffix, the class docstring, and the session_scoped parameter docs to describe isolation relative to the resolved workspace (session or configured scope). Addresses review feedback on PR microsoft#8542. * fix(core): harden session-scoped file access boundaries Address review feedback on PR microsoft#8542: - Normalize ls/grep directories with _normalize_relative_path(..., is_directory=True) in scoped mode so a ".." directory cannot escape the session workspace through a permissive custom store. - Place every scoped working folder under a fixed ~access- namespace directory, so file access and file memory working folders cannot collide when both providers share one store root and a literal-safe identifier. - Treat a non-empty explicit scope as enabling scoped mode by itself, aligning with FileMemoryProvider(scope=...). Adds parent-traversal, namespace-collision, and scope-only regression tests and updates layout assertions to the namespaced folder shape. All harness suites pass; ruff clean.
1 parent 435012e commit 87d4d0a

6 files changed

Lines changed: 359 additions & 21 deletions

File tree

‎python/packages/core/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID
205205
- **`FileSystemAgentFileStore`** - Disk-backed store rooted under a configurable directory. Enforces relative-path normalization, root containment, and rejects symlink/reparse-point segments to prevent escape.
206206
- **`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`.
207207
- **`FileStoreEntry`** - `SerializationMixin` DTO returned by `list_children`, carrying an entry `name` and `type` (`"file"` or `"directory"`).
208-
- **`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.
208+
- **`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; pass `session_scoped=True` (with an optional explicit `scope`) to confine tool operations to a working folder derived from the session id or scope via the shared `_storage_key_segment` derivation (the provider fails closed when neither is available).
209209

210210
### File Memory Harness (`_harness/_file_memory.py`)
211211

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,7 @@ def _assemble_context_providers(
154154
disable_file_memory: bool,
155155
file_memory_store: AgentFileStore | None,
156156
file_access_store: AgentFileStore | None,
157+
file_access_session_scoped: bool,
157158
file_access_disable_write_tools: bool,
158159
file_access_disable_readonly_tool_approval: bool,
159160
file_access_disable_write_tool_approval: bool,
@@ -196,6 +197,7 @@ def _assemble_context_providers(
196197
disable_write_tools=file_access_disable_write_tools,
197198
disable_readonly_tool_approval=file_access_disable_readonly_tool_approval,
198199
disable_write_tool_approval=file_access_disable_write_tool_approval,
200+
session_scoped=file_access_session_scoped,
199201
)
200202
)
201203

@@ -330,6 +332,7 @@ def create_harness_agent(
330332
disable_file_memory: bool = False,
331333
file_memory_store: AgentFileStore | None = None,
332334
file_access_store: AgentFileStore | None = None,
335+
file_access_session_scoped: bool = False,
333336
file_access_disable_write_tools: bool = False,
334337
file_access_disable_readonly_tool_approval: bool = False,
335338
file_access_disable_write_tool_approval: bool = False,
@@ -454,6 +457,10 @@ def create_harness_agent(
454457
opt-in: when None (default), no FileAccessProvider is added and the agent has no
455458
file access tools. When set, a FileAccessProvider is added, giving the agent shared
456459
read/write file tools backed by the supplied store.
460+
file_access_session_scoped: When True, the FileAccessProvider confines tool operations
461+
to a working folder derived from the active session id, so files are isolated per
462+
session instead of shared across sessions. When False (default), the shared-store
463+
semantics are preserved. Only used when file_access_store is set.
457464
file_access_disable_write_tools: When True, the FileAccessProvider advertises only its
458465
read-only tools (read, read_lines, ls, grep); the write tools (write, delete, replace,
459466
replace_lines) are hidden. When False (default), all tools are advertised. Only
@@ -608,6 +615,7 @@ def create_harness_agent(
608615
disable_file_memory=disable_file_memory,
609616
file_memory_store=file_memory_store,
610617
file_access_store=file_access_store,
618+
file_access_session_scoped=file_access_session_scoped,
611619
file_access_disable_write_tools=file_access_disable_write_tools,
612620
file_access_disable_readonly_tool_approval=file_access_disable_readonly_tool_approval,
613621
file_access_disable_write_tool_approval=file_access_disable_write_tool_approval,

‎python/packages/core/agent_framework/_harness/_agent.pyi‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ def create_harness_agent(
7171
disable_file_memory: bool = False,
7272
file_memory_store: AgentFileStore | None = None,
7373
file_access_store: AgentFileStore | None = None,
74+
file_access_session_scoped: bool = False,
7475
file_access_disable_write_tools: bool = False,
7576
file_access_disable_readonly_tool_approval: bool = False,
7677
file_access_disable_write_tool_approval: bool = False,

0 commit comments

Comments
 (0)