CereParse

Fast Semantic OCR-to-RAG Compiler powered by Gemma 4 on Cerebras

Upload a technical PDF or paper. CereParse will extract text, then reconstructs Markdown, metadata, RAG chunks, citation graphs, QA reports, and Cerebras speed metrics.

Upload a technical PDF or paper

💡 Quick Test / Bypass OCR: We have preloaded a sample document below. Feel free to edit it or paste your own raw OCR text directly.

Raw OCR Text Input

arXiv:2604.14228v1 [cs.SE] 14 Apr 2026
Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems
Jiacheng Liu \( ^{1} \) , Xiaohan Zhao \( ^{1} \) , Xinyi Shang \( ^{1,2} \) , Zhiqiang Shen \( ^{1,\dagger} \)
\( ^{1} \) VILA Lab, Mohamed bin Zayed University of Artificial Intelligence,  \( ^{2} \) University College London
 \( ^{\dagger} \) Corresponding author
Claude Code is an agentic coding tool that can run shell commands, edit files, and call external services on behalf of the user. This study describes its comprehensive architecture by analyzing the publicly available TypeScript source code \( ^{a} \) and further comparing it with OpenClaw, an independent open-source AI agent system that answers many of the same design questions from a different deployment context. Our analysis identifies five human values, philosophies, and needs that motivate the architecture (human decision authority, safety and security, reliable execution, capability amplification, and contextual adaptability) and traces them through thirteen design principles to specific implementation choices. The core of the system is a simple while-loop that calls the model, runs tools, and repeats. Most of the code, however, lives in the systems around this loop: a permission system with seven modes and an ML-based classifier, a five-layer compaction pipeline for context management, four extensibility mechanisms (MCP, plugins, skills, and hooks), a subagent delegation and orchestration mechanism, and append-oriented session storage. A comparison with OpenClaw, a multi-channel personal assistant gateway, shows that the same recurring design questions produce different architectural answers when the deployment context changes: from per-action safety evaluation to perimeter-level access control, from a single CLI loop to an embedded runtime within a gateway control plane, and from context-window extensions to gateway-wide capability registration. We finally identify six open design directions for future agent systems, grounded in recent empirical, architectural, and policy literature. Our GitHub is available at: https://github.com/VILA-Lab/ Dive-into-Claude-Code.
Correspondence: Zhiqiang Shen (Zhiqiang.Shen@mbzuai.ac.ae)
\( ^{a} \) v2.1.88, link. Disclaimer: All materials used in this work are obtained from publicly available online sources. We have not used any private, confidential, or unauthorized materials, and we do not intend to infringe any copyright or intellectual property rights. The original intellectual property rights to the source code belong to Anthropic.
1 Introduction
AI-assisted software development has evolved from autocomplete-style tools such as GitHub Copilot (Chen et al., 2021), through IDE-integrated assistants like Cursor (Cursor, 2026), to fully agentic systems that autonomously plan multi-step modifications, execute shell commands, read and write files, and iterate on their own outputs. Claude Code (Anthropic, 2026a) is an agentic coding tool released by Anthropic (Anthropic, 2026c). Its official documentation describes an “agentic loop” that plans and executes actions toward accomplishing a goal and can call tools, evaluate results, and continue until the task is done \( ^{1} \) . This shift from suggestion to autonomous action introduces architectural requirements that have no counterpart in completion-based tools. These requirements define a design space, a set of recurring questions spanning topics such as safety, context management, extensibility, and delegation that every coding agent must navigate. This study uses source-level analysis of Claude Code to show how one production system answers these questions.
Despite growing adoption, Anthropic publishes user-facing documentation for Claude Code but not detailed architectural descriptions. This study uses source code analysis to describe architectural design decisions. Anthropic's internal survey of 132 engineers and researchers (Huang et al., 2025) reports that about \(27\%\) of Claude Code-assisted tasks were work that would not have been attempted without the tool, suggesting that the architecture enables qualitatively new workflows rather than merely accelerating existing ones.
\( ^{1} \) https://code.claude.com/docs/en/how-claude-code-works.
1
── PAGE 2 / 46 ──
In this work, we first identify five human values/philosophies and thirteen design principles that motivate the architecture (Section 2), then organize the analysis in three parts:
1. Design-space analysis. We identify recurring design questions (where reasoning lives, how the iteration loop is structured, what safety posture to adopt, how the extension surface is partitioned, how context is managed, how work is delegated across subagents, and how sessions persist) and analyze Claude Code's answers through a 7-component high-level structure and a 5-layer subsystem architecture, tracing each choice to specific source files (Section 3). The analysis aims to build a deep understanding of the system mechanism, with the goal of informing the design of better and more powerful agent systems.
2. Architectural contrast with OpenClaw. Beyond analyzing Claude Code itself, we also compare its design philosophy with that of open-source agent system OpenClaw (Steinberger and OpenClaw Contributors, 2026), a multi-channel personal assistant gateway, across six design dimensions to show how the same recurring questions produce different answers under different deployment contexts (Section 10), in order to highlight both the common principles and the key differences between commercial and open-source software. This comparison helps reveal how deployment setting, product goals, safety requirements, and user assumptions shape architectural choices in different ways. By examining where these systems converge and where they diverge, our study aims to provide useful guidance and practical insights for the design of future, more capable agent systems.
3. Open directions for future agent systems. Building on the design-space analysis and the OpenClaw contrast, Section 12 identifies six open directions spanning the observability-evaluation gap, cross-session persistence, harness boundary evolution, horizon scaling, governance, and the evaluative lens, each drawing on empirical, architectural, and policy literature. Used as an evaluative lens, our study also reveals an open question: while the Claude Code agent system substantially amplifies the short-term capabilities of programmers and end users, it offers limited mechanisms that explicitly support long-term human improvement, deeper understanding, and sustained codebase coherence.
The core agent loop is a while-true cycle with state management. The surrounding subsystems for safety, extensibility, context management, delegation, and persistence make up the bulk of the implementation. Source-level analysis \( ^{2} \) allows us to identify design choices, subsystem boundaries, and implementation trade-offs directly from the system itself rather than inferring them solely from product descriptions.
Running example. To keep the architecture concrete, we trace the task “Fix the failing test in auth.test.ts” through Sections 3 to 9. This example illustrates how a seemingly simple user request activates multiple architectural layers, including tool invocation, permission checks, context selection, iterative repair, delegation, and session persistence.
Paper organization. Section 2 identifies the human values and design principles that motivate the architecture. Section 3 introduces the high-level architecture and the design questions it answers. Sections 4 to 9 each analyze a major subsystem's design choices. Section 10 contrasts the analysis with OpenClaw, Section 11 provides discussion, and Section 12 surveys open questions for future agent systems. Sections 13 and 14 then cover related work and conclusions. Section B describes the evidence base and methodology.
2 Design Philosophies, Design Principles and Architectural Motivations
Production coding agents are built by humans, for humans, and the architectural decisions they embed reflect what their creators believe matters. This section identifies the human values that motivate Claude Code's design, traces them through recurring design principles, and frames the design-space questions that organize the analysis in Sections 3 to 9.
Anthropic's framework for safe agents states a central tension: “Agents must be able to work autonomously; their independent operation is exactly what makes them valuable. But humans should retain control over how their goals are pursued” (Anthropic, 2025a). Claude's Constitution resolves this not through rigid decision procedures
\( ^{2} \) Our analysis is grounded primarily in the source code, supplemented by official Anthropic documentation and selected community analysis, Section B details the evidence base and methodology.
2
── PAGE 3 / 46 ──
but by cultivating “good judgment and sound values that can be applied contextually” (Anthropic, 2026b). These commitments, together with empirical findings about how developers actually use the tool (Huang et al., 2025; McCain et al., 2026), point to five human values that shape the architecture.
2.1 Five Values and Philosophies
Human Decision Authority. The human retains ultimate decision authority over what the system does, organized through a principal hierarchy (Anthropic, then operators, then users) that formalizes who holds authority over what (Anthropic, 2026b). The system is designed so that humans can exercise informed control: they can observe actions in real time, approve or reject proposed operations, interrupt compatible in-progress operations, and audit after the fact. When Anthropic found that users approve 93% of permission prompts (Hughes, 2026), the response was not to add more warnings but to restructure the problem: defined boundaries (sandboxing, auto-mode classifiers) within which the agent can work freely, rather than per-action approvals that users stop reviewing once habituated (Dworken and Weller-Davies, 2025).
Safety, Security, and Privacy. The system protects humans, their code, their data, and their infrastructure from harm, even when the human is inattentive or makes mistakes. This is distinct from Human Decision Authority: where authority is about the human's power to choose, safety is about the system's obligation to protect even when that power lapses. Anthropic's safe-agents framework separately identifies securing agent interactions and protecting privacy across extended interactions as core commitments (Anthropic, 2025a). The auto-mode threat model (Hughes, 2026) explicitly targets four risk categories: overeager behavior, honest mistakes, prompt injection, and model misalignment.
Reliable Execution. The agent does what the human actually meant, stays coherent over time, and supports verifying its work before declaring success. This value spans both single-turn correctness (did it interpret the request faithfully?) and long-horizon dependability (does it remain coherent across context window boundaries, session resumption, and multi-agent delegation?). Anthropic's product documentation (Anthropic, 2026d) describes a three-phase loop that the agent repeats until the task is complete: gather context, take action, and verify results. The agent design guidance (Schluntz and Zhang, 2024) further emphasizes that “ground truth from the environment” at each step assesses progress. The harness-design guidance (Rajasekaran, 2026) likewise notes that “agents tend to respond by confidently praising the work,” even when quality is mediocre, motivating separation of generation from evaluation.
Capability Amplification. The system materially increases what the human can accomplish per unit of effort and cost. Anthropic's internal survey (Huang et al., 2025), discussed in Section 1, suggests that the architecture enables qualitatively new workflows, not merely faster existing ones: approximately \(27\%\) of tasks represented work that would not otherwise have been attempted. The system is described by its creators as "a Unix utility rather than a traditional product," built from the smallest building blocks that are "useful, understandable, and extensible" (Cherny and Wu, 2025). The architecture invests in deterministic infrastructure (context management, tool routing, recovery) rather than decision scaffolding (explicit planners or state graphs), on the premise that increasingly capable models benefit more from a rich operational environment than from frameworks that constrain their choices.
Contextual Adaptability. The system fits the user's specific context (their project, tools, conventions, and skill level) and the relationship improves over time. The extension architecture (CLAUDE.md, skills, MCP, hooks, plugins) provides configurability at multiple levels of context cost (Sections 6 and 7). Longitudinal data (McCain et al., 2026) shows that the human-agent relationship evolves: auto-approve rates increase from approximately \(20\%\) at fewer than 50 sessions to over \(40\%\) by 750 sessions. This pattern, described as autonomy that is "co-constructed by the model, the user, and the product," means the system is designed for trust trajectories rather than fixed trust states. MCP's donation to the Linux Foundation's Agentic AI Foundation (The Linux Foundation, 2025) reflects the ecosystem dimension of this value.
3
── PAGE 4 / 46 ──
Table 1 Design principles, the values they serve, and the design-space question each answers. Principles map to multiple values; implementations appear in the sections indicated.
<table><tr><td>Principle</td><td>Values Served</td><td>Design Question</td><td>Sections</td></tr><tr><td>Deny-first with human escalation</td><td>Authority, Safety</td><td>Should unrecognized actions be allowed, blocked, or escalated to the human?</td><td>5, 8, 9</td></tr><tr><td>Graduated trust spectrum</td><td>Authority, Adaptability</td><td>Fixed permission level, or a spectrum users traverse over time?</td><td>5</td></tr><tr><td>Defense in depth with layered mechanisms</td><td>Safety, Authority, Reliability</td><td>Single safety boundary, or multiple overlapping ones using different techniques?</td><td>3, 5</td></tr><tr><td>Externalized programmable policy</td><td>Safety, Authority, Adaptability</td><td>Hardcoded policy, or externalized configs with lifecycle hooks?</td><td>5, 6</td></tr><tr><td>Context as scarce resource with progressive management</td><td>Reliability, Capability</td><td>What is the binding resource constraint, and how to manage it: single-pass truncation or graduated pipeline?</td><td>4, 6, 7, 8</td></tr><tr><td>Append-only durable state</td><td>Reliability, Authority</td><td>Mutable state, checkpoint snapshots, or append-only logs?</td><td>4, 9</td></tr><tr><td>Minimal scaffolding, maximal operational harness</td><td>Capability, Reliability</td><td>Invest in scaffolding-side reasoning, or operational infrastructure that lets the model reason freely?</td><td>3, 4</td></tr><tr><td>Values over rules</td><td>Capability, Authority</td><td>Rigid decision procedures, or contextual judgment backed by deterministic guardrails?</td><td>3, 5, 7</td></tr><tr><td>Composable multi-mechanism extensibility</td><td>Capability, Adaptability</td><td>One unified extension API, or layered mechanisms at different context costs?</td><td>6</td></tr><tr><td>Reversibility-weighted risk assessment</td><td>Capability, Safety</td><td>Same oversight for all actions, or lighter for reversible and read-only ones?</td><td>4, 5, 8</td></tr><tr><td>Transparent file-based configuration and memory</td><td>Adaptability, Authority</td><td>Opaque database, embedding-based retrieval, or user-visible version-controllable files?</td><td>7</td></tr><tr><td>Isolated subagent boundaries</td><td>Reliability, Safety, Capability</td><td>Subagents share the parent&#x27;s context and permissions, or operate in isolation?</td><td>8</td></tr><tr><td>Graceful recovery and resilience</td><td>Reliability, Capability</td><td>Fail hard on errors, or silently recover and reserve human attention for unrecoverable situations?</td><td>4, 5</td></tr></table>
2.2 Design Principles
These values are operationalized through thirteen design principles, each answering a recurring question that production coding agents must resolve. Table 1 summarizes the principles; subsequent sections (Section 3–Section 9) trace each through specific implementation choices.
These principles can be read against three major alternative design families. First, rule-based orchestration: frameworks such as LangGraph (LangChain, Inc., 2024) encode decision logic as explicit state graphs with typed edges, choosing scaffolding over minimal harness. Second, container-isolated execution: SWE-Agent and OpenHands (Yang et al., 2024; Wang et al., 2024b) rely on Docker isolation rather than layered policy enforcement. Third, version-control-as-safety: tools like Aider (Gauthier, 2024) use Git rollback as the primary safety mechanism rather than deny-first evaluation. Claude Code's principle set is distinctive in combining minimal decision scaffolding with layered policy enforcement, values-based judgment with deny-first defaults, and progressive context management with composable extensibility.
2.3 From Values to Architecture
Each value traces through its principles to specific architectural decisions:
4
── PAGE 5 / 46 ──
![](images/0.jpg)

