> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem Tools: Workspace and OS File Access

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * crates/palyra-cli/src/commands/status.rs
  * crates/palyra-common/src/redaction.rs
  * crates/palyra-common/src/workspace\_patch.rs
  * crates/palyra-daemon/src/application/code\_intel\_runtime.rs
  * crates/palyra-daemon/src/application/project\_facts.rs
  * crates/palyra-daemon/src/application/tool\_runtime/code\_intel.rs
  * crates/palyra-daemon/src/application/tool\_runtime/os\_file.rs
  * crates/palyra-daemon/src/application/tool\_runtime/workspace\_file.rs
  * crates/palyra-daemon/src/application/tool\_runtime/workspace\_patch.rs
  * crates/palyra-daemon/src/application/tool\_runtime/workspace\_patch/checkpoint\_flow\.rs
  * crates/palyra-daemon/src/application/tool\_runtime/workspace\_scope.rs
  * crates/palyra-daemon/src/application/verification.rs
  * crates/palyra-daemon/src/domain/workspace.rs
  * crates/palyra-safety/src/lib.rs
</details>

The `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

The `workspace_scope` module derives the active roots for a tool call by layering dynamic context over static configuration:

1. **Run-Launch Context**: Extra roots, launch CWD, and exact file grants supplied via the `RunLaunchCliContext` in the run's parameter delta [crates/palyra-daemon/src/application/tool\_runtime/workspace\_scope.rs#45-51](http://crates/palyra-daemon/src/application/tool_runtime/workspace_scope.rs#45-51).
2. **Session Focus**: The directory the operator is currently focused on in the UI, resolved as an `ActiveWorkspaceRoot` [crates/palyra-daemon/src/application/tool\_runtime/workspace\_scope.rs#32-38](http://crates/palyra-daemon/src/application/tool_runtime/workspace_scope.rs#32-38).
3. **Agent Roots**: The baseline directories configured for the specific agent [crates/palyra-daemon/src/application/tool\_runtime/workspace\_scope.rs#85-93](http://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](http://crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#3-9).

**Data Flow: Workspace Path Resolution**

```mermaid theme={null}
graph TD
    A["Tool Input Path"] --> B["resolve_workspace_file"]
    B --> C{"Workspace Scoping"}
    C --> D["Run-Launch Roots"]
    C --> E["Session Focus Root"]
    C --> F["Agent Config Roots"]
    D & E & F --> G["Canonicalize & Containment Check"]
    G --> H["ResolvedWorkspaceFile"]
    H --> I["OS File Handle"]
```

Sources: [crates/palyra-daemon/src/application/tool\_runtime/workspace\_file.rs#1-14](http://crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#1-14), [crates/palyra-daemon/src/application/tool\_runtime/workspace\_scope.rs#1-16](http://crates/palyra-daemon/src/application/tool_runtime/workspace_scope.rs#1-16)

## Workspace File Operations

The `workspace_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 through `palyra-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](http://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](http://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](http://crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#37-51), [crates/palyra-safety/src/lib.rs#1-9](http://crates/palyra-safety/src/lib.rs#1-9)

## Palyra Patch Document Format

The `palyra.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 in `palyra-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](http://crates/palyra-daemon/src/application/tool_runtime/workspace_patch.rs#53-55).

### Patch Execution Pipeline

Execution follows a strict fail-closed sequence:

1. **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](http://crates/palyra-daemon/src/application/tool_runtime/workspace_patch.rs#145-148).
2. **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](http://crates/palyra-daemon/src/application/tool_runtime/workspace_patch/checkpoint_flow.rs#110-113).
3. **Preflight Checkpoint**: A snapshot of the affected files is captured in the `JournalStore` [crates/palyra-daemon/src/application/tool\_runtime/workspace\_patch/checkpoint\_flow.rs#131-150](http://crates/palyra-daemon/src/application/tool_runtime/workspace_patch/checkpoint_flow.rs#131-150).
4. **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](http://crates/palyra-common/src/workspace_patch.rs#1-7).
5. **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](http://crates/palyra-daemon/src/application/tool_runtime/workspace_patch/checkpoint_flow.rs#4-8).

**Data Flow: Patch Execution with Checkpointing**

```mermaid theme={null}
graph TD
    A["palyra.fs.apply_patch Input"] --> B["workspace_patch::apply_workspace_patch (Dry Run)"]
    B --> C["assess_workspace_mutation_risk"]
    C --> D["capture_workspace_patch_checkpoint (Preflight)"]
    D --> E["apply_workspace_patch (Real Write)"]
    E --> F["capture_diagnostic_snapshot (Code Intel)"]
    F --> G["capture_workspace_patch_checkpoint (Post-change)"]
    G --> H["WorkspacePatchOutcome"]
