Harness adapters¶
Official local builds include every adapter below. Install each native CLI separately for local use.
| Harness ID | Providers | Distribution |
|---|---|---|
codex |
openai, openrouter, gateway, bedrock, foundry |
Core |
claude |
anthropic, openrouter, gateway, bedrock, foundry |
Core |
copilot |
github, openai, anthropic, openrouter, gateway, bedrock |
Core |
pi |
anthropic, openai, openrouter, gateway, bedrock, github |
Core |
opencode |
openai, anthropic, openrouter, bedrock, gateway, github, opencode, opencode-go |
Contributed |
hermes |
openai, anthropic, openrouter, gateway, github, bedrock |
Contributed |
Each adapter owns its CLI version range. Local run, checkpoint resume and ACP sessions check
all agent lanes before any node starts, using the captured launch search path and native environment.
Each distinct executable is probed once. Local probes use the earlier of their own 60-second limit
and the controller's remaining preparation budget (ZEROSHOT_PREPARATION_TIMEOUT, 600 seconds by
default), shared with checkpoint restoration and runtime composition. Expiry cancels preparation,
confirms helper process-tree cleanup and refuses admission, even after a successful late response.
Workspace replacement finishes once begun; the CLI's extra stop grace allows cleanup only.
ACP retains an independent 60-second limit per probe. An older, incompatible or unreadable version
is refused with the lane, executable, reported version, supported range and installation step.
| Harness | Minimum | First unsupported release | Basis |
|---|---|---|---|
claude |
2.1.310 | Open | Per-result usage and stopped-subagent fields |
codex |
0.155.0 | Open | Verified adapter fixtures |
copilot |
1.0.70 | Open | Oldest CLI explicitly handled by the adapter |
pi |
1.4.0 | Open | Tested hosted release |
hermes |
0.22.5 | 0.22.6 | Live memory/session/verifier contract; 0.22.6 breaks native agent cleanup |
opencode |
None | None | Version 2 compatibility and its minimum belong to the version 2 port |
An open upper bound accepts newer releases; an exclusive upper bound marks a known incompatibility. Copilot also checks its RPC protocol at session connection. Claude retains its first-turn check using the same range declaration. Contained Claude launches disable the native auto-updater to preserve the image's exact tested pin.
Local builds enable contributed-harnesses by default. Platform and the default target image disable
default features and independently admit only the core registry. Targets advertise enabled pairs
through openengine.runtime-harnesses/v1; installing a CLI doesn't enable its adapter. Contributed
lanes require positive advertisement, while older targets without the extension retain legacy core
submissions.
Core adapters receive product maintenance. Contributors maintain their adapters; zeroshot doesn't guarantee contributed-harness compatibility with native releases. Both groups must implement the same full execution, session and Active Memory contracts. Each runtime names its harness, provider and model explicitly. Model identifiers remain provider-owned strings.
Gateway connections carry GATEWAY_BASE_URL and GATEWAY_API_KEY. Pi, Copilot, OpenCode and Hermes
also require GATEWAY_API: openai-responses, openai-completions or anthropic-messages.
Codex always uses Responses; Claude always uses Messages. Copilot's Bedrock lane uses AWS's
OpenAI-compatible Responses endpoint with AWS_BEARER_TOKEN_BEDROCK and AWS_REGION; an optional
AWS_BEDROCK_BASE_URL preserves a custom endpoint. Models must support the chosen native API.
Codex and Claude foundry lanes share one Microsoft Foundry connection; see
Microsoft Foundry.
Local native login works for Codex/OpenAI, Claude/Anthropic, Copilot/GitHub and its OpenAI,
Anthropic and OpenRouter BYOK lanes, and Pi/Anthropic, OpenAI and GitHub. OpenCode and Hermes retain
native authentication for every supported provider except gateway, including the native AWS
credential chain for Bedrock. OpenCode's opencode (Zen) and opencode-go (Go) lanes reuse the
native OpenCode account login; a declared OPENCODE_API_KEY serves both. Other lanes require
declared connections. GitHub connections use
COPILOT_GITHUB_TOKEN; each harness owns its native exchange and refresh behavior. Declared
credentials use private runtime state and preserve saved logins.
Local OpenCode and Hermes runs preserve native configuration discovery with declared credentials.
Their declared authentication takes precedence over ambient authentication for the selected lane,
while native settings and plugins continue to apply. OpenCode keeps its original HOME/XDG paths and native
permission policy. Its declared authentication uses a private plugin, so OPENCODE_PURE=true
conflicts with that setup. Native plugins and custom transport code run with the native CLI's authority.
Local OpenCode adds no --auto flag and skips configuration inspection
because that inspection can start background dependency work.
Hermes uses the interpreter from its installed canonical executable and native configuration factories without attaching to its shared gateway. Local profiles, plugins, MCP and permissions remain native. Declared connections override native dotenv values. Remote backends retain native containment limits. Missing native acknowledgement makes cleanup unconfirmed and fails execution; unreported child usage makes totals incomplete.
Execution environment¶
Every per-node harness child process receives these public, nonsecret execution labels, including agent verifiers and host-owned auxiliary agents. Local and contained launches use the same contract.
| Variable | Value |
|---|---|
ZEROSHOT_RUN_ID |
Owning run's existing ID. |
ZEROSHOT_NODE_NAME |
Authored node name, or the auxiliary agent's host-owned name. |
ZEROSHOT_NODE_KIND |
Graph kind: step or verifier. |
ZEROSHOT_NODE_INSTANCE_ID |
Existing run-scoped node instance; mapped items have distinct identities, while retries and loop revisits retain their instance. |
ZEROSHOT_EXECUTION_REF |
Opaque public execution selector shared with logs, attach and diagnostics. |
ZEROSHOT_NODE_ATTEMPT |
One-based reducer attempt within the current node visit. |
ZEROSHOT_NODE_ITERATION |
One-based iteration of the innermost enclosing authored loop; 0 outside loops. |
For outer iteration 3 and inner iteration 2, a node inside the inner loop sees iteration 2.
A node in the outer body after the inner loop sees 3. The inner count restarts at 1 on the
next outer visit; a node after all loops sees 0. Map indices do not affect iteration values.
Reducer retries keep the iteration and advance the attempt. Fresh loop visits follow the reducer's
attempt reset. Harness continuations, provider retries, structured-output corrections and configuration
inspection launches retain the dispatch metadata; spawning a process never advances either number.
Auxiliary agents use their own run, node and execution identities, iteration 0 outside authored
loops, and attempt 1 unless the host request explicitly represents a retry of that visit.
zeroshot applies these labels after environment merges, replacing stale incoming values, with case-insensitive names on Windows. It never changes the controller's process environment or puts labels in credential connections. Descendant tools and hooks may inherit them subject to native harness filtering; remote tool backends retain their own environment policies. Descendants can keep or change inherited labels, so they are not secrets or evidence of authorization. Native control, decision and delivery nodes do not acquire a fabricated harness process.
Contribute an adapter¶
Add an implementation under zeroshot/src/harnesses/adapters/contributed/ and register it in that
directory's register function. Core implementations live beside it under adapters/core/;
existing public native_v2_codex, native_v2_claude, native_v2_copilot and native_v2_pi module
paths remain available to embedders.
A registration supplies a descriptor, an optional HarnessCliVersion declaration (range, version
arguments/parser, native environment selector and upgrade step), provider-access declarations, local path normalization, pure
reserved-control validation for harnessConfig, and a factory. Keep descriptors pure: no credential reads, filesystem inspection, process launches or
provider requests. The registry validates bounded harness/provider IDs and compatible pairs.
Factories receive HarnessBuildContext and return HarnessAdapter with NodeDriver and
SessionFactory implementations.
Run closure drains active invocations before calling the optional NodeDriver::close_run hook.
Use it to release run-owned bookkeeping while preserving native sessions owned by an ACP session.
The hook may be called repeatedly.
Adapters own native protocols, authentication translation and permission handling, including their
environment allowlists and home/path expansion. Use shared process and session helpers for private
execution files, bounded streaming, cancellation and cleanup. Apply the shared
provider_process::apply_execution_environment helper after environment merges for every agent launch. Support workers and verifiers with
authoritative response validation, bounded corrections, reusable sessions, live output and usage
that reports uncertainty when totals are incomplete.
Install the native Active Memory hook, plugin or bridge in the adapter. Shared memory owns recall
budgets, receipts and maintenance; missing acknowledgement means unknown delivery evidence. Declare
how the harness takes a steer at a tool call (SteerRoute): as a user message through its own
message channel where it has one, confirmed with ActiveMemoryHooks::steer_shown when the harness
reports the message in the conversation, and inside hook context only otherwise. Place neither a
steer nor a lesson inside a tool result, and say whether the harness keeps tool-call context in its
session (HookQuery::context_kept).
Run focused fixtures and shared registry/session tests. The ignored contract in
harnesses/live_tests.rs requires a disposable test repository and explicit ZEROSHOT_LIVE_HARNESS,
ZEROSHOT_LIVE_PROVIDER, ZEROSHOT_LIVE_MODEL and ZEROSHOT_LIVE_WORKSPACE values. Set
ZEROSHOT_LIVE_CLI_BINARY to a separately built CLI's absolute path for memory callbacks. Optional
ZEROSHOT_LIVE_CONNECTION_FIELDS lists additional declared field names, separated by commas.
Test native bridges too, and check the core-only library:
Native configuration ownership¶
All registered adapters implement per-node native configuration. Keep carrier parsing shared and reserved controls adapter-local. Bind configuration at the invocation or session boundary, never on the lane-wide adapter. Native APIs use object options; CLI arguments remain argument tokens. Preserve the same configuration on corrections, retries and session resumes. Leave unknown native names and values to native initialization. Do not add an option allowlist, portable permission policy, native validation prompt, or generalized inspection subprocess.
Owned authentication, transport, response schemas, identity, memory hooks and containment cannot be replaced through overrides. Existing permission inspection only decides whether to add an automatic local bypass. Native initialization failure must preserve its bounded redacted cause and node/harness identity, settle cleanup, and skip automatic correction/fallback/retry. Focused process/session tests must cover forwarding, isolation, reuse and rejection for every registered adapter.
Conversations in checkpoints¶
Adapters select only the files belonging to a conversation identifier and name their destination
under the successor's provider session storage. They never split, redact or pack transcripts, and
change one only where the provider records its working directory inside it.
Capture includes the identifier and Codex's cumulative usage baseline as one complete unit, bounded
at 1 GiB. Shared checkpoint code copies raw files beside workspace into the lineage's deduplicating
repository and rejects absolute, escaping or symlink names. Checkpoint deletion removes this data.
Credentials and configuration are excluded. Missing or unsupported material starts a new conversation
with a node-naming system log; a failed continued turn follows the existing attempt policy and its
retry starts new. Capture never fails a checkpoint.
Codex requires a cumulative usage report covering the latest turn; absent usage, including an older
baseline retained for in-run accounting, makes that checkpoint's conversation unavailable. Contained
restores assign provider ownership to restored files and their ancestors through the private session
home, so nested storage stays accessible without changing any directory outside that home.
Codex captures its named rollout under sessions; Claude captures the named transcript and its
session directory under the cwd-specific project, relocating them for the successor workspace. Pi
captures the named session JSONL. Pi finds a session ID only among the sessions of its working
directory, which the file's first line names, so restore writes that line again with the successor
workspace and copies every later line unchanged; a first line that is no such header starts a new
conversation. Copilot captures the named session-state directory. Hermes
captures the private node's SQLite database and sidecars. Contained OpenCode captures its exclusively
owned database; local OpenCode's shared database is not captured because it contains other
conversations. Local OpenCode and older OpenCode layouts without the private SQLite database
therefore take the logged fallback.
Hosts implementing workspace storage receive ConversationFiles through the optional
RunCheckpointStore::retain_conversations method. Store the files outside the exported workspace
and return the selected files through restored_conversations, including continuations with a
retained workspace. Existing hosts compile without these methods and use the logged fallback.
The ignored checkpoint_conversation_live_contract in harnesses/live_tests.rs verifies recall
after capture and restoration with a new workspace and empty provider storage. OpenCode uses its
private home layout; its shared local storage is covered by the fallback regression. It uses the
same ZEROSHOT_LIVE_* settings as the shared live contract. The local CLI's ignored
live_suspended_conversation checks recall through the built binary. Before release, run the adapter
contract with each supported CLI/provider lane; the owner also checks suspended hosted runs after
installing conversation storage support on that host.
Authored node instructions accept up to 262,144 UTF-8 bytes. Steering uses the same bound. The
native tool-call carrier on every agent conversation, whether Active Memory is on or off, picks a
steer up at a tool call. From there it travels as a user message through Claude Code's stream-json
stdin, Copilot's session.send in immediate mode, Pi's steering queue or a stored OpenCode
session message, and inside hook context on Codex and Hermes. The host supplies the shared carrier
frame bound to each adapter; adapters retain installation and acknowledgement ownership.