Figure 1 High-level system structure of Claude Code. The system decomposes into seven functional components: user, interfaces, the agent loop, a permission system, tools, state & persistence, and an execution environment. All entry surfaces converge on the same agent loop.
- Human Decision Authority motivates deny-first evaluation, the graduated trust spectrum, append-only state (auditable history), externalized programmable policy, and values-over-rules (Sections 5 to 7 and 9).
- Safety, Security, and Privacy motivates defense in depth, deny-first defaults, reversibility-weighted assessment, externalized policy, and isolated subagent boundaries (Sections 5 and 8).
- Reliable Execution motivates context-as-scarce-resource, append-only durable state, graceful recovery, isolated subagent boundaries, and defense in depth (Sections 4 and 7 to 9).
- Capability Amplification motivates minimal scaffolding, composable extensibility, reversibility-weighted risk, context management, and graceful recovery (Sections 4 to 6).
- Contextual Adaptability motivates transparent file-based memory, composable extensibility, the graduated trust spectrum, and externalized programmable policy (Sections 5 to 7).
These mappings also reveal what the architecture does not do: it does not impose explicit planning graphs on the model's reasoning, does not provide a single unified extension mechanism, and does not restore all session-scoped trust-related state across resume. These absences are consistent with the principle set above.
2.4 An Evaluative Lens: Long-term Capability Preservation
The five values above describe what the architecture is designed to serve. This paper also applies a sixth concern, whether the architecture preserves long-term human capability, as an evaluative lens. This concern is real: Anthropic's own study of 132 engineers and researchers (Huang et al., 2025) documents a “paradox of supervision” in which overreliance on AI risks atrophying the skills needed to supervise it, and independent research (Shen and Tamkin, 2026) finds that developers in AI-assisted conditions score 17% lower on comprehension tests. However, this concern is not prominently reflected as a design driver in the architecture or in Anthropic's stated design values. We therefore treat it not as a co-equal value but as a cross-cutting concern: a question applied across all five values in Section 11, asking whether short-term amplification comes at the cost of long-term human understanding, codebase coherence, and the developer pipeline.
3 Architecture Overview
Building a production coding agent requires answering several recurring design questions: where should reasoning live, how many execution engines are needed, what safety posture to adopt, and what resource to treat as the binding constraint. Claude Code's architecture can be read as one set of answers to these questions. At the implementation level, the system has seven components connected by a main data flow: a user submits a prompt through one of several interfaces, which feeds into a shared agent loop. The agent loop assembles context, calls the Claude model, receives responses that may include tool-use requests, routes those requests through a permission system, and dispatches approved actions to concrete tools that interact with the execution environment. Throughout this process, state and persistence mechanisms record the conversation
5
── PAGE 6 / 46 ──
transcript, manage session identity, and support resume, fork, and rewind operations.
3.1 Design Questions and Running Example
The description is organized around four design questions that recur across production coding agents, each grounding one or more of the design principles identified in Table 1. Each question is introduced here with Claude Code's answer, a note on plausible alternatives, and then demonstrated progressively through Sections 4 to 9.
Where does reasoning live? In Claude Code, the model reasons about what to do; the harness is responsible for executing actions. The model emits tool_use blocks as part of its response, and the harness parses them, checks permissions, dispatches them to tool implementations, and collects results (query.ts). The model never directly accesses the filesystem, runs shell commands, or makes network requests. This separation has a security consequence: because reasoning and enforcement occupy separate code paths, a compromised or adversarially manipulated model cannot override the sandboxing, permission checks, or deny-first rules implemented in the harness. The model's only interface to the outside world is the structured tool_use protocol, which the harness validates before execution. Community analysis of the extracted source estimates that only about 1.6% of Claude Code's codebase constitutes AI decision logic, with the remaining 98.4% being operational infrastructure, a ratio that illustrates how thin the core agent reasoning layer is. Alternative designs invest more heavily in scaffolding-side reasoning: Devin maintains explicit planning and task-tracking structures, while LangGraph (LangChain, Inc., 2024) routes control flow through developer-defined state graphs.
How many execution engines? Claude Code uses a single queryLoop() function that executes regardless of whether the user is interacting through an interactive terminal, a headless CLI invocation, the Agent SDK, or an IDE integration (query.ts). Only the rendering and user-interaction layer varies. Other systems use mode-specific engines: for example, an IDE integration may follow a different code path than a CLI tool, trading uniformity for surface-specific optimization.
What is the default safety posture? Claude Code's default safety posture is deny-first with human escalation: deny rules override ask rules override allow rules, and unrecognized actions are escalated to the user rather than allowed silently (permissions.ts). Multiple independent safety layers (permission rules, PreToolUse hooks, the auto-mode classifier when enabled, and optional shell sandboxing) apply in parallel, so any one can block an action (Section 5). This combines the deny-first with human escalation and defense in depth with layered mechanisms principles from Table 1. Alternative approaches shift the trust boundary elsewhere: SWE-Agent and OpenHands (Yang et al., 2024; Wang et al., 2024b) rely on container-based isolation to contain arbitrary execution, while Aider (Gauthier, 2024) uses git-based rollback as its primary safety net.
What is the binding resource constraint? In Claude Code, the context window (200K for older models, 1M for the Claude 4.6 series) is the binding resource constraint. Five distinct context-reduction strategies execute before every model call (query.ts), and several other subsystem decisions (lazy loading of instructions, deferred tool schemas, summary-only subagent returns) exist to limit context consumption (Section 7). The five-layer pipeline exists because no single compaction strategy addresses all types of context pressure. Budget reduction targets individual tool outputs that overflow size limits. Snip handles temporal depth. Microcompact reacts to cache overhead. Context collapse manages very long histories. Auto-compact performs semantic compression as a last resort. Each layer operates at a different cost-benefit tradeoff, and earlier, cheaper layers run before costlier ones. Alternative architectures treat other resources as the primary bottleneck, for instance compute budget (limiting the number of model calls or tool invocations) or working memory (maintaining an explicit scratchpad rather than relying on the conversation history).
Running example. To ground these principles, we thread a single task through Sections 3 to 9: “Fix the failing test in auth.test.ts.” In this section the user submits the prompt through one of Claude Code’s interfaces. Subsequent sections trace the request through the query loop, permission gate, tool pool, context window, subagent delegation, and session persistence.
6
── PAGE 7 / 46 ──
![](images/0.jpg)

