Repair Escalation & Safety Guards
Relevant source files
The following files were used as context for generating this wiki page:
Repair Escalation & Safety Guards constitute the robust validation and recovery framework within the plugsuits code-editing engine. This system ensures that file modifications are performed deterministically while providing progressive error recovery for LLMs that produce malformed or stale edit instructions. It acts as a protective layer between the model's output and the filesystem, preventing unauthorized path traversal, stale writes, and corrupted file states.
The primary goal is to maintain high synchronization (sync) between the model's mental model of the code and the actual disk state. This is achieved through a combination of hashline-aware anchors, atomic writes, and a multi-tiered repair logic that can auto-correct common formatting errors before bailing to explicit human or model intervention.
Sources: README.md, packages/cea/src/tools/modify/AGENTS.md
1. Edit Validation and Hashline Integrity
The system utilizes a "hashline-native" edit engine. Instead of relying on fuzzy text matching, it uses unique line anchors generated during the read_file operation. These anchors, formatted as {line_number}#{hash_id}, ensure that an edit is applied to the exact line intended by the model, even if line numbers have shifted slightly.
Hash-Verified Safety
A critical safety guard is the expected_file_hash. When provided, the tool verifies the current hash of the target file against the hash the model saw during its last read. If they do not match, the edit is rejected to prevent "stale writes" where the model might overwrite changes made by a previous turn or an external process.
| Parameter | Type | Description |
|---|---|---|
path | string | Target file path. |
pos | string | Starting line anchor (e.g., 10#AB). |
end | string | Optional ending anchor for range replacements. |
expected_file_hash | string | Optional hash to ensure the file hasn't changed since it was last read. |
Sources: packages/cea/src/tools/modify/edit-file.ts:58-75, packages/cea/src/tools/modify/edit-file.test.ts:98-115
2. Progressive Repair & Escalation Logic
The "Repair Escalation" mechanism handles malformed inputs from weaker models. The engine doesn't immediately fail on syntax errors in the tool call; instead, it attempts to "repair" the input.
The Repair Pipeline
- Lenient Parsing: The system first attempts to parse input using a lenient Zod schema if the strict schema fails, specifically focusing on cases where the
linesfield might be missing or malformed. - Auto-Repair: The
validateAndRepairEditsfunction identifies common patterns of malformed LLM output, such as including line content within theposanchor string (e.g.,2#HR|content). - Escalation Bail: If the model repeatedly fails with the same error (like omitting the
linesfield), the system escalates by returning a diagnostic message that includes the content of the target lines to help the model recover.
This diagram illustrates the flow from receiving a tool call to either successful application or a diagnostic bail.
Sources: packages/cea/src/tools/modify/edit-file.ts:140-165, packages/cea/src/tools/modify/edit-file-repair.ts
Soft-Reject and Bail Thresholds
To prevent infinite loops of failed edits, the system implements thresholds:
- ESCALATION_BAIL_THRESHOLD: After 6+ identical failures on a specific anchor, the system returns a "soft-reject" string instead of throwing an error.
- FILE_BAIL_THRESHOLD: After 10+ total failures on a single file, it suggests the model use
write_fileto replace the entire file content as a fallback.
Sources: packages/cea/src/tools/modify/edit-file.test.ts:543-610
3. Filesystem Safety Guards (C-1, C-2, H-1)
The engine enforces strict filesystem invariants to prevent the agent from escaping the project context or leaving the filesystem in an inconsistent state.
Path and Symlink Protection (C-1, C-2)
The assertWriteSafety utility (derived from safety-utils) performs the following checks:
- Path Traversal (C-1): Blocks any path containing
..segments or absolute paths that resolve outside the definedrootDir. - Symlink Guard (C-2): Blocks edits or writes through symbolic links to prevent the agent from accidentally modifying system files or files outside the workspace.
Atomic Write Operations (H-1)
All file modifications use an atomic write strategy (safeAtomicWriteFile). The engine writes the new content to a temporary file first and then renames it to the target path. This ensures:
- No partial writes occur if the process crashes.
- File integrity is maintained during the transition.
- No temporary file residue is left behind in the directory.
Sources: packages/cea/src/tools/modify/edit-file.ts:175-195, packages/cea/src/tools/modify/write-file.test.ts:184-230, packages/cea/src/tools/modify/edit-file.test.ts:688-710
4. Diagnostics and Reporting
When an edit is applied, the system returns a structured report. If the repair logic was used, warnings are appended to this report to inform the model (and the user) about the adjustments made.
This sequence shows the interaction between the model, the tool's internal validation, and the final filesystem write.
Sources: packages/cea/src/tools/modify/edit-file.ts:79-99, packages/cea/src/tools/modify/edit-file.test.ts:390-410
Conclusion
The Repair Escalation & Safety Guards system ensures that plugsuits remains a reliable and safe tool for autonomous code editing. By prioritizing deterministic hashline anchors and enforcing strict filesystem boundaries (C-1, C-2, H-1), the project mitigates the risks associated with LLM non-determinism. The multi-tiered repair logic further enhances the system's resilience, allowing it to guide models through errors rather than failing abruptly.
Sources: packages/cea/src/tools/modify/AGENTS.md, README.md