fix(sdk/python): let AsyncConfig env flags fall back to the class default - #1100

Summary

Takes the AsyncConfig half of #1089 — the point raised there about #1082. The other half (the
remaining strict parsers in logger.py, agent.py and agent_server.py) is #1090, and this PR does
not touch those files.

#1082 replaced five lambda x: x.lower() == "true" converters with two polarity-aware helpers. Each
one hard-codes the answer for "unrecognised string": _env_flag_default_on returns True,
_env_flag_default_off returns False. That is right for AsyncConfig's own field defaults, but it
makes the fallback independent of the class, so a subclass that changes a default gets the parser's
answer instead of its own:

@dataclass
class CachingOff(AsyncConfig):
    enable_result_caching: bool = False

# AGENTFIELD_ASYNC_ENABLE_RESULT_CACHING=maybe
CachingOff.from_environment().enable_result_caching   # True on main — should be False

Subclassing is a supported pattern here, not a hypothetical: AsyncConfig is a plain dataclass and both
public constructors take one (agent.py:846, client.py:182), and
test_client_keeps_explicit_async_config already pins that a caller-supplied instance is used as-is.

The fallback machinery is already correct — get_env_var catches (ValueError, TypeError) and returns
the default_value it was handed, which from_environment() passes as config.<field>, i.e. the
class's real default. The boolean converters simply never reach it, because a membership test cannot
fail. The float and int converters in the same function do reach it.

So this adds one polarity-free parser and points all five flags at it:

def _env_flag(value: str) -> bool:
    normalized = value.strip().lower()
    if normalized in _TRUE_VALUES:
        return True
    if normalized in _FALSE_VALUES:
        return False
    raise ValueError(f"unrecognised boolean environment value: {value!r}")

An unrecognised value now raises, get_env_var catches it, and the default comes from the class.

This also matches the Go control plane, which has always parsed this way: config.applyBoolEnv
(control-plane/internal/config/config.go:1128) leaves *target untouched and logs
warning: invalid %s=%q: %v; keeping %t when strconv.ParseBool rejects the string, and the handler
tests pin parseBool(" YeS ") → true, parseBool("0") → false, parseBool("maybe") → error.
Whitespace-tolerant, vocabulary-based, error on unknown. Go additionally logs a warning; Python's
float and int converters fall back silently today, so this matches the local convention rather than
adding logging — happy to add a warning too if you'd prefer the Go behaviour exactly.

AsyncConfig's own observable behaviour does not change. With no AGENTFIELD_ASYNC_* set,
get_env_var returns the default before consulting any converter, so the new code is never reached;
digesting every field of from_environment() on both trees gives the same SHA-256
(5960894a0c0bd6c817a09800eee26998e09625f7dfb23cd3d75ce1ee9088eb90). Vocabulary values parse exactly
as before, and out-of-vocabulary values still yield the field default for AsyncConfig itself — the
default just now comes from the class, which is what fixes the subclass case.

One thing to decide as a reviewer

_env_flag_default_on and _env_flag_default_off are kept, re-expressed in terms of _env_flag,
because #1090 contains from .async_config import _env_flag_default_off in logger.py and removing it
would break an open PR. A test pins both wrappers' contract.

The trade-off: after this change _env_flag_default_on has no caller anywhere in the repository (it was
only used by the four call sites this PR rewrites). I kept it because it is the matching half of a
two-day-old pair whose sibling #1090 depends on, and deleting one while keeping the other seemed like
arbitrary churn. If you would rather drop it, that is a one-line change and I am happy to.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Docs only
• Tests only
• CI / tooling
• Breaking change

Test plan

19 tests added to sdk/python/tests/test_async_config.py. On unmodified main they give 9 failed,
92 passed, distributed exactly as the defect predicts:

• 2 × the subclass scenarios above (a default-on flag forced off, and the default-off
  enable_event_stream forced on), each getting the parser's baked-in answer instead of the class's.
• 6 × test_every_flag_falls_back_to_its_own_class_default — all five flags × three unparseable values
  × three classes, of which only the two fields whose subclass default contradicts the baked-in polarity
  fail. The other nine pass on main too, so the failures are surgical rather than blanket.
• 1 × test_env_flag_rejects_values_outside_the_vocabulary (" ON " → True, "Off" → False,
  maybe/``/2/`truthy` → `ValueError`).
• test_polarity_wrappers_keep_their_contract_for_external_callers passes on main as well as after
  the fix — that is deliberate, it is the guard for fix(python-sdk): use SDK-wide truthy/falsy vocabulary for remaining strict env flags #1090's import.

