1. The while loop#

This is the foundation. On every iteration of the loop:

1. The model reads the assembled system prompt and the current context.
2. The model decides which tool to call.
3. The harness runs the tool.
4. The tool result is fed back into the context.
5. The loop repeats.

The loop continues until the model produces a text-only response with no tool call, or it hits a maximum-iteration cap that the harness sets to keep things from running away.

That is it. Five lines of pseudo-code:

1
while not done and iterations < max_iters:
2
    response = model.complete(context)
3
    if response.is_text_only:
4
        done = True
5
    else:
6
        result = registry.dispatch(response.tool_call)
7
        context.append(response, result)
8
    iterations += 1

Everything else in the harness exists to support those five lines. When you read the “an agent is just a while loop” tweets, this is what they mean. The tweets are not wrong. They are just incomplete, because the other eight components are what make the while loop trustworthy.

2. Context management#

On every turn, the context tree grows: user messages, tool calls, tool results, sub-agent reports, file reads. Left unmanaged, the context will eventually exceed whatever window the model was trained on. When that happens, things get bad in interesting ways: the model starts forgetting what it just did, contradicts earlier decisions, and on long tasks it can wrap things up prematurely just to escape the pressure.

The harness’s job is to decide what to keep verbatim, what to summarize, and what to discard. This process is called compaction.

Claude Code’s window was 200K tokens for a long time and then expanded to 1M for Opus. At roughly 80 to 90 percent capacity, compaction triggers automatically. Recent messages stay verbatim because they are most relevant. Older messages get summarized because their cost-to-value ratio is poor.

Compaction done badly has consequences. Sonnet 4.5 famously showed what people came to call context anxiety, where the model would notice the context filling up and rush through remaining steps. Opus 4.6 is much less twitchy about this and Anthropic actually removed the explicit context-reset machinery from their internal long-running agents harness because the new model handles compaction natively. That is a story for another article, but it is a useful preview: the harness does not just grow over time, it also prunes.

Figure 7 - Compaction in flight: Context grows on every turn until it bumps the compaction trigger around 80 to 90 percent capacity. The harness keeps recent messages verbatim because they are most relevant to the current step, summarizes older messages because their cost-to-value ratio has dropped, and discards what no longer matters. Done well, the agent stays oriented. Done badly, you get context anxiety and rushed conclusions.

3. Tools and skills#

We want to draw a distinction here that the wider community is still settling on.

Tools are primitives: read file, edit file, run bash, search code, fetch URL. They are universal in the sense that the same tool works across teams and projects with no domain knowledge.

Skills are organizational knowledge encoded above the tool layer, usually as Markdown files. Skills are specific to your team, your workflow, your domain. The dotzlaw.com project where this article was drafted has a write-article skill, a review-servoy-code skill, a generate-linkedin-post skill, and so on. Each one is a Markdown file the agent reads when invoked. It tells the agent how we like things done here.

Both tools and skills are managed by the same component: a registry. The registry maps every name to a permission level, a handler function, and a one-line description. Three operations:

• register(name, handler, perms, desc) adds a new tool or skill.
• get(name) retrieves the handler for dispatch.
• descriptors() returns a lightweight list of name, permission, and description that the harness sends to the model so it knows what is available.

The descriptor list matters more than people realize. It is what the model sees in its system prompt as “here are your tools.” Get the descriptions wrong and the model picks the wrong tool. Get them too verbose and you waste the prompt budget. Get them right and the model usually does the right thing on the first try.

4. Sub-agent management#

When a task is too large or too parallel for a single conversation thread, the harness spawns sub-agents. Each sub-agent gets its own session with an isolated context, its own restricted tool set, and a focused system prompt scoped to the task at hand. The pattern is spawn, restrict, collect.

There are three sub-agent archetypes we see across reference implementations:

• Exploration sub-agents have broad read permissions and a discovery-focused prompt. They go find things.
• General sub-agents have a standard toolset for normal work.
• Verification sub-agents are read-only or very limited write, with a validation-focused prompt. They check work.

The dotzlaw.com pipeline uses this pattern explicitly. The article-researcher (exploration), the article-writer (general), and the article-reviewer (verification) are three sub-agents the team-lead orchestrator dispatches in sequence. The reviewer cannot edit drafts. The writer cannot publish. Each one is bounded to its job, and the orchestrator collects the outputs.

Parallel sub-agents are where this component starts paying for itself. Manus, the research agent, has been reported to run hundreds of web pages in parallel as separate sub-agents, then collect the results [5]. Practitioners building contract-review harnesses at scale describe similar fan-out: dozens of per-clause sub-agents running simultaneously, with the parent orchestrator staying under 10K tokens while the cumulative sub-agent work runs into the hundreds of thousands [5]. That is the kind of fan-out you cannot do in a single thread without melting the context window.

Figure 6 - Spawn, restrict, collect: The pattern is the same in every harness that scales beyond a single thread. The orchestrator spawns a sub-agent with an isolated context, restricts the tool set to what the task actually needs, and collects the result. The contract-review example above is the structural argument for this component: a lean parent orchestrator holding the strategy, dozens of focused children doing the per-clause analysis. You cannot do that in one conversation; you can do it across many small ones.

5. Built-in skills#

Every harness ships a baseline set of non-negotiable primitives that work out of the box. If your agent cannot read or edit files, it is not a coding agent.

The primitive set:

• File operations: read, write, edit, search.
• Cell or shell execution: bash, REPLs, scripts.
• Code navigation: find references, jump to definition, structural search.

Modern harnesses ship higher-level built-ins on top of those primitives:

