Skip to main content

What Are Harnesses

A harness is the control system around model calls -- not just the prompt text sent to a provider, but the full environment that governs what the model can do, how it can do it, and how outcomes are verified.

The short version​

When you give a language model a prompt, you get text back. When you give it tools, memory, policy, and verification, you get a harness. The harness is what turns "the model said something" into "the work is done, verified, and traceable."

Why harnesses matter​

A model alone may produce useful output, but it does not produce reliable output. Without a harness, every model call is an isolated transaction: no memory across turns, no policy enforcement, no tool safety, no outcome verification, no honest boundary between "I know this" and "I am guessing."

The harness provides the missing infrastructure:

Without a harnessWith a harness
Model output is treated as truthOutput is validated against schemas and evidence
Every call reinvents policy from prosePolicy lives in code, schemas, and gates
Long tasks lose contextRetained artifacts carry compact, typed state
Tools are all-or-nothingTools are projected per-lane with side-effect classification
Failure modes are invisibleLoop detection, progress tracking, and escalation are explicit
Nothing is auditableEvery step produces evidence of what happened

This is why the best current systems treat the harness as the product boundary and the model as one component inside it.

The core pattern​

Every effective harness shares a common structure. The specifics vary, but there are six ingredients that consistently appear:

  1. State machine -- the harness owns the lifecycle, not the model.
  2. Context planner -- what the model sees is deliberately assembled, not blindly stuffed.
  3. Model and role routing -- different tasks use different models, lanes, and tool profiles.
  4. Tool and capability projection -- not every tool is available to every lane. Side-effect gates, approval rules, and schema validation happen in the harness, not the prompt.
  5. Verification and evidence -- outcomes are proved, not just asserted. Evidence persists across sessions.
  6. Failure taxonomy and loop breakers -- the harness detects and stops semantic loops, repeated failures, and progress stalls.

The environment matters more than prompt cleverness. Structure the task well, and a weaker model can do useful work. Leave the task unstructured, and even a strong model flails.

Proven examples​

OpenCode​

OpenCode is an open-source CLI coding agent with a well-structured harness. It demonstrates several patterns that are directly relevant to understanding harness engineering.

What makes it a harness:

  • Agent system with typed boundaries. OpenCode uses a set of defined agents (Build, Plan, Explore, Scout, General) rather than a single monolithic agent. Each agent has a distinct role, tool set, and output contract. This is isomorphic to Holon's lane-based routing: different contexts, different tools, different verification.

  • Skills as reusable instruction packages. OpenCode's skill system bundles identity, discovery metadata, and instruction/contract resources into reusable packages. Skills like holon-desktop-startup, spec-authoring, and rubberduck-plan-review are not just prompts -- they carry structured metadata, loaded on demand, and govern how specific task families execute. This maps directly to Holon's plugin package model where skills, workflows, and adapter bindings compose into specialist harnesses.

  • Tool catalog with side-effect classification. OpenCode projects a governed tool surface: bash (with description parameter explaining intent), edit, write, glob, grep, read, task, question, webfetch, skill. Each tool has a defined shape, documented side effects, and runtime validation. Not every tool is available in every context. This is the same pattern Holon uses with RuntimeToolDescriptor, side-effect classes, and per-lane tool projection.

  • Progressive disclosure through AGENTS.md. OpenCode uses a navigation-based instruction model: start at README.md, then AGENTS.md, then discover deeper docs through index pages. The model is given an entrypoint and a traversal strategy, not a giant monolithic instruction blob. Holon's docs graph, docs/index.md -> docs/system/index.md traversal, and retained artifact approach follow the same principle.

  • Host-owned configuration surface. OpenCode's AGENTS.md, .opencode/, opencode.json, and skill directories are host-authored, host-governed configuration. The model reads them but does not own them. Holon takes this further by making host authority explicit in the runtime itself rather than just in file conventions.

  • Validation as a first-class step. OpenCode's instructions explicitly require running validation commands (lint, typecheck, test) after changes, surfacing results, and treating passing tests as evidence rather than proof. This is a harness pattern: the host verification surface sits alongside the model, not inside it.

Key ideas Holon draws from the OpenCode pattern:

  • Agent lanes with distinct tool profiles and output contracts.
  • Search-first, incremental context assembly instead of brute-force context loading.
  • File-level tool boundaries (glob, grep, read, edit, write) that keep workspace state inspectable.
  • Validation steps as harness-owned gates, not model-owned suggestions.

