Claude Code Architecture Explained: Agent Loop, Tool System, and Permission Model (Rust Rewrite Analysis)

def run_turn(user_input):
 session.messages.append(UserMessage(user_input))


`while True:
 if iterations > max_iterations:
 raise Error("Max iterations exceeded")

 response = api_client.stream(system_prompt, session.messages)

 assistant_message = parse_response(response)
 session.messages.append(assistant_message)

 tool_calls = extract_tool_uses(assistant_message)

 if not tool_calls:
 break

 for tool_name, input in tool_calls:
 permission = authorize(tool_name, input)

 if permission == Allow:
 result = tool_executor.execute(tool_name, input)
 session.messages.append(ToolResult(result))
 else:
 session.messages.append(
 ToolResult(deny_reason, is_error=True)
 )`


Enter fullscreen mode
 


 Exit fullscreen mode


`---

## A Concrete Example

User asks:

> “What is 2 + 2?”

Execution flow:

| Step | Message State | Description |
| ------ | -------------------------- | ------------------------ |
| Start | `[User("2+2")]` | User input |
| API #1 | + Assistant (calls tool) | Model decides to compute |
| Tool | + ToolResult("4") | Tool executes |
| API #2 | + Assistant("Answer is 4") | Final answer |
| End | Loop exits | No more tool calls |

Termination condition:

> The model decides to stop calling tools.

---

## Key Design Insight #1: Messages = State

Instead of managing state explicitly:

* The system stores everything as messages
* The full state is reconstructible from history

Benefits:

* Easy persistence (save session)
* Easy replay (debugging)
* Easy compression (context trimming)

> One append-only structure solves multiple problems.

---

## Key Design Insight #2: Errors Are Feedback

When a tool is denied:

* The system does **not** crash
* It returns an error as a `ToolResult`

This is fed back to the model.

Result:

* The model adapts
* Chooses alternative strategies

> Failure becomes part of the reasoning loop.

---

## Tool System: 18 Tools, One Pattern

The Rust version implements 18 built-in tools in a unified structure.

---

### Three Layers


```plaintext
1. Tool Registry → defines schema and permissions
2. Dispatcher → routes tool calls
3. Implementation → executes logic`


Enter fullscreen mode
 


 Exit fullscreen mode


### Tool Specification


```json id="i9j1sx"
{
 "name": "bash",
 "description": "Execute shell commands",
 "input_schema": {
 "command": "string",
 "timeout": "number?"
 },
 "required_permission": "DangerFullAccess"
}


`This schema is passed directly to the LLM.

---

### Why JSON Schema Matters

* Decouples LLM from implementation
* Enables language-agnostic tools
* Standardizes interfaces

> Schema = contract

---

### Dispatcher Pattern


```python id="5g5syv"
def execute_tool(name, input):
 match name:
 "bash" -> run_bash()
 "read_file" -> run_read()
 ...`


Enter fullscreen mode
 


 Exit fullscreen mode


Adding a tool:


- Define input struct

- Implement logic

- Add one dispatch line


### Sub-Agent Design


Sub-agents reuse the same runtime:


```python id="5y9zsl"
runtime = AgentRuntime(
 session = new_session,
 tool_executor = restricted_tools,
 permission = high,
 prompter = None
)


`Key constraint:

* Sub-agents cannot spawn sub-agents

This prevents recursion loops.

---

## Permission System: Minimal but Complete

The system uses **5 permission levels**:

* ReadOnly
* WorkspaceWrite
* DangerFullAccess
* Prompt
* Allow

---

### Core Logic


```python id="9t9ahj"
if current >= required:
 allow
elif one_level_gap:
 ask_user
else:
 deny`


Enter fullscreen mode
 


 Exit fullscreen mode


### Design Insight: Gradual Escalation


Instead of:


- All-or-nothing access


It uses:


> Controlled escalation


- Small gap → ask user

- Large gap → deny


### Sub-Agent Safety Model


Sub-agents:


- Have high permission

- But no user prompt interface


Result:


- Allowed within scope

- Automatically blocked outside


> Two mechanisms combine into precise control.


## Part 1 Summary


Claude Code’s core reduces to three components:


`Agent Loop → execution engine
Tool System → action layer
Permissions → safety control`


Enter fullscreen mode
 


 Exit fullscreen mode


Key principles:


- Messages are the only state

- LLM decides when to stop

- Tools are schema-driven

- Errors are part of reasoning

- Permissions are incremental


## Final Thought


After stripping away 500K lines of code, what remains is surprisingly small:


> A loop, a tool interface, and a permission system.


That’s enough to build a functional AI agent.


But making it robust, scalable, and safe—that’s where the real complexity begins.


## Next Part


Claude Code Deep Dive (Part 2): Context Engineering and Design Patterns


- Prompt construction

- Config merging

- Context compression

- Practical design takeaways


## References


- Claw Code (Rust rewrite): https://github.com/instructkr/claw-code

- Project site: https://claw-code.codes/

- Claude Code official repo: https://github.com/anthropics/claude-code