async function runLoop(task: string): Promise<string> {
  const messages: Message[] = [{ role: "user", content: task }];
  
  while (true) {
    const response = await model.complete(messages);
    
    if (response.stopReason === "end_turn") {
      return response.content; // Model says it's done
    }
    
    if (response.toolUse) {
      const result = await executeTool(response.toolUse);
      messages.push({ role: "tool", content: result });
    }
    
    messages.push({ role: "assistant", content: response.content });
  }
}

git clone https://github.com/anthropics/anthropic-quickstarts
cd anthropic-quickstarts/computer-use-demo  # Pi is in the agent subdirectory
# OR: git clone https://github.com/anthropics/pi (if direct repo is available)

# 📖 Teaching Document — Module 0.1: What Is a Harness?

# Module 0.1 — What Is a Harness?

**Course**: Master Course — Harness Engineering (12+ Hours)

**Module**: 0 — The Landscape

**Section**: 0.1

**Duration**: 15 minutes

**Level**: Senior Engineer and above

**Prerequisites**: Familiarity with LLM APIs (OpenAI, Anthropic, or equivalent). No agent framework experience required.

---

## Learning Objectives

After completing this section, you will be able to:

1. Define a harness precisely and distinguish it from the model it wraps.
2. State the three fundamental jobs of any harness and identify where each job lives in a real codebase.
3. Place any harness on the thickness spectrum and explain *why* its designer chose that position.
4. Explain why four independent engineering teams in 2025–2026 built structurally identical architectures.
5. Read Pi's source code and locate the loop, tools, and safety boundary as running code.

---

## 1. The Problem With Talking About "The AI"

When engineers say "the AI did X" or "the AI failed to do Y," they are usually describing behavior that has nothing to do with the model weights. They are describing the harness.

The model — the transformer, the weights, the inference endpoint — is a function. Given a sequence of tokens, it produces a next token (or a structured output). That is all it does. It has no memory across calls. It cannot run code. It cannot read files. It does not know what time it is. It does not retry when a tool fails. It does not stop when a token budget is exhausted. It does not ask a human for permission before deleting a file.

All of that is the harness.

In a typical production agent system, the model is responsible for approximately **1.6% of the code**. The harness is the other 98.4%. This is not a quirk of a particular framework — it is a structural property of every agent system at production scale. The model is a powerful component. The harness is the product.

This section defines what a harness is, what it does, and why its architecture converges across very different engineering teams.

---

## 2. Definition: What Is a Harness?

A **harness** is the infrastructure layer that wraps a language model and gives it the capability to act repeatedly in the world until a task is complete.

More precisely: a harness is the code, configuration, and runtime scaffolding that:

- Runs the model in a **loop** — repeatedly calling it until a stop condition is met
- Provides the model with **tools** — functions it can invoke to interact with the world
- Enforces **safety and permission boundaries** — controlling what the model is allowed to do

These three functions — loop, tools, safety — are not optional extensions. They are the minimal sufficient set. Every production harness has all three, in some form. A system that is missing any one of them is not a harness — it is a prompt.

### 2.1 What a Harness Is Not

- A harness is **not** a fine-tuned model. The model inside a harness is typically a general-purpose foundation model. The harness is what shapes its behavior.
- A harness is **not** a system prompt. A system prompt is one input to a harness, typically a small fraction of its complexity.
- A harness is **not** a framework. LangChain, LangGraph, CrewAI, and the OpenAI Agents SDK are frameworks that help you build harnesses. The harness is what you build *using* those frameworks — or without them.
- A harness is **not** an agent. "Agent" refers to the goal-directed behavior of the combined system. The harness is the machinery that produces that behavior.

---

## 3. The Three Jobs of a Harness

Every harness, regardless of complexity, performs exactly three jobs. Understanding these jobs is the foundation for everything that follows in this course.

### Job 1: The Loop

The model is stateless. A single call to `anthropic.messages.create()` produces one response and terminates. To make the model behave like an agent — something that works toward a goal over multiple steps — you need a loop.

