palyra.fs tool family provides the agent with controlled, scoped access to the host filesystem. It is divided into two primary categories: Workspace Tools (scoped to agent roots and session focus) and the OS File Tool (for broader system access in local desktop profiles). All filesystem operations are subject to strict path canonicalization, containment checks, and safety redaction.
Workspace Scoping and Path Resolution
Workspace tools operate on an ordered list of workspace roots derived from the agent configuration, session focus, and run-launch context. Path resolution ensures that an agent cannot traverse outside its assigned boundaries.Scoping Hierarchy
Theworkspace_scope module derives the active roots for a tool call by layering dynamic context over static configuration:
- Run-Launch Context: Extra roots, launch CWD, and exact file grants supplied via the
RunLaunchCliContextin the run’s parameter delta crates/palyra-daemon/src/application/tool_runtime/workspace_scope.rs#45-51. - Session Focus: The directory the operator is currently focused on in the UI, resolved as an
ActiveWorkspaceRootcrates/palyra-daemon/src/application/tool_runtime/workspace_scope.rs#32-38. - Agent Roots: The baseline directories configured for the specific agent crates/palyra-daemon/src/application/tool_runtime/workspace_scope.rs#85-93.
Security and Resolution
Every path is canonicalized before containment checks. To prevent TOCTOU (Time-of-Check Time-of-Use) attacks, file reads re-resolve the handle after opening to ensure the path wasn’t swapped crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#3-9. Data Flow: Workspace Path Resolution Sources: crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#1-14, crates/palyra-daemon/src/application/tool_runtime/workspace_scope.rs#1-16Workspace File Operations
Theworkspace_file module implements read, list-dir, and search tools.
| Tool Name | Key Function | Purpose |
|---|---|---|
palyra.fs.read_file | execute_read_file | Reads file content with optional line/byte windowing. |
palyra.fs.list_dir | execute_list_dir | Lists directory entries with metadata. |
palyra.fs.search | execute_search | Recursive grep-like search with traversal budgets. |
Safety and Redaction
Text output from these tools passes throughpalyra-safety before reaching the model. If secrets are detected, the content is replaced with placeholders (e.g., <redacted>), and the redacted flag is set in the output crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#118-149. Binary files are never returned as text; instead, they provide a SHA-256 digest and a short base64 prefix crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#114-117.
Sources: crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#37-51, crates/palyra-safety/src/lib.rs#1-9
Palyra Patch Document Format
Thepalyra.fs.apply_patch tool uses a specialized grammar designed for LLM reliability. It supports atomic application of multi-file changes.
Patch Grammar
The parser, located inpalyra-common, recognizes several operation headers:
*** Add File: <path>: For creating new files.*** Replace File: <path>: For full-file rewrites.*** Replace Line: <path>: For targeted single-line edits.*** Update File: <path>: For hunk-based edits using@@markers crates/palyra-daemon/src/application/tool_runtime/workspace_patch.rs#53-55.
Patch Execution Pipeline
Execution follows a strict fail-closed sequence:- Dry Run: The patch is parsed and planned against the filesystem without writing crates/palyra-daemon/src/application/tool_runtime/workspace_patch.rs#145-148.
- Risk Assessment: The plan is checked for high-risk operations (e.g., deleting security configs or lockfiles) crates/palyra-daemon/src/application/tool_runtime/workspace_patch/checkpoint_flow.rs#110-113.
- Preflight Checkpoint: A snapshot of the affected files is captured in the
JournalStorecrates/palyra-daemon/src/application/tool_runtime/workspace_patch/checkpoint_flow.rs#131-150. - Atomic Apply: Changes are written to disk. If any part fails, a best-effort rollback is performed crates/palyra-common/src/workspace_patch.rs#1-7.
- Post-change Checkpoint: A final snapshot is taken to verify the mutation crates/palyra-daemon/src/application/tool_runtime/workspace_patch/checkpoint_flow.rs#4-8.
OS File Access
Thepalyra.fs.os_file tool provides access to the broader operating system. It is intended for local desktop profiles where the agent acts as a user assistant.
Path Access Modes
TheOsFilePolicy determines what the tool can reach:
- Unrestricted: Full access to the OS (typically for local development).
- Strict: Limited to workspace roots, user home (
HOME/USERPROFILE), temp directories, and roots defined in thePALYRA_OS_FILE_ROOTSenvironment variable crates/palyra-daemon/src/application/tool_runtime/os_file.rs#3-9.
Supported Operations
The tool implements a flat schema for multiple operations via theOsFileOperation enum: Stat, Read, Write, Copy, Move, DeleteFile, DeleteEmptyDir, Mkdir, ListDir, and Search crates/palyra-daemon/src/application/tool_runtime/os_file.rs#89-102.
Sources: crates/palyra-daemon/src/application/tool_runtime/os_file.rs#17-42, crates/palyra-daemon/src/application/tool_runtime/os_file.rs#107-112
Implementation Details
Key Classes and Functions
WorkspaceReadFileInput: Defines the JSON schema for reading files crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#74-87.apply_workspace_patch: The core engine inpalyra-commonthat performs the actual filesystem mutations crates/palyra-common/src/workspace_patch.rs#1-7.capture_workspace_patch_checkpoint: Records the state of the workspace before/after a patch in theJournalStorecrates/palyra-daemon/src/application/tool_runtime/workspace_patch/checkpoint_flow.rs#131-150.redact_text_for_export: Apalyra-safetyfunction used by all filesystem tools to sanitize text before it is returned to the agent crates/palyra-safety/src/lib.rs#1-9.
Resource Limits
To prevent DoS or excessive resource consumption, all tools enforce hard limits:- Read Limit:
MAX_WORKSPACE_READ_FILE_BYTES(e.g., 128KB) crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#46. - Search Limit:
WORKSPACE_SEARCH_MAX_FILES(2,000 files) andWORKSPACE_SEARCH_MAX_DEPTH(32) crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#59-62. - Patch Limit:
max_patch_bytes(256KB) andmax_files_touched(64) crates/palyra-common/src/workspace_patch.rs#52-61.