[DOCS] Hooks and Bash tool docs omit stale-read warning for formatter/linter workflows

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Auto-format code after edits" and related PostToolUse formatter/linter workflows

Current Documentation

The docs currently recommend formatter and linter workflows like these:

Automatically run Prettier on every file Claude edits, so formatting stays consistent without manual intervention. This hook uses the PostToolUse event with an Edit|Write matcher, so it runs only after file-editing tools. The command extracts the edited file path with jq and passes it to Prettier.

This example validates Bash commands with the PreToolUse hook and runs a linter after file edits with PostToolUse: command: "./scripts/run-linter.sh"

Hooks let you run shell commands before or after Claude Code actions, like auto-formatting after every file edit or running lint before a commit.

The Bash tool runs each command in a separate process with the following persistence behavior: Working directory persists across commands. Environment variables do not persist.

None of these pages explain what happens when a Bash formatter or linter rewrites a file Claude already read earlier in the session.

What's Wrong or Missing?

Changelog v2.1.89 says:

Improved Bash tool to warn when a formatter/linter command modifies files you have previously read, preventing stale-edit errors

The current docs already encourage PostToolUse formatting and linting hooks, but they do not explain this file-state interaction at all.

That leaves two gaps:

1. Users are shown workflows like prettier --write and custom lint scripts that can rewrite files after Claude has already read them.
2. The docs never say that Claude Code now warns about that situation, or why Claude may need to re-read an affected file before making another edit.

This is not just an internal implementation detail. It is part of how recommended hook-based formatting/linting workflows behave in practice, and it explains a user-visible warning that can now appear in those setups.

Suggested Improvement

Add a short note anywhere the docs recommend formatter/linter commands that rewrite files after edits, especially in the hooks guide example.

Something along these lines would cover the behavior:

Formatter or linter commands run through Bash or PostToolUse hooks can rewrite files after Claude has already read them. When that happens, Claude Code warns so the file can be re-read before further edits. This prevents stale-edit mistakes in workflows such as prettier --write, eslint --fix, or custom lint/format scripts.

It would also help to add a brief cross-reference in the Bash tool behavior section so the warning is documented outside the hook examples.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks-guide | Primary PostToolUse auto-format example using prettier --write |
| https://code.claude.com/docs/en/sub-agents | Example that runs a linter after file edits |
| https://code.claude.com/docs/en/tools-reference | Bash tool behavior section is the natural place for the warning/re-read explanation |
| https://code.claude.com/docs/en/overview | Recommends auto-formatting after every file edit and lint before commit |
| https://code.claude.com/docs/en/best-practices | Suggests writing hooks that run eslint after every file edit |
| https://code.claude.com/docs/en/context-window | Describes a PostToolUse hook that runs prettier after every file edit |

Total scope: 6 pages affected

Source: Changelog v2.1.89

Exact changelog entry:

Improved Bash tool to warn when a formatter/linter command modifies files you have previously read, preventing stale-edit errors