New features / v2.1.269

Raise the Workflow tool's agent concurrency limit

CHANGELOG · original

Added CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS (1–256) to raise the Workflow tool's per-run concurrent agent limit for inference-bound fan-outs

The runtime applies the following constraints:

Constraint	Why
No mid-run user input	A run pauses on its own only for agent permission prompts and a usage-limit wait. For sign-off between stages, run each stage as its own workflow
No direct filesystem or shell access from the workflow itself	Agents read, write, and run commands. The script coordinates the agents
No module loading: a script that contains `import()` fails before the run starts	The script body is plain JavaScript. Put work that needs a library in an agent's task
Up to 16 concurrent agents by default, fewer when Claude Code has fewer CPUs available, including inside a CPU-limited container. To change the limit, set `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` to a value from 1 to 256, which requires Claude Code v2.1.269 or later	Bounds local resource use
In a fan-out, agents that share the first agent's prompt-cache prefix start up to 5 seconds after it by default	All but the first read the prefix the first agent cached instead of each processing it uncached
Up to 4,096 items in a single `parallel()` or `pipeline()` call: the runtime rejects a longer list with an error	A silent cap would drop part of the workload without telling the script
1,000 agents total per run	Prevents runaway loops

Documentation snapshot · 2026-09-23