How AIClaw's Harness Runtime Stops Agents From Pretending They're Done

AIClaw has been pushing a new execution layer into origin/master across three recent commits:

• 2026-07-02 feat: add harness execution protocol
• 2026-07-06 refactor(agent): integrate harness runtime verifier
• 2026-07-09 feat(agent): align harness execution runtime

The feature is called the Harness Runtime. The short version is simple: AIClaw no longer treats "the model says it's finished" as enough evidence that the task is actually complete.

Instead, the executor now runs a contract-and-evidence loop that decides whether an answer is allowed to finish.

The Problem

Most agent systems have an annoying failure mode:

1. The model makes a plan.
2. It calls a few tools.
3. It writes a confident answer.
4. The answer is missing evidence, missing files, or is only a progress update.

If the runtime accepts that answer, the execution trace looks successful even when the work is incomplete.

AIClaw's new harness runtime is built to close that gap. The README now describes it as a layer that turns the user objective into a task contract, records evidence, validates tool and final-answer stages, and injects correction prompts when the work is not actually ready to ship.

The Core Model

The design doc centers the runtime around four parts:

Contract -> Evidence -> Validate -> Correct

Each turn now gets a TaskContract inferred from the user objective, agent profile, tools, files, and plan state. That contract decides things such as:

• whether a plan is required
• whether tool evidence is required
• whether artifacts are required
• whether the output should be treated as text, file, mixed, or JSON

Execution evidence is collected in an EvidenceLedger. It records:

• execution tools that actually ran
• tool events and their status
• generated file artifacts
• plan snapshots
• validation and correction events
• blocker evidence such as permission, auth, policy, not-found, rate-limit, and timeout failures

That gives AIClaw a stable internal record of what happened, not just what the model claimed happened.

Four Validation Gates

The verifier now checks four stages:

Stage	What it checks
pre_tool	Whether a requested tool call is allowed by policy
post_tool	Whether the current round collected usable evidence
pre_final	Whether the candidate final answer is complete enough to finish
pre_save	Whether the final content still satisfies artifact and attachment requirements before persistence

This matters because different failures show up at different times.

For example:

• A tool may be policy-blocked before it runs.
• A tool may run but fail with auth or permission errors.
• A final answer may be non-empty but still be only a progress message.
• A file-delivery task may claim success but omit the generated file link.

The harness catches each of these at the correct stage instead of waiting for the user to notice later.

What Counts as a Real Final Answer

The runtime now classifies final outcomes instead of treating every non-empty answer the same way.

In pkg/harness/outcome.go, AIClaw distinguishes between:

• success
• blocked
• partial
• progress_only
• unknown

That sounds small, but it changes agent behavior a lot.

If the model says things like "I'm continuing", "please wait", or "next I will generate the file", the candidate can be treated as progress_only and rejected at the final gate.

If tools failed because of permission or authentication issues, the harness can require the final answer to explicitly explain that blocker instead of letting the agent drift into a vague summary.

Corrections Instead of Silent Failure

When validation fails, AIClaw does not immediately give up. The verifier can append a structured correction prompt and continue the turn, but only within a bounded retry budget.

The new runtime standardizes these self-correction nudges so that:

• final-gate rejection
• post-tool evidence rejection
• truncated or interrupted model rounds

all consume the same correction budget.

If the agent still cannot produce a valid answer, AIClaw closes the turn with a concrete failure message rather than pretending the run succeeded.

Better Alignment With Plan State

One detail I like is how this feature works with AIClaw's Runtime Plan State instead of bypassing it.

The harness can bootstrap an initial plan when a task contract requires one. The plan template is intentionally simple:

1. Understand the goal and dependencies
2. Execute tools and collect evidence
3. Validate evidence and output requirements
4. Deliver the final answer

That keeps planning inside the runtime, while the verifier checks that the plan reaches a terminal state before the answer is accepted.

A New finish Tool

The July 9 alignment work also adds a built-in finish tool. The model can explicitly submit a final answer through a structured completion signal, and the harness then runs the explicit final gate before closing the turn.

This is a useful pattern for agent runtimes:

• the model can say "this is my final answer"
• the executor still decides whether the answer is actually allowed to finish

That separation makes the system easier to reason about and easier to debug in execution logs.

Why This Matters In Practice

This feature is not about making the agent sound smarter. It is about making the runtime more honest.

If a task needs tool-backed evidence, generated files, or a finished plan, AIClaw now has a concrete mechanism to enforce that. The result is a better execution trace for both developers and operators:

• fewer fake-complete answers
• clearer blocker reporting
• better attachment delivery checks
• visible harness validation steps in logs when something goes wrong

The README now positions AIClaw as a platform that favors explicit execution traces and durable runtime state over invisible agent magic. The harness runtime is a good example of that philosophy becoming real code.

Where To Look In The Repo

If you want to inspect the implementation, the most relevant files are:

• docs/design/agent-harness-runtime.md
• internal/agent/harness.go
• internal/agent/harness_verifier.go
• internal/agent/finish_tool.go
• pkg/harness/contract.go
• pkg/harness/runtime.go
• pkg/harness/outcome.go

The interesting part is not just the validator package. It is the way the verifier, plan state, tool execution, and final message persistence now fit together as one execution contract.

AIClaw is open source and self-hosted, so if you're building agents that need real execution guarantees instead of optimistic chat output, this is one of the areas worth studying next.