fix(delegation): resolve child fallback chains through the full pin x config matrix (#80450)

[ayushnangia]

Summary

Completes the delegation fallback-chain matrix from the #80450 cross-PR map: one pure function, _resolve_child_fallback_chain, implementing all six cells of the pin × delegation.fallback_providers decision table — composing the pin semantics of #80465 (@teknium1) with the config-chain semantics of #80438 (@wz-heng) / #80421 (@andrexibiza) for #65038 (@mlahatte), and settling the composition cell that all three leave undefined.

Root cause (the class)

Every open PR on this seam answers "which fallback chain does a non-head agent get?" for one input combination, editing the same parent_fallback hunk. The combinations interact: #80465 nulls the chain on pin, #80438/#80421 install a configured chain — land them in either order and pinned-child semantics differ silently. The matrix needs to be decided once, in one place.

Changes

tools/delegate_tool.py — _resolve_child_fallback_chain(parent_agent, delegation_cfg, pinned):

pin	delegation.fallback_providers	result
yes	declared, non-empty	declared chain — delegation-scoped recovery honors both explicit intents; the silent drag in #80450 is specifically the parent's chain substituting a pin
yes	declared, empty []	none — explicit disable
yes	absent	none — pin fails loudly (exactly #80465's semantics)
no	declared, non-empty	declared chain (exactly #80438/#80421's semantics, #65038)
no	declared, empty []	none — explicit disable
no	absent	inherit parent chain (historical behavior, byte-identical)

Malformed declared values log and fall back pin-aware (none when pinned, parent chain otherwise) — extending #80421's log-and-inherit contract so the config-error path can't reintroduce the drag. Entries normalize through the canonical hermes_cli.fallback_config.get_fallback_chain (ordering/dedupe identical to top-level chains). The two pre-existing inheritance tests are made hermetic against the real user config, as #80438 also did.

Validation

• tests/tools/test_delegate_fallback_matrix.py (14 tests): all six matrix cells, empty-parent edge, normalizer dedupe, pin-aware malformed fallback (both arms), non-dict config, plus four end-to-end wiring tests through _build_child_agent including pin+declared. Red on main: the suite fails collection (resolver doesn't exist); the wiring behaviors are unreachable.
• Neighbors: test_delegate.py + test_async_delegation.py + test_fallback_config.py — 88/88 via scripts/run_tests.sh.
• Interplay verified: the executable class map in test(delegation): executable class map for fallback-chain resolution (#80450) #80474 flips its three xfails to XPASS against this branch (1 passed, 1 skipped, 3 xpassed) — the map and this fix compose as designed.

Scope notes

• Deliberately deferential on landing order: if fix(delegation): honor pinned delegation.provider — no silent parent-fallback substitution #80465 lands first, this rebases to the declared-chain cells plus the precedence guard; if maintainers prefer folding any of it into fix(delegation): honor pinned delegation.provider — no silent parent-fallback substitution #80465 or the fix(delegation): honor worker fallback providers #80438/fix(delegation): honor delegation.fallback_providers for child agents #80421 pair, take it freely — the decision table and its tests are the point.
• If the precedence call goes the other way (pin + declared ⇒ loud-fail-only), it's a one-line change in the resolver and two test edits; the matrix structure stands either way.
• Chain-entry members (fix(agent): honor explicit api_mode on fallback chain entries #80209 api_mode, fix(fallback): benched credentials must not disqualify a chain entry #79840 benched credentials) and auxiliary agents (fix(review): propagate configured curator fallback chains #79750) are separate modules with their own PRs — unaffected here.

[ayushnangia]

Update per @andrexibiza's go-ahead on #80450: absorbed the complementary, non-overlapping parts of #80421 — the config_defaults entry, cli-config.yaml.example block, and user-guide docs for delegation.fallback_providers — as 29bcac3 with Co-authored-by credit. This PR now carries the full surface of the config-chain member (behavior + defaults + docs) alongside the matrix; #80438 remains a compatible alternative for the behavior half.

[spfcraze]

This was generated by AI during triage.

Summary:
A delegation.model-only pin (provider inherited) still inherits the parent fallback chain under this matrix, because the resolver keys its pin cell on override_provider alone — the model arm of #80450, which this PR cites, stays outside the fix.

Problems:

• The new call site passes pinned=bool(override_provider) to _resolve_child_fallback_chain (delegate_tool.py:1625 in head 29bcac3), so an explicit delegation.model without delegation.provider/base_url takes the unpinned column, where the resolver's default (default = None if pinned else parent_chain, :1334) hands the child the parent's chain.
• On origin/main, _resolve_delegation_credentials returns provider: None for that configuration ("No provider override — child inherits everything from parent"), so a model-only pin is exactly the case where override_provider is empty; delegate_task: pinned delegation.provider/model silently replaced at runtime by inherited parent fallback chain #80450's proposed fix names this arm ("or an explicit delegation.model pin").

Solution:
Key the pin on the model as well — pinned=bool(override_provider or model) at the call site — or state in the description that the matrix covers provider pins only.

---

Checked against 29bcac3 — the tip of fix/80450-fallback-matrix when this was written — and 0957277, main at the same moment.

[ayushnangia]

Correct catch — fixed in f536c90. The pin is now keyed on override_provider or model: at both call sites model is creds["model"], i.e. delegation.model config, so keying on it adds no false pins (per-task/LLM-chosen models never flow through that parameter), and base_url-only pins already resolve to a provider override in _resolve_delegation_credentials. Two matrix tests added for the model arm (absent chain → no inheritance; declared chain → declared), red before the fix. The resolver docstring now states the full pin definition: provider, base_url, or model-only.

[ayushnangia]

Triage update: #80438 closed into this family (wz-heng's comment cites this PR as the canonical coverage) — and #65052 is the config-plumbing layer beneath this one. Landing order note posted on #65052; the three PRs are layered, not competing.