Skip to content

How to add a harness adapter

Use this page when you want the engine to drive a harness that has no adapter yet. An adapter is a small Python object. It starts the headless command of a harness, and turns the event stream of the harness into a result that the engine understands.

An adapter also reads a stream of its harness: it gives the tokens so far, as two counts, and the time of the newest event. delegate status and the live view of delegate watch use them to show what an agent does while it runs. The summary line of delegate run gives the tokens too.

You do not read the engine for this. You need the interface below, one recorded stream for each end state, and the contract test of this page.

The interface

An adapter is one object behind one interface. The interface is the harness port, in delegate/ports/harness.py. The adapters are in the package delegate/adapters/.

The engine gives the adapter an AdapterRequest. It has these fields:

  • agent: the name of the agent to run.
  • model: the model, which the engine took from the tier column of the adapter. The adapter never chooses a model.
  • prompt: the brief for the agent.
  • cwd: the working directory, which is a worktree or a temporary copy.
  • report_path: where the agent writes its JSON report.
  • event_stream: the file where the adapter writes the event stream of the harness. The engine chooses it, and writes it to the journal before the agent starts, so delegate status can read the stream while the agent runs. Its directory exists.
  • resume_session: the session id of an earlier run to resume, or None.
  • idle_timeout and report_valid: the idle timeout in seconds, and a function that gives true when the file at report_path is valid. When the check is true and the harness wrote no event for the idle timeout, the adapter ends the session. The helper run_harness does this for you.
  • agent_timeout: the time limit of the session in seconds, or None. When the session runs longer, the adapter ends it. run_harness does this for you too.
  • mcp_servers: the MCP servers of the stack, as McpServer values. Each has a name and one of command (a local server) and url (a remote server). Give the agent these servers in the configuration form of your harness. If your harness can ignore the other MCP configuration of the user and of the project, do that, so the agent gets only these servers.
  • added_directories: the directories outside cwd that the agent can read and change. For a verifier, this is the proof copy of a red proof. When the engine gives the session a scratch directory, that directory is the last entry. Add each one to the session if your harness has a way to do that. If it has none, state that limit on the page of your adapter.
  • environment: environment entries for the session, as a mapping of names to values. They carry the settings of the worktree of the agent, for example the hooks that refuse a push. Add them over the environment that you give your harness, and change none of them. The helper run_harness does this for you. When the engine gives the session a scratch directory, the mapping also sets TMPDIR to that directory. The mapping is empty for a session with no worktree of its own.
  • sealed: the sealed agent for agent, as a SealedAgent with the agent, the handle, the seal directory, the files and the source. The engine made it at the start of the work with the seal method of your adapter. It checked each file of the seal before this request. Start the session from the seal. The value is None when the engine sealed no agent of that name.