Figure 2 Runtime turn flow showing the end-to-end execution of a single agentic turn: user prompt enters through context assembly, the model is called, tool requests pass through the permission gate, tool results feed back into the loop, and compaction manages context pressure.
3.2 High-Level System Structure
The seven-component model (Figure 1) maps directly to source files:
1. User: Submits prompts, approves permissions, reviews output.
2. Interfaces: Interactive CLI, headless CLI (claude -p), Agent SDK, and IDE/Desktop/Browser. All surfaces feed the same loop.
3. Agent loop: The iterative cycle of model call, tool dispatch, and result collection, implemented as the queryLoop() async generator in query.ts.
4. Permission system: Deny-first rule evaluation (permissions.ts), the auto-mode ML classifier, and hook-based interception (types/hooks.ts).
5. Tools: Up to 54 built-in tools (19 unconditional, 35 conditional on feature flags and user type) assembled via assembleToolPool() (tools.ts), merged with MCP-provided tools. Plugins contribute indirectly through MCP servers and the skill/command registry.
6. State & persistence: Mostly append-only JSONL session transcripts (sessionStorage.ts), global prompt history (history.ts), and subagent sidechain files.
7. Execution environment: Shell execution with optional sandboxing (shouldUseSandbox.ts), filesystem operations, web fetching, MCP server connections, and remote execution.
The data flow follows a left-to-right spine: the user submits a request through an interface, which enters the agent loop. The loop proposes actions to the permission system; approved actions reach tools, which interact with the execution environment and return tool_result messages back to the loop. State and persistence sit alongside the loop, recording transcripts and loading prior session data.
The application entry point main() in main.tsx initializes security settings (including NoDefaultCurrentDirectoryInExePath to prevent Windows PATH hijacking), registers signal handlers for graceful shutdown, and dispatches to the appropriate execution mode.
7
── PAGE 8 / 46 ──
![](images/0.jpg)

