feat(plan): enforce strict read-only policy and halt execution on violation

[jerop]

Summary

This PR refines the experimental Plan Mode by implementing a strict "secure-by-default" policy that allows only read and search operations. It also enhances the tool scheduler to immediately halt agent execution if a prohibited tool is attempted, preventing retry loops and providing clear guidance to the user.

Closes #16625

Details

Policy Implementation

• Introduced packages/core/src/policy/policies/plan.toml with a default-deny rule for all tools in Plan mode.
• Explicitly allow-listed read and search tools (read_file, web_fetch, google_web_search, etc.) only.

Execution Control

• Updated CoreToolScheduler to return a STOP_EXECUTION error type when a tool is denied in Plan mode.
• This triggers the existing "Stop" logic in the agent loop, preventing the model from retrying the same blocked action.

How to Validate

1. Build the project:

   npm run build

2. Run in Plan Mode:

   # Ensure experimental.plan is enabled in your settings
   npm start -- --approval-mode=plan 

3. Attempt a Write Operation:

   • Ask: "Create a new file called test.txt"
   • Expected: The agent stops immediately with the error: "Tool execution denied by policy. You are in Plan Mode - adjust your prompt to only use read and search tools."

4. Attempt a Read Operation:

   • Ask: "Read package.json"
   • Expected: The tool executes successfully.

Pre-Merge Checklist

• Updated relevant documentation and README (Self-documenting policy files)
• Added/updated tests (Integration and Unit tests added)
• Noted breaking changes (None, Plan mode is experimental)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
  • Linux

[github-actions]

Size Change: +375 B (0%)

Total Size: 23.1 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	23.1 MB	+375 B (0%)
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB	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-closed.sb	3.29 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

_{compressed-size-action}

[jacob314]