docs(core): add authentication guide for remote subagents

[adamfweidman]

Summary

Adds authentication documentation to the remote subagents page covering all supported auth types and how Google ADC works for agents.

Details

Updates docs/core/remote-agents.md with:

• All 4 auth types: apiKey, http, google-credentials, oauth2
• How google-credentials selects access tokens (*.googleapis.com) vs identity tokens (*.run.app)
• Dynamic value resolution ($ENV_VAR, !command, literals)
• Auth validation, retry behavior, and agent card fetching
• Configuration examples for each auth type

Minor update to docs/core/subagents.md to reference auth in the remote agents link.

Related Issues

Fixes #21953

How to Validate

1. Read docs/core/remote-agents.md and verify auth docs are accurate
2. Cross-reference YAML examples against Zod schemas in packages/core/src/agents/agentLoader.ts
3. Verify google-credentials token selection matches packages/core/src/agents/auth-provider/google-credentials-provider.ts

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-cli]

Hi @adamfweidman, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[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 enhances the documentation for remote subagents by introducing a comprehensive guide on authentication. It clarifies how users can configure various authentication methods, including API keys, HTTP authentication, Google Application Default Credentials, and OAuth 2.0, ensuring secure communication with remote agents. The update aims to provide clear instructions and examples, making it easier for developers to integrate and manage authenticated remote subagents within the Gemini CLI.

Highlights

• Comprehensive Authentication Documentation: Added a detailed guide for authenticating remote subagents, covering various methods and best practices.
• Supported Authentication Types: Documented four authentication types: apiKey, http (Bearer, Basic, Raw), google-credentials, and oauth2.
• Dynamic Value Resolution: Explained how to use environment variables, shell commands, and literal values for sensitive authentication parameters.
• Google Application Default Credentials (ADC): Provided specific guidance on using ADC, including token selection logic for Google APIs vs. Cloud Run, setup, and allowed hosts.
• Auth Validation and Retry Behavior: Described how the Gemini CLI validates authentication configurations and automatically retries requests on 401/403 responses.
• Documentation Cross-Reference: Updated the main subagents documentation to explicitly reference the new authentication guide for remote agents.

Changelog

• docs/core/remote-agents.md
  • Added a new 'auth' field to the remote agent configuration table.
  • Introduced a detailed 'Authentication' section covering supported types, dynamic values, and specific configurations for 'apiKey', 'http', 'google-credentials', and 'oauth2'.
  • Included explanations for 'google-credentials' token selection, setup, and allowed hosts.
  • Documented auth validation, retry behavior, and agent card fetching with authentication.
• docs/core/subagents.md
  • Updated the description for the remote subagents documentation link to explicitly mention authentication.

Activity

• No human activity has occurred on this pull request yet.

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 adds comprehensive documentation for authentication with remote subagents. The documentation for apiKey, http, and oauth2 authentication methods is well-written and appears to correctly reflect the implementation. However, a critical issue has been identified with the documentation for the google-credentials auth type, as it describes a feature that is not yet fully implemented. This violates the guideline to avoid documenting premature features, which can lead to user confusion and immediate maintenance overhead. My review includes a detailed comment on this issue.

_{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-4DQWJDEN.js	0 B	-3.62 MB (removed)	🏆
./bundle/chunk-XMMENVDE.js	0 B	-13.4 MB (removed)	🏆
./bundle/core-WWYSO2K3.js	0 B	-40.1 kB (removed)	🏆
./bundle/devtoolsService-HKWRY7L3.js	0 B	-27.7 kB (removed)	🏆
./bundle/interactiveCli-2BWJIET3.js	0 B	-1.59 MB (removed)	🏆
./bundle/oauth2-provider-O462LO7O.js	0 B	-9.19 kB (removed)	🏆
./bundle/chunk-MMMYEUJI.js	13.4 MB	+13.4 MB (new file)	🆕
./bundle/chunk-WMFQ342W.js	3.62 MB	+3.62 MB (new file)	🆕
./bundle/core-JV6AU33H.js	40.1 kB	+40.1 kB (new file)	🆕
./bundle/devtoolsService-IZXDZHSL.js	27.7 kB	+27.7 kB (new file)	🆕
./bundle/interactiveCli-DN6PAKZL.js	1.59 MB	+1.59 MB (new file)	🆕
./bundle/oauth2-provider-K74P2SQ4.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	689 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-LGJJQHBL.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-KVR6H2RG.js	518 B	+518 B (new file)	🆕

_{compressed-size-action}

[gsquared94]

Requesting doc updates about service proxies.