• How to make a git commit (with a sane message format).
• How to open a pull request (with a body, not just a title).
• How to run tests and interpret results (parse the failure, tell the user what broke).

These are not optional. The reason your agent feels useful from minute one with Claude Code or Cursor is that someone already wrote those built-ins for you. The reason a from-scratch LangChain agent feels janky for the first three weeks is that you are still wiring the file-edit tool yourself.

One non-obvious detail: built-in skills must use pure standard libraries. No framework dependencies. The agent will run in environments where the developer has not installed your framework, and a built-in skill that breaks on a missing import is no better than no built-in skill at all.

6. Session persistence and memory#

Long agent sessions are stateful, and processes crash. If the harness does not write state to disk, every crash erases the entire session. That is fine for a five-second toy demo and unacceptable for an agent that is running for an hour while you are at lunch.

The modern approach is the boring one, and it is the right one: append-only JSON or Markdown files. Every event the agent generates, every message, every tool call, every tool result, every compaction event, gets written as one line. The append() method opens the file in append mode, writes the event, flushes to disk, and closes. If the process dies on the next line, this one is already safe.

The replay() method reads the file back line by line and reconstructs the session. Because the file is append-only, two concurrent runs can share the log without locking, and you can tail -f the file in another terminal to watch the agent think in real time. We do this often. It is genuinely fun, and you also catch problems early.

Anthropic’s recent managed-agent work explored building session management as a separate service from the harness itself, rather than embedding it inside. That is interesting for very long-running production agents but for most people the embedded append-only-log approach is plenty.

7. System prompt assembly#

The system prompt is not a static string. It is the output of a pipeline that walks ancestor directories looking for specific instruction files (CLAUDE.md, AGENTS.md, and similar) and injects their contents dynamically. That is how Claude Code knows the conventions of your project the moment you open the terminal in the project root.

There is a critical ordering rule here that almost every from-scratch builder gets wrong on the first attempt:

Static content must come first. Dynamically loaded content comes second.

Reverse the order and you break prefix caching. Prompt caching in modern LLM APIs works by hashing the token prefix of your system prompt across calls [8]. Identical prefixes hit the cache, which can be 5x or more cheaper and faster [8]. If your dynamically loaded CLAUDE.md content sits at the front of the prompt, every call has a unique prefix because the file’s modification time has bumped a header somewhere, and you get zero cache hits. Your bills go up, your latency goes up, and you do not understand why because the diff in your system prompt looks tiny. The fix is one line: put the static boilerplate first, dynamic content second, so the cache-hit prefix is as long as possible.

It is a single-line fix, and it routinely cuts inference cost by half on long-running agent sessions.

8. Lifecycle hooks#

The extensibility layer. Hooks let you inject custom logic before or after a tool runs, without touching the harness core.

There are two types and they are not symmetric.

Pre-tool hooks fire before the tool runs. They receive the tool name and tool input. They can do one of three things:

• Allow the call to proceed.
• Deny the call and return an error to the model.
• Modify the call (rewrite arguments, swap one tool for another).

Pre-tool hooks are how you implement organizational policy. “Never run rm -rf against /home.” “Always pipe pytest through this wrapper.” “Block writes to any file matching secrets/*.” These rules live in the hook, not the model. The model is not asked to be trusted with the policy; the harness enforces it.

Post-tool hooks fire after the tool runs. They receive the tool output. They cannot block anything, by design. They are for auditing, logging, observability, and telemetry. If your security team needs an audit trail, this is where it goes.

Figure 8 - Two hooks, one loop iteration: Pre-tool hooks gate the call before it runs and can allow, deny, or rewrite it. Post-tool hooks audit the call after it runs and cannot block anything. The asymmetry is intentional: enforcement happens up front, observability happens at the back. Both are how you wire organizational policy and audit infrastructure into a harness without touching the core loop.

Hooks are also the mechanism by which enterprises plug harnesses into existing approval workflows and audit infrastructure. The harness does not care what you put in the hook, it just guarantees the hook will fire at the right point in the loop.

9. Permissions and safety#

The component that turns a useful tool into one you will let near production.

Most harnesses use a three-level permission hierarchy:

• read: can read files and directories; no modifications.
• workspace: can modify files within the session workspace.
• full: can execute arbitrary commands and modify any accessible path.

Each tool declares its minimum required permission level. The harness enforces the declared permission at dispatch time, before the tool runs. A read tool simply cannot be invoked under a read permission session if it tries to escalate, and that check is in the harness, not in the model.

The interesting case is bash. The same bash tool can be safe or dangerous depending on what command string the model wants to run. So the harness does dynamic command classification:

• Safe commands like ls, cat, grep, pwd get classified as read-only.
• Dangerous commands like rm, sudo, shutdown, mkfs jump straight to full access (which the model probably does not have, so the call fails fast).
• Everything else lands at the workspace level.

The classifier is not perfect, and that is why the final piece exists: interactive approvals. For any destructive action, the harness can pause and request explicit user approval before execution. You see this in Claude Code as the “do you want to allow this command?” prompt. That gate has to be in the harness, not in the model. A model can be talked out of caution by a sufficiently clever prompt; a hard-coded “ask the human first” check cannot.

Figure 9 - Three tiers, one classifier, one human gate: The harness checks permission at dispatch time, before the tool runs. The bash tool gets a special path because the same tool can be safe or dangerous depending on the command, so a classifier sorts commands into the right tier on the fly. Anything destructive then hits the interactive approval gate, which lives in the harness on purpose. A clever prompt can talk a model out of caution; it cannot talk a hard-coded “ask the human first” check out of firing.