refusals: detect the F5 Guardrails block, which returns HTTP 200 #1177

Summary

Omni Gateway v1.14.0 ships the
F5 Guardrails policy,
backed by F5 AI Guardrails (CalypsoAI). Unlike every guardrail the SDK types today, it blocks with
HTTP 200 and a native content-filter response in the caller's format (OpenAI, Anthropic or
Gemini). The SDK currently reports an F5 block as a successful completion.

Motivation

BG §2.1/§2.2. A block that looks like success is worse than an untyped one. The agent goes on to use
the content-filter stub as if it were a real answer, and no refusal handler (donkey.on()) or span
ever records it.

Current behavior (verified)

• python/src/donkey_kit/core/errors.py:706-715 (the classify() docstring) and
  docs/verified-apis.md:469: only non-2xx responses are classified. A 2xx never reaches
  classify().
• python/src/donkey_kit/core/_refusal_body.py:220: the content-safety vendor table is consulted
  only on the 403 path.
• rg content_filter python/src only matches the Bedrock rejection fixture. Nothing inspects a
  2xx for a filtered completion.

Proposal

• Verify first: capture a blocked 200 on
  Donkey-Development-Kit/donkey-development-kit-provisioning#61, non-streaming and
  streaming. Record the body (for example finish_reason: "content_filter"), the
  observability/reason headers, and the scan-ID header. Add the docs/verified-apis.md row in this
  issue.
• Add a 2xx detection hook in the shared transport. It keys on the policy's verdict header, not on
  body text, so a genuine model content_filter stop isn't misread. It raises a typed refusal with
  vendor "F5 AI Guardrails", the failed F5 scanner names as categories, and the scan ID as an
  attribute.
• Streaming: the policy buffers and rewrites the stream, so the hook must also work on stream
  completion.
• Don't raise on flagged (audit) or redacted; at most record them on the span.
• Type the 503 fail-closed (none_response, redaction_failed) as a guardrail outage, not a
  content block.

Cross-surface impact

• core: a new 2xx hook in transport, plus _refusal_body.py, _wire.py, errors.py, and
  telemetry.py (verdict and scan-ID span attributes).
• llm: the OpenAI client's streaming and non-streaming paths.
• integrations: every adapter goes through the shared transport. The conformance kit
  (python/tests/conformance/suite.py) needs a 2xx-refusal case so all frameworks are checked at
  once.
• registry / tools: not affected.
• TypeScript parity (planned): flag. A 2xx-refusal hook is a new transport contract the TS
  port must copy.
• CLI: donkey mock needs to be able to serve a 200 content-filter fixture.
• Nextra docs site: errors.mdx. Explain that this refusal arrives on a 200.
• docs/verified-apis.md: a new row with a new discriminator class (2xx refusal).

Out of scope

• Other federated guardrail vendors. Each has its own independent issue.
• F5 audit-mode reporting beyond span attributes.

Depends on

• Donkey-Development-Kit/donkey-development-kit-provisioning#61: the live proxy to capture
  against.

Related

• verify: federated guardrail verdict shapes for Akamai, CrowdStrike and Google Armor #305 / refusals: type the Akamai federated guardrail verdict #313: earlier combined federated-guardrail tracking. This issue owns F5 independently.
• upstream: guardrail-verdict error contract is under-documented #251: upstream guardrail-verdict contract gap. It's worth asking the gateway team why F5 uses
  200 when the other guardrails use 403.
• Acceptance: Donkey-Development-Kit/donkey-development-kit-acceptance#69.

Acceptance criteria

• A live-captured F5 block (non-streaming and streaming) raises a typed refusal instead of
  returning a completion.
• A genuine model content_filter stop without the F5 verdict header does not raise.
• flagged / redacted outcomes don't raise. The 503 is not typed as a content block.
• The conformance kit covers the 2xx refusal across all adapters.
• Fixtures, the docs/verified-apis.md row, and errors.mdx updated.