The adapter gives back an AdapterResult. It has these fields:

  • exit_status: the exit status of the harness process.
  • end_state: finished, failed, or capped. Any other value is an error. The stream of the session decides it. The exit status does not change it: the engine weighs the exit status itself.
  • session_id: the session id that the harness gave, or None.
  • event_stream: the path of the captured stream, which is the event_stream of the request.
  • ended_idle: true when the adapter ended the session at the idle timeout. run_harness tells you.
  • ended_timeout: true when the adapter ended the session at the agent_timeout. run_harness tells you. Give it as ended_timeout=process.ended_timeout. The helper can end a session at the limit before the session writes an event. In that case, do not treat an empty stream as a failure to start.
  • refused: one pair for each tool call that the permission settings of the harness refused, in the order of the stream: the tool, and the name that the harness gives that setting (for example don't ask). Leave it empty when your harness does not write such a refusal. The engine copies it into the result event, and delegate watch shows it as a problem.
  • final_text: the last text of the agent in the stream, or None. The engine reads the verdict from it when a verifier writes no report file. Leave it None when your harness stream has no such text.
  • reason: the text that says why you ended the session as failed when the stream does not say it. For example, the harness did not load the sealed agent. The engine puts it in the reason of the failed step. Leave it None otherwise.
  • command_errors: one pair for each call of the shell tool whose tool result is an error, in the order of the stream: the command of the call, and the text of its result. Read the pairs from the tool calls and the tool results of the stream, not from the final text. The guard probe reads a denial of the guard from these pairs. Leave it empty when your harness stream does not show the tool results. Then a guard probe through your adapter is never denied. The probe reads only the first error of its own command.
  • refused_commands: the command of each call of the shell tool whose tool result says that a permission mode of the harness refused the tool. The text of such a refusal can hold the word denied. The guard probe uses this list to tell it from a denial of the guard: a refusal of the probe command itself gives inconclusive. Leave it empty when your harness has no permission mode that refuses a tool.

The adapter class has four attributes and six methods. The example in step 2 writes the first two attributes, run and activity. The other parts serve the sealed agent, the setup check and the guard probe. Read them before you register an adapter for a real run.

The attributes:

  • tier_column: the name of the column of the tier table that holds the models of this harness. The engine reads it each time it resolves the model of an agent.
  • supports_resume: true when the harness can resume a session. The engine reads it when it starts a continuation. When it is true, the engine sets resume_session. Otherwise it starts a new agent.
  • checks_setup: true when seal and permits can serve the setup check. The dry run reads it. The start of each run and each resume reads it too, and checks that each verifier permits the gates of its stack. When it is false, the dry run says that it skipped the check, and a run starts with no check. An adapter that has no such guard, as a scripted adapter of a test, leaves it false. An adapter that does not have the attribute counts as false.
  • probes_guard: true when the engine can start the guard probe through run: a session from the sealed agent that tries a command which the guard of a verifier must deny. The engine reads it at the start of a run, at a resume, and in the dry run. When it is false, the engine runs no probe. An adapter that does not have the attribute counts as false. Set it to true only when your harness runs an agent from its seal outside the repository, and your adapter fills command_errors.
  • project_config_paths: the paths, relative to the root of a tree, that the harness loads as project configuration from its working directory. A path of a directory ends with /. A verifier works in a copy of the tree under review. A file at one of these paths in a commit of a specialist would load in the verifier. The engine adds these paths to the built-in hotspots of each stack. Give an empty tuple when your harness loads no project configuration. An adapter that does not have the attribute counts as empty.

The methods:

  • run: takes the request and returns the result.
  • activity: takes the path of a stream that the adapter wrote, and returns an Activity with three fields. tokens_new is the new tokens that the agent used so far: the input, the cache writes, and the output. tokens_cache is the cache reads so far. last_event is the time (UTC) of the newest event that has a time, or None. The stream can be the stream of an agent that still runs, so it can end in half a line.
  • seal: takes the agent name, the directory source and the directory into. It finds the agent file, writes the seal into into, and returns a SealedAgent, or None when it finds no agent file. The engine calls it for each agent at the start of a run, and again at a resume with --agents-changed. It can raise AdapterError to refuse to seal. For the verifier of a stack with verifier-tools, the engine also gives the keyword argument mcp_tools: a tuple of McpTool values, each with a server and a name. Add each tool to the sealed agent in the form of your harness, where the agent has a list of tools. The engine gives mcp_tools only when it is not empty.
  • permits: takes a SealedAgent and a command. It returns None when the guard of the sealed agent permits the command, else the reason of the denial as text. The setup check of the dry run calls it, for an adapter whose checks_setup is true.
  • agent_paths: takes the agent name and the directory source. It returns the paths where the harness looks for the agent file, in the order of its search. The setup check names them when seal finds no agent file.
  • harness_version: takes no argument. It returns the version of the harness as text, or None when your adapter cannot tell it. The engine keeps a denied guard probe on the machine for 24 hours, by the seal of the verifier and this version. A later probe of the same seal on the same version then starts no session. Return None when your adapter has no guard probe. An adapter that returns None, or that does not have the method, keeps no probe.

The port module also gives you AdapterError, for a harness that cannot run the agent at all. The module delegate/adapters/process.py gives you the helper run_harness. It starts the command with the prompt on standard input, and writes the standard output to the event stream of the request. It also ends an idle session after a valid report. It returns the exit status, the standard error, ended_idle and ended_timeout. The module delegate/adapters/streams.py gives you the helper read_events. It reads a line-delimited JSON stream, and ignores half a line at the end. A missing file, or a bad line before the end, raises AdapterError. The package delegate.adapters holds the registry: register adds an adapter under a name, as the tests of the engine do. See the adapter interface for the rules of each part.

Steps

1. Measure the harness

Run the headless command of the harness on a real machine. Write down these facts:

  • The command, and the option for the model, for the agent, and for the session.
  • How the harness takes the prompt. Put it on standard input when you can, so it is not in the arguments.
  • The event that ends a run, and how it shows a normal end, an output limit, and an error.
  • Whether the harness selects a named agent. If it cannot, send the body of the agent file as part of the prompt.

Record one stream for each end state. Write the version of the harness and the date in a manifest, because a harness changes.

2. Write the adapter

This example drives a harness myharness. The prompt goes on standard input. The stream has one JSON event on each line. Each event has a time, and a usage event gives the tokens of one model call: new for the new tokens, and cache for the cache reads.

myharness.py
"""The MyHarness adapter: drive `myharness run --json`."""

from __future__ import annotations

from datetime import datetime
from pathlib import Path

from delegate.adapters.process import run_harness
from delegate.adapters.streams import read_events
from delegate.ports.harness import CAPPED, FAILED, FINISHED, Activity, AdapterError, AdapterRequest, AdapterResult

# The command that starts the harness.
COMMAND: str = "myharness"

# The `status` of the last `result` event, mapped to the end state of the run.
END_STATE_OF_STATUS: dict[str, str] = {"done": FINISHED, "length": CAPPED}


class MyHarnessAdapter:
    """Run one agent through `myharness run`."""

    tier_column: str = "myharness"
    supports_resume: bool = True

    def run(self, request: AdapterRequest) -> AdapterResult:
        command = [COMMAND, "run", "--json", "--model", request.model, "--agent", request.agent]
        if request.resume_session is not None:
            command += ["--session", request.resume_session]
        stream = request.event_stream
        process = run_harness(command, request)
        if not stream.read_text().strip():
            raise AdapterError(
                f"{COMMAND} exited with status {process.returncode} and wrote no event for agent {request.agent!r}: "
                f"{process.stderr.strip()}"
            )
        events = read_events(stream)
        session_id = next((str(event["session"]) for event in events if "session" in event), None)
        results = [event for event in events if event.get("type") == "result"]
        end_state = END_STATE_OF_STATUS.get(str(results[-1].get("status")), FAILED) if results else FAILED
        return AdapterResult(process.returncode, end_state, session_id, stream, process.ended_idle)

    def activity(self, stream: Path) -> Activity:
        events = read_events(stream)
        usages = [event for event in events if event.get("type") == "usage"]
        new = sum(int(event["new"]) for event in usages)
        cache = sum(int(event["cache"]) for event in usages)
        times = [datetime.fromisoformat(str(event["time"])) for event in events if "time" in event]
        return Activity(new, cache, times[-1] if times else None)

The adapter fails loud. A harness that writes no event raises AdapterError with a message that names the agent. A stream with no result event ends failed. The exit status stays beside the end state and does not change it: the engine weighs the exit status itself.

3. Record the streams and write the contract test

A contract test turns a recorded stream into a result and checks the fields of the result. The harness process is the system boundary, so the test replaces it with a stand-in command that replays the recording. The adapter starts the stand-in as a subprocess, as it starts the real command.

Keep the recorded streams in tests/fixtures/.

tests/fixtures/finished.jsonl
{"type": "session", "session": "ses-1", "time": "2026-10-08T19:55:10+00:00"}
{"type": "text", "text": "The work is done.", "time": "2026-10-08T19:55:11+00:00"}
{"type": "usage", "new": 1200, "cache": 3400, "time": "2026-10-08T19:55:11+00:00"}
{"type": "result", "status": "done", "time": "2026-10-08T19:55:12+00:00"}
tests/fixtures/capped.jsonl
{"type": "session", "session": "ses-2", "time": "2026-10-08T19:56:00+00:00"}
{"type": "text", "text": "The work is not", "time": "2026-10-08T19:56:01+00:00"}
{"type": "usage", "new": 900, "cache": 0, "time": "2026-10-08T19:56:01+00:00"}
{"type": "result", "status": "length", "time": "2026-10-08T19:56:02+00:00"}

The manifest holds the version of the harness and the date of the recording, so a reader knows when to measure again.

tests/fixtures/manifest.json
{
  "harness": "MyHarness",
  "harness_version": "1.2.3",
  "recorded": "2026-10-08",
  "fixtures": {
    "finished.jsonl": {"end_state": "finished"},
    "capped.jsonl": {"end_state": "capped"}
  }
}

The test file below holds the cases that each adapter needs. Add a case for each end state and each error that your harness can give.

tests/test_myharness_adapter.py
"""The contract of the MyHarness adapter: it turns a recorded stream into a result."""

from __future__ import annotations

import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

import pytest
from delegate.ports.harness import Activity, AdapterError, AdapterRequest

from myharness import MyHarnessAdapter

FIXTURES: Path = Path(__file__).parent / "fixtures"


def install(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, stream: Path, exit_status: int = 0) -> Path:
    """Put a stand-in `myharness` first on PATH. It records its call, replays the stream, and exits with the status."""
    bin_dir = tmp_path / "bin"
    bin_dir.mkdir()
    log = tmp_path / "call.json"
    stand_in = bin_dir / "myharness"
    stand_in.write_text(
        f"#!{sys.executable}\n"
        "import json, sys\n"
        f"json.dump({{'argv': sys.argv[1:], 'stdin': sys.stdin.read()}}, open({str(log)!r}, 'w'))\n"
        f"sys.stdout.write(open({str(stream)!r}).read())\n"
        f"sys.exit({exit_status})\n"
    )
    stand_in.chmod(0o755)
    monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}{os.environ['PATH']}")
    return log


