---
title: File Edit Guard
url: https://arcana.otnelhq.com/docs/file-edit-guard
---

New in v0.4.0 

Line-level analysis with stable rule IDs and ML evidence in RunProof.

# File Edit Guard

The **File Edit Guard** analyzes every file mutation at the line level to detect destructive patterns before they execute. It classifies edits with stable rule IDs that surface in the TUI, approval metadata, and RunProof ML evidence.

## How It Works

When the agent attempts to edit, write, or patch a file, the guard:

1. **Computes diff stats** — Lines added, deleted, changed, and the change ratio
2. **Analyzes blast radius** — Max consecutive additions/deletions, unchanged prefix/suffix
3. **Classifies the edit** — Assigns one or more stable rule IDs
4. **Routes to permission** — Determines if approval is needed
5. **Records evidence** — Rules appear in RunProof ML evidence for audit

## Guard Rules

Each edit is classified with one or more rules:

| Rule ID | Trigger | Severity |
| --- | --- | --- |
| `WHOLESALE_REPLACEMENT` | Change ratio exceeds threshold (default 80%) | High |
| `LARGE_CHANGE` | Total changed lines exceeds threshold (default 100) | Medium |
| `BLOCK_DELETION` | 20+ consecutive lines deleted | High |
| `BLOCK_INSERTION` | 30+ consecutive lines inserted | Medium |
| `MANIFEST_EDIT` | Edit to `package.json`, `Cargo.toml`, etc. | Medium |
| `PERMISSION_POLICY_EDIT` | Edit to permission/policy files | High |
| `SELF_AWARENESS_DESTRUCTIVE` | Destructive edit to self-awareness files | High |
| `FILE_DELETE` | File deletion via `apply_patch` | High |
| `FILE_MOVE` | File move/rename via `apply_patch` | Medium |

## TUI Display

Guard rules appear as chips in the TUI permission dialog:

- `[WHOLESALE REPLACEMENT]` — Red chip, requires explicit approval
- `[BLOCK DELETION]` — Red chip, highlights destructive pattern
- `[LARGE CHANGE]` — Yellow chip, informational
- `[MANIFEST EDIT]` — Yellow chip, dependency changes
- `[PERMISSION POLICY]` — Red chip, security-sensitive
- `[FILE DELETE]` — Red chip, file removal

## ML Evidence in RunProof

Guard rules are recorded in RunProof ML evidence for audit:

```json
{
  "ml_evidence": {
    "file_edit_guard": {
      "rules": ["BLOCK_DELETION", "MANIFEST_EDIT"],
      "destructive": true,
      "file": "src/auth.ts",
      "lines_deleted": 45,
      "lines_added": 12,
      "max_consecutive_deletions": 45,
      "change_ratio": 0.78
    }
  }
}
```

## Dependency Manifest Detection

Edits to dependency files are automatically classified as `MANIFEST_EDIT`:

- `package.json` / `package-lock.json`
- `Cargo.toml` / `Cargo.lock`
- `go.mod` / `go.sum`
- `requirements.txt` / `Pipfile`
- `pyproject.toml`

The signal engine classifies these as **installs** for analysis purposes.

## Configuration

Guard thresholds can be tuned in `arcana.json`:

```json
{
  "guard": {
    "large_change_lines": 100,
    "wholesale_threshold": 0.8,
    "block_deletion_lines": 20,
    "block_insertion_lines": 30,
    "backup_threshold": 0.5
  }
}
```

## Examples

### Safe Edit (No Guard)

```diff
  // src/utils.ts
- const x = 1;
+ const x = 2;
```

Single line change — no guard rules triggered.

### Large Change

```diff
  // src/auth.ts
- // 50 lines of old auth logic
+ // 50 lines of new auth logic
```

Triggers: `LARGE_CHANGE` — requires approval.

### Block Deletion

```diff
  // src/api.ts
- // 25 consecutive lines deleted
+ // 3 new lines added
```

Triggers: `BLOCK_DELETION`, `LARGE_CHANGE` — requires explicit approval.

### Manifest Edit

```diff
  // package.json
  "dependencies": {
+   "new-package": "^1.0.0"
  }
```

Triggers: `MANIFEST_EDIT` — classified as dependency install.

## Related

- [Trust & Security](/docs/trust-boundaries) — Security model and trust boundaries
- [Subagents](/docs/subagents) — Delegation with guard rules applied
- [Autonomy Modes](/docs/autonomy-modes) — Control how much autonomy agents have