fix(core-tools): resolve defensive path resolution for at-reference files and fix macOS tests

[luisfelipe-alt]

Summary

This PR implements a comprehensive, defensive path resolution fix for a critical production bug where filesystem tools (read_file, replace, write_file) fail with a "File not found" error when the model passes a path prefixed with @ (e.g., @policies/new-policies.txt).

Additionally, this PR resolves macOS-specific test failures in EditTool and WriteFileTool caused by path resolution mismatches (due to the /var -> /private/var symlink on macOS), sanitizes file paths by stripping null bytes to prevent potential crash vulnerabilities, and enhances test stability by generating unique session IDs in trackerTools.test.ts.

Furthermore, this PR incorporates several critical security and robustness enhancements requested during code review, including consistent @ prefix stripping, plan-mode boundary enforcement, and test isolation improvements.

Details

We implemented a centralized, defensive path resolution utility and applied targeted, platform-aware fixes to align the test environment with the production path resolution behavior:

1. Defensive Path Resolution (packages/core/src/utils/paths.ts):

   • Implemented resolveDefensiveToolPath to strip leading @ reference prefixes if the literal path does not exist but the stripped path does.
   • Consistent @ Prefix Stripping: Updated the logic to consistently strip the @ prefix when creating new files/directories (unless a literal @-prefixed directory already exists on disk), preventing the accidental creation of literal @-prefixed folders (e.g., @src, @policies).
   • Path Alias Support: Added explicit checks for @/ and @\ prefixes to always strip the @ and leading slashes, ensuring that common path aliases are resolved correctly even when the target directory does not exist yet.
   • Null Byte Sanitization: Sanitizes file paths by stripping any null bytes (\0) at the very beginning of resolveDefensiveToolPath to prevent potential crash vulnerabilities (TypeError) in downstream synchronous file system operations.

2. Tool Integration & Hardening:

   • ReadFileTool (packages/core/src/tools/read-file.ts): Applied resolveDefensiveToolPath in both the constructor and validateToolParamValues.
   • WriteFileTool (packages/core/src/tools/write-file.ts):
     • Applied resolveDefensiveToolPath in the constructor, validateToolParamValues, and getCorrectedFileContent (simplifying and hardening the logic by calling it directly for all paths, including absolute paths).
     • Plan-Mode Boundary Enforcement: Removed the path.isAbsolute check in getCorrectedFileContent to ensure that absolute paths in plan mode do not bypass resolveAndValidatePlanPath, strictly restricting the agent to the plans directory.
     • Plan-Mode Sanitization: Sanitizes null bytes from file paths before resolving the plan path in the constructor, validation, and content correction methods to prevent resolveToRealPath from throwing errors.
   • EditTool (packages/core/src/tools/edit.ts):
     • Applied resolveDefensiveToolPath in the constructor, validateToolParamValues, and getModifyContext.
     • Null Byte Sanitization in Fallbacks: Added explicit null byte sanitization in the absolute path fallback branches (constructor, validation, and context methods) to prevent unsanitized paths from leaking downstream.
     • Plan-Mode Sanitization: Sanitizes null bytes from file paths before resolving the plan path in the constructor, validation, and context methods to prevent resolveToRealPath from throwing errors.
   • Path Corrector (packages/core/src/utils/pathCorrector.ts): Applied resolveDefensiveToolPath at the beginning of correctPath.

3. macOS Test Fixes & Test Isolation:

   • Mock Workspace Context (packages/core/src/test-utils/mockWorkspaceContext.ts): Updated createMockWorkspaceContext to resolve all input directories to their real paths using fs.realpathSync. This ensures that on macOS, any directory starting with /var/... is correctly resolved to /private/var/..., matching the behavior of the production code and fixing 30 failures in edit.test.ts and boundary failures in write-file.test.ts.
   • WriteFileTool Tests (packages/core/src/tools/write-file.test.ts):
     • Test Isolation: Declared rootDir and plansDir without static global initializers and initialized them with unique temporary directories using fs.mkdtempSync inside beforeEach to prevent race conditions and test interference during concurrent test execution.
     • Updated specific test cases to resolve expected paths to their real paths using resolveToRealPath before asserting.
   • EditTool Tests (packages/core/src/tools/edit.test.ts):
     • Resolved tempDir to its real path using fs.realpathSync in beforeEach to ensure all generated paths are fully resolved, fixing all remaining macOS path mismatches.

