@@ -0,0 +1,202 @@
1+# Edit Tools: Hashline-Anchored File Editing
2+
3+## Background
4+
5+The standard approaches to LLM-driven file editing all share the same fundamental
6+weakness: they require the model to reproduce file content it already saw.
7+
8+- **str_replace** (Claude Code, OpenCode, 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+
19+These are not model failures. They are harness failures. The model understood the
20+task but could not express the change reliably through the tool interface.
21+
22+Source: Can Boluk, "The Harness Problem" (Feb 2026). Benchmark of 16 models across
23+3 edit formats showed that format choice alone swings success rates by 10-60
24+percentage points.
25+
26+## Our Approach: Hashline
27+
28+Instead of making the model reproduce old content, we give it a stable, verifiable
29+identifier for every line. When the model reads a file, each line comes back tagged
30+with a 2-character content hash derived from SHA-256.
31+
32+The model references these tags to express edits. It never needs to reproduce
33+whitespace, indentation, or surrounding context. If it can recall a 2-char hex tag,
34+it knows what it is editing.
35+
36+If the file changed between the read and the edit, the hashes will not match and
37+the operation is rejected before any corruption can occur.
38+
39+## Open Tool
40+
41+**File:** `internal/mcp_tools/open.go`
42+
43+Opens a file in the TUI editor and returns hashline-tagged content to the LLM.
44+Each line is formatted as `linenum:hash|content`, where the hash is a 2-char hex
45+digest of that line's content.
46+
47+### Behaviour
48+
49+1. Validates the file path (absolute resolution, CWD-scoped, no traversal).
50+2. Reads the file from disk.
51+3. Records the file as "read" in the shared FileReadTracker.
52+4. Optionally extracts a line range (1-indexed start/end).
53+5. Sends the raw content to the TUI editor pane for display.
54+6. Computes hashline tags for each line.
55+7. Returns the tagged output to the LLM.
56+
57+The tagged output gives the model everything it needs for subsequent edits: line
58+numbers 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+
70+Modifies files using hash-anchored operations. Exactly one operation per call.
71+Returns 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
76+inserts new content in their place. Both anchors are validated against the current
77+file before any modification. The replacement content may have more or fewer lines
78+than the range it replaces.
79+
80+**Insert** adds new content after a single anchored line. The anchor is validated,
81+then the new lines are spliced in immediately after it. Existing lines below shift
82+down.
83+
84+**Delete** removes lines from a start anchor to an end anchor (inclusive). Both
85+anchors are validated. The lines between them (inclusive) are removed and the file
86+is compacted.
87+
88+**Create** writes a brand new file. It fails if the file already exists. It does
89+not require a prior Open call since there is no existing content to read. Parent
90+directories are created automatically.
91+
92+### Anchors
93+
94+An anchor is a pair of line number (1-indexed) and hash (2-char hex). The hash is
95+the first byte of the SHA-256 digest of the line's content. Both values come from
96+the Open tool's output.
97+
98+Before any edit, the handler re-reads the file from disk and validates each anchor
99+against the current content. If a hash does not match, the edit is rejected with a
100+clear error indicating the file changed. The model must re-Open the file to get
101+fresh hashes.
102+
103+### Fresh Hashes After Edit
104+
105+Every successful edit returns the entire updated file with new hashline tags. This
106+is critical for chaining: if the model needs to make a second edit, it must use the
107+hashes from the edit response, not the original Open response. Line numbers shift
108+after inserts and deletes, and content hashes change after replacements.
109+
110+## Safety Layers
111+
112+The system enforces four independent safety checks, any one of which can reject a
113+bad edit.
114+
115+### Read-Before-Edit
116+
117+**File:** `internal/mcp_tools/filetrack.go`
118+
119+Open and Edit share a FileReadTracker. When Open successfully reads a file, it
120+records the absolute path. When Edit receives a replace, insert, or delete, it
121+checks that the file was previously opened. If not, it returns an error directing
122+the model to Open the file first.
123+
124+This prevents the model from guessing hashes or editing files it has not seen.
125+Create operations bypass this check since they target files that do not exist yet.
126+
127+The tracker is thread-safe (sync.RWMutex) and scoped to the session lifetime.
128+
129+### Hash Validation
130+
131+**File:** `internal/hashline/hashline.go`
132+
133+Before any modification, the edit handler re-reads the file and validates every
134+anchor. The Anchor.Validate method checks that the line number is in range and that
135+the hash matches the current content. ValidateRange additionally checks that start
136+comes before end.
137+
138+This catches concurrent modifications, external edits, or stale hashes from a
139+previous edit in a chain.
140+
141+### Path Traversal Prevention
142+
143+Both Open and Edit resolve paths to absolute form, then verify the result is within
144+or below the current working directory. Paths containing ".." that escape the CWD
145+are rejected.
146+
147+### Operation Count Enforcement
148+
149+Each Edit call must contain exactly one operation. Zero operations or multiple
150+operations are rejected before any file I/O occurs.
151+
152+## Hashline Package
153+
154+**File:** `internal/hashline/hashline.go`
155+
156+The 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
159+2 hex characters. This gives 256 possible values per line. Collisions are possible
160+but rare for lines in the same file, and a collision only means the edit is not
161+rejected when it perhaps should be. It never causes corruption since the line number
162+is also checked.
163+
164+**TagLines** splits content by newline and produces a TaggedLine for each, with
165+sequential 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
170+content. ValidateRange validates a start-end pair and checks ordering.
171+
172+## Registration
173+
174+**File:** `cmd/symb/main.go`
175+
176+A single FileReadTracker is created and shared between the Open and Edit handlers.
177+Both tools are registered on the MCP proxy. After the Bubbletea program is created,
178+both 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,
194+tag formatting, anchor validation (in range, out of range, wrong hash), range
195+validation, and a full round-trip from tagging to validation.
196+
197+**Edit tool:** 13 tests. Covers replace (single line, multi-line, expanding),
198+insert, delete, create, create-fails-if-exists, hash mismatch rejection, no
199+operation, multiple operations, path traversal rejection, read-before-edit
200+enforcement, and create bypassing the read check.
201+
202+References: https://blog.can.ac/2026/02/12/the-harness-problem/ and the opencode source code.