Holon's Harness Model

Holon's harness is the runtime control system that governs every model interaction. It is not a prompt library, not a multi-agent framework, and not a provider abstraction layer. It is the product boundary between human intent and verified outcomes.

The six-layer harness

Holon structures harness responsibility into six layers, each owned by the runtime:

1. Host-owned state machine

The runtime, not the model, owns the lifecycle of every turn. From user intent to verified completion, the harness decides what happens next, not the model.

Key properties:

• The runtime is the system of record for session state, workflow state, approvals, and evidence.
• Model output is one input to the state machine, not the driver of the state machine.
• The model can suggest next steps but cannot change the lifecycle itself.

Implementation status (0.1.0): The goal/turn lifecycle with explicit state transitions, bounded plan creation, run management, and evidence capture are implemented. Agent as a runtime concept (agent lanes, tool-based agents) is planned but not yet implemented.

2. Context planner

What the model sees is deliberately assembled, not blindly concatenated. Every lane has an explicit input budget:

B_in = B_policy + B_tools + B_artifacts + B_retrieval + B_recent + B_user + B_margin

Where each term is measured and bounded:

• B_policy: stable host instruction and lane contract (cacheable prefix).
• B_tools: tool schema and descriptions for the current lane.
• B_artifacts: retained host-owned context from prior turns.
• B_retrieval: freshly retrieved documents or snippets.
• B_recent: verbatim recent transcript for continuity.
• B_user: the current turn or task payload.
• B_margin: reserved room for tool calls, output, and recovery.

If the budget does not fit, the answer is retrieval reduction, compaction, decomposition, or blocked outcome -- not "hope the model sorts it out."

3. Model and role routing

Different lanes use different models, tool profiles, and context configurations. Holon routes by task properties, not by vague persona:

• Lane: main-chat, summary-scout, planner, reviewer, child lane. Each lane has a defined role, tool set, output contract, and model preference.
• Routing factors: task openness, artifact coupling, error consequence, validator strength.
• Escalation: when a cheaper lane fails validation, the harness escalates to a stronger model lane with evidence of what went wrong.
• Route telemetry: every routing decision is logged with the reason, the outcome, and the estimated regret. The harness learns from routing mistakes.

Current status: role-aware routing exists for main-chat and summary-scout. Broader lane routing, deeper subagents, and richer cost telemetry remain future work.

4. Tool and capability projection

Not every capability is available to every lane. The harness projects a filtered tool surface based on:

• Side-effect class: read-only, local write, external write, destructive, credential-sensitive.
• Approval requirements: write and destructive operations require explicit user or policy approval.
• Lane constraints: child lanes get narrower tool sets than parent lanes.
• Readiness: tools must pass dependency, target, and health checks before appearing.

Key mechanisms:

• runtime-tool/list provides the low-context catalog view.
• runtime-capability/discover provides context-aware progressive disclosure, ranking tools by relevance for the current interaction.
• runtime-tool/call executes a validated and approved tool invocation with evidence capture.
• Function calling is one model-facing projection of tools, not the execution authority itself.

Safety defaults:

• Read-only by default for model-callable tools.
• Write tools remain runtime-only (runtime-tool/call) unless explicitly approved.
• Unknown execution lanes fail closed.
• MCP and generic plugin lanes remain blocked for live execution.

5. Verification and evidence

Every step that produces output also produces evidence. Verification is structural, not prose-based:

Structured output contracts:

Output class	Producer	Consumer	Required gate
Planner output	Planning agent	Workflow runner	Schema validation
Reviewer output	Review agent	Plan approval gate	Schema validation
Tool result	Capability executor	Workflow/frozen-tool caller	Declared output schema or typed failure
AI step result	Model-backed workflow node	Workflow runner	Schema, budget, and fallback policy
Script artifact proposal	Agent generating scripts	Frozen-tool promotion gate	Purpose, inputs, command, side effects, validation
Frozen-tool proposal	Crystallization process	Promotion validator	Schema, provenance, and evidence
Repair/fallback proposal	AI fallback agent	Failing deterministic step	Schema and policy gate

Evidence capture:

• Run events record what executed, with what inputs, producing what outputs.
• Subprocess evidence includes exit code, duration, and bounded stdout/stderr previews.
• Frozen-tool proposals carry provenance links to the runs that produced them.
• Evidence persists across sessions and supports audit, review, and replay.

Implementation status (0.1.0): Structured output validation is implemented for 6 output classes. Tiered run events with evidence records are implemented. Frozen-tool promotion lifecycle and provenance links are partially implemented. Broader verification lanes (automatic reviewer agents) remain planned.

