@google/gemini-cli-core 0.66.0-preview.0 → 0.67.0-nightly.20261022.g09d81bf11

package/dist/docs/changelogs/index.md

@@ -18,6 +18,25 @@ on GitHub.
 | [Preview](preview.md) | Experimental features ready for early feedback. |
 | [Stable](latest.md)   | Stable, recommended for general use.            |
 
+## Announcements: v0.65.0 - 2026-10-20
+
+- **Custom Telemetry Headers:** Added support for configuring custom OTLP
+  headers in telemetry configuration
+  ([#29641](https://github.com/google-gemini/gemini-cli/pull/29641) by
+  @jesussamuel-byte).
+- **Filesystem & Traversal Performance:** Optimized ignore pattern filtering
+  with subtree pruning and deferred recursive file reads for directory
+  references ([#29582](https://github.com/google-gemini/gemini-cli/pull/29582)
+  by @amelidev, [#29617](https://github.com/google-gemini/gemini-cli/pull/29617)
+  by @jvargassanchez-dot).
+- **Workspace Security & Session Resilience:** Enforced read-only workspace
+  settings in untrusted folders, resolved infinite OAuth retry loops, and
+  prevented session poisoning on rapid Ctrl+C interruptions
+  ([#29583](https://github.com/google-gemini/gemini-cli/pull/29583) by
+  @jvargassanchez-dot,
+  [#29655](https://github.com/google-gemini/gemini-cli/pull/29655) by
+  @villahernandez-coder).
+
 ## Announcements: v0.64.0 - 2026-10-13
 
 - **Atomic Operations & State Persistence:** Serialized file tool operations

package/dist/docs/changelogs/latest.md

@@ -1,6 +1,6 @@
-# Latest stable release: v0.64.0
+# Latest stable release: v0.65.0
 
-Released: October 13, 2026
+Released: October 20, 2026
 
 For most users, our latest stable release is the recommended release. Install
 the latest stable version with:
@@ -11,72 +11,103 @@ npm install -g @google/gemini-cli
 
 ## Highlights
 
-- **Atomic File Operations & State Recovery:** Serialized file tool operations
-  with atomic writes and introduced atomic CLI state persistence with automatic
-  recovery from backup on corruption.
-- **Chat Recording Optimization:** Implemented append-only delta patching and
-  bounded history windowing in ChatRecordingService to optimize memory and disk
-  efficiency during long-running sessions.
-- **CLI Input & Reference Resolution:** Added support for resolving `@file:line`
-  references, resolved CPU hangs and quote swallowing on `@` symbols within code
-  blocks, and prevented ghost text wrap hangs.
-- **Terminal UI & Interaction Stability:** Ensured Ctrl+C emergency aborts
-  reliably reach active cancellation handlers, made selection list confirmation
-  with Enter and Spacebar dependable, preserved scroll positions, and fixed
-  Windows ConPTY IME cursor forwarding.
+- **Custom Telemetry Headers:** Added support for configuring custom OTLP
+  headers in telemetry settings, enabling authentication and header
+  customization for OpenTelemetry collectors.
+- **File System Performance & Traversal:** Optimized ignore pattern filtering
+  with subtree pruning to accelerate directory scanning, deferred recursive file
+  reads for `@<directory>` references, and improved empty file handling across
+  multi-byte encodings.
+- **Session Resilience & State Integrity:** Prevented session poisoning during
+  rapid Ctrl+C interruptions, preserved resumed session history on quick exits,
+  and eliminated duplicate tool response turns upon resuming sessions.
+- **Authentication & Workspace Security:** Enforced read-only workspace settings
+  in untrusted folders, aligned OAuth callback parameter validation with RFC
+  9207 metadata, and resolved infinite authentication retry loops.
+- **Terminal UI & Interactive Stability:** Resolved interactive mode hangs on
+  Enter keypresses, prevented unnecessary terminal clears and scroll resets when
+  expanding output with Ctrl+O, and restored debounced static UI refreshes on
+  terminal width changes.
 
 ## What's Changed
 
-- refactor(a2a-server): implement V1 to V2 settings migration logic by
+- fix(cli): enforce read-only workspace settings in untrusted folders by
   @jvargassanchez-dot in
-  [#29450](https://github.com/google-gemini/gemini-cli/pull/29450)
-- fix(acp): bridge PromptResponse.usage and emit usage_update notifications
-  (#29389) by @elberthc-byte in
-  [#29549](https://github.com/google-gemini/gemini-cli/pull/29549)
-- Changelog for v0.63.0-preview.0 by @gemini-cli-robot in
-  [#29565](https://github.com/google-gemini/gemini-cli/pull/29565)
-- fix(cli): propagate resolved folder trust state in headless mode (#29031) by
-  @amelidev in [#29528](https://github.com/google-gemini/gemini-cli/pull/29528)
-- chore(release): bump version to 0.64.0-nightly.20260929.gd75234cae by
+  [#29583](https://github.com/google-gemini/gemini-cli/pull/29583)
+- fix(core): avoid duplicate tool response turns when resuming sessions by
+  @diegogodinezr in
+  [#29618](https://github.com/google-gemini/gemini-cli/pull/29618)
+- fix(core): prevent deletion of resumed session history on quick exit (#29198)
+  by @villahernandez-coder in
+  [#29584](https://github.com/google-gemini/gemini-cli/pull/29584)
+- Changelog for v0.64.0-preview.0 by @gemini-cli-robot in
+  [#29656](https://github.com/google-gemini/gemini-cli/pull/29656)
+- Changelog for v0.63.0 by @gemini-cli-robot in
+  [#29659](https://github.com/google-gemini/gemini-cli/pull/29659)
+- fix(core): align OAuth callback iss parameter validation with RFC 9207
+  metadata by @luisfelipe-alt in
+  [#29616](https://github.com/google-gemini/gemini-cli/pull/29616)
+- fix(cli): prevent unnecessary terminal clears and scroll resets when expanding
+  with Ctrl+O by @jesussamuel-byte in
+  [#29640](https://github.com/google-gemini/gemini-cli/pull/29640)
+- chore(release): bump version to 0.65.0-nightly.20261006.gfb972b2f8 by
   @gemini-cli-robot in
-  [#29567](https://github.com/google-gemini/gemini-cli/pull/29567)
-- fix(cli): prevent CPU hang and quote swallowing on @ within code (#29434) by
-  @elberthc-byte in
-  [#29557](https://github.com/google-gemini/gemini-cli/pull/29557)
-- fix(core): serialize file tool operations and make writes atomic (#29078) by
+  [#29657](https://github.com/google-gemini/gemini-cli/pull/29657)
+- fix(ci): add missing loop in unassign-inactive-assignees workflow by
+  @ugorla-dev in
+  [#29609](https://github.com/google-gemini/gemini-cli/pull/29609)
+- fix(core): enforce terminal user turn invariant and normalize request contents
+  by @luisfelipe-alt in
+  [#29612](https://github.com/google-gemini/gemini-cli/pull/29612)
+- `feat(telemetry): support custom OTLP headers in telemetry configuration` by
+  @jesussamuel-byte in
+  [#29641](https://github.com/google-gemini/gemini-cli/pull/29641)
+- fix(auth): prevent infinite verification and OAuth retry loops by
+  @villahernandez-coder in
+  [#29655](https://github.com/google-gemini/gemini-cli/pull/29655)
+- fix(cli): handle JSON parse and response stream errors in fetchJson by
+  @jesussamuel-byte in
+  [#29658](https://github.com/google-gemini/gemini-cli/pull/29658)
+- fix(core): preserve line terminators in truncateString by @diegogodinezr in
+  [#29673](https://github.com/google-gemini/gemini-cli/pull/29673)
+- fix(vscode-ide-companion): make IdeServer.stop() resolve while MCP sessions
+  are open by @elberthc-byte in
+  [#29674](https://github.com/google-gemini/gemini-cli/pull/29674)
+- fix(core): retain ask_user question text in the tool result display by
   @elberthc-byte in
-  [#29499](https://github.com/google-gemini/gemini-cli/pull/29499)
-- fix(core): implement append-only delta patching and bounded history windowing
-  in ChatRecordingService by @jvargassanchez-dot in
-  [#29568](https://github.com/google-gemini/gemini-cli/pull/29568)
-- fix(cli): persist state atomically and recover from backup on corruption by
+  [#29677](https://github.com/google-gemini/gemini-cli/pull/29677)
+- fix(core): eliminate false positives on untrusted command flags and compound
+  loops by @DavidAPierce in
+  [#29672](https://github.com/google-gemini/gemini-cli/pull/29672)
+- fix(cli): clear cached credentials when re-selecting Google login by
   @urielefrenvirtusa in
-  [#29558](https://github.com/google-gemini/gemini-cli/pull/29558)
-- fix(cli): ensure Ctrl+C emergency abort reaches cancellation handler during
-  active operations by @urielefrenvirtusa in
-  [#29586](https://github.com/google-gemini/gemini-cli/pull/29586)
-- fix(cli): resolve @file:line references and prevent ghost text wrap hang by
+  [#29643](https://github.com/google-gemini/gemini-cli/pull/29643)
+- fix(cli): resolve hang on Enter keypress in interactive mode (#23297) by
+  @elberthc-byte in
+  [#29476](https://github.com/google-gemini/gemini-cli/pull/29476)
+- perf(core): optimize ignore filtering and enable subtree pruning (#29077) by
+  @amelidev in [#29582](https://github.com/google-gemini/gemini-cli/pull/29582)
+- fix(a2a-server): isolate tool rejection to active call in sequential batches
+  by @jvargassanchez-dot in
+  [#29683](https://github.com/google-gemini/gemini-cli/pull/29683)
+- fix(cli): skip eager recursive file reading for @<directory> references by
+  @jvargassanchez-dot in
+  [#29617](https://github.com/google-gemini/gemini-cli/pull/29617)
+- fix(cli): keep loading other extensions when one fails the allowlist check by
   @jesussamuel-byte in
-  [#29581](https://github.com/google-gemini/gemini-cli/pull/29581)
-- fix(ui): ensure Windows ConPTY forwards IME cursor position by
+  [#29720](https://github.com/google-gemini/gemini-cli/pull/29720)
+- fix(cli): correct reverse search highlight index for expanding unicode
+  characters by @diegogodinezr in
+  [#29699](https://github.com/google-gemini/gemini-cli/pull/29699)
+- fix(core): treat whitespace-only UTF-16 and UTF-32 files as empty by
   @jesussamuel-byte in
-  [#29560](https://github.com/google-gemini/gemini-cli/pull/29560)
-- fix(cli): retry directory removal on Windows locking errors during extension
-  updates by @jesussamuel-byte in
-  [#29540](https://github.com/google-gemini/gemini-cli/pull/29540)
-- fix(acp): resolve session by exact id and handle listener cleanup on session
-  failure by @diegogodinezr in
-  [#29580](https://github.com/google-gemini/gemini-cli/pull/29580)
-- fix(cli): preserve scroll position and partition pending height budget by
-  @luisfelipe-alt in
-  [#29520](https://github.com/google-gemini/gemini-cli/pull/29520)
-- fix(cli): ensure Enter and Spacebar reliably confirm selection list options by
-  @ugorla-dev in
-  [#29502](https://github.com/google-gemini/gemini-cli/pull/29502)
-- fix(patch): cherry-pick 2ce1a69 to release/v0.64.0-preview.0-pr-29672 to patch
-  version v0.64.0-preview.0 and create version 0.64.0-preview.1 by
-  @gemini-cli-robot in
-  [#29696](https://github.com/google-gemini/gemini-cli/pull/29696)
+  [#29722](https://github.com/google-gemini/gemini-cli/pull/29722)
+- fix(cli): restore debounced static UI refresh on terminal width changes by
+  @jvargassanchez-dot in
+  [#29644](https://github.com/google-gemini/gemini-cli/pull/29644)
+- fix(cli): prevent session poisoning on rapid Ctrl-C interruption by
+  @villahernandez-coder in
+  [#29728](https://github.com/google-gemini/gemini-cli/pull/29728)
 
 **Full Changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.63.0...v0.64.0
+https://github.com/google-gemini/gemini-cli/compare/v0.64.0...v0.65.0

package/dist/docs/changelogs/preview.md

@@ -1,6 +1,6 @@
-# Preview release: v0.65.0-preview.0
+# Preview release: v0.66.0-preview.0
 
-Released: October 13, 2026
+Released: October 20, 2026
 
 Our preview release includes the latest, new, and experimental features. This
 release may not be as stable as our [latest weekly release](latest.md).
@@ -13,103 +13,99 @@ npm install -g @google/gemini-cli@preview
 
 ## Highlights
 
-- **Custom Telemetry Headers**: Added support for configuring custom OTLP
-  headers in telemetry settings, enabling authentication and header
-  customization for OpenTelemetry collectors.
-- **File System Performance & Traversal**: Optimized ignore pattern filtering
-  with subtree pruning to accelerate directory scanning, deferred recursive file
-  reads for `@<directory>` references, and improved empty file handling across
-  multi-byte encodings.
-- **Session Resilience & State Integrity**: Prevented session poisoning during
-  rapid Ctrl+C interruptions, preserved resumed session history on quick exits,
-  and eliminated duplicate tool response turns upon resuming sessions.
-- **Authentication & Workspace Security**: Enforced read-only workspace settings
-  in untrusted directories, aligned OAuth callback parameter validation with RFC
-  9207 metadata, and resolved infinite authentication retry loops.
-- **Terminal UI & Interactive Stability**: Resolved interactive mode hangs on
-  Enter keypresses, prevented unnecessary terminal clears and scroll resets when
-  expanding output with Ctrl+O, and restored debounced static UI refreshes on
-  terminal width changes.
+- **Terminal UI & Output Synchronization**: Implemented synchronized terminal
+  output and isolated spinner rendering to prevent flickering, preserved
+  terminal scrollback during viewport refreshes, corrected debug console height
+  calculations, and eliminated right-hand border bleed in scrollable tool
+  containers.
+- **Tool Execution & Scheduler Architecture**: Refactored the tool execution
+  flow to emit tool call groups directly from the scheduler, removing UI
+  lookahead logic and simplifying execution scheduling.
+- **Shell & Git Environment Integrity**: Preserved user-level `~/.gitconfig`
+  settings across shell and Git environments, disabled interactive credential
+  and SSH prompts to prevent hangs in automated environments, and forwarded
+  termination signals from bootstrap parent processes.
+- **Configuration & Keybindings Flexibility**: Added support for a `keys` array
+  in `keybindings.json`, ensured settings placeholders resolve correctly after
+  loading `.env` files, and improved CLI self-update verification against PATH
+  shadowing.
+- **Networking & MCP Security**: Supported opt-in private network endpoints for
+  MCP OAuth flows and prevented false positive matches in authentication error
+  handling.
 
 ## What's Changed
 
-- fix(cli): enforce read-only workspace settings in untrusted folders by
-  @jvargassanchez-dot in
-  [#29583](https://github.com/google-gemini/gemini-cli/pull/29583)
-- fix(core): avoid duplicate tool response turns when resuming sessions by
-  @diegogodinezr in
-  [#29618](https://github.com/google-gemini/gemini-cli/pull/29618)
-- fix(core): prevent deletion of resumed session history on quick exit (#29198)
-  by @villahernandez-coder in
-  [#29584](https://github.com/google-gemini/gemini-cli/pull/29584)
-- Changelog for v0.64.0-preview.0 by @gemini-cli-robot in
-  [#29656](https://github.com/google-gemini/gemini-cli/pull/29656)
-- Changelog for v0.63.0 by @gemini-cli-robot in
-  [#29659](https://github.com/google-gemini/gemini-cli/pull/29659)
-- fix(core): align OAuth callback iss parameter validation with RFC 9207
-  metadata by @luisfelipe-alt in
-  [#29616](https://github.com/google-gemini/gemini-cli/pull/29616)
-- fix(cli): prevent unnecessary terminal clears and scroll resets when expanding
-  with Ctrl+O by @jesussamuel-byte in
-  [#29640](https://github.com/google-gemini/gemini-cli/pull/29640)
-- chore(release): bump version to 0.65.0-nightly.20261006.gfb972b2f8 by
+- Update ROADMAP.md to no longer reference outdated 2025 roadmap by
+  @DavidAPierce in
+  [#29723](https://github.com/google-gemini/gemini-cli/pull/29723)
+- Changelog for v0.65.0-preview.0 by @gemini-cli-robot in
+  [#29739](https://github.com/google-gemini/gemini-cli/pull/29739)
+- chore(release): bump version to 0.66.0-nightly.20261013.g204db94ae by
   @gemini-cli-robot in
-  [#29657](https://github.com/google-gemini/gemini-cli/pull/29657)
-- fix(ci): add missing loop in unassign-inactive-assignees workflow by
+  [#29740](https://github.com/google-gemini/gemini-cli/pull/29740)
+- Changelog for v0.64.0 by @gemini-cli-robot in
+  [#29741](https://github.com/google-gemini/gemini-cli/pull/29741)
+- fix(ui): implement synchronized output and isolate spinner rendering by
+  @diegogodinezr in
+  [#29725](https://github.com/google-gemini/gemini-cli/pull/29725)
+- fix(ui): fix debug console height calculation and terminalBuffer flickering by
   @ugorla-dev in
-  [#29609](https://github.com/google-gemini/gemini-cli/pull/29609)
-- fix(core): enforce terminal user turn invariant and normalize request contents
-  by @luisfelipe-alt in
-  [#29612](https://github.com/google-gemini/gemini-cli/pull/29612)
-- `feat(telemetry): support custom OTLP headers in telemetry configuration` by
-  @jesussamuel-byte in
-  [#29641](https://github.com/google-gemini/gemini-cli/pull/29641)
-- fix(auth): prevent infinite verification and OAuth retry loops by
+  [#29695](https://github.com/google-gemini/gemini-cli/pull/29695)
+- fix(cli): prevent right-hand border bleed in scrollable tool containers by
   @villahernandez-coder in
-  [#29655](https://github.com/google-gemini/gemini-cli/pull/29655)
-- fix(cli): handle JSON parse and response stream errors in fetchJson by
-  @jesussamuel-byte in
-  [#29658](https://github.com/google-gemini/gemini-cli/pull/29658)
-- fix(core): preserve line terminators in truncateString by @diegogodinezr in
-  [#29673](https://github.com/google-gemini/gemini-cli/pull/29673)
-- fix(vscode-ide-companion): make IdeServer.stop() resolve while MCP sessions
-  are open by @elberthc-byte in
-  [#29674](https://github.com/google-gemini/gemini-cli/pull/29674)
-- fix(core): retain ask_user question text in the tool result display by
-  @elberthc-byte in
-  [#29677](https://github.com/google-gemini/gemini-cli/pull/29677)
-- fix(core): eliminate false positives on untrusted command flags and compound
-  loops by @DavidAPierce in
-  [#29672](https://github.com/google-gemini/gemini-cli/pull/29672)
-- fix(cli): clear cached credentials when re-selecting Google login by
-  @urielefrenvirtusa in
-  [#29643](https://github.com/google-gemini/gemini-cli/pull/29643)
-- fix(cli): resolve hang on Enter keypress in interactive mode (#23297) by
+  [#29742](https://github.com/google-gemini/gemini-cli/pull/29742)
+- refactor(core,cli): emit tool call groups from the scheduler and drop the UI
+  lookahead by @jesussamuel-byte in
+  [#29736](https://github.com/google-gemini/gemini-cli/pull/29736)
+- fix(core): format and quote Windows diff command arguments in openDiff by
+  @jvargassanchez-dot in
+  [#29753](https://github.com/google-gemini/gemini-cli/pull/29753)
+- fix(cli): round before selecting units in formatDuration by @diegogodinezr in
+  [#29766](https://github.com/google-gemini/gemini-cli/pull/29766)
+- fix(core): disable interactive credential and SSH prompts in getSafeGitEnv by
+  @villahernandez-coder in
+  [#29760](https://github.com/google-gemini/gemini-cli/pull/29760)
+- fix(cli): resolve settings placeholders after loading .env files by
   @elberthc-byte in
-  [#29476](https://github.com/google-gemini/gemini-cli/pull/29476)
-- perf(core): optimize ignore filtering and enable subtree pruning (#29077) by
-  @amelidev in [#29582](https://github.com/google-gemini/gemini-cli/pull/29582)
-- fix(a2a-server): isolate tool rejection to active call in sequential batches
-  by @jvargassanchez-dot in
-  [#29683](https://github.com/google-gemini/gemini-cli/pull/29683)
-- fix(cli): skip eager recursive file reading for @<directory> references by
+  [#29750](https://github.com/google-gemini/gemini-cli/pull/29750)
+- fix(core): harden SKILL.md frontmatter parsing for single-line descriptions by
+  @jesussamuel-byte in
+  [#29769](https://github.com/google-gemini/gemini-cli/pull/29769)
+- Add Banner about Gemini CLI not being optimized for Gemini 4 by @srithreepo in
+  [#29774](https://github.com/google-gemini/gemini-cli/pull/29774)
+- Update README to remove obsolete content by @srithreepo in
+  [#29775](https://github.com/google-gemini/gemini-cli/pull/29775)
+- fix(ci): remove unsupported members permission in unassign-inactive-assignees
+  workflow by @ugorla-dev in
+  [#29770](https://github.com/google-gemini/gemini-cli/pull/29770)
+- fix(cli): reset slash-command conflict dedupe when conflicts reappear by
   @jvargassanchez-dot in
-  [#29617](https://github.com/google-gemini/gemini-cli/pull/29617)
-- fix(cli): keep loading other extensions when one fails the allowlist check by
+  [#29768](https://github.com/google-gemini/gemini-cli/pull/29768)
+- fix(cli): verify active binary update to prevent PATH shadowing false success
+  by @urielefrenvirtusa in
+  [#29757](https://github.com/google-gemini/gemini-cli/pull/29757)
+- fix(cli): support 'keys' array in keybindings.json by @urielefrenvirtusa in
+  [#29773](https://github.com/google-gemini/gemini-cli/pull/29773)
+- fix(cli): forward termination signals from bootstrap parent to child process
+  by @villahernandez-coder in
+  [#29790](https://github.com/google-gemini/gemini-cli/pull/29790)
+- fix(ui): preserve terminal scrollback during viewport refreshes by
+  @diegogodinezr in
+  [#29792](https://github.com/google-gemini/gemini-cli/pull/29792)
+- fix(cli): decode streamed Node HTTP activity chunks with StringDecoder by
   @jesussamuel-byte in
-  [#29720](https://github.com/google-gemini/gemini-cli/pull/29720)
-- fix(cli): correct reverse search highlight index for expanding unicode
-  characters by @diegogodinezr in
-  [#29699](https://github.com/google-gemini/gemini-cli/pull/29699)
-- fix(core): treat whitespace-only UTF-16 and UTF-32 files as empty by
+  [#29827](https://github.com/google-gemini/gemini-cli/pull/29827)
+- chore: migrate gsutil usage to gcloud storage by @gurusai-voleti in
+  [#29839](https://github.com/google-gemini/gemini-cli/pull/29839)
+- fix(core): preserve user-level ~/.gitconfig in shell and git environments by
   @jesussamuel-byte in
-  [#29722](https://github.com/google-gemini/gemini-cli/pull/29722)
-- fix(cli): restore debounced static UI refresh on terminal width changes by
-  @jvargassanchez-dot in
-  [#29644](https://github.com/google-gemini/gemini-cli/pull/29644)
-- fix(cli): prevent session poisoning on rapid Ctrl-C interruption by
-  @villahernandez-coder in
-  [#29728](https://github.com/google-gemini/gemini-cli/pull/29728)
+  [#29832](https://github.com/google-gemini/gemini-cli/pull/29832)
+- fix(core): prevent false positive matches in isAuthenticationError by
+  @urielefrenvirtusa in
+  [#29835](https://github.com/google-gemini/gemini-cli/pull/29835)
+- fix(core): support opt-in private network endpoints for MCP OAuth flows by
+  @luisfelipe-alt in
+  [#29844](https://github.com/google-gemini/gemini-cli/pull/29844)
 
 **Full Changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.64.0-preview.1...v0.65.0-preview.0
+https://github.com/google-gemini/gemini-cli/compare/v0.65.0-preview.0...v0.66.0-preview.0

package/dist/docs/cli/sandbox.md

@@ -118,6 +118,14 @@ mount your local project folder and operate within `/Users/you/project` inside
 the container. This allows the AI to seamlessly read and modify your project
 files while remaining isolated from the rest of your system.
 
+**How it works (IDE integration):**
+
+When you start Gemini CLI from your IDE's integrated terminal, the host process
+bridges the IDE companion connection into the container over `docker exec` (or
+`podman exec`). The companion's port and authentication token stay on the host;
+only the IDE calls that Gemini CLI needs are relayed. For details, see
+[Using with sandboxing](../ide-integration/index.md#using-with-sandboxing).
+
 **Quick setup:**
 
 To enable Docker sandboxing, run Gemini CLI with the sandbox flag and specify
@@ -220,6 +228,14 @@ To set up runsc:
 2.  Configure the Docker daemon to use the runsc runtime.
 3.  Verify the installation.
 
+gVisor gives the container its own user-space network stack, so services bound
+to your host's loopback interface aren't reachable from inside the sandbox, even
+with `--network host`. Gemini CLI's IDE integration doesn't rely on container
+networking: the host process bridges the connection over `docker exec` (see
+[Using with sandboxing](../ide-integration/index.md#using-with-sandboxing)). If
+you configure the `runsc` runtime with `--network=none`, the sandboxed CLI has
+no external network access at all and can't reach the Gemini API.
+
 ### 5. LXC/LXD (Linux only, experimental)
 
 Full-system container sandboxing using LXC/LXD. Unlike Docker/Podman, LXC
@@ -437,6 +453,14 @@ $env:SANDBOX_SET_UID_GID="false"  # Disable UID/GID mapping
 - Check sandbox profile allows network.
 - Verify proxy configuration.
 
+**IDE integration doesn't connect**
+
+- Inside a container sandbox, the connection is bridged by the host process when
+  the sandbox starts. Make sure the IDE companion extension is running, then
+  restart Gemini CLI from the IDE's integrated terminal.
+- Run with `DEBUG=1` and look for `[IdeBridge]` messages. See
+  [Using with sandboxing](../ide-integration/index.md#using-with-sandboxing).
+
 ### Debug mode
 
 ```bash

package/dist/docs/ide-integration/index.md

@@ -214,12 +214,22 @@ If you are using Gemini CLI within a sandbox, be aware of the following:
 - **On macOS:** The IDE integration requires network access to communicate with
   the IDE companion extension. You must use a Seatbelt profile that allows
   network access.
-- **In a Docker container:** If you run Gemini CLI inside a Docker (or Podman)
-  container, the IDE integration can still connect to the VS Code extension
-  running on your host machine. The CLI is configured to automatically find the
-  IDE server on `host.docker.internal`. No special configuration is usually
-  required, but you may need to ensure your Docker networking setup allows
-  connections from the container to the host.
+- **In a container sandbox (Docker, Podman, or gVisor/runsc):** IDE integration
+  works, but not over the network. The companion extension's server listens only
+  on your host's loopback interface and requires an authentication token that is
+  never passed into the container. Instead, Gemini CLI on the host bridges the
+  connection for you: it connects to the extension itself and relays the IDE
+  calls into the container over `docker exec` (or `podman exec`), using a Unix
+  socket inside the container. The bridge doesn't depend on container
+  networking, so it also works with gVisor's isolated network stack. Only
+  `openDiff` and `closeDiff` for files inside your IDE workspace, and the IDE
+  context updates, are relayed. For the bridge to be set up, the extension must
+  be running when you start Gemini CLI, and the sandbox image must provide
+  `node` (the default image does).
+- **In a dev container or Remote - SSH session:** IDE integration connects
+  directly, because the extension host and Gemini CLI share the same loopback
+  interface.
+- **With LXC/LXD:** IDE integration isn't available from inside an LXC sandbox.
 
 ## Troubleshooting
 
@@ -240,6 +250,20 @@ If you are using Gemini CLI within a sandbox, be aware of the following:
     2.  Open a new terminal window in your IDE to ensure it picks up the correct
         environment.
 
+- **Message:**
+  `🔴 Disconnected: Failed to connect to IDE companion extension in [IDE Name]. Gemini CLI is running inside a sandbox: make sure the extension is installed and running in your IDE, then restart Gemini CLI so the sandbox can bridge the connection.`
+
+  - **Cause:** Gemini CLI is running inside a container sandbox and the host
+    couldn't bridge the connection, usually because the extension wasn't running
+    when the sandbox started.
+  - **Solution:**
+    1.  Make sure the **Gemini CLI Companion** extension is enabled and shows as
+        running in your IDE.
+    2.  Quit Gemini CLI and start it again from the IDE's integrated terminal.
+        The bridge is set up when the sandbox starts.
+    3.  If the problem continues, start Gemini CLI with `DEBUG=1` and look for
+        `[IdeBridge]` messages before the UI appears.
+
 - **Message:**
   `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable`
   - **Cause:** The connection to the IDE companion was lost.

package/dist/src/agents/registry.js

@@ -133,51 +133,54 @@ export class AgentRegistry {
         }
         this.loadBuiltInAgents();
         // Load project-level agents: .gemini/agents/ (relative to Project Root)
-        const folderTrustEnabled = this.config.getFolderTrust();
-        const isTrustedFolder = this.config.isTrustedFolder();
-        if (!folderTrustEnabled || isTrustedFolder) {
-            const projectAgentsDir = this.config.storage.getProjectAgentsDir();
-            const projectAgents = await loadAgentsFromDirectory(projectAgentsDir);
-            for (const error of projectAgents.errors) {
-                const msg = `Agent loading error: ${error.message}`;
-                errors?.push(msg);
-                coreEvents.emitFeedback('error', msg);
-            }
-            const ackService = this.config.getAcknowledgedAgentsService();
-            const projectRoot = this.config.getProjectRoot();
-            const unacknowledgedAgents = [];
-            const agentsToRegister = [];
-            for (const agent of projectAgents.agents) {
-                this.ensureRemoteAgentHash(agent);
-                if (!agent.metadata?.hash) {
-                    agentsToRegister.push(agent);
-                    continue;
+        // Skip if the workspace is the user's home directory to avoid loading global agents twice
+        if (!this.config.storage.isWorkspaceHomeDir()) {
+            const folderTrustEnabled = this.config.getFolderTrust();
+            const isTrustedFolder = this.config.isTrustedFolder();
+            if (!folderTrustEnabled || isTrustedFolder) {
+                const projectAgentsDir = this.config.storage.getProjectAgentsDir();
+                const projectAgents = await loadAgentsFromDirectory(projectAgentsDir);
+                for (const error of projectAgents.errors) {
+                    const msg = `Agent loading error: ${error.message}`;
+                    errors?.push(msg);
+                    coreEvents.emitFeedback('error', msg);
                 }
-                const isAcknowledged = await ackService.isAcknowledged(projectRoot, agent.name, agent.metadata.hash);
-                if (isAcknowledged) {
-                    agentsToRegister.push(agent);
+                const ackService = this.config.getAcknowledgedAgentsService();
+                const projectRoot = this.config.getProjectRoot();
+                const unacknowledgedAgents = [];
+                const agentsToRegister = [];
+                for (const agent of projectAgents.agents) {
+                    this.ensureRemoteAgentHash(agent);
+                    if (!agent.metadata?.hash) {
+                        agentsToRegister.push(agent);
+                        continue;
+                    }
+                    const isAcknowledged = await ackService.isAcknowledged(projectRoot, agent.name, agent.metadata.hash);
+                    if (isAcknowledged) {
+                        agentsToRegister.push(agent);
+                    }
+                    else {
+                        unacknowledgedAgents.push(agent);
+                    }
                 }
-                else {
-                    unacknowledgedAgents.push(agent);
+                if (unacknowledgedAgents.length > 0) {
+                    coreEvents.emitAgentsDiscovered(unacknowledgedAgents);
                 }
+                await Promise.allSettled(agentsToRegister.map(async (agent) => {
+                    try {
+                        await this.registerAgent(agent, errors);
+                    }
+                    catch (e) {
+                        const msg = `Error registering project agent "${agent.name}": ${e instanceof Error ? e.message : String(e)}`;
+                        debugLogger.warn(`[AgentRegistry] ${msg}`, e);
+                        errors?.push(msg);
+                        coreEvents.emitFeedback('error', msg);
+                    }
+                }));
             }
-            if (unacknowledgedAgents.length > 0) {
-                coreEvents.emitAgentsDiscovered(unacknowledgedAgents);
+            else {
+                coreEvents.emitFeedback('info', 'Skipping project agents due to untrusted folder. To enable, ensure that the project root is trusted.');
             }
-            await Promise.allSettled(agentsToRegister.map(async (agent) => {
-                try {
-                    await this.registerAgent(agent, errors);
-                }
-                catch (e) {
-                    const msg = `Error registering project agent "${agent.name}": ${e instanceof Error ? e.message : String(e)}`;
-                    debugLogger.warn(`[AgentRegistry] ${msg}`, e);
-                    errors?.push(msg);
-                    coreEvents.emitFeedback('error', msg);
-                }
-            }));
-        }
-        else {
-            coreEvents.emitFeedback('info', 'Skipping project agents due to untrusted folder. To enable, ensure that the project root is trusted.');
         }
         // Load user-level agents: ~/.gemini/agents/
         const userAgentsDir = Storage.getUserAgentsDir();