Harness Engineering

What a Harness Is: The Agent's Runtime and Boundary

Background & Principles

A single messages.create() is stateless inference: you hand it input, it hands you output, and the model neither knows nor cares what happened before or after. Wrapping that one inference call into something that autonomously completes multi-step tasks — everything happening in between is the harness:

• Tool dispatch: parse the model's tool_use block, route to a local function, and feed tool_result back into the next turn's messages.
• Loop control: decide stop vs. continue — via stop_reason == "end_turn", max_iters, token budget, or a human checkpoint.
• State / memory: the messages array, scratch files, vector store, external DB — every piece of cross-turn state is remembered by the harness, never by the model.
• Permission gate: allow / deny / ask decisions before tool execution (Claude Code's ask / accept-edit / plan tiers).
• Recovery: retry / fallback / human takeover when a tool fails, the network flakes, or the model goes off the rails.

90% of real-world experience comes from how these pieces are engineered, not from the model's raw reasoning. Cognition said it plainly in their 2025 Don't Build Multi-Agents post: their moat is harness design, not smarter prompts. Claude Code's plan mode, Cursor's composer, Aider's git auto-commit — same base model, different OS.

Hands-on Example

Separate prompt issues from harness issues with a 30-second triage — when your agent misbehaves, ask first:

# —— PROMPT's fault ——
- model picks the wrong tool
- output format unstable
- skips reasoning steps
- violates a stated constraint

# —— HARNESS's fault ——
- spins forever in a loop after 10 turns (missing loop control)
- agent crashes on first tool error (missing recovery)
- gets dumber as context grows (missing compaction)
- no chance for human approval on dangerous calls (missing permission gate)
- same prompt works in Claude Code but fails in your script (different harness)

Pin this triage table at the root of your agent project — running it before debugging cuts time in half.

Dissecting the Claude Code Harness: What's Actually Doing the Work

Background & Principles

Claude Code is the public SOTA coding harness today. Pulling it apart gives you a blueprint you can copy into your own agent. Six core abstractions:

• Tool registry: a small set of orthogonal tools — Read / Edit / Write / Bash / Grep / Glob. The key word is small and orthogonal, not "lots and fancy". Anthropic's engineering team repeats this in their blog: more tools → higher tool-selection failure rate.
• Permission gate: three tiers (ask / accept-edit / plan). Plan mode physically disables Write/Edit/Bash, forcing the model into read-and-think only. This is harness-level interception, not a prompt-level promise.
• Hooks system: UserPromptSubmit / PreToolUse / PostToolUse / SessionStart / Stop event hooks let you inject custom shell commands (lint, tests, logging) at harness boundaries. The harness exposes itself as a programmable platform.
• Subagents: each subagent is a child process with its own context window — used to execute sub-tasks that can be black-boxed (search, research, run tests), with only the summary flowing back to the parent. Fundamentally: context isolation.
• Slash commands / Skills: common prompt + tool combinations packaged as triggers. The harness compiles them into the system prompt's registry.
• Auto compaction: when context approaches the limit, the harness automatically compresses history (the structured-summary route from Day 2).

None of these are "nice to have" — every single one maps to a concrete failure mode: no plan mode → the model acts before it thinks; no hooks → you re-run lint manually on every commit; no subagent → one big search pollutes the main context into uselessness. Harness design is making "the things you should do to avoid stepping on rakes" part of the system.

Hands-on Example

Reading Claude Code's own .claude/settings.json is the fastest harness onramp — directly observe how a SOTA harness exposes configuration surface:

{
  "permissions": {
    "allow": ["Read", "Grep", "Bash(git status:*)", "Bash(npm test:*)"],
    "ask":   ["Edit", "Write", "Bash(git push:*)"],
    "deny":  ["Bash(rm -rf:*)", "Bash(*--no-verify*)"]
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{"type":"command", "command":"pnpm lint --fix $CLAUDE_FILE_PATHS"}]
    }],
    "Stop": [{"hooks":[{"type":"command","command":"pnpm test --silent"}]}]
  },
  "env": { "BASH_DEFAULT_TIMEOUT_MS": "120000" }
}

This 30-line config does four things that would otherwise need code: tiered permissions (allow / ask / deny with precise glob patterns), save-triggered lint, tests on session end, and a Bash timeout floor. That's the declarative interface a harness gives you — you don't fork Claude Code to make its runtime obey your engineering discipline.

Build Your Own Minimal Harness: 100 Lines of Python That Run an Agent

Background & Principles

The minimal skeleton of a harness has five components: tool registry · loop controller · message buffer · permission gate · recovery. Everything else is a variation. The 100-line Python below runs end-to-end, handles multi-turn tool calls, blocks dangerous commands, and compacts when tokens cross a threshold — it's not pretty, but every line is something you can read and modify.

Hands-on Example

import anthropic, json, subprocess
from pathlib import Path

client = anthropic.Anthropic()
MODEL  = "claude-sonnet-4-6"