Figure 3 Expanded layered architecture showing five subsystem layers: surface (Interactive CLI, Headless CLI, Agent SDK, IDE/Desktop/Browser, UI/renderer), core (agent loop, compaction pipeline), safety/action (permission system incl. auto-mode classifier, hook pipeline, extensibility, built-in tools, MCP tools, shell sandbox, subagent spawning), state (context assembly, runtime state, session persistence, CLAUDE.md + memory, sidechain transcripts), and backend (execution backends, external resources).
3.3 Layered Subsystem Decomposition
The five-layer decomposition (Figure 3) expands the seven-component model into a finer-grained view, mapping each layer to specific source directories.
Surface layer (entry points and rendering). The src/entrypoints/ directory contains startup paths, including the SDK entry with coreTypes.ts, controlSchemas.ts, and coreSchemas.ts. The src/screens/ directory composes full-screen layouts, and src/components/ provides terminal UI building blocks via the ink framework. The interactive CLI launches a terminal UI with real-time streaming, permission dialogs, and progress indicators. The headless CLI (claude -p) creates a QueryEngine instance for single-shot processing. The Agent SDK emits typed events via async generators.
Core layer (agent loop, compaction pipeline). The queryLoop() async generator (query.ts) implements the iterative agent loop, consuming assembled context from the state layer and dispatching tool requests to the safety/action layer. Before every model call, a compaction pipeline of five sequential shapers (query.ts:365–453) manages context pressure: budget reduction, snip, microcompact, context collapse, and auto-compact (Sections 4.3 and 7.3).
Safety/action layer (permission system, hooks, extensibility, tools, sandbox, subagents). The permission system (permissions.ts) implements deny-first rule evaluation with up to seven permission modes (if also counting internal-only bubble and feature-gated auto) (types/permissions.ts) and an integrated auto-mode ML classifier (yoloClassifier.ts) that provides a two-stage fast-filter and chain-of-thought evaluation of tool safety (Section 5). A hook pipeline spanning 27 event types (coreTypes.ts; output schemas in types/hooks.ts) can block, rewrite, or annotate tool requests; of these, 5 are safety-related while the remaining 22 serve lifecycle and orchestration purposes (Section 6). An extensibility subsystem allows plugins and skills to register tools and hooks into the runtime. Tool pool assembly via assembleToolPool() (tools.ts) merges built-in and MCP-provided tools. Approved shell commands pass through a shell sandbox (shouldUseSandbox.ts) that restricts filesystem and network access independently of the permission system. Subagent spawning via AgentTool (AgentTool.tsx, runAgent.ts) is dispatched through the same buildTool() factory as all other tools, re-entering the queryLoop() with an isolated context window and returning only a summary to the parent (Section 8).
8
── PAGE 9 / 46 ──
State layer (context assembly, runtime state, persistence, memory, sidechains). Context assembly is a memoized state loader, not a routing hub: getSystemContext() (context.ts) computes session-level system context including git status, and getUserContext() (context.ts) loads the CLAUDE.md hierarchy and current date. Both are cached for reuse: system context is appended to the system prompt, while user context is added as a user-context message. The src/state/ directory manages runtime application state. Session transcripts are stored as mostly append-only JSONL files at project-specific paths (sessionStorage.ts). The CLAUDE.md + memory subsystem provides a four-level instruction hierarchy (claudemd.ts) from managed settings to directory-specific files, plus auto-memory entries that Claude writes during conversations (Section 7.2). Sidechain transcripts (sessionStorage.ts:247) store each subagent's conversation in a separate file, preventing subagent content from inflating the parent context (Section 8.3). Global prompt history is maintained in history.jsonl (history.ts). Resume and fork operations reconstruct session state from transcripts (conversationRecovery.ts).
Backend layer (execution backends, external resources). Shell command execution with optional sandboxing (BashTool.tsx, PowerShellTool.tsx), remote execution support (src/remote/), MCP server connections across multiple transport variants including stdio, SSE, HTTP, WebSocket, SDK, and IDE-specific adapters (services/mcp/client.ts), and 42 tool subdirectories in src/tools/ implement concrete tool logic.
3.4 QueryEngine: A Clarification
The class documentation at QueryEngine.ts states: “QueryEngine owns the query lifecycle and session state for a conversation. It extracts the core logic from ask() into a standalone class that can be used by both the headless/SDK path and (in a future phase) the REPL.” The class is a conversation wrapper for non-interactive surfaces, not the engine itself. Its constructor accepts a QueryEngineConfig with initial messages, an abort controller, a file-state cache, and other per-conversation state. Its submitMessage() method is an async generator that orchestrates a single turn. The shared query path lives in query() (query.ts), which wraps an internal queryLoop(); QueryEngine delegates to query().
This distinction matters architecturally: the interactive CLI also calls query(), bypassing QueryEngine entirely. The shared code path is the loop function, not the engine class.
3.5 Permission and Safety Layers
The safety-by-default principle is implemented through seven independent layers. A request must pass through all applicable layers, and any single layer can block it:
1. Tool pre-filtering (tools.ts): Blanket-denied tools are removed from the model's view before any call, preventing the model from attempting to invoke them.
2. Deny-first rule evaluation (permissions.ts): Deny rules always take precedence over allow rules, even when the allow rule is more specific.
3. Permission mode constraints (types/permissions.ts): The active mode determines baseline handling for requests matching no explicit rule.
4. Auto-mode classifier: An ML-based classifier evaluates tool safety, potentially denying requests the rule system would allow.
5. Shell sandboxing (shouldUseSandbox.ts): Approved shell commands may still execute inside a sandbox restricting filesystem and network access.
6. Not restoring permissions on resume (conversationRecovery.ts): Session-scoped permissions are not restored on resume or fork.
7. Hook-based interception (types/hooks.ts): PreToolUse hooks can modify permission decisions; PermissionRequest hooks can resolve decisions asynchronously alongside the user dialog (or before it, in coordinator mode).
These layers are described in detail in Section 5.
9
── PAGE 10 / 46 ──
3.6 Context as Bottleneck: Beyond Compaction
Beyond the five-layer compaction pipeline (detailed in Section 7), several other subsystem decisions reflect the context-as-bottleneck constraint:
- CLAUDE.md lazy loading: The base CLAUDE.md hierarchy is loaded at session start, but additional nested-directory instruction files and conditional rules are loaded only when the agent reads files in those directories, preventing unused instructions from consuming context.
- Deferred tool schemas: When ToolSearch is enabled, some tools include only their names in the initial context; full schemas are loaded on demand.
- Subagent summary-only return: Subagents return only summary text to the parent, not their full conversation history (Section 8).
- Per-tool-result budget: Individual tool results are capped at a configurable size, preventing a single verbose output from consuming disproportionate context.
4 Turn Execution: The Agentic Query Loop
When the user submits “Fix the failing test in auth.test.ts,” the input enters a reactive loop, one of several possible orchestration patterns for coding agents. This section examines Claude Code’s choice of a simple while-loop architecture and traces one turn of that loop end-to-end, illustrating three design principles from Table 1: minimal scaffolding with maximal operational harness, context as scarce resource with progressive management, and graceful recovery and resilience.
4.1 The Query Pipeline
Each turn follows a fixed sequence (Figure 2, query.ts):
1. Settings resolution. The queryLoop() function destructures immutable parameters including the system prompt, user context, permission callback, and model configuration.
2. Mutable state initialization. A single State object stores all mutable state across iterations, including messages, tool context, compaction tracking, and recovery counters. The loop's seven continue points (the "continue sites") each overwrite this object in one whole-object assignment rather than mutating fields individually.
3. Context assembly. The function getMessagesAfterCompactBoundary() retrieves messages from the last compact boundary forward, ensuring that compacted content is represented by its summary rather than the original messages.
4. Pre-model context shapers. Five shapers execute sequentially (Section 4.3).
5. Model call. A for await loop over deps.callModel() streams the model's response, passing assembled messages (with user context prepended), the full system prompt, thinking configuration, the available tool set, an abort signal, the current model specification, and additional options including fast-mode settings, effort value, and fallback model.
6. Tool-use dispatch. If the response contains tool_use blocks, they flow to the tool orchestration layer (Section 4.2).
7. Permission gate. Each tool request passes through the permission system (Section 5).
8. Tool execution and result collection. Tool results are added to the conversation as tool_result messages, and the loop continues.
9. Stop condition. If the response contains no tool_use blocks (text only), the turn is complete.
The queryLoop() function is defined as an AsyncGenerator, yielding StreamEvent, RequestStartEvent, Message, TombstoneMessage, and ToolUseSummaryMessage events as it progresses. This generator-based design enables streaming output to the UI layer while maintaining a single synchronous control flow within the loop.
Claude Code's reactive loop follows the ReAct pattern (Yao et al., 2022): the model generates reasoning and tool invocations, the harness executes actions, and results feed the next iteration. Alternative orchestration patterns include explicit graph-based routing (LangChain, Inc., 2024), where control flow is defined as a state machine with typed edges, and tree-search methods (Zhou et al., 2023) that explore multiple action trajectories
10
── PAGE 11 / 46 ──
before committing. Anthropic's own documentation (Schluntz and Zhang, 2024) identifies five composable workflow patterns (prompt chaining, routing, parallelization, orchestrator-workers, and evaluator-optimizer) of which Claude Code primarily uses the orchestrator-workers pattern for subagent delegation (Section 8) while keeping the core loop reactive. The reactive design trades search completeness for simplicity and latency: each turn commits to one action sequence without backtracking.
4.2 Tool Dispatch and Streaming Execution
When the model response contains tool_use blocks, the system chooses between two execution paths. The primary path uses StreamingToolExecutor, which begins executing tools as they stream in from the model response, reducing latency for multi-tool responses. The fallback path uses runTools() in toolOrchestration.ts, which iterates over partitions produced by partitionToolCalls(). Both paths classify tools as concurrent-safe or exclusive. Read-only operations can execute in parallel, while state-modifying operations like shell commands are serialized.
The StreamingToolExecutor (StreamingToolExecutor.ts) manages concurrent execution with two coordination mechanisms:
- Sibling abort controller. Fires when any Bash tool errors, immediately terminating other in-flight subprocesses rather than letting them run to completion.
- Progress-available signal. Wakes up the getRemainingResults() consumer when new output is ready.
Results are buffered and emitted in the order tools were received, so output order stays the same even when tools run in parallel. This is important because the model expects tool results in the same order as its tool-use requests. This concurrent-read, serial-write execution model occupies a middle ground between fully serial dispatch and more aggressive speculative approaches such as PASTE (Sui et al., 2026), which speculatively pre-executes predicted future tool calls while the model is still generating, hiding tool latency through speculation.
The tool result collection phase iterates over updates from either the streaming executor or the synchronous runTools() generator. Each update may carry a tool result, an attachment, or a progress event. A special check detects hook_stopped_continuation attachments: if a PostToolUse hook signals that the turn should not continue, a shouldPreventContinuation flag is set. Results are normalized for the Anthropic API via normalizeMessagesForAPI(), filtering to keep only user-type messages.
4.3 Pre-Model Context Shapers
Five context shapers execute sequentially in query.ts before every model call, each operating on the messagesForQuery array. The five shapers run in sequence, with earlier steps applying lighter reductions before later steps apply broader compaction.
Budget reduction. (applyToolResultBudget()). Enforces per-message size limits on tool results, replacing oversized outputs with content references. Exempt tools (those where maxResultSizeChars is not finite) retain their full output. Content replacements are persisted for agent and session query sources to enable reconstruction on resume. Budget reduction runs before microcompact because microcompact operates purely by tool_use_id and never inspects content; the two compose cleanly.
Snip. (snipCompactIfNeeded(), gated by HISTORY_SNIP). A lightweight trim that removes older history segments, returning {messages, tokensFreed, boundaryMessage}. The snipTokensFreed value is plumbed to auto-compact because the main token counter derives context size from the usage field on the most recent assistant message, and that message survives snip with its pre-snip input_tokens still attached; snip's savings are therefore invisible to the counter unless passed through explicitly.
Microcompact. Fine-grained compression that always runs a time-based path and optionally a cache-aware path (gated by CACHED_MICROCOMPACT). When the cached path is enabled, boundary messages are deferred until after the API response so they can use actual cache_deleted_input_tokens rather than estimates. Returns {messages, compactionInfo} where compactionInfo may include pendingCacheEdits.
11
── PAGE 12 / 46 ──
Context collapse. Gated by CONTEXT_COLLAPSE. A read-time projection over the conversation history. The source comments explain: “Nothing is yielded; the collapsed view is a read-time projection over the REPL’s full history. Summary messages live in the collapse store, not the REPL array. This is what makes collapses persist across turns.” Unlike the other shapers, context collapse does not mutate the REPL’s stored history; it replaces the messagesForQuery array with a projected view via applyCollapsesIfNeeded(), so the model sees the collapsed version while the full history remains available for reconstruction.
Auto-compact. The fifth shaper, triggering a full model-generated summary via compactConversation() in compact.ts. This function executes PreCompact hooks, creates a summary request using getCompactPrompt(), and calls the model to produce a compressed summary. The result feeds into buildPostCompactMessages() (compact.ts). Auto-compact fires only when the context still exceeds the pressure threshold after all four previous shapers have run.
4.4 Recovery Mechanisms
The query loop implements several recovery mechanisms for edge cases:
- Max output tokens escalation: When the response hits the output token cap, the system can retry with an escalated limit, subject to a GrowthBook flag and the absence of an existing override or environment-variable cap. Up to three recovery attempts are allowed per turn (MAX_OUTPUT_TOKENES_RECOVERY_LIMIT = 3).
- Reactive compaction (gated by REACTIVE_COMPACT): When the context is near capacity, reactive compact summarizes just enough to free space. The hasAttemptedReactiveCompact flag ensures this fires at most once per turn.
- Prompt-too-long handling: If the API returns a prompt_too_long error, the loop first attempts context-collapse overflow recovery and reactive compaction. Only after these fail does it terminate with reason: 'prompt_too_long'.
- Streaming fallback: The onStreamingFallback callback handles streaming API issues, allowing the loop to retry with a different strategy.
- Fallback model: The fallbackModel parameter enables switching to an alternative model if the primary model fails.
4.5 Stop Conditions
Multiple conditions can terminate the loop:
1. No tool use: The model produces only text content (the primary stop condition).
2. Max turns: The configurable maxTurns limit is reached.
3. Context overflow: The API returns prompt_too_long.
4. Hook intervention: A PostToolUse hook sets hook_stopped_continuation.
5. Explicit abort: The abortController signal fires.
The turn pipeline determines how tool requests are orchestrated and recovered. The next section examines the gate that determines whether each request is permitted to execute at all.
5 Tool Authorization and Control Boundaries
Production coding agents adopt different safety architectures: layered policy enforcement, OS-level sandboxing, or version-control-based rollback. Claude Code combines the first two, implementing four design principles from Table 1: deny-first with human escalation, graduated trust spectrum, defense in depth with layered mechanisms, and reversibility-weighted risk assessment.
When Claude decides to execute a tool (for example, running npm test via BashTool to reproduce the auth test failure), the request enters the permission pipeline shown in Figure 4. Every tool invocation passes through the permission system, and the default behavior is to deny or ask rather than allow silently. This default is motivated by a documented behavioral pattern: Anthropic's auto-mode analysis (Hughes, 2026)
12
── PAGE 13 / 46 ──
![](images/0.jpg)

