From Agents
to Harnesses

For three sprints, the “run the compliance gate” skill never fired. Each time, the agent decided in good faith that it satisfied the intent of the rule. No person could point to the run that proved it. We made the gate available as /comply, a command that the reviewer types. Then we could answer the question “did the gate run?” for the first time.

The agent selects the skills. The user cannot make a skill fire. Commands reverse this. The operator invokes a command, so a command is a routing guarantee. It is a named entry point into a known procedure, and you can audit it.

You cannot make the agent choose the correct path. But you can give the operator a path that the agent cannot refuse.

The settlement-rounding step gave a result that changed by one cent between runs. The error was too small to fail a check, and too large to trust. The skill gave the calculation in prose and let the agent derive it again each time. We put the approved implementation into a script. We reduced the skill phase to one instruction: invoke the script. The cent did not move again.

A skill phase in natural language lets the agent interpret the phase and write the code at run time. That is the correct default for new work. But you can make a phase, review it, curate it, and approve it. Then you can package the same code as a script. You can reduce the phase description to an instruction that adapts or invokes that script. The non-determinism of regeneration becomes the determinism of a constant artifact under version control.

“Done” was what the agent thought was done. Sometimes the test suite failed and the diff had no license header. We put a gate at the end of the turn. Now “done” must satisfy a checker that does not negotiate.

The stop-hook fires when the agent tries to end its turn. At that hook point, deterministic code examines the output for structural and semantic properties. You can also drive the loop again from here. A stop-hook can return a block decision with a reason. The block prevents the agent from stopping, and the reason becomes its next instruction. The hook is a hard exit gate.

One guardrail is necessary. The harness sends a stop_hook_active flag. The flag is true when the agent is already in a forced continuation. The hook must obey the flag. If it does not, the hook loops forever.

#!/usr/bin/env python3
"""Stop-hook gate: refuse to end the turn until the build is verifiably clean.

The harness invokes this when the agent tries to stop. Emitting a "block"
decision returns control to the agent with `reason` as its next instruction;
exiting 0 silently lets it stop.
"""
import json, subprocess, sys

payload = json.load(sys.stdin)

# Honor the forced-continuation flag, or this gate loops forever.
if payload.get("stop_hook_active"):
    sys.exit(0)

checks = subprocess.run(["make", "verify"], capture_output=True, text=True)
if checks.returncode != 0:
    print(json.dumps({
        "decision": "block",
        "reason": f"Verification failed; fix before finishing:\n{checks.stdout}",
    }))
sys.exit(0)

Some properties need judgement, not an exit code. An example is the question “is this complete?” For these, a prompt-type or agent-type hook runs a low-cost evaluator in the same slot. The structure is the same. Only the oracle is different.

The migration guide needed four passes before the style linter was quiet. We did those passes by hand. Each time we wrote the prompt again and read the report again. This was the least deterministic part of a pipeline that was otherwise clean. A /loop changed “continue until it is clean” from a habit into a construct.

A /loop construct runs a task again and again until the outcome is satisfactory. The loop is not deterministic on its own. But it increases the minimum result that we can expect. A loop is only as deterministic as its verifier. A loop with no oracle only uses turns.

So loops and hooks go together well. The hook is the oracle and the loop is the driver. Together they move toward a property that you can name.

The overnight batch was correct until one morning. On that morning, an agent applied a plan that no person had seen. We did not want a slower batch. We wanted a hard gate between plan and apply, owned by something that was not the agent. So we wrote the gate, and we called the harness from inside it.

A custom wrapper drives the harness through its API or its CLI. The wrapper is a more specific and more deterministic relative of /loop. The multi-turn question also has a clean answer. The first headless call returns a session id. Later calls resume the same session and keep the full context. This is the same thread-id pattern that graph-based orchestration SDKs use.

The control flow is now in code that the operator owns. The agent gives capability. The wrapper gives the guarantee that a person reviews each change before the harness applies it.

"""Deterministic envelope around an agent harness.

The orchestrator — not the agent — owns the control flow: it opens a
session, holds it open across turns by session id, and inserts a hard
human-approval gate between *plan* and *apply*.
"""
import json, subprocess

def run(prompt, session=None):
    """Invoke the harness for one turn; return its parsed JSON result.

    :param prompt: the operator message for this turn.
    :param session: an existing session id to resume, or None to start one.
    :returns: the result, including `session_id` for continuation.
    """
    cmd = ["claude", "-p", prompt, "--output-format", "json", "--max-turns", "8"]
    if session:
        cmd += ["--resume", session]
    return json.loads(subprocess.run(cmd, capture_output=True, text=True).stdout)

plan = run("Plan the migration. Do not modify any files yet.")
sid = plan["session_id"]

if input("Approve this plan? [y/N] ").strip().lower() == "y":
    run("Apply the approved plan exactly as described.", session=sid)