Claude Code is a thin agent loop wrapped in a thick safety harness

Anthropic publishes user docs for Claude Code, not architecture docs. Liu and colleagues at MBZUAI's VILA Lab read the extracted TypeScript source for v2.1.88 line by line and wrote down what they found. The result is a 46-page reverse-engineering of a production coding agent that runs shell commands, edits files, and calls external services on a developer's behalf.

Their central finding is a ratio. By community estimate, roughly 1.6% of the codebase is the agent's decision logic. The other 98.4% is the harness: permission gates, tool routing, context compaction, extensibility plumbing, recovery logic, session persistence. The model decides; everything else exists to make sure it can decide safely and that its decisions actually run.

This inverts the dominant pattern in agent engineering. Frameworks like LangGraph push decision logic into developer-defined state graphs. Devin pairs an explicit planner with the model. Claude Code goes the other way: give the model maximum latitude inside a deterministic environment so rich that good judgment is the only thing it needs to supply.

The authors extract five values that motivate the architecture: human decision authority, safety and security, reliable execution, capability amplification, and contextual adaptability. Each maps to design principles, and each principle maps to specific source files.

The core is unromantic. A queryLoop() async generator runs the model, parses tool-use blocks, checks permissions, dispatches tools, collects results, and loops until the model stops producing tool calls. That is it. The same loop serves the interactive CLI, the headless CLI, the SDK, and IDE integrations. Only the rendering layer changes.

Everything interesting happens around the loop. Seven independent safety layers, from blanket tool pre-filtering through deny-first rules through an ML classifier through shell sandboxing, must all be satisfied before a tool runs. Five context shapers compact the conversation before every model call. Four extension mechanisms (MCP servers, plugins, skills, hooks) plug in at different context costs. Subagents spawn with isolated context windows and return only summaries to the parent.

The deny-first design exists because Anthropic measured that users approve 93% of permission prompts. Interactive confirmation is behaviourally unreliable, so safety cannot rest on human vigilance. The architectural response is not more dialogs but fewer: defined boundaries within which the agent can act freely, and multiple independent layers that block bad actions whether or not the user is paying attention.

That defense-in-depth rests on an independence assumption that breaks under pressure. Security researchers documented that shell commands with more than 50 subcommands fall back to a single generic prompt because per-subcommand parsing froze the UI. When safety layers share performance constraints, they can degrade together.

Two CVEs disclosed in 2025 and 2026 exploit a temporal gap the paper makes explicit: extensions (hooks, MCP servers) load before the trust dialog, creating a pre-trust window where the permission system is not yet engaged. The spatial diagram is correct; the temporal ordering is the attack surface.

The five-layer compaction pipeline reflects a clear position: the context window is the scarce resource. No single strategy handles every kind of pressure, so the layers escalate. Budget reduction caps individual tool outputs. Snip trims old history. Microcompact does cache-aware compression. Context collapse projects a virtual view. Auto-compact summarises the lot.

CLAUDE.md memory is plain Markdown in a four-level hierarchy from OS-managed to gitignored-local. The authors note this is a deliberate trade: file-based memory is inspectable, editable, and version-controllable, where embedding-based retrieval is none of those things. Compliance is probabilistic; the deterministic enforcement lives in the permission rules.

The flip side is opacity. Context collapse operates without user-visible output. Microcompact's cache-aware decisions depend on prompt caching the user cannot see. Five interacting layers, several behind feature flags, produce behaviour difficult to predict from any single config file.

The paper applies a sixth concern as an evaluative lens rather than a design value: long-term human capability preservation. The architecture amplifies short-term productivity but offers limited mechanisms that explicitly preserve long-term understanding or codebase coherence.

The supporting evidence comes from adjacent work, not Claude Code directly. A 16-developer RCT (Becker et al. 2025) found AI tools made experienced developers 19% slower despite a perceived 20% improvement. A causal analysis of 807 Cursor-using repositories (He et al. 2025) found code complexity rose 40.7%, with the initial velocity spike dissipating to baseline by month three. An EEG study (Kosmyna et al. 2025) found weakened neural connectivity in LLM users that persisted after the tool was removed.

The OpenClaw comparison is the paper's sharpest move. The same design questions recur, but a multi-channel personal assistant gateway answers them differently: perimeter-level access control instead of per-action evaluation, gateway-wide plugin registries instead of per-window context costs, multi-agent routing instead of subagent delegation. The two systems can even compose, with OpenClaw hosting Claude Code as a coding harness. The design space is layered, not flat.