[DOCS] Format-on-save hooks don't document consecutive edit behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/hooks-guide

Section/Topic

The Auto-format code after edits section.

Current Documentation

The hooks guide currently says:

Automatically run Prettier on every file Claude edits, so formatting stays consistent without manual intervention.

and presents this pattern as a ready-to-use example:

This hook uses the PostToolUse event with an Edit|Write matcher, so it runs only after file-editing tools.

with the example:

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}

No note explains what happens when Claude makes multiple consecutive Edit or Write calls to the same file while the hook rewrites that file after each step.

What's Wrong or Missing?

The docs present format-on-save hooks as a standard pattern, but they do not explain an important behavior: the hook rewrites the file on disk after each edit, so consecutive edits to the same file involve intermediate on-disk changes between tool calls.

That omission matters because the v2.1.90 release specifically fixed this failure mode:

"Fixed Edit/Write failing with \"File content has changed\" when a PostToolUse format-on-save hook rewrites the file between consecutive edits"

The current docs still do not tell users:

1. That this pattern involves consecutive file rewrites between edits.
2. That older versions could fail with File content has changed in this situation.
3. That this pattern is now supported correctly as of v2.1.90.

Suggested Improvement

Add a note under Auto-format code after edits explaining that a PostToolUse formatter rewrites the file after each Edit or Write, including between consecutive edits to the same file.

That note should say:

1. This is expected behavior for format-on-save hooks.
2. Claude Code v2.1.90 and later handle this correctly for consecutive edits.
3. On older versions, users may see a File content has changed error if a formatter rewrites the file between tool calls.

This would make the documented pattern safer to adopt and easier to troubleshoot.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks-guide | The format-on-save example is documented, but the consecutive-edit interaction and prior failure mode are not |

Total scope: 1 page affected

Source: Changelog v2.1.90

"Fixed Edit/Write failing with \"File content has changed\" when a PostToolUse format-on-save hook rewrites the file between consecutive edits"