feat(core): virtual tools support (#1806)

[matiasmolinas]

This PR introduces a "Manifest-Driven Virtual Tool System" to the Gemini CLI, enabling users to define and execute custom, sandboxed tools directly from their project's GEMINI.md file. This is a generic, opt-in feature that enhances CLI extensibility without altering its core behavior for existing users.

The implementation consists of two main parts:

1. A ManifestParser that detects a special ### Tools section in GEMINI.md and extracts tool definitions (a shell script and a JSON schema).
2. A VirtualShellTool class that executes these parsed scripts within the CLI's existing, secure sandbox, delegating the execution to the native ShellTool.

This change democratizes tool creation, allowing any user who can write a simple shell script to create powerful, project-specific AI workflows and advanced agentic systems like LLMunix.

Dive Deeper

The primary motivation for this change is to unlock advanced agentic behavior by providing a simple, secure, and accessible way to extend the CLI's capabilities. Instead of building a complex, framework-specific runner, this PR enhances the existing GEMINI.md context-loading mechanism to support executable manifests.

Architectural Approach:

• Decoupled & Agnostic: The core CLI remains unaware of any specific agentic framework (like LLMunix). It only gains the generic ability to parse a Markdown manifest and execute shell scripts. This keeps the core clean and maintainable.
• Secure by Default: By creating a new VirtualShellTool that delegates its execution to the battle-tested native ShellTool, we ensure all user-defined code runs within the existing sandboxing infrastructure (Docker, Podman, or Seatbelt). This is a critical security consideration.
• Low Barrier to Entry: Users no longer need to write TypeScript or set up complex MCP servers for many common use cases. If a task can be done in a shell script, it can now be a tool.

How it Works:

1. On startup, the MemoryDiscoveryService loads GEMINI.md files as usual.
2. It now passes the content to a new ManifestParser, which looks for a ### Tools section.
3. For each tool defined with a #### tool_name header and corresponding sh and json code blocks, the parser creates a VirtualToolDefinition object.
4. For each definition, a new VirtualShellTool instance is created and registered with the ToolRegistry.
5. When the LLM calls one of these virtual tools, the VirtualShellTool instance stringifies the arguments, passes them to the tool's script via a GEMINI_TOOL_ARGS environment variable, and executes the script within the sandbox.
6. stdout from the script is returned to the LLM as the tool's result.

This approach is powerful because it allows the entire "firmware" of an agentic system—its core logic (the system prompt) and its system calls (the virtual tools)—to live and be version-controlled directly within the user's project repository.

Reviewer Test Plan

To validate these changes, pull down this branch and run the following tests.

1. Unit & Basic Integration Test:

• Run the full test suite to ensure no existing functionality is broken:

  npm test

• Run the new integration test for manifest tools to validate the core mechanics in isolation:

  npm run test:e2e manifest-tools

2. End-to-End Acceptance Test with LLMunix:
This is the most important test, as it validates the feature's ability to power a complex, real-world agentic system.

• Step 1: Clone the test repository.

  git clone https://github.com/EvolvingAgentsLabs/llmunix
  cd llmunix

• Step 2: Initialize the workspace.

  ./llmunix-boot

• Step 3: Run the local build of Gemini CLI.
  From the gemini-cli project root:

  npm start

  The CLI should start, and you will see logs indicating that the virtual tools from llmunix/GEMINI.md have been registered (e.g., [MemoryDiscovery] Registered virtual tool 'run_agent' from ...).

• Step 4: Provide a high-level goal.
  At the Gemini CLI prompt, enter the following goal:

  > Create a research report on "AI Safety in Multi-Agent Systems" by:
  > 1. Using ResearchAgent to gather information
  > 2. Using SummarizationAgent to create an outline
  > 3. Using WritingAgent to produce the final report
  > 4. Save everything to workspace/reports/ai_safety_research.md
  

• Step 5: Observe and Validate Agent Behavior.
  You should observe the following sequence of events, which confirms the system is working as intended:

  • The agent will use the list_files virtual tool to check its capabilities.
  • It will identify that WritingAgent.md is missing.
  • It will autonomously create the WritingAgent.md file using the write_file virtual tool.
  • It will then proceed to execute its plan by calling the run_agent virtual tool multiple times.
  • The agent should successfully complete the task, creating the final report in the workspace/reports/ directory.

Testing Matrix

	🍏 macOS (Intel)	🪟 Windows (WSL2)	🐧 Linux (Ubuntu)
npm run	✅	✅	✅
npx	✅	✅	✅
Docker	✅	✅	✅
Podman	-	-	-
Seatbelt	✅	-	-

Linked issues / bugs

Resolves #1806

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @matiasmolinas, 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 significantly expands the Gemini CLI's capabilities by enabling users to define custom, sandboxed tools directly within their project's GEMINI.md files. This feature, designed for security and ease of use, allows for more powerful and project-specific AI workflows. Beyond the core virtual tool functionality, I've also implemented security enhancements for user authentication, refined chat history management, and made several minor UI/UX improvements.

Highlights

• Virtual Tool System Introduction: I've introduced a new 'Manifest-Driven Virtual Tool System' to the Gemini CLI. This allows users to define and execute custom, sandboxed tools directly from their project's GEMINI.md file, significantly enhancing CLI extensibility for advanced AI workflows.
• Manifest Parsing: A new ManifestParser has been implemented to detect and extract tool definitions from a special ### Tools section within GEMINI.md files. Each tool definition includes a shell script and a JSON schema.
• Virtual Tool Execution: The VirtualShellTool class is now responsible for executing these user-defined shell scripts within the CLI's existing secure sandbox. Arguments are passed via the GEMINI_TOOL_ARGS environment variable, and stdout is returned as the tool's result.
• Tool Discovery Integration: The ToolRegistry has been updated to automatically discover and register these new virtual tools upon startup, integrating them seamlessly with existing built-in and discovered tools.
• Enhanced Security for Google Account ID Retrieval: I've refactored the Google Account ID retrieval process to use id_token verification, which is a more secure and privacy-preserving method compared to the previous userinfo endpoint.
• Chat History Compression Logic: The GeminiClient now includes logic to dynamically manage chat history size. It can trigger summarization based on token limits, ensuring the model operates efficiently within its context window.
• Documentation and Testing: Comprehensive documentation for virtual tools has been added, and a new integration test specifically validates the core mechanics of the virtual tool system.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 is currently in preview and 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 to provide feedback.

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 introduces manifest-driven virtual tools, a powerful extension to the CLI. A critical change to the telemetry system involves sending Personally Identifiable Information (PII). This change was not documented in the pull request description and requires immediate attention to ensure user privacy and compliance.

[srithreepo]

Thanks so much for you efforts in this space, we really appreciate your contributions and encourage you to keep them coming !

This is a very good idea and will be valuable for many users. In order to help users build and implement use cases such as this, we encourage users to implement these using either extensions or MCP Servers.

Have you considered one of thes approaches? You can learn more about Extensions here, https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md

Please don't hesitate to reach out if you had any further thoughts / comments about this.

While we are closing this PR for now, we do look forward to seeing how you take this forward as an extension or MCP server !