fix(sandbox): centralize async git worktree resolution and enforce read-only security

[ehedlund]

Summary

Centralizes Git Worktree resolution to be asynchronous and strictly enforces read-only access across all sandboxes to prevent RCE vulnerabilities via git hooks.

Details

This PR refactors how we handle Git Worktrees inside the sandbox and addresses critical security feedback:

• Centralized & Async Resolution: Migrated resolveGitWorktreePaths to use node:fs/promises and moved it into the core resolveSandboxPaths step, eliminating redundant synchronous resolution across OS builders.
• Path Cleanup: Removed local tryRealpath implementations in favor of the shared resolveToRealPath utility.
• Enforced Read-Only Security:
  • macOS (seatbelt): Removed unconditional file-write* access for git worktree directories, granting only file-read* to prevent malicious hook modification.
  • Linux (bwrap): Replaced conditional write binding with unconditional --ro-bind-try (read-only).
  • Windows: Added explicit documentation and test assertions to ensure Low Integrity (write) access is not granted to git worktrees, relying on Windows' default read inheritance.
• Testing: Added extensive unit and integration tests verifying read access is permitted while write access to external worktree directories is strictly blocked.

Related Issues

How to Validate

1. Run the core integration tests: npm run test -w @google/gemini-cli-core -- src/services/sandboxManager.integration.test.ts
2. Test using a git worktree setup that the CLI successfully runs read-only git operations but blocks modifications to the worktree's .git files.

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 @ehedlund, 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 sandbox manager by centralizing Git worktree resolution and extending its support to Windows. By consolidating the worktree logic into a single, asynchronous step, the change improves maintainability and ensures consistent behavior across operating systems. This also addresses a previous gap by enabling proper sandboxing for Git worktrees on Windows, alongside updates to Linux and macOS builders to leverage this unified approach.

Highlights

• Centralized Git Worktree Resolution: The logic for resolving Git worktree paths has been centralized into a shared resolveSandboxPaths step, improving consistency and maintainability across different sandbox managers.
• Windows Git Worktree Support: Comprehensive support for Git worktrees has been added to the Windows sandbox manager, including the necessary Low Integrity access grants to ensure proper functionality.
• Asynchronous File System Operations: The resolveGitWorktreePaths function has been refactored to be fully asynchronous, utilizing node:fs/promises for improved performance and non-blocking I/O.
• Unified Path Resolution Utility: All local implementations of tryRealpath have been replaced with a single, shared resolveToRealPath utility, streamlining path resolution logic.
• Sandbox Builder Updates: Linux (bwrap) and macOS (seatbelt) sandbox builders have been updated to consume the newly centralized Git worktree paths from ResolvedSandboxPaths.
• Enhanced Testing: New unit and integration tests have been introduced to thoroughly validate Git worktree functionality across all supported platforms.

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.

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. ↩

[github-actions]

Size Change: -60 B (0%)

Total Size: 34 MB

Filename	Size	Change
./bundle/chunk-5QDCNTKY.js	0 B	-3.47 kB (removed)	🏆
./bundle/chunk-BEZVRD5X.js	0 B	-3.16 MB (removed)	🏆
./bundle/chunk-PCRMHXG3.js	0 B	-14.8 MB (removed)	🏆
./bundle/core-P2XNJBEN.js	0 B	-45.6 kB (removed)	🏆
./bundle/devtoolsService-BIH77Y6P.js	0 B	-28.4 kB (removed)	🏆
./bundle/gemini-PEVHKVMZ.js	0 B	-552 kB (removed)	🏆
./bundle/interactiveCli-4CAMGVG7.js	0 B	-1.66 MB (removed)	🏆
./bundle/oauth2-provider-L7FNVSJ5.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-2DIZBDVH.js	3.16 MB	+3.16 MB (new file)	🆕
./bundle/chunk-KSKCLAWV.js	3.47 kB	+3.47 kB (new file)	🆕
./bundle/chunk-KVKX6KD4.js	14.8 MB	+14.8 MB (new file)	🆕
./bundle/core-I766MSGC.js	45.6 kB	+45.6 kB (new file)	🆕
./bundle/devtoolsService-DPRTLPDX.js	28.4 kB	+28.4 kB (new file)	🆕
./bundle/gemini-QPW74JNH.js	552 kB	+552 kB (new file)	🆕
./bundle/interactiveCli-6BD5R3GY.js	1.66 MB	+1.66 MB (new file)	🆕
./bundle/oauth2-provider-MVYAORRI.js	9.16 kB	+9.16 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size	Change
./bundle/bundled/third_party/index.js	8 MB	0 B
./bundle/chunk-34MYV7JD.js	2.45 kB	0 B
./bundle/chunk-5AUYMPVF.js	858 B	0 B
./bundle/chunk-5PS3AYFU.js	1.18 kB	0 B
./bundle/chunk-664ZODQF.js	124 kB	0 B
./bundle/chunk-DAHVX5MI.js	206 kB	0 B
./bundle/chunk-ETSDHTGW.js	1.96 MB	0 B
./bundle/chunk-IUUIT4SU.js	56.5 kB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/cleanup-6LOTO6NL.js	0 B	-856 B (removed)	🏆
./bundle/devtools-36NN55EP.js	696 kB	0 B
./bundle/dist-T73EYRDX.js	356 B	0 B
./bundle/events-XB7DADIJ.js	418 B	0 B
./bundle/gemini.js	4.97 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/memoryDiscovery-YL35JRSL.js	980 B	0 B
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	222 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	229 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	13.4 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/cleanup-3AJM62IL.js	856 B	+856 B (new file)	🆕

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request refactors git worktree and submodule path resolution across Linux, macOS, and Windows sandboxes by centralizing the logic in resolveSandboxPaths and adopting asynchronous file system operations. The tryRealpath utility has been replaced with resolveToRealPath from the shared paths utility. Feedback identifies critical security vulnerabilities in the macOS and Windows implementations where granting write access to git directories could enable Remote Code Execution via malicious git hooks. Additionally, test assertions for the Linux sandbox should be updated to reflect read-write mounting for these paths to ensure consistency with the intended sandbox policy.