def request(tmp_path: Path, **changes: object) -> AdapterRequest:
    cwd = tmp_path / "work"
    cwd.mkdir(exist_ok=True)
    (tmp_path / "reports").mkdir(exist_ok=True)  # the engine names a stream in a directory that exists
    fields: dict[str, object] = dict(
        agent="python-specialist", model="gateway/large-model", prompt="## Task\nTicket a\n", cwd=cwd,
        report_path=tmp_path / "reports" / "a.specialist.json", event_stream=tmp_path / "reports" / "a.specialist.stream.jsonl",
    )
    fields.update(changes)
    return AdapterRequest(**fields)  # type: ignore[arg-type]


def test_a_finished_stream_gives_finished_and_the_session_id_and_the_captured_stream(tmp_path, monkeypatch):
    install(tmp_path, monkeypatch, FIXTURES / "finished.jsonl")

    result = MyHarnessAdapter().run(request(tmp_path))

    assert (result.exit_status, result.end_state, result.session_id) == (0, "finished", "ses-1")
    assert result.event_stream == tmp_path / "reports" / "a.specialist.stream.jsonl"
    assert result.event_stream.read_text() == (FIXTURES / "finished.jsonl").read_text()


def test_a_stream_that_stops_at_the_output_limit_gives_capped_and_keeps_the_session_id(tmp_path, monkeypatch):
    install(tmp_path, monkeypatch, FIXTURES / "capped.jsonl")

    result = MyHarnessAdapter().run(request(tmp_path))

    assert (result.end_state, result.session_id) == ("capped", "ses-2")


