xonecas.io
62159
Sy

symb / files

symb / docs / EDIT_TOOLS.md

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/