The loop is the harness component that:

- Calls the model with the current context
- Parses the model's response to determine what action to take
- Executes the action (via a tool or directly)
- Updates the context with the result
- Decides whether to continue or stop
- Repeats

The simplest possible loop looks like this in TypeScript:

```tsx
async function runLoop(task: string): Promise<string> {
  const messages: Message[] = [{ role: "user", content: task }];
  
  while (true) {
    const response = await model.complete(messages);
    
    if (response.stopReason === "end_turn") {
      return response.content; // Model says it's done
    }
    
    if (response.toolUse) {
      const result = await executeTool(response.toolUse);
      messages.push({ role: "tool", content: result });
    }
    
    messages.push({ role: "assistant", content: response.content });
  }
}
```

This is a real implementation. Pi's core loop is approximately 80 lines of TypeScript that does exactly this, plus a max-iterations guard. The model's intelligence is not in this code — the loop is pure orchestration.

Loop architectures vary significantly (ReAct, Plan-then-Execute, graph-based, conversation-driven), and Module 1 covers them in depth. For now, understand that the loop *is the agent* — without it, you have a chatbot.

### Job 2: Tools

A stateless model can reason about the world but cannot act on it. Tools are the interface between the model's reasoning and real-world effects.

A tool is a function that:

1. Has a **name** the model uses to invoke it
2. Has a **description** the model reads to decide when to use it
3. Has an **input schema** (JSON Schema / Pydantic) the model must conform to
4. Has an **implementation** that the harness executes on the model's behalf
5. Returns a **result** that the harness inserts into context for the model's next turn

Critically: the model does not execute tools. The model outputs a structured request for a tool call. The harness intercepts that request, executes the tool, and returns the result. The model never touches the filesystem, the network, or any external system directly. That indirection is a security boundary, not an implementation detail.

Tool examples from production harnesses:

- `bash` — run a shell command; return stdout/stderr
- `read_file` — read file contents into context
- `write_file` — write content to a file path
- `search_web` — query a search engine; return ranked results
- `computer_use` — click, type, and screenshot a desktop

The number of tools a harness provides is one of the most consequential design decisions in harness engineering. We will return to this extensively.

### Job 3: Safety

A loop with tools, given no constraints, will do whatever the model decides is appropriate to complete the task — including destructive, irreversible, or unauthorized actions. The safety layer is the harness component that enforces constraints on what the model is allowed to do.

Safety manifests in several forms:

