What Problem This Solves

Provider refusals (Anthropic safety classifiers, OpenAI content_filter) silently bypass the model fallback chain. When a provider returns a refusal, the agent run-loop surfaces a generic "LLM request failed." error without ever consulting the configured fallback models — even though Anthropic's own refusal copy recommends configuring a fallback model.

• Problem: classifyFailoverClassificationFromMessage has no refusal pattern → classifyAssistantFailoverReason returns null → failoverFailure=false → shouldRotateAssistant=false → continue_normal → fallback chain never checked
• Solution: Add "refusal" to FailoverReason, match Anthropic refusal and content_filter messages in the unified failover classifier, route Anthropic sensitive stop reason through the refusal path, and gate the fallback on the opt-in refusalFallback config flag
• What changed:
  • src/agents/embedded-agent-helpers/types.ts (+1, new failover reason)
  • src/agents/embedded-agent-helpers/errors.ts (+3/−8, refusal detection via isRefusalErrorMessage from failover-matches.ts; preserve refusal text when all fallbacks exhausted)
  • src/agents/embedded-agent-helpers/failover-matches.ts (+8, ERROR_PATTERNS.refusal regex patterns + isRefusalErrorMessage export)
  • src/agents/embedded-agent-helpers/failover-matches.test.ts (refusal classification tests)
  • src/agents/failover-policy.ts (+2, cooldown probe eligibility for refusal)
  • src/agents/failover-policy.test.ts (refusal cooldown policy tests)
  • src/agents/anthropic-transport-stream.ts (+1/−2, route sensitive stop reason through applyAnthropicRefusal so it produces errorCode: "provider_refusal")
  • src/agents/auth-profiles/types.ts (+1, AuthProfileFailureReason mirror)
  • src/agents/runtime-plan/types.ts (+1, AgentRuntimeFailoverReason mirror)
  • src/agents/embedded-agent-runner/run/failover-policy.ts (refusal skips auth rotation, goes directly to fallback_model)
  • src/agents/agent-command.ts (pass config to result classifier callback)
  • src/agents/embedded-agent-runner/result-fallback-classifier.ts (gate result-payload refusals on refusalFallback + config param)
  • src/config/types.agent-defaults.ts (+15, refusalFallback config flag)
  • src/config/zod-schema.agent-defaults.ts (+1, Zod schema for strict validation)
  • src/config/schema.help.ts (+2, refusalFallback help documentation)
  • src/config/schema.labels.ts (+1, refusalFallback config label)
  • docs/concepts/model-failover.md (+34, Provider refusals documentation section)
• Registry sync: packages/gateway-protocol/src/schema/cron.ts, src/cron/run-log/entry-codec.ts, src/agents/auth-profiles/failure-copy.ts — all downstream registries updated
• What did NOT change: resolveFailoverStatus (refusal has no HTTP analog), resolveSessionSuspensionReason (default circuit_open is correct), buildFailoverRemediationHint (only triggers for auth). Refusal is intentionally excluded from AUTH_FAILURE_REASONS and FAILURE_REASON_PRIORITY because it is not an auth-profile-level failure.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Fixes [Bug]: Provider refusals (Anthropic refusal / OpenAI content_filter) never trigger the model fallback chain — turn dies with generic 'LLM request failed.' #98976
• This PR fixes a bug or regression

Motivation

Three production incidents in one morning logged failoverReason: null for Anthropic refusals with Anthropic refusal (category: bio) ... in the error body. Each time the provider message explicitly said "API integrators: you can reduce refusals for your users by configuring a fallback model — see https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback". But OpenClaw never triggered the fallback chain because the failover classification pipeline had no concept of a refusal.

After fix, a refusal skips profile rotation (content decision, not credential problem) and goes directly to model fallback. The next candidate handles the turn without polluting auth cooldown state.

Approach Analysis

The core question is: when a provider's safety classifier refuses a prompt, should OpenClaw automatically route to the next configured fallback model?

Three approaches were considered:

Approach A: Always fallback on refusal

Route all refusals through the failover chain, same as rate_limit and timeout.

• Pro: Simplest implementation. Matches Anthropic's own recommendation ("configure a fallback model"). Best UX for false-positive cases.
• Con: If the fallback model has weaker content safety, a provider-blocked prompt could receive a different outcome. This is a product/security policy decision best left to the user.
• Status: Rejected — too aggressive as a default, and maintainers flagged it as a security-boundary concern.

Approach B: Never fallback on refusal (current behavior)

Keep refusals as terminal errors. Users who want to retry must manually switch models or resubmit.

