Why Edit Failed and What It Reveals About the Tools

1. Why the error occurred:

The Edit tool performs exact string replacement, not a fuzzy or AI-mediated substitution — it takes an old_string and a new_string and does a literal, character-for-character match. For the edit to apply, that old_string has to appear in the file exactly once (unless replace_all is explicitly set), because if it appears multiple times, Claude Code has no way to programmatically determine which specific occurrence the intended target is — it would be guessing. Rather than silently picking one occurrence (which could easily be the wrong one, especially in a config file where the same default value or key name might legitimately repeat), the tool refuses to apply an ambiguous edit and surfaces the ambiguity back to Claude, which then either narrows old_string with more surrounding context to pin down a unique match, or explicitly opts into replacing every occurrence with replace_all: true if that's actually correct.

2. Contrast with sed via Bash:

A raw sed command run through the Bash tool has no equivalent built-in safeguard. sed -i 's/old/new/g' will happily rewrite every matching occurrence across the file (or even across multiple files, depending on how it's invoked) without any uniqueness check — whatever the pattern matches, it changes, silently and immediately. The Edit tool's refusal-on-ambiguity behavior is a property of the tool itself, baked into how it's built; a shell command run via Bash doesn't inherit that property just because Bash is also a Claude Code tool; Bash is a general-purpose execution tool, and its safety comes entirely from whatever the invoked command itself does or doesn't check. This is part of why Claude Code strongly prefers the dedicated Edit tool over Bash-based text manipulation for file changes: Edit gives structural guarantees (matched-exactly-once, reversible via checkpointing) that an arbitrary shell command doesn't.

3. Evaluating the "just use AI judgment" argument:

Disagree, and the reasoning connects directly to the reversibility and predictability themes running through the tool and permission design. The entire point of gating file edits behind an exact, unambiguous match is that a wrong guess on a config default is the kind of mistake that's easy to introduce and easy to miss in review — it looks like a plausible, syntactically valid change, so a human skimming a diff might not catch that the wrong of three identical-looking defaults got changed. Making the tool "smarter" by letting it pick based on AI judgment converts a case that currently produces a loud, immediate, correctable error (Claude asks for disambiguation, or the developer clarifies) into a case that could silently produce a plausible-looking wrong edit that only surfaces as a bug much later, disconnected from its cause. This mirrors exactly why permission modes treat reversible, low-stakes actions (a Read) differently from ones that are cheap to get wrong but expensive to notice being wrong — the system consistently prefers "stop and ask" over "silently do something probably right." A tool that fails loudly on ambiguity is a feature of that same philosophy, not a UX gap.