feat(core): intelligent tool parallelism with Kind-based batching and shell read-only detection

[wenshao]

What this PR does

When the model returns multiple tool calls in one response, they used to execute one by one — even if they're all read-only. This PR makes read-only tools run in parallel.

Before vs After

Model returns: [Read₁, Read₂, Grep, Bash("git log"), Read₃]

Before:  Read₁ → Read₂ → Grep → Bash → Read₃     (5 sequential steps)
After:   [Read₁ + Read₂ + Grep + Bash + Read₃]     (1 parallel step)

With mixed safe/unsafe tools, ordering is preserved via consecutive batching — consecutive safe tools are grouped into one parallel batch, but an unsafe tool breaks the batch:

Model returns: [Read₁, Read₂, Edit, Read₃]

Batch 1: [Read₁ + Read₂]  ← parallel (both safe, consecutive)
Batch 2: [Edit]            ← sequential (unsafe, breaks the batch)
Batch 3: [Read₃]           ← sequential (safe, but alone after the break)

3 steps instead of 4. Read₃ can't join Batch 1 because Edit sits between them.

What's safe to parallelize

	Tools	Why
Parallel	Read, Grep, Glob, WebFetch, WebSearch, ListDirectory	Kind-based: Read/Search/Fetch have no side effects
Parallel	Shell read-only commands (git log, git status, cat, ls, wc, diff, ...)	Checked by existing isShellCommandReadOnly() — a whitelist of ~30 commands with git subcommand validation. Unknown commands → sequential (fail-closed)
Parallel	Agent	Spawns independent subprocesses, no shared state
Sequential	Edit, WriteFile	File mutations must preserve ordering
Sequential	Shell mutating (npm install, rm, mkdir, ...)	Not on the read-only whitelist
Sequential	TodoWrite, SaveMemory	Kind.Think but write to disk
Sequential	Everything else	Fail-closed: unknown tools default to sequential

Behavior change: Agent tools

Previously, Agent tools were unconditionally pulled into a separate concurrent group (ran in parallel regardless of position). Now they follow the same consecutive batching rules as other safe tools. [Edit, Agent] previously ran concurrently; now Agent waits for Edit to finish. This is safer — it preserves the model's intended ordering.

Comparison with Claude Code

Capability	Claude Code	Qwen Code (after this PR)
Read-only tool parallelism	Yes	Yes
Consecutive batch grouping	Yes	Yes
Shell read-only detection	regex + shell-quote + per-flag validation	regex + shell-quote + command whitelist (same approach, comparable coverage)
Streaming tool execution	Yes	No (minimal benefit on Gemini API)

Core parallel execution capability is now on par with Claude Code.

Note: Qwen Code also has a tree-sitter-bash AST parser (isShellCommandReadOnlyAST) used for permission decisions. The concurrency check uses the synchronous regex-based checker for performance (partitioning must be synchronous). Both checkers share the same command whitelist.

Changes

File	Change
tools.ts	Add CONCURRENCY_SAFE_KINDS set (Read, Search, Fetch)
coreToolScheduler.ts	isConcurrencySafe(), partitionToolCalls(), runConcurrently() with shell read-only detection and configurable concurrency cap (QWEN_CODE_MAX_TOOL_CONCURRENCY, default 10)
mock-tool.ts	Support custom kind option for testing
coreToolScheduler.test.ts	Tests for all-safe parallel, mixed batching, shell read-only concurrency, env isolation

Test plan

• npx vitest run packages/core/src/core/coreToolScheduler.test.ts — 55 tests pass
• npx tsc --noEmit -p packages/core/tsconfig.json — type check passes
• Manual: model returns multiple read_file calls → parallel execution confirmed

🤖 Generated with Claude Code

[github-actions]

📋 Review Summary

This PR implements intelligent tool parallelism based on tool Kind, replacing the hard-coded Agent-only concurrent execution model. The implementation is well-structured, with clear separation of concerns and comprehensive test coverage. The changes enable read-only tools (Read, Search, Fetch, Think) to execute in parallel while preserving ordering semantics for mutating tools (Edit, Execute).

🔍 General Feedback

• Clean architecture: The helper functions (isConcurrencySafe, partitionToolCalls, runConcurrently) are well-isolated and follow single-responsibility principles.
• Good documentation: JSDoc comments clearly explain the batching behavior with concrete examples.
• Thoughtful design: The consecutive batching approach preserves implicit ordering that models may rely on while maximizing parallelism opportunities.
• Configurable concurrency: The QWEN_CODE_MAX_TOOL_CONCURRENCY environment variable provides operational flexibility.
• Test coverage: The updated test properly validates that all concurrency-safe tools run in parallel rather than just Agent tools.

