feat(hashline): Phase 3 — hashline_edit tool

[randomm]

Context

Part of the hashline EPIC (#209). Depends on Phase 1 (#210) and Phase 2 (#211) being merged first. You need applyHashlineEdits and HashlineEdit from src/tool/hashline.ts, and the OPENCODE_EXPERIMENTAL_HASHLINE flag from Phase 2.

Read the EPIC (#209), Phase 1 (#210), and Phase 2 (#211) before starting.

What You Are Building

Three things:

• packages/opencode/src/tool/hashline_edit.ts — the tool definition
• packages/opencode/src/tool/hashline_edit.txt — the description shown to the model
• A one-line export addition to edit.ts (see below)

Do NOT otherwise modify edit.ts, edit.txt, or any other existing tool.

Required Change to edit.ts

normalizeLineEndings is defined in edit.ts line 23 but is not exported. Add export:

// Change from:
function normalizeLineEndings(text: string): string {
// To:
export function normalizeLineEndings(text: string): string {

This is the only change to edit.ts. trimDiff is already exported at line 582.

Required Imports

import z from "zod"
import * as path from "path"
import { Tool } from "./tool"
import { Bus } from "../bus"
import { File } from "../file"
import { FileWatcher } from "../file/watcher"
import { FileTime } from "../file/time"
import { LSP } from "../lsp"
import { Instance } from "../project/instance"
import { Snapshot } from "@/snapshot"
import { Filesystem } from "../util/filesystem"
import { assertExternalDirectory } from "./external-directory"
import { createTwoFilesPatch, diffLines } from "diff"
import { trimDiff, normalizeLineEndings } from "./edit"
import { applyHashlineEdits } from "./hashline"
import type { HashlineEdit } from "./hashline"
import DESCRIPTION from "./hashline_edit.txt"

Note: HashlineMismatchError and HashlineNoOpError are NOT imported — they are never caught or referenced in this file. They propagate naturally as unhandled exceptions. Importing them without using them would cause a lint error.

Tool Schema

const AnchorSchema = z.string().regex(
  /^\d+[\u4E00-\u9FFF]$/,
  "Anchor must be a line number followed by a single CJK character, e.g. '14丐'"
)

const EditSchema = z.discriminatedUnion("op", [
  z.object({
    op: z.literal("set_line"),
    anchor: AnchorSchema.describe("The line to replace, e.g. '14丐'"),
    new_text: z.string().describe("Replacement text. Empty string deletes the line."),
  }),
  z.object({
    op: z.literal("replace_lines"),
    start_anchor: AnchorSchema.describe("First line of the range to replace"),
    end_anchor: AnchorSchema.describe("Last line of the range to replace (inclusive)"),
    new_text: z.string().describe("Replacement text. Empty string deletes the range."),
  }),
  z.object({
    op: z.literal("insert_after"),
    anchor: AnchorSchema.describe("Insert new lines after this line"),
    text: z.string().min(1).describe("Text to insert (must be non-empty)"),
  }),
])

const HashlineEditParams = z.object({
  filePath: z.string().describe("Absolute path to the file to edit"),
  edits: z.array(EditSchema).min(1).describe("List of edit operations to apply atomically"),
})

Tool Execute Logic

async execute(params, ctx) {
  const filePath = path.isAbsolute(params.filePath)
    ? params.filePath
    : path.join(Instance.directory, params.filePath)

  await assertExternalDirectory(ctx, filePath)

  let diff = ""
  let contentOld = ""
  let contentNew = ""

  await FileTime.withLock(filePath, async () => {
    const file = Bun.file(filePath)
    const stats = await file.stat().catch(() => {})
    if (!stats) throw new Error(`File ${filePath} not found`)
    if (stats.isDirectory()) throw new Error(`Path is a directory: ${filePath}`)

    // Throws if hashline_read was not called on this file in this session.
    await FileTime.assert(ctx.sessionID, filePath)

    contentOld = await file.text()

    // Synchronous — do NOT use await.
    // Throws HashlineMismatchError or HashlineNoOpError on failure.
    // Do NOT catch these — let them propagate through withLock (which re-throws via try/finally).
    // If either error is thrown, execution does NOT reach the code below the lock.
    // contentOld/contentNew remaining "" is irrelevant — those lines are never reached.
    contentNew = applyHashlineEdits(contentOld, params.edits)

    diff = trimDiff(
      createTwoFilesPatch(filePath, filePath, normalizeLineEndings(contentOld), normalizeLineEndings(contentNew))
    )

    await ctx.ask({
      permission: "edit",
      patterns: [path.relative(Instance.worktree, filePath)],
      always: ["*"],
      metadata: { filepath: filePath, diff },
    })

    await file.write(contentNew)
    await Bus.publish(File.Event.Edited, { file: filePath })
    await Bus.publish(FileWatcher.Event.Updated, { file: filePath, event: "change" })
    contentNew = await file.text()
    diff = trimDiff(
      createTwoFilesPatch(filePath, filePath, normalizeLineEndings(contentOld), normalizeLineEndings(contentNew))
    )
    FileTime.read(ctx.sessionID, filePath)
  })

  // Only reached on success (no thrown errors above)
  const filediff: Snapshot.FileDiff = {
    file: filePath,
    before: contentOld,
    after: contentNew,
    additions: 0,
    deletions: 0,
  }
  for (const change of diffLines(contentOld, contentNew)) {
    if (change.added) filediff.additions += change.count || 0
    if (change.removed) filediff.deletions += change.count || 0
  }

  // Note the nested structure: { metadata: { ... } }
  ctx.metadata({
    metadata: {
      diff,
      filediff,
      diagnostics: {},
    },
  })

  let output = "Edit applied successfully."
  await LSP.touchFile(filePath, true)
  const diagnostics = await LSP.diagnostics()
  const normalizedFilePath = Filesystem.normalizePath(filePath)
  const issues = diagnostics[normalizedFilePath] ?? []
  const errors = issues.filter((item) => item.severity === 1)
  if (errors.length > 0) {
    const limited = errors.slice(0, 20)
    const suffix = errors.length > 20 ? `\n... and ${errors.length - 20} more` : ""
    output += `\n\nLSP errors detected in this file, please fix:\n<diagnostics file="${filePath}">\n${limited.map(LSP.Diagnostic.pretty).join("\n")}${suffix}\n</diagnostics>`
  }

  return {
    metadata: { diagnostics, diff, filediff },
    title: `${path.relative(Instance.worktree, filePath)}`,
    output,
  }
},

Tool Description File (hashline_edit.txt)

Write clear instructions for the model. Keep under 60 lines. Look at edit.txt for style.

Must include:

1. Purpose: Applies precise line-addressed edits using CJK hash anchors from hashline_read. All edits applied atomically.
2. Prerequisite: Call hashline_read first. Anchors from the regular read tool will NOT work.
3. Three operations:
   • set_line: Replace single line. new_text: "" deletes the line.
   • replace_lines: Replace contiguous range (inclusive). new_text: "" deletes the range.
   • insert_after: Insert after anchor line. text must be non-empty.
4. Anchor format: Copy LINENUM꜀ prefix verbatim from hashline_read output. Do NOT include line content. Example: hashline_read shows 42丐 return foo() → anchor is 42丐.
5. Batching: All edits for a file in one call. Re-read with hashline_read before further edits.
6. On hash mismatch: Error shows current file with updated anchors (changed lines prefixed →). Copy new anchors and retry.
7. Example:

   // hashline_read output:
   3丒export function greet(name: string) {
   4专  return "hello"
   5且}
   // hashline_edit call:
   { "filePath": "/path/to/file.ts", "edits": [
     { "op": "set_line", "anchor": "4专", "new_text": "  return `hello, ${name}`" }
   ]}
   

Registry Wiring

Step 1 — Update the registry line added in Phase 2.

Find this line in registry.ts all() array (added by Phase 2):

// BEFORE (Phase 2 added this — find it and edit it):
...(Flag.OPENCODE_EXPERIMENTAL_HASHLINE ? [HashlineReadTool] : []),

// AFTER (replace the above line — do NOT add a new line):
...(Flag.OPENCODE_EXPERIMENTAL_HASHLINE ? [HashlineReadTool, HashlineEditTool] : []),

Do NOT add a second spread line — that would register HashlineReadTool twice.

Step 2 — Suppress edit (but NOT write) when hashline is active.

write is used for new file creation and full rewrites — hashline has no equivalent. Only edit is superseded. Update the existing filter in tools():

// Before (existing code):
if (t.id === "edit" || t.id === "write") return !usePatch

// After:
if (t.id === "edit") return !usePatch && !Flag.OPENCODE_EXPERIMENTAL_HASHLINE
if (t.id === "write") return !usePatch

Tests

Create file: packages/opencode/test/tool/hashline_edit.test.ts

Pattern: create temp file → call hashline_read execute to get valid anchors → call hashline_edit execute.

Required test cases:

1. set_line replaces correct line; file on disk updated
2. replace_lines replaces a range correctly
3. insert_after inserts at correct position
4. Multiple edits in one call all applied
5. HashlineMismatchError propagates when anchor hash doesn't match
6. HashlineNoOpError propagates when edits produce identical content
7. Calling without prior hashline_read throws FileTime.assert error
8. Non-existent file → clear File not found: error
9. After successful edit, re-reading with hashline_read shows updated content
10. Registry filtering: with process.env.OPENCODE_EXPERIMENTAL_HASHLINE = "1" set before accessing Flag, edit tool is absent from tools() result; write is still present. (Because Flag.OPENCODE_EXPERIMENTAL_HASHLINE is a dynamic getter added in Phase 2, setting process.env before reading it works correctly.)

File Conventions

• Prefer const over let; avoid else — prefer early returns
• No // TODO, // FIXME, as any, @ts-ignore
• Max 500 lines per file

Acceptance Criteria

• src/tool/hashline_edit.ts created, exports HashlineEditTool
• src/tool/hashline_edit.txt created with clear model instructions
• normalizeLineEndings exported from edit.ts (one-line change only)
• HashlineEditTool registered in registry.ts all() (Phase 2 line updated, not duplicated)
• When flag active: edit absent from tool list, write still present
• All 10 tests pass: bun test test/tool/hashline_edit.test.ts
• bun run typecheck passes with 0 errors
• bun test passes with 0 failures (no regressions)
• edit.ts modified only by adding export to normalizeLineEndings

Quality Gates (Non-Negotiable)

• TDD: Write failing tests first, then implement
• Local verification: bun run typecheck && bun test pass before completion
• No suppressions: No as any, @ts-ignore, // eslint-disable

[randomm]

Adversarial Review — Corrections Required

CRITICAL: normalizeLineEndings is NOT exported from edit.ts

Issue says: Import trimDiff and normalizeLineEndings from ./edit

Actual: normalizeLineEndings is defined at edit.ts:23 as a non-exported local function. Only trimDiff (line 582) is exported.

Fix: Either export it in Phase 1 or Phase 2 (add export to the function), or inline the one-liner in hashline_edit.ts:

// Inline — do not import from edit.ts (it's not exported)
function normalizeLineEndings(text: string): string {
  return text.replaceAll("\r\n", "\n")
}

Update edit.ts to export it if you want to share it:

export function normalizeLineEndings(text: string): string {
  return text.replaceAll("\r\n", "\n")
}

This is a one-line change to edit.ts — acceptable since it's an additive export, not a behavioural change.

---

CRITICAL: Flag does not exist — exact definition required

Issue says: "Add OPENCODE_EXPERIMENTAL_HASHLINE to src/flag.ts"

Actual file path: src/flag/flag.ts (not src/flag.ts). Add this line inside the Flag namespace following the OPENCODE_EXPERIMENTAL_LSP_TOOL pattern (line 49):

export const OPENCODE_EXPERIMENTAL_HASHLINE = OPENCODE_EXPERIMENTAL || truthy("OPENCODE_EXPERIMENTAL_HASHLINE")

Without this, Flag.OPENCODE_EXPERIMENTAL_HASHLINE is undefined and TypeScript will fail to compile.

---

CRITICAL: Missing imports — compilation will fail

The issue says "same as edit.ts lines 112-153" for the metadata/LSP block but does not list the required imports. These are all needed:

import { Bus } from "../bus"
import { File } from "../file"
import { FileWatcher } from "../file/watcher"
import { FileTime } from "../file/time"
import { Snapshot } from "@/snapshot"
import { LSP } from "../lsp"
import { Filesystem } from "../util/filesystem"
import { createTwoFilesPatch, diffLines } from "diff"
import { trimDiff } from "./edit"             // exported ✓
// normalizeLineEndings — see critical issue above, either export from edit.ts or inline
import { assertExternalDirectory } from "./external-directory"
import { Instance } from "../project/instance"

Add a complete imports section to the issue.

---

CRITICAL: ctx.metadata() API — wrong call pattern

Issue says: "same as edit.ts lines 112-153" without showing the exact call.

Actual edit.ts lines 124-130:

ctx.metadata({
  metadata: {
    diff,
    filediff,
    diagnostics: {},
  },
})

Note the nested metadata: key inside the argument object. A developer writing ctx.metadata({ diff, filediff }) will get a type error. Show this explicitly.

---

CRITICAL: applyHashlineEdits is synchronous but issue uses await

Issue says: contentNew = await applyHashlineEdits(contentOld, params.edits)

Phase 1 defines applyHashlineEdits as synchronous (function applyHashlineEdits(...): string). Using await on a sync function works in JS/TS but is misleading. Be explicit: either define it as async in Phase 1 or drop the await here. Recommend keeping it synchronous and writing:

contentNew = applyHashlineEdits(contentOld, params.edits)

---

ISSUE: Suppressing write tool when hashline is active — questionable

Issue says: When OPENCODE_EXPERIMENTAL_HASHLINE is active, suppress write (full file rewrite) alongside edit.

Problem: write is used for creating new files with oldString: "" and for complete file rewrites when patching is impractical. Hashline mode has no equivalent for creating new files from scratch. Suppressing write means the model can't create new files at all in hashline mode.

Fix: Do NOT suppress write. Only suppress edit:

if (t.id === "edit") {
  return !usePatch && !Flag.OPENCODE_EXPERIMENTAL_HASHLINE
}
// write remains available in all modes — needed for new file creation

---

ISSUE: FileTime interoperability — must confirm hashline_read sets the read timestamp

Issue says: FileTime.assert(ctx.sessionID, filePath) will throw if file not read first.

Key question: FileTime.read() stores reads by sessionID + filePath key regardless of which tool called it. As long as Phase 2 (hashline_read) calls FileTime.read(ctx.sessionID, filePath), Phase 3's FileTime.assert will pass. Verify Phase 2 includes this call — it is listed in Phase 2's "Copy these behaviours" but should be explicitly cross-referenced here: "This works because hashline_read calls FileTime.read(). You must NOT call hashline_edit without first calling hashline_read in the same session."

---

ISSUE: Snapshot.FileDiff — must include filediff in metadata

The metadata block in edit.ts (lines 112-122) builds a Snapshot.FileDiff with diffLines(). The issue's "same as lines 112-153" is too vague. Show the complete block explicitly:

const filediff: Snapshot.FileDiff = {
  file: filePath,
  before: contentOld,
  after: contentNew,
  additions: 0,
  deletions: 0,
}
for (const change of diffLines(contentOld, contentNew)) {
  if (change.added) filediff.additions += change.count || 0
  if (change.removed) filediff.deletions += change.count || 0
}
ctx.metadata({ metadata: { diff, filediff, diagnostics: {} } })

---

IMPROVEMENT: Test 10 is incorrect — registry filtering test needs clarification

Issue says: "When OPENCODE_EXPERIMENTAL_HASHLINE is active, regular edit tool is NOT in the tool list (verify registry filtering)"

In tests, Flag.OPENCODE_EXPERIMENTAL_HASHLINE is evaluated at module load time (it's a const). To test this, you need to set process.env.OPENCODE_EXPERIMENTAL_HASHLINE = "1" before importing registry. This is non-trivial to test correctly. Add guidance: "Use OPENCODE_EXPERIMENTAL_HASHLINE=1 bun test to run this test, or mock the Flag value."

[randomm]

Second Adversarial Pass — Corrections

CRITICAL: OPENCODE_EXPERIMENTAL_HASHLINE must be a dynamic getter, not a const

Issue says: Add to src/flag/flag.ts:

export const OPENCODE_EXPERIMENTAL_HASHLINE = OPENCODE_EXPERIMENTAL || truthy("OPENCODE_EXPERIMENTAL_HASHLINE")

Problem: This is a module-level const evaluated once at import time. Test 10 requires toggling the flag between tests via process.env. Setting process.env after import has zero effect on an already-evaluated const. This makes Test 10 impossible to implement as a standard unit test.

Looking at flag.ts lines 67–150: all flags that need to be testable at runtime use Object.defineProperty with a dynamic getter. This is the established pattern for this exact problem.

Fix: Add the flag as a dynamic getter (same pattern as OPENCODE_DISABLE_CLAUDE_CODE at line 67):

// In flag.ts, INSTEAD of the const — add after the other experimental flags:
Object.defineProperty(Flag, "OPENCODE_EXPERIMENTAL_HASHLINE", {
  get() {
    return Flag.OPENCODE_EXPERIMENTAL || truthy("OPENCODE_EXPERIMENTAL_HASHLINE")
  },
  enumerable: true,
  configurable: false,
})

Also add the TypeScript declaration inside the Flag namespace so it type-checks:

export declare const OPENCODE_EXPERIMENTAL_HASHLINE: boolean

With this pattern, Test 10 works correctly:

process.env.OPENCODE_EXPERIMENTAL_HASHLINE = "1"
// Flag.OPENCODE_EXPERIMENTAL_HASHLINE is now true (getter re-evaluates)
const tools = await ToolRegistry.tools(mockModel)
// assert edit is absent, write is present
delete process.env.OPENCODE_EXPERIMENTAL_HASHLINE

---

CRITICAL: HashlineMismatchError and HashlineNoOpError imports are unused and will cause build errors

Issue says: Include in Required Imports:

import { applyHashlineEdits, HashlineMismatchError, HashlineNoOpError } from "./hashline"

Problem: These error classes are never referenced in hashline_edit.ts — they are never caught, never used in type annotations, never passed to instanceof. An import of a value that is never used will cause a TypeScript/Bun lint error, which blocks CI under the project's zero-bypass policy.

Fix: Remove them from the import. applyHashlineEdits is the only thing needed from ./hashline at runtime:

import { applyHashlineEdits } from "./hashline"
import type { HashlineEdit } from "./hashline"

The errors propagate naturally without needing to be named in this file.

---

ISSUE: Registry — Phase 3 must REPLACE Phase 2's line, not add a new one

Issue says: "Register tool in registry.ts in the all() array alongside HashlineReadTool (added in Phase 2)."

Problem: A junior dev will likely ADD a new spread line rather than edit the existing one, producing:

...(Flag.OPENCODE_EXPERIMENTAL_HASHLINE ? [HashlineReadTool] : []),      // Phase 2
...(Flag.OPENCODE_EXPERIMENTAL_HASHLINE ? [HashlineReadTool, HashlineEditTool] : []),  // Phase 3 — WRONG, duplicates Read

Fix: Provide an explicit before/after:

// BEFORE (what Phase 2 added — find this line and edit it):
...(Flag.OPENCODE_EXPERIMENTAL_HASHLINE ? [HashlineReadTool] : []),

// AFTER (replace the above line with this):
...(Flag.OPENCODE_EXPERIMENTAL_HASHLINE ? [HashlineReadTool, HashlineEditTool] : []),

Do NOT add a second spread line. Edit the existing one in place.

---

ISSUE: ctx.metadata() and error flow when applyHashlineEdits throws

Issue says: applyHashlineEdits is called inside withLock. If it throws, the lock re-throws (verified: withLock uses try/finally and rethrows). Execution does NOT reach the filediff, ctx.metadata(), or return lines outside the lock.

This is correct behaviour — the error propagates as a tool error and the model sees the HashlineMismatchError message. No fix needed, but clarify in the issue:

If applyHashlineEdits throws (HashlineMismatchError or HashlineNoOpError), the exception propagates through withLock (which uses try/finally and re-throws). Execution does NOT reach the filediff block, ctx.metadata(), or return below. contentOld and contentNew remaining as "" is irrelevant because those lines are never reached. This is the correct and intended behaviour.

[randomm]

Implemented in PR #217. Note: write tool suppression bug tracked in #222.