Problem

The str_replace tool documentation says the target string should appear exactly once by default, but the implementation replaces the first occurrence without enforcing uniqueness.

Impact

Agents and users can unintentionally edit the wrong occurrence in a file while receiving a successful result, especially in generated code or documents with repeated snippets.

Suggested Fix

Count occurrences before replacement. If the old string appears zero times or more than once, return a clear error unless an explicit replace_all or occurrence-index option is requested.

Tests

• Unique match succeeds.
• Zero matches returns an error.
• Multiple matches returns an error by default.
• Explicit replace-all behavior, if supported, replaces all matches.

References

• backend/packages/harness/deerflow/sandbox/tools.py:1310
• backend/packages/harness/deerflow/sandbox/tools.py:1335