Feature Request: Typed Config-Runtime Contract

Supersedes: This FR has been expanded from the original "Typed Plugin Hook Protocol" scope. Hook calls are one sub-pattern; this FR now covers the full contract gap across config→runtime, state→path, and interface→caller boundaries.

Value Score: 44/60 (73%) — HIGH VALUE

No existing FR covers this scope. Related:

• Config schema validation: missing Pydantic/schema enforcement #27342 (Config schema validation) is complementary — validates config shape at load time, doesn't ensure consumers read fields
• feat(display): declarative tool preview schema to eliminate per-tool hardcoding #28621 (Declarative tool preview) is the same structural pattern in a different domain (display)

Problem

Hermes has no contract layer between config/state producers and consumers. When a new field is added to config.yaml, a hook signature, or a state object, there is no mechanism to ensure every downstream consumer picks it up. The result: silent failures that only surface when users hit the un-updated code path.

This is not a theory — it is the #1 recurring bug pattern in the open issue tracker.

Evidence: 17 bugs, one root cause, four sub-patterns

We analyzed 100 open bug issues and found 17 that follow the exact same structural defect. They break into four sub-patterns:

Sub-pattern 1: Config field declared, no consumer (4 bugs)

New config.yaml key added and documented, but the bridge code that maps it to a runtime variable/env-var was never updated.

Sub-pattern 2: Path A works, path B broken (5 bugs)

Feature works correctly on one execution path (e.g., startup) but is broken on another (e.g., /model switch, gateway restart, fallback activation). The logic was copy-pasted or reimplemented instead of shared.

Sub-pattern 3: Interface expanded, caller missed (3 bugs)

A hook signature, callback, or protocol method was extended with new parameters, but not all call sites were updated.

Sub-pattern 4: State added, not propagated (3 bugs)

A new field was added to a state dict/object, but not all paths that serialize/deserialize/transform that state preserve the new field.

(✅ = already fixed, listed here as evidence the pattern is real and fixable)

Also related (same structural pattern, different domain)

Why individual fixes don't scale

Each of the 5 bugs we fixed required ~30 lines of targeted code. But fixing #28046 (max_tokens) did nothing to prevent #28863 (docker_extra_args) — they're the same structural defect manifesting in different config keys. Every new config field or code path is a ticking time bomb until someone reports it.

The pattern will keep recurring as long as producer→consumer bindings remain implicit.

Proposed Solution

A lightweight contract layer that makes bindings declarative and verifiable — not a big-bang rewrite, but an incremental rollout:

Phase 1: Config Field Registry + Startup Validator

Define a registry mapping config keys to their expected consumers:

CONFIG_CONTRACTS = {
    "terminal.docker_extra_args": {
        "env_var": "TERMINAL_DOCKER_EXTRA_ARGS",
        "consumer": "gateway.run._terminal_env_map",
        "type": list[str],
    },
    "custom_providers.*.models.*.max_tokens": {
        "consumer": "agent.agent_init",
        "fallback": 4096,
        "type": int,
    },
}

On startup, validate every declared field has at least one active consumer. Emit warnings (not errors) for:

• Orphan fields (declared in config, no consumer registered)
• Stale bindings (consumer references a field that no longer exists)

Zero behavior change — purely additive observability.

Phase 2: Typed Hook Payloads

Replace ad-hoc kwargs in plugin hook invocations with typed payloads:

@dataclass
class PreToolCallPayload:
    session_id: str
    tool_call_id: str
    tool_name: str
    tool_input: dict
    # Future fields added here automatically propagate

# Single entry point constructs the payload — all call sites get every field

This is the original scope from this FR (#28961, #25204, #7344). A Protocol-based approach ensures any new field added to the payload is structurally visible to all consumers.

Phase 3: Path Parity Tests

A test helper that verifies: if path A (startup) reads/configures field X, then path B (/model switch, gateway restart, fallback) must also read X.

def assert_config_path_parity(field: str, paths: list[str]):
    """Fail CI if any declared path doesn't consume the field."""

This turns "path divergence" bugs into CI failures before they reach users.

What this prevents

Existing proof of concept

The generic get_custom_provider_model_field() function introduced in PR #28988 (fixing #28046) is a working micro-example of this approach: instead of separate get_custom_provider_context_length() and get_custom_provider_max_tokens() functions with duplicated logic, we extracted a single generic lookup that any new per-model config field can use without writing new bridge code.

Fixes (as evidence): #28046, #28961, #28841, #28663, #28296
Would prevent: #28863, #28662, #28034, #28753, #28651, #28489, #28023, #28746, #28637, #28825, #28632, #28055
Related: #27342 (complementary), #28621 (same pattern, different domain)