feat: implement Open Plugins agents support

[NTaylorMullen]

Summary

This PR implements support for specialized sub-agents within Open Plugins. It enables automatic discovery, namespacing, and variable expansion for agents defined in an Open Plugin's agents/ directory.

Details

• Core Changes:
  • Updated AgentDefinition to include pluginRoot in metadata.
  • Added recursivelyExpandPluginRoot in agentLoader.ts to support ${PLUGIN_ROOT} expansion in agent configs (system prompts, descriptions, MCP server args).
  • Updated loadAgentsFromDirectory to handle optional pluginRoot.
• CLI Integration:
  • Implemented resolvePluginAgents in plugin.ts to discover and namespace agents using the {plugin-name}:{agent-name} format.
  • Updated ExtensionManager to pass the effective extension path during agent loading.
  • Enhanced extensions list output to display discovered sub-agents.

Related Issues

Fixes https://github.com/google-gemini/maintainers-gemini-cli/issues/1594

How to Validate

1. Unit Tests:
   • Run npm test -w @google/gemini-cli-core -- src/agents/agentLoader.test.ts to verify variable expansion logic.
2. Integration Tests:
   • Run npm run test:e2e -- integration-tests/open-plugin-agents.test.ts to verify the full discovery and namespacing flow.
3. Manual Check:
   • Create a local Open Plugin with an agents/ directory containing a .md agent file.
   • Install it using gemini extensions install <path>.
   • Run gemini extensions list and verify the agent appears correctly namespaced and with expanded paths.

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

[gemini-code-assist]

Summary of Changes

Hello, 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 introduces a significant enhancement by allowing Open Plugins to define and manage their own sub-agents. This feature includes automatic discovery of agents within a plugin's directory structure, proper namespacing to avoid conflicts, and dynamic variable expansion for ${PLUGIN_ROOT} within agent configurations. The changes ensure that agents defined within plugins are fully functional and correctly integrated into the CLI's extension ecosystem, improving the modularity and self-containment of Open Plugins.

Highlights

• Open Plugin Agent Support: Implemented support for specialized sub-agents within Open Plugins, allowing plugins to define and manage their own agents.
• Variable Expansion: Added functionality to automatically expand the ${PLUGIN_ROOT} variable in agent configurations (system prompts, descriptions, MCP server arguments) to the plugin's absolute path.
• Agent Discovery and Namespacing: Enabled automatic discovery of agents located in an Open Plugin's agents/ directory and introduced namespacing using the {plugin-name}:{agent-name} format.
• CLI Integration: Updated the CLI's extension manager to correctly load and display these new sub-agents, passing the necessary plugin root context during agent loading.
• Testing: Added new unit tests for ${PLUGIN_ROOT} expansion logic and an integration test to validate the full discovery, namespacing, and expansion flow for Open Plugin agents.

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.

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. ↩

[github-actions]

🧠 Model Steering Guidance

This PR modifies files that affect the model's behavior (prompts, tools, or instructions).

• ⚠️ Consider adding Evals: No behavioral evaluations (evals/*.eval.ts) were added or updated in this PR. Consider adding a test case to verify the new behavior and prevent regressions.
• 🚀 Maintainer Reminder: Please ensure that these changes do not regress results on benchmark evals before merging.

---

This is an automated guidance message triggered by steering logic signatures.

[gemini-code-assist]

Code Review

This pull request introduces support for sub-agents within Open Plugins, a valuable enhancement that enables automatic discovery, namespacing, and variable expansion. The implementation is well-structured and includes both unit and integration tests. I've identified one high-severity security issue related to path manipulation, where the ${PLUGIN_ROOT} variable expansion could fail or be exploited if the plugin's file path contains special characters. The suggested fix effectively sanitizes the path component. Overall, this is a solid contribution with a critical security improvement.

_{Note: Security Review is unavailable for this PR.}

[gemini-code-assist]

The String.prototype.replace() method interprets special character sequences (like $&, $') in the replacement string as substitution patterns rather than literal strings. If the pluginRoot path happens to contain these characters (which is valid for file paths on some systems), the expansion of ${PLUGIN_ROOT} will be incorrect. This constitutes a path manipulation vulnerability, as unsanitized path components can lead to broken paths, unexpected behavior, or even path traversal if the resulting path is used in file system operations without further validation. To ensure pluginRoot is always treated as a literal string during replacement, it's safer to use a replacer function, effectively sanitizing the path component.

Suggested change

	return obj.replace(/\${PLUGIN_ROOT}/g, pluginRoot) as unknown as T;
	return obj.replace(/\${PLUGIN_ROOT}/g, () => pluginRoot) as unknown as T;

References

1. Sanitize user-provided file paths used in file system operations to prevent path traversal vulnerabilities. This comment addresses a similar issue where a path component needs sanitization to prevent incorrect interpretation during string replacement, which could lead to path manipulation.