[DOCS] WebFetch permission docs omit rule precedence over built-in preapproved domains

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

WebFetch tool behavior, especially how built-in preapproved domains interact with explicit WebFetch(domain:...) permission rules

Current Documentation

The docs currently say:

In the default and acceptEdits permission modes, WebFetch prompts the first time it reaches a new domain. To allow a domain in advance without a prompt, add a permission rule like WebFetch(domain:example.com). The auto and bypassPermissions permission modes skip the prompt entirely.

And the permissions reference says:

Allow rules let Claude Code use the specified tool without manual approval. Ask rules prompt for confirmation whenever Claude Code tries to use the specified tool. * Deny rules prevent Claude Code from using the specified tool. Rules are evaluated in order: deny -> ask -> allow. The first matching rule wins, so deny rules always take precedence.

It also defines the WebFetch matcher only as:

* WebFetch(domain:example.com) matches fetch requests to example.com

What's Wrong or Missing?

These pages do not explain the built-in preapproved-domain exception for WebFetch or how explicit domain rules interact with it.

In v2.1.162, the changelog says:

Fixed WebFetch permission rules not being applied to built-in preapproved domains; explicit WebFetch(domain:...) deny/ask/allow rules now take precedence over the preapproved-host auto-allow

That leaves two documentation gaps:

A. The WebFetch behavior page reads as if every new-domain decision follows the same prompt path

tools-reference says WebFetch prompts the first time it reaches a new domain, but it does not disclose that Claude Code also has built-in preapproved hosts that can auto-allow fetches.

B. The permissions docs do not say that explicit WebFetch(domain:...) rules override that auto-allow

The permissions page documents generic deny -> ask -> allow precedence and the WebFetch(domain:...) matcher, but it does not state that this precedence also applies when the target host is one of the built-in preapproved WebFetch domains. Readers who are trying to force a prompt or deny on one of those hosts have no stable documentation telling them that explicit rules now win.

Suggested Improvement

Update the stable WebFetch and permissions docs to match v2.1.162.

For example, add a note near the WebFetch behavior section such as:

Some WebFetch hosts are built in as preapproved domains and may skip the usual first-visit prompt. Explicit WebFetch(domain:...) permission rules still take precedence: matching deny rules block the fetch, matching ask rules still prompt, and matching allow rules pre-approve it.

Then add a matching sentence in the permissions reference under WebFetch so readers can find the precedence rule from either page.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | 278 | WebFetch says it prompts on the first visit to a new domain, but does not mention built-in preapproved hosts or explicit-rule precedence |
| https://code.claude.com/docs/en/permissions | 25-29, 239 | Generic deny -> ask -> allow ordering and WebFetch(domain:...) syntax are documented, but the built-in preapproved-domain override case is not |

Total scope: 2 pages affected

Version context: https://code.claude.com/docs/en/changelog for v2.1.162 says explicit WebFetch(domain:...) deny/ask/allow rules now take precedence over the preapproved-host auto-allow.