feat(agents): implement proper agent nesting with parentAgentId propagation

Enables correct UI nesting of spawned agents by propagating parentAgentId through the event system. Backend now adds parentAgentId to nested agent events, and CLI uses this to nest spawned agents under their parents instead of showing them at top level.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

backend/src/run-programmatic-step.ts

@@ -20,7 +20,10 @@ import type {
 } from '@codebuff/common/types/messages/content-part'
 import type { PrintModeEvent } from '@codebuff/common/types/print-mode'
 import type { AgentState } from '@codebuff/common/types/session-state'
-import type { ParamsExcluding, ParamsOf } from '@codebuff/common/types/function-params'
+import type {
+  ParamsExcluding,
+  ParamsOf,
+} from '@codebuff/common/types/function-params'
 import type { Logger } from '@codebuff/common/types/contracts/logger'
 import type { WebSocket } from 'ws'
 
@@ -271,6 +274,7 @@ export async function runProgrammaticStep(
       }
 
       // Execute the tool synchronously and get the result immediately
+      // Wrap onResponseChunk to add parentAgentId to nested agent events
       await executeToolCall({
         ...params,
         toolName: toolCall.toolName,
@@ -284,7 +288,65 @@ export async function runProgrammaticStep(
         fullResponse: '',
         state,
         autoInsertEndStepParam: true,
-        excludeToolFromMessageHistory,
+        excludeToolFromMessageHistory,        onResponseChunk: (chunk: string | PrintModeEvent) => {
+          if (typeof chunk === 'string') {
+            onResponseChunk(chunk)
+            return
+          }
+
+          // Only add parentAgentId if this programmatic agent has a parent (i.e., it's nested)
+          // This ensures we don't add parentAgentId to top-level spawns
+          if (state.agentState.parentId) {
+            // Add parentAgentId to nested agent events for proper nesting in UI
+            if (
+              chunk.type === 'subagent_start' ||
+              chunk.type === 'subagent_finish'
+            ) {
+              // Only add parentAgentId if it's not already set (e.g., by spawn_agents)
+              if (!(chunk as any).parentAgentId) {
+                logger.debug(
+                  {
+                    eventType: chunk.type,
+                    agentId: chunk.agentId,
+                    parentId: state.agentState.agentId,
+                  },
+                  `run-programmatic-step: Adding parentAgentId to ${chunk.type} event`,
+                )
+                onResponseChunk({
+                  ...chunk,
+                  parentAgentId: state.agentState.agentId,
+                })
+                return
+              }
+            }
+
+            // Add parentAgentId to tool calls and results from nested agents
+            if (
+              chunk.type === 'tool_call' ||
+              chunk.type === 'tool_result'
+            ) {
+              // Only add parentAgentId if it's not already set
+              if (!(chunk as any).parentAgentId) {
+                logger.debug(
+                  {
+                    eventType: chunk.type,
+                    agentId: (chunk as any).agentId,
+                    parentId: state.agentState.agentId,
+                  },
+                  `run-programmatic-step: Adding parentAgentId to ${chunk.type} event`,
+                )
+                onResponseChunk({
+                  ...chunk,
+                  parentAgentId: state.agentState.agentId,
+                })
+                return
+              }
+            }
+          }
+
+          // For other events or top-level spawns, send as-is
+          onResponseChunk(chunk)
+        },
       })
 
       // TODO: Remove messages from state and always use agentState.messageHistory.

backend/src/tools/handlers/tool/spawn-agent-utils.ts

@@ -332,14 +332,22 @@ export async function executeSubagent(
   const { onResponseChunk, agentTemplate, parentAgentState, isOnlyChild } =
     withDefaults
 
-  onResponseChunk({
-    type: 'subagent_start',
+  const startEvent = {
+    type: 'subagent_start' as const,
     agentId: withDefaults.agentState.agentId,
     agentType: agentTemplate.id,
     displayName: agentTemplate.displayName,
     onlyChild: isOnlyChild,
     parentAgentId: parentAgentState.agentId,
-  })
+  }
+  withDefaults.logger.debug(
+    {
+      ...startEvent,
+      parentAgentId: parentAgentState.agentId,
+    },
+    'executeSubagent: Sending subagent_start event',
+  )
+  onResponseChunk(startEvent)
 
   // Import loopAgentSteps dynamically to avoid circular dependency
   const { loopAgentSteps } = await import('../../../run-agent-step')

backend/src/tools/handlers/tool/spawn-agents.ts

@@ -158,15 +158,42 @@ export const handleSpawnAgents = ((
                 return
               }
 
-              // Don't overwrite agentId for events that already have the correct agent ID
-              // (subagent_start/finish, tool_call, tool_result from nested agents)
+              // For nested agent events, add parentAgentId to enable proper nesting in UI
               if (
                 chunk.type === 'subagent_start' ||
-                chunk.type === 'subagent_finish' ||
-                chunk.type === 'tool_call' ||
-                chunk.type === 'tool_result'
+                chunk.type === 'subagent_finish'
               ) {
-                writeToClient(chunk)
+                logger.debug(
+                  {
+                    eventType: chunk.type,
+                    agentId: chunk.agentId,
+                    parentId: subAgentState.agentId,
+                    parentAgentId: subAgentState.agentId,
+                  },
+                  `spawn-agents: Adding parentAgentId to ${chunk.type} event`,
+                )
+                writeToClient({
+                  ...chunk,
+                  parentAgentId: subAgentState.agentId,
+                })
+                return
+              }
+
+              // For tool calls and results from nested agents, preserve the agentId but add parentAgentId
+              if (chunk.type === 'tool_call' || chunk.type === 'tool_result') {
+                logger.debug(
+                  {
+                    eventType: chunk.type,
+                    agentId: (chunk as any).agentId,
+                    parentId: subAgentState.agentId,
+                    parentAgentId: subAgentState.agentId,
+                  },
+                  `spawn-agents: Adding parentAgentId to ${chunk.type} event`,
+                )
+                writeToClient({
+                  ...chunk,
+                  parentAgentId: subAgentState.agentId,
+                })
                 return
               }
 

cli/src/chat.tsx

@@ -49,6 +49,7 @@ export type ContentBlock =
       toolName: ToolName
       input: any
       output?: string
+      agentId?: string
     }
   | {
       type: 'agent'

cli/src/components/branch-item.tsx

@@ -21,6 +21,7 @@ interface BranchItemProps {
   name: string
   content: ReactNode
   prompt?: string
+  agentId?: string
   isCollapsed: boolean
   isStreaming: boolean
   branchChar: string
@@ -34,6 +35,7 @@ export const BranchItem = ({
   name,
   content,
   prompt,
+  agentId,
   isCollapsed,
   isStreaming,
   branchChar,

cli/src/components/message-block.tsx

@@ -165,6 +165,7 @@ export const MessageBlock = ({
         <BranchItem
           name={displayInfo.name}
           content={displayContent}
+          agentId={toolBlock.agentId}
           isCollapsed={isCollapsed}
           isStreaming={isStreaming}
           branchChar={branchChar}
@@ -231,6 +232,7 @@ export const MessageBlock = ({
           name={agentBlock.agentName}
           content={displayContent}
           prompt={agentBlock.initialPrompt}
+          agentId={agentBlock.agentId}
           isCollapsed={isCollapsed}
           isStreaming={isStreaming}
           branchChar={branchChar}