feat(adk): propagate parent + root context_id headers on outbound A2A calls - #1927

Summary

Stamps two conversation-lineage HTTP headers on every outbound KAgentRemoteA2ATool call so a remote peer can correlate the turn with the originating chat conversation across a chain of A2A hops.

• x-kagent-parent-context-id — immediate caller's session id (changes per hop)
• x-kagent-root-context-id — top-of-chain context_id (stable across hops + across turns of the same conversation)

Closes #1926.

Why

KAgentRemoteA2ATool.run_async ships the outbound A2A message with context_id = self._last_context_id, a uuid4() minted once per tool instance. The receiving peer has no way to correlate the turn with the chat that started it. Anyone building multi-hop kagent fleets that key per-conversation state (sessions, worker pods, idempotency tokens, cache entries) on a stable identifier today either hand-rolls a header_provider on every tool or accepts losing continuity at every hop.

Motivating concrete failure mode: a chat-tier Declarative agent delegates to a router that spawns a per-conversation worker pod (e.g. a kubernetes-sigs/agent-sandbox SandboxClaim running claude --print); the router has no stable identifier to key the claim on, so a fresh pod spawns every turn and the user-visible symptom is "the agent loses memory between turns" even though the kagent UI thread is the same.

The receive side already copies all inbound HTTP headers into session.state["headers"] (set by A2aAgentExecutor.execute, lines 541-545), so no server-side plumbing change is needed — a peer that wants the root context_id just reads it from session state.

What changed

python/packages/kagent-adk/src/kagent/adk/_remote_a2a_tool.py

• Two new module-level header constants: PARENT_CONTEXT_ID_HEADER and ROOT_CONTEXT_ID_HEADER.
• _build_call_context now also derives a lineage-headers dict and merges it into the outbound ClientCallContext state. The existing header_provider callback still wins on overlap, so callers can override lineage when they need to.
• Helper _build_lineage_headers derives parent_context_id from tool_context.session.id and root_context_id from the inbound state["headers"] (forwarded unchanged when present, falls back to legacy parent header for older callers, falls back to caller's own session id when this agent is the chain root). Returns {} when no session id is resolvable so the outbound request matches pre-feature behavior on stub tool contexts.

python/packages/kagent-adk/tests/unittests/test_remote_a2a_tool.py

• Extends _MockSession/MockToolContext to expose id and state so lineage logic is testable.
• Extends _make_tool helper to forward an optional header_provider.
• New TestLineageHeaderPropagation class covers six cases:
  • Root agent stamps own id as parent + root.
  • Mid-chain agent forwards root unchanged + overrides parent with own id.
  • Legacy inbound with only parent header promotes it to root.
  • No session id → no lineage headers (non-breaking).
  • header_provider overrides lineage when callers need to.
  • End-to-end through _SubagentInterceptor onto outbound http_kwargs.headers.

Test plan

• uv run ruff format --diff → clean
• uv run ruff check → "All checks passed!"
• uv run pytest packages/kagent-adk/tests/unittests/test_remote_a2a_tool.py -q → 28 passed

Notes for reviewers

• Marked draft to gather design feedback first per CONTRIBUTING.md guidance. Happy to iterate on header naming, derivation rules, or scope.
• Backward-compatible: callers that ignore the new headers see no behavior change; callers that opt in just read session.state["headers"][ROOT_CONTEXT_ID_HEADER].
• The export of header-name constants is intentional so BYO consumers (from kagent.adk._remote_a2a_tool import ROOT_CONTEXT_ID_HEADER) avoid string-literal drift.