[FEATURE] Ability for Write/Edit hooks to debounce multiple writes to the same file

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

In ~/.claude/settings.json, we have a formatter hook defined,

  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/claude-formatter-hook.sh"
          }
        ]
      }
    ]

which runs various linters, including npx eslint --fix on JS/TS files.

One of our eslint rules is "remove unused imports."

This causes a frequent point of friction, where CC wants to add an import and then a usage of that import (in that order), so it adds the import – then the hook runs and removes it! – then the usage of it – then it gets confused because the import is gone. Our AGENTS.md file documents this scenario, so at least it understands within a few seconds _why_ this is happening, but we can't seem to get it to write the _usage first_ or otherwise avoid this churn.

Proposed Solution

It would be great if the hooks could differentiate when multiple actions are being done on the same file. Perhaps CC itself should only call the hook once after it's done, per file.

Alternative Solutions

I have seen a MultiEdit hook mentioned elsewhere, though not in the current documentation, (and I'm not sure how that would work in this case, anyway).

Alternately, is there already a way to handle this case now?

Priority

Low - Nice to have

Feature Category

File operations

Use Case Example

Working on a Typescript app:

1. I tell Claude Code to add something involving path.resolve().
2. CC adds import {resolve} from 'path'; at the top of the file.
3. This triggers the PostToolUse hook with the write or edit matcher.
4. Our configuration of this hook runs eslint --fix, including remove-unused-imports. This causes the import line – which is not yet "used" – to be removed.
5. CC then adds a line below which _uses_ resolve().
6. It then executes the code, or the typechecker, and sees that "resolve is undefined" – CC gets confused, reads the code again, and sees that the import is gone.
7. CC adds the import line back.

Additional Context

_No response_