62159
Sy
symb / files
8.1 KB
1# Edit Tools: Hashline-Anchored File Editing 2 3## Background 4 5The standard approaches to LLM-driven file editing all share the same fundamental 6weakness: they require the model to reproduce file content it already saw. 7 8- **str_replace** (Claude Code, most agents) makes the model reproduce 9 the exact old text including whitespace. Multiple matches or slight misrecall 10 cause failures. The "string not found" error is one of the most common complaints. 11 12- **apply_patch** (OpenAI Codex) expects models to produce a custom diff format. 13 Models not specifically tuned for it fail catastrophically. Grok 4 had a 50.7% 14 patch failure rate in benchmarks. 15 16- **Cursor's approach** trains a separate 70B model just to apply edits. Even then, 17 full file rewrites outperform diffs for files under 400 lines. 18 19These are not model failures. They are harness failures. The model understood the 20task but could not express the change reliably through the tool interface. 21 22Source: Can Boluk, "The Harness Problem" (Feb 2026). Benchmark of 16 models across 233 edit formats showed that format choice alone swings success rates by 10-60 24percentage points. 25 26## Our Approach: Hashline 27 28Instead of making the model reproduce old content, we give it a stable, verifiable 29identifier for every line. When the model reads a file, each line comes back tagged 30with a 2-character content hash derived from SHA-256. 31 32The model references these tags to express edits. It never needs to reproduce 33whitespace, indentation, or surrounding context. If it can recall a 2-char hex tag, 34it knows what it is editing. 35 36If the file changed between the read and the edit, the hashes will not match and 37the operation is rejected before any corruption can occur. 38 39## Open Tool 40 41**File:** `internal/mcp_tools/open.go` 42 43Opens a file in the TUI editor and returns hashline-tagged content to the LLM. 44Each line is formatted as `linenum:hash|content`, where the hash is a 2-char hex 45digest of that line's content. 46 47### Behaviour 48 491. Validates the file path (absolute resolution, CWD-scoped, no traversal). 502. Reads the file from disk. 513. Records the file as "read" in the shared FileReadTracker. 524. Optionally extracts a line range (1-indexed start/end). 535. Sends the raw content to the TUI editor pane for display. 546. Computes hashline tags for each line. 557. Returns the tagged output to the LLM. 56 57The tagged output gives the model everything it needs for subsequent edits: line 58numbers for positioning and content hashes for verification. 59 60### Parameters 61 62- **file** (required): Path to the file. 63- **start** (optional): Starting line number, 1-indexed. 64- **end** (optional): Ending line number, 1-indexed. 65 66## Edit Tool 67 68**File:** `internal/mcp_tools/edit.go` 69 70Modifies files using hash-anchored operations. Exactly one operation per call. 71Returns the full updated file with fresh hashes after every edit. 72 73### Operations 74 75**Replace** removes lines from a start anchor to an end anchor (inclusive) and 76inserts new content in their place. Both anchors are validated against the current 77file before any modification. The replacement content may have more or fewer lines 78than the range it replaces. 79 80**Insert** adds new content after a single anchored line. The anchor is validated, 81then the new lines are spliced in immediately after it. Existing lines below shift 82down. 83 84**Delete** removes lines from a start anchor to an end anchor (inclusive). Both 85anchors are validated. The lines between them (inclusive) are removed and the file 86is compacted. 87 88**Create** writes a brand new file. It fails if the file already exists. It does 89not require a prior Open call since there is no existing content to read. Parent 90directories are created automatically. 91 92### Anchors 93 94An anchor is a pair of line number (1-indexed) and hash (2-char hex). The hash is 95the first byte of the SHA-256 digest of the line's content. Both values come from 96the Open tool's output. 97 98Before any edit, the handler re-reads the file from disk and validates each anchor 99against the current content. If a hash does not match, the edit is rejected with a 100clear error indicating the file changed. The model must re-Open the file to get 101fresh hashes. 102 103### Fresh Hashes After Edit 104 105Every successful edit returns the entire updated file with new hashline tags. This 106is critical for chaining: if the model needs to make a second edit, it must use the 107hashes from the edit response, not the original Open response. Line numbers shift 108after inserts and deletes, and content hashes change after replacements. 109 110## Safety Layers 111 112The system enforces four independent safety checks, any one of which can reject a 113bad edit. 114 115### Read-Before-Edit 116 117**File:** `internal/mcp_tools/filetrack.go` 118 119Open and Edit share a FileReadTracker. When Open successfully reads a file, it 120records the absolute path. When Edit receives a replace, insert, or delete, it 121checks that the file was previously opened. If not, it returns an error directing 122the model to Open the file first. 123 124This prevents the model from guessing hashes or editing files it has not seen. 125Create operations bypass this check since they target files that do not exist yet. 126 127The tracker is thread-safe (sync.RWMutex) and scoped to the session lifetime. 128 129### Hash Validation 130 131**File:** `internal/hashline/hashline.go` 132 133Before any modification, the edit handler re-reads the file and validates every 134anchor. The Anchor.Validate method checks that the line number is in range and that 135the hash matches the current content. ValidateRange additionally checks that start 136comes before end. 137 138This catches concurrent modifications, external edits, or stale hashes from a 139previous edit in a chain. 140 141### Path Traversal Prevention 142 143Both Open and Edit resolve paths to absolute form, then verify the result is within 144or below the current working directory. Paths containing ".." that escape the CWD 145are rejected. 146 147### Operation Count Enforcement 148 149Each Edit call must contain exactly one operation. Zero operations or multiple 150operations are rejected before any file I/O occurs. 151 152## Hashline Package 153 154**File:** `internal/hashline/hashline.go` 155 156The hashline package is a standalone library with no dependencies on the tool layer. 157 158**LineHash** computes SHA-256 of a line's content and returns the first byte as 1592 hex characters. This gives 256 possible values per line. Collisions are possible 160but rare for lines in the same file, and a collision only means the edit is not 161rejected when it perhaps should be. It never causes corruption since the line number 162is also checked. 163 164**TagLines** splits content by newline and produces a TaggedLine for each, with 165sequential numbering starting at a given offset. 166 167**FormatTagged** joins tagged lines into the string format returned to the LLM. 168 169**Anchor** pairs a line number and hash. Validate checks both against actual file 170content. ValidateRange validates a start-end pair and checks ordering. 171 172## Registration 173 174**File:** `cmd/symb/main.go` 175 176A single FileReadTracker is created and shared between the Open and Edit handlers. 177Both tools are registered on the MCP proxy. After the Bubbletea program is created, 178both handlers receive a reference to it so they can send messages to the TUI. 179 180## Comparison With Other Approaches 181 182| Property | str_replace | apply_patch | Hashline | 183|---|---|---|---| 184| Model must reproduce old content | Yes | Yes (as diff context) | No | 185| Sensitive to whitespace | Very | Somewhat | Not at all | 186| Detects concurrent changes | No (silent corruption) | No | Yes (hash mismatch) | 187| Requires model-specific tuning | No | Effectively yes | No | 188| Enforces read-before-edit | Varies by agent | No | Yes | 189| Token cost of anchoring | High (full old text) | Medium (context lines) | Low (2-char hash) | 190 191## Test Coverage 192 193**hashline package:** 7 tests, 96.7% coverage. Tests cover hashing determinism, 194tag formatting, anchor validation (in range, out of range, wrong hash), range 195validation, and a full round-trip from tagging to validation. 196 197**Edit tool:** 13 tests. Covers replace (single line, multi-line, expanding), 198insert, delete, create, create-fails-if-exists, hash mismatch rejection, no 199operation, multiple operations, path traversal rejection, read-before-edit 200enforcement, and create bypassing the read check. 201 202References: https://blog.can.ac/2026/02/12/the-harness-problem/