<table><tr><td>Principle</td><td>Description</td></tr><tr><td>Progressive Trust</td><td>The agent starts with minimal autonomy; users expand it by approving tool invocations that become permanent rules.</td></tr><tr><td>Deny-First, Ask-by-Default</td><td>Deny rules always win, even under looser modes. If no rule matches, the gate asks the user instead of silently running or blocking.</td></tr><tr><td>Composable Policy</td><td>Three mechanisms shape policy: declarative rules, global trust modes, and programmable hooks, each independently configurable.</td></tr></table>
Figure 4 Permission gate overview and design principles.
found that users approve approximately 93% of permission prompts, indicating that approval fatigue renders interactive confirmation behaviorally unreliable as a sole safety mechanism. Because users habitually approve without careful review, the system must maintain safety independently of human vigilance. This motivates the architectural commitment to deny-first evaluation, blanket-deny pre-filtering, and sandboxing as independent layers that operate regardless of user attentiveness.
5.1 Permission Modes and Rule Evaluation
Seven permission modes exist across the type definitions (5 external modes at types/permissions.ts; auto added conditionally; bubble in the type union):
1. plan: The model must create a plan; execution proceeds only after user approval.
2. default: Standard interactive use. Most operations require user approval.
3. acceptEdits: Edits within the working directory and certain filesystem shell commands (mkdir, rmdir, touch, rm, mv, cp, sed) are auto-approved; other shell commands require approval.
4. auto: An ML-based classifier evaluates requests that do not pass fast-path checks (gated by TRANSCRIPT_CLASSIFIER).
5. dontAsk: No prompting, but deny rules are still enforced.
6. bypassPermissions: Skips most permission prompts, but safety-critical checks and bypass-immune rules still apply.
7. bubble: Internal-only mode for subagent permission escalation to the parent terminal.
The five externally visible modes (acceptEdits, bypassPermissions, default, dontAsk, plan) are defined in the EXTERNAL_PERMISSION_MODES array. The auto mode is conditionally included only when the TRANSCRIPT_CLASSIFIER feature flag is active. The bubble mode exists in the type union but not in either mode array; it is used internally for subagent permission escalation (Section 8).
Permission rules are evaluated in deny-first order (permissions.ts). The toolMatchesRule() function checks deny rules first: a deny rule always takes precedence over an allow rule, even when the allow rule is more specific. A broad deny (“deny all shell commands”) cannot be overridden by a narrow allow (“allow npm test”). The rule system supports tool-level matching (by tool name) and content-level matching (matching specific tool input patterns, such as Bash(prefix:npm)).
The seven modes span a graduated autonomy spectrum, from plan (user approves all plans before execution) through default and acceptEdits to bypassPermissions (minimal prompting). This gradient reflects a recurring design tension: as autonomy increases, the system must shift from interactive approval to automated safety checks. Other agent systems resolve this tension differently. SWE-Agent and OpenHands (Yang et al., 2024; Wang et al., 2024b) use Docker container isolation, sandboxing the agent's entire execution environment rather than evaluating individual tool invocations. Aider (Gauthier, 2024) relies on Git as a safety net, making all changes reversible through version control. Claude Code's approach layers multiple policy-enforcement mechanisms on top of optional container sandboxing, trading simplicity for fine-grained control over individual actions.
13
── PAGE 14 / 46 ──
5.2 The Authorization Pipeline
The full authorization pipeline proceeds through several stages:
Pre-filtering. Before any tool request reaches runtime evaluation, filterToolsByDenyRules() (tools.ts) strips blanket-denied tools from the model's view entirely at tool pool assembly time. The documentation states: "Uses the same matcher as the runtime permission check, so MCP server-prefix rules like mcp__server strip all tools from that server before the model sees them." This prevents the model from attempting to invoke forbidden tools, so the model does not waste calls on them.
PreToolUse hook. Registered hooks fire as part of the permission pipeline. A PreToolUse hook can return a permissionDecision to deny or ask, or an updatedInput that modifies the tool's input parameters (types/hooks.ts). A hook allow does not bypass subsequent rule-based denies or safety checks. In the interactive path, the user dialog is queued first and hooks run asynchronously; coordinator and similar background-agent paths await automated checks before showing the dialog.
Rule evaluation. The deny-first rule engine evaluates the request. MCP tools are matched by their fully qualified mcp__server__tool name, and server-level rules match all tools from that server.
Permission handler. The handler in useCanUseTool.tsx branches into one of four paths based on runtime context:
1. Coordinator: For multi-agent coordination mode. Attempts automated resolution (classifier, hooks, rules) before falling back to user interaction.
2. Swarm worker: Handles worker agents in a multi-agent swarm with their own resolution logic.
3. Speculative classifier: When BASH_CLASSIFIER is enabled and the tool is BashTool, a speculative classifier races a pre-started classification result against a timeout. If the classifier returns with high confidence, the tool is approved instantly without user interaction.
4. Interactive: The fallback path. Presents the standard user approval dialog through the terminal UI.
In coordinator and some background paths, automated resolution is attempted before user interaction. In the standard interactive path, the dialog can appear first while hooks or classifier checks continue in parallel. When the classifier or a deny rule blocks an action, the system treats the denial as a routing signal rather than a hard stop: the model receives the denial reason, revises its approach, and attempts a safer alternative in the next loop iteration. The PermissionDenied hook event (Section 6) enables external code to observe and respond to these denials programmatically. This recovery-oriented design means that permission enforcement shapes the agent's behavior rather than simply halting it.
5.3 Auto-Mode Classifier and Hook Lifecycle
The auto-mode classifier (yoloClassifier.ts) participates in permission decisions when enabled. When TRANSCRIPT_CLASSIFIER is enabled, the classifier loads three prompt resources:
- A base system prompt.
- An external permissions template.
- For Anthropic-internal users, a separate internal template.
The classifier evaluates the proposed tool invocation against the conversation transcript and the permission template, producing an allow, deny, or request for manual approval. The function is UsingExternalPermissions() checks USER_TYPE and a forceExternalPermissions config flag to select the appropriate template.
Of the 27 hook events defined in the source (coreTypes.ts), five participate directly in the permission flow, each with a specific Zod-validated output schema (types/hooks.ts):
- PreToolUse: Can return permissionDecision (deny or ask, but allow does not bypass subsequent checks), permissionDecisionReason, and updatedInput (modify parameters).
- PostToolUse: Can inject additionalContext and, for MCP tools, return updatedMCPToolOutput to modify results before they enter the context.
14
── PAGE 15 / 46 ──
- PostToolUseFailure: Can inject additionalContext for error-specific guidance.
- PermissionDenied: Can provide retry guidance after auto-mode denials.
- PermissionRequest: Can return a decision of allow or deny. In coordinator and similar paths, this can resolve before the user dialog. In the standard interactive path, it can also run alongside the dialog.
For non-MCP tools, the tool_result is emitted before the PostToolUse hook fires. For MCP tools, the result is delayed until after post hooks have run, enabling updatedMCPToolOutput to take effect.
5.4 Shell Sandboxing
Shell sandboxing provides an additional layer of protection for Bash and PowerShell commands (shouldUseSandbox.ts). The shouldUseSandbox() function checks whether sandboxing is globally enabled, whether the invocation has opted out, and whether the command matches any exclusion patterns.
When active, the sandbox provides filesystem and network isolation independent of the application-level permission model. A command can be permission-approved but still sandboxed, or permission-denied and never reach the sandbox check. The two systems operate on different axes: authorization versus isolation.
The layered safety architecture rests on an independence assumption: if one layer fails, others catch the violation. However, several layers share common performance constraints. Security researchers (Adversa.ai, 2026) have documented that commands with more than 50 subcommands fall back to a single generic approval prompt instead of running per-subcommand deny-rule checks, because per-subcommand parsing caused UI freezes. This example demonstrates that defense-in-depth can degrade when its layers share failure modes, a structural tension between safety and performance analyzed further in Section 11.3.
The permission pipeline governs whether a tool request executes. The next section examines what determines which tools exist in the first place: the extensibility architecture that assembles the model's action surface.
6 Extensibility: MCP, Plugins, Skills, and Hooks
A recurring design question for coding agents is how to structure the extension surface: a single unified mechanism, a small number of specialized mechanisms, or a layered stack with different context costs. The analysis here illustrates two design principles from Table 1: composable multi-mechanism extensibility and externalized programmable policy. Returning to the running example, once Claude is trying to repair auth.test.ts and the earlier npm test request has been mediated by the permission system (Section 5), the next question is what extension-enabled action surface is available for the repair. When a turn begins in Claude Code, the model sees not just built-in tools like BashTool and FileReadTool, but also database query tools from an MCP server, a custom lint skill from .claude/skills/, and tools contributed by an installed plugin. These arrive through four mechanisms that extend the agent at different points of the loop: MCP servers provide external tool integration, plugins package and distribute bundles of components, skills inject domain-specific instructions, and hooks intercept the tool execution lifecycle. Anthropic's documentation (Anthropic, 2026d) presents a broader view that includes CLAUDE.md (Section 7) and subagents (Section 8) alongside the four mechanisms analyzed here. We treat CLAUDE.md and subagents in their own sections because they operate in different subsystems (context construction and delegation, respectively), but the context-cost ordering is architecturally significant: it reveals how each extension point trades off expressiveness against the bounded context window.
6.1 Four Extension Mechanisms
The mechanisms are implemented in distinct source directories (Figure 5) and serve different integration patterns:
MCP servers. The Model Context Protocol is the primary external tool integration path. MCP servers are configured from multiple scopes: project, user, local, and enterprise, with additional plugin and claude.ai servers merged at runtime (services/mcp/config.ts). The MCP client (services/mcp/client.ts) supports multiple transport types: stdio, SSE, HTTP, WebSocket, SDK, plus IDE-specific variants (sse-ide, ws-ide) and
15
── PAGE 16 / 46 ──
# one turn of Claude Code's agent loop
while not stopped:
    # a) assemble -- build what the model sees
    context = assemble(
    system_prompt,    # instructions header
    tool_schemas,    # callable tool signatures
    history,    # prior turn messages
    hook_additions,    # pushed in by hooks
    )
    # b) model -- pick the next action
    action = model(context, tools)    # flat tool pool
    if action.is_text_only():
    stopped = run_stop_hooks(action)    # may veto
    continue
    # c) execute -- gate and run the tool call
    if not permitted(action):
    continue
    action = run_pre_tool_hooks(action)    # block/rewrite
    result = execute(action)    # tool runs here
    result = run_post_tool_hooks(result)    # mutate/annotate
    history.append(action, result)
