@senpi/runtime 3.0.180 → 3.0.181

package/dist/telemetry/spans/span-hooks.js

@@ -8,6 +8,21 @@
  *   - subagent_* lifecycle    → `invoke_agent` (INTERNAL), parented to the model span
  *   - agent_end               → ends any still-open spans for the run
  *
+ * On OpenClaw 10.x (`modernHost`):
+ *   - there is no `subagent_spawning` hook, so `subagent_spawned` opens the `invoke_agent` span;
+ *   - the tool-search tools (`tool_search`, `tool_describe`, and the dispatcher `dispatch_action`,
+ *     `tool_call` on 10.4) get `execute_tool` spans with `senpi.tool.bridge = true` and count on
+ *     `tool.bridge.calls`, not `tool.calls`. The inner tool a dispatcher runs (id
+ *     `tool_call:<sanitized outer id>:…`) nests under the dispatcher's span. Its own
+ *     `after_tool_call` normally closes it (10.10 `embedded-agent-subscribe.handlers.tools.completion.ts:603-626`);
+ *     any inner span still open when the dispatcher's `after_tool_call` fires is closed there with
+ *     the outer outcome, and a late inner `after_tool_call` for it is then ignored, so each inner call
+ *     is counted and evented once under its own name.
+ *
+ * On both hosts each `chat` span carries `senpi.llm.calls` (the run's `model_call_ended` count),
+ * and the drift alarm skips any unoffered name the host ran in the run (a direct call to a deferred
+ * tool is legal in 10.x tool-search directory mode).
+ *
  * Open and finalize are separate callbacks, so we can't use `withSpan`; we `startSpan`
  * and hold the handle in a session-keyed registry until the finalize hook, recording
  * errors directly on the held span (it's never the active span, so `logger.error` won't).
@@ -21,7 +36,7 @@ import { SpanKind, context as otelContext, propagation, trace, } from "@opentele
 import { getTracer } from "../../telemetry/tracing.js";
 import { HEADER_ADDRESS, HEADER_CORRELATION_ID, HEADER_RECIPE_NAME, HEADER_RUNTIME_ID, HEADER_RUNTIME_VERSION, } from "./constants.js";
 import { GEN_AI, errorTypeOf, firstNumber, normalizeGenAiMessages, recordSpanError, setDefinedAttributes, setGenAiContentAttribute, toFinishReasons, } from "./gen-ai.js";
-import { elapsedSeconds, recordToolCall, recordInvokeAgentDuration, recordOperationDuration, recordTokenUsage, } from "../../telemetry/metrics.js";
+import { elapsedSeconds, recordToolBridgeCall, recordToolCall, recordInvokeAgentDuration, recordOperationDuration, recordTokenUsage, } from "../../telemetry/metrics.js";
 import { emitToolCalled, offeredToolNames, requestedToolNames, } from "../../telemetry/tool-plane.js";
 import { createLogger } from "../../utils/logger.js";
 const logger = createLogger("[senpi-core][span-hooks]");
@@ -30,6 +45,23 @@ const logger = createLogger("[senpi-core][span-hooks]");
  * `skill_router.decision` event shares (`src/utils/event-catalog.ts`). Distinct from `senpi.run.id`.
  */
 const OPENCLAW_RUN_ID_ATTR = "senpi.openclaw.run_id";
+/** The tool-search bridge tools and their `senpi.tool.bridge_kind` (10.10 `src/agents/tool-search-types.ts:10-12`; `tool_call` is the 10.4 dispatcher). */
+const BRIDGE_TOOL_KINDS = {
+    tool_search: "search",
+    tool_describe: "describe",
+    dispatch_action: "call",
+    tool_call: "call",
+};
+/**
+ * Port of OpenClaw's inner-call id sanitizer
+ * (`openclaw-worktrees/v2026.10.10-beta.3/src/agents/tool-search-runtime.ts:211-214`): the inner
+ * call a dispatcher runs gets the id `tool_call:${sanitizeToolCallIdPart(outerToolCallId)}:…`
+ * (the literal `tool_call:` prefix is kept on 10.10, where only the dispatcher was renamed).
+ */
+export function sanitizeToolCallIdPart(value) {
+    const safe = value.trim().replace(/[^A-Za-z0-9_.:-]+/g, "_");
+    return safe.slice(0, 120) || "call";
+}
 /**
  * Grace window the `agent_end` sweep holds a finished model span before ending it, so a
  * trailing `llm_output` (observed ~1 ms later in the codex/harness flow, but timed generously)
@@ -37,9 +69,20 @@ const OPENCLAW_RUN_ID_ATTR = "senpi.openclaw.run_id";
  * process open; an orphan run with no `llm_output` lets the timer end the span.
  */
 export const MODEL_SPAN_END_GRACE_MS = 2000;
+/**
+ * Registers the span hooks.
+ *
+ * @returns How many hooks were registered (10 on 5.x; 9 on 10.x, which has no `subagent_spawning`).
+ */
 export function registerSpanHooks(options) {
     const { api } = options;
+    const modernHost = options.modernHost === true;
     const tracer = getTracer();
+    let hookCount = 0;
+    const on = (hookName, handler, opts) => {
+        api.on(hookName, handler, opts);
+        hookCount += 1;
+    };
     // Cap on drift events per turn so a flood of invented tool calls can't balloon the log.
     const MAX_DRIFT_EVENTS_PER_TURN = 8;
     // Held model spans, keyed by (sessionKey, runId). The tool/subagent spans parent
@@ -54,13 +97,23 @@ export function registerSpanHooks(options) {
     // (agentId → sessionKey/runId) from llm_input, plus the last-seen pair, so tool
     // hooks can resolve their host session.
     const sessionByAgentId = new Map();
+    // Latest run per session, for a 10.x subagent_spawned whose ctx names the requester session but
+    // not its run (ctx.runId is the child run there).
+    const latestRunBySession = new Map();
     let lastActive = null;
     const rememberSession = (agentCtx, sessionKey, runId) => {
         const agentId = nonEmptyString(asRecord(agentCtx)?.agentId);
         if (agentId)
             sessionByAgentId.set(agentId, { sessionKey, runId });
+        latestRunBySession.set(sessionKey, runId);
         lastActive = { sessionKey, runId };
     };
+    /** Stamps the run's model-call count on a `chat` span about to end. */
+    const stampLlmCalls = (held) => {
+        if (held.llmCalls && held.llmCalls > 0) {
+            setDefinedAttributes(held.span, { "senpi.llm.calls": held.llmCalls });
+        }
+    };
     const resolveToolSession = (ctx) => {
         const direct = {
             sessionKey: readSessionKey(ctx, undefined),
@@ -86,7 +139,7 @@ export function registerSpanHooks(options) {
         return model ? trace.setSpan(otelContext.active(), model.span) : otelContext.active();
     };
     // ─── LLM (`chat` span) ───────────────────────────────────────────────────
-    api.on("llm_input", (event, agentCtx) => {
+    on("llm_input", (event, agentCtx) => {
         try {
             const identity = readIdentity(agentCtx);
             const sessionKey = readSessionKey(agentCtx, event);
@@ -100,8 +153,13 @@ export function registerSpanHooks(options) {
             // A duplicate llm_input for the same (session, run) means a new turn opened
             // without the previous one closing — end the prior span before replacing it.
             const prior = modelSpans.get(key);
-            if (prior)
+            if (prior) {
+                // Its agent_end grace timer would end the replaced span a second time.
+                if (prior.endTimer)
+                    clearTimeout(prior.endTimer);
+                stampLlmCalls(prior);
                 endSpan(prior.span);
+            }
             const ev = asRecord(event) ?? {};
             const requestModel = nonEmptyString(ev.model);
             const provider = nonEmptyString(ev.provider);
@@ -148,7 +206,7 @@ export function registerSpanHooks(options) {
             logger.warn("llm_input handler failed", { err: errMsg(err) });
         }
     });
-    api.on("llm_output", (event, agentCtx) => {
+    on("llm_output", (event, agentCtx) => {
         try {
             const sessionKey = readSessionKey(agentCtx, event);
             const runId = readRunId(agentCtx, event);
@@ -167,6 +225,7 @@ export function registerSpanHooks(options) {
             // Cancel any deferred teardown the agent_end sweep scheduled — we finalize the span here.
             if (held.endTimer)
                 clearTimeout(held.endTimer);
+            stampLlmCalls(held);
             const ev = asRecord(event) ?? {};
             const usage = asRecord(ev.usage);
             // Token field naming varies by provider/wrapper; try every known spelling.
@@ -201,9 +260,14 @@ export function registerSpanHooks(options) {
             // deduped + capped so a flood of invented calls can't balloon the log.
             if (held.offeredTools) {
                 const offered = held.offeredTools;
+                // A name the host ran in this run is not invented: in 10.x tool-search directory mode a
+                // direct call to any deferred tool (a `senpi__` MCP tool or a deferred OpenClaw tool) is
+                // legal though not in the offered set (`tool-search-directory.ts:194-197` on 10.10). An
+                // unoffered name that never ran is drift on every host and in every mode.
+                const ran = held.ranTools;
                 const seen = new Set();
                 for (const name of requestedToolNames(outputMessages)) {
-                    if (offered.has(name) || seen.has(name))
+                    if (offered.has(name) || seen.has(name) || ran?.has(name))
                         continue;
                     if (seen.size >= MAX_DRIFT_EVENTS_PER_TURN)
                         break;
@@ -237,7 +301,7 @@ export function registerSpanHooks(options) {
     // The provider-call result: `outcome`, `failureKind`, timing. This is the ONLY
     // signal for a failed/aborted turn — `llm_output` never fires when the call
     // errors, so without this a wedged turn is indistinguishable from a healthy one.
-    api.on("model_call_ended", (event, agentCtx) => {
+    on("model_call_ended", (event, agentCtx) => {
         try {
             const sessionKey = readSessionKey(agentCtx, event);
             const runId = readRunId(agentCtx, event);
@@ -246,6 +310,7 @@ export function registerSpanHooks(options) {
             const held = modelSpans.get(sessionLlmKey(sessionKey, runId));
             if (!held)
                 return; // span already finalized, or not one we opened — best effort.
+            held.llmCalls = (held.llmCalls ?? 0) + 1;
             const ev = asRecord(event) ?? {};
             const outcome = nonEmptyString(ev.outcome);
             const failureKind = nonEmptyString(ev.failureKind);
@@ -270,7 +335,59 @@ export function registerSpanHooks(options) {
         }
     });
     // ─── Tool (`execute_tool` span) ────────────────────────────────────────────
-    api.on("before_tool_call", (event, toolCtx) => {
+    // Inner calls a dispatcher's after_tool_call closed, so their own late after_tool_call is not
+    // counted again; the value says whether that close already evented a failure (the outer call
+    // errored). FIFO-bounded: a host that never sends that late hook must not grow it.
+    const closedByDispatcher = new Map();
+    const CLOSED_BY_DISPATCHER_MAX = 512;
+    const innerKey = (sessionKey, runId, toolCallId) => `${sessionKey} ${runId} ${toolCallId}`;
+    const markClosedByDispatcher = (key, failureEvented) => {
+        closedByDispatcher.set(key, failureEvented);
+        while (closedByDispatcher.size > CLOSED_BY_DISPATCHER_MAX) {
+            const oldest = closedByDispatcher.keys().next().value;
+            closedByDispatcher.delete(oldest);
+        }
+    };
+    /**
+     * A 10.x dispatcher's open `execute_tool` span in this run whose inner-call prefix
+     * `tool_call:${sanitize(outer id)}:` starts `innerToolCallId`, for parenting the inner span.
+     */
+    const findDispatcherSpanFor = (sessionKey, runId, innerToolCallId) => {
+        for (const held of toolSpans.values()) {
+            if (held.bridgeKind !== "call" || !held.toolCallId)
+                continue;
+            if (held.sessionKey !== sessionKey || held.runId !== runId)
+                continue;
+            if (innerToolCallId.startsWith(`tool_call:${sanitizeToolCallIdPart(held.toolCallId)}:`))
+                return held;
+        }
+        return undefined;
+    };
+    /** Records the outcome on a held tool span and ends it, after its args stamping settles. */
+    const finalizeToolSpan = (held, errored, error, result) => {
+        const span = held.span;
+        void (async () => {
+            try {
+                if (held.pending)
+                    await held.pending;
+                if (errored) {
+                    recordSpanError(span, error);
+                }
+                else {
+                    await setGenAiContentAttribute(span, GEN_AI.TOOL_CALL_RESULT, result);
+                }
+            }
+            finally {
+                try {
+                    span.end();
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+        })();
+    };
+    on("before_tool_call", (event, toolCtx) => {
         try {
             const identity = readIdentity(toolCtx);
             const resolved = resolveToolSession(toolCtx);
@@ -283,14 +400,27 @@ export function registerSpanHooks(options) {
             const toolCallId = nonEmptyString(ev?.toolCallId) ??
                 nonEmptyString(asRecord(toolCtx)?.toolCallId) ??
                 null;
+            const model = modelSpans.get(sessionLlmKey(resolved.sessionKey, resolved.runId));
+            if (model)
+                (model.ranTools ??= new Set()).add(toolName);
+            const bridgeKind = modernHost ? BRIDGE_TOOL_KINDS[toolName] : undefined;
+            // An inner call a 10.x dispatcher runs nests under the dispatcher's span.
+            const dispatcher = modernHost && !bridgeKind && toolCallId?.startsWith("tool_call:")
+                ? findDispatcherSpanFor(resolved.sessionKey, resolved.runId, toolCallId)
+                : undefined;
             const key = toolKey(resolved.sessionKey, resolved.runId, toolCallId, toolName, ++toolSeq);
-            const span = tracer.startSpan(`execute_tool ${toolName}`, { kind: SpanKind.INTERNAL }, parentContextForModel(resolved.sessionKey, resolved.runId));
+            const span = tracer.startSpan(`execute_tool ${toolName}`, { kind: SpanKind.INTERNAL }, dispatcher
+                ? trace.setSpan(otelContext.active(), dispatcher.span)
+                : parentContextForModel(resolved.sessionKey, resolved.runId));
             const held = {
                 span,
                 sessionKey: resolved.sessionKey,
                 runId: resolved.runId,
                 startMs: Date.now(),
                 toolName,
+                ...(toolCallId ? { toolCallId } : {}),
+                ...(bridgeKind ? { bridgeKind } : {}),
+                ...(bridgeKind === "call" ? { requestedId: nonEmptyString(asRecord(ev?.params)?.id) } : {}),
             };
             toolSpans.set(key, held);
             setDefinedAttributes(span, {
@@ -299,6 +429,7 @@ export function registerSpanHooks(options) {
                 [OPENCLAW_RUN_ID_ATTR]: resolved.runId,
                 [GEN_AI.TOOL_NAME]: toolName,
                 [GEN_AI.TOOL_CALL_ID]: toolCallId ?? undefined,
+                "senpi.tool.bridge": bridgeKind ? true : undefined,
                 // Best-effort skill attribution from a skill-file read (no first-class skill hook exists).
                 "senpi.skill.name": skillNameFromToolArgs(ev?.params ?? ev?.input),
                 ...identityAttributes(identity),
@@ -311,42 +442,117 @@ export function registerSpanHooks(options) {
             logger.warn("before_tool_call handler failed", { err: errMsg(err) });
         }
     });
-    api.on("after_tool_call", (event, toolCtx) => {
+    on("after_tool_call", (event, toolCtx) => {
         try {
             const resolved = resolveToolSession(toolCtx);
-            if (!resolved) {
-                logger.debug("after_tool_call session unresolved; skipping");
-                return;
-            }
             const ev = asRecord(event);
             const toolName = nonEmptyString(ev?.toolName) ?? nonEmptyString(ev?.name) ?? "unknown";
             const error = ev?.error;
             const errored = error !== undefined && error !== null;
-            // Tool-plane event (narrative): a failed tool call — the agent-blind hole, greppable instead
-            // of span-only. A successful call already rides its span + (state-changing) its domain event,
-            // so it is not re-evented here. Emitted before the span lookup so a failure is never lost when
-            // the matching before_tool_call span wasn't registered.
-            if (errored) {
+            const result = ev?.result;
+            const toolCallId = nonEmptyString(ev?.toolCallId) ??
+                nonEmptyString(asRecord(toolCtx)?.toolCallId) ??
+                null;
+            const bridgeKind = modernHost ? BRIDGE_TOOL_KINDS[toolName] : undefined;
+            const emitFailure = (name, bridge) => {
                 emitToolCalled({
-                    name: toolName,
+                    name,
                     origin: "agent",
                     outcome: "error",
                     errorType: errorTypeOf(error),
                     errorMessage: error instanceof Error ? error.message : String(error),
+                    ...(bridge ? { bridge: true } : {}),
                 });
+            };
+            const foundKey = resolved
+                ? findToolKey(toolSpans, resolved.sessionKey, resolved.runId, toolCallId, toolName)
+                : undefined;
+            const held = foundKey ? toolSpans.get(foundKey) : undefined;
+            if (foundKey)
+                toolSpans.delete(foundKey);
+            if (bridgeKind) {
+                // Inner calls of this dispatcher still open: their own after_tool_call normally closed them
+                // first (10.10/10.4), so these are the ones it missed. They take the outer outcome here,
+                // count once under their own names, and a late after_tool_call for them is ignored.
+                const inner = [];
+                if (bridgeKind === "call" && resolved && toolCallId) {
+                    const prefix = `tool_call:${sanitizeToolCallIdPart(toolCallId)}:`;
+                    for (const [k, h] of toolSpans) {
+                        if (h.sessionKey !== resolved.sessionKey || h.runId !== resolved.runId)
+                            continue;
+                        if (!h.toolCallId?.startsWith(prefix))
+                            continue;
+                        toolSpans.delete(k);
+                        markClosedByDispatcher(innerKey(h.sessionKey, h.runId, h.toolCallId), errored);
+                        inner.push(h);
+                    }
+                }
+                if (errored) {
+                    if (inner.length > 0) {
+                        for (const h of inner)
+                            emitFailure(h.toolName ?? "unknown");
+                    }
+                    else if (bridgeKind === "call" && held?.innerErrored) {
+                        // The inner call's own after_tool_call already reported this failure.
+                    }
+                    else if (bridgeKind === "call") {
+                        // No inner call, or one that succeeded: the dispatcher's own failure (a cap, a result
+                        // post-processing error) is still a failure the agent saw, so it is always evented.
+                        const requested = held?.requestedId ?? nonEmptyString(asRecord(ev?.params)?.id);
+                        emitFailure(requested ?? toolName, requested !== undefined);
+                    }
+                    else {
+                        emitFailure(toolName);
+                    }
+                }
+                for (const h of inner) {
+                    recordToolCall({
+                        toolName: h.toolName,
+                        origin: "agent",
+                        outcome: errored ? "error" : "ok",
+                        errorType: errored ? errorTypeOf(error) : undefined,
+                        durationSec: elapsedSeconds(h.startMs),
+                    });
+                    finalizeToolSpan(h, errored, error, result);
+                }
+                recordToolBridgeCall({ kind: bridgeKind, outcome: errored ? "error" : "ok" });
+                if (held)
+                    finalizeToolSpan(held, errored, error, result);
+                return;
             }
-            const toolCallId = nonEmptyString(ev?.toolCallId) ??
-                nonEmptyString(asRecord(toolCtx)?.toolCallId) ??
-                null;
-            const foundKey = findToolKey(toolSpans, resolved.sessionKey, resolved.runId, toolCallId, toolName);
-            if (!foundKey) {
+            // A late after_tool_call for an inner call its dispatcher already closed and counted. Its
+            // span and metric are done; a failure it reports is still evented unless the dispatcher's
+            // close already did (a dispatcher can return an inner error to the model as a result).
+            if (modernHost && resolved && toolCallId) {
+                const k = innerKey(resolved.sessionKey, resolved.runId, toolCallId);
+                const failureEvented = closedByDispatcher.get(k);
+                if (failureEvented !== undefined) {
+                    closedByDispatcher.delete(k);
+                    if (errored && !failureEvented)
+                        emitFailure(toolName);
+                    return;
+                }
+            }
+            // Tool-plane event (narrative): a failed tool call — the agent-blind hole, greppable instead
+            // of span-only. A successful call already rides its span + (state-changing) its domain event,
+            // so it is not re-evented here. Emitted before the span check so a failure is never lost when
+            // the matching before_tool_call span wasn't registered.
+            if (errored)
+                emitFailure(toolName);
+            // Tell the still-open dispatcher that its inner call's failure is already reported.
+            if (errored && modernHost && resolved && toolCallId?.startsWith("tool_call:")) {
+                const dispatcher = findDispatcherSpanFor(resolved.sessionKey, resolved.runId, toolCallId);
+                if (dispatcher)
+                    dispatcher.innerErrored = true;
+            }
+            if (!resolved) {
+                logger.debug("after_tool_call session unresolved; skipping");
+                return;
+            }
+            if (!held) {
                 logger.debug("after_tool_call: no open tool span", { toolName, toolCallId });
                 return;
             }
-            const held = toolSpans.get(foundKey);
-            const span = held.span;
-            toolSpans.delete(foundKey);
-            const result = ev?.result;
             recordToolCall({
                 toolName: held.toolName,
                 origin: "agent",
@@ -354,83 +560,83 @@ export function registerSpanHooks(options) {
                 errorType: errored ? errorTypeOf(error) : undefined,
                 durationSec: elapsedSeconds(held.startMs),
             });
-            void (async () => {
-                try {
-                    if (held.pending)
-                        await held.pending;
-                    if (errored) {
-                        recordSpanError(span, error);
-                    }
-                    else {
-                        await setGenAiContentAttribute(span, GEN_AI.TOOL_CALL_RESULT, result);
-                    }
-                }
-                finally {
-                    try {
-                        span.end();
-                    }
-                    catch {
-                        /* best effort */
-                    }
-                }
-            })();
+            finalizeToolSpan(held, errored, error, result);
         }
         catch (err) {
             logger.warn("after_tool_call handler failed", { err: errMsg(err) });
         }
     });
-    // ─── Subagent (`invoke_agent` span, four-hook lifecycle) ───────────────────
-    api.on("subagent_spawning", (event, subagentCtx) => {
-        try {
-            const identity = readIdentity(subagentCtx);
-            const ev = asRecord(event);
-            const ctxObj = asRecord(subagentCtx);
-            const hostSessionKey = nonEmptyString(ctxObj?.requesterSessionKey) ??
-                nonEmptyString(ctxObj?.sessionKey) ??
-                "";
-            const hostRunId = nonEmptyString(ctxObj?.runId) ?? nonEmptyString(ctxObj?.requesterRunId) ?? "";
-            const childSessionKey = nonEmptyString(ev?.childSessionKey) ?? nonEmptyString(ctxObj?.childSessionKey);
-            if (!childSessionKey) {
-                logger.warn("subagent_spawning missing childSessionKey; skipping span");
-                return;
+    // ─── Subagent (`invoke_agent` span) ────────────────────────────────────────
+    // 5.x: subagent_spawning opens, subagent_spawned enriches. 10.x has no subagent_spawning, so
+    // subagent_spawned opens the span when none is held for the child.
+    /** Opens and holds the `invoke_agent` span for `childSessionKey`, hosted by the given run. */
+    const openSubagentSpan = (params) => {
+        const { childSessionKey, hostSessionKey, hostRunId, ev } = params;
+        const prior = subagentSpans.get(childSessionKey);
+        if (prior)
+            endSpan(prior.span);
+        const agentName = nonEmptyString(ev?.label) ?? nonEmptyString(ev?.agentId) ?? "unknown";
+        const span = tracer.startSpan(`invoke_agent ${agentName}`, { kind: SpanKind.INTERNAL }, hostSessionKey && hostRunId
+            ? parentContextForModel(hostSessionKey, hostRunId)
+            : otelContext.active());
+        // sessionKey/runId carry the HOST run so the agent_end sweep can reach this span.
+        const held = {
+            span,
+            sessionKey: hostSessionKey,
+            runId: hostRunId,
+            startMs: Date.now(),
+            agentName,
+        };
+        subagentSpans.set(childSessionKey, held);
+        setDefinedAttributes(span, {
+            [GEN_AI.OPERATION_NAME]: "invoke_agent",
+            [GEN_AI.CONVERSATION_ID]: nonEmptyString(hostSessionKey),
+            [GEN_AI.AGENT_NAME]: agentName,
+            "senpi.subagent.mode": nonEmptyString(ev?.mode),
+            "senpi.subagent.requester": nonEmptyString(ev?.requester),
+            "senpi.subagent.thread_requested": typeof ev?.threadRequested === "boolean" ? ev.threadRequested : undefined,
+            ...identityAttributes(params.identity),
+        });
+        return held;
+    };
+    if (!modernHost) {
+        on("subagent_spawning", (event, subagentCtx) => {
+            try {
+                const ev = asRecord(event);
+                const ctxObj = asRecord(subagentCtx);
+                const hostSessionKey = nonEmptyString(ctxObj?.requesterSessionKey) ??
+                    nonEmptyString(ctxObj?.sessionKey) ??
+                    "";
+                const hostRunId = nonEmptyString(ctxObj?.runId) ?? nonEmptyString(ctxObj?.requesterRunId) ?? "";
+                const childSessionKey = nonEmptyString(ev?.childSessionKey) ?? nonEmptyString(ctxObj?.childSessionKey);
+                if (!childSessionKey) {
+                    logger.warn("subagent_spawning missing childSessionKey; skipping span");
+                    return;
+                }
+                openSubagentSpan({ childSessionKey, hostSessionKey, hostRunId, ev, identity: readIdentity(subagentCtx) });
             }
-            const prior = subagentSpans.get(childSessionKey);
-            if (prior)
-                endSpan(prior.span);
-            const agentName = nonEmptyString(ev?.label) ?? nonEmptyString(ev?.agentId) ?? "unknown";
-            const span = tracer.startSpan(`invoke_agent ${agentName}`, { kind: SpanKind.INTERNAL }, hostSessionKey && hostRunId
-                ? parentContextForModel(hostSessionKey, hostRunId)
-                : otelContext.active());
-            // sessionKey/runId carry the HOST run so the agent_end sweep can reach this span.
-            subagentSpans.set(childSessionKey, {
-                span,
-                sessionKey: hostSessionKey,
-                runId: hostRunId,
-                startMs: Date.now(),
-                agentName,
-            });
-            setDefinedAttributes(span, {
-                [GEN_AI.OPERATION_NAME]: "invoke_agent",
-                [GEN_AI.CONVERSATION_ID]: nonEmptyString(hostSessionKey),
-                [GEN_AI.AGENT_NAME]: agentName,
-                "senpi.subagent.mode": nonEmptyString(ev?.mode),
-                "senpi.subagent.requester": nonEmptyString(ev?.requester),
-                "senpi.subagent.thread_requested": typeof ev?.threadRequested === "boolean" ? ev.threadRequested : undefined,
-                ...identityAttributes(identity),
-            });
-        }
-        catch (err) {
-            logger.warn("subagent_spawning handler failed", { err: errMsg(err) });
-        }
-    });
-    api.on("subagent_spawned", (event, subagentCtx) => {
+            catch (err) {
+                logger.warn("subagent_spawning handler failed", { err: errMsg(err) });
+            }
+        });
+    }
+    on("subagent_spawned", (event, subagentCtx) => {
         try {
             const ev = asRecord(event);
             const ctxObj = asRecord(subagentCtx);
             const childSessionKey = nonEmptyString(ev?.childSessionKey) ?? nonEmptyString(ctxObj?.childSessionKey);
             if (!childSessionKey)
                 return;
-            const held = subagentSpans.get(childSessionKey);
+            let held = subagentSpans.get(childSessionKey);
+            if (!held && modernHost) {
+                // 10.x ctx: `runId` is the CHILD run; the host is the requester session, whose run is
+                // `requesterRunId` when given, else that session's latest run seen at llm_input.
+                const hostSessionKey = nonEmptyString(ctxObj?.requesterSessionKey) ?? nonEmptyString(ctxObj?.sessionKey) ?? "";
+                const hostRunId = nonEmptyString(ctxObj?.requesterRunId) ??
+                    (hostSessionKey ? latestRunBySession.get(hostSessionKey) : undefined) ??
+                    "";
+                held = openSubagentSpan({ childSessionKey, hostSessionKey, hostRunId, ev, identity: readIdentity(subagentCtx) });
+            }
             if (!held)
                 return;
             const span = held.span;
@@ -444,7 +650,7 @@ export function registerSpanHooks(options) {
             logger.warn("subagent_spawned handler failed", { err: errMsg(err) });
         }
     });
-    api.on("subagent_delivery_target", (event, subagentCtx) => {
+    on("subagent_delivery_target", (event, subagentCtx) => {
         try {
             const ev = asRecord(event);
             const ctxObj = asRecord(subagentCtx);
@@ -468,7 +674,7 @@ export function registerSpanHooks(options) {
             logger.warn("subagent_delivery_target handler failed", { err: errMsg(err) });
         }
     });
-    api.on("subagent_ended", (event, subagentCtx) => {
+    on("subagent_ended", (event, subagentCtx) => {
         try {
             const ev = asRecord(event);
             const ctxObj = asRecord(subagentCtx);
@@ -509,7 +715,7 @@ export function registerSpanHooks(options) {
         }
     });
     // ─── Agent end (orphan sweep) ──────────────────────────────────────────────
-    api.on("agent_end", (event, agentCtx) => {
+    on("agent_end", (event, agentCtx) => {
         try {
             const sessionKey = readSessionKey(agentCtx, event);
             const runId = readRunId(agentCtx, event);
@@ -542,6 +748,7 @@ export function registerSpanHooks(options) {
                     model.endTimer = setTimeout(() => {
                         if (modelSpans.get(llmKey) === model)
                             modelSpans.delete(llmKey);
+                        stampLlmCalls(model);
                         endSpan(model.span);
                     }, MODEL_SPAN_END_GRACE_MS);
                     model.endTimer.unref?.();
@@ -568,11 +775,14 @@ export function registerSpanHooks(options) {
             if (lastActive && lastActive.sessionKey === sessionKey && lastActive.runId === runId) {
                 lastActive = null;
             }
+            if (latestRunBySession.get(sessionKey) === runId)
+                latestRunBySession.delete(sessionKey);
         }
         catch (err) {
             logger.warn("agent_end handler failed", { err: errMsg(err) });
         }
     });
+    return hookCount;
 }
 // ─── Span key helpers ───────────────────────────────────────────────────────
 const SEP = " ";