Codex (OpenAI)​

Codex is OpenAI's closed-source coding agent with a published harness engineering philosophy. The OpenAI harness engineering article describes a set of patterns that align with Holon's approach.

What makes it a harness:

  • AGENTS.md as a table of contents. OpenAI explicitly argues that AGENTS.md should be a map, not an encyclopedia. Give the model navigation, not one giant blob. This is the same progressive-disclosure pattern OpenCode uses and Holon inherits.

  • Environment over prompt elegance. The OpenAI writeup emphasizes that architecture invariants, repo-local linters, and structured files matter more than clever prompt phrasing. When the environment is structured, the model succeeds. When it is underspecified, even strong models flail. This is a core Holon conviction: push critical rules into schemas, validators, capability gates, and policy code, not just prose.

  • Structured plans as the system of record. Codex produces execution plans that are repo-visible progress artifacts, not just transcript text. Holon's orchestration lifecycle makes this explicit: planning is a bounded, revisable, inspectable state, not a hidden model thought.

  • Measurable optimization categories. The OpenAI article identifies the same optimization families that Holon's harness research targets: model routing, context topology, retrieval quality, tool surface pruning, verification, and evaluation telemetry. These are not prompt engineering tricks -- they are harness architecture decisions.

Key ideas Holon draws from the Codex pattern:

  • The harness, not the prompt, is the product boundary.
  • Enforce invariants with tools (linters, schemas, validators), not just prose rules.
  • Plan explicitly, make progress visible, and keep state outside the model.

Patterns that work​

Across OpenCode, Codex, Anthropic's published work, and Holon's own research, several patterns consistently predict harness quality:

1. Progressive disclosure beats giant manuals​

Give the model an entrypoint and a navigation strategy. Do not stuff every rule, every tool, and every transcript into every call. The model retrieves the smallest relevant slice rather than ingesting one giant blob.

Concrete application: Holon's runtime-capability/discover provides context-aware tool surface projection. The model sees only the tools and context relevant to the current lane and step, not the entire catalog.

2. Legibility and enforcement beat taste-only rules​

The more a rule matters, the less it should live only in prose. Push critical rules into schemas, validators, capability gates, event contracts, tests, or policy code.

Concrete application: Holon's holon-structured-output validates every agent boundary that feeds downstream systems, workflow state, or other agents. A wrong output is rejected at the schema gate, not caught later by reading prose.

3. Externalized state for long-horizon work​

Transcript alone is not durable state. Summaries, plans, decisions, blockers, and evidence need explicit storage and retrieval with freshness, supremacy, and conflict semantics.

Concrete application: Holon's retained session artifacts are typed, host-owned compact context, separate from transcript history. They carry freshness metadata and can be superseded.

4. Subagents help only with real separation​

Multi-agent systems are not automatically better than single agents. They work best when they buy real parallel exploration or context isolation. Otherwise they become expensive prompt-on-prompt overhead with no added capability.

Concrete application: Holon's child lanes are deliberately bounded -- one parent turn may launch at most one read-only child lane, and child execution is sequential. The child must have a meaningfully different role, tool scope, or context from the parent.

5. Route cheap models into narrow lanes​

Weaker models succeed where the harness reduces task entropy: fewer candidate tools, smaller tool sets, typed outputs, deterministic validators. Stronger models are reserved for ambiguity, synthesis, and high-consequence work.

Concrete application: Holon's role-aware routing already distinguishes main-chat from summary-scout, and the harness engineering research defines a RouteScore heuristic based on openness, coupling, consequence, and validator strength.

6. Verify, do not just generate​

Every important output should be validated before it reaches the user or the next workflow step. Cheap first-pass reviewers, structured output contracts, and execution-derived evidence all contribute.

Concrete application: Holon's structured output classes (planner output, reviewer output, tool result, AI step result, script artifact proposal, frozen-tool proposal, repair/fallback proposal) each have a defined schema, required validation gate, and consumer.

What a harness is not​

  • Not a better prompt. The prompt is one surface; the harness is the entire control environment around it.
  • Not a model wrapper. A harness owns policy, state, and evidence. A wrapper just passes calls through.
  • Not a multi-agent framework. Multiple agents can be part of a harness, but they are neither necessary nor sufficient. The harness is the governance layer.

Where to go next​