feat: add custom header support for provider requests

[tevenfeng]

Summary

• Add model.custom_headers config option to attach arbitrary HTTP headers to provider requests
• Add custom_providers[].custom_headers / providers.<name>.custom_headers for provider-specific headers; this is the only provider-level field, while headers is intentionally not supported to avoid ambiguity
• New agent/client_headers.py module with get_model_custom_headers() and merge_default_headers() helpers for header sanitization and ordered merging
• Propagate default_headers through the request chain: run_agent → auxiliary_client → anthropic_adapter → SDK client, including subagents via delegate_tool
• Preserve provider-level custom headers through CLI, oneshot, TUI/gateway/cron runtime paths, named custom providers, credential-pool resolution, direct-alias/bare-custom resolution, and Anthropic-compatible endpoints

Config Example

Global headers for all provider requests:

model:
  custom_headers:
    X-Source: "hermes-agent"
    X-Cost-Center: "team-ai-infra"

Provider-specific headers:

custom_providers:
  - name: "my-relay"
    base_url: "https://relay.example.com/v1"
    api_key: "sk-example"
    custom_headers:
      X-Relay-Key: "relay-secret"
      X-Cost-Center: "team-ai-infra"

The same field is supported after migration in the providers: map:

providers:
  my-relay:
    api: "https://relay.example.com/v1"
    api_key: "sk-example"
    custom_headers:
      X-Relay-Key: "relay-secret"

Closes #9398

Test Plan

• scripts/run_tests.sh tests/hermes_cli/test_runtime_provider_resolution.py tests/hermes_cli/test_config.py tests/cli/test_cli_provider_resolution.py tests/hermes_cli/test_tui_resume_flow.py tests/agent/test_auxiliary_named_custom_providers.py
• New tests/agent/test_client_headers.py — sanitization, merge semantics, empty/None inputs
• New tests in tests/agent/test_anthropic_adapter.py — header merge with Anthropic defaults, provider-override-wins-on-conflict
• New tests in tests/agent/test_auxiliary_client.py — _normalize_main_runtime header handling, _try_anthropic header propagation, explicit vs context priority
• Runtime/provider tests cover custom_providers[].custom_headers, providers.<name>.custom_headers, credential-pool propagation, bare-custom/direct-alias lookup, and migration preservation

[shailensobhee]

Nice! Tested it - this PR works :) Thanks..

[shailensobhee]

Btw, you seemed to have worked on 0.12. The code has conflicts with Hermes Agent v0.13.0 (2026.5.7) .

You may wish to make a new PR update?

Also, you check that verify: false is also treated such that config like this would work?

custom_providers:
    reject_unauthorized: false
      ss
  - id: "custom-model"
    name: "Some Endpoint"
    api_mode: "anthropic_messages"
    base_url: "https://custom-url"
    custom_headers:
      x-api-key: "somekey"
      Ocp-Apim-Subscription-Key: "somekey"
      Host: "custom-url.com"
    verify: false
    model: "Claude-Opus-4.6"
    context_length: 1000000

[tevenfeng]

you check that verify: false is also treated such that config like this would work?

Well i'm pretty sure that we still don't support verify: false yet, let me dig into the code more deeply and fix that when i have the time.

Also I find out that the provider-level 'headers' config may not work, I'll fix that(meanwhile we should rename that config to 'custom_headers' to avoid confusion)

[alt-glitch]

This was generated by AI during triage.

Related: #9518, #56244, and #50796 are the active custom-header cluster. Current #14314 carries both provider-level extra-header handling and backward-compatible model custom headers across more runtime paths, so it is related rather than a duplicate. A maintainer should select the canonical contract after the required rebase.