docs: overhaul subagents documentation and add /agents command

[abhipatel12]

Summary

Complete revamp of subagents documentation, providing a comprehensive guide to their use, management, and configuration.

Details

• How to use subagents: Added a new section to subagents.md explaining automatic delegation and the new @agent-name syntax for forced invocation.
• Managing subagents:
  • Added the /agents slash command suite to docs/reference/commands.md (list, reload, enable, disable, config).
  • Clarified the distinction between interactive management (/agents) and persistent configuration (settings.json).
• Configuration & Overrides:
  • Updated codebase_investigator configuration examples to use the modern agents.overrides structure.
  • Added a section on modelConfigs.overrides with overrideScope for targeting specific agents.
  • Corrected default values for max_turns (30) and timeout_mins (10) based on codebase investigation.
• Custom Agents:
  • Detailed tool wildcard support (*, mcp_*, mcp_server_*).
  • Clarified tool inheritance (defaults to all parent tools if omitted).
  • Added documentation on isolation and recursion protection (subagents cannot call other subagents).
• Model Examples: Updated various examples to use gemini-3-flash-preview for better alignment with current recommended models.

Related Issues

Resolves #20310

How to Validate

• Review modified documentation in docs/core/subagents.md and docs/reference/commands.md.
• Ensure all technical details (defaults, syntax, settings paths) align with the current implementation.

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 significantly overhauls the documentation for subagents, providing a more comprehensive and user-friendly guide. It introduces new methods for interacting with and configuring subagents, including an interactive slash command and detailed persistent configuration options. The changes aim to clarify subagent behavior, management, and advanced features, ensuring users have up-to-date and accurate information for leveraging these capabilities.

Highlights

• Subagent Usage: Added a new section to subagents.md explaining automatic delegation and the new @agent-name syntax for forced invocation.
• Subagent Management: Introduced the /agents slash command suite to docs/reference/commands.md (list, reload, enable, disable, config) and clarified the distinction between interactive management and persistent configuration via settings.json.
• Configuration & Overrides: Updated codebase_investigator configuration examples to use the modern agents.overrides structure, added a section on modelConfigs.overrides with overrideScope, and corrected default values for max_turns (30) and timeout_mins (10).
• Custom Agents: Detailed tool wildcard support (*, mcp_*, mcp_server_*), clarified tool inheritance, and added documentation on isolation and recursion protection (subagents cannot call other subagents).
• Model Examples: Updated various examples to use gemini-3-flash-preview for better alignment with current recommended models.

Changelog

• docs/core/subagents.md
  • Added a new 'How to use subagents' section, detailing automatic delegation and explicit invocation using the '@' syntax.
  • Updated the codebase_investigator configuration example to use the agents.overrides structure.
  • Changed the model in a subagent example from gemini-2.5-pro to gemini-3-flash-preview.
  • Revised the configuration schema table to update default values for max_turns (from 15 to 30), timeout_mins (from 5 to 10), and temperature (added default of 1).
  • Introduced new sections for 'Tool wildcards' and 'Isolation and recursion protection' for subagents.
  • Added a comprehensive 'Managing subagents' section, covering interactive management with the new /agents command and persistent configuration via settings.json using agents.overrides and modelConfigs.overrides.
• docs/reference/commands.md
  • Documented the new /agents slash command, including its description, experimental note, and sub-commands: list, reload, enable, disable, and config.

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 provides a significant and much-needed overhaul of the subagents documentation. The new content clearly explains how to use, manage, and configure subagents, and introduces the new /agents command. The documentation is well-structured and easy to follow. I found one high-severity issue in a configuration example where an incorrect property name is used, which would prevent the configuration from working as expected.

_{Note: Security Review has been skipped due to the limited scope of the PR.}

[github-actions]

Size Change: -4 B (0%)

Total Size: 26.1 MB

Filename	Size	Change
./bundle/chunk-EPV6FKGX.js	0 B	-13.4 MB (removed)	🏆
./bundle/chunk-RUDBQ5LS.js	0 B	-3.62 MB (removed)	🏆
./bundle/core-AGCEXANM.js	0 B	-40.2 kB (removed)	🏆
./bundle/devtoolsService-CCIJ5N4V.js	0 B	-27.7 kB (removed)	🏆
./bundle/interactiveCli-5PIVK5XI.js	0 B	-1.59 MB (removed)	🏆
./bundle/oauth2-provider-IQXLGMQI.js	0 B	-9.19 kB (removed)	🏆
./bundle/chunk-2PYKBZ5B.js	13.4 MB	+13.4 MB (new file)	🆕
./bundle/chunk-JW7AMT6I.js	3.62 MB	+3.62 MB (new file)	🆕
./bundle/core-FPQXMAMW.js	40.2 kB	+40.2 kB (new file)	🆕
./bundle/devtoolsService-NTR7Y3F5.js	27.7 kB	+27.7 kB (new file)	🆕
./bundle/interactiveCli-BXC74SLZ.js	1.59 MB	+1.59 MB (new file)	🆕
./bundle/oauth2-provider-RFZFLED5.js	9.19 kB	+9.19 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size	Change
./bundle/chunk-34MYV7JD.js	2.45 kB	0 B
./bundle/chunk-37ZTTFQF.js	966 kB	0 B
./bundle/chunk-5AUYMPVF.js	858 B	0 B
./bundle/chunk-5Q3GACO5.js	1.95 MB	0 B
./bundle/chunk-664ZODQF.js	124 kB	0 B
./bundle/chunk-DAHVX5MI.js	206 kB	0 B
./bundle/chunk-IUUIT4SU.js	56.5 kB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/devtools-36NN55EP.js	696 kB	0 B
./bundle/dist-T73EYRDX.js	356 B	0 B
./bundle/gemini.js	695 kB	0 B
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB	0 B
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB	0 B
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB	0 B
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB	0 B
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB	0 B
./bundle/keychain-token-storage-U7RYMHHK.js	0 B	-518 B (removed)	🏆
./bundle/memoryDiscovery-RQEFN44F.js	922 B	0 B
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B
./bundle/src-QVCVGIUX.js	47 kB	0 B
./bundle/tree-sitter-7U6MW5PS.js	274 kB	0 B
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB	0 B
./bundle/undici-4X2YZID5.js	360 B	0 B
./bundle/keychain-token-storage-6GCYRU2T.js	518 B	+518 B (new file)	🆕

_{compressed-size-action}

[jkcinouye]

LGTM - just one note about the order in commands.md