Feature: First-Run Experience for Project-Level Sub-Agents

[abhipatel12]

Feature Request: First-Run Experience for Project-Level Sub-Agents

Problem

Currently, when a user trusts a folder, any project-level sub-agents defined in .gemini/agents/*.toml are automatically loaded and registered. Since these agents operate in ApprovalMode.YOLO (forced by AgentExecutor), they can execute tools without explicit user confirmation. Users may not be aware of which agents are being introduced by a project, leading to potential security or transparency concerns.

Proposed Solution

Implement a "First-Run Experience" (FRE) for project-level sub-agents. When the AgentRegistry discovers new or modified sub-agents in a project directory, it should:

1. Detect New/Changed Agents: Track which agents have already been "acknowledged" by the user for a given project.
2. Notify the User: On the first run where new agents are detected, display a summary of these agents (name, description, and potentially their system prompt/tools).
3. Request Acknowledgement: Optionally require the user to acknowledge or "opt-in" to these sub-agents before they can be invoked via delegate_to_agent.

Details

• Precedence should be given to user-level agents in ~/.gemini/agents/, which do not require this FRE.
• The acknowledgement state should probably be stored in the project-level .gemini/ state or the global user config, keyed by project path and agent hash/version.
• This ensures that even in trusted folders, the user has visibility into the autonomous tools being added to their environment.

Tasks

• Define storage for "acknowledged" project agents.
• Implement detection of new/modified TOML files in .gemini/agents/.
• Create a UI component (CLI/Ink) to display the "New Agents Discovered" notice.
• Update AgentRegistry to handle the acknowledgement flow during initialization.