• Pro: Safety classifiers are never bypassed. No risk of routing blocked prompts to models with different policies.
• Con: Loses Anthropic's documented fallback recommendation. False-positive refusals (which are common — two of the three production incidents that triggered this issue were classifier false positives) force users to manually retry, which is the exact experience Anthropic says fallback models should solve.
• Status: Rejected — not because it's wrong, but because it leaves a real UX gap that prevents users from following the provider's own guidance.

Approach C (chosen): Opt-in via refusalFallback flag

Add a configuration flag agents.defaults.refusalFallback (default: false) that users enable when they want refusals to enter the fallback chain.

• Why it wins: Puts the decision in the user's hands. Users who understand their fallback chain's safety characteristics can opt in; everyone else sees no change.
• Key insight: OpenClaw does not operate its own safety classifiers — it passes prompts to providers, and each provider runs its own independent safety checks. Routing a refused prompt from Anthropic to a fallback GPT model doesn't "bypass" Anthropic's safety; it simply asks GPT for its independent assessment. GPT runs its own safety classifiers independently.
• Safe default: false means zero behavior change for existing users.
• Preserves refusal diagnostics: Even when fallback is enabled and all candidates refuse, the original refusal text (e.g. "Anthropic refusal (category: bio): ...") is shown to the user, not a generic "LLM request failed."
• Risk profile: The user explicitly configures both the flag and the fallback models, so they own the policy decision.

Config: agents.defaults.refusalFallback

This behavior is opt-in via a new config flag:

{
  "agents": {
    "defaults": {
      "refusalFallback": true
    }
  }
}

Default: false — provider refusals are surfaced as terminal errors (existing behavior preserved).

Trade-offs

Pro (why turn it on):

