Repository navigation
Description
Part of #1810. Follow-up to #1906 §2, deferred out of the toolCall record so it does not block the export.
Problem
A tool call can end without a result, and the timeline already handles the case: when an agent finishes a tool and then cannot reach the model to report back — a lid closed, a VPN dropped — endStrandedTools ends the span at the first failed dial to a model host. Its own doc records why the pass exists: one 9-minute Bash drew as 8 hours before it, and the dial it cuts at measured within a fraction of a second of the tool's real end against Claude Code's transcripts.
The pairing package cannot see this case. core/session/toolpair was extracted from buildAgents alone (#2041), and endStrandedTools runs afterwards from Build, needing t.Agents, t.Turns and t.Hosts — none of which the pairing has. So a stranded call matches none of the four reasons toolpair knows (result, background, ended_run, stopped, abandoned).
The spec names the reason (endReason: "stranded", T31) and leaves where the cut runs Open (§2.2).
Why this is not cosmetic
Measured on one 30-day laptop archive: 56 dial-failed tunnel rows and 30 dial_failed errors. Stranding fires on real traffic.
Until this lands, a stranded call exports as abandoned, because lastAsk[agent] is after its start and that branch catches it. An abandoned call carries no duration (T16), so the export silently drops the timing of a call that did finish and was measured accurately.
That biases the part of the data the export exists to answer: a stranded call is disproportionately a long one — a closed laptop lid strands the 9-minute Bash, not the 24 ms Edit. So the undercount lands in the heavy tail, which is what §3.3's duration bands and any sandbox density figure turn on.
Two options
A. Carry the host-failure times into the pairing. toolpair.Calls gains an input — the failed-dial times per host — and decides stranded beside the other four reasons.
- For: the reason lives where every other reason lives; one place to read when the rules change.
- Against: changes the pairing's signature and its inputs. The pass is matched by host, not by agent (see below), so the input is not simply "this agent's failures".
B. Apply the stranding cut in the export, over the records it is about to write.
- For: the pairing's inputs stay as they are; the export already buffers a session to pair it.
- Against: a second implementation of a pass the timeline owns, which is the drift Refactor: Share the tool-call pairing between the timeline and the export #2041 exists to prevent. Would want the shared helper to be the cut itself, not a copy of it.
Author leans A, for #2041's reason: a closing case that exists twice drifts. But B is defensible if carrying host state into toolpair turns out to drag Hosts with it.
Three things the implementer needs to know
HasEndmust includestranded.toolpair.EndReason.HasEnd()isresult || backgroundtoday. A stranded call HAS an end, so without thisomitemptydrops the duration of one that measured 0 ms (spec T16's cross-PR note).strandedwins overresultandbackgroundwhen both apply. The result can arrive hours later once the network is back;buildAgentsends the call on it and the stranding pass then movesEndback to the dial. SoresultSeqstays present, anddurationMsends at the dial, not atresultSeq— the one case where those two disagree (spec §4.4a).- The cut is matched by host, not by agent, and that bounds what
strandedclaims.endStrandedTools's documentedshortcut:is that a blip in any other agent — a parent included — ends a tool whose own branch had no success first, so a subagent's longBashcan be cut where the main agent retried. Two agents stranded by one outage both end at its first failure. The upstream note says to revisit if CONNECTs come to carry the agent id.
Also worth fixing with it
timeline.Tool has no field for this: a stranded span is neither lost nor open, so a consumer filtering both still totals an outage-adjacent span as ordinary tool time. docs/session-export.md warns about it in prose (#2009), but exposing endReason on the span would make it checkable. That needs a timeline.Tool JSON change and an agentop story, so it is a separate decision — noted here so the two are not solved twice.
Where it lives
core/session/toolpair— the reason, and whichever input option A needscore/session/timeline/timeline.go—endStrandedTools, andlostForinagents.gocore/sessionexport— the record'sendReason, if option Bdocs/superpowers/specs/2026-11-19-tool-call-export-record-design.md— §2.2's Open item, T16, T31
Assisted-By: Claude (Anthropic AI) noreply@anthropic.com
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsNew/ToDo
Activity
Docs: Say resultSeq answers whether a result arrived, and that T31 is…
Docs: Spec the toolCall export record, and correct the per-tool laten…
webchang commentedon Nov 21, 2026
From the consumer side: our trajectory format (rossoctl/trajectory-schema v2.2) and its converter for the
toolCallexport already take this case as specified in #2009.endReason: "stranded"maps to an end reasonstrandedthat requires a duration. ItsdurationMsand itsresultSeq(when a result arrived later) are kept as given, and the end reason is never inferred fromresultSeq.backgrounded(T32a) maps to its own flag, so a call that is both stranded and backgrounded keeps both facts.That makes item 1 a hard requirement for us, not just a nicety. We tested a
strandedrecord whosedurationMswas omitted: it converts to a file our validator rejects, because a stranded call must carry its duration. So please makeHasEndincludestrandedbefore the export writes it. Until then, the interimabandoned(with no duration) converts cleanly.webchang commentedon Nov 21, 2026
A small update to my previous comment: our converter now (trajectory-schema v2.2.1) handles a
strandedrecord withoutdurationMsgracefully. It reports the record and writes the call without the end reason, so the output stays valid instead of being rejected. Item 1 still matters as much as before, though: withoutHasEndincludingstranded, both the reason and the measured duration of such a call would be lost on our side.webchang commentedon Nov 21, 2026
@mrsabath, a short summary of our two comments above, for when you pick this up:
Our trajectory format and its converter for the toolCall export already support this case, as #2009 specifies it. A stranded call keeps its measured durationMs, and its resultSeq if a result arrives later. The end reason is never inferred from resultSeq. The backgrounded flag (T32a) is kept separately, so a call that is both stranded and backgrounded keeps both facts.
Item 1 in this issue is the part that matters most to us: HasEnd must include stranded. If it doesn't, the zero-omission rule drops a measured 0 ms duration. When we tested a stranded record without durationMs, our converter could no longer keep the call's reason or its duration. It now reports the record and writes the call without the reason, so the output stays valid, but the facts are lost. Until this lands, the interim export as "abandoned" (with no duration) converts cleanly on our side.