6. Failure taxonomy and loop breakers

The harness detects and stops semantic loops, not just code-level infinite loops:

Failure surface	Signal	Response
Clarification loop	Repeated similar questions, no new state	Ask once better, then block or assume explicitly
Retrieval loop	Repeated sources/files, low novelty	Narrow scope or escalate
Tool paralysis	High tool-choice entropy, frequent invalid selection	Shrink toolset or improve descriptions
Summary telephone	Loss of key details between artifacts	Reduce hierarchy depth, preserve raw refs
Orchestration tax	High overhead-to-task token ratio	Simplify lane stack
Planner-reviewer deadlock	Repeated mutual disagreement	Define authoritative stop or human gate
Repair loop	Retrying without new evidence	Declare blocked or escalate

The harness also tracks monotonic progress explicitly. If Progress_t <= 0 for k consecutive iterations, the harness stops, escalates, or declares blocked rather than continuing to spin.

Honesty defaults:

• The harness can say "I don't know" or "this is blocked" with provenance.
• Unknown outcomes are not silently replaced with plausible guesses.
• Fallback behavior is declared, not improvised.

Implementation status (0.1.0): The honesty defaults and failure taxonomy are design goals. Current implementation has basic run cancellation (queued runs only), plan-scoped admission (one active run per plan), and linear plan revision. Full loop detection, progress tracking, and automatic escalation remain future work.

Harness profiles and self-upgrade

Holon separates harness configuration from model prompting through harness profiles.

Harness profiles

A HarnessProfile is a typed configuration record that defines how a harness lane behaves:

• Agent configuration: role, instructions, tool allowlist.
• Routing policy: which model for which task properties, escalation rules.
• Parallelism and depth: fan-out limits, child depth caps, concurrency bounds.
• Context management: prompt section budgets, artifact retention, compaction triggers.
• Retrieval policy: search scope, authority ranking, freshness weights.
• Tool projection: side-effect class ceilings, approval gates, readiness requirements.
• Verification policy: structured output contracts, reviewer lanes, evidence requirements.
• Clarification posture: how to handle ambiguity, when to ask vs assume.
• Rollout and activation: canary, rollout percentage, rollback, lifecycle state.

Profiles resolve through a deterministic precedence chain: system -> user -> workspace -> task-family -> session -> goal. Non-overridable invariants (child depth, concurrency, write-tool boundaries, profile attribution) are enforced by the runtime, not by profile content.

Implementation status (0.1.0): Harness profile CRUD (create, read, list) and profile resolution are implemented via CLI and runtime. The profile DTO defines all typed sections. Profile-driven routing, automatic metrics feedback, and rollout/canary gating are not yet implemented.

Self-upgrade

Holon's self-upgrade system governs how harness profiles evolve:

• Profiles are versioned, measured, and rolled out with canary gating.
• Metrics (verified success rate, route regret, escalation precision, loop incidence) feed profile quality assessment.
• Rollback is automatic if a new profile regresses on guarded metrics.
• No hidden prompt mutation or global learned defaults -- profile changes are visible, versioned, and attributable. Implementation status: These self-upgrade behaviors (canary rollout, automatic metrics feedback, auto-rollback) are future-state. Current implementation supports harness profile CRUD and resolution only. Profile-driven routing and canary gating are planned but not yet implemented.

Specialist harness compositions

A specialist harness is a package-level composition that bundles a harness profile with the skills, workflows, adapter bindings, evals, and verification policies needed for a specific task family. It is defined by the repo-internal Specialist Harness Contract spec as a packaging convention, not a new executable runtime.

A specialist harness package declares:

• A harness profile reference (owned by self-upgrade).
• Task families (e.g. docs, research, code-review).
• Required assets (workflows, skills, adapter bindings, eval packs).
• Verification and activation posture.

This is Holon's answer to "how do I share a proven harness configuration for a specific kind of work?" -- it is a marketplace package that composes existing v2-core assets under a named profile, not a parallel harness runtime.

Concrete example: docs-research harness

A low-risk first specialist harness prototype is described in the Specialist Harness Contract spec. See also RM-current-readiness-007 in the active roadmap.

Where to go next

• Tooling Taxonomy -- the precise definition of every term used above (agent, tool, skill, capability, frozen tool, etc.)
• Orchestration Lifecycle -- the step-by-step lifecycle from intent to evidence
• AI Contract And Conformance Boundaries -- host authority and instruction-contract rules
• Plugin Packages -- how packages surface capabilities through the harness
• Cli Architecture -- how the holon CLI exercises the same harness
• Known Issues -- current limitations and what's implemented vs planned