How to Use inheritParentSystemPrompt in Codebuff: System Prompt Inheritance and Caching

Enable inheritParentSystemPrompt on child agents to reuse the parent's system prompt for prompt caching, reducing token usage while maintaining consistent behavior across agent hierarchies.

The inheritParentSystemPrompt feature in the CodebuffAI/codebuff repository enables sophisticated prompt caching across hierarchical agent structures. This mechanism allows sub-agents to inherit the exact system prompt from their parent, eliminating redundant token consumption and ensuring uniform high-level behavior. Understanding when and how to implement this inheritance pattern is essential for building cost-effective, multi-agent systems.

What is inheritParentSystemPrompt?

inheritParentSystemPrompt is a boolean configuration option in the AgentDefinition type that instructs a sub-agent to reuse the exact system prompt of its parent agent. Instead of generating or defining a unique system message, the child agent receives the cached parent prompt, enabling prompt caching at the runtime level. This is implemented in .agents/types/agent-definition.ts (lines 84-90), where the property is defined alongside validation rules that prevent conflicts with custom system prompts.

When to Enable System Prompt Inheritance

Enable inheritParentSystemPrompt when you need to optimize token usage and maintain behavioral consistency across agent hierarchies. The following situations warrant its use:

• You maintain large, stable system prompts. When the parent agent defines a lengthy system message (e.g., "You are a senior full-stack developer..."), reusing it avoids re-sending identical text for every sub-agent invocation.

• You require prompt caching for performance. The runtime sends the parent's system prompt only once in packages/agent-runtime/src/run-agent-step.ts, then passes the cached version to all children that inherit it, significantly reducing API costs.

• The child agent's behavior is tool-driven. When the sub-agent's functionality is defined primarily by its available tools and instructionsPrompt rather than a unique personality or constraints, inheritance keeps the configuration lightweight.

• You need strict behavioral constraints. Inheritance prevents accidental divergence; the schema validation in common/src/types/dynamic-agent-template.ts (lines 85-98) rejects any non-empty systemPrompt when inheritParentSystemPrompt is enabled.

When to Avoid Inheritance

Do not use inheritParentSystemPrompt when the child agent requires a different high-level personality or constraints than the parent. If the sub-agent needs to override part of the parent's system prompt or operate under distinct behavioral guidelines, define a separate systemPrompt instead. Inheritance is inappropriate when you want the child to deviate from the parent's core instructions in any way.

How It Works Under the Hood

The implementation spans schema validation, runtime execution, and documentation generation.

Schema Validation

The Zod schema in common/src/types/dynamic-agent-template.ts enforces mutual exclusivity between inheritance and custom prompts. When inheritParentSystemPrompt is true, the validator ensures systemPrompt is either missing or empty, throwing an error if both fields are present.

Runtime Execution

In packages/agent-runtime/src/run-agent-step.ts, the runner decides whether to reuse the parent's system prompt and tools. Lines 54-57 determine tool inheritance, while lines 78-81 handle the system prompt:

// Decide whether to use the parent's tools for prompt caching
const useParentTools =
  agentTemplate.inheritParentSystemPrompt && parentTools !== undefined

// Build system prompt – reuse parent if inheritance is enabled
let system: string
if (agentTemplate.inheritParentSystemPrompt && parentSystemPrompt) {
  system = parentSystemPrompt
} else {
  const systemPrompt = await getAgentPrompt({ … })
  system = systemPrompt ?? ''
}

Documentation Generation

When rendering agent descriptions for sub-agents, the template in packages/agent-runtime/src/templates/prompts.ts (lines 31-35) automatically appends an indication that the agent is inheriting its system prompt from the parent, ensuring transparency in the agent hierarchy.

Step-by-Step Implementation

Follow these steps to implement system prompt inheritance in your Codebuff agents.

Define the Parent Agent

Create the parent agent with a complete systemPrompt that establishes the foundational behavior:

import { AgentDefinition } from '.agents/types/agent-definition'

