fix(bedrock): enforce guardrails on Claude via InvokeModel headers

[JoaoMarcos44]

Closes #52179

Problema

Bedrock Guardrails configurados em bedrock.guardrail eram silenciosamente ignorados para todos os modelos Claude. A causa raiz: o SDK AnthropicBedrock usa a API InvokeModel, que não tem parâmetro guardrailConfig no corpo da requisição — apenas a Converse API tem. O config era lido corretamente (load_config() retornava o bloco), mas nunca era anexado à chamada real.

Isso afeta todos os três caminhos de entrada:

• Servidor de API (POST /v1/chat/completions — Open WebUI, etc.)
• One-shot (hermes -z)
• Gateway nativo interativo

Causa raiz confirmada

config.bedrock.guardrail  →  lido ✓
guardrail_config dict     →  construído ✓
Converse API call         →  guardrailConfig ausente ✗  ← nunca anexado

O SDK AnthropicBedrock roteia Claude via InvokeModel, não Converse — e InvokeModel não tem campo guardrailConfig. Uma abordagem anterior (Option A) roteava Claude+guardrail para a Converse API como workaround, mas isso sacrificava prompt caching, thinking budgets e contexto de 1M tokens.

Solução ()

Injetar o guardrail como headers HTTP (X-Amzn-Bedrock-GuardrailIdentifier, X-Amzn-Bedrock-GuardrailVersion, X-Amzn-Bedrock-Trace) em cada requisição InvokeModel via extra_headers do SDK Anthropic. O AWS Bedrock processa esses headers antes de encaminhar ao modelo — enforcement idêntico ao guardrailConfig da Converse API, sem perder nenhuma feature do Claude.

agent_init.py          →  lê config, armazena agent._bedrock_guardrail_headers
chat_completion_helpers.py  →  passa headers para transport.build_kwargs()
transports/anthropic.py     →  repassa para build_anthropic_kwargs()
anthropic_adapter.py        →  merge em extra_headers (coexiste com fast-mode betas)
                                → SDK call com X-Amzn-Bedrock-Guardrail* headers

Claude sempre permanece no caminho anthropic_messages / InvokeModel — sem regressão em features. Modelos não-Claude continuam na Converse API inalterados.

Arquivos modificados

Arquivo	Mudança
hermes_cli/runtime_provider.py	Reverte condição Option-A; Claude sempre usa anthropic_messages
agent/agent_init.py	Lê guardrail config no init; popula _bedrock_guardrail_headers; banner + Guardrails
agent/chat_completion_helpers.py	+1 linha: passa bedrock_guardrail_headers ao transport
agent/transports/anthropic.py	Repassa param; guardrail_intervened → content_filter; aceita conteúdo vazio no stop reason
agent/anthropic_adapter.py	Merge de headers em extra_headers sem sobrescrever betas existentes
hermes_logging.py	Fallback try/except ImportError para concurrent_log_handler (Windows)
tests/agent/test_bedrock_integration.py	Atualiza testes de routing; +8 novos testes de header injection e stop reason

Testes

531 passed, 15 skipped

Novos testes adicionados:

• TestBedrockGuardrailRouting — Claude+guardrail agora fica em anthropic_messages (não mais bedrock_converse)
• TestBedrockGuardrailHeaderInjection — 5 testes: headers presentes, trace, coexistência com fast-mode, forwarding pelo transport
• TestBedrockGuardrailStopReason — 3 testes: mapeamento guardrail_intervened → content_filter, resposta vazia válida

Verificação manual (evidência do reporter)

# Antes do fix — guardrail ignorado, modelo responde normalmente
aws bedrock-runtime converse ... → stopReason: guardrail_intervened  ✓ (API direta)
hermes -z "prompt bloqueado"    → resposta normal                    ✗ (hermes ignorava)

# Após o fix — headers injetados em cada InvokeModel call
X-Amzn-Bedrock-GuardrailIdentifier: <id>
X-Amzn-Bedrock-GuardrailVersion: 1
→ stop_reason: guardrail_intervened → finish_reason: content_filter  ✓

Impacto em features

Feature	Option A (rota para Converse)	Option B (este PR)
Guardrail enforced	✓	✓
Prompt caching	✗ perdido	✓ preservado
Thinking budgets	✗ perdido	✓ preservado
Contexto 1M tokens	✗ perdido	✓ preservado
Fast mode (Opus 4.6)	✗ perdido	✓ preservado

[teknium1]

Thanks for tracing the Claude/InvokeModel split. Current main still has the reported gap: Bedrock Claude uses anthropic_messages in agent/agent_init.py:767-785, while guardrail config is initialized only for bedrock_converse at agent/agent_init.py:895-915; agent/chat_completion_helpers.py:781-816 likewise forwards it only through Converse.

Problems

• agent/agent_init.py:661-662 in this PR converts any non-empty bedrock.guardrail.trace value to ENABLED. The documented values include disabled and enabled_full (website/docs/guides/aws-bedrock.md:75-76), so disabled would unexpectedly enable tracing and enabled_full would be lost.
• The PR parent is 0c442fa1, behind current main (8a5f8379). Salvage must resolve the moved surrounding code rather than apply the old context directly.

Suggested changes

