fix(fs_write): guide model to read-before-write and prevent sed fallback

[sandikodev]

Problem

Two related issues caused cascading failures during AI-assisted file editing:

Issue 1: Model guesses old_str without reading the file first

The fs_write tool description did not explicitly require the model to read the file before calling str_replace. The model would reconstruct old_str from memory or context, which fails when:

• The file has been modified since it was last read
• Whitespace or indentation differs from what the model expects
• The model is working from a partial view of the file

This produces the error: no occurrences of "..." were found

Issue 2: Model falls back to sed -i after str_replace failure

When str_replace fails, the model would fall back to shell commands like sed -i as a workaround. This is dangerous because:

• No diff preview before execution
• No validation — silently corrupts files if the pattern matches unintended lines
• Can affect multiple files if the pattern is too broad
• Not reversible without version control

This compounds the original error into a potentially destructive cascade.

Fix

1. Tool description — explicit read-before-write instruction:

ALWAYS use fs_read to read the file content BEFORE calling str_replace.
Never guess or reconstruct old_str from memory.

2. Tool description — explicit anti-fallback instruction:

If str_replace fails because old_str was not found, do NOT fall back to
shell commands like sed. Instead, re-read the file with fs_read and retry
with the correct content.

3. Error message improvement — guidance at point of failure:

Before:

no occurrences of "..." were found

After:

no occurrences of "..." were found — use fs_read to read the current file
content and retry str_replace with the exact text. Do NOT fall back to
shell commands like sed.

4. Multiple occurrences error — actionable hint:

Before:

3 occurrences of old_str were found when only 1 is expected

After:

3 occurrences of old_str were found when only 1 is expected — add more
surrounding context to old_str to make it unique

Testing

cargo test -p chat_cli

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[sandikodev]

Superseded by #3725.

This PR added read-before-write guidance to the tool description and improved the error message. PR #3725 includes all of that plus the actual fuzzy matching implementation, making the guidance accurate (the tool now tolerates minor indentation differences). The two PRs should be reviewed together or #3724 closed in favour of #3725.