{
  "schema_version": "1.3.0",
  "slug": "in-what-scenarios-must-an-instance-propagate-rather-than-regenerate-the-parent-span-id-across-a-nested-multi-agent-handoff-retry",
  "title": "In what scenarios must an instance propagate rather than regenerate the parent span ID across a nested multi-agent handoff retry",
  "date_of_record": "2026 November 18",
  "scope": "Applies to distributed tracing in systems where an agent runtime spawns child agents (sub-agents, tool-calling agents, planner/executor pairs) and where any hop can retry independently. Does not apply to single-process instrumentation, nor to async fan-out where each child is an independent root by design (fire-and-forget jobs).",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/in-what-scenarios-must-an-instance-propagate-rather-than-regenerate-the-parent-span-id-across-a-nested-multi-agent-handoff-retry.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/in-what-scenarios-must-an-instance-propagate-rather-than-regenerate-the-parent-span-id-across-a-nested-multi-agent-handoff-retry.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/in-what-scenarios-must-an-instance-propagate-rather-than-regenerate-the-parent-span-id-across-a-nested-multi-agent-handoff-retry.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1331,
    "python_slice_tokens": 253,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The failure mode is not \"lost trace context\" — that produces a visibly broken trace and is easy to detect. The failure mode is **span ID regeneration on retry of a nested handoff**, which produces a trace that *looks* well-formed: every span has a parent, the trace ID is stable, and the tree renders. What is actually lost is the **retry identity**: a retried...",
    "what_was_observed": "In a three-tier handoff (orchestrator → planner agent → tool-executor agent), the planner issued a tool call whose transport timed out at the orchestrator's 30s deadline while the executor was still running. The orchestrator retried the handoff. The retry path re-entered the executor's `invoke()` wrapper, which — because it constructed a child span from the *current* context rather than from the *retry envelope* — mi...",
    "condition_of_validity": "The regenerate-on-retry behavior is only *safe* when the retried unit is genuinely idempotent-and-independent, i.e. when all three hold: 1. The retry has a fresh input set (not a re-delivery of the same logical request), and 2. Downstream consumers do not join spans by attempt identity, and 3. No partial work from the first attempt can surface later. In nest...",
    "decision_boundary": "At the handoff boundary, decide by *who owns the attempt*: - If the **caller** owns retry semantics (caller deadlines, caller-driven re-dispatch), the caller must mint the child span ID once, store it in the retry envelope, and pass it on every delivery. The callee adopts it. - If the **callee** owns retry semantics (internal retry loop inside the executor),...",
    "operational_effect": "Enforcing propagate-not-regenerate across nested handoffs converts a class of silent double-counting into an explicit, countable signal: retries appear as `retry.count > 0` on a single span with a single span ID, and the original stall remains visible in that span's duration. Cost attribution and latency percentiles become correct without downstream dedup he..."
  },
  "matched_failure_symptoms": [
    "DOMAIN:EPISTEMIC_PROVENANCE_AND_FEDERATION_ROUTING"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "974ffe8242588e6ce0573d86591e1657c9d05a0e19b7b455156c7b7ff221659c",
    "verified_classes": [
      "SpanPropagationError",
      "RetryEnvelope"
    ],
    "verified_functions": [
      "resolve_child_span_id"
    ],
    "verified_functions_count": 1,
    "defensive_guards_count": 3,
    "raised_exceptions": [
      "SpanPropagationError"
    ],
    "sample_fail_closed_invariants": [
      "first delivery of handoff requires a caller-minted attempt_span_id; callee must not mint its own"
    ],
    "stdlib_dependencies": [
      "dataclasses",
      "typing"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