4. Test Stability:

   • Tracker Tools Tests (packages/core/src/tools/trackerTools.test.ts): Replaced the hardcoded sessionId: 'test-session' with a dynamically generated unique session ID using Math.random() to prevent test session leakage and concurrency issues.

5. Consolidated Test Suite (packages/core/src/tools/at-reference-resolution.test.ts):

   • Created a new consolidated test suite verifying successful path resolution, file updates, new file creation, nested subdirectory creation, path traversal blocking, and symlink loop handling across all three tools.

6. Build Script Robustness (scripts/build.js):

   • Modified the build script to use npx --no-install npm-run-all to force using the locally installed version and bypass registry/network calls, making the build script robust in corporate environments (Corp Airlock).

Related Issues

How to Validate

Step 1: Run the modified test suites on macOS

Run the following commands on a macOS machine to verify that all tests pass successfully:

npx vitest run packages/core/src/tools/edit.test.ts
npx vitest run packages/core/src/tools/write-file.test.ts
npx vitest run packages/core/src/tools/at-reference-resolution.test.ts
npx vitest run packages/core/src/tools/trackerTools.test.ts

Expected Output: All 125+ tests pass successfully with zero failures.

Step 2: Run the test suites on Linux/Windows (Regression Check)

Run the same commands on Linux or Windows to ensure zero regressions:

npx vitest run packages/core/src/tools/write-file.test.ts packages/core/src/tools/at-reference-resolution.test.ts

Expected Output: All 63 tests pass successfully with zero failures.

Step 3: Run linting and type checking

Verify that the codebase remains fully compliant with the project's engineering standards:

npm run lint && npm run typecheck

Expected Output: Zero linting or type-checking errors.

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
  • Windows
    • npm run
    • npx
  • Linux
    • npm run
    • npx

[github-actions]

📊 PR Size: size/XL

• Lines changed: 1288
• Additions: +1196
• Deletions: -92
• Files changed: 21

[luisfelipe-alt]

/gemini review

