# File Operation Skills

Skill-level file operation tools provide safe, enhanced file system
operations for agents.  All tools enforce path traversal guards, binary
file detection, and atomic writes.

## Tools

| Tool               | Capability   | Description                                      |
|--------------------|-------------|--------------------------------------------------|
| `skill/file-read`  | `read_only` | Read file with binary detection and size limits  |
| `skill/file-write` | `writes`    | Write file atomically with newline normalization |
| `skill/file-edit`  | `writes`    | Edit file with permission preservation           |
| `skill/file-delete`| `writes`    | Delete file with existence check                 |

## ReadFile

Reads file content with the following safety features:

- **Binary detection**: Rejects files identified as binary (PNG, ELF,
  ZIP, etc.) with an explicit error message.
- **Size limits**: Files exceeding 10 MB are rejected.
- **UTF-8 normalization**: Content is decoded with the requested
  encoding and normalized to valid UTF-8.
- **Line offset/limit**: Supports reading a specific range of lines.

### Example

```python
from cleveragents.skills.builtins.file_ops import register_skill_file_tools
from cleveragents.tool.registry import ToolRegistry
from cleveragents.tool.runner import ToolRunner

registry = ToolRegistry()
register_skill_file_tools(registry)
runner = ToolRunner(registry)

result = runner.execute("skill/file-read", {
    "path": "src/main.py",
    "sandbox_root": "/project",
})
print(result.output["content"])
```

### Error Cases

| Condition             | Error Message                                   |
|----------------------|--------------------------------------------------|
| Binary file          | `Binary file detected: 'path'`                  |
| File too large       | `File too large: N bytes exceeds limit`          |
| File not found       | `File not found: 'path'`                         |
| Path traversal       | `Path traversal detected: 'path' escapes ...`   |
| Not a regular file   | `Not a regular file: 'path'`                     |

## WriteFile

Writes content to a file using atomic operations:

1. Content is written to a temporary file in the same directory.
2. The temporary file is renamed to the target path using `os.replace`.
3. If any error occurs, the temporary file is cleaned up.

### Newline Normalization

The `newline_mode` parameter controls line ending conversion:

- `"preserve"` (default): No conversion.
- `"lf"`: Convert all line endings to `\n`.
- `"crlf"`: Convert all line endings to `\r\n`.

## EditFile

Edits files using string replacement with:

- **Atomic writes**: Same temp-file-then-rename strategy as WriteFile.
- **Permission preservation**: Original file permissions are restored.
- **Single or all replacements**: Controlled by `replace_all` flag.

## DeleteFile

Deletes a file with:

- **Existence check**: Returns `existed: false` for missing files.
- **Type check**: Rejects directory targets.
- **Path traversal guard**: Same as all other tools.

## Path Traversal Guards

All tools reject paths that would escape the sandbox root:

- Paths containing `..` segments that resolve outside the sandbox.
- Absolute paths that fall outside the sandbox directory.

The rejected path is included in the error message for diagnostics.

## File Size Limits

ReadFile enforces a 10 MB content size limit.  Files exceeding this
limit produce an explicit error rather than consuming excessive memory.

## Binary File Detection

ReadFile detects binary files by:

1. Checking for known binary file signatures (PNG, GIF, JPEG, ZIP,
   ELF, MZ/PE, gzip).
2. Heuristic: if more than 10% of the first 8192 bytes are non-text
   control characters, the file is classified as binary.