# Claude Code Architecture: Hooks, Subagents, and Context Explained

> When you run a command in Claude Code, you are driving a deterministic state machine governed by strict memory caps, shell hook contracts, and subagent boundaries. Here is how Claude Code actually works under the hood, how exit code 2 enforces hard guardrails on tool execution, and why isolated subagents prevent context window exhaustion.

- Published: 2026-11-01
- Duration: 7:00
- Video: https://www.youtube.com/watch?v=QH4jZrcI-2M
- Article: https://buildverse.fun/videos/claude-code-architecture-hooks-subagents-and-context-explain
- Source: Buildverse (https://buildverse.fun)

## Chapters

- [0:00](https://www.youtube.com/watch?v=QH4jZrcI-2M&t=0) Why Claude Code is a deterministic state machine
- [0:50](https://www.youtube.com/watch?v=QH4jZrcI-2M&t=50) Memory caps: the 200-line and 4 MiB rules
- [1:58](https://www.youtube.com/watch?v=QH4jZrcI-2M&t=118) The PreToolUse hook contract: exit codes 0, 1, and 2
- [3:35](https://www.youtube.com/watch?v=QH4jZrcI-2M&t=215) Subagent context architecture: isolated vs forked
- [5:00](https://www.youtube.com/watch?v=QH4jZrcI-2M&t=300) The /compact routine & deferred MCP schemas
- [6:18](https://www.youtube.com/watch?v=QH4jZrcI-2M&t=378) Four architectural rules recap

## Commands & links

```text
Claude Code memory documentation: https://code.claude.com/docs/en/memory.md
Claude Code hooks reference: https://code.claude.com/docs/en/hooks.md
Claude Code subagents guide: https://code.claude.com/docs/en/sub-agents.md
Claude Code context window guide: https://code.claude.com/docs/en/context-window.md
Claude Code MCP architecture: https://code.claude.com/docs/en/mcp.md
```

## Article

### Why Claude Code is a deterministic state machine

When you run a command in Claude Code, you are not just streaming tokens to an AI model. You are driving a deterministic execution engine governed by strict startup limits, pre-tool shell contracts, and subagent memory boundaries.

Most developers treat the CLI as an open-ended chatbot, and then wonder why their instructions get silently ignored, why safety scripts fail to stop rogue commands, or why their context window fills up after three prompt turns. The official documentation documents the exact mechanics, but almost nobody reads the architectural specifications.

Here is how Claude Code actually works under the hood, how its exit code blocking contract enforces hard guardrails, and why isolated subagents are the only way to keep your primary context clean.

### Memory caps: the 200-line and 4 MiB rules

Start with what loads when you open a session. md file to configure your build rules, coding conventions, and architectural standards. md has a hard file size ceiling of four megabytes. If your instructions file exceeds four megabytes, Claude Code skips it entirely without loading a single line.

Even more critical is how auto memory operates. md file, it only loads the first two hundred lines, or twenty-five kilobytes of text, when starting a new conversation. Every memory, guideline, or lesson written past line two hundred is completely ignored at session startup. If you let that file grow unchecked, your oldest or newest rules silently disappear from the model prompt.

Keep your always-on rules concise and inside that two hundred line limit, and move specialized guidelines into skills that load on demand. Now look at the tool execution pipeline.

### The PreToolUse hook contract: exit codes 0, 1, and 2

When Claude Code decides to edit a file, run a shell command, or call an external service, it does not execute the action immediately. Instead, it passes through the PreToolUse hook lifecycle. This is where you can build deterministic guardrails that no prompt hallucination can bypass. A PreToolUse hook executes a local shell script before the tool runs, and its behavior is dictated by a strict three-state exit code contract.

If your hook script returns exit code zero, it represents success, and Claude Code allows the tool operation to proceed. If your hook returns exit code one, the CLI treats it as a non-blocking warning, displaying the output but continuing execution unless you explicitly configured failure blocking in your settings. But the most powerful mechanism is exit code two.

In the Claude Code hook architecture, exit code two is the designated blocking error code. The moment your hook exits with code two, tool execution halts immediately, the command is cancelled, and the standard error output is fed directly back to Claude as the explicit blocking reason. This allows you to enforce absolute security rules, like blocking destructive database drops or preventing unauthorized file overwrites, with zero model ambiguity.

After a tool successfully finishes, PostToolUse hooks trigger, receiving both the original tool input and the output payload in JSON format through standard input for logging or automated testing.

### Subagent context architecture: isolated vs forked

The next architectural layer is subagent orchestration. In a standard terminal session, every file you read, every grep command you run, and every directory listing you inspect gets permanently appended to your conversation history. If Claude inspects ten files searching for a bug, thousands of tokens of raw code enter your context window, driving up caching costs and pushing earlier instructions out of memory.

Subagents solve this by decoupling exploration from execution. When Claude Code launches an isolated subagent, that subagent executes with a completely empty, fresh context window. Every file read, grep search, and codebase exploration performed inside the isolated subagent stays strictly inside that subagent. None of those intermediate tool calls enter your primary conversation context.

When the subagent finishes, it returns only its synthesized final response back to the parent session. If the subtask requires existing context, Claude Code can spawn a forked subagent instead. A forked subagent inherits conversation history up to the exact fork point, but all subsequent tool calls and file reads remain isolated within the fork.

### The /compact routine & deferred MCP schemas

By offloading heavy codebase research to subagents, your main session stays lean and responsive. Finally, look at context management and the compaction contract. As a session progresses, you will eventually reach the limits of your active context window. Running the slash compact command triggers an automated compaction routine.

The CLI summarizes your conversation history into a structured markdown overview, freeing up token capacity so you can continue working without restarting your terminal. md file fresh from disk, ensuring your primary project rules remain pristine. However, any path-specific rules or nested instructions that were loaded dynamically during the session get summarized away during compaction unless they exist in the root configuration file.

Additionally, Claude Code manages Model Context Protocol integrations with deferred tool schemas. Rather than loading thousands of tokens of verbose JSON schema definitions for every connected MCP server at session startup, tool schemas are deferred until the model actually calls them. Only the tool names and top-level descriptions reside in startup memory, keeping your initial context consumption minimal.

### Four architectural rules recap

Here is the recap. First, respect memory limits. md stays well below the four megabyte cap. Second, use exit code two in your PreToolUse hooks whenever you need a deterministic, non-negotiable blocking guardrail.

Third, leverage isolated and forked subagents to keep heavy file exploration out of your primary context window. And fourth, remember that slash compact refreshes root rules while summarizing dynamic path instructions. If this helped, subscribe. Build with AI.

For real.