Skip to main content

Agent harness architecture study November 2026

Dated research snapshot: 2026-11-11. Local baseline: 71397f88e1eabd995c3eba6173ee9307f470d37c.

Agent harnesses differ most in how they preserve valid state across tool execution, cancellation, context reduction and restart. An extensible agent loop is useful, but it needs explicit contracts for message projection, resource ownership and effect settlement. Agent-compositor already has replaceable execution strategies and many of the visible features in the surveyed systems. The most concrete findings concern replay integrity and the durability of acknowledged progress.

This is design history and a source study, not the current product reference or an approved implementation roadmap. Current behavior remains documented in agent features, core customization, UI and storage contracts and the plugin-owned guides.

Scope and evidence​

The comparison covers 18 systems. Each external source link below includes an immutable commit. Source branches can contain optional or experimental implementations; presence in a repository does not establish availability in a published binary. Pi's ordinary coding-agent CLI, its extension examples and the separate experimental applications in its monorepo must be evaluated separately.

External implementation and test sources were inspected. Their tests describe intended contracts; they were not executed as part of this study. Assertions were checked for the key findings rather than treating a test title as proof. For example, some OpenHands locking tests only assert result count, so the lock manager implementation is needed to establish the resource-acquisition mechanism.

Two deterministic local API probes were executed against the baseline. They used ScriptedProvider, an in-memory tool and an injected failing journal, with no remote model, shell tool or project file mutation. Their observations are recorded below. They establish the local behavior described, not the response of a particular external API.

Feature vocabulary​

LayerQuestions that distinguish implementations
Turn executionWhat is one turn or step? Which events close it? Can input arrive while it runs?
Model boundaryWhich messages and tools are sent? Where are provider metadata, retries and usage normalized?
Tool admissionWhen are arguments validated, hooks applied and permissions evaluated?
Tool schedulingWhich calls may overlap? Are conflicts defined globally, by tool or by resource?
Context projectionIs the model request a view of durable history, or the same mutable message array?
CompactionWhich atomic groups survive? How are summaries, recent work and previous summaries combined?
PersistenceWhat must be stored before acknowledging a prompt or running an effect? What survives an abrupt process exit?
CancellationDoes it cancel one prompt, a turn, queued work, child agents or the whole session? How are pending calls settled?
DelegationWhat context, model, permissions, tools, budgets and lifetime does a child inherit?
Background workWho owns the process? How is completion delivered and deduplicated? What happens after reload or restart?
MemoryAre notes, recalled conversations, skills and context summaries separate stores with separate write authority?
Extension boundaryCan an extension add tools, replace a strategy, replace a context engine or supply the entire harness?
Client protocolCan clients reconnect, interrupt, answer approvals and identify the durable session without parsing terminal output?

Systems and implementation contracts​

