Claude Code Agent Architecture: 4‑Layer Breakdown & 3 Key Designs from while(true) to Autonomous Decision‑Making

Claude Code Agent is organized into four logical layers: the Interaction layer (main.tsx/REPL) receives user input, the Orchestration layer (query.ts) runs the queryLoop() while‑true cycle, the Execution layer (StreamingToolExecutor) performs tool calls, and the Infrastructure layer (Memory/MCP/Compact) manages persistent state.

Core Mechanism 1: queryLoop while‑true Loop

The queryLoop function in src/query.ts repeatedly calls the LLM in streaming mode, detects tool_use blocks, executes tools, and injects results back into the conversation. State is carried across iterations via a State object that records messages, tool‑use context, auto‑compact tracking, turn count, and a transition.reason indicating why the loop entered the current turn (e.g., next_turn, stop_hook_blocking, max_output_tokens_recovery, etc.). The loop terminates via seven explicit exit paths (completed, max_turns, aborted_tools, hook_stopped, blocking_limit, prompt_too_long, stop_hook_prevented), each guarded by the stopHooks module ( src/query/stopHooks.ts) which acts as the sole legal exit guard.

async function* queryLoop(params: QueryParams, consumedCommandUuids: string[]): AsyncGenerator<StreamEvent | Message | ..., Terminal> { ... }

Core Mechanism 2: StreamingToolExecutor

When a tool_use block arrives, the StreamingToolExecutor (defined in src/services/tools/StreamingToolExecutor.ts) adds the tool to a TrackedTool queue. Tools marked isConcurrencySafe = true (e.g., GrepTool, FileReadTool) run concurrently; unsafe tools (e.g., FileEditTool, BashTool) run serially. The executor creates a child AbortController ( siblingAbortController) so that a failure in one tool aborts its siblings immediately, preventing wasted work.

export class StreamingToolExecutor {
  private tools: TrackedTool[] = [];
  private siblingAbortController: AbortController;
  constructor(toolDefinitions: Tools, canUseTool: CanUseToolFn, toolUseContext: ToolUseContext) { ... }
  addTool(block: ToolUseBlock, assistantMessage: AssistantMessage): void { ... }
}

Core Mechanism 3: autoCompact Circuit‑Breaker

Long‑running agents accumulate conversation history until the token window is exceeded, causing prompt_too_long errors. The autoCompact module ( src/services/compact/autoCompact.ts) triggers when token usage exceeds effectiveContextWindow - 13 000. It performs a four‑stage compression pipeline:

snip – local trimming of stale messages.

microcompact – cache‑based diff compression without LLM calls.

context collapse – folds processed tool calls into summary blocks.

autocompact – a full LLM summarisation (the most expensive step).

The AutoCompactTrackingState tracks consecutiveFailures; after three failures ( MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3) the circuit‑breaker stops further attempts, saving hundreds of thousands of API calls per day.

type AutoCompactTrackingState = {
  compacted: boolean;
  turnCounter: number;
  turnId: string;
  consecutiveFailures?: number;
};
const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3;

Before/After Comparisons

Three read‑only tools executed serially took ~300 ms; with StreamingToolExecutor they run concurrently in ~100 ms (3× speed‑up).

Without autoCompact, long dialogs crash with prompt_too_long; with the four‑stage compressor and circuit‑breaker the agent remains stable.

AutoCompact failure handling reduced wasted API calls from unlimited retries to a bounded three‑attempt limit, saving ~250 K calls per day in production.

Quick Reference Table

queryLoop – src/query.ts – while‑true driver, maintains State.

State – src/query.ts – carries messages, tool context, turn count, transition reason.

StreamingToolExecutor – src/services/tools/StreamingToolExecutor.ts – stream‑driven tool execution, concurrency safety, sibling abort.

TrackedTool – src/services/tools/StreamingToolExecutor.ts – tracks tool status (queued → executing → completed → yielded).

runTools – src/services/tools/toolOrchestration.ts – non‑stream fallback, partitions tools via partitionToolCalls.

partitionToolCalls – src/services/tools/toolOrchestration.ts – groups consecutive safe tools for parallel execution.

autoCompact – src/services/compact/autoCompact.ts – four‑stage context compression with circuit‑breaker.

AutoCompactTrackingState – src/services/compact/autoCompact.ts – tracks compacted flag, turn info, and failure count.

Memory (MEMORY.md) – src/memdir/memdir.ts – auto‑memory limited to 200 lines / 25 KB.

MCP client – src/services/mcp/client.ts – external tool server interface (stdio/SSE/HTTP/WS).

Conclusion

Claude Code Agent demonstrates a layered, self‑adjusting design where the perpetual while(true) loop decouples LLM reasoning from tool execution, StreamingToolExecutor provides safe concurrency, and autoCompact ensures long‑term stability through progressive compression and a robust circuit‑breaker. The architecture enables autonomous decision‑making while keeping resource usage predictable.