Why Claude Code’s Architecture Keeps Agents Stable: A Deep Dive into Runtime Design

1. Entry and Startup Chain

Claude Code avoids loading the entire runtime at once; it first determines the launch mode (local, headless, remote, fast‑path) and then proceeds through three phases: entry routing, process‑level initialization, and session preparation. Process state (cwd, projectRoot, telemetry) is kept separate from interactive session state, preventing the main loop from being polluted by mixed concerns.

2. REPL / UI Orchestration

The REPL is not a simple message view but an orchestrator that assembles the current capability set, merges tool, plugin, and permission contexts, and emits a structured event stream before handing control to the model. It decides whether an input is a fast‑path command, builds the execution context, and finally invokes query(...).

3. Query Loop / QueryEngine

The query loop upgrades a single request into a stateful machine. It performs memory prefetch, skill discovery, budgeting, and compacting before streaming the model. When a tool call appears, the loop pauses, runs the tool, normalizes the result, writes it back into the message history, and continues. This loop maintains a persistent state object with fields such as messages, toolUseContext, maxOutputTokensRecoveryCount, and turnCount, enabling long‑context handling, failure recovery, and tool result reintegration.

4. Tool Runtime

Tools are treated as first‑class runtime objects, not mere function calls. Each tool defines a schema, validation, concurrency safety, permission checks, and result mapping. The execution flow is:

Parse and validate input against the tool’s schema.

Run pre‑tool hooks and decide permission.

Execute the tool (potentially streaming).

Map the output to a structured tool_result block.

This design centralizes parameter validation, permission, concurrency, progress reporting, and error handling, preventing duplicated logic across tools.

5. Permission System

Permission decisions are expressed as rich objects rather than simple booleans. A decision can be allow, ask, or deny, each carrying a reason, suggestions, blocked paths, and pending classifier checks. The system separates logical authorization from sandbox enforcement, allowing automatic decisions where possible and only prompting the user when necessary.

6. Task / Multi‑Agent / Background Execution

Claude Code introduces a unified Task abstraction that represents any long‑running or background activity, whether it is a sub‑agent, remote worker, or background session. Tasks track status, progress, notifications, and result payloads, and they can be backgrounded, persisted to disk, and evicted after a timeout. This prevents the main loop from being polluted by concurrent executions.

7. MCP / Skills / Plugins Extension Layer

External capabilities (MCP, skills, plugins) are translated into internal objects: commands, tools, or skill descriptors. A SkillDescriptor includes description, allowed tools, model preferences, effort level, hooks, execution context, and optional agent binding. By converging diverse extensions into a small set of internal abstractions, the platform remains stable as it scales.

8. Overall Architecture

The system can be visualized as three primary chains:

Control Chain : startup → REPL → query loop, establishing the execution boundary.

Execution Chain : query loop → tool runtime → permission → sandbox, handling actions.

Task Chain : task runtime manages concurrency, persistence, and result back‑flow for long‑running agents.

All extensions feed into these chains without breaking the core abstractions, ensuring that complexity is isolated where it belongs.

state = {
  messages,
  toolUseContext,
  maxOutputTokensOverride,
  autoCompactTracking,
  maxOutputTokensRecoveryCount,
  hasAttemptedReactiveCompact,
  turnCount,
  pendingToolUseSummary,
  transition,
}

while (true) {
  prefetchMemoryAndSkills();
  messagesForQuery = applyBudget(messages);
  messagesForQuery = snipAndCompact(messagesForQuery);
  assistant = streamModel(messagesForQuery);
  if (!assistant.hasToolUse) return finishTurn(assistant);
  toolResult = runToolUse(assistant.toolUse, toolUseContext);
  state.messages = writeBack(messages, assistant, toolResult);
}

type PermissionDecision =
  | { behavior: 'allow'; updatedInput?; decisionReason? }
  | { behavior: 'ask'; message: string; suggestions?: PermissionUpdate[]; blockedPath?: string; pendingClassifierCheck?: PendingClassifierCheck }
  | { behavior: 'deny'; message: string; decisionReason: string }

type SkillDescriptor = {
  description: string;
  allowedTools: string[];
  whenToUse?: string;
  model?: Model;
  effort?: Effort;
  hooks?: Hooks;
  executionContext?: 'fork';
  agent?: string;
}