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:

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:

{
  "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:

{
  "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)

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

Single line change — no guard rules triggered.

Large Change

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

Triggers: LARGE_CHANGE — requires approval.

Block Deletion

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

Triggers: BLOCK_DELETION, LARGE_CHANGE — requires explicit approval.

Manifest Edit

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

Triggers: MANIFEST_EDIT — classified as dependency install.

Related