🎯 Specific Feedback

🟡 High

• File: packages/core/src/core/coreToolScheduler.ts:344-349 - The isConcurrencySafe function checks ToolNames.AGENT by name but other tools by kind. This creates an inconsistency in how concurrency safety is determined. Consider whether Agent should also have a Kind.Agent value added to CONCURRENCY_SAFE_KINDS for consistency, or document why Agent is treated as a special case.

• File: packages/core/src/core/coreToolScheduler.ts:358-369 - The partitionToolCalls logic groups consecutive safe tools but creates a sequential batch for each unsafe tool. This means [Read, Edit, Read] becomes [[Read](parallel), [Edit](seq), [Read](seq)] - the second Read could potentially run in parallel with the first if they're both safe. However, the current design intentionally preserves ordering, which is correct but worth documenting more explicitly that this is a deliberate ordering guarantee, not a limitation.

🟢 Medium

• File: packages/core/src/core/coreToolScheduler.ts:1353-1371 - The runConcurrently function uses a Set to track executing promises and removes them via .then() callback. However, if a promise rejects before completion, the .then() callback may not execute properly. Consider using .finally() instead to ensure cleanup:

  const p = this.executeSingleToolCall(call, signal).finally(() => {
    executing.delete(p);
  });

• File: packages/core/src/tools/tools.ts:740-746 - The CONCURRENCY_SAFE_KINDS set is exported but only used internally by coreToolScheduler.ts. Consider whether this should be exported or kept internal to reduce API surface. If exported, consider adding a comment explaining the safety guarantees (no side effects, no shared mutable state).

• File: packages/core/src/core/coreToolScheduler.ts:344 - The comment mentions "no side effects, no shared mutable state" but the isConcurrencySafe function doesn't verify these properties - it relies on the Kind classification. Consider adding a stronger comment that tool implementers must ensure their Kind-appropriate tools actually satisfy these guarantees.

🔵 Low

• File: packages/core/src/core/coreToolScheduler.test.ts:3147 - The test timeout was increased from 20ms to 50ms for the read tool. Consider using a more descriptive constant or configuration value to make the test intent clearer (e.g., const TOOL_EXECUTION_DELAY = 50).

• File: packages/core/src/core/coreToolScheduler.ts:334 - The decorative separator line (// ─── Tool Concurrency Helpers ────────────────────────────────) uses Unicode characters that may not render consistently across all editors. Consider using standard ASCII separators for better compatibility.

• File: packages/core/src/test-utils/mock-tool.ts:27 - The kind?: Kind option is added but there's no validation that the provided kind matches the tool's actual behavior. Consider adding a comment or validation in test utilities to ensure test authors don't misclassify mock tools.

✅ Highlights

• Excellent test update: The test at line 3122 properly validates that ALL concurrency-safe tools (not just Agent) run in parallel, with clear assertions checking that all starts happen before any ends.
• Smart batching strategy: The partitionToolCalls function elegantly handles the complex scenario of interleaved safe/unsafe tools while preserving ordering guarantees.
• Environment variable configuration: Adding QWEN_CODE_MAX_TOOL_CONCURRENCY shows operational maturity and allows tuning for different environments.
• Minimal changes: The implementation achieves significant functionality with focused changes to only 4 files, demonstrating good modular design.
• Type safety: The use of ReadonlySet<Kind> and proper TypeScript typing ensures the concurrency-safe kinds list is immutable and type-checked.

[Copilot]

Pull request overview

This PR updates the core tool scheduling logic to reduce end-to-end latency by executing consecutive “concurrency-safe” tool calls in parallel (batched by tool Kind), instead of only running Agent tools concurrently.

Changes:

• Introduces a CONCURRENCY_SAFE_KINDS allowlist to classify tool kinds as parallel-safe.
• Adds batching + capped parallel execution to CoreToolScheduler via partitionToolCalls() and runConcurrently().
• Updates test utilities and scheduler tests to support/verify kind-driven parallelism.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
packages/core/src/tools/tools.ts	Adds a concurrency-safe Kind set used to determine which tool calls may run in parallel.
packages/core/src/core/coreToolScheduler.ts	Implements Kind-based batching, safety checks, and concurrency-capped parallel execution.
packages/core/src/test-utils/mock-tool.ts	Allows tests to assign a custom kind to mock tools.
packages/core/src/core/coreToolScheduler.test.ts	Updates the concurrency test to assert parallel execution for concurrency-safe tools.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.