• Reduces user interruption from false-positive safety classifiers (Anthropic's safety classifiers have known false-positive rates, as evidenced by the production logs that triggered this issue — a music track titled "Species Filter" tripping the bio category)
• Each provider runs its own independent safety checks — routing to a fallback model does NOT bypass the original provider's moderation, it simply asks another provider for its independent assessment
• Anthropic's own refusal response explicitly recommends "configuring a fallback model"

Con (why keep it off):

• If the fallback model has weaker or different content safety policies, the same prompt may receive a different outcome than the original provider intended
• In compliance-sensitive deployments, operators may want refusals to always be surfaced rather than silently routed

Recommendation: Turn on if your fallback chain uses models with comparable safety guardrails (e.g., Claude Sonnet → Claude Haiku, or GPT-5.5 → GPT-5.4). Keep off if you need every provider safety block to be terminal and visible.

Evidence

• Behavior addressed: Provider refusals (Anthropic stop_reason=refusal/sensitive, OpenAI finish_reason=content_filter) are classified as failover-eligible, triggering the configured model fallback chain instead of silently dying with "LLM request failed."
• Real environment tested: Linux x86_64, Node 22, branch fix/provider-refusal-fallback-98976
• Exact steps or command run after this patch:

node --import tsx -e "
import { classifyFailoverReason, classifyAssistantFailoverReason } from './src/agents/embedded-agent-helpers/errors.ts';

const cases = [
  { input: 'Anthropic refusal (category: bio): The content...', expect: 'refusal' },
  { input: 'Anthropic refusal.', expect: 'refusal' },
  { input: 'Provider finish_reason: content_filter', expect: 'refusal' },
  { input: 'LLM request failed.', expect: null },
  { input: 'rate limit exceeded', expect: 'rate_limit' },
  { input: 'The request was refused by the proxy.', expect: null },
];
for (const c of cases) {
  const result = classifyFailoverReason(c.input);
  const status = result === c.expect ? 'PASS' : 'FAIL';
  console.log(status + ' | \"' + c.input.substring(0, 60) + '\" → ' + result);
}

// Verify regex-based matching is case-insensitive
console.log();
console.log('=== Case insensitive regex test ===');
console.log(classifyFailoverReason('anthropic REFUSAL (category: legal): policy'));
console.log(classifyFailoverReason('Finish_reason: content_filter'));

// Verify sensitive stop reason
console.log();
console.log('=== sensitive stop reason → refusal ===');
const msg = {
  role: 'assistant', api: 'anthropic-chat', provider: 'anthropic',
  model: 'claude-sonnet-4-6', stopReason: 'error',
  errorCode: 'provider_refusal',
  errorMessage: 'Anthropic refusal (sensitive): Content declined.',
  content: [], usage: { input: 1, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 1,
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
  timestamp: Date.now(),
};
console.log(classifyAssistantFailoverReason(msg));
"

• Evidence after fix:

$ node --import tsx -e "..." 2>&1
PASS | "Anthropic refusal (category: bio): The content..." → refusal
PASS | "Anthropic refusal." → refusal
PASS | "Provider finish_reason: content_filter" → refusal
PASS | "LLM request failed." → null
PASS | "rate limit exceeded" → rate_limit
PASS | "The request was refused by the proxy." → null

=== Case insensitive regex test ===
refusal
refusal

=== sensitive stop reason → refusal ===
refusal

Classification matrix:

Cooldown probe matrix:

Failover decision matrix:

Unit test results:

 ✓ failover-matches.test.ts   27 passed (including refusal patterns)
 ✓ failover-policy.test.ts     42 passed (including refusal decision tests)

• Observed result after fix:

  1. classifyFailoverReason("Anthropic refusal ...") returns "refusal" — was null
  2. Regex matching is case-insensitive and word-bounded — more robust than the original startsWith
  3. sensitive stop reason now routes through applyAnthropicRefusal, producing errorCode: "provider_refusal"
  4. refusal is excluded from AUTH_FAILURE_REASONS and FAILURE_REASON_PRIORITY — it is not an auth-level failure
  5. refusalFallback config has schema help, label, and public documentation
  6. classifyAssistantFailoverReason with errorCode: "provider_refusal" returns "refusal"
  7. All existing failover classifications unchanged — zero regression

• What was not tested: Live end-to-end with real Anthropic API key (not available in this environment). The classification, policy, and failover decision logic is fully source-verified; a real API-key test is needed to confirm the transport-level sensitive→applyAnthropicRefusal mapping and the full refusal→fallback flow in a running gateway. This is a follow-up item for a maintainer or contributor with Anthropic API key access.

Root Cause

classifyFailoverClassificationFromMessage in src/agents/embedded-agent-helpers/errors.ts had no pattern for "Anthropic refusal" or "Provider finish_reason: content_filter". When an assistant message arrived with stopReason="error" and refusal text, the classifier returned null, isFailoverAssistantError returned false, shouldRotateAssistant returned false, and resolveRunFailoverDecision returned { action: "continue_normal" } — which ends the turn with no fallback attempt.

Provenance: introduced by the original shared/anthropic-refusal.ts — the refusal→error mapping was wired but never connected to failover classification.

Confidence: clear — single classification entry point, all callers downstream react to the returned reason.

User-visible / Behavior Changes

When refusalFallback: true is set and a provider refuses a prompt:

• The agent falls back to the next candidate (skips profile rotation — refusal is a content decision, not a credential problem)
• When no fallbacks are configured, or all candidates refuse, the final refusal text is shown
• When refusalFallback is unset or false, behavior is unchanged

Additionally, Anthropic sensitive stop reason is now properly handled — previously it was mapped as a generic error; now it produces errorCode: "provider_refusal" with proper diagnostics, consistent with refusal stop reason behavior.

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Compatibility / Migration

• Backward compatible? Yes — refusalFallback defaults to false, preserving existing behavior. AUTH_FAILURE_REASONS no longer includes "refusal" (it was never used in practice for auth profile state).
• Config/env changes? Yes — new agents.defaults.refusalFallback boolean (optional, default: false) with schema help/label/docs
• Migration needed? No

Best-fix Verdict

• Best fix: Yes. The single classification entry point (classifyFailoverClassificationFromMessage) is the right boundary because every failover path (assistant-stage, prompt-stage, signal-level, detail-level) already goes through it. Adding a new reason here automatically propagates to the full fallback pipeline without touching any of the downstream decision helpers.
• Refactor needed: No
• Alternative considered: Classifying refusal via failover-error.ts's resolveFailoverReasonFromError path. Rejected — that path only fires for thrown errors, whereas refusal is a normal stream result with stopReason="error" on the assistant message. The message-level classifier is the correct gate.

Risks and Mitigations

• Risk: The refusal reason string format changes across Anthropic SDK versions. Mitigation: regex /\banthropic refusal\b/i provides word-boundary matching with case insensitivity — more robust than the original startsWith. The underlying applyAnthropicRefusal function always produces "Anthropic refusal" as the message prefix.
• Risk: OpenAI content_filter finish reason could be confused with a future provider that uses different wording. Mitigation: regex /\bfinish_reason:\s*content_filter\b/i matches the canonical output of mapOpenAIStopReason.
• Risk: Refusal fallback may route a provider-blocked prompt to a model with different safety policies. Mitigation: this feature is opt-in via refusalFallback (default: false). Each provider runs its own independent safety checks.
• Risk: sensitive stop reason from Anthropic was previously treated as a generic error; changing it to applyAnthropicRefusal changes its error behavior. Mitigation: applyAnthropicRefusal is already the standard refusal handler used for refusal stop reason — this change makes sensitive consistent with the existing refusal path.

Fixes #98976