feat(core): transition sub-agents to XML format and improve definitions

[NTaylorMullen]

Summary

This PR transitions the sub-agent listing in the system prompt to a structured XML format for Gemini 3 models and centralizes sub-agent rendering within the core snippet files. It also removes obsolete methods from the AgentRegistry to simplify sub-agent management and ensures consistent instructions across the system prompt and template substitutions.

Details

• XML Transition: Sub-agents are now listed using <available_subagents> and <subagent> tags for Gemini 3 models to improve model parsing and tool selection reliability.
• Centralization: Sub-agent rendering logic has been moved from AgentRegistry to snippets.ts and snippets.legacy.ts, allowing for better model-specific tailoring.
• Simplification: Removed getDirectoryContext from AgentRegistry as its logic is now handled by the prompt providers.
• Snapshot Updates: Updated snapshots for prompts.test.ts to reflect the new XML structure and formatting changes (indentation and spacing).
• Consistency: Unified sub-agent instructions across the core system prompt and template substitutions.

Related Issues

Fixes #18550

How to Validate

Run the core prompt tests and verify snapshots:

npm test -w @google/gemini-cli-core -- src/core/prompts.test.ts

Run a full preflight check to ensure no regressions:

npm run preflight

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello @NTaylorMullen, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refactors how sub-agent information is presented within the system prompts, particularly for Gemini 3 models. By moving to a structured XML format and centralizing the rendering logic, the system achieves greater consistency with existing prompt patterns and improves the overall maintainability of prompt generation. This change also cleans up deprecated code related to sub-agent context retrieval.

Highlights

• Sub-agent Listing Format Transition: The sub-agent listing in the Gemini 3 system prompt has been transitioned from a Markdown format to a structured XML format (<available_subagents>) for improved consistency with other prompt structures like skills.
• Centralized Sub-agent Rendering Logic: Sub-agent rendering logic and prose have been centralized within the prompts/ directory. Dedicated snippets (snippets.ts for XML and snippets.legacy.ts for Markdown) now handle the formatting for different model types.
• Unified Substitution Logic: The ${SubAgents} substitution logic in utils.ts has been updated to utilize these new centralized renderers, ensuring a consistent approach to injecting sub-agent information into prompts.
• Removal of Obsolete Code: The getDirectoryContext method and its associated tests have been removed from AgentRegistry, streamlining the codebase and eliminating deprecated functionality.
• Improved Data Handling in PromptProvider: The PromptProvider now passes structured sub-agent data (obtained via getAllDefinitions) to the snippet renderers, enhancing the flexibility and maintainability of prompt generation.

Changelog

• packages/core/src/agents/generalist-agent.test.ts
  • Added getAllDefinitions: () => [] to the mocked AgentRegistry to align with new API usage.
• packages/core/src/agents/registry.test.ts
  • Removed tests for the getDirectoryContext method, as this method is being removed.
• packages/core/src/agents/registry.ts
  • Removed the getDirectoryContext method, which was responsible for generating a markdown 'phone book' of agents.
• packages/core/src/core/snapshots/prompts.test.ts.snap
  • Updated multiple snapshots to reflect the new XML-based sub-agent listing for preview models and the Markdown-based listing for legacy models, replacing the generic 'Mock Agent Directory' text.
• packages/core/src/core/prompts-substitution.test.ts
  • Imported AgentDefinition type.
  • Updated mock AgentRegistry to include getAllDefinitions.
  • Modified the test for ${SubAgents} substitution to expect the new structured output (Markdown list) instead of a simple string from getDirectoryContext.
• packages/core/src/core/prompts.test.ts
  • Imported AgentDefinition type.
  • Updated mock AgentRegistry to include getAllDefinitions with sample data.
  • Added a new test case should include sub-agents in XML for preview models to verify the XML output for sub-agents.
  • Adjusted existing tests to ensure the correct sub-agent rendering is applied based on the active model.
• packages/core/src/prompts/promptProvider.ts
  • Modified applySubstitutions call to pass the isGemini3 flag.
  • Changed the agentContexts property in SystemPromptOptions to subAgents, which now maps getAllDefinitions to a structured array of { name, description } objects instead of directly using getDirectoryContext.
• packages/core/src/prompts/snippets.legacy.ts
  • Updated SystemPromptOptions interface to use subAgents (an array of SubAgentOptions) instead of agentContexts (a string).
  • Introduced SubAgentOptions interface for structured sub-agent data.
  • Renamed renderAgentContexts to renderSubAgents and updated its implementation to format sub-agents as a Markdown list.
• packages/core/src/prompts/snippets.ts
  • Updated SystemPromptOptions interface to use subAgents (an array of SubAgentOptions) instead of agentContexts (a string).
  • Introduced SubAgentOptions interface for structured sub-agent data.
  • Renamed renderAgentContexts to renderSubAgents and updated its implementation to format sub-agents into an XML structure.
• packages/core/src/prompts/utils.ts
  • Imported snippets and legacySnippets modules.
  • Modified applySubstitutions function to accept an isGemini3 boolean parameter.
  • Implemented conditional logic within applySubstitutions to use either the XML-generating snippets.renderSubAgents or the Markdown-generating legacySnippets.renderSubAgents based on the isGemini3 flag.
  • Updated the sub-agent data source to config.getAgentRegistry().getAllDefinitions() for both rendering paths.

Activity

• The author, NTaylorMullen, created this pull request to transition sub-agents to an XML format and improve definitions.
• The pull request includes updates to unit tests and snapshots to reflect the new prompt structures.
• The author has validated the changes on MacOS using npm run.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request is a well-executed refactoring that transitions the sub-agent listing in system prompts to a structured XML format for Gemini 3 models, while maintaining a markdown format for legacy models. The changes successfully centralize the rendering logic for sub-agents into the prompts/ directory, removing it from AgentRegistry and simplifying the ${SubAgents} substitution process. This improves code clarity and maintainability. The test suite has been updated comprehensively to reflect these changes, including new tests for the XML format and adjustments to existing mocks and snapshots. The overall implementation is clean and aligns with the stated goals. I have not found any issues of high or critical severity.

[github-actions]

Size Change: +1.08 kB (0%)

Total Size: 23.9 MB

Filename	Size	Change
./bundle/gemini.js	23.8 MB	+1.08 kB (0%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[abhipatel12]

LGTM