claude-code - 💡(How to fix) Fix [DOCS] Third-party model docs omit background side-query fallback to the active main model [1 comments, 2 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/model-config

Section/Topic

ANTHROPIC_DEFAULT_HAIKU_MODEL, deprecated ANTHROPIC_SMALL_FAST_MODEL, and third-party deployment guidance for background functionality

Current Documentation

The docs currently say:

| ANTHROPIC_DEFAULT_HAIKU_MODEL | The model to use for haiku, or background functionality |

Note: ANTHROPIC_SMALL_FAST_MODEL is deprecated in favor of ANTHROPIC_DEFAULT_HAIKU_MODEL.

They also describe separate primary and small/fast defaults for third-party providers without explaining the fallback behavior added in v2.1.141. For example:

Claude Code uses these default models when no pinning variables are set:

| Model type | Default value | | Primary model | us.anthropic.claude-sonnet-4-5-20250929-v1:0 | | Small/fast model | us.anthropic.claude-haiku-4-5-20251001-v1:0 |

and:

For regional endpoints, ensure the primary model and small/fast model are supported in your selected region

What's Wrong or Missing?

The current docs explain that background functionality uses the Haiku/small-fast model slot, but they do not explain the behavior Claude Code now uses on Bedrock, Vertex AI, Microsoft Foundry, and gateway deployments when that separate Haiku model ID is unavailable and no explicit override is set.

In v2.1.141, background side-queries were changed to fall back to the active main-loop model instead of sending an unavailable Haiku model ID. Without that note, readers are left with an outdated mental model that background side-queries always require a separate available Haiku model configuration on those providers.

Suggested Improvement

Add a short note in the model configuration and third-party provider docs clarifying that:

Before:

Background functionality uses the Haiku/small-fast model slot.

After:

Background functionality prefers the Haiku/small-fast model slot (ANTHROPIC_DEFAULT_HAIKU_MODEL, or deprecated ANTHROPIC_SMALL_FAST_MODEL). On Bedrock, Vertex AI, Microsoft Foundry, and gateway deployments, if no separate override is set and the configured Haiku model ID is unavailable, Claude Code v2.1.141 and later fall back to the active main-loop model for those background side-queries. Administrators should still pin ANTHROPIC_DEFAULT_HAIKU_MODEL when they want a specific background model.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 5 pages affected

This is scoped to one root cause: third-party model documentation does not explain the v2.1.141 fallback from an unavailable background Haiku model to the active main-loop model.