feat(core): add concurrency safety guidance for subagent delegation (#17753)

[abhipatel12]

Summary

Add concurrency safety guidance for subagent delegation to prevent race conditions when running agents in parallel. This PR introduces clear instructions for the model on when it is safe to parallelize subagent calls and when it must remain sequential.

Details

• Added explicit Concurrency Safety and Mandate to the strategic orchestration and sub-agent delegation prompts.
• Instructs the model to NEVER run multiple subagents in parallel if they mutate the same files/resources, unless explicitly requested by the user.
• Allows parallel execution for independent tasks (e.g., multiple research agents).
• Included a new evaluation test evals/concurrency-safety.eval.ts to verify the model adheres to these parallelism rules.
• Updated evals/test-helper.ts to set commit.gpgsign false in test git repositories to prevent blocking on GPG prompts during CI/tests.

Related Issues

Fixes #17753

How to Validate

Run the new concurrency safety evaluation:

npm test evals/concurrency-safety.eval.ts

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 introduces crucial concurrency safety guidelines for subagent delegation within the core agent system. The aim is to mitigate race conditions by providing clear instructions to the model on when it is safe to parallelize subagent calls (e.g., for read-only tasks) and when sequential execution is mandatory (e.g., for tasks modifying shared resources). This enhancement ensures greater stability and predictability in agent operations, supported by a new evaluation test to validate compliance with these rules and a minor configuration update to streamline test execution.

Highlights

• Concurrency Safety Guidance: Explicit concurrency safety guidance was added to strategic orchestration and sub-agent delegation prompts to prevent race conditions.
• Parallel Execution Rules: Models are now instructed to never run multiple subagents in parallel if they mutate the same files/resources, unless explicitly requested, while allowing parallel execution for independent tasks.
• New Evaluation Test: A new evaluation test, evals/concurrency-safety.eval.ts, was introduced to verify that the model adheres to these new parallelism rules.
• Test Infrastructure Update: evals/test-helper.ts was updated to set commit.gpgsign false in test Git repositories, preventing GPG prompts from blocking CI/tests.

Changelog

• evals/concurrency-safety.eval.ts
  • Added a new evaluation test file to verify concurrency safety rules for subagent delegation.
• evals/test-helper.ts
  • Updated the evalTest function to set git config commit.gpgsign false for test repositories.
• packages/core/src/core/snapshots/prompts.test.ts.snap
  • Updated multiple prompt snapshots to include new "Concurrency Safety and Mandate" guidance.
• packages/core/src/prompts/snippets.legacy.ts
  • Added "Concurrency Safety and Mandate" guidance to the legacy sub-agent delegation prompt snippet.
• packages/core/src/prompts/snippets.ts
  • Added "Concurrency Safety and Mandate" guidance to the main strategic orchestrator prompt snippet.

Activity

• No human activity has been recorded for this pull request yet.

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

Total Size: 26 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	25.5 MB	+429 B (0%)
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 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

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces important concurrency safety guidance for subagent delegation, preventing potential race conditions. The changes include new prompts for the model, evaluation tests to verify the behavior, and a CI improvement to disable GPG signing. The implementation is solid, but there is one violation of the repository's development conventions regarding modifications to legacy prompt files.

[gundermanc]

I wonder if this is going to discourage parallelism in general. Is there any value to indicating that parallelism is encouraged, just only when it's safe (parallel reads, or parallel writes to different files or directories)?

[abhipatel12]

Yeah I def see the concern. In this case, we have the Tool Usage section that still encourages parallelism of general tool use.

this wording is primarily conservative for parallelism of subagents that may mutate things. I think that should be fine. There should be a follow up task that goes deeper into encouraging parallel calls whether subagents or tools.

For parallelism of subagents that mutate things, we'll need to test more. I attempted to be less restrictive, but even in cases that were obviously destructive, the model often still chose to run agents in parallel. even when directly modifying the same file.

[gundermanc]

Approved with a suggestion.