# How does an instance detect the Silent Tool-Span Orphan When a GenAI Agent Aborts Mid-Tool-Call **Date of Record:** 2026 November 16 **Scope:** Applies to OpenTelemetry GenAI semantic conventions (agent spans, `execute_tool` child spans, and `gen_ai.usage.*` token metrics) emitted by agent runtimes that can cancel or crash between tool invocation and tool result. Does not apply to synchronous single-shot LLM calls with no tool loop, nor to runtimes that guarantee span closure via a supervisor process outside the instrumented boundary. ## Core Distinction The GenAI semantic conventions treat an agent invocation as a parent span (`gen_ai.operation.name = "invoke_agent"`) with child `execute_tool` spans carrying `gen_ai.tool.name`, `gen_ai.tool.call.id`, and a result attribute. The naive invariant an operator assumes is: *every `execute_tool` span that starts will end, and its parent agent span will aggregate its cost.* The non-obvious boundary is that **span emission and span closure are decoupled from the agent's logical lifecycle**. When an agent is aborted (context-window overflow, user cancellation, OOM kill of the worker, or a tool timeout enforced by the orchestrator), the tool child span may be *started but never ended*, or ended with `status = ERROR` while the parent agent span still records a successful `gen_ai.usage.output_tokens` total that excludes the tool's own token consumption. The result is an orphaned span that is neither a clean error nor a clean success, and whose cost is silently absent from the parent's aggregate. ## What Was Observed During a rollback of a tool-augmented agent, a subset of `invoke_agent` spans showed `status = OK` with `gen_ai.usage.output_tokens` values that were internally consistent but *lower than the sum of their child `execute_tool` spans' recorded token attributes*. Cross-referencing by `gen_ai.tool.call.id` revealed child spans whose `end_time` was absent (exported as incomplete) or whose `status.message` contained a cancellation string the parent never propagated. The parent's token counter had been flushed at the point of the last successful LLM turn, before the tool result was folded back in. The orchestrator, seeing a "successful" agent span, treated the run as complete and did not retry the tool. The tell was not an error rate spike — it was a *cost deficit*: aggregate `gen_ai.usage.output_tokens` across agent spans diverged from the sum of per-tool-call token attributes by a small, persistent fraction (0.3–1.1% depending on tool latency distribution). This deficit is invisible to latency SLOs and invisible to error-rate SLOs, because both the parent and the surviving children report healthy statuses. ## Condition of Validity This failure mode is *only* detectable when all three hold: 1. The runtime emits a stable `gen_ai.tool.call.id` on both the parent's tool-call attribute and the child span, allowing join. 2. Child `execute_tool` spans carry their own token attributes (`gen_ai.usage.input_tokens` / `output_tokens`) rather than deferring entirely to the parent. 3. The collector retains incomplete spans long enough to correlate (default tail-sampling that drops spans lacking `end_time` will erase the evidence). If the runtime emits no per-tool token attributes, the deficit is unmeasurable and the invariant is untestable — you cannot detect what was never recorded. If tail-sampling drops orphaned spans, the deficit appears as ordinary variance. ## Decision Boundary The boundary is between **treating an agent span's status as authoritative for its children** versus **reconstructing completion from the child set**. The correct operational rule: an `invoke_agent` span is only *complete* if the set of `gen_ai.tool.call.id` values referenced in its attributes is a subset of the child `execute_tool` spans that have both `start_time` and `end_time`. A parent with `status = OK` but a missing or unterminated child is a *phantom success* and must be reclassified before it feeds cost dashboards or retry logic. Do not trust the parent's token aggregate when any referenced tool call id lacks a terminated child; recompute from children and flag the delta. ## Operational Effect Once the phantom-success class is separated, the cost deficit resolves to a countable set of aborted-mid-tool runs, and the orchestrator can be made to retry exactly those tool calls (idempotent by `gen_ai.tool.call.id`) instead of trusting the parent's OK. The practical consequence is that agent token accounting becomes *reconcilable* rather than merely plausible: parent aggregate equals sum of terminated children plus an explicit, logged residue for aborted calls. Runtimes that skip this reconciliation will silently under-report cost on every cancellation path, and the error compounds with tool latency because longer tools widen the abort window. ```python from dataclasses import dataclass class OrphanedToolSpanError(RuntimeError): """Raised when an agent span claims success but a referenced tool call has no terminated child execute_tool span.""" pass @dataclass class ToolCall: call_id: str terminated: bool output_tokens: int @dataclass class AgentSpan: span_id: str status_ok: bool reported_output_tokens: int referenced_call_ids: list[str] children: dict[str, ToolCall] def reconcile_agent_span(span: AgentSpan) -> int: """Return the true output-token total, or raise if the span is a phantom success.""" missing = [ cid for cid in span.referenced_call_ids if cid not in span.children or not span.children[cid].terminated ] if missing and span.status_ok: raise OrphanedToolSpanError( f"agent span {span.span_id} reports OK but tool calls {missing} " f"have no terminated child span; reported tokens " f"{span.reported_output_tokens} are not reconcilable" ) return sum(c.output_tokens for c in span.children.values() if c.terminated) ```