Imported from AndreDalwin/DrizzyAgent (src/tools/hashline-edit/AGENTS.md). Install upstream with npx skills add AndreDalwin/DrizzyAgent --skill hashline-edit. Copyright stays with the author.

src/tools/hashline-edit/ — Hash-Anchored File Edit Tool

Generated: 2026-03-06

OVERVIEW

24 files. Implements the hashline_edit tool — hash-anchored file editing where every line reference includes a content hash (LINE#ID). Validates hashes before applying edits, rejecting stale references.

THREE-OP MODEL

All edits use exactly 3 operations:

lines: null or lines: [] with replace = delete. delete: true at tool level = delete file.

EXECUTION PIPELINE

hashline-edit-executor.ts
  → normalize-edits.ts       # Parse RawHashlineEdit → HashlineEdit (validate op schema)
  → validation.ts            # Validate LINE#ID references (hash match, line exists)
  → edit-ordering.ts         # Sort bottom-up (by line number, descending)
  → edit-deduplication.ts    # Remove duplicate ops
  → edit-operations.ts       # Apply each op using edit-operation-primitives.ts
  → autocorrect-replacement-lines.ts  # Auto-fix indentation/formatting
  → hashline-edit-diff.ts    # Build diff output using diff-utils.ts

KEY FILES

LINE#ID FORMAT

{line_number}#{hash_id}

• hash_id: two chars from ZPMQVRWSNKTXJBYH (CID letters)
• Example: 42#VK means line 42 with hash VK
• Validation: recompute hash of current line content → must match stored hash
• Content separator: | (pipe) between hash tag and content in read output

AUTOCORRECT BEHAVIORS (built-in)

• Merged lines auto-expanded back to original count
• Indentation restored from original lines
• BOM and CRLF line endings preserved
• >>> prefix and diff markers in lines text auto-stripped

ERROR CASES

• Hash mismatch → edit rejected, diff shown with current state
• Overlapping ranges → detected and rejected
• Missing pos for replace → schema error
• lines: null with append/prepend → schema error

HOW LINE HASHES WORK

// Reading: every line gets tagged
"42#VK| function hello() {"

// Editing: reference by tag
{ op: "replace", pos: "42#VK", lines: "function hello(name: string) {" }

// If file changed since read: hash won't match → rejected before corruption