What Is Agent-Harness Engineering
A language model, on its own, only predicts text. What turns it into an agent that can read your files, edit code, run tests, and fix its own mistakes is the harness — the software wrapped around the raw model. This chapter defines that harness and its four moving parts, so the two tools we compare next make sense.
Framing draws on the published designs of Claude Code and OpenAI Codex CLI; specifics are cited in Chapters 2–3.
- The harness is everything around the model — not the model's weights — that lets it act reliably in the real world.
- It has four parts: the tool interface, context management, permissions and sandboxing, and verification and feedback loops.
- Two agents built on similarly capable models can behave very differently because their harnesses differ.
- "Harness engineering" is the craft of designing these four parts — the lens for the whole handbook.
From a model that predicts to an agent that acts
A large language model is, at its core, a function that takes text and returns more text. Ask it to write a function and it will produce plausible code, but it cannot open your repository, cannot run the tests, and does not know whether what it wrote even compiles. It has no hands. Everything it "knows" about your task has to arrive as text in a single prompt, and everything it "does" is text it hands back.
An agent is what you get when you close that gap. You give the model a way to request actions — "read this file", "run this command" — and you build a program that actually performs those actions, captures the result, and feeds it back so the model can decide what to do next. That loop, running until the task is done, is the difference between a chatbot that suggests code and an assistant that edits your project and confirms the tests pass.
The program that mediates this loop is the harness. It decides which actions the model is even allowed to name, how much of your project the model can see at once, what happens before a risky command runs, and how the model learns whether its last action worked. None of that lives in the model's weights. It lives in engineering choices made by the people who build the agent.
The four parts of a harness
It helps to break the harness into four responsibilities. Almost every design decision in Claude Code or Codex CLI falls into one of these buckets, which is why we keep returning to them in the chapters ahead.
- The tool interface — the menu of actions the model can invoke, and how those actions are described to it.
- Context management — what the model sees at any moment: which files, which instructions, which past steps, and what is left out.
- Permissions and sandboxing — the guardrails that decide what runs freely, what needs a human's approval, and what is blocked outright.
- Verification and feedback — how the result of each action returns to the model so it can check its work and recover from mistakes.
Think of them as the four questions every agent must answer: What can it do? What does it know? What is it allowed to do without asking? And how does it find out whether it worked?
1. The tool interface — what the model can do
A tool is a named, described action the model is allowed to request: read a file, write a file, search text, run a shell command, fetch a web page. The harness advertises this menu to the model, usually as structured definitions with a name, a description, and the shape of the arguments each one expects. When the model wants to act, it does not run anything itself — it emits a structured request naming a tool and its arguments, and the harness executes it.
The design of this interface matters more than it first appears. A single, general Bash tool is enormously flexible but hard to reason about and hard to secure. Narrow, purpose-built tools like Read and Edit are easier to permission, easier to sandbox, and give the model clearer feedback when something goes wrong. Good tool descriptions also steer behavior: how a tool is worded nudges the model toward the right one for the job. Most coding agents converge on a similar core set — read, edit, write, search, run commands, browse the web — but the granularity and the exact contract differ, and those differences ripple into everything else.
2. Context management — what the model sees
The model can only reason about what is in front of it. Its context window — the span of text it processes at once — is finite, and a real codebase is far larger than any window. So the harness is constantly deciding what to put in and what to leave out: which files to load, which project instructions to include, how much of the running conversation to keep, and when to summarize older steps to make room for new ones.
This is arguably the hardest part of harness engineering. Load too little and the model works blind, inventing details about code it never saw. Load too much and you waste the window, slow the agent down, and bury the important lines in noise. Modern harnesses lean on ideas like progressive disclosure — showing the model a short description of a capability up front and loading the full detail only when it is actually needed — and on persistent project instructions that are re-supplied even after older conversation is compacted away. How an agent decides what the model sees, moment to moment, shapes both its accuracy and its cost.
Context management also includes memory that survives a single task: a file of project conventions, a record of how the build works, notes the agent accumulates over time. Whether that memory is a hand-written file, an automatic log, or both is one of the clearest places two harnesses diverge.
3. Permissions and sandboxing — what it may do safely
An agent that can run arbitrary shell commands is powerful and dangerous in equal measure. The same Bash tool that runs your test suite could delete files, push to production, or leak secrets — sometimes because the model misread the task, sometimes because hostile text it read in a file talked it into doing so. The permissions-and-sandboxing layer exists to bound that risk.
Two techniques work together here. Permissions are policy: rules about which actions run automatically, which pause to ask a human, and which are forbidden, often expressed as modes ("read-only", "auto-approve edits", "ask before anything risky"). Sandboxing is enforcement at the operating-system level: confining the agent's processes so that even if the model decides to do something destructive, the OS physically prevents writes outside the workspace or blocks network access. Policy tells the agent what it should do; the sandbox guarantees what it can do. Strong harnesses use both, and let you dial the balance between safety and the friction of constant approval prompts.
4. Verification and feedback — how it knows it worked
The final part closes the loop. After every action, the harness returns a result to the model: the contents of the file it read, the output and exit code of the command it ran, the error the compiler emitted. This feedback is what lets an agent be more than a one-shot guesser. It writes a change, runs the tests, sees three failures, reads the messages, and fixes them — a cycle no single prediction could achieve.
The quality of that feedback channel is decisive. Crisp, well-formatted tool results — a clean diff, a precise error, a clear exit code — let the model self-correct quickly. Vague or truncated results leave it flailing. This is also where a harness can lean on the environment itself as a source of truth: compilers, linters, type checkers, and test runners are objective judges, and a well-built harness routes their verdicts straight back to the model. An agent is only as reliable as its ability to notice it was wrong.
Why the harness — not just the model — decides quality
It is tempting to believe that agent quality is simply model quality: pick the smartest model and you win. In practice, two agents built on comparably capable models can feel worlds apart, and the harness is usually why. One surfaces exactly the right files and the other floods the window with noise. One catches its own failing test and retries; the other declares victory and moves on. One asks before deleting your branch; the other just deletes it. Same class of engine, very different cars.
That is why this handbook studies harnesses rather than benchmarking models. The next two chapters take the four parts you just met — tool interface, context, permissions, verification — and examine how each is built in Claude Code and then in OpenAI Codex CLI. The final chapter puts them side by side. Keep the four questions in mind as you read: what can it do, what does it know, what may it do without asking, and how does it find out whether it worked?