- **Permission flags**: explicitly enumerate what capabilities are enabled (e.g., Claude Code's 40 discrete flags)
- **Approval gates**: require human confirmation before high-risk actions
- **Sandboxing**: restrict the execution environment so damage is contained
- **Stop conditions**: exit the loop before a bad state becomes worse
- **Trust boundaries**: tag world-derived content as untrusted before it enters context

Safety is not a feature you add after building the harness. It is a dimension of every architectural decision: loop design, tool design, memory design, sandbox design, permission model. Modules 5, 6, and 11 cover each of these in depth.

---

## 4. The Convergent Architecture: Four Teams, One Design

In 2025–2026, four independent engineering teams — at Anthropic (Claude Code), OpenAI (Codex CLI / Agents SDK), Google DeepMind (Gemini CLI), and in the open-source community (Pi, Aider, oh-my-opencode) — built production agent harnesses without coordinating their designs. They produced architecturally identical systems.

Each of these systems has:

1. A **ReAct-derived loop** (or close variant) that interleaves model reasoning and tool execution
2. A **tool registry** with named, schema-validated tools
3. A **permission or safety layer** that constrains execution
4. A **context management system** that handles token budget and history
5. A **sandboxed execution environment** (or clear documentation of why it was omitted)

This is not coincidence. It is **convergent evolution** — the same selection pressure (build a reliable, safe, useful AI agent) producing the same architecture. The design space has a natural attractor.

What this means for you as an engineer: the core pattern is stable. Learning one harness deeply makes every other harness legible. The variation between harnesses is almost entirely in *thickness* — how much complexity each layer has — not in *structure*.

---

## 5. The Thickness Spectrum

The single most useful mental model for comparing harnesses is the **thickness spectrum** — a continuum from minimal (thin) to fully-featured (thick) harnesses.

### The Thin Extreme: Pi

Pi (by Anthropic, open source) is the reference point for thin harnesses. Its design philosophy is documented explicitly: do as little as possible in the harness; let the model do the work.

Key metrics:

- **Tools**: 4 (bash, read_file, write_file, search)
- **System prompt**: <1,000 tokens
- **Total harness code**: ~1,200 lines of TypeScript
- **Permission model**: trust-the-model; no per-action approval gates
- **Context management**: minimal; no active compaction
- **Safety features**: max-iterations guard, basic error handling

Pi's design choices are not limitations — they are *decisions*. The designers concluded that adding a 5th tool, or a complex permission model, or active context compaction, would add complexity that the model could handle more gracefully on its own. For Pi's use case (personal coding assistant), this is correct.

### The Thick Extreme: Claude Code

Claude Code is the reference point for thick harnesses.

Key metrics:

- **Tools**: 40+ (file operations, bash, browser, computer use, MCP protocol)
- **System prompt**: ~40,000 tokens (estimated)
- **Permission model**: 40 discrete capability flags, independently controllable
- **Context management**: active compaction, JIT retrieval, observation masking
- **Safety features**: plan-mode, approval gates, trust boundaries on tool output, credential isolation
- **Multi-session**: full state persistence, handoff files, multi-agent orchestration

Claude Code's complexity exists because its use case demands it: it runs in enterprise environments, handles multi-tenant workloads, manages credentials, and needs to be auditable. A thin harness would be inappropriate.

### The Design Question

The thickness spectrum gives you a design question: **how thick does this harness need to be for its use case?**

This is not an aesthetic question — it is an engineering one. Every layer of thickness adds:

- Code to maintain
- Failure modes to handle
- Attack surface to defend
- Cognitive overhead for developers

And every layer also adds:

- Capability
- Safety
- Observability
- Controllability

The correct answer depends on the use case. Pi and Claude Code are both correct for their respective contexts. A senior harness engineer can defend *why* a design decision lives where it does on the spectrum.

### Spectrum Reference Table

| Harness | Tools | System Prompt | Permission Model | Complexity |
| --- | --- | --- | --- | --- |
| Pi | 4 | <1,000 tokens | Trust-the-model | Thin |
| Aider | ~8 | ~2,000 tokens | Git-gated | Thin-medium |
| Codex CLI | ~10 | ~3,000 tokens | 3-tier (suggest/auto/full) | Medium |
| Gemini CLI | ~12 | ~4,000 tokens | Auto-approve default | Medium |
| OpenCode | ~15 | ~5,000 tokens | Session-scoped | Medium |
| oh-my-opencode | ~20 (meta) | ~8,000 tokens | Role-based (subagent hierarchy) | Medium-thick |
| OpenAI Agents SDK | Configurable | Configurable | 7 sandbox providers | Framework |
| LangGraph | Configurable | Configurable | Graph interrupt() | Framework |
| Claude Code | 40+ | ~40,000 tokens | 40 discrete flags | Thick |
| NemoClaw | 40+ + governance | ~40,000 tokens | External governance layer | Thick+ |

---

## 6. Reading a Harness From the Outside In

The lab for this section asks you to read Pi's entire source in 30 minutes and map the loop. Here is the methodology you will use for every harness in this course.

### Step 1: Find the Entry Point

Start with `package.json` or `pyproject.toml`. Find the `main` or `scripts.start` field. That file is the entry point. Everything the harness does begins there.

### Step 2: Find the Loop

Search for the `while` loop or recursive function that calls the model. In TypeScript harnesses, look for `await model.complete()` or `await anthropic.messages.create()` inside a loop. The surrounding code is the loop controller.

### Step 3: Find the Tool Registry

Search for tool definitions: JSON schema objects with `name`, `description`, and `input_schema` fields. The list of registered tools defines the harness's capability surface.

### Step 4: Find the Safety Layer

Search for permission checks, approval prompts, sandbox invocations, and stop conditions. This is often the least centralized part of the harness — safety logic can be scattered across the loop, the tool executor, and the entry point.

### Step 5: Find the Context Manager

Search for token counting, history truncation, and compaction logic. In thin harnesses, this may be absent. In thick harnesses, it is a major subsystem.

### Step 6: Write the Verdict

Write a one-paragraph summary: what loop architecture does this harness use? How many tools? What is the permission model? Where does it fall on the thickness spectrum, and why did the designers put it there?

This 6-step methodology is the same one you will use for every deep-dive in this course.

---

## 7. Anti-Patterns: What Harnesses Are Commonly Mistaken For

### Anti-Pattern 1: The Mega-Prompt

A very long, highly engineered system prompt with detailed instructions for every scenario. This is not a harness. It is a prompt. It has no loop (each call is independent), no tools (the model can only output text), and no safety enforcement (the model's own refusal is the only guardrail). When the task complexity grows, the mega-prompt fails — because a prompt cannot retry, recover, or call external systems.

### Anti-Pattern 2: The Framework Wrapper

An application that uses LangChain or the OpenAI Assistants API as a black box, exposing a thin interface on top. This is a harness in the sense that it loops and has tools — but the engineer doesn't understand what the framework is doing, which means they cannot debug it, audit it, or secure it. Using frameworks is fine; treating them as black boxes is not.

### Anti-Pattern 3: The Infinite Retry

A harness that retries every error indefinitely. This is a common mistake in harness loops. A production harness must have a typed error taxonomy: transient errors (retry with backoff), model-recoverable errors (return to model as a tool result), user-fixable errors (interrupt to human), and fatal errors (terminate immediately). Module 7 covers this in depth.

### Anti-Pattern 4: Tools Without Schemas

Tool descriptions written as free-text paragraphs, with untyped inputs. The model reads tool descriptions as prompts — it uses the description to decide when and how to call the tool. An untyped tool is an unreliable tool. Every production tool has a Pydantic schema (Python) or Zod schema (TypeScript), validated before execution.

---

## 8. The Course Map

This module has introduced the three-layer architecture: loop, tools, safety. The remaining 12 modules each go deep on one layer or cross-cutting concern:

- **Module 1** — The loop in depth: ReAct, Plan-then-Execute, graph-based, stop conditions, observability
- **Module 2** — Tool design: schemas, dispatch, routing, MCP protocol, tool security
- **Module 3** — Context management: token budgets, compaction, JIT retrieval, prompt assembly
- **Module 4** — Memory: in-context, working files, semantic stores, multi-session continuity
- **Module 5** — Sandboxing: inside vs. outside sandbox, providers, filesystem/network scoping
- **Module 6** — Permissions and approval: permission models, HITL design, prompt injection as bypass
- **Module 7** — Error handling: taxonomy, stuck-loop detection, graceful degradation
- **Module 8** — State and checkpointing: git-based, LangGraph super-steps, multi-session design
- **Module 9** — Verification: computed, visual, model-judged, human-in-loop, retry budgets
- **Module 10** — Observability: structured logs, traces, token accounting, replay-driven debugging
- **Module 11** — Security: OWASP Agentic AI Top 10, offensive techniques, defensive countermeasures
- **Module 12** — Capstone: build a production harness from scratch

The deep-dive sessions (DD-01 through DD-21) apply the 6-phase methodology to each of the 21 major production harnesses. By the end of the course, you will have a working mental model of every significant harness in production today.

---

## 9. Key Terms

| Term | Definition |
| --- | --- |
| **Harness** | Infrastructure layer wrapping a language model; provides loop, tools, and safety |
| **Loop** | The control structure that repeatedly calls the model and executes its actions |
| **Tool** | A named, schema-validated function the model can request; executed by the harness |
| **Safety layer** | Harness components that constrain what the model is allowed to do |
| **Thickness spectrum** | Continuum from minimal (Pi) to fully-featured (Claude Code) harnesses |
| **Convergent evolution** | Multiple independent teams producing structurally identical architectures |
| **Tool registry** | The set of tools registered with the harness; defines its capability surface |
| **Permission flags** | Discrete, independently controllable capability switches (e.g., Claude Code's 40 flags) |
| **Stop condition** | The condition under which the loop exits; e.g., end_turn, max iterations, fatal error |
| **Context window** | The token buffer the model sees on each call; managed by the harness, not the model |

---

## 10. Lab Exercise: Read Pi's Source in 30 Minutes

**Objective**: Apply the 6-step outside-in methodology to Pi. Locate the loop, tool registry, and safety layer as running code. Write the Architect's Verdict.

**Setup**:

```bash
git clone https://github.com/anthropics/anthropic-quickstarts
cd anthropic-quickstarts/computer-use-demo  # Pi is in the agent subdirectory
# OR: git clone https://github.com/anthropics/pi (if direct repo is available)
```

**Steps**:

1. Open the repo. Run `wc -l **/*.ts` or `cloc .` to see total line count. Record it.
2. Find the entry point (`package.json` → `main`).
3. Find the loop. Identify: what is the stop condition? What triggers a tool call? What updates the context?
4. Find the tool registry. List all 4 tools with their names and descriptions.
5. Find the safety layer. What constraints does Pi enforce? What does it *not* enforce (deliberately)?
6. Find the context manager (or confirm it doesn't exist). If it exists, what does it do?
7. Write a one-paragraph Architect's Verdict: loop architecture, tools, permission model, position on thickness spectrum, and *why* the designers made those choices.

**Expected output**: A filled-in 6-phase analysis card and a one-paragraph verdict. You will use this format for every harness in the course.

**Stretch goal**: Run Pi on a small task. Use `console.log` to instrument the loop and print every tool call and model turn. Confirm your static reading matches the runtime behavior.

---

## 11. References

1. **Yao et al. (2022)** — *ReAct: Synergizing Reasoning and Acting in Language Models*. arXiv:2210.03629. The foundational paper describing the Thought→Action’Observation loop that most production harnesses implement.
2. **Wei et al. (2022)** — *Chain-of-Thought Prompting Elicits Reasoning in Large Language Models*. arXiv:2201.11903. The predecessor to ReAct; establishes why multi-step reasoning in context produces better results.
3. **Anthropic (2025)** — *Claude Code: Best practices for agentic coding*. Anthropic documentation. Source for the 40-flag permission model and system prompt architecture.
4. **Liu et al. (2024)** — *Lost in the Middle: How Language Models Use Long Contexts*. arXiv:2307.03172. The definitive empirical study on context position effects; foundational for Module 3.
5. **Luzzardi, M. (2025)** — *Inside vs. Outside Sandbox Architecture*. Vercel engineering blog. The definitive framing of the two fundamental sandbox architectures in Module 5.
6. **OWASP (2026)** — *OWASP Agentic AI Top 10*. [owasp.org](http://owasp.org). The reference taxonomy for harness security in Module 11.
7. **Pi source code** — [github.com/anthropics/anthropic-quickstarts](http://github.com/anthropics/anthropic-quickstarts). The lab harness for this module.
8. **Aider source code** — [github.com/paul-gauthier/aider](http://github.com/paul-gauthier/aider). Reference for the thin-medium range of the thickness spectrum.
9. **oh-my-opencode source code** — The meta-harness reference for subagent hierarchy and role-based tool filtering.
10. **NemoClaw source code** — NVIDIA's hardened fork; reference for the governance-beneath-the-agent architecture.