feat: add support for calling multiple subagents at once

[Githubguy132010]

TLDR

Subagents now execute in parallel instead of sequentially. Add maxConcurrentSubagents parameter (default: 1) to control concurrency. For 5 independent tasks, execution time reduces from 5×T to ~2×T with maxConcurrentSubagents=3. Users can enable and configure parallel execution through the CLI settings menu. The TaskTool now dynamically informs the AI about the actual execution mode to ensure correct behavior. Settings require CLI restart to take effect. Includes robust error handling and input validation to prevent edge cases.

Dive Deeper

Core Changes:

• Modified coreToolScheduler.ts to separate TaskTool execution from other tools
• TaskTools execute in parallel up to maxConcurrentSubagents limit using Set-based promise tracking
• Non-TaskTools remain sequential (preserves existing behavior)
• Added executeTaskToolCallsInParallel() with race-condition-free concurrency control
• Refactored execution into executeSingleToolCall() for reuse
• Improved error handling: Uses .finally() to ensure promises are always removed from executing Set, even when tasks fail
• Input validation: Validates maxConcurrentSubagents to minimum of 1 using Math.max() to prevent infinite loops

Configuration:

• Added maxConcurrentSubagents parameter to Config and QueryOptions (SDK)
• Default value of 1 maintains backward compatibility
• Validation: Config constructor validates minimum value to prevent 0 or negative values

CLI Settings Menu:

• Added "Enable Parallel Subagent Execution" toggle in Experimental category (default: OFF)
• Added "Max Concurrent Subagents" numeric setting (default: 3, recommended: 3-5)
• Both settings accessible via /settings command in the CLI
• Settings marked as requiresRestart: true - CLI restart required for changes to take effect
• Settings show restart warning when changed

Dynamic AI Guidance:

• TaskTool description now adapts based on parallel execution configuration
• When disabled: AI sees "Agents run sequentially (one at a time)"
• When enabled: AI sees "IMPORTANT: Launch multiple agents concurrently (up to N agents at once)"
• Ensures AI behavior matches actual execution mode and uses appropriate tool call patterns

Testing:

• 4 original tests verify parallel execution, sequential fallback, concurrency limits, and tool type separation
• New test: Error handling during parallel execution - verifies that failed tasks don't block other parallel tasks from completing
• All tests passing ✓

Usage:

Via CLI Settings Menu (requires restart):

1. Run qwen CLI
2. Type /settings command
3. Navigate to "Experimental" section
4. Toggle "Enable Parallel Subagent Execution" to ON
5. Adjust "Max Concurrent Subagents" (recommended: 3-5)
6. Save settings with 's'
7. Exit and restart the CLI for changes to take effect
8. Parallel execution now active

Via SDK:

const result = await query({
  prompt: 'Analyze files in parallel',
  options: {
    maxConcurrentSubagents: 3,  // Run up to 3 subagents concurrently
    agents: [{ name: 'analyzer', ... }],
  },
});

Important Notes:

• The Config object is created once at CLI startup and reads settings then. Changes to parallel execution settings during runtime require a CLI restart to take effect. The settings now properly indicate this requirement with a restart warning.
• Input validation prevents invalid values (0 or negative) that could cause infinite loops
• Error handling ensures failed tasks don't prevent other parallel tasks from completing

Known Limitation:

• CLI UI may flicker when running multiple parallel subagents due to concurrent output updates. This is a terminal rendering issue separate from the core parallel execution feature. Workarounds: use lower concurrency (2-3), redirect output to file, or use SDK instead of CLI.

Reviewer Test Plan

1. CLI Settings Menu:

   • Run qwen and type /settings
   • Navigate to Experimental section
   • Verify "Enable Parallel Subagent Execution" toggle appears
   • Verify "Max Concurrent Subagents" numeric input appears
   • Toggle settings on/off and save
   • Verify restart warning appears when settings change

2. Restart requirement verification:

   • Change parallel execution settings
   • Save settings
   • Restart CLI (exit and run qwen again)
   • Verify settings are now active

3. Parallel execution with AI awareness:

   • Enable parallel execution in settings
   • Restart CLI
   • Ask AI to "analyze these 3 files" or similar multi-subagent task
   • Verify AI uses multiple task tool calls in a single message
   • Verify subagents execute in parallel (reduced execution time)

4. Sequential fallback:

   • Keep parallel execution disabled in settings (or set maxConcurrentSubagents: 1)
   • Restart CLI if changed
   • Verify AI description shows "Agents run sequentially"
   • Verify behavior matches original sequential execution

5. Concurrency limit:

   • Enable parallel execution with maxConcurrentSubagents: 2
   • Restart CLI
   • Schedule 5 TaskTools, verify max 2 execute simultaneously

6. Tool separation: Mix TaskTools and other tools, verify only TaskTools parallelize

7. AI guidance verification:

   • With parallel disabled: Check tool description indicates sequential execution
   • With parallel enabled: Check tool description emphasizes concurrent usage with correct limit

8. Error handling verification:

   • Create scenarios where some parallel tasks fail
   • Verify that successful tasks complete despite failures in other parallel tasks
   • Verify no infinite loops or hangs occur

9. Input validation verification:

   • Attempt to set maxConcurrentSubagents to 0 or negative values via SDK
   • Verify Config validates to minimum of 1

Run existing integration tests to validate no regressions:

npm test -- coreToolScheduler.test.ts  # All 26+ tests should pass (includes new error handling test)
npm test -- settingsSchema.test.ts     # Settings schema tests pass

Testing Matrix

	🍏	🪟	🐧
npm run	❓	❓	✅
npx	❓	❓	❓
Docker	❓	❓	❓
Podman	❓	❓	❓
Seatbelt	❓	❓	❓

Linked issues / bugs

Related #856 to improving qwen-code workflow performance for multi-task scenarios.