The most instructive agent architecture in the world is not open source, and that is precisely why it is worth studying.
Last week I wrote about the MBZUAI study that decompiled Claude Code and found that 98.4% of it is harness infrastructure, with only 1.6% left for the model’s actual decision logic. The number made for a good provocation. But a ratio is not a lesson. The lesson is in what that 98.4% actually does, layer by layer, and why four independent teams drew the same boundaries around it without coordinating. If you want a reference implementation for the runtime layer, this is as close as you are going to get without Anthropic handing you the source.
The study, “Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems” (arxiv 2604.14228), breaks the architecture into seven components: User, Interfaces, Agent Loop, Permission System, Tools, State & Persistence, and Execution Environment. The names are unglamorous. The decisions inside them are where the real engineering lives.
Start with the agent loop and the single clearest architectural line in the whole system. The model emits tool_use blocks. The harness parses them, checks permissions, dispatches them to tool implementations, and collects the results. The model never touches the filesystem, never runs a shell command, never makes a network request. Reasoning and enforcement live in two separate code paths. That separation is not a convenience. It is a security property. A compromised model, or one that has been adversarially manipulated through its context, cannot override the sandboxing, the permission checks, or the deny-first rules, because it has no direct path to the thing those rules protect.
Most agent frameworks I have audited do not enforce this line. They hand the model a tool and let it call it. The permission layer, if one exists, is advisory. The model is trusted to behave. Claude Code inverted that assumption and built the trust boundary into the topology of the code.
The permission system is the most instructive piece for anyone building a runtime today. It has seven modes, and it evaluates deny-first, with a blanket-deny pre-filter that runs before anything else. The default posture is refusal, not consent. That choice is motivated by an empirical finding I have not been able to shake since I read it: Anthropic’s own auto-mode analysis found that users approve roughly 93% of permission prompts. Approval fatigue makes interactive confirmation behaviorally worthless as a safety mechanism. The system cannot rely on a human to catch the bad call, because the human has already trained themselves to click yes. So Claude Code layers an ML-based classifier, sandboxing, and the deny-first gate so that safety holds even when attention does not.
Context management is the second place the reference implementation earns its keep. Claude Code runs against a context window that is never big enough, and it handles that with a five-layer compaction pipeline. When the agent is about to overflow, it does not just truncate to the first N tokens and hope. It compacts progressively, preserving whatever matters most at each stage, and it has four extension mechanisms to pull in what the model needs: MCP for tools, plugins, skills, and hooks. The compaction pipeline and the extension mechanisms are two halves of the same insight. The window is bounded, and everything else is a strategy for deciding what deserves to be inside it.
That is the part most builders get wrong. They treat context as a bucket to fill and then empty. Claude Code treats context as a managed resource, with an explicit pressure-handling plan and an explicit mechanism for re-expanding what got compacted away. The failure mode of the bucket approach is silent. The agent forgets something critical, and you do not find out until it behaves strangely thirty turns later.
State and persistence follow the same discipline. Claude Code uses append-oriented session storage. Every event is written once, in order, and the session is reconstructed from the log. That is a deceptively simple decision. It means a crash never loses the prefix of what happened, a restart can replay or resume cleanly, and there is an audit trail of every action the agent took. Compare that to the frameworks that keep agent state floating in memory and lose everything the moment the process dies. Restate, which we covered last week, gives durable execution as an external service. Claude Code bakes an append-only equivalent into its own bookkeeping.
The pieces assemble into something coherent because they are all answers to the same underlying question: what does a model need to be trusted to act, and what does the system need to guarantee it survives whatever the model does? The study identifies five human values driving the whole design: human decision authority, safety and security, reliable execution, capability amplification, and contextual adaptability. The permission layer serves the first two. The state design serves reliable execution. The extension mechanisms serve capability amplification. The compaction pipeline serves contextual adaptability.
Here is where the honest assessment has to come in, because this is not a victory lap. Claude Code is not a neutral reference architecture. It is Anthropic’s answer to Anthropic’s constraints. The study puts it plainly: Claude Code and OpenClaw answer the same recurring design questions with different architectural answers. OpenClaw routes everything through a unified event queue. Claude Code layers deny-first permissions and a compaction pipeline. Neither is wrong. They are optimizing for different guarantees, different deployment models, different threat models.
The transferable lesson is not “copy Claude Code.” It is the specific set of decisions that turn out to be load-bearing, and those decisions are remarkably consistent across the good runtimes I have seen this month. Separate reasoning from enforcement, and make the separation structural rather than stylistic. Default to deny, not consent, and assume the human will click yes out of fatigue. Treat the context window as a bounded resource with an explicit management plan. Persist state so a crash is a resume point, not a reset. Make the whole thing auditable by construction.
The dark side of the study makes the same point from the other direction. The real-world vulnerabilities that have caused developer exposure were not in the model’s inference logic. They were in the permission pipeline, the hooks system, and the sandbox. The components the four teams classified as harness infrastructure are exactly the components that failed in the field. When the model was the weak point, it hallucinated a bad tool call. When the harness was the weak point, it let something through that should never have reached the filesystem. The second failure is the one you cannot blame on the model, and the one that gets people fired.
If you are building an agent runtime right now, you do not need Anthropic’s source code to learn from their decisions. You need to ask the same questions and answer them honestly. Does your model have a direct path to the filesystem, or does every action pass through a permission gate it cannot bypass? When your context window fills, is there a plan, or is there a truncation bug waiting to surface? If the process dies on step 37, do you resume, or do you start the whole workflow over from nothing? Claude Code has answers to all three. The answers are not proprietary. The willingness to build them before the demo is what separates a harness from a conversation.
The model was never the hard part. Four teams looking at the same artifact proved that the interesting engineering is in the other 98.4%. That is where the mistakes are made, where the breaches happen, and where the survivors get built.
If this was useful, forward it to one engineer who needs less noise in their feed.