agent-harness-article · Part 1
You rent the model, you own the harness: an agent vocabulary
You use an AI coding assistant every day, and you have heard "agent," "harness," "context," and "memory" used as if they were four names for one thing.
Marcin
Java since 2007, .NET since 2010 · Azure · lately deep in LLMs
1. Why these words keep blurring
You use an AI coding assistant every day, and you have heard "agent," "harness," "context," and "memory" used as if they were four names for one thing. Sometimes they are just brand names for "the AI." Sometimes one speaker means the model and the next means everything around it, and nobody stops to say which.
I've been writing code for over a decade, and I've seen plenty of misunderstandings caused by one thing having three different names. Here is one picture to hang the words on: a skilled contractor, hired by the hour, who forgets yesterday and works on a job site you set up. The contractor is the model you rent, and the job site is the harness you own. The picture has limits. A contractor is a person, and a model is not. "Hired by the hour" only says the contractor is rented. "Forgets yesterday" is literally true of a session, and the next section shows why.
The thesis is an argument rather than a measured result: you rent the model, you own the harness, and reliability is built in the harness rather than requested from the model. "Own" needs a limit. It means the layer you configure around the model, and it means all of it only if you write the loop yourself, rather than using a product or kit that runs it for you. I'll say where the split stops being clean, that limit included, before you have to ask.
This is a vocabulary article, so it builds nothing. It separates model, context window, tool, agent loop, agent, harness, memory, and skill, and it tests the words on one worked example: a map you can walk through in assistants you already use. It reads on its own.
2. The model is the part you rent
The model is the part that reasons and decides what to do next. Claude Code's agentic loop is powered by two components, models that reason and tools that act (How Claude Code works). The glossary puts the split in one line: "Claude Code is the harness; Claude is the model inside it." In a coding assistant, "model" names the language model that answers you. In the picture, it is the contractor, the part you rent.
The context window is the working space the model reads from during a session. What sits there: the conversation so far, file contents, command output, and the standing instructions the assistant adds, among other things I'll name when they matter (glossary). In the picture, it is what the contractor has in mind right now.
The contractor forgets yesterday, and the reason is plain: each session begins with a fresh context window (memory page). Whatever was in yesterday's window is not in today's unless something puts it back, and what puts it back is the subject of a later section.
3. Why a smaller window helps, and what that rests on
Why prefer a smaller, relevant window? Anthropic gives the reason itself. In its post on context engineering, it says that as the number of tokens in the window grows, the model's ability to recall information from it falls, and it calls the effect context rot. Anthropic describes a gradient rather than a hard cliff, and it points to studies on needle-in-a-haystack benchmarking without naming them. These are tests that hide one fact in a long input and ask the model to find it.
The best-known study of this kind is "Lost in the Middle" by Liu and colleagues. They found that performance was often best when the relevant information sat at the start or end of the input and lower when it sat in the middle, even for models built for long inputs. Chroma, which sells a vector database and so has a stake in the answer, later tested 18 models, among them Claude Opus 4, the GPT-4.1 family, o3, and Gemini 2.5, and found that they became less reliable as the input grew.
The evidence has limits. Liu and colleagues tested 2023-era models. Chroma's one position test, 11 needle positions in a single task, showed no notable variation, and its authors do not generalize from it, so I would not turn the middle is the weak spot into a rule. What both agree on is the direction: more input, less reliable recall. I have not seen the same measurements repeated on current models, so "prefer a smaller, relevant window" is a working rule, not a measured one.
The harness has its own answers to a crowded window. One of them, the subagent, turns up in the map section.
4. Tools, and the loop that decides when to stop
A tool is an action the model can take: reading a file, editing code, running a shell command, searching the web. Without tools the model can only respond with text (glossary, How Claude Code works). In the picture, the tools are the shed.
The model never runs a tool. It asks, and software runs it. Anthropic's tool-use overview and OpenAI's function-calling guide describe the same exchange: the model returns a structured call, software runs it, and the result goes back to the model. In the picture, the contractor fills out a requisition, and somebody else opens the padlock and brings back the result.
The agent loop is the cycle those requests live in: gather context, take action, verify results, and repeat until the task is done (Claude Code's docs say so, and Anthropic's Agent SDK post says it in other words). The Claude Agent SDK is Anthropic's SDK for building your own agents. When you build an agent with it, the SDK runs the loop, as Claude Code runs it for you. In the picture: look at the site, decide, act, look again, until done or stopped.
Stopped is the interesting word, because the docs name four ways a loop ends. The model finishes with a final response and no tool calls (Agent SDK loop doc, OpenAI's Agents SDK runner). A cap is hit, on turns or budget in the Agent SDK and on turns in OpenAI's runner. An error occurs. Or you interrupt, which Claude Code allows at any point. Anthropic's Building effective agents names the same kinds of stops.
Only the first ending is the model's own call. The other three are imposed from outside the model, and in the picture they are the stop rule. Turn and budget caps are a feature of agents built with the Agent SDK (loop doc). I could not find them listed as Claude Code or Copilot settings.
5. Agent or workflow: who decides the next step
Workflows and agents are made of the same parts, a model and tools. What differs is who decides the next step. Anthropic's Building effective agents draws the line I use. Workflows are "systems where LLMs and tools are orchestrated through predefined code paths." Agents are "systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks." The post calls both agentic systems.
In a workflow, your code decides. You write the steps in advance: call the model, run a tool, call the model again. The model fills in the content of each step, but not the order of the steps. In an agent, the model decides. After each tool result it chooses what comes next, another tool call or a final answer, and the loop runs until it finishes or is stopped. In both, the harness runs every tool.
My one-sentence version of an agent, built on Anthropic's: a model that decides its own next steps and calls tools in a loop until it finishes or is stopped. In the picture, the agent is the contractor working a job on the site, and a workflow is the same contractor following a checklist you wrote.
Here is the test I use: is the sequence of steps known in advance? If yes, it is a workflow, whatever the product page calls it, and you do not need to hand the sequence to a model. The test is for the product in front of you, and I claim nothing about how many products sold as agents are workflows.
Do you need an agent at all? Anthropic advises finding the simplest solution possible and increasing complexity only when needed, which "might mean not building agentic systems at all," and OpenAI's practical guide says to validate the use case first, because otherwise a deterministic solution may suffice.
OpenAI's own pages word "agent" three ways: "LLMs equipped with instructions and tools" in the Agents SDK documentation, an AI system with instructions, guardrails, and tools in the developer "Building agents" track, and systems that independently accomplish tasks on the user's behalf in A practical guide to building agents (PDF). The wording differs, but Anthropic and OpenAI, the two I compared, both describe a model, tools, a loop, and some autonomy.
6. The harness is the job site
"Harness" has two common scopes, and the difference moves the line between what you rent and what you own.
The broad scope comes from the Claude Code glossary: the tools, context management, and execution environment that turn a language model into a capable coding agent. The entry says "Claude Code is the harness; Claude is the model inside it" and that the harness supplies file access, shell execution, permission gating (the assistant asking before it acts), and the loop that chains actions together. How Claude Code works says the layer that provides the tools and manages the context the model sees is what "agentic harness" refers to. In the picture, this is the job site: everything around the contractor. The logbook and the binder, which come next, belong to the site too.
The narrow scope comes from Anthropic's Managed Agents post: the harness is the loop that calls Claude and routes its tool calls. It is one of three components, next to a session (an append-only log of everything that happened) and a sandbox (where Claude runs code and edits files). The post calls Claude together with its harness "the brain" and the sandboxes and tools "the hands." The Hugging Face glossary defines the harness the same narrow way: the execution layer inside the agent that calls the model, handles tool calls, and decides when to stop. It adds that Claude Code and Codex use "harness" for the whole nonmodel layer, and that frameworks use the word differently.
I use the broad scope, and it is a choice. The reasons: it is the wording of the docs for an assistant you use; it matches the job site, which holds everything around the contractor; and the rent-or-own question is about everything around the model, not only the loop. If another post uses the narrow sense, translate: the harness is then the loop that calls the model and handles its tool calls, and the other parts get their own names, such as the session and the sandbox in the Managed Agents post or the scaffolding in the Hugging Face glossary.
One more formulation you will meet is "Agent = Model + Harness." It comes from LangChain's The Anatomy of an Agent Harness (2026-03-10, Vivek Trivedy), where it is the author's opinion, from a framework vendor, and the post credits no one for it. A later post by Osmani (2026-04-19) repeats it and credits Trivedy, so it is not independent confirmation. Neither Anthropic nor OpenAI defines an agent as model plus harness, and the glossary line "Claude Code is the harness; Claude is the model inside it" is the closest wording I know of in a vendor's own docs. I treat the formula as an attributed formulation, and the definition of agent in the previous section stands.
The map draws the broad line, the glossary's.
7. What the contractor remembers tomorrow
Memory, in one sentence: it is what carries across sessions, and it lives in files. Within a session the model has only its context window. In the picture, the site logbook outlives the contractor's day.
Claude Code's memory page says two mechanisms carry knowledge across sessions: CLAUDE.md files, which you write, and auto memory, which Claude writes. Both are loaded at the start of every conversation. Anthropic's long-running agents post shows the same pattern in a different setup: each new session begins with no memory of what came before, and the setup bridges sessions with a progress log (claude-progress.txt), a feature list in JSON, and git commits. Both setups write what must survive into files outside the window.
The glossary calls the context window "working memory for a session," so you will see the window called memory in the docs. I keep "memory" for what carries across sessions, so the two never share a word. Anthropic's context-engineering post names "structured note-taking, or agentic memory" as a technique for long-horizon work, and that is as far into memory engineering as this article goes.
Not everything that reaches the window is memory. Skills and instruction files are written guidance that the harness puts into the context window, and what differs between them is when. In the picture, both are the binder of how things are done here. CLAUDE.md plays both parts: it is the binder when you write it as instructions, and part of the logbook because it carries across sessions.
A skill is a directory with a SKILL.md file that must give the skill a name and a description (Anthropic's Agent Skills post, and the open Agent Skills specification). Claude Code skills follow the Agent Skills open standard (skills page).
In Claude Code, CLAUDE.md files in the working directory or above load at the start of every session, while path-scoped rules and CLAUDE.md files in subdirectories load on demand, when a matching file is read, written, or edited (memory page). Skill descriptions load at session start so Claude knows what exists, and a skill's full content loads only when the skill is invoked. The Agent SDK's loop doc lists the same load timing for CLAUDE.md and skills.
8. Advice versus enforcement: where reliability comes from
Some harness parts only put text in front of the model. Others run whatever the model decides, or stop it. My argument is that reliability comes from the second kind. Here is the test I use: if the model ignores this rule, does anything stop the action? If nothing does, it is advice. If something does, it is enforced. The activity at the end applies the same test to your own setup.
The binder and the logbook are advice. CLAUDE.md and auto memory are loaded as context, not as enforced configuration (memory page), so the model can fail to follow them. Skill text is advice for the same reason: once loaded, it is context. A binder is a request: the contractor can skim it, misread it, or lose page nine. The loss is real. Instructions given only in conversation can disappear when older messages are replaced by a summary (compaction), which is why Claude's docs tell you to put persistent rules in CLAUDE.md (How Claude Code works, loop doc, glossary).
Hooks and permission gating are the foreman. Hooks are enforced. The Claude Code glossary's "Hook" entry says a hook fires at fixed lifecycle points so that certain actions always happen, rather than depending on the model's choice. The Agent SDK docs say a hook that rejects a PreToolUse event, the one that fires before a tool runs, prevents the tool call from executing, and the memory page says to use a PreToolUse hook to block an action regardless of what Claude decides. That is what I mean when I call hooks deterministic. Permission gating, the approve-or-deny moment you note in step 3 of the activity below, behaves the same way in practice, though I could not tell whether you can configure it. A loop cap is a third enforced part, in agents you build with the Agent SDK.
CLAUDE.md and auto memory are context, hooks fire at fixed lifecycle points, and a loop can be capped. From that I argue that reliability gets built in the parts that run regardless of the model, not in text asking the model to behave.
9. The map: find each part in a tool you use
In this section, "the picture" means the contractor metaphor and "the map" means the first diagram, which draws one line between the model and the harness. The diagram below sorts the parts of Claude Code by who sets them: the model is rented, the product supplies the tools, the loop, and permission gating, and you configure the instruction file, skills, hooks, and subagents.
Where to find the parts you configure in Claude Code:
- Instruction file:
CLAUDE.mdin the working directory or above, orAGENTS.mdonly when there is none (v2.1.277 or later). - Skills: the skills page.
- Hooks: the hooks guide.
- Subagents: the sub-agents page.
A subagent is a helper that runs in its own context window with its own system prompt, tool access, and permissions. It does not see the main conversation's history, the skills already invoked, or the files already read, and it returns only a summary. That is the Claude Code description (the glossary entry, the sub-agents page), and GitHub's docs say Copilot custom agents can run as subagents with a separate context window so the main agent's context is not cluttered. Back to the crowded window: a subagent is one harness answer to it. The messy work happens in someone else's window, and only the summary comes back. I could not tell whether a subagent's instructions are enforced, so the diagram does not sort them.
If you use Copilot, GitHub documents where its files live in its pages on repository instructions, agent skills, and custom agents. Paths and behavior change between versions, so check the documentation for your version.
10. Is the split just a teaching simplification?
The strongest objection is that the rent-or-own split is a teaching simplification. It has four legs. The first is about how the parts depend on each other, and the other three are about words.
Model and harness are coupled. Anthropic's Managed Agents post and harness-design post say that harness components encode assumptions about what the model cannot do on its own, and that those assumptions go stale as models improve. The harness-design post gives a case: context resets built for Sonnet 4.5's "context anxiety" (a model wrapping up early as it nears what it believes is its limit) could be dropped for Opus 4.5. That holds for the two models named, and I do not generalize it. The objection has a stronger form, that models are trained with particular harnesses in mind, so a model and its harness are not freely swappable. I know of no source that says so, and I do not assert it. It is an open question.
Even one vendor draws the line between model and harness in two places, as the diagram in the harness section shows, which is why the contractor metaphor avoids the word "brain": using it would pick one side of the disagreement without saying so. Beyond the broad and narrow senses, the harness-design post uses "harness" for a setup of three agents (planner, generator, and evaluator) with context resets, and defines it nowhere. The long-running agents post uses it six times without defining it and calls the Claude Agent SDK "a powerful, general-purpose agent harness." OpenAI's developer Agents page uses it for a managed runtime: "The Agents API runs the Codex harness and manages the underlying agent infrastructure." And things sold as agents are often fixed workflows, which the test from the agent section settles: if the steps are known in advance, it is a workflow, whatever the page calls it. I do not claim how common that is.
The answer is that the thesis concerns who controls what and what holds when the model ignores a rule, not where a vendor puts a word. Wherever a vendor draws the line, the parts that run whatever the model decides (hooks and permission gating) behave differently from the parts that only put text in front of the model (instruction files, memory, and skill text). Instruction files such as CLAUDE.md, and skill text, are advice you write; auto memory is advice Claude writes. Coupling is a reason to own the harness: if its components encode assumptions about one model, someone has to retune them when the model changes.
"Own" needs its limit. In Claude Code the runtime is itself a vendor product (Claude Code is the harness, in the glossary's words), so what you own is the layer you configure, as the diagram in the map section shows. You own all of it only if you write the loop yourself. If you build an agent with the Agent SDK, you set its turn and budget caps, so the cap is yours too, while the SDK still supplies the loop.
I concede three things. The line moves. Harness parts built around one model's limits may need retuning when the model changes, as in the Sonnet 4.5 to Opus 4.5 case. And no measurement backs the thesis, which is an argument from how the parts work.
Scoped, the thesis makes two claims, and they are separate. You rent the model, and you own the layer of the harness you configure, all of it if you write the loop yourself. Reliability comes from the harness parts that run whatever the model decides, not from text that asks the model to behave. The first claim is about who controls the setup; the second is about what holds when the model ignores a rule.
11. The words side by side
The contractor carries every definition in this article, so it helps to see them side by side.
| Term | In the picture | What it names in your coding assistant |
|---|---|---|
| Model | The contractor, hired by the hour | The language model that answers you |
| Context window | What the contractor has in mind right now | The working space for one session |
| Tool | The shed | The actions the model can request, which software runs |
| Agent loop | Look at the site, decide, act, look again, until done or stopped | The repeated cycle; a cap, an error, or an interrupt is the stop rule |
| Memory | The site logbook that outlives the contractor's day | Files that carry knowledge across sessions |
| Skill or instruction file | The binder of how things are done here | Written guidance the harness puts into the window |
| Hook and permission gating | The foreman | Harness parts that run whatever the model decides |
| Harness | The job site around the contractor: shed, logbook, binder, foreman, stop rule | The tools, context management, and execution environment around the model |
| Agent | The contractor working a job on that site | A model that decides its own next steps and calls tools in a loop |
The picture makes the rent-or-own split concrete. The contractor is hired. You write the binder and your part of the logbook, and Claude writes auto memory. Reliability sits in the parts of the site that do not depend on the contractor: the foreman and the stop rule. In Claude Code you configure the hooks, and permission gating comes with the product. The diagram in the map section shows who sets what.
Activity 1: Find the map in a tool you use
Pick one coding assistant you use daily, Claude Code or Copilot, and fill in the diagram from the map section for it. Write down the assistant and the version it reports, then make three short lists, one per group in the diagram.
- Model (rented): write down which model the assistant is calling, as the assistant shows it.
- Context window (rented): list what you know is in the window during one session: the conversation so far, files read, command output, standing instructions, loaded skills. Mark which of those you put there and which the assistant added.
- Tools (supplied by the product): list the actions the assistant can take for you, such as reading a file, editing code, running a shell command, or searching the web. Mark one you have seen it request and one you approved or denied. That approve-or-deny moment is permission gating.
- Agent loop (supplied by the product): watch one task from start to finish. Note the gather, act, and verify steps, and which of the four endings stopped it: a final response, a cap, an error, or your interrupt. Skip the search for a cap in your settings; the loop section says why.
- Instruction file (configured by you): find the file or files your assistant reads and note whether each loads at session start or on demand. Claude Code readers: the map section lists the files, and the section on what the contractor remembers tomorrow gives the load timing.
- Skills (configured by you): note whether you have any, where your assistant keeps them, and when each one loads. Claude Code readers: the same two sections cover it.
- Hooks (configured by you): note whether your setup defines any. If it defines none, write "none." Claude Code readers: the hooks guide is linked in the map section.
- Subagents (configured by you): note whether you have defined any, and where your assistant keeps subagents or custom agents.
- Sort the instruction file, the skill text, and any hook as advice (context the model may not follow) or enforced (runs whatever the model decides), using the test from the section on advice and enforcement. Sort the approve-or-deny moment from step 3 as well. In Claude Code, mark it enforced in practice. In Copilot, if something in your assistant stops an action whatever the model decides, such as the approval prompt from step 3, put it on the enforced side.
- Compare your lists with the diagram. Any element you could not find, and anything you found that the diagram lacks, is a finding to write down.
You end up with three short lists and an advice or enforced mark on each part you configure and on permission gating. Anything you could not place is where your ownership stops.
How to check your lists:
- You can name one item in your setup that is advice and one that is enforced, and say why. Permission gating counts as the enforced item when no hook is defined.
- You can name which of the four endings stopped the loop you watched and the observation that shows it.
- You can say which parts you configure, which the product supplies, and where your ownership stops.
A few hints:
- If you use another assistant, do steps 1 to 4 and 9 in it, and sort only the approve-or-deny moment.
- Expect paths and behavior to change between versions, and note the version you read.
- If the model ignores a rule in your instruction file, you have found the advice side of the test. In Claude Code, a hook is the way to make an action happen or not happen regardless of what the model decides.
12. The question to keep
My view, and you may disagree: the useful question about any assistant is what happens when the contractor ignores a rule. Open the file where you wrote the rule you care about most, and ask whether anything stops the action if the model skips it. If nothing does, you have left a note for someone who forgets yesterday, and nothing on the site enforces it yet. I would rather learn that on a quiet afternoon than from a surprise in production.
This is part 1 of a planned series on agent memory and harness engineering.
Sources
- How Claude Code works (Claude Code docs)
- Claude Code glossary
- How Claude remembers your project (Claude Code docs: memory)
- Harness design for long-running application development (Anthropic Engineering)
- Effective context engineering for AI agents (Anthropic Engineering)
- Context Rot: How Increasing Input Tokens Impacts LLM Performance (Chroma Research)
- Lost in the Middle: How Language Models Use Long Contexts (arXiv:2307.03172)
- RULER: What's the Real Context Size of Your Long-Context Language Models? (arXiv:2404.06654)
- NoLiMa: Long-Context Evaluation Beyond Literal Matching (arXiv:2502.05167)
- Tool use with Claude (Claude API docs)
- Function calling (OpenAI developer docs)
- Building agents with the Claude Agent SDK (Claude blog)
- How the agent loop works (Claude Agent SDK docs)
- Running agents (OpenAI Agents SDK, Python)
- A practical guide to building agents (OpenAI, PDF)
- Building effective agents (Anthropic Engineering)
- OpenAI Agents SDK (Python) documentation home
- Building agents (OpenAI developer track)
- The Anatomy of an Agent Harness (LangChain blog)
- Scaling Managed Agents: Decoupling the brain from the hands (Anthropic Engineering)
- Agent Harness Engineering (Addy Osmani, blog)
- Harness, Scaffold, and the AI Agent Terms Worth Getting Right (Hugging Face blog)
- Effective harnesses for long-running agents (Anthropic Engineering)
- Equipping agents for the real world with Agent Skills (Anthropic Engineering)
- Agent Skills specification (agentskills.io)
- Extend Claude with skills (Claude Code docs: skills)
- Automate actions with hooks (Claude Code docs: hooks guide)
- Adding repository custom instructions for GitHub Copilot
- About agent skills (GitHub Copilot docs)
- Create custom subagents (Claude Code docs: sub-agents)
- About custom agents (GitHub Copilot docs)
- Agents (OpenAI developer docs)