export const parent: AgentDefinition = {
  id: 'parent-agent',
  version: '0.1.0',
  displayName: 'Parent Agent',
  model: 'anthropic/claude-sonnet-4.6',
  systemPrompt: `
You are an expert software architect.
- Always write production-grade TypeScript.
- Follow the project's linting rules.
- Keep explanations concise.
`,
  instructionsPrompt: 'Help the user solve coding problems.',
  toolNames: ['read_files', 'write_file', 'spawn_agents'],
  spawnableAgents: ['child-agent'],
}
export default parent

Configure the Child Agent

Define the child agent with inheritParentSystemPrompt: true and omit the systemPrompt field. Use instructionsPrompt for child-specific modifications:

import { AgentDefinition } from '.agents/types/agent-definition'

export const child: AgentDefinition = {
  id: 'child-agent',
  version: '0.1.0',
  displayName: 'Child Agent',
  model: 'anthropic/claude-sonnet-4.6',
  // Inherit the parent's system prompt – do NOT set systemPrompt
  inheritParentSystemPrompt: true,
  // Child-specific instructions – these are appended after the inherited system prompt
  instructionsPrompt: `
You are a code-review sub-assistant.
- Focus on TypeScript type safety.
- Suggest improvements only when they reduce complexity.
`,
  toolNames: ['read_files', 'write_file'],
}
export default child

Spawn the Child Agent

Use the spawn_agents tool within a handleSteps generator to instantiate the child. The runtime automatically applies the cached parent system prompt:

function* handleSteps({ logger }) {
  logger.info('Spawning child agent')
  yield {
    toolName: 'spawn_agents',
    input: {
      agents: [
        {
          agent_type: 'child-agent',
          // No custom systemPrompt – inheritance is automatic
          input: { /* any child inputs */ },
        },
      ],
    },
  }

  // Continue with parent logic…
}

If you need the child to access conversation history, explicitly set includeMessageHistory: true in the agent definition. Inheritance does not automatically include message history.

Validation Errors and Troubleshooting

Attempting to set both inheritParentSystemPrompt: true and a custom systemPrompt triggers a validation error. The test suite in packages/agent-runtime/src/__tests__/prompt-caching-subagents.test.ts (lines 329-361) demonstrates this behavior:

// This will throw during validation:
const badAgent: AgentDefinition = {
  id: 'bad',
  inheritParentSystemPrompt: true,
  systemPrompt: 'I want a different system prompt', // ❌ invalid
}

Running this code produces the error: "Cannot specify both systemPrompt and inheritParentSystemPrompt. When inheritParentSystemPrompt is true, systemPrompt must be empty."

Summary

• Enable inheritParentSystemPrompt on child agents to reuse the parent's system prompt and achieve prompt caching.
• Never set systemPrompt when inheritance is enabled; the schema in dynamic-agent-template.ts enforces this constraint.
• Use instructionsPrompt to provide child-specific behavioral modifications without breaking inheritance.
• Enable includeMessageHistory separately if the child requires access to conversation context.
• Reference the source files: .agents/types/agent-definition.ts for type definitions, run-agent-step.ts for runtime logic, and prompt-caching-subagents.test.ts for validation examples.

Frequently Asked Questions

Can I set a custom systemPrompt when inheritParentSystemPrompt is true?

No. The Zod schema validator in common/src/types/dynamic-agent-template.ts explicitly forbids this combination. When inheritParentSystemPrompt is enabled, the systemPrompt field must be empty or omitted entirely. Attempting to set both will result in a schema validation error before the agent runs.

Does inheritance include message history?

No. The inheritParentSystemPrompt flag controls only the system prompt inheritance. If you need the child agent to view the conversation history from the parent, you must separately enable includeMessageHistory: true in the agent definition. These are distinct configuration options with separate behaviors.

How does this improve performance?

By reusing the parent's system prompt, Codebuff avoids re-sending identical system text for every sub-agent invocation. This prompt caching reduces token consumption significantly when spawning multiple children, as the runtime sends the system prompt only once and references the cached version for subsequent inherited agents.

What happens if the parent changes its system prompt?

Child agents inherit the parent's system prompt at runtime when spawned. If the parent's systemPrompt is modified, subsequent spawns of the child agent will receive the updated system prompt automatically. However, already-running child agents retain the system prompt they received at initialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}