Harness Design Dimensions and Archetypes¶

A source-grounded study of 70 agent-system projects reduces harness infrastructure to five recurring design dimensions and five archetypes — a population-level lens for reading and comparing harnesses.

Related lesson: What a Harness Is — this concept features in a hands-on lesson with quizzes.

Why dimensions beat ad-hoc comparison¶

Harness code — the non-LLM mediator handling tools, context, delegation, safety, and orchestration — shapes agent behavior as much as the model does. The evidence is independent: pure harness changes took Terminal Bench 2.0 from 52.8% to 66.5% (LangChain). So projects diverge sharply in how they engineer this layer.

Hu Wei (2026) "Architectural Design Decisions in AI Agent Harnesses" analyses 70 publicly available agent-system projects through source code and technical material. The result is a shared vocabulary for reading harness choices across the whole population.

Five design dimensions¶

graph TD
    H[Agent Harness] --> SA[Subagent Architecture]
    H --> CM[Context Management]
    H --> TS[Tool Systems]
    H --> SM[Safety Mechanisms]
    H --> OR[Orchestration]

Each dimension is a position choice, not a binary (arXiv:2604.18071):

Subagent architecture — flat, hierarchical, or peer coordination between specialized agents.
Context management — file-persistent, hybrid, and hierarchical strategies dominate the corpus; ephemeral in-memory is rarer in production systems.
Tool systems — registry-oriented systems are dominant; MCP- and plugin-oriented extensions are emerging.
Safety mechanisms — intermediate isolation (sandboxes, permission prompts) is common; high-assurance audit (provenance-aware decision auditing) is rare.
Orchestration — the control flow and scheduling layer around agent loops.

The paper complements the 12-dimension / 13-system scaffold-architecture taxonomy (arXiv:2604.03515) detailed in the next section: finer-grained analysis of individual scaffolds, lower population coverage. Pick the five-dimension view for reading across the whole population; pick the 12-dimension view when characterizing a single scaffold in depth.

How design choices cluster¶

Design dimensions are not independent. arXiv:2604.18071 reports three recurring clusters:

Cluster	What pairs with what
Coordination ↔ context	Deeper subagent coordination pairs with more explicit context services
Execution ↔ governance	Stronger execution environments correlate with more structured governance
Tooling ↔ ecosystem	Formalised tool-registration boundaries align with broader ecosystem ambitions

The implication for design: a single upgrade rarely lands in isolation. Adding multi-agent coordination without matching context services leaves agents starved of state. Tightening tool boundaries without ecosystem commitments imposes cost without the reach that justifies it.

Five archetypes¶

The same paper groups the 70 projects into five recurring archetypes (arXiv:2604.18071):

Archetype	Profile
Lightweight tools	Minimal harness infrastructure; a thin loop around tool calls
Balanced CLI frameworks	Moderate complexity; CLI-oriented with adaptive loops and registry tools
Multi-agent orchestrators	Deep coordination, explicit context services, role-specialized subagents
Enterprise systems	Structured governance, stronger isolation, broader ecosystem scope
Scenario-verticalised projects	Domain-specific harnesses optimized for one class of workflow

Archetypes are descriptive clusters, not prescriptions. A project's archetype emerges from the dimension choices that reinforce each other — which is why the co-occurrence clusters matter more than any single dimension.

Reading a harness with the framework¶

Apply the five dimensions in order when evaluating or designing a harness:

Where on the subagent spectrum — single loop, delegated roles, or peer coordination?
Which context strategy — file-persistent, hybrid, hierarchical, or ephemeral?
Which tool system — direct shell, typed registry, MCP, or plugin?
Which safety posture — none, intermediate isolation, or high-assurance audit?
Which orchestration layer — fixed pipeline, adaptive loop, or external scheduler?

Read the cluster alignments to predict where effort is missing: a project with multi-agent coordination but no file-persistent context is likely under-invested on context services; one with formal tool registration but no ecosystem scope is paying integration cost without reach.

When the framework under-delivers¶

Single-script tools — only one or two dimensions are meaningful, so the archetype collapses to "lightweight tools" without informing design.
Pre-production prototypes — co-occurrence patterns assume differentiated systems, and early harnesses are not yet clustered.
In-house vertical harnesses — the domain predetermines the archetype, so the framework adds vocabulary without decision support.

Example¶

Reading two public harnesses through the dimensions:

Harness A, a terminal coding agent: single control loop (flat subagent), accumulated in-memory context with summarization on threshold, typed tool registry exposed as a shell-like interface, permission prompts before destructive actions, adaptive orchestration. Archetype: balanced CLI framework. Expected co-occurrence gap: limited multi-agent coordination means no need for explicit context services, which matches its single-context strategy.