• Preserve the configured trace enum when constructing the header and test all documented trace values.
• Add a temp-HERMES_HOME configuration-to-client test that captures both streaming and non-streaming AnthropicBedrock invocation kwargs.

Automated hermes-sweeper review.

[JiaDe-Wu]

I measured this PR's mechanism against live Bedrock before commenting, and I want to lead with the good part: the header approach works. Then two things that will stop it landing as written.

The mechanism is correct — confirmed live

Temporary guardrail in us-east-2, one custom word filter on zorblax, blockedInputMessaging="BLOCKED_BY_GUARDRAIL_INPUT", prompt Say the single word zorblax and nothing else., model us.anthropic.claude-sonnet-5, via the same SDK this PR routes through:

AnthropicBedrock(aws_region="us-east-2").messages.create(
    model="us.anthropic.claude-sonnet-5", max_tokens=40, messages=[...],
    extra_headers={"X-Amzn-Bedrock-GuardrailIdentifier": gid,
                   "X-Amzn-Bedrock-GuardrailVersion": "DRAFT",
                   "X-Amzn-Bedrock-Trace": "ENABLED"})

WITHOUT headers -> stop_reason=end_turn  text=zorblax
WITH headers    -> stop_reason=end_turn  text=BLOCKED_BY_GUARDRAIL_INPUT

Same result through raw boto3 invoke_model(..., guardrailIdentifier=..., guardrailVersion="DRAFT"), RequestId 944fef8a-cab6-453b-914e-4e9bf03a3db3, amazon-bedrock-guardrailAction=INTERVENED. So your claim that InvokeModel headers give enforcement parity without giving up prompt caching / thinking / 1M context holds up. Guardrail deleted afterwards.

1. The detection won't fire

Look at the stop_reason in both runs above: end_turn, blocked or not. InvokeModel does not change it the way Converse does. This PR adds

"guardrail_intervened": "content_filter",   # transports/anthropic.py _STOP_REASON_MAP

and adds "guardrail_intervened" to the empty-content branch of the has-content check. Neither can ever trigger on this route — guardrail_intervened is a Converse stopReason, and this PR deliberately keeps Claude off Converse. The observable signal is in the response body:

model_extra = {"amazon-bedrock-guardrailAction": "INTERVENED",
               "amazon-bedrock-trace": {"guardrail": {"input": {"<gid>": {"wordPolicy":
                 {"customWords": [{"match": "zorblax", "action": "BLOCKED", ...

The Anthropic SDK keeps it as an unmodelled extra field, so getattr(response, "model_extra", {}) or {} reaches it — I verified that specific access, it is not a guess.

Worth fixing rather than deferring, because the current failure mode is the bad one: the headers do block, so BLOCKED_BY_GUARDRAIL_INPUT comes back as ordinary assistant text with a normal finish reason, and the agent then reasons over it as if the model had said it. A guardrail that silently substitutes text is harder to debug than one that visibly refuses.

2. It no longer applies to main

• merge-base 9df5f879b4, 17,633 commits behind 87cc4de430
• a real git merge --no-ff into today's main conflicts in 7 of 8 files: agent/agent_init.py, agent/anthropic_adapter.py, agent/chat_completion_helpers.py, agent/transports/anthropic.py, hermes_cli/runtime_provider.py, tests/agent/test_bedrock_integration.py, tests/agent/test_pet_generate.py
• more importantly, the code you patch has moved. git grep guardrail up_ssh/main -- hermes_cli/runtime_provider.py is now empty; the Bedrock routing and the guardrail_config build live in hermes_cli/runtime_provider_backends.py (_bedrock_guardrail_config at :172, the is_anthropic_bedrock_model(...) and not has_bearer_token branch at :218). Resolving the textual conflict in runtime_provider.py would leave the live path untouched.

I mention that second point specifically because a clean-looking git merge-tree misled me here first — it reported no conflicts for this PR, and the real merge found seven. Worth rebasing off an actual merge, not a merge-tree probe.

Two smaller notes on the rebase target:

• Your removal of if guardrail_config: runtime["guardrail_config"] = guardrail_config is right, and it is still dead on main: _runtime_agent_kwargs() in gateway/run.py is an explicit whitelist that does not include the key, so it is set on every Bedrock route and read on none. The Converse route only works because _init_bedrock_client re-reads config.yaml itself.
• openai.gpt-5.6-sol and friends resolve to api_mode="codex_responses" on Bedrock, which drops the guardrail the same way. Out of scope for this PR — flagging it so it does not look covered by "non-Claude models continue on Converse". (openai.gpt-oss-120b-1:0 does stay on Converse; the split is is_openai_bedrock_model.)

Full route table and the end-to-end reproduction are on #52179. Happy to re-run any of this against a rebased head.

[teknium1]

Thanks @JoaoMarcos44, the header mechanism was right and is now on main via #107815 (f845624), with credit in the commit and PR body.

Why a reimplementation rather than a rebase: the base was ~17k commits behind with conflicts in 7 of 8 files, the Bedrock routing had moved to hermes_cli/runtime_provider_backends.py, and the block detection was keyed on the Converse-only guardrail_intervened stopReason, which InvokeModel never emits (it returns end_turn and flags the block in amazon-bedrock-guardrailAction). The landed version attaches the headers at the client level so every AnthropicBedrock client gets them, and maps the INTERVENED body field to content_filter.

Closing as superseded by #107815.