[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 introduces a robust, defensive path resolution mechanism to handle @ prefixed file paths, preventing production errors where tools fail to locate files. It also addresses platform-specific test instabilities on macOS by ensuring consistent real-path resolution and adds a new consolidated test suite to verify path handling across all filesystem tools.

Highlights

• Defensive Path Resolution: Implemented resolveDefensiveToolPath to handle @ prefixed paths and sanitize inputs by stripping null bytes, preventing potential crashes.
• macOS Test Fixes: Standardized path resolution using fs.realpathSync across test suites to resolve symlink mismatches (e.g., /var vs /private/var) on macOS.
• Tool Integration: Updated ReadFileTool, WriteFileTool, EditTool, and pathCorrector to utilize the new defensive resolution and real-path validation logic.
• Consolidated Testing: Added a comprehensive test suite for @ reference resolution and improved overall test stability by using dynamic session IDs.

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

[gemini-code-assist]

Code Review

This pull request introduces defensive path resolution and sanitization across several tools (EditTool, ReadFileTool, WriteFileTool, and pathCorrector) by implementing and utilizing resolveDefensiveToolPath and resolveToRealPath. This helps handle LLM-generated paths safely, stripping null bytes and reference prefixes (like @), and resolving symlinks. Corresponding tests have been updated or added to verify these behaviors. The reviewer pointed out a potential vulnerability in packages/core/src/tools/edit.ts where a fallback branch for absolute paths could leak unsanitized null bytes if resolveToRealPath throws an error, and suggested sanitizing the path before fallback.

[gemini-code-assist]

Code Review

This pull request introduces defensive path resolution and sanitization (such as stripping null bytes and handling '@' prefixes) across the EditTool, ReadFileTool, and WriteFileTool to prevent path traversal and ensure safe workspace access. The review feedback highlights a critical edge case where paths like @/ or @\ can resolve to the workspace root, and points out an inconsistency in stripping the @ prefix when creating new directories, which could lead to the accidental creation of literal @-prefixed folders. Suggestions were provided to consistently strip the prefix and update the corresponding tests.

[luisfelipe-alt]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces defensive path resolution and sanitization across several tools (EditTool, ReadFileTool, WriteFileTool) and utilities. It implements resolveDefensiveToolPath to strip null bytes and handle @ reference prefixes safely, and resolves paths to their real paths using resolveToRealPath to prevent path traversal vulnerabilities and handle symlinks gracefully. The review feedback highlights that in write-file.test.ts, rootDir and plansDir are declared as module-level variables with static paths, which can cause race conditions and test interference during concurrent test execution. The reviewer suggests initializing these variables with unique temporary directories inside beforeEach to ensure proper test isolation.

[luisfelipe-alt]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces defensive path resolution and sanitization across various tools (Edit, ReadFile, WriteFile) to prevent path traversal and null byte injection vulnerabilities, notably by implementing resolveDefensiveToolPath and resolving paths to their real paths. It also adds comprehensive tests for at-reference path resolution, null byte sanitization, and symlink loops. The feedback highlights an inconsistency in packages/core/src/tools/write-file.ts where absolute paths are not sanitized using resolveDefensiveToolPath in getCorrectedFileContent, and suggests simplifying this by calling the sanitization function directly.

[luisfelipe-alt]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces defensive path resolution and sanitization across file tools (such as edit, read, and write tools) to prevent path traversal, null byte injection, and accidental creation of literal '@'-prefixed directories. The feedback highlights several locations in plan-mode resolution within edit.ts and write-file.ts where raw file paths containing null bytes could still cause resolveToRealPath to throw errors, recommending that these paths be sanitized before resolving the plan path.

[DavidAPierce]

Overall, LGTM, however there are some test failures. Here's a breakdown of the Mac os failures and a potential way forward with them:

Root Cause

The test failures occur because of a prefix mismatch when verifying path
ownership in test environments on macOS. On macOS, the temporary directory
/var is a symbolic link to /private/var.

1. Path Generation: The test suite creates a temporary directory using the
   fsPromises.mkdtemp function. This returns a path beginning with /var/....
2. Canonical Real Path Resolution: Under the changes introduced in this PR,
   core tools resolve paths to their canonical real paths. Specifically,
   GlobTool resolves search directories using fs.realpathSync. This converts
   the directory path from /var/... to /private/var/....
3. Prefix Validation Failure: The test suite implements verification in
   isPathAllowed using a direct startsWith check:

   const directories = workspaceContext.getDirectories(); // returns ['/var/folders/...']
   if (directories.some((dir) => absolutePath.startsWith(dir))) { ... }

   Because absolutePath is /private/var/... (canonical) and dir is
   /var/... (unresolved), the prefix match fails.
4. Bypassed Debug Messages: Due to this permission failure, GlobTool
   raises an access error. This error is caught by the catch block in
   handleAtCommand rather than generating the expected debug message:

   `Glob search for '**/*nonexistent.txt*' found no files or an error. Path nonexistent.txt will be skipped.`

   As a result, the test assertion for mockOnDebugMessage fails.

Solution

To resolve this issue, you must update the test setup so that all generated
temporary directories are resolved to their canonical real paths before storing
them.

Apply the following modifications to atCommandProcessor.test.ts:

1. In the first beforeEach block (around line 66):

   const rawTestRootDir = await fsPromises.mkdtemp(
     path.join(os.tmpdir(), "folder-structure-test-"),
   );
   testRootDir = await fsPromises.realpath(rawTestRootDir);

2. In the it("should resolve files in multiple workspace directories") test (around line 1470):

   const rawSecondRootDir = await fsPromises.mkdtemp(
     path.join(os.tmpdir(), "second-root-"),
   );
   const secondRootDir = await fsPromises.realpath(rawSecondRootDir);

3. In the describe("checkPermissions") beforeEach block (around line 1652):

   const rawTestRootDir = await fsPromises.mkdtemp(
     path.join(os.tmpdir(), "check-permissions-test-"),
   );
   testRootDir = await fsPromises.realpath(rawTestRootDir);

Converting temporary paths using realpath ensures that they consistently begin
with the /private prefix on macOS, aligning the test assertions with the
canonical resolutions of the core tools.

Once these tests are passing, we're good to LGTM and merge.

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'.

This PR will be closed in 7 days if it remains without that designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding.

[luisfelipe-alt]

Overall, LGTM, however there are some test failures. Here's a breakdown of the Mac os failures and a potential way forward with them:

Root Cause

The test failures occur because of a prefix mismatch when verifying path ownership in test environments on macOS. On macOS, the temporary directory /var is a symbolic link to /private/var.
...

The complete suite of unit tests for the others shard was executed on a macOS environment to validate compatibility and ensure the correct resolution of temporary directories and symbolic links.
Command executed:

npm run test:ci --workspace "@google/gemini-cli-core" --workspace "@google/gemini-cli-a2a-server" --workspace "gemini-cli-vscode-ide-companion" --workspace  "@google/gemini-cli-test-utils" --if-present -- --overage.enabled=false >> mac-ci-test_04.txt 2>> mac-ci-test_04.txt

Execution Results (Sanitized):

* **`@google/gemini-cli-core`**:

RUN  v3.2.4 <WORKSPACE_ROOT>/packages/core
   Test Files  402 passed | 1 skipped (403)
        Tests  7667 passed | 50 skipped (7717)
     Duration  44.33s

* **`@google/gemini-cli-a2a-server`**:
   RUN  v3.1.1 <WORKSPACE_ROOT>/packages/a2a-server
   Test Files  14 passed (14)
        Tests  138 passed (138)
     Duration  3.53s

* **`gemini-cli-vscode-ide-companion`**:
   RUN  v3.2.4 <WORKSPACE_ROOT>/packages/vscode-ide-companion
   Test Files  3 passed (3)
        Tests  40 passed | 1 skipped (41)
     Duration  1.98s

Conclusion: 100% of the executed tests completed successfully. No failures or regressions were detected in the macOS environment.

The following output is only to show how I verified no errors in Mac environment:

$ grep -E "Test Files.*passed" mac-ci-test_04.txt
 Test Files  402 passed | 1 skipped (403)
 Test Files  14 passed (14)
 Test Files  3 passed (3)
$ grep -E "Test Files.*failed" mac-ci-test_04.txt
$ 

Next steps

@DavidAPierce , I am working to fix the other tests failing in the Mac environment detected in GitHub Pipeline. I will try to validate all CI suites before the next round of code review and I will add a comment with the details about how I verified that.

[luisfelipe-alt]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces defensive path resolution and sanitization across multiple tools (Edit, Glob, Grep, ReadFile, RipGrep, and WriteFile) and utilities. It implements resolveDefensiveToolPath to strip null bytes and handle @ prefixes safely, and consistently resolves paths to their real paths using resolveToRealPath to prevent issues with symlinks. Test suites have been updated to reflect these changes, and a new consolidated test suite for At-Reference path resolution has been added. I have no feedback to provide as there are no review comments.

_{Note: Security Review did not run due to the size of the PR.}

[luisfelipe-alt]

I have completed the changes, and I ran the following commands in a Mac in order to validate them:

# 1. Clear or create the results file
> mac-results.txt

# 2. Run the CLI shard tests (where the current failure is)
echo "=== RUNNING CLI SHARD TESTS ===" >> mac-results.txt
LANG=en_US.UTF-8 npm run test:ci --workspace "@google/gemini-cli" -- --coverage.enabled=false  >> mac-results.txt 2>&1

# 3. Run the OTHERS shard tests (where the previous failures were)
echo "=== RUNNING OTHERS SHARD TESTS ===" >> mac-results.txt
LANG=en_US.UTF-8 npm run test:ci --workspace "@google/gemini-cli-core" --workspace "@google/gemini-cli-a2a-server" --workspace "gemini-cli-vscode-ide-companion" --workspace "@google/gemini-cli-test-utils" --if-present -- --coverage.enabled=false  >> mac-results.txt 2>&1

# 4. Run the scripts tests
echo "=== RUNNING SCRIPTS TESTS ===" >> mac-results.txt
LANG=en_US.UTF-8 npm run test:scripts --  >> mac-results.txt 2>&1

# 5. Validation
npm run lint >> mac-results.txt 2>&1
npm run typecheck >> mac-results.txt 2>&1

I have validated the success of the changes:

$ grep -E "Test Files.*passed" mac-results.txt 
 Test Files  463 passed (463)
 Test Files  402 passed | 1 skipped (403)
 Test Files  14 passed (14)
 Test Files  3 passed (3)
 Test Files  11 passed (11)
$ grep -E "Test Files.*failed" mac-results.txt 
$ 

@DavidAPierce , the PR is ready for the next round of code review.

[github-actions]

✅ 70 tests passed successfully on gemini-3-flash-preview.

🧠 Model Steering Guidance

This PR modifies files that affect the model's behavior (prompts, tools, or instructions).

• ⚠️ Consider adding Evals: No behavioral evaluations (evals/*.eval.ts) were added or updated in this PR. Consider adding a test case to verify the new behavior and prevent regressions.

---

This is an automated guidance message triggered by steering logic signatures.