Use parent's tools in subagents. Leave note on what tools are actually available. Fixes prompt caching!

Author: jahooma

packages/agent-runtime/src/__tests__/cost-aggregation.test.ts

@@ -90,6 +90,7 @@ describe('Cost Aggregation System', () => {
       repoUrl: undefined,
       signal: new AbortController().signal,
       system: 'Test system prompt',
+      tools: {},
       userId: 'test-user',
       userInputId: 'test-input',
       writeToClient: () => {},

packages/agent-runtime/src/__tests__/prompt-caching-subagents.test.ts

@@ -407,6 +407,83 @@ describe('Prompt Caching for Subagents with inheritParentSystemPrompt', () => {
     // allowing the LLM provider to cache and reuse the system prompt
   })
 
+  it('should pass parent tools and add subagent tools message when inheritParentSystemPrompt is true', async () => {
+    const sessionState = getInitialSessionState(mockFileContext)
+
+    // Create a child that inherits system prompt and has specific tools
+    const childWithTools: AgentTemplate = {
+      id: 'child-with-tools',
+      displayName: 'Child With Tools',
+      outputMode: 'last_message',
+      inputSchema: {},
+      spawnerPrompt: '',
+      model: 'anthropic/claude-sonnet-4',
+      includeMessageHistory: false,
+      inheritParentSystemPrompt: true,
+      mcpServers: {},
+      toolNames: ['read_files', 'code_search'],
+      spawnableAgents: [],
+      systemPrompt: '',
+      instructionsPrompt: '',
+      stepPrompt: '',
+    }
+
+    mockLocalAgentTemplates['child-with-tools'] = childWithTools
+
+    // Run parent agent first
+    await loopAgentSteps({
+      ...loopAgentStepsBaseParams,
+      userInputId: 'test-parent',
+      prompt: 'Parent task',
+      agentType: 'parent',
+      agentState: sessionState.mainAgentState,
+    })
+
+    const parentMessages = capturedMessages
+    const parentSystemPrompt = (parentMessages[0].content[0] as TextPart).text
+
+    // Mock parent tools
+    const parentTools = { read_files: {}, write_file: {}, code_search: {} }
+
+    // Run child agent with inheritParentSystemPrompt=true and parentTools
+    capturedMessages = []
+    const childAgentState = {
+      ...sessionState.mainAgentState,
+      agentId: 'child-agent',
+      agentType: 'child-with-tools' as const,
+      messageHistory: [],
+    }
+
+    await loopAgentSteps({
+      ...loopAgentStepsBaseParams,
+      userInputId: 'test-child',
+      prompt: 'Child task',
+      agentType: 'child-with-tools',
+      agentState: childAgentState,
+      parentSystemPrompt: parentSystemPrompt,
+      parentTools: parentTools as any,
+    })
+
+    const childMessages = capturedMessages
+
+    // Verify child uses parent's system prompt
+    expect(childMessages[0].role).toBe('system')
+    expect((childMessages[0].content[0] as TextPart).text).toBe(
+      parentSystemPrompt,
+    )
+
+    // Verify there's a message about subagent tools
+    const subagentToolsMessage = childMessages.find(
+      (msg) =>
+        msg.role === 'user' &&
+        msg.content[0].type === 'text' &&
+        msg.content[0].text.includes('subagent') &&
+        msg.content[0].text.includes('read_files') &&
+        msg.content[0].text.includes('code_search'),
+    )
+    expect(subagentToolsMessage).toBeTruthy()
+  })
+
   it('should support both inheritParentSystemPrompt and includeMessageHistory together', async () => {
     const sessionState = getInitialSessionState(mockFileContext)
 

packages/agent-runtime/src/__tests__/spawn-agents-message-history.test.ts

@@ -68,6 +68,7 @@ describe('Spawn Agents Message History', () => {
       sendSubagentChunk: mockSendSubagentChunk,
       signal: new AbortController().signal,
       system: 'Test system prompt',
+      tools: {},
       userId: TEST_USER_ID,
       userInputId: 'test-input',
       writeToClient: () => {},

packages/agent-runtime/src/__tests__/spawn-agents-permissions.test.ts

@@ -67,6 +67,7 @@ describe('Spawn Agents Permissions', () => {
       sendSubagentChunk: mockSendSubagentChunk,
       signal: new AbortController().signal,
       system: 'Test system prompt',
+      tools: {},
       userId: TEST_USER_ID,
       userInputId: 'test-input',
       writeToClient: () => {},

packages/agent-runtime/src/__tests__/subagent-streaming.test.ts

@@ -70,6 +70,7 @@ describe('Subagent Streaming', () => {
       sendSubagentChunk: mockSendSubagentChunk,
       signal: new AbortController().signal,
       system: 'Test system prompt',
+      tools: {},
       userId: TEST_USER_ID,
       userInputId: 'test-input',
       writeToClient: mockWriteToClient,

packages/agent-runtime/src/run-agent-step.ts

@@ -58,6 +58,7 @@ import type {
   CustomToolDefinitions,
   ProjectFileContext,
 } from '@codebuff/common/util/file'
+import type { ToolSet } from 'ai'
 
 async function additionalToolDefinitions(
   params: {
@@ -481,6 +482,7 @@ export async function loopAgentSteps(
     localAgentTemplates: Record<string, AgentTemplate>
     logger: Logger
     parentSystemPrompt?: string
+    parentTools?: ToolSet
     prompt: string | undefined
     signal: AbortSignal
     spawnParams: Record<string, any> | undefined
@@ -554,6 +556,7 @@ export async function loopAgentSteps(
     localAgentTemplates,
     logger,
     parentSystemPrompt,
+    parentTools,
     prompt,
     signal,
     spawnParams,
@@ -631,18 +634,29 @@ export async function loopAgentSteps(
           },
         })) ?? ''
 
-  const tools = await getToolSet({
-    toolNames: agentTemplate.toolNames,
-    additionalToolDefinitions: async () => {
-      if (!cachedAdditionalToolDefinitions) {
-        cachedAdditionalToolDefinitions = await additionalToolDefinitions({
-          ...params,
-          agentTemplate,
-        })
-      }
-      return cachedAdditionalToolDefinitions
-    },
-  })
+  // Use parent's tools for prompt caching when inheritParentSystemPrompt is true
+  const useParentTools =
+    agentTemplate.inheritParentSystemPrompt && parentTools !== undefined
+
+  const tools = useParentTools
+    ? parentTools
+    : await getToolSet({
+        toolNames: agentTemplate.toolNames,
+        additionalToolDefinitions: async () => {
+          if (!cachedAdditionalToolDefinitions) {
+            cachedAdditionalToolDefinitions = await additionalToolDefinitions({
+              ...params,
+              agentTemplate,
+            })
+          }
+          return cachedAdditionalToolDefinitions
+        },
+      })
+
+  // Build a message explaining the subagent's tool access when using parent's tools
+  const subagentToolsMessage = useParentTools
+    ? `You are a subagent that only has access to the following tools: ${agentTemplate.toolNames.join(', ')}. Do not attempt to use any other tools.`
+    : undefined
 
   const hasUserMessage = Boolean(
     prompt || (spawnParams && Object.keys(spawnParams).length > 0),
@@ -651,6 +665,14 @@ export async function loopAgentSteps(
   const initialMessages = buildArray<Message>(
     ...agentState.messageHistory,
 
+    // Add subagent tools message before user prompt when using parent's tools for caching
+    subagentToolsMessage &&
+      userMessage({
+        content: withSystemTags(subagentToolsMessage),
+        tags: ['SUBAGENT_TOOLS'],
+        keepDuringTruncation: true,
+      }),
+
     hasUserMessage && [
       {
         // Actual user message!
@@ -877,7 +899,10 @@ export async function loopAgentSteps(
     )
 
     // Re-throw NetworkError and PaymentRequiredError to allow SDK retry wrapper to handle it
-    if (error instanceof Error && (error.name === 'NetworkError' || error.name === 'PaymentRequiredError')) {
+    if (
+      error instanceof Error &&
+      (error.name === 'NetworkError' || error.name === 'PaymentRequiredError')
+    ) {
       throw error
     }
 

packages/agent-runtime/src/tools/handlers/handler-function-type.ts

@@ -18,6 +18,7 @@ import type { Logger } from '@codebuff/common/types/contracts/logger'
 import type { PrintModeEvent } from '@codebuff/common/types/print-mode'
 import type { AgentState, Subgoal } from '@codebuff/common/types/session-state'
 import type { ProjectFileContext } from '@codebuff/common/util/file'
+import type { ToolSet } from 'ai'
 
 type PresentOrAbsent<K extends PropertyKey, V> =
   | { [P in K]: V }
@@ -49,6 +50,7 @@ export type CodebuffToolHandlerFunction<T extends ToolName = ToolName> = (
     sendSubagentChunk: SendSubagentChunkFn
     signal: AbortSignal
     system: string
+    tools?: ToolSet
     trackEvent: TrackEventFn
     userId: string | undefined
     userInputId: string

packages/agent-runtime/src/tools/handlers/tool/spawn-agent-inline.ts

@@ -17,6 +17,7 @@ import type { ParamsExcluding } from '@codebuff/common/types/function-params'
 import type { PrintModeEvent } from '@codebuff/common/types/print-mode'
 import type { AgentState } from '@codebuff/common/types/session-state'
 import type { ProjectFileContext } from '@codebuff/common/util/file'
+import type { ToolSet } from 'ai'
 
 type ToolName = 'spawn_agent_inline'
 export const handleSpawnAgentInline = (async (
@@ -32,6 +33,7 @@ export const handleSpawnAgentInline = (async (
     localAgentTemplates: Record<string, AgentTemplate>
     logger: Logger
     system: string
+    tools?: ToolSet
     userId: string | undefined
     userInputId: string
     writeToClient: (chunk: string | PrintModeEvent) => void
@@ -44,6 +46,7 @@ export const handleSpawnAgentInline = (async (
     | 'parentAgentState'
     | 'agentState'
     | 'parentSystemPrompt'
+    | 'parentTools'
     | 'onResponseChunk'
     | 'clearUserPromptMessagesAfterResponse'
     | 'fingerprintId'
@@ -57,6 +60,7 @@ export const handleSpawnAgentInline = (async (
     agentTemplate: parentAgentTemplate,
     fingerprintId,
     system,
+    tools: parentTools = {},
     userInputId,
     writeToClient,
   } = params
@@ -105,6 +109,9 @@ export const handleSpawnAgentInline = (async (
     agentState: childAgentState,
     fingerprintId,
     parentSystemPrompt: system,
+    parentTools: agentTemplate.inheritParentSystemPrompt
+      ? parentTools
+      : undefined,
     onResponseChunk: (chunk) => {
       // Inherits parent's onResponseChunk, except for context-pruner (TODO: add an option for it to be silent?)
       if (agentType !== 'context-pruner') {

packages/agent-runtime/src/tools/handlers/tool/spawn-agent-utils.ts

@@ -12,6 +12,7 @@ import type {
   ParamsExcluding,
   OptionalFields,
 } from '@codebuff/common/types/function-params'
+import type { ToolSet } from 'ai'
 import type { PrintModeEvent } from '@codebuff/common/types/print-mode'
 import type {
   AgentState,
@@ -231,6 +232,7 @@ export async function executeSubagent(
     {
       agentTemplate: AgentTemplate
       parentAgentState: AgentState
+      parentTools?: ToolSet
       onResponseChunk: (chunk: string | PrintModeEvent) => void
       isOnlyChild?: boolean
       ancestorRunIds: string[]

packages/agent-runtime/src/tools/handlers/tool/spawn-agents.ts

@@ -18,6 +18,7 @@ import type { Logger } from '@codebuff/common/types/contracts/logger'
 import type { ParamsExcluding } from '@codebuff/common/types/function-params'
 import type { PrintModeEvent } from '@codebuff/common/types/print-mode'
 import type { AgentState } from '@codebuff/common/types/session-state'
+import type { ToolSet } from 'ai'
 
 export type SendSubagentChunk = (data: {
   userInputId: string
@@ -40,6 +41,7 @@ export const handleSpawnAgents = (async (
     localAgentTemplates: Record<string, AgentTemplate>
     logger: Logger
     system: string
+    tools?: ToolSet
     userId: string | undefined
     userInputId: string
     sendSubagentChunk: SendSubagentChunk
@@ -59,6 +61,7 @@ export const handleSpawnAgents = (async (
       | 'fingerprintId'
       | 'isOnlyChild'
       | 'parentSystemPrompt'
+      | 'parentTools'
       | 'onResponseChunk'
     >,
 ): Promise<{ output: CodebuffToolOutput<ToolName> }> => {
@@ -70,6 +73,7 @@ export const handleSpawnAgents = (async (
     agentTemplate: parentAgentTemplate,
     fingerprintId,
     system: parentSystemPrompt,
+    tools: parentTools = {},
     userInputId,
     sendSubagentChunk,
     writeToClient,
@@ -118,6 +122,9 @@ export const handleSpawnAgents = (async (
           fingerprintId,
           isOnlyChild: agents.length === 1,
           parentSystemPrompt,
+          parentTools: agentTemplate.inheritParentSystemPrompt
+            ? parentTools
+            : undefined,
           onResponseChunk: (chunk: string | PrintModeEvent) => {
             if (typeof chunk === 'string') {
               sendSubagentChunk({