fix(opencode): Improve "Read" tool output to aid subsequent uses of the "Edit" tool

[albertov]

What does this PR do?

This PR helps models (tested with Haiku 4.5) use the "Edit" tool more effectively with regards to leading whitespace after reading context given by the "Read" tool. Fixes #10656

How did you verify your code works?

I tasked agents with writing Haskell (white-space sensitive) and they improved considerably their success rate (to consistently perfect edits) when using the Edit tool as to not introduce leading-whitespace related errors

[github-actions]

Hey! Your PR title Improve "Read" tool output to aid subsequent uses of the "Edit" tool doesn't follow conventional commit format.

Please update it to start with one of:

• feat: or feat(scope): new feature
• fix: or fix(scope): bug fix
• docs: or docs(scope): documentation changes
• chore: or chore(scope): maintenance tasks
• refactor: or refactor(scope): code refactoring
• test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

No duplicate PRs found

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[albertov]

Below is the conclusion at which Haiku 4.5 at copilot-github analysed codebase to figure out.

Why are agents having so much trouble using the edit tool from opencode when dealing with whitespace and indentation?

---

The Root Problem

The edit tool has a critical design flaw in how it instructs agents to handle the line number prefix from the Read tool output.

The Documentation Issue

In packages/opencode/src/tool/edit.txt, the tool states:

When editing text from Read tool output, ensure you preserve the exact indentation 
(tabs/spaces) as it appears AFTER the line number prefix. The line number prefix 
format is: spaces + line number + tab. Everything after that tab is the actual 
file content to match. Never include any part of the line number prefix in the 
oldString or newString.

The problem: This instruction is extremely difficult for agents to follow because:

1. Visual ambiguity: When you see 45 function foo(), it's nearly impossible to distinguish where the "line number prefix" (spaces + line number + tab) ends and the actual indentation begins, especially since tabs and spaces look identical visually.

2. Fragile parsing: Agents must correctly parse the line number prefix format (spaces + number + tab), but different tools/systems may format the line output differently, making this brittle.

3. Easy mistakes: An agent might accidentally:

   • Include leading spaces from the prefix in the oldString
   • Strip legitimate indentation from the beginning of the code line
   • Miscount spaces vs tabs

The Implementation Shows Why

Looking at the replace() function in packages/opencode/src/tool/edit.ts, there are 9 different "replacer" strategies used to try to fix agent mistakes:

for (const replacer of [
    SimpleReplacer,
    LineTrimmedReplacer,
    BlockAnchorReplacer,
    WhitespaceNormalizedReplacer,      // ← Handles whitespace issues
    IndentationFlexibleReplacer,       // ← Handles indentation issues
    EscapeNormalizedReplacer,
    TrimmedBoundaryReplacer,
    ContextAwareReplacer,
    MultiOccurrenceReplacer,
  ])

Even with these fallback strategies:

• WhitespaceNormalizedReplacer collapses all whitespace to single spaces (/\s+/g, " ")
• IndentationFlexibleReplacer strips common leading indentation

These exist precisely because agents struggle with whitespace/indentation. The tool was designed with these fallbacks as a band-aid, acknowledging the fundamental problem.

Why Agents Struggle

1. Invisible characters: The line number prefix uses a TAB character (invisible, variable width)
2. Context loss: The Read tool output format strips structural context
3. Ambiguous instructions: "Everything after that tab" is ambiguous when tabs aren't rendered visually
4. No validation feedback: An agent won't know they got it wrong until the edit fails

Solution

The edit tool documentation should be updated to provide explicit visual guidance, such as:

• Show agents exactly what to copy (with a clear marker)
• Provide examples with visual separators
• Or, better yet: Have the Read tool strip the line number prefix before returning output to agents, so they never have to parse it manually