harness-multitool

Conversations

How the harness stores a conversation and carries it between providers. It is the specification behind ADR 0022, ADR 0023 and ADR 0024 and ADR 0025.

The invariants

IdInvariant
INV-15The daemon holds the conversation. A conversation is always stored, and every message in and out goes through the daemon. Frontends and adapters never hold a conversation of their own.
INV-16One consistent conversation. The daemon's log is the one account of what was said. A provider's own form of a conversation is derived from it and brought up to date from it.
INV-17The format is the harness's own. The log depends on no provider: it stays readable and usable with any provider disconnected.
INV-18Any adapter, at any time, in any direction. A conversation can be switched to any connected adapter between any two messages, and goes on with what was said so far.
INV-19A connected adapter brings its provider's conversations. Connecting a provider's adapter means reading that provider's conversations, writing into them, and resuming them in the harness.
INV-20Consistent at every moment, by design. Every form of a conversation that exists holds what the log holds, and the log holds what the form holds. No step of a conversation is taken on a stale side: what a form gained outside the harness reaches the log before anything reads it, and what the log gained reaches the form before the next call to any provider and when a run ends.
INV-21There and back, at any moment. A conversation can move between the harness and a provider's own program in either direction, any number of times, with nothing lost and nothing to do but open it there. It stays one conversation: no copy, no fork, the same id.

One message

Every adapter follows the same chain.

sequenceDiagram
    participant F as Frontend
    participant D as Daemon
    participant A as Adapter
    participant P as Provider
    F->>D: the message
    D->>D: store it in the log
    D->>A: this conversation's adapter
    A->>A: bring the provider's form up to date from the log
    A->>P: send
    P-->>A: the reply, as it comes
    A-->>D: store it in the log
    D-->>F: bring it to the frontend

Around every step the daemon keeps the forms in line with the log, whichever adapter runs the step:

