Skip to content

Explanation

Harness and model

The most consequential decision in Nawa is a line: what the harness (the engine and everything deterministic) owns, and what the model owns. Most of the rulebook that governs Nawa's development follows from where that line is drawn, and most of the temptations to "fix" Nawa are temptations to move it.

The line

The harness owns the deterministic guarantees: truthful observations and errors, stable identity, persistence, permissions, transactions, tool execution, validation, process lifecycle, and state consistency.

The model owns the intelligent decisions: interpreting intent, planning, selecting tools, researching, coding, diagnosing, and adapting.

The test for where a correction belongs: Is Nawa failing to provide a reliable environment, or did the model make a poor decision inside a reliable environment? Only the first normally needs harness code. If the model lacked facts or capabilities, the harness improves the general tool or observation it supplies. If the model had complete facts and working tools and chose poorly, the fix is minimal, general prompt guidance — never a keyword router, a forced tool sequence, a special-case recovery path, silent rewriting of its output, or a restriction aimed at one model.

What this rules out

  • Scenario-specific rules. A defect in an app the coder wrote is evidence about Nawa, not a pattern to encode. Nawa changes only at a general boundary — capability, observability, reasoning, verification — that applies across languages and frameworks.
  • Claim-verification ceremony. No evidence ledgers or fact ids policing the answer's prose; the deliverable is verified by running it.
  • Prescribed solution paths. A more capable model tomorrow must have more freedom, not less; if a capable model could solve the task with general tools and truthful state, the harness must not lay out the route.

Restrictions are justified only by safety, authorisation, data integrity, interoperability, or deterministic correctness. Within the scopes a permission mode authorises, capabilities are complete and general-purpose; security constrains authority and side effects, not the method.

Facts, not interpretations

The harness's side of the line carries a hard requirement: truthful, complete, factual information. Machine-to-model payloads contain structured facts and verbatim output only — no harness-authored advice, summaries standing in for evidence, verdicts, inferred causes, coaching, or "next action". A failure receipt names its source and phase and includes every applicable fact: owner, executable and arguments, working directory, platform, exit code or signal, timeout and cancellation state, stdout, stderr, diagnostics, completeness. A validator rejection returns the defect code, the location, the expected and observed values, and the rejected input; recovery comes from exact facts, not instructions.

Two consequences shape many tool results you will see:

  • Token limits never delete evidence. A result too large for the request is stored whole in the workspace's evidence and returned with its path, hash, size and completeness, page by page. Nothing is truncated silently.
  • Absence stays labelled. Missing, stale, truncated or incomplete information is reported as such; it is never turned into success or into an invented cause.

Nonbinding facts at decision boundaries

There is one carefully bounded exception to "the model decides": at a decision boundary, the harness may attach a nonbinding classification, default, ranking or proposed priority to observable facts. A decision model's ranking of page elements, its probability that an expectation was met, the classifier's screening verdict on external content — these ride along as facts the model weighs. They never become an unappealable semantic verdict: relevance, sufficiency, applicability and acceptability stay with the model. That is why a ranking never hides an element and an expectation check never blocks an action (Decisions beside the LLM).

Why the line is drawn here

Because the two sides fail differently. A harness defect is deterministic and testable: a lost fact, a wrong permission, a process that outlived its turn. A model's judgement error is not — and encoding today's model's preferred answer into the harness makes tomorrow's model worse at the same task while making the defect invisible. Keeping the guarantees in code and the judgement in the model keeps both fixable in the right place, and keeps every failure classifiable: harness defect, model judgement error, or an information or interface gap — which is the first thing Nawa's own development rules require of any fix.

The rulebook is AGENTS.md in the source tree, sections Harness-model responsibility boundary and Factuality and machine contracts.