async-concurrency

Async Concurrency

The pattern

Claude Code's tool execution is mostly sequential — one tool at a time — but read-only tools can run in parallel when isConcurrencySafe() returns true. Cancellation is propagated via AbortController passed through ToolUseContext. Parallel initialization uses Promise.all(). Streaming partial results uses onProgress callbacks fed into a StreamingToolExecutor.

The key design: concurrency safety is a per-call decision, not a per-tool constant. A bash tool reading git status is safe to run concurrently. The same bash tool running npm install is not. The tool knows its own input and can make the right call.

Why this matters

In a developer session, the LLM often requests several read operations in sequence (read file A, read file B, check git status). If these were strictly sequential, the user would wait for three round-trips to disk. isConcurrencySafe: true tells the scheduler it can run these in parallel, reducing perceived latency.

Cancellation is critical for long-running tools (bash commands, web fetches). When the user presses Ctrl+C, the AbortController's signal fires and all in-flight tool calls must stop promptly. A tool that ignores context.abortController.signal will keep running after the user cancelled, blocking the next turn.

Git status is a concrete example: Claude Code parallelizes five git commands — branch, default branch, status, recent log, and user name — with a single Promise.all(). This collapses what would be ~500ms of sequential I/O into a single ~100ms concurrent batch.

How to apply it

1. For isConcurrencySafe(input): return true only for operations that don't mutate state. File reads, globs, searches, and git status commands are safe. File writes, bash mutations, and agent spawns are not.
2. For isReadOnly(input): return true for operations that make no persistent changes. Used to determine if the tool can be skipped in speculation mode.
3. Pass context.abortController.signal to all async I/O: fetch(), execFile(), file streams. This ensures immediate cancellation on user interrupt.
4. Check signal.aborted at checkpoints in long-running loops.
5. When a tool runs multiple I/O operations that are independent, use Promise.all() — don't await them sequentially.
6. For streaming partial results, call onProgress(progressData) as work proceeds. The UI subscribes to these calls to show live output.