[DOCS] Document diff timeout behavior for large files with few common lines

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/how-claude-code-works

Section/Topic

How Claude Code Works — built-in tools / file operations behavior; also relevant to any troubleshooting or limitations section.

Current Documentation

The current documentation contains no mention of diff timeouts, diff performance limits, or fallback behavior when diffing large files. The how-claude-code-works page describes file operations only at a high level:

File operations — Read files, edit code, create new files, rename and reorganize

There is no documentation about how Claude Code handles edge cases during diff computation (e.g., very large files, files with few common lines, or the fallback behavior that applies when diff computation takes too long).

What's Wrong or Missing?

Claude Code v2.1.83 fixed a hang that occurred when diffing very large files with few common lines. The fix introduced a 5-second timeout on diff computation, after which the diff falls back gracefully. This is observable, user-facing behavior: users working with large generated files, minified assets, binary-adjacent text files, or data files may see a truncated or simplified diff rather than a full line-by-line comparison.

This behavior is entirely undocumented. Users who encounter a degraded diff display have no way to know:

• That a timeout caused the simplified output
• That the timeout threshold is 5 seconds
• That the fallback is intentional and safe (not an error)
• What kinds of files are most likely to trigger this path

Source: Changelog v2.1.83 — "Fixed a hang when diffing very large files with few common lines — diffs now time out after 5 seconds and fall back gracefully"

Suggested Improvement

Add a note in the how-claude-code-works page (or a dedicated limitations/performance section) explaining:

• When Claude Code computes a diff for a file edit, it applies a 5-second timeout to protect against hangs on pathological inputs (very large files or files with few common lines).
• If the timeout is reached, the diff display falls back gracefully — the edit is still applied correctly, but the visual diff shown may be simplified or omitted.
• Files most likely to trigger this path include large minified files, generated files, data files, or any file where the old and new versions share very few common lines.

This helps users understand that a simplified diff is not an error and that their edits were applied correctly.

Impact

Medium - Makes feature difficult to understand

Additional Context