A harness is a loop.
Everything else is craft.

01The thesis

Both take apart the same black box and find the same thing: no planning engine, no reasoning framework, no graph. An array of messages, a handful of functions, a while loop.

The practical consequence for building one: the loop is done in an hour. The work sits at its edges — error handling, permissions, context budget, tool quality. Flip that around and start with architecture, and you are building past the problem.

02The model touches nothing

The most important mental model on this page. With it, every harness design makes sense; without it, you build security holes.

Everything important follows from this: permission checks, sandboxing, path validation and output limits belong in the harness, without exception — never in the prompt. A prompt is a request, not a safeguard.

03The loop

Two nested loops. The outer one collects user input; the inner one lets the model call tools until it is done.

# The complete agent. Everything else is hardening.
conversation = []

while True:
    conversation.append({"role": "user", "content": input("you: ")})

    while True:                                  # inner loop
        msg = client.messages.create(
            model=MODEL, max_tokens=8192,
            system=SYSTEM_PROMPT,
            tools=[t["schema"] for t in TOOLS.values()],
            messages=conversation,
        )
        conversation.append({"role": "assistant", "content": msg.content})

        calls = [b for b in msg.content if b.type == "tool_use"]
        if not calls:
            print(text_of(msg)); break                # done → user's turn

        results = [run_tool(c) for c in calls]      # answer every call!
        conversation.append({"role": "user", "content": results})

04The state is an array

The server remembers nothing. Everything the agent “knows” lives entirely in conversation and is resent in full on every step. That explains three things at once:

• Why context gets expensive. Cost and latency grow with the array, not with the task. The contents of a 4,000-line file stay in the budget for the rest of the session.
• Why compaction is necessary. At some point the array hits the context window. Without a countermeasure, the session dies in the middle of the task.
• Why persistence is trivial. Serializing the array means: save, resume, fork and debug sessions. Build this early — it is your entire observability.

05Anatomy of a tool

Four fields. Only one of them is code — the other three are prompt engineering.

# A tool = schema + function. The description carries the behavior.
READ_FILE = {
  "name": "read_file",
  "description": (
      "Reads the contents of a file relative to the working directory. "
      "Use this before editing a file. "
      "NOT for directories - use list_files for that."),
  "input_schema": {
      "type": "object",
      "properties": {"path": {"type": "string",
                      "description": "Relative path, e.g. src/main.py"}},
      "required": ["path"],
  },
}

The dispatcher that doesn't swallow errors

Errors are not crashes, they are information for the model. It reads “file not found”, fixes the path and tries again. A harness that lets exceptions propagate takes away the agent's ability to correct itself.

def run_tool(call):
    fn = TOOLS.get(call.name)
    try:
        out = fn["function"](**call.input) if fn else f"unknown tool: {call.name}"
        err = fn is None
    except Exception as e:
        out, err = f"{type(e).__name__}: {e}", True   # error = feedback
    return {"type": "tool_result", "tool_use_id": call.id,
            "content": truncate(out, 30_000), "is_error": err}

06The three tools that are enough

Both articles independently arrive at the same minimal set. With it, the agent already reads, writes and changes real projects.

The trick with edit_file: a single tool covers creating and changing, and the model never has to count line numbers — it quotes the text it wants to replace. That is exactly why string replacement works better than any diff format.

def edit_file(path, old_str, new_str):
    if old_str == new_str:
        raise ValueError("old_str and new_str must differ")

    p = safe_path(path)                       # mandatory, see section 08
    if old_str == "":
        p.parent.mkdir(parents=True, exist_ok=True)
        p.write_text(new_str); return f"created {path}"

    src = p.read_text()
    n = src.count(old_str)
    if n == 0:
        raise ValueError("old_str not found - read the file again")
    if n > 1:
        raise ValueError(f"old_str found {n}x - include more context")

    p.write_text(src.replace(old_str, new_str))
    return f"edited {path}"

07Two ways to wire up tools

This is where the articles diverge — and the choice decides how much parser code you write.

Option B is instructive because it shows that tool use isn't API magic, just a convention. For the build you still pick A: whatever you save on parser code goes into tool quality.

08What separates a demo from a harness

Both articles name this gap but don't fill it. This is the list your agent has to work through — sorted by impact.

09The build plan

Five phases. Each ends with an acceptance test that must pass before the next one starts. A coding agent can work through this top to bottom.

10Pitfalls

• Incomplete tool_results. A single missing block makes the next API call invalid. The number one cause of failures when rebuilding this.
• Appending tool results as an assistant message. They belong in a user message.
• Exceptions instead of error text. Takes away the agent's self-correction and your robustness.
• Security in the prompt. “Please don't write outside the project” is not a boundary. safe_path() is.
• Line-number edits. Models miscount. String replacement with enough context is more robust.
• Unchecked tool output. One log, one window, session dead.
• Architecture before the loop. Planners, state machines, graphs — all of it before P3 is a distraction from the actual problem.
• Too many tools too early. Twenty tools dilute the choice. Three good ones beat ten mediocre ones.

11Agent spec

The same page, condensed to what a coding agent needs as its assignment. Copy it and hand it over as a prompt.

# TASK: Build a coding-agent harness

## Invariant
The LLM touches nothing. It returns text; every effect happens in your
code. Security, limits and permissions belong in the harness, never in the
prompt.

## Architecture
- State = one array `conversation`. The API is stateless.
- Outer loop: append user input.
- Inner loop: API call (with tool definitions) -> if tool_use blocks
  come back: execute all of them locally, append all results as ONE user
  message, call again. No tool_use -> print text, leave the loop.
- Use the API's native tool calling; don't parse a text protocol.

## Tool contract
Every tool: name (snake_case, verb_object), description (says WHEN and WHEN
NOT), input_schema (JSON Schema, every field described), function
(always returns a string).
Never throw errors: return them as a tool_result with is_error=true and a
readable message. Truncate every result to roughly 30k characters.
Every tool_use block gets exactly one tool_result with a matching
tool_use_id.

## Tools (in this order)
1. list_files(path?)  -> JSON array, directories end with "/",
   .git and node_modules skipped.
2. read_file(path)    -> contents as a string.
3. edit_file(path, old_str, new_str) -> replaces old_str with new_str.
   old_str == "" and file missing -> create (incl. parent directories).
   old_str not found -> error "read the file again".
   old_str found multiple times -> error "include more context". MANDATORY.
Only after that: bash (timeout + approval), grep/glob, task (sub-agent).

## Security (not optional)
safe_path(path): resolve, check against the project root, reject symlinks
and escapes. Call it in EVERY file tool.
Writing and executing tools require user approval with a preview.

## Phases with acceptance tests
P0 Scaffold   -> two turns, the second refers to the first.
P1 Loop       -> dummy tool gets called; two calls per turn work.
P2 Three tools -> "write fizzbuzz.js up to 15" creates, reads and changes
                 the file; "which version is in package.json" is found
                 on its own via list_files.
P3 Hardening  -> approvals, truncation, iteration limit, streaming, save/
                 load session. A rejected approval doesn't crash.
P4 Endurance  -> token counter, auto-compaction from 75% of the window,
                 project context from AGENTS.md, sub-agent with its own
                 array. 40+ tool calls survive a compaction.

## Do not build
Planners, state machines, graph frameworks, a tool zoo. The loop is the
architecture. The rest is craft at its edges.

Keep building

Questions about rebuilding this, your own harness variants and what actually holds up day to day — that's what I discuss in my community.