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

[Prefix]

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
• E2E coverage — happy to add if a maintainer points at the right place; the change is non-breaking by construction (additive headers + no-op when no session id), so I scoped this PR to unit coverage initially.

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.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR adds propagation of conversation lineage headers to outbound A2A calls so downstream agents can correlate requests across multi-hop subagent chains.

Changes:

• Introduced x-kagent-parent-context-id and x-kagent-root-context-id header derivation and propagation in KAgentRemoteA2ATool.
• Updated call-context header merging logic to allow header_provider overrides while preserving lineage by default.
• Added unit tests covering lineage semantics and verifying headers reach outbound HTTP via _SubagentInterceptor.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
python/packages/kagent-adk/src/kagent/adk/_remote_a2a_tool.py	Adds lineage header constants and logic to compute/merge outbound propagation headers.
python/packages/kagent-adk/tests/unittests/test_remote_a2a_tool.py	Extends mocks to support session id/state and adds focused tests for lineage propagation & override behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[EItanya]

These changes make sense to me overall. @supreme-gg-gg is the expert on this flow so I'd like his take first. The one thing I'd like to say is that we should add this to the go runtime as well.

[Prefix]

added go lang