SystemHarness mechanismContract worth studyingEvidence
CodexTyped Rust turn and tool runtime; parallel admission, approvals, sandbox attempts, child-agent ownership and context recovery.Cancellation completes pending dynamic calls and excludes a late response from subsequent context.Source · Tests
OpenCodeEffect services combine session storage, inboxes, execution ownership, scoped tool fibers and background subagent completion.Completion observers survive a moved or evicted child and notify its parent once in the tested generation.Source · Tests
PiA configurable agent loop separates internal messages from provider conversion; extension hooks, steering and follow-up queues surround each step.Parallel tools emit completion events as they finish but persist results in source order; any sequential tool serializes the batch.Source · Tests
Gemini CLIA scheduler separates validation, policy, confirmation and execution; parallelizable calls form ordered waves.Read-only defaults can be overridden by the call's wait_for_previous behavior; topic updates retain a special ordering rule.Source · Tests
Qwen CodeAgentCore is complemented by a workflow interpreter, dispatch scheduler, journal, result validation and aggregate budgets.Pause holds admission and result delivery; abort rejects queued dispatches and prevents a later resume of that scheduler.Source · Tests
Mistral VibeA Rust state machine accepts commands and returns actions for the surrounding runtime; checkpoints capture validated engine state.Checkpoint restoration rejects inconsistent tool identities, arguments, batch cardinality and program continuation state.Source · Tests
Kimi Code CLIDependency-injected services connect a journaled machine engine to prompts, tool execution, compaction and permission policies.Active-turn cancellation, queued-turn cancellation and disposal have distinct outcomes; disposal settles all pending turns.Source · Tests
ClineSessionRuntime retains cross-run state while AgentRuntime owns one execution; model/tool hooks and prepareTurn form explicit boundaries.Recovery avoids replaying a turn that already performed provider-executed tool activity; approval preparation precedes opted-in parallel execution.Source · Tests
Kilo CLIAn OpenCode-derived Effect runner combines role policies, context preparation, tool materialization, snapshots and overflow recovery.The tool registry is materialized for the selected agent's permissions. Shared ancestry does not establish parity with current OpenCode.Source · Tests
Grok BuildRust session actors coordinate a sampler, ToolBridge, input queues, persistence acknowledgements and child execution.Cancellation reaches the sampler and settles the originating request; deeper queued prompts can remain visible.Source · Tests
AiderCoder assembles selected files and repository context, parses an edit format, applies changes and feeds failures back through bounded reflection.Editing has explicit parsing and application semantics, including malformed or incomplete SEARCH/REPLACE blocks.Source · Tests
mini-SWE-agentA small model/environment loop records actions and observations; environment implementations own process execution and isolation.Step, cost, time and repeated-format-error limits are distinct termination conditions; timeout observations can retain partial output.Source · Tests
GooseAn ordered re-entrant operation pipeline runs over persisted conversation state, with effect handling for tools, approvals, compaction and subagents.Cancellation finalizes interrupted operations and open tool calls rather than merely dropping the active future.Source · Tests
Hermes AgentA memory-provider lifecycle and a replaceable context engine are separate from the conversation loop and delegation backend.Forked agents suppress memory writes and recall while retaining the pre-compression checkpoint path.Source · Tests
OpenClawThe gateway selects registered harnesses and context engines; registration tracks ownership, capabilities and session cleanup.Required reset failure is propagated after sibling cleanup settles; plugin ownership controls registry replacement.Source · Tests
DeepSeek HarnessThe agent loop, tools and context components are Cordis services; an event log is folded into a separately validated model-visible surface.Invalid content replacements leave incremental state unchanged; tool-result rewrites preserve identity and non-content fields.Source · Tests
CrushA Go coordinator builds Fantasy-backed session agents; per-session dispatch, queues, cancellation and permission services remain explicit.A session grant is bound to the issued command and request; fields supplied by an answering client cannot widen it.Source · Tests
OpenHands SDKConversation state is backed by an EventLog; the agent executes action batches and context condensers construct a view of the history.Declared resources control locking; undeclared resources fall back to a tool mutex, while explicitly empty declarations permit concurrency.Source · Tests

Crush is included for architecture inspection as a source-available project; its FSL license must not be conflated with MIT or Apache-2.0. The OpenHands row concerns the current software-agent SDK rather than assuming that the older standalone CLI remains maintained. Claude Code and other proprietary engines cannot receive the same source-level treatment merely because their integration documentation is public.

Turn state and effect execution​

Three useful designs emerge from the inspected systems.

Pi keeps an understandable loop with explicit callbacks around context transformation, request preparation and tool calls. It has separate steering and follow-up queues: steering can enter at a step boundary, while follow-up work can keep the outer loop alive after it would otherwise stop. These are different scheduling promises.

Vibe exposes a state transition boundary. HarnessSession.apply works on a candidate state and commits it only if the command is accepted. The surrounding runtime performs actions and returns results. Its checkpoint validation covers engine state, including pending tools and program continuations, rather than treating a checkpoint as an arbitrary serialized object. Vibe transition code and checkpoint invariants are useful references for a replacement engine contract.

Goose builds an ordered operation pipeline over persisted conversation state. The pipeline includes operations for inference, tools, approvals, compaction, steering and stopping. Cancellation has a finalization path for operations and unresolved calls. That makes cleanup part of the execution protocol. See Goose machine and cancellation cases.

