Add usage to onDelegationComplete hook (#15825)

Co-authored-by: Taofeeq Oluderu <oluderutaofeeq@gmail.com>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>

Author: 3 people

.changeset/crisp-moons-jump.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Added sub-agent token usage to `onDelegationComplete` results, so apps can track per-sub-agent token costs

packages/core/src/agent/agent.ts

@@ -4282,7 +4282,13 @@ export class Agent<
                   });
                 }
 
-                result = { text: generateResult.text, subAgentThreadId, subAgentResourceId, subAgentToolResults };
+                result = {
+                  text: generateResult.text,
+                  subAgentThreadId,
+                  subAgentResourceId,
+                  subAgentToolResults,
+                  usage: generateResult.usage,
+                };
               } else if (
                 (methodType === 'generate' || methodType === 'generateLegacy') &&
                 resolvedModelVersion === 'v1'
@@ -4295,7 +4301,21 @@ export class Agent<
                   ...resolveObservabilityContext(context ?? {}),
                   context: filteredContextMessages as unknown as CoreMessage[],
                 });
-                result = { text: generateResult.text };
+                const subAgentToolResultsLegacy = generateResult.toolResults?.map((toolResult: any) => ({
+                  toolName: toolResult.toolName,
+                  toolCallId: toolResult.toolCallId,
+                  result: toolResult.result,
+                  args: toolResult.args,
+                  isError: toolResult.isError,
+                }));
+
+                result = {
+                  text: generateResult.text,
+                  subAgentThreadId,
+                  subAgentResourceId,
+                  subAgentToolResults: subAgentToolResultsLegacy,
+                  usage: generateResult.usage,
+                };
               } else if (
                 (methodType === 'stream' || methodType === 'streamLegacy') &&
                 supportedLanguageModelSpecifications.includes(resolvedModelVersion)
@@ -4441,11 +4461,13 @@ export class Agent<
                 // Use streamResult.text (a delayed promise) which resolves to the
                 // output-processor-modified text, rather than the raw accumulated text-deltas.
                 const processedText = await streamResult.text;
+                const subAgentUsage = await streamResult.usage;
                 result = {
                   text: processedText,
                   subAgentThreadId,
                   subAgentResourceId,
                   subAgentToolResults,
+                  usage: subAgentUsage,
                 };
               } else {
                 if (typeof resolvedAgent.streamLegacy !== 'function') {
@@ -4476,6 +4498,10 @@ export class Agent<
                 result = { text: fullText };
               }
 
+              // Note: `usage` is included in `result` for successful generate, generateLegacy,
+              // and stream code paths. The `streamLegacy` path accumulates text only and won't
+              // have `usage`. Error/rejected delegation callbacks may also omit it.
+
               // Call onDelegationComplete hook if provided
               if (delegation?.onDelegationComplete) {
                 try {

packages/core/src/agent/agent.types.ts

@@ -143,6 +143,14 @@ export interface DelegationCompleteContext {
     text: string;
     subAgentThreadId?: string;
     subAgentResourceId?: string;
+    /** Aggregate token usage from the sub-agent's execution */
+    usage?: {
+      inputTokens: number;
+      outputTokens: number;
+      totalTokens: number;
+      reasoningTokens?: number;
+      cachedInputTokens?: number;
+    };
   };
   /** Duration of the delegation in milliseconds */
   duration: number;

packages/core/src/agent/subagent.ts

@@ -28,6 +28,7 @@ export type SubAgentGenerateResult = Pick<FullOutput, 'text' | 'finishReason' |
   toolResults?: SubAgentToolResult[];
   suspendPayload?: unknown;
   resumeSchema?: unknown;
+  usage?: FullOutput['usage'];
 };
 
 export type SubAgentStreamResult = {