[scidomino]

Approved but Gemini pointed out this edge case. Address it if you feel like it:

1. macOS (seatbeltArgsBuilder.ts):
   Currently, the PR adds (allow file-read* (subpath ...)) for the worktree paths. However, Seatbelt rules are additive and evaluated in order. If a user explicitly allows write access to a parent directory of the worktree via policyAllowed, the write access will cascade to the worktree .git directory.
   Suggestion: Similar to how GOVERNANCE_FILES are handled, consider appending an explicit (deny file-write* (subpath ...)) for worktreeGitDir and mainGitDir at the bottom of the profile to make the read-only enforcement bulletproof against policy overrides.

2. Linux (bwrapArgsBuilder.ts):
   The --ro-bind-try for git worktrees is pushed to bwrapArgs before policyAllowed and policyWrite bindings. Because bwrap processes mounts in order (later mounts overlay earlier ones), a broad write policy for a parent directory will override the read-only bind of the git directory.
   Suggestion: Consider moving the gitWorktree read-only binds closer to the end of the argument list (near the forbidden paths logic) to guarantee they cannot be overridden by broad write policies.

[DavidAPierce]

LGTM + CLI Review:

Review Summary
This PR significantly enhances the security of the sandbox environments (macOS, Linux, and Windows) by centralizing the resolution of Git worktree paths and enforcing strict read-only access to these directories. This is
a critical security fix aimed at preventing Remote Code Execution (RCE) via malicious git hooks. The refactoring also improves performance by making path resolution asynchronous.

---

Detailed Findings

1. Correctness & Security

• RCE Mitigation: The core improvement is the switch from file-write* to file-read* (or equivalent) for git worktree directories. By ensuring that the sandboxed agent cannot modify .git/hooks or .git/config in a
  worktree, the PR effectively closes a potential RCE vector.
• Asynchronous I/O: The refactoring of resolveGitWorktreePaths to use node:fs/promises is a welcome change, preventing event-loop blocking during sandbox initialization.
• Bidirectional Link Verification: The addition of a security check to verify the bidirectional link between the .git file and the gitdir in the worktree is excellent. This prevents an attacker from "tricking" the
  sandbox into granting read access to arbitrary directories by crafting a fake .git file.

2. Maintainability & Readability

• Centralized Logic: Moving the git worktree resolution into the shared resolveSandboxPaths (in sandboxManager.ts) ensures that all platforms (macOS, Linux, Windows) use a consistent set of pre-resolved paths, reducing
  duplication and potential bugs in platform-specific builders.
• Utility Standardization: Replacing multiple local implementations of tryRealpath with a shared resolveToRealPath utility improves codebase consistency.
• Clear Intent: The comments added across bwrapArgsBuilder.ts, seatbeltArgsBuilder.ts, and WindowsSandboxManager.ts clearly explain why read-only access is enforced (to prevent RCE).

3. Testability

• Comprehensive Coverage: The PR includes high-quality unit tests for the new async logic in fsUtils.test.ts and platform-specific builders.
• Integration Testing: The new integration tests in sandboxManager.integration.test.ts are particularly strong, as they empirically verify that:
  • Git worktree files are still readable within the sandbox.
  • Attempts to write to git worktree directories are blocked, even when "YOLO" mode (full workspace write access) is enabled.

---

Improvements & Suggestions

• Logic Simplification (Minor): In packages/core/src/services/sandboxManager.ts, the code for creating the gitWorktree object can be slightly more concise, though the current implementation is perfectly clear.
• Windows ACLs: The Windows implementation correctly skips grantLowIntegrityAccess for git worktrees, which effectively keeps them read-only for the sandboxed process. This is a clever and idiomatic use of the Windows
  integrity system.

Conclusion
Recommendation: Approved.

The changes are architecturally sound, well-tested, and significantly improve the security posture of the Gemini CLI. The transition to async path resolution is also a great performance win.