a) assemble(): what the model sees
<table><tr><td>Element</td><td>What it does</td></tr><tr><td>CLAUDE.md files</td><td>Loaded into context; files above the working directory load at startup, and subdirectory files load on demand</td></tr><tr><td>Skill descriptions</td><td>Advertises skills so the model calls SkillTool</td></tr><tr><td>MCP resources &amp; prompts</td><td>Non-tool content an MCP server pushes</td></tr><tr><td>Output style</td><td>Replaces the response-formatting system block</td></tr><tr><td>UserPromptSubmit hook</td><td>Inject context, or block, on every user turn</td></tr><tr><td>SessionStart hook</td><td>One-shot context injection at session start</td></tr></table>
b model(): what the model can reach
<table><tr><td>Element</td><td>What it does</td></tr><tr><td>Built-in tools</td><td>Read / Edit / Bash / ... shipped with the CLI</td></tr><tr><td>MCP tools</td><td>Tools from any MCP server, in the same flat pool</td></tr><tr><td>SkillTool</td><td>Meta-tool that launches a skill by name</td></tr><tr><td>AgentTool</td><td>Meta-tool that spawns a sub-agent recursively</td></tr></table>
execute(): whether / how an action runs
<table><tr><td>Element</td><td>What it does</td></tr><tr><td>Permission rules</td><td>Declarative allow / deny / ask per call</td></tr><tr><td>PreToolUse hook</td><td>Approve / block / rewrite a tool call</td></tr><tr><td>PostToolUse hook</td><td>Mutate output or inject context after a call</td></tr><tr><td>Stop hook</td><td>Force the loop to keep going at model stop</td></tr><tr><td>SubagentStop hook</td><td>Same, for sub-agents spawned via AgentTool</td></tr><tr><td>Notification hook</td><td>External side effects on user notifications</td></tr></table>
Figure 5 Where Claude Code's extension mechanisms plug into the agent loop. The pseudocode on the left is a zoom-in of the Agent Loop block in Figure 1. Every agent loop has three injection points: (a) assemble() controls what the model sees, (b) model() controls what it can reach, and (c) execute() controls whether and how an action actually runs.
an internal claudeai-proxy. Each connected server contributes tool definitions as MCPTool objects. Dedicated built-in tools ListMcpResourcesTool and ReadMcpResourceTool provide access to MCP resources.
Plugins. Plugins serve a dual role: they are both a packaging format and a distribution mechanism. The PluginManifestSchema (utils/plugins/schemas.ts) accepts ten component types: commands, agents, skills, hooks, MCP servers, LSP servers, output styles, channels, settings, and user configuration. The plugin loader (utils/plugins/pluginLoader.ts) validates manifests and routes each component to its respective registry: commands and skills surface through the SkillTool meta-tool, agents appear in definitions consumed by AgentTool, hooks merge into the hook registry, MCP and LSP servers fold into their standard configurations, and output styles modify response formatting. A single plugin package can therefore extend Claude Code across multiple component types simultaneously, making plugins the primary distribution vehicle for third-party extensions.
Skills. Each skill is defined by a SKILL.md file with YAML frontmatter. The parseSkillFrontmatterFields() function (loadSkillsDir.ts) parses 15+ fields including display name, description, allowed tools (granting the skill access to additional tools), argument hints, model overrides, execution context ('fork' for isolated execution), associated agent definitions, effort levels, and shell configuration. Skills can define their own hooks, which register dynamically on invocation. Bundled skills are registered in-memory at startup. When invoked, the SkillTool meta-tool injects the skill's instructions into the context.
16

Cerebras max output tokens per agent call

8192 40960

Fast demo mode: skip RAG chunks and citation graph

Generate RAG chunks

Generate citation graph

Include OCR text in download bundle