[BUG] Contradictory guidance on Write() vs Edit() permission rule matching in settings.json

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

I'm running into conflicting guidance from Claude Code itself about how permission rules in .claude/settings.json are matched, and I can't tell which is correct — this is a guardrail on a file containing API credentials, so I don't want to guess.

The conflict:

On session startup, Claude Code prints this warning:

"Permission deny rule (.claude/settings.json): Write(functions/.env) is not matched by file permission checks — only Edit(path) rules are. Use Edit(functions/.env) instead (Edit rules cover all file-editing tools)."

This says Write(path) rules are never evaluated, and to use Edit(path) only.
Running /doctor recommends the opposite — that I add Write(functions/.env) back alongside Edit(functions/.env).

I've now had this flagged both ways across separate sessions, with no way to verify which claim about the permission engine is actually true.

What I need clarified:

Does Write(path) ever get evaluated by the permission engine, separately from Edit(path)?
If not, why does /doctor recommend adding it?
If it does matter, what's the difference in coverage between Write(path) and Edit(path) — i.e., what would a Write()-only or Edit()-only rule miss?

Environment:

Claude Code v2.1.219
macOS, zsh
Model: Opus 5, high effort, Claude Pro

Happy to provide the full settings.json or reproduce with a test repo if useful.

What Should Happen?

I have conflicting error messages from Claude Code, and i have no way to verify which one is correct. need clarity.

Error Messages/Logs

Permission deny rule (.claude/settings.json): Write(functions/.env) is not matched by file permission checks — only Edit(path) rules are. Use Edit(functions/.env) instead (Edit rules cover all file-editing tools)

Steps to Reproduce

<img width="777" height="185" alt="Image" src="https://github.com/user-attachments/assets/a94c7d26-5858-4898-88c1-c843419f9d5f" />

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

was always working, till 2 days ago

Claude Code Version

v2.1.219

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_