def test_a_finished_stream_with_a_failing_exit_status_stays_finished_and_keeps_the_exit_status(tmp_path, monkeypatch):
    install(tmp_path, monkeypatch, FIXTURES / "finished.jsonl", exit_status=143)

    result = MyHarnessAdapter().run(request(tmp_path))

    assert (result.exit_status, result.end_state, result.ended_idle) == (143, "finished", False)


def test_the_command_carries_the_model_and_the_agent_of_the_request_and_the_prompt_goes_on_stdin(tmp_path, monkeypatch):
    log = install(tmp_path, monkeypatch, FIXTURES / "finished.jsonl")

    MyHarnessAdapter().run(request(tmp_path, model="gateway/medium-model", agent="python-verifier", prompt="SECRET-BRIEF\n"))

    call = json.loads(log.read_text())
    assert call["argv"][call["argv"].index("--model") + 1] == "gateway/medium-model"
    assert call["argv"][call["argv"].index("--agent") + 1] == "python-verifier"
    assert call["stdin"] == "SECRET-BRIEF\n" and "SECRET-BRIEF" not in " ".join(call["argv"])
    assert "--session" not in call["argv"]


def test_a_continuation_resumes_the_session_of_the_last_run(tmp_path, monkeypatch):
    log = install(tmp_path, monkeypatch, FIXTURES / "finished.jsonl")

    MyHarnessAdapter().run(request(tmp_path, resume_session="ses-1"))

    argv = json.loads(log.read_text())["argv"]
    assert argv[argv.index("--session") + 1] == "ses-1"


