fix(core): expose GEMINI_PLANS_DIR to hook environment

[Adib234]

Summary

Fixes a regression where hook scripts intercepting exit_plan_mode could no longer determine the absolute path to the plan file. This occurred because PR #22737 changed the plan_path argument to plan_filename.

Details

Following user steering, this PR:

1. Exposes GEMINI_PLANS_DIR: Modified HookRunner to inject the absolute path of the plans directory into the environment of all command hooks.
2. Updates Documentation:
   • Adds GEMINI_PLANS_DIR to the list of provided environment variables in docs/hooks/index.md.
   • Updates the archive-plan.sh example in docs/cli/plan-mode.md to show how to reconstruct the plan path using the new environment variable and the existing plan_filename input.
3. Strengthens Tests: Added unit tests to HookRunner to verify the presence of GEMINI_PLANS_DIR in spawned processes.

This approach keeps the tool interface stable while providing necessary context to external scripts through the execution harness.

Related Issues

Closes #25054

How to Validate

1. Unit Tests:

   npm test -w @google/gemini-cli-core -- src/hooks/hookRunner.test.ts

2. Manual Verification:
   Configure a hook for exit_plan_mode that echoes $GEMINI_PLANS_DIR to verify it's correctly populated.

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-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 addresses a regression where hook scripts could no longer determine the absolute path to plan files due to a previous change in argument naming. By injecting the absolute path of the plans directory into the hook environment, external scripts can now reliably locate and process plan artifacts. The changes also include necessary documentation updates and expanded test coverage to ensure stability.

Highlights

• Environment Variable Exposure: Exposed the GEMINI_PLANS_DIR environment variable to all command hooks via the HookRunner to ensure scripts can reliably locate plan files.
• Documentation Updates: Updated documentation to include GEMINI_PLANS_DIR in the environment variable list and revised the archive-plan.sh example to correctly reconstruct plan paths.
• Testing: Added unit tests to HookRunner to verify that GEMINI_PLANS_DIR is correctly injected into the environment of spawned processes.

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: +468 B (0%)

Total Size: 34.1 MB

Filename	Size	Change
./bundle/chunk-5MTPIP2P.js	0 B	-14.8 MB (removed)	🏆
./bundle/chunk-DEIUXSN4.js	0 B	-3.8 kB (removed)	🏆
./bundle/chunk-IKQTM5SS.js	0 B	-3.16 MB (removed)	🏆
./bundle/core-3PWJQDRU.js	0 B	-46.2 kB (removed)	🏆
./bundle/devtoolsService-7M2QBO5S.js	0 B	-28.4 kB (removed)	🏆
./bundle/gemini-CKDWSP6B.js	0 B	-552 kB (removed)	🏆
./bundle/interactiveCli-LSIIXZ22.js	0 B	-1.66 MB (removed)	🏆
./bundle/oauth2-provider-M2XK32PX.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-5WAAPGLA.js	3.16 MB	+3.16 MB (new file)	🆕
./bundle/chunk-B3EFB7BU.js	3.8 kB	+3.8 kB (new file)	🆕
./bundle/chunk-KPBJO235.js	14.8 MB	+14.8 MB (new file)	🆕
./bundle/core-EFVU2SKZ.js	46.2 kB	+46.2 kB (new file)	🆕
./bundle/devtoolsService-ENGAN4NS.js	28.4 kB	+28.4 kB (new file)	🆕
./bundle/gemini-QVOHPSPW.js	552 kB	+552 kB (new file)	🆕
./bundle/interactiveCli-KNP5DB6V.js	1.66 MB	+1.66 MB (new file)	🆕
./bundle/oauth2-provider-ZCMCUSWH.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-IUUIT4SU.js	56.5 kB	0 B
./bundle/chunk-P52CHEF3.js	1.96 MB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/cleanup-QDGW7GB4.js	0 B	-932 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-23MICZEL.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-IIJ4OC7U.js	932 B	+932 B (new file)	🆕

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces the GEMINI_PLANS_DIR environment variable for hooks, updating the hook runner, associated tests, and documentation. It also standardizes the casing of terms like 'plan mode' throughout the documentation. Feedback includes a security recommendation to sanitize filenames in a documentation bash example using basename to prevent path traversal. Additionally, the extensive changes to package-lock.json should be reverted to avoid lockfile pollution and adhere to the repository's focus on small, targeted pull requests.

[jerop]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the GEMINI_PLANS_DIR environment variable to the hook execution environment, updating the documentation, HookRunner implementation, and associated tests. Feedback indicates a potential command injection vulnerability because the new variable is not properly escaped during command expansion. Furthermore, the implementation is currently missing the GEMINI_SESSION_ID and GEMINI_CWD variables that are already documented as part of the hook environment, and the test suite should be updated to include these for full coverage.