ClaudeCode’s Tool System: Everything is a Tool

Design Philosophy

Whether it’s reading a file, executing a shell command, or dispatching a sub-agent that can run autonomously for dozens of steps, it’s all the same to the LLM: output a tool_use block, wait for a tool_result.

Three lines, three tool calls — the LLM’s perspective is perfectly symmetric.

Tool Interface: A Unified Contract

Every tool implements the same interface. The core is: what call() returns doesn’t matter. Read returns file content, Bash returns stdout, AgentTool returns the sub-agent’s final reply. To the caller, it’s all just a string.

The LLM can request multiple tools at once, and the system splits them into batches:

• For consecutive read-only tools (isConcurrencySafe = true), they are grouped into a concurrent batch
• Any write operation forms its own sequential batch

Someone might ask: what if there’s a background tool call in the middle? In fact, a background tool is an “instant-completing tool” as far as the batch is concerned Once an async tool is invoked, it instantly returns { status: 'async_launched', agent_id: '...' }. When the background task actually finishes, the result is stored into messageQueueManager; let me briefly digress to explain messageQueueManager. Simply put, think of it as “ClaudeCode’s input queue, holding events that haven’t been processed yet.” There are several priority levels: 1. now — such events immediately terminate the current turn; e.g., user pressing esc. 2. next — after the current turn ends, before the next LLM call; e.g., a normal user message triggers the next turn. 3. later — processed only when the current round is completely idle; e.g., completion notifications for background tasks. When dequeuing, items are taken by priority order, FIFO within the same priority. Simply put, any user input in ClaudeCode goes through MessageQueueManager for management (except slash commands). Back to the async tool: after the async task is dispatched, the LLM immediately receives a message: “Background task dispatched! Task ID: xxxx.” If the LLM can’t wait, it can check earlier. When the task finishes, the result is stored in messageQueueManager with later priority, and at the end of the current turn it gets injected into the context […]

Agent Tool: The Heaviest Tool, But Still a Tool

AgentTool is the “heaviest” Tool in the entire system, yet it follows the exact same interface.

Inside its call(), it does the following: spins up a brand new QueryEngine with its own message history, tool pool, and permission context, then runs a complete agent loop (LLM → tool → LLM → tool…) independently until the task is done.

From the outside, it’s no different from Read: you put an input in, you get a result string out.

Of course, it also uses the same synchronous and asynchronous handling approaches, exactly as described above.