flowchart TD
    A[A session opens, or a message comes] --> B{Is the form held by the provider's own program?}
    B -- yes, to send --> C[Refused, naming the program: one writer at a time]
    B -- no --> D[Pull: what the form gained past its position goes into the log]
    D --> E[Push: what the log gained past what the form holds is appended to the form]
    E --> F[The step: a provider call, or the provider's own program]
    F --> G{Did the provider's program write the form itself?}
    G -- yes --> H[The form's new position is recorded; its lines are the ones the log already has]
    G -- no --> E
    H --> I[The run ends with log and form the same]
    E --> I

A frontend sends operations and hears events: it holds a view, not the conversation. Everything the engine does (its log, its tools, its calls to a provider) happens in the daemon (IF-19, CON-75).

The format

The conversation is the session's event log (INV-5): one JSON line per event, appended in order. Two things read it.

What the log holds about a provider is marked as such and is never needed to read the conversation: a block a model signed for itself (OpaqueBlock), and the id of a session a provider keeps of its own (BackendSession, ConversationImported).

FormSynced links a session to a form. It records which provider, its id, the position reached in that form, and how many messages of the session the form holds.

The next pull starts at that position and the next push at that count, so neither side is ever read or written twice. A build without the adapter simply leaves the form behind until one with it opens the session.

The forms of a conversation

ProviderIts formReading itWriting it
Claude Codea transcript file it keeps, per directory (IF-18); claude --resume keeps its id and fileits real chain, whole on import and past the position after thatlines appended on its chain, and a new transcript for a session that has none (CON-74)
ChatGPT plan, OpenAI-compatible, Ollamathe history in each request; nothing is kept with the provider—built from the log for every request
Anthropic APIthe history in each request—built from the log for every request, with the blocks this model signed

With Claude Code, the transcript is brought up to all earlier history and the new message goes as the prompt, and Claude Code records it itself. It refuses to go on from a file with no prompt, and writing the message first would send it twice. The end state is the one the chain describes: both hold the message before the reply starts.

What the harness adds to a provider's form is only ever appended: every byte that was there stays as it was. A form is created for a session the first time the session goes on through that provider; one that exists is kept current from then on, through any other provider's turns.

Transformation

Whatever made the log, what a provider receives is valid for it (provider_ready, CON-73).

What the log hasWhat the provider gets
Text, tool calls, tool resultsThe same, in its own wire form
Two user messages in a rowOne message
A tool result and typed text togetherThe result first, then the text
A call with no result, cut off by a stop or a compactionThe call, answered with "no result in the record"
A result whose call is not in what is sentNothing
A block another provider or model signedNothing: it goes only to the model that made it
A summary from a compactionThe summary, and nothing from before it; older requests stay as a one-line note

Reading a provider's form leaves things out, on purpose (CON-72):

Switching

The harness's tools for a delegate

A delegate gets the harness's own tools over MCP, whichever way its row runs: multitool mcp serves the journal, maps and flowcharts of the daemon, the Telegram channel and the reload (mcp__harness__*). So an agent needs nothing outside the harness to keep its records.

An agent changing the harness

An agent can change the harness it runs in. plugins_reload builds from the source at once, while its turn goes on.

At the swap the process and the daemon are replaced, and the daemon's delegates end with it. The conversations reopen from their forms, and the tab that asked gets a message from the harness, which starts its next turn. A reload the user asked for sends no message.

Bringing a journal in

multitool journal import [--aside] <file|-> brings in a journal and its maps from a stream of JSON documents, {"entries": [...]} and {"map": {...}}, under the ids they have, so that what cites them still means them. Run again, it updates what changed; other text under an id refuses the whole import. --aside moves what is there out of the way first, renamed and not deleted. multitool journal export prints the same stream.

Running inside a launcher

./run.sh --under "<launcher>" runs the harness inside a program that starts claude from the PATH and gives it an identity and messages. The harness takes the place of claude there, and a delegate still finds the real one. What the launcher sets reaches sessions as a window's environment, and what it types reaches the composer as a paste:

A delegate is claude -p, and Claude Code offers some tools only in its interactive mode: asking with options, its plan mode, and artifacts. Under the harness those are the harness's own, or absent.

Changing the adapter in the settings

Choosing another adapter or model in the harness's settings moves every open conversation of the window onto it, at once:

Moving between the harness and a provider's program

When things go wrong

CaseWhat happens
A window goes awayIts runs finish in the daemon. The log has the reply, and the next window shows it (CON-76).
A prompt with nobody to answerA denial, once the window has not polled for 30 seconds.
A session open in a window still thereRefused, saying why: one writer to a log (CON-77).
A session whose window went away, its run still onThe run comes to the window opening it: what was said, a waiting prompt, the rest live.
The form was rewound in the provider's programThe log only grows: it gains the new branch and says that a rewind happened.
A form cannot be writtenAn error on screen. The count of what it holds has not moved, so the next step tries again from there.
A conversation open in the provider's programSending is refused, naming it (CON-78).
The adapter is changed while a run is onNot possible: the controls are disabled, and the daemon refuses (CON-79).
A conversation cannot be reconnected to the chosen adapterThe daemon signals the failure and the spinner ends. An error on that conversation's tab; it stays on the adapter it had, and the status line shows that one.
The window goes away during a syncThe daemon finishes it: an append is whole lines, and a new form appears whole or not at all. The next window opens it as it stands.
The daemon stopsIts windows say so. The log keeps everything up to its last flush, and the conversation opens again.
A daemon of another buildReplaced when idle. If it is running conversations, the window works on its own.
Claude Code will not load a transcriptAn error on screen, not a silent loss of context. Its format is undocumented and can change with its version.
A damaged line in a provider's filePassed over and counted (CON-72).

How it is checked

CheckWhat it proves
tools/pty_daemon.pyA TUI killed in the middle of a reply: the daemon finishes, the denied tool never runs, and a new window shows the reply and goes on
tools/real_move.pyReal Claude Code and a real other provider: a conversation made in one, moved back and forth, each side naming every word told on the other; bytes before each append unchanged
tools/pty_attach.pyA TUI killed with a run on: the next window takes the run over with its prompt, and nothing shows twice
tools/real_transform.pyOne session through real providers, each naming what the earlier ones were told
tools/pty_import.pyA conversation brought in: drawn, forked at the first message, then resumed; the original's bytes unchanged
crates/session/tests/e2e.rsThe daemon and a client in one process; a session brought in going on with another provider
crates/api/src/model.rs, crates/backend-claude-code/src/conversations.rsThe rules of transformation; a written transcript reading back equal

This page's source