From 81a34156a56b0ecbe19d1b2e1b02ad06a3294a5d Mon Sep 17 00:00:00 2001 From: emozilla Date: Fri, 26 Jun 2026 23:28:50 -0400 Subject: [PATCH] docs(telemetry): clarify reserved subagent-lineage hooks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The subagent_start/stop hooks are registered but no-op. The prior comment implied subagents need no handling because they inherit via contextvars — misleading, since a delegated child runs on a separate thread with its own session id and trace. Clarify the real situation: a subagent's model/tool calls are already captured as their own tel_runs row via the child's run_conversation, so nothing is lost. These hooks are reserved for recording parent->child lineage (needs a tel_runs.parent_run_id column), deferred until a consumer needs the delegation tree. Comment-only. --- plugins/telemetry/__init__.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/plugins/telemetry/__init__.py b/plugins/telemetry/__init__.py index 43ca8a10e7c..0f5157295c9 100644 --- a/plugins/telemetry/__init__.py +++ b/plugins/telemetry/__init__.py @@ -296,9 +296,15 @@ def _as_float(v: Any) -> Optional[float]: # ── subagent lineage (reserved) ───────────────────────────────────────────── +# A delegated subagent runs its own ``run_conversation`` with its own session id, so +# its model/tool calls are already captured as a separate tel_runs row via the normal +# hooks — no subagent activity is lost. These hooks fire with the parent<->child bridge +# (parent_session_id, child_session_id, child_role, child_goal); they are reserved for +# recording parent->child *lineage* (linking a child run back to its parent), which +# needs a tel_runs.parent_run_id column. Deferred until a consumer needs the delegation +# tree; left registered as the attachment point. @_safe def _on_subagent_start(**kw: Any) -> None: - # Subagents inherit the run context via contextvars; no explicit handling needed. return None