```

Sources: [crates/palyra-daemon/src/application/tool\_runtime/workspace\_patch.rs#1-12](http://crates/palyra-daemon/src/application/tool_runtime/workspace_patch.rs#1-12), [crates/palyra-daemon/src/application/tool\_runtime/workspace\_patch/checkpoint\_flow.rs#82-108](http://crates/palyra-daemon/src/application/tool_runtime/workspace_patch/checkpoint_flow.rs#82-108), [crates/palyra-common/src/workspace\_patch.rs#124-133](http://crates/palyra-common/src/workspace_patch.rs#124-133)

## OS File Access

The `palyra.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

The `OsFilePolicy` 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 the `PALYRA_OS_FILE_ROOTS` environment variable [crates/palyra-daemon/src/application/tool\_runtime/os\_file.rs#3-9](http://crates/palyra-daemon/src/application/tool_runtime/os_file.rs#3-9).

### Supported Operations

The tool implements a flat schema for multiple operations via the `OsFileOperation` enum: `Stat`, `Read`, `Write`, `Copy`, `Move`, `DeleteFile`, `DeleteEmptyDir`, `Mkdir`, `ListDir`, and `Search` [crates/palyra-daemon/src/application/tool\_runtime/os\_file.rs#89-102](http://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](http://crates/palyra-daemon/src/application/tool_runtime/os_file.rs#17-42), [crates/palyra-daemon/src/application/tool\_runtime/os\_file.rs#107-112](http://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](http://crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#74-87).
* `apply_workspace_patch`: The core engine in `palyra-common` that performs the actual filesystem mutations [crates/palyra-common/src/workspace\_patch.rs#1-7](http://crates/palyra-common/src/workspace_patch.rs#1-7).
* `capture_workspace_patch_checkpoint`: Records the state of the workspace before/after a patch in the `JournalStore` [crates/palyra-daemon/src/application/tool\_runtime/workspace\_patch/checkpoint\_flow.rs#131-150](http://crates/palyra-daemon/src/application/tool_runtime/workspace_patch/checkpoint_flow.rs#131-150).
* `redact_text_for_export`: A `palyra-safety` function used by all filesystem tools to sanitize text before it is returned to the agent [crates/palyra-safety/src/lib.rs#1-9](http://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](http://crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#46).
* **Search Limit**: `WORKSPACE_SEARCH_MAX_FILES` (2,000 files) and `WORKSPACE_SEARCH_MAX_DEPTH` (32) [crates/palyra-daemon/src/application/tool\_runtime/workspace\_file.rs#59-62](http://crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#59-62).
* **Patch Limit**: `max_patch_bytes` (256KB) and `max_files_touched` (64) [crates/palyra-common/src/workspace\_patch.rs#52-61](http://crates/palyra-common/src/workspace_patch.rs#52-61).

Sources: [crates/palyra-daemon/src/application/tool\_runtime/workspace\_file.rs#53-71](http://crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#53-71), [crates/palyra-common/src/workspace\_patch.rs#37-50](http://crates/palyra-common/src/workspace_patch.rs#37-50)