# 1) TOOL REGISTRY: schema for the model, handler stays local
TOOLS = {
  "read_file": {
    "schema": {"name":"read_file","description":"Read a file",
      "input_schema":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}},
    "handler": lambda p: Path(p["path"]).read_text()[:8000]
  },
  "run_bash": {
    "schema": {"name":"run_bash","description":"Run a shell command (read-only)",
      "input_schema":{"type":"object","properties":{"cmd":{"type":"string"}},"required":["cmd"]}},
    "handler": lambda p: subprocess.run(p["cmd"],shell=True,capture_output=True,text=True,timeout=30).stdout[:8000]
  }
}

# 2) PERMISSION GATE: physical interception, never trust model self-discipline
DENY = ["rm -rf", "--no-verify", "sudo", "curl ", "> /"]
def permit(tool, args):
    if tool == "run_bash":
        cmd = args.get("cmd","")
        if any(d in cmd for d in DENY): return False, f"denied: {cmd}"
    return True, None

# 3) LOOP CONTROLLER + 4) MESSAGE BUFFER + 5) RECOVERY
def agent(task, max_iters=20):
    msgs = [{"role":"user", "content": task}]
    schemas = [t["schema"] for t in TOOLS.values()]
    for i in range(max_iters):
        r = client.messages.create(model=MODEL, max_tokens=4096, tools=schemas, messages=msgs,
            system="You are a careful research agent. Use tools step by step.")
        msgs.append({"role":"assistant", "content": r.content})
        if r.stop_reason == "end_turn":
            return next((b.text for b in r.content if b.type=="text"), "")
        results = []
        for b in r.content:
            if b.type != "tool_use": continue
            ok, reason = permit(b.name, b.input)
            if not ok:
                out = reason
            else:
                try:
                    out = TOOLS[b.name]["handler"](b.input)
                except Exception as e:
                    out = f"ERROR: {type(e).__name__}: {e}"   # critical: errors go back to the model too
            results.append({"type":"tool_result","tool_use_id":b.id,"content":str(out)})
        msgs.append({"role":"user", "content": results})
    return "hit max_iters"

Four key decisions: (1) schema and handler are decoupled — schema is the contract for the model, handler is your local code, and you never let the model directly eval. (2) Permissions are a physical gate, not a prompt constraint — the deny list runs at the harness layer, and no amount of model persuasion bypasses it. (3) Errors go back to the model rather than raising — this is the foundation of self-recovery; error messages are some of the most valuable signal the model gets. (4) max_iters defaults to 20 — you must have a ceiling, otherwise tool-selection jitter will spin forever.

Close Reading: Building Effective Agents — When You Should Not Write an Agent at All

Background & Principles

Anthropic's late-2024 Building Effective Agents (Erik Schluntz & Barry Zhang) is the most important agent-engineering writing of the past two years. The thing most worth citing isn't the code — it's the taxonomy. It forcibly splits all "agentic" applications into two camps:

• Workflow: LLMs and tools orchestrated by predefined code paths. The developer fully controls the control flow; the LLM only generates content / makes routing decisions at fixed nodes.
• Agent: the LLM dynamically decides which tool to call, in what order, when to stop. Control flow lives in the model.

The payload of this distinction: most production systems should be workflows, not agents. Workflows are more predictable, cheaper, easier to eval, easier to debug. Agents are only the right move when the task is open-ended, the step count can't be planned in advance, and decisions depend on intermediate results (autonomous debugging, deep research, complex codework).

The blog lists five workflow patterns worth memorizing as an architectural checklist:

1. Prompt chaining: cut the task into steps, each step a prompt, output of step N feeding step N+1. Optionally insert gates (fail-fast and roll back).
2. Routing: a classifier prompt routes requests to different downstream prompts / models.
3. Parallelization: split the task into parallel sub-tasks (sectioning), or run multiple voters and aggregate (voting).
4. Orchestrator-workers: an orchestrator dynamically splits sub-tasks, dispatches to workers, collects results — exactly Claude Code's subagent pattern.
5. Evaluator-optimizer: one LLM generates, another evaluates and gives feedback, iterate until quality bar. Great for writing, translation, complex code.

An actual agent sits one level above these five — you escalate to it only when the task is too open to express as a workflow. Quoted directly: "When building applications with LLMs, we recommend finding the simplest solution possible, and only increasing complexity when needed."

Hands-on Example

A typical mis-built-as-agent ask: "read a user-uploaded PDF, extract key points, generate a one-page summary." Sounds agentic? It's actually a prompt chain:

# BAD: build an agent and give it read_pdf / summarize / save as tools
agent("Read report.pdf and give me a one-page summary")
#  → model may skip extraction and fabricate, occasionally forgets to save, hard to debug

# GOOD: prompt-chain workflow with explicit code-level control flow
def summarize_pdf(path):
    text   = extract_pdf(path)                        # pure code, no LLM
    if len(text) > 50_000:
        chunks = chunk_by_heading(text)
        partials = [summarize_chunk(c) for c in chunks]  # parallel LLM calls
        return synthesize(partials)                   # second LLM step
    return summarize_short(text)

When do you actually escalate to an agent? Three signals firing at once: (1) the number of steps can't be known in advance; (2) each step's next move depends on the previous step's result; (3) the final output is verifiable (otherwise the agent goes off the rails and you can't tell). Coding, research, complex data analysis qualify. Writing emails, translation, report generation generally don't.