Frontend · Backend · AI Programming

Claude Code's Async Tools: Turn Waiting Test Runs Into Task IDs and Notifications

By LEE · Oct 22, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Teams using Claude Code in interactive or CI workflows can stop blocking the model on long commands and start parallel work. Getting the choice wrong is costly: async adds task management, cache misses, and permission overhead, and the token bill collects the difference.

Summary

Claude Code's async tools change the semantics of tool calls from blocking function calls to task submission. Instead of running `npm test` synchronously and freezing the conversation, a model can call `Bash` with `run_in_background: true`, get a task ID immediately, and move on to other modules. When the process exits, the harness injects a notification, and the model reads the output from disk with `Read`. The same pattern extends to subagents, which are background by default, and to event monitoring, cron scheduling, and scripted Workflows.

Each form has its own constraints: background tasks cap output at 5GB, die with the session, and default to 30 minutes unattended; Monitor streams every line but has a 5-minute default deadline; CronCreate only fires in an idle REPL and expires recurring jobs after 7 days. The scheduling guidance also exposes a cost dimension most agent frameworks ignore: a 5-minute prompt-cache TTL means a wake-up after 300 seconds rereads the full context uncached, so the recommended heartbeat is 1200–1800 seconds. Workflow is the heaviest option and requires explicit user opt-in; most teams should master background Bash and TaskStop before orchestrating dozens of agents.

Takeaways

— Claude Code's `tools` array shrank from 20 to 12 between 2.1.303 and 2.1.304; the deferred 10 load through `ToolSearch` instead of being injected at startup.

— Foreground Bash times out at 120 seconds by default (max 600); a timed-out command is moved to the background rather than killed, unless it starts with `sleep` or background tasks are disabled.

— In background mode, `timeout` means maximum lifetime: default 600 seconds, max 7200. Output writes to disk and the model fetches it with `Read`; `TaskOutput` is gone since 2.1.277.

— Background tasks terminate at 5GB of output, clean up on session exit, default to 30 minutes unattended (max 2 hours), and `-p` text-prompt runs default to 10 minutes.

— Subagents run in the background by default; a foreground subagent is the exception. Completed subagents can be resumed by name with `SendMessage` without losing context.

— Subagent isolation supports `worktree` (temporary git worktree, auto-cleaned) and `remote` (cloud environment). Models are forbidden from fabricating pending agent results; the harness injects completion notifications.

— `Monitor` streams each output line as an event, has a default deadline of 5 minutes (max 30), and is unavailable on Bedrock, Vertex, and Foundry, or when telemetry-disabling env vars are set.

— `CronCreate` only fires in an idle REPL, caps at 50 jobs per session, expires recurring jobs after 7 days, and uses jitter (up to half a period, capped at 30 minutes) to avoid synchronized API load.

— `ScheduleWakeup` constrains delays to 60–3600 seconds; the recommended heartbeat is 1200–1800 seconds because the 5-minute prompt-cache TTL makes a 300-second wake the worst option.

— `Workflow` runs a JavaScript script in the background, keeps intermediate results in script variables, requires explicit user opt-in, defaults to fewer than 10 agents, and supports `resumeFromRunId`.

— Version 2.1.304 enabled `ToolSearch` by default under custom `ANTHROPIC_BASE_URL`; if a gateway or platform rejects tool search, requests fail on 2.1.304, and 2.1.305 retries without it.

Conclusions

Claude Code's protocol-level shift from `tool_result` payloads to task handles is what actually enables the model to do other work; shell `&` alone never gave the harness a way to re-invoke the model on completion.

The `ScheduleWakeup` guidance treats a model wake-up as a priced event: waiting 300 seconds is worse than both shorter and much longer intervals because it misses the 5-minute prompt cache without amortizing the miss. That is a cost model most agent schedulers don't have.

The hard rule against fabricating pending agent results closes the 'hallucinated completion' hole at the protocol layer, a stronger guarantee than relying on the model to be honest about what it knows.

Version 2.1.304's default flip for `ToolSearch` broke configurations where the platform rejects the search, and 2.1.305 had to add a retry path. Default changes in agent tooling can silently become hard failures for gateway users.

Starting with background Bash and `TaskStop` before adopting Workflow is the practical order; multi-agent orchestration is a later layer, not the first one.

Concepts & terms

run_in_background

A tool parameter that makes a Claude Code tool call return a task ID immediately instead of blocking on a result. The command runs detached, survives across turns, and re-invokes the model when it finishes.

TaskStop

A control tool that cancels a background task by ID. It is the async counterpart to interrupting the current turn; pressing Esc does not cancel background work.

Monitor

A Claude Code tool that runs a command in the background and feeds each line of output back to the model as an event. It suits tailing logs, polling CI, and watching for changes, not just waiting for process exit.

ToolSearch

A mechanism that lazy-loads a tool's JSONSchema on first use instead of injecting all tool schemas at startup. It saves context tokens but is a synchronous call; it does not run tools in parallel or in the background.

Prompt-cache TTL

Anthropic's default 5-minute time-to-live for cached conversation context. If a model wakes up after the TTL expires, the next request rereads the full context uncached, which is slower and more expensive.

Workflow

A background orchestration tool that runs a JavaScript script using `agent()`, `parallel()`, `pipeline()`, and `phase()` to coordinate subagents. Intermediate results stay in script variables, and the conversation only receives the final report.

Git worktree

An independent working directory attached to the same git repository. Claude Code uses it as an isolation boundary so subagents can work on the same repo without interfering with the main checkout.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