def test_a_harness_that_writes_no_event_raises_and_names_the_agent(tmp_path, monkeypatch):
    empty = tmp_path / "empty.jsonl"
    empty.write_text("")
    install(tmp_path, monkeypatch, empty)

    with pytest.raises(AdapterError, match="python-specialist"):
        MyHarnessAdapter().run(request(tmp_path))


def test_the_activity_of_a_stream_gives_its_tokens_and_the_time_of_its_newest_event():
    activity = MyHarnessAdapter().activity(FIXTURES / "finished.jsonl")

    assert activity == Activity(1200, 3400, datetime(2026, 10, 8, 19, 55, 12, tzinfo=timezone.utc))


def test_the_activity_of_a_live_stream_that_ends_in_half_a_line_reads_the_complete_lines(tmp_path):
    lines = (FIXTURES / "finished.jsonl").read_text().splitlines(keepends=True)
    live = tmp_path / "live.jsonl"
    live.write_text("".join(lines[:3]) + lines[3][:20])

    assert MyHarnessAdapter().activity(live) == Activity(1200, 3400, datetime(2026, 10, 8, 19, 55, 11, tzinfo=timezone.utc))


def test_each_recording_is_in_the_manifest_with_the_harness_version_and_the_date():
    manifest = json.loads((FIXTURES / "manifest.json").read_text())

    assert manifest["harness_version"] and manifest["recorded"]
    assert sorted(manifest["fixtures"]) == sorted(path.name for path in FIXTURES.glob("*.jsonl"))

Three more cases belong in the file for a real harness. Give one case for a stream that is cut off before its last event. Give one for a line that is not JSON. Give one for the activity of a stream that has no event with a time.

4. Connect the adapter to the kit

The command-line driver finds a built-in adapter by name and hands it to the engine. The engine imports the port only. Make these changes in the package delegate:

  1. Put the adapter module in delegate/adapters/, beside claude_code.py and opencode.py.
  2. Add a branch for the name in get in delegate/adapters/__init__.py.
  3. Add the name to ADAPTERS in run/workflow.py, so a workflow can name it.
  4. Add a column that tier_column names to each tier in tiers.toml.

Then check the model. A test runs delegate run with the stand-in command and a workflow that names the adapter. It reads the model from the call of the stand-in. The model must be the model of the tier column for the mode. See tests/test_run_opencode.py in the repository for the pattern.

A user who cannot change the kit can still add a column in a tier file of their own. See how to point the tiers at a gateway.

5. Run the harness for real, and write the reference page

The recorded streams show that the adapter reads them. They do not show that the real harness gives them. Run the adapter once against the real harness on a real machine. Write the reference page of the adapter. Put in it the version of the harness, the date, the command, the end states, the recorded streams, and the result of the run. Link the page from the README. See the OpenCode adapter reference for a page of this kind.

The contract-test pattern

Each adapter has three kinds of test:

  1. Contract tests replay a recorded stream through a stand-in command and check the fields of the result. They also check the command: the model and the agent of the request, and the prompt on standard input. And they check the activity of a recorded stream. They also check the activity of a part of a stream that ends in half a line, as a live stream can.
  2. A model test runs delegate run through main(argv) and checks that the model on the command comes from the tier column of the adapter.
  3. A live run on a real machine, noted once in the reference page.

A test never imports a private function and never checks a log line. The stand-in replaces only the harness process.

Version main