These patterns can coexist: an engine can have small internal transitions while exposing a higher-level asynchronous session API. Replacing the loop should preserve host-owned authorization, accounting, cancellation and result publication boundaries.

Parallel tool scheduling​

Four policies should not be collapsed into a single parallel flag.

ImplementationAdmission policyConsequence
PiA sequential configuration or any sequential tool makes the entire batch sequential. Otherwise prepared calls execute concurrently.Simple batch-wide barrier; completed results are stored in declaration order.
CodexParallel-capable tools take a shared lock; exclusive tools take a write lock.Parallel work and exclusive work use one admission gate.
Gemini and ClineOrdered groups of adjacent parallelizable calls execute together.Sequential calls separate concurrency waves. Gemini additionally interprets explicit wait behavior.
OpenHandsTools declare resource keys; shared keys serialize. Locks are acquired in sorted order. Undeclared resources fall back to a tool-wide mutex.Different files or sessions may overlap while calls touching the same declared resource wait. Correct declarations matter.

The evidence is in Pi's scheduler, Pi's ordering tests, Codex's gate, Gemini's scheduling tests, Cline's execution tests, OpenHands' executor and resource lock manager.

Two orders must remain separate: UI completion order and the canonical order of the messages sent to the provider. Parallelism must also preserve argument validation and permission admission. Cline explicitly tests approval preparation before parallel execution.

Agent-compositor's default batch strategy is sequential. Its public batch context already supports a replacement strategy that calls context.execute concurrently, and the current customization tests exercise that path through the normal permission gate. The public ToolSpec has no resource-declaration contract equivalent to OpenHands. Resource-aware scheduling would be an additional contract, not a missing ability to replace the scheduler.

Durable history and model context​

An audit log and a model request serve different purposes. A log must retain enough information to explain what happened; a model request must satisfy provider structure and size constraints.

DeepSeek Harness makes the distinction explicit through its session surface. Events are folded into a model-visible sequence, and plugins may supply message projections. Replacements are validated before changing the incremental surface. A tool-result content rewrite cannot silently alter call identity or unrelated metadata. See surface implementation and surface validation cases.

OpenHands applies condensation through a view over events. Its tests preserve tool-batch atomicity: forgetting one observation can remove the corresponding batch from the view, including related observations, while leaving other batches intact. This avoids a request that retains calls without their matching results. See batch atomicity cases.

Pi stores a tree of entries and constructs the active context from the selected branch and compaction boundary. Branching a conversation is distinct from restoring files.

Agent-compositor has an append-only event journal and replayTranscript, plus a replaceable SessionRepository. It also has explicit context restoration and compaction events. The local replay observation below identifies a specific incomplete-call boundary that still needs a policy if stronger recovery is desired.

Compaction and recovery​

Compaction has at least five separate jobs:

  1. Measure the next request, including tool schemas, instructions, media and output reserve.
  2. Prune or offload repeatable large tool output while preserving call/result structure.
  3. Summarize older work and preserve the recent working tail.
  4. Recover from a provider's actual context overflow.
  5. Update usage estimates and prevent a repeated-compaction loop.

OpenCode can prepare a summary in the background before it is needed. Its settings distinguish automatic compaction, reserve buffer and precomputation. The background summary must remain compatible with the history it replaces. OpenCode compaction is a useful implementation reference, rather than a promise of a universal latency improvement.

Gemini truncates history to a safe summarizer budget and has a fallback after a previous failed automatic summarization. Gemini compression tests cover budget-driven truncation and failure behavior.

Goose distinguishes actual provider error kinds from text that resembles a context error. Its tests require no compaction merely because text looks like a context error, stop repeated context-error recovery, and compact tool pairs only at an appropriate boundary. Providers that own their context do not receive an additional Goose compaction operation. See compaction lifecycle cases.

Cline has explicit handling for output truncation, context overflow and provider-executed tools. Its tests prevent compact-and-replay recovery from repeating a turn that already performed provider tool activity. This is a broader recovery issue than local tool execution. See runtime recovery cases.