All 82 tests already in the file (from #1082 and before) pass unchanged. The test subclasses are
decorated @dataclass; without that the inherited __init__ keeps the base defaults and the scenario
does not reproduce at all.

Commands run locally (Windows, CPython 3.13.12 in an isolated venv, pip install -e ".[dev]" plus
ruff==0.15.22 at the version sdk-python.yml pins):

• cd sdk/python && python -m pytest tests/test_async_config.py --no-cov → 101 passed
• cd sdk/python && python -m pytest --ignore=tests/test_agent_mesh.py --no-cov →
  9 failed, 2487 passed, 6 skipped, against 9 failed, 2468 passed, 6 skipped on unmodified
  main. 2487 = 2468 + 19, and the sorted set of failing test ids is byte-identical to main, so
  nothing regressed. Those 9 are pre-existing Windows-host failures — 'gbk' codec can't decode from
  pathlib.read_text, and b'inline\r' != b'inline\n' CRLF assertions — that pass on CI's
  ubuntu-latest. tests/test_agent_mesh.py is excluded because it hangs on this host at ~8%,
  verified to hang identically on unmodified main.
• cd sdk/python && python -m mypy --config-file mypy.ini agentfield/ → Success: no issues found in
  81 source files
• cd sdk/python && python -m ruff check . → All checks passed
• cd sdk/python && python -m ruff format --diff agentfield/async_config.py tests/test_async_config.py
  → 2 files already formatted

Test coverage

• I ran tests for the surface(s) I changed locally.
• New code paths are covered by tests in this PR (no bare additions).
• If I removed code, I updated coverage-baseline.json — not applicable; no source lines were
  removed that carried coverage, and no surface percentage can move (see below).
• The coverage gate check is green in CI before requesting review — I cannot run
  ./scripts/coverage-summary.sh locally because it measures all five surfaces and this machine has
  no Go, Bun, or Docker engine. Leaving this for CI rather than claiming it.

Heads-up so the gate output is not misread: agentfield.async_config is not in the --cov whitelist
in pyproject.toml's pytest addopts (which lists nine modules), and scripts/coverage-surface.sh
measures sdk-python by running bare pytest, so this file never reaches sdk-python-coverage.xml.
patch-coverage-gate.sh runs diff-cover against that XML and can only count lines the report knows
about, so this PR will report sdk-python | 0 | — | ➖ no changes. #1078 shows the mechanism — it
touched 2 executable lines in rate_limiter.py (whitelisted) plus 48 test lines and the gate reported
exactly 2 | 100.00%.

So the gate reporting "no changes" here is not evidence that the new code is untested. _env_flag is
exercised directly and through from_environment() for all five flags across truthy, falsey, padded,
unparseable and unset values, and both wrappers are pinned. Adding --cov=agentfield.async_config to
addopts would let the gate see this module — I left pyproject.toml alone to keep this to one seam,
and can send that separately if you want it.

Checklist

• I have read docs/CONTRIBUTING.md and docs/DEVELOPMENT.md.
• Commits are signed and follow conventional-commits style. — the subject follows
  conventional-commits; the commit is not signed, as I have no signing key configured. Flagging it
  rather than ticking the box.
• I have linked any related issues — Python SDK: remaining env flags with strict boolean parsing #1089 (this is the AsyncConfig half) and fix(sdk/python): parse AGENTFIELD_ASYNC boolean flags with the repo's env vocabulary #1082 (the PR it
  follows from). Not using a closing keyword, because fix(python-sdk): use SDK-wide truthy/falsy vocabulary for remaining strict env flags #1090 also fixes part of Python SDK: remaining env flags with strict boolean parsing #1089 and should not be
  pre-empted.

Related issues / PRs

• Python SDK: remaining env flags with strict boolean parsing #1089 — the issue this takes the AsyncConfig half of; the maintainer's description of the fix
  ("one parser that raises ValueError on unknown values, letting get_env_var's existing fallback
  return the class's real default") is what is implemented here.
• fix(sdk/python): parse AGENTFIELD_ASYNC boolean flags with the repo's env vocabulary #1082 — the PR that introduced the two polarity helpers this replaces for AsyncConfig.
• fix(python-sdk): use SDK-wide truthy/falsy vocabulary for remaining strict env flags #1090 — the other half of Python SDK: remaining env flags with strict boolean parsing #1089 (logger.py, agent.py, agent_server.py). No file overlap with
  this PR, but it imports _env_flag_default_off from async_config, which is why that helper is kept.
  Whichever merges second should be a clean rebase.