Harness B, a multi-agent research system: hierarchical subagents with orchestrator-worker topology, file-persistent progress files and hybrid per-agent context, plugin-style tool registration with MCP extensions, sandbox isolation and audit logging, external scheduler driving orchestration. Archetype: multi-agent orchestrator / enterprise. Co-occurrence checks pass: deep coordination paired with explicit context services; formal tool registration paired with ecosystem scope.

The dimensions frame the differences; the archetypes name the clusters.

The 12-dimension scaffold taxonomy (single-scaffold view)¶

For characterizing one scaffold in depth, source-code analysis of 13 open-source coding agent scaffolds reduces the same harness layer to 12 dimensions grouped in three layers. Architecturally distinct systems produce identical surface capabilities — trajectory studies observe outputs without explaining differences — so the taxonomy makes the design choices comparable.

graph TD
    S[Coding Agent Scaffold] --> CA[Control Architecture]
    S --> TEI[Tool & Environment Interface]
    S --> RM[Resource Management]

    CA --> CA1[Loop topology]
    CA --> CA2[Planning strategy]
    CA --> CA3[Search / branching]
    CA --> CA4[Error recovery]

    TEI --> TEI1[Tool abstraction level]
    TEI --> TEI2[Environment access model]
    TEI --> TEI3[Feedback routing]
    TEI --> TEI4[Output typing]

    RM --> RM1[Context budget strategy]
    RM --> RM2[State persistence]
    RM --> RM3[Tool-call capping]
    RM --> RM4[Cost guardrails]

Layer 1, control architecture, decides what to do next and when to stop. Loop topology is a spectrum: fixed pipelines run a predetermined sequence; adaptive loops react to tool output; MCTS scaffolds build a search tree with backtracking. Moatless Tools implements full MCTS with numeric reward and backpropagation (arXiv:2604.03515).

Topology	Predictability	Compute	Best for
Fixed pipeline	High	Low	Well-defined, repeatable tasks
Adaptive loop	Medium	Medium	Observation-reaction cycles
MCTS / search	Low	High	Unknown solution paths

Planning strategy decides whether the scaffold reasons about future steps before acting (planning-first emits a plan then executes; interleaved adapts at the cost of inspectability). Error recovery ranges from aborting on first failure to retry loops, exception-specific handlers, and rollback to checkpoints.

Layer 2, the tool and environment interface. Tool abstraction level varies from direct shell (maximum flexibility, no boundary for testing) to typed registries that reject malformed calls and enable reasoning and execution separation. Environment access model sets what the agent can observe and modify (sandboxes give a recoverable surface). Feedback routing controls where tool results go: returning all output to context is simple but expensive, while routing large outputs to disk with a summary preserves budget (Anthropic context engineering guide).

Layer 3, resource management, handles the bounded resources of a model-in-a-loop. Context budget strategy decides what enters context and when it is pruned (see Loop Strategy Spectrum). State persistence decides what survives between iterations: in-memory state is lost on failure, while file-backed state enables resumption via progress files and feature list files. Tool-call capping and cost guardrails bound unbounded loops per session, per tool, or per cost.

Scaffold architectures resist discrete classification (arXiv:2604.03515): 11 of 13 agents analyzed compose multiple loop primitives rather than implementing one. Treat dimensions as continuous scales. Ask "where does this scaffold sit on the control strategy spectrum?" rather than "is this a pipeline or an agent?" Reading three open-source scaffolds through the control layer: Agentless runs a 10-stage pipeline of independent scripts linked by JSONL on disk — predictable, auditable, cheap, but degrades when reproduction needs exploration; SWE-agent runs a single ReAct loop over a typed tool registry and restricted shell — more resilient to unexpected paths, higher per-run cost; Moatless Tools runs full MCTS — strongest on open-ended tasks, highest compute, hardest to debug when a bad branch dominates. The 12-dimension view adds overhead without value for single-script tools (no meaningful control architecture to classify) and retrospective audits (it tells you what was built, not whether the design was right).

Key Takeaways¶

Five dimensions — subagent architecture, context management, tool systems, safety mechanisms, orchestration — cover the non-LLM choices in an agent harness.
Dimension choices cluster: coordination with context services, execution with governance, tooling with ecosystem. Single-axis upgrades under-perform the paired investment.
Five archetypes (lightweight, CLI, multi-agent, enterprise, verticalised) are descriptive clusters derived from the 70-project corpus, not prescribed templates.
The framework is most useful at ecosystem level; pair it with a finer-grained taxonomy when characterising a single scaffold.
Rare-in-corpus signals are actionable: high-assurance audit is uncommon, so any project claiming it should be verified, not assumed.