feat(core): implement model-driven parallel tool scheduler

[abhipatel12]

Summary

This PR implements a robust, model-driven parallel tool scheduler by introducing a wait_for_previous parameter to all tool schemas. It shifts concurrency control from hardcoded tool categories (Kinds) to explicit model intent, allowing tools to batch into parallel waves by default unless the model flags a tool to act as a sequential barrier.

Details

• Scheduler Batching: The _isParallelizable method in Scheduler now checks request.args?.wait_for_previous. If omitted or false, tools execute concurrently.
• Schema Injection: DeclarativeTool now universally injects the wait_for_previous parameter into tool schemas (via addWaitForPreviousParameter).
• Prompt Refinement: System instructions regarding tool usage have been updated to explicitly instruct the model on how to parallelize reads, independent shell commands, and independent file edits, while forbidding parallel edits to the SAME file.
• Testing Coverage: Unit tests in scheduler.test.ts have been updated/added to ensure the new batching logic handles both parallel waves and sequential barriers correctly.

Related Issues

How to Validate

1. Start the CLI in interactive mode: npm start
2. Run the following prompt which explicitly requires sequential execution (an edit followed by a read):

In a single turn, I want you to write a script that writes a random number between 1 and 10 and writes it to random-num.md in the cwd, and a cat shell command that reads that file to tell me what the number was. Remember, I want these two tool calls in the same turn/batch.

3. Ensure the tool calls execute sequentially, and the second tool correctly reads the output created by the first.

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 significantly enhances the tool scheduling mechanism by shifting concurrency control from hardcoded tool categories to explicit model intent. By introducing a wait_for_previous parameter, tools can now be batched for parallel execution by default, with the model explicitly flagging tools that require sequential execution. This change provides greater flexibility and control over tool execution flow, improving efficiency and preventing race conditions, particularly for file operations.

Highlights

• Model-Driven Concurrency Control: Introduced a wait_for_previous boolean parameter to all tool schemas, enabling the model to explicitly control whether a tool should wait for prior tools to complete or run in parallel.
• Scheduler Logic Update: The Scheduler's parallelization logic was refactored to evaluate the wait_for_previous parameter in tool requests, defaulting to parallel execution if the parameter is omitted or false.
• Universal Schema Injection: Modified DeclarativeTool to automatically inject the wait_for_previous parameter into all tool schemas, ensuring its availability for all tools.
• Prompt Refinement for Model Guidance: Updated system prompts with explicit instructions for models on how to utilize wait_for_previous for parallel reads, independent shell commands, and file edits, while strictly forbidding parallel edits to the same file.
• Enhanced Test Coverage: Expanded unit tests for the scheduler to thoroughly validate both parallel and sequential tool execution scenarios based on the new wait_for_previous parameter.

Changelog

• packages/core/src/agents/subagent-tool-wrapper.test.ts
  • Updated the expected tool schema in tests to include the new wait_for_previous boolean parameter.
• packages/core/src/core/snapshots/prompts.test.ts.snap
  • Updated prompt snapshots to reflect new guidelines for parallelism, sequencing with wait_for_previous, and explicit rules against parallel edits to the same file.
• packages/core/src/prompts/snippets.ts
  • Modified renderOperationalGuidelines to incorporate detailed instructions on tool parallelism, sequential execution using wait_for_previous, and a warning about concurrent file edits.
• packages/core/src/scheduler/scheduler.test.ts
  • Modified a test request (req2) to explicitly set wait_for_previous: true for sequential execution testing.
• packages/core/src/scheduler/scheduler.ts
  • Removed the Kind enum import, indicating a shift away from kind-based parallelization.
  • Refactored the _isParallelizable method to evaluate tool requests based on the wait_for_previous argument, defaulting to parallel if the argument is absent.
• packages/core/src/scheduler/scheduler_parallel.test.ts
  • Updated a test request (req3) to include wait_for_previous: true.
  • Added new test cases to verify parallel execution when wait_for_previous is false and sequential execution when it is true, even for read-only tools.
• packages/core/src/tools/mcp-client.test.ts
  • Updated a test schema to include the wait_for_previous parameter.
• packages/core/src/tools/mcp-tool.test.ts
  • Modified a test to assert that the wait_for_previous parameter is correctly injected into the tool schema.
• packages/core/src/tools/tool-registry.test.ts
  • Updated a test to verify that the wait_for_previous parameter is present in registered tool schemas.
• packages/core/src/tools/tools.ts
  • Introduced a isSchemaObject type guard for schema validation.
  • Implemented addWaitForPreviousParameter method within DeclarativeTool to dynamically inject the wait_for_previous boolean parameter into all tool schemas.

Activity

• The author has implemented a new model-driven parallel tool scheduler.
• The author has updated system instructions to guide the model on parallel and sequential tool usage.
• Unit tests have been updated and added to cover the new batching logic and wait_for_previous parameter.
• The author has validated the changes on MacOS using npm run.
• The author has updated relevant documentation and README (if needed) and added/updated tests.

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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

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: +2.1 kB (+0.01%)

Total Size: 26.6 MB

Filename	Size	Change
./bundle/gemini.js	26.1 MB	+2.1 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request implements a model-driven parallel tool scheduler by introducing a wait_for_previous parameter, which is a solid architectural improvement for concurrency control. However, it introduces a significant security risk by defaulting to parallel execution for all tools, including those that modify the system state, shifting the responsibility for preventing race conditions to the LLM. It is recommended to default to sequential execution for state-changing tools to ensure a 'secure by default' posture. Additionally, an issue was identified in the addWaitForPreviousParameter implementation that could fail to add the new parameter in some edge cases.