Agent-compositor already counts schema overhead and preserves a tool-result tail boundary during compaction. Its default implementation uses summary plus recent messages, enforces bounded summarizer inputs and rejects a non-shrinking summary. The current overflow detector uses message patterns. Typed provider failures and an explicit request-projection boundary are candidates for stronger recovery semantics; they are not prerequisites for using the existing compaction service.

Cancellation and late results​

Cancellation needs a terminal outcome for every admitted request. An AbortSignal alone does not settle a pending approval, close an open tool exchange or decide what happens to queued prompts.

The inspected systems make different policy choices:

  • Kimi separates cancellation of the active turn from cancellation of a queued turn; disposal settles all active and queued turns. It preserves partial output with different interruption-reminder behavior for user and programmatic cancellation. Loop cases.
  • DeepSeek Harness exposes a keep-inbox choice and tests races around waking, cancellation, transition to idle and disposal. Its shutdown path drains buffered events. Cancellation cases and shutdown persistence.
  • Grok's cancellation tests distinguish the originating prompt from deeper queued prompts, propagate cancellation to the sampler and wait for prompt settlement. Some paths retain later queued work. Session cancellation cases.
  • Codex completes cancelled dynamic calls and excludes a terminated cell's late response from context. Dynamic-call cases.
  • Crush tests that an idle cancellation cannot poison the next accepted prompt and that entry-time cancellation still publishes run completion. Dispatch cancellation cases.

Agent-compositor intentionally clears ordinary queued work on Stop and pauses automatic follow-ups after interruption. This differs from engines that retain deeper prompts; it is a policy choice. A future adapter needs to map cancellation scope explicitly rather than mapping every external stop command to one boolean.

Cancellation also has two relevant completion points: the user sees that interruption was accepted, and the runtime finishes draining started effects. Source code must be checked for both before claiming that the system is idle.

Persistence and restart​

OpenCode records an execution claim with the start event. Success, failure and deliberate user interruption release it; shutdown interruption preserves it for restart recovery. This separates durable intent from process-local execution ownership. Execution ownership.

A claim is not an exactly-once guarantee for arbitrary external effects. A process can fail after an external operation succeeds and before its result is durably stored. Recovery needs tool-specific reconciliation, an idempotency key or explicit user intervention at that boundary.

Vibe's runtime checkpoint is another distinct mechanism. It validates the internal state needed to resume the machine. It does not by itself establish a filesystem rollback or a transactional external operation.

Cline's checkpoint restoration separately addresses code and conversation. Its tests reject restoration after HEAD moved or the branch diverged, and its transaction captures recovery state before destructive restoration. Restore cases.

Agent-compositor's current ordinary session journal is best effort. Workflow run snapshots have stronger, separate persistence and ownership rules. A future durable session mode should be a selected journal/execution policy, with explicit behavior when a write fails, rather than an undocumented change to all interactive sessions.

Subagents and workflow orchestration​

A child agent needs separate answers for context, authority and lifetime.

A fresh child can receive a small task-specific prompt. A fork can inherit a context snapshot, but copying all parent history may create both cost and instruction-boundary problems. Kimi constrains fork compatibility and tests request parity and interrupted child output. Fork cases.

Permissions and provider capabilities should be inherited only when the route and ownership remain appropriate. Hermes tests that the same-route child can inherit a sanitized capability map, while a provider or base-URL override keeps the default denial. Capability inheritance.

Detached work needs an owner beyond the foreground turn. OpenCode's completion observer survives movement or eviction of its child session. Agent-compositor's trusted background API similarly retains a plugin-instance lifetime and revokes it on unload. A stable session ID is insufficient if completion delivery still holds a disposed plugin instance.

Qwen's workflow scheduler treats pause as an admission/result-delivery gate, and abort as a terminal restriction on further scheduling. Its replay uses a chain of dispatch identities: an unchanged prefix may reuse validated results; the first miss invalidates the suffix. Budget admission is checked again at the dispatch boundary. Orchestrator, scheduler cases and budget ledger case.

Agent-compositor already has both a Python task-result journal and a DAG workflow engine. The former chains code and prompt hashes; the latter has stage dependencies, process leases, attempts, disjoint token reservations and completion generations. Its documented recovery pauses unfinished runs and requires explicit resume. Completed results are not automatically invalidated by later repository edits. Context identity or content-based freshness would be an additional policy; re-running a completed external effect is not a safe general freshness check.

Memory and skill learning​

Project instructions, user notes, current-session summaries, recalled conversations and learned skills should have separate lifecycles.

Hermes gives memory providers turn/session hooks and a pre-compression checkpoint contract. A required checkpoint failure must propagate before destructive compression; best-effort legacy providers keep different semantics. Forked agents suppress ordinary memory writes and recall but may participate in the checkpoint path. Checkpoint contract cases and fork scope cases.

This prevents an auxiliary worker from silently treating its temporary task as a lasting preference for the primary user. It also exposes a capability problem: a harness that controls its own native compaction must either satisfy the selected memory checkpoint contract or refuse that combination.

Agent-compositor's memory plugin provides explicit project/global notes and bounded prompt injection. Its task plan and skills systems address other kinds of retained information. These already count as memory features, but they are not equivalent to a provider lifecycle for automatic extraction, retrieval, provenance and forgetting.

Extensions and execution authority​

A tool plugin, a strategy replacement, a context engine and a complete external harness occupy different extension boundaries.

Pi exposes callbacks, tools, model providers, context processing and UI extensions. DeepSeek Harness composes services, including the loop. OpenClaw registers full harness implementations and tracks their plugin ownership. Its reset tests require sibling cleanup to settle before propagating required cleanup failure. Harness registry and cleanup cases.

Agent-compositor already exposes public turn, batch, context and journal services. Invocation-scoped context objects expire after a turn or hook timeout, and retained plugin APIs are revoked after unload. The customization and hook tests exercise these restrictions. These are host API boundaries; trusted JavaScript still runs in-process and is not an OS isolation boundary.

Policy approval and OS execution confinement must remain separate. A plan-mode prompt alone does not prevent mutation, and a tool permission decision alone does not confine an unrestricted subprocess. Exact command and request identity also matter: Crush grant cases verify that an answer cannot widen the issued grant.

External clients and session managers​

Codex app-server exposes persistent conversations, streamed events, interruption and approval handling through a documented protocol. ACP integrations provide another way to host an agent behind a client. These protocols can supply structured lifecycle information that a terminal manager would otherwise infer from text. Codex app-server documentation.

The manager layer still owns a different problem:

ManagerMechanismBoundary
Agent DeckSession integration, terminal state and transcript inspection; background work classification.A detected terminal state is weaker than an authoritative engine completion event.
Agent of EmpiresPersistent agent sessions, worktrees, lifecycle tracking, container options and structured interfaces.Workspace/process management remains distinct from the selected agent's reasoning loop.
Claude SquadAn instance binds a program to a tmux session, a branch and a worktree.Filesystem separation does not imply coordinated budgets or automatic semantic task merging.

See Agent Deck background classification, Agent of Empires worktree creation and Claude Squad instance ownership.

An adapter contract for Compositor would need stable session identity, lifecycle events, prompt/interrupt operations, approval exchange, capability negotiation, reconnect behavior and usage ownership. Parsing a terminal remains a compatibility path for engines without that interface.

Agent compositor baseline​

The active product engine is packages/core/src/loop.ts. The smaller packages/agent loop is historical reference code and must not be used to infer current product gaps.

AreaExisting implementation at the baselineRemaining distinction from the references
Replaceable executionPublic turn, batch, input/context and journal services; invocation-scoped capabilities.A serialized transition/checkpoint engine is a possible alternative implementation.
Parallel toolsSequential default; a replacement batch strategy can run calls concurrently through the permission gate.ToolSpec has no declared-resource locking contract.
ContextSummary/tail compaction, schema overhead, pressure management and explicit restoration.No separately selected, validated model-visible projection contract comparable to the DSH surface.
Session persistenceReplaceable repository, append-only events, history and replay.Default writes are best effort; incomplete tool exchanges are not repaired by replay.
Independent agentsSeparate cores, transcripts, permissions and budgets; optional worktrees.External engine adapters need lifecycle and capability mappings beyond a pane.
Background workPlugin-owned lifetimes, bounded deduplicated wake queue, shell completion events.Ordinary sessions and OS jobs do not automatically become durable restartable services.
WorkflowsDAG scheduling, leases, token reservations, stage recovery and completion generations; Python result-prefix replay.Saved results do not establish repository freshness or exactly-once side effects.
MemoryExplicit project/global notes, skills, task plans and conversation history.Automatic memory-provider extraction/recall/checkpoint authority is a distinct possible extension.

Relevant local sources and tests:

Reproduced local observations​

Follow-up implementation on 2026-11-11 addresses both observations below. Configured journal failures now stop execution and replay supplies interrupted results for incomplete tool exchanges. The default store also serializes concurrent appends within an instance. The observations retain their historical baseline; see current session behavior and journal contracts for the updated guarantees.

Journal failure can coexist with a completed tool and turn​

The probe injected a SessionJournal whose create method succeeded and whose append method always threw. A ScriptedProvider requested one in-memory tool and then returned a final answer.

Observed result: 19 append attempts failed, the tool executed once, the core emitted turn.complete, state became idle and failure remained absent. No project file or external system was changed by the tool.

This matches the explicit catch in AgentCore.persistDefault: ordinary session storage is best effort. It means that completion in the live session is not evidence that the transcript or tool result was saved. The design choice is valid for an availability-oriented session, but a durable execution mode needs a different persistence/error contract. Persistence implementation.

Replay can send an unmatched tool call to the provider​

The probe replayed a user prompt followed by one tool.call event with no tool.result, representing an interrupted event tail. replayTranscript returned a user message and an assistant message containing the unmatched call. AgentCore.resume then sent that unmatched call to ScriptedProvider with the continuation prompt.

The missing call ID remained unfinished. The probe establishes the incomplete request structure at the provider boundary; it did not contact a remote API or claim a specific vendor rejection.

A recovery policy should account for pending calls before the next request: synthesize an explicit interrupted result, reconcile a durably identified job, or stop for recovery. It should not silently re-run an unknown external effect. Replay implementation, wire conversion.

Candidate design work​

These are study conclusions for discussion, not accepted implementation tasks.

  1. Close replay integrity first. Give every admitted tool call a terminal result or an explicit unresolved state. Check provider-visible history after cancellation, crash and context changes.
  2. Make durability a selected contract. Distinguish best-effort chat storage from execution that requires durable admission and result records. Expose storage failure and recovery status when that mode is selected.
  3. Separate history from request projection. Validate call/result groups, context replacements and provider metadata at the model boundary while retaining the audit history.
  4. Define concurrency metadata. Allow tool implementations to declare execution mode and canonical resource keys; preserve deterministic transcript order and permission checks under custom schedulers.
  5. Specify cancellation scope and settlement. Distinguish prompt, turn, child, workflow, queue and session shutdown. Define which work remains queued and which late results are excluded.
  6. Use typed recovery signals. Bound retry/compaction and distinguish a retryable transport error, a context overflow, truncated output, an authorization failure and an already executed provider action.
  7. Keep memory and background ownership explicit. Tie extraction, recall, completion delivery and retained APIs to the correct session, actor and plugin generation.
  8. Add external harness adapters through capabilities. Keep tiling independent of engine choice; define the structured lifecycle needed to integrate engines through ACP, app-server or an engine-specific protocol.

Reference reading order​

For a new engine implementation, start with Pi's loop and Vibe's transition/checkpoint boundary. For tool scheduling, compare Codex's shared/exclusive gate with OpenHands' resource locks. For durable conversation state, compare OpenCode's execution claims, DSH's surface projection and OpenHands' event views. For orchestration, study Qwen's scheduler and replay alongside Compositor's existing workflow engine. For long-term memory, inspect Hermes' provider and fork-scope contracts. For whole-engine replacement, inspect OpenClaw's registry ownership and cleanup rules.