AIP-45: HARNESS (harness/v1): interactive harness manifest
A markdown + frontmatter format for declaring an interactive harness — a long-running, bidirectional, agent-as-process binary like Hermes Agent, Claude Code, OpenCode, Goose, or Gemini CLI — and how to install, spawn, and converse with it. Layers over AIP-29 (CLI.md) for install/version/auth blocks and AIP-44 (ACP.md) for the session/wire model when protocol=acp; falls back to MCP or proprietary protocols via a discriminator.
| Field | Value |
|---|---|
| AIP | 45 |
| Title | HARNESS (harness/v1): interactive harness manifest |
| Status | Review |
| Type | Schema |
| Domain | cli.sh |
| Requires | AIP-17 (RUNNER), AIP-19 (SECRETS), AIP-29 (CLI), AIP-36 (SANDBOX), AIP-44 (ACP) |
| Reference Impl | @agentproto/harness |
| Resources | ./resources/aip-45 — ADAPTER.md, HARNESS.schema.json, STREAM-EVENTS.schema.json, EXAMPLES.md |
Abstract
HARNESS.md packages an interactive harness — a binary that
hosts an agent loop (Hermes, Claude Code, OpenCode, Goose, Gemini CLI)
and converses bidirectionally with a client over stdio or a similar
duplex channel. Each manifest declares how to install, version-check,
sandbox, authenticate, and talk to the binary, with a protocol
discriminator (acp | mcp | proprietary | print) selecting the
wire shape.
AIP-45 is a sibling, not a rival, of AIP-29. AIP-29
remains the home for tool CLIs — gh, stripe, kubectl,
ffmpeg — whose semantics are one-shot cmd → output. AIP-45 covers
harnesses whose semantics are persistent sessions with streamed
turn events. The two share the install / version / auth / sandbox
substrate via JSON Schema $ref, so a future "tool CLI that has both
modes" can carry both manifests without duplication.
Motivation
Agent runtimes shipped as CLIs are a fast-growing category:
- Hermes Agent (Nous Research, ACP server)
- Claude Code (Anthropic, ACP via
@agentclientprotocol/claude-agent-acp) - OpenCode (sst, native ACP support)
- Goose (Block, MCP-over-stdio)
- Gemini CLI (Google, proprietary REPL)
- Cursor background agents (ACP)
Today every product wires each one bespoke: invoke it as a subprocess, parse its prompt / output / streaming events, manage its lifecycle, hand it secrets, route tool calls. The cost compounds across products — Guilde, Katchy, Simone, dev tooling — and across platforms (macOS, Linux, headless servers, Modal/Daytona sandboxes).
AIP-45 factors the integration shape into a single declarative file
plus a single TypeScript runner (@agentproto/harness), the
same way AIP-29 factors tool-CLI integration. The discriminator means
new harnesses join the catalog by writing a manifest, not by writing
runner code.
The companion observation: harnesses converge on ACP. Hermes,
Claude Code, OpenCode, Cursor all speak it. Treating ACP as the
default while leaving room for MCP (Goose), proprietary REPLs
(Gemini CLI today), and headless one-shot CLIs driven print-style
yields one runner with one wire-stable arm and three fallback arms.
Specification
This section uses RFC 2119 keywords (MUST / SHOULD / MAY).
Conformance
A manifest is AIP-45-conformant iff:
- Its frontmatter validates against
./resources/aip-45/draft/HARNESS.schema.json. - Its
install,version_check,authblocks satisfy AIP-29's schemas (referenced via$ref). - When
protocol: "acp", the binary's ACP server satisfies the upstream ACP specification at the AIP-44acp_revdeclared by the boundACP.md. - When
protocol: "mcp", the binary speaks MCP-over-stdio permodelcontextprotocol.io. - When
protocol: "proprietary", the manifest's harness package (harnessfield) implements theAgentCliClientinterface from@agentproto/harness. - When
modesis present, every entry has a uniqueidmatching^[a-z0-9][a-z0-9\-]*$; mode patches reference no symbols beyondbin_args_appendandenv. - When
optionsis present, every entry has a uniqueidmatching^[a-z0-9][a-z0-9_]*$;type: enumentries declare anenumarray;min/maxonly appear ontype: integer. - When
continuationis present,defaultis insupported; ifdefault == "native-resume"thencapabilities.resumable: trueMUST also be declared. - When
protocol: "print", the manifest MAY omit theprintblock (Claude Code defaults apply); whenprint.event_schemais declared, it MUST be one of the closed enum values listed in § Theprintarm below.
Frontmatter
The full schema lives in
./resources/aip-45/draft/HARNESS.schema.json.
Top-level fields (informative summary):
| Field | Required | Description |
|---|---|---|
name | Yes | Kebab id matching parent dir |
id | Yes | Stable runtime id |
description | Yes | One-paragraph purpose |
version | Yes | Semver of this manifest |
bin | Yes | Path to the binary |
bin_args | No | Default argv (e.g. ["acp"] for hermes acp) |
env | No | Static, always-on environment variables (string → string) merged into the spawn env before any mode/option env patch, so those can override. The always-on counterpart to modes[].env / options[].env; the main user is a generic ACP agent whose whole config surface is bin + args + env. |
install | Yes | Array of install methods (AIP-29 $ref) |
version_check | Yes | Version detection (AIP-29 $ref) |
setup | No | Post-install configuration steps (AIP-29 $ref) — daemons, bind-time prompts, OAuth, external pickers |
auth | No | Auth surface (AIP-29 $ref), plus an optional methods map listing the credential methods the harness can present per route. See § Presentable auth methods per route. |
sandbox | Yes | Sandbox profile (AIP-36 $ref) |
confinedReadPaths | No | READ-only paths an OS-confined spawn needs to boot (e.g. the CLI's own global config files under $HOME, which the sandbox denies). See § Sandbox integration. |
protocol | Yes | acp | mcp | proprietary | print |
acp | When protocol=acp | Ref to AIP-44 ACP.md describing the wire profile |
mcp | When protocol=mcp | Inline MCP server config |
harness | When protocol=proprietary | NPM package implementing AgentCliClient. Named adapter in earlier drafts; adapter is removed (AIP-70 §4). |
print | When protocol=print | Inline print surface config (optional — Claude Code defaults when omitted) |
session | No | Session settings: mode, idle_timeout_ms, max_turns |
models | No | Model routing: default, allowed, env-mapped. Each allowed entry is a bare id string (provider unstated — the projector MUST NOT guess one) or { id, provider?, mode? }: id is unchanged on the wire, provider is the ProviderPreset id (or direct provider) that serves and bills the model, mode is this harness's mode id that routes to provider. |
gateways | No | Gateway endpoints (Anthropic/OpenAI-compatible backends) this harness can be pointed at. Formerly presets, which remains a legacy alias. See § Gateways. |
capabilities | No | Declarative capability flags (mirror of ACP capability map for non-ACP runtimes) |
modes | No | Mutually-exclusive operation modes (e.g. claude-code's plan / accept-edits / bypass-permissions). One active per turn. |
options | No | Independent typed knobs (model, max-turns, auto, ...). Multiple may be active per turn. |
continuation | No | How prior turns reach the CLI. Declares default + supported strategies. |
runner | No | AIP-17 RUNNER.md ref or inline runner block |
protocol discriminator
Four values, with cross-field requirements:
# protocol: "acp" → MUST declare `acp` referencing an AIP-44 ACP.md
protocol: acp
acp: ./hermes-acp.ACP.md
# protocol: "mcp" → MUST declare `mcp` with server config
protocol: mcp
mcp:
command: goose
args: [serve]
transport: stdio
# protocol: "proprietary" → MUST declare `harness` (NPM package)
protocol: proprietary
harness: "@agentproto/harness-gemini"
# protocol: "print" → one fresh subprocess per turn (headless one-shot).
# The `print` block is OPTIONAL — omitted, Claude Code defaults apply.
protocol: print
print:
prompt_flag: "--prompt" # absent ⇒ prompt is the last positional arg
output_format: ["--output", "jsonl"]
pre_prompt: ["--no-interactive"]
resume: { flag: "--resume", kind: "value" }
event_schema: mastra-jsonlRuntimes that don't recognise the declared protocol MUST refuse to
load the manifest; this is a hard error, not a warning.
The print arm
Amendment — codifies shipped behaviour.
protocol: "print"is a fourth discriminator arm. It is validated by the closed enumz.enum(["acp", "mcp", "proprietary", "print"])inpackages/harness/src/schema.tsand driven bypackages/harness/src/protocol/print-arm.tsin the reference implementation.
print serves headless one-shot CLIs: instead of a long-lived
connection, the driver spawns one fresh subprocess per turn and
maps the CLI's stdout event stream onto the normalised taxonomy. The
driver-side session object persists across turns; only the per-turn
child is fresh. Because no child outlives a turn, the arm is immune
to the stale-proxy race that long-lived connections are exposed to.
The print manifest block declares the CLI's one-shot surface:
| Field | Description |
|---|---|
prompt_flag | How the prompt text is passed. Absent (or "positional") — appended as the last positional arg. A string — passed as --<prompt_flag> <text> before any trailing positional args. |
output_format | Output-format flags appended before the prompt. Default ["--output-format", "stream-json"] (Claude Code); e.g. Mastra Code uses ["--output", "jsonl"]. |
pre_prompt | Extra flags inserted between output_format and the prompt (e.g. Claude Code's ["--no-interactive"]). |
resume | Resume/continue flag for reattaching to a prior session: flag plus kind — "value" passes --flag <sessionId>, "boolean" passes the bare flag. |
event_schema | Closed enum selecting the event mapper: claude-stream-json (default) | mastra-jsonl | antigravity-stream-json | jcode-ndjson. |
Session tracking and resume. The session's sessionId starts
empty (or pre-seeded from a prior session id) and is captured after
the first successful turn from the wire event that carries the
session / thread identifier (Claude: result.session_id; Mastra:
result.threadId). Subsequent turns pass the declared resume flag
so the CLI rehydrates the conversation. Because the session object —
not the child process — carries the id, resume works without any
long-lived connection.
Session model
session:
mode: ephemeral | persistent | resumable # default: ephemeral
idle_timeout_ms: integer # default: 600000 (10 min)
max_turns: integer # default: unlimited
context_carryover: boolean # default: true within a sessionephemeral sessions are torn down on disconnect. persistent sessions
survive client reconnect within idle_timeout_ms. resumable sessions
are durable across runs (requires the binary to support session/load
or equivalent — clients MUST refuse to declare resumable against a
binary lacking the capability).
Stream event taxonomy
When the runtime relays the binary's output to a host, events conform to a closed taxonomy regardless of underlying protocol:
| Event | Description |
|---|---|
text-delta | Streaming agent message text chunk |
tool-call | Agent invoking a tool — args + tool id |
tool-result | Tool's response delivered back to the agent |
thought | Agent's internal reasoning (when capability declared) |
agent-prompt | Agent asking the user / client to choose: a tool permission, a question, or a plan approval |
mode-changed | The session's current mode changed (when capabilities.mode_events declared) |
turn-end | Agent has finished the current turn |
error | Out-of-band error during the turn |
The runner translates protocol-specific events to this taxonomy exactly once at the protocol arm boundary; downstream consumers never see protocol-specific shapes.
The reference implementation carries the event name in a kind field
({ kind: "text-delta", sessionId, text }); the subsections below use
that field name. Field-level shapes for agent-prompt and
mode-changed are published as JSON Schema in
STREAM-EVENTS.schema.json.
Session modes and mode-changed (added 2026-10-28)
A harness MAY expose session modes: a runtime registry of modes
the caller can switch between mid-session (an ACP agent's
SessionModeState.availableModes, or the equivalent a proprietary arm
reports), with one current mode. Session modes are not the manifest's
static modes[] (see § Modes), which are composed at spawn. The
caller switches a session mode with setSessionMode(modeId) (ACP
session/set_mode). A harness can also switch by itself, for example
when an approved plan moves the session from a planning mode to an
executing mode.
A mode-changed event reports that the current session mode is now a
different one:
{
kind: "mode-changed"
sessionId: string
modeId: string // the current mode after the change
previousModeId: string // the mode before the change
cause: "caller" | "agent"
reason?: string // human-readable, e.g. "plan approved"
_meta?: Record<string, unknown>
}Rules:
- A harness that exposes session modes and declares
capabilities.mode_events: trueMUST emitmode-changedwithcause: "agent"whenever the current mode changes for any reason other than the caller's ownsetSessionModecall. This includes a switch that follows the caller's answer to aplan-approvalrequest (see below): the caller approved a plan, but the harness picked the target mode and made the switch. - The harness SHOULD also emit
mode-changedwithcause: "caller"once a caller'ssetSessionModecall has been applied. A refused or no-op call emits nothing. - A harness MUST NOT emit
mode-changedwhenmodeIdequalspreviousModeId. The mode a session starts in is reported by the session's initial state (ACPSessionModeState.currentModeId), not by an event. modeIdMUST be one of the session's available modes.- The event is emitted after the switch took effect and before any other event produced under the new mode. When no turn is in flight, it is delivered on the session's out-of-turn event channel, like any other event the agent emits between turns.
- When
protocol: "acp", the arm translates an ACPcurrent_mode_updatesession update intomode-changed. It fillspreviousModeIdfrom the mode it tracked before the update, and setscause: "caller"only when the update confirms asession/set_modethe arm itself sent and has not seen applied yet; otherwisecause: "agent".
A caller that tracks the current mode SHOULD update it from
mode-changed rather than from the agent's prose or thought text.
agent-prompt requests (added 2026-10-28)
An agent-prompt event asks the caller to choose among options. It
mirrors ACP session/request_permission:
{
kind: "agent-prompt"
sessionId: string
toolCallId: string // request id, passed back to respondPermission
options: Array<{
optionId: string
name: string
kind: "allow_once" | "allow_always" | "reject_once" | "reject_always"
}>
text?: string // human-readable question line
toolName?: string
rawInput?: unknown
request?: "tool-permission" | "question" | "plan-approval" // default "tool-permission"
question?: QuestionRequest // when request is "question"
planApproval?: PlanApprovalRequest // when request is "plan-approval"
_meta?: Record<string, unknown> // vendor extras
}The caller answers with respondPermission(toolCallId, resolution),
where resolution is { optionId, feedback? } (one of the offered
options, plus optional free text), { answers } (only for a question
with fields, see Multi-field questions)
or { cancelled: true }. Outside answers, feedback is the only place
free text travels.
request names what the agent is asking for. It is OPTIONAL and an
absent value reads as tool-permission, so every existing event stays
valid.
request | Meaning | Typed payload |
|---|---|---|
tool-permission | May the agent run this tool call? (toolName, rawInput) | none |
question | The agent asks the user a question | question |
plan-approval | The agent submits a plan and waits for approval before acting on it | planApproval |
type QuestionRequest = {
prompt: string // the question text
choices: Array<{
optionId: string // MUST appear in options
label: string
description?: string
}>
allowFreeText: boolean // a typed answer is accepted
freeTextOptionId?: string // REQUIRED when allowFreeText; MUST appear in options
fields?: QuestionField[] // multi-field form (2026-11-03), see below
}
type PlanApprovalRequest = {
plan?: string // the plan text
planRef?: string // or a reference to it (path or URI)
targetModeId?: string // the session mode entered if approved
approveOptionId: string // MUST appear in options, kind allow_once
rejectOptionId: string // MUST appear in options, kind reject_once
}Rules:
- A harness that sets
requesttoquestionorplan-approvalMUST carry the matching typed payload, and MUST declarecapabilities.typed_prompts: true. - Every option a typed payload refers to MUST also be in
options, with a human-readablename. Every typed request MUST offer at least one option of kindreject_onceorreject_always, so a caller can always refuse. - Question. The caller answers a choice by selecting its
optionId. WhenallowFreeTextis true, the caller answers with free text by selectingfreeTextOptionIdand putting the text infeedback. A free-text selection withoutfeedbackis an empty answer; the harness MUST NOT invent one. - Plan approval. A
plan-approvalrequest MUST carryplan,planRef, or both. SelectingapproveOptionIdapproves the plan. SelectingrejectOptionIdrejects it, andfeedback, when present, is the reason handed back to the agent. WhentargetModeIdis set and the plan is approved, the harness switches to that mode and emitsmode-changedwithcause: "agent"(rule 1 of the previous subsection) when it declaresmode_events. A rejected plan leaves the mode unchanged. { cancelled: true }declines any request kind._metastays the place for vendor extras. A harness SHOULD NOT carry in_metawhatrequest,questionorplanApprovalalready express.
A caller that ignores request still works: it sees a permission
prompt with named options, picks one by optionId, and may attach
feedback. For a question it picks a choice, or the free-text option
with its text; for a plan it picks approve or reject. Only the
rendering is generic.
Multi-field questions (2026-11-03)
A harness question is often more than one single-choice line: Claude
Code's AskUserQuestion asks up to four questions at once, each single
or multiple choice, each with an "Other" box. QuestionRequest carries
such a form in its OPTIONAL fields array.
type QuestionFieldInput = "single" | "multi" | "text" | "boolean" | "number"
type QuestionField = {
id: string // stable key, unique in the prompt
input: QuestionFieldInput
header?: string // short chip label
prompt: string // the question text for this field
choices?: Array<{ // REQUIRED, non-empty, for single / multi
value: string // what goes back to the harness
label: string
description?: string
preview?: string // e.g. a code snippet shown on focus
}>
allowFreeText?: boolean // single / multi: a typed answer is accepted too
required?: boolean
recommended?: string // a choices[].value, see rule 4
}
// The answer, keyed by field id. An absent field is skipped.
type QuestionAnswers = Record<string, {
selected?: string[] // single: 0 or 1 value, multi: 0..n values
text?: string // free text, a text input, or String(number)
value?: boolean | number // boolean / number inputs
}>Rules:
- When
fieldsis present it is the source of truth.promptis then the overall message, andchoices,allowFreeTextandfreeTextOptionIdare a projection for callers that predatefields: filled from the only field when the form is exactly onesinglefield (one option per choice, plus the free-text option when that field allows free text, every one of them inoptions), andchoices: [],allowFreeText: falseotherwise. - A prompt with
fieldsMUST offer a submit option of kindallow_onceand a skip option of kindreject_once, so a caller that only understandsoptionscan always unblock the harness. The projection of rule 1 MAY add more. - The caller submits the form with
{ answers }.selectedholdschoices[].values (at most one forsingle),textthe typed answer (only whereallowFreeTextis true, or for atext/numberfield),valueabooleanornumberanswer. A harness MUST reject answers naming an unknown field or value, and MUST reject{ answers }on a prompt withoutfields. Selecting the skip option declines the whole form;{ cancelled: true }cancels it. recommendedis set by the party relaying the prompt (for example the daemon), from what it knows. A client renders it as a marker and MUST NOT invent one.
Mapping an ACP form elicitation (informative). ACP's elicitation/create
with mode: "form" carries a JSON Schema; claude-agent-acp and
codex-acp use it for AskUserQuestion. A client that advertises
clientCapabilities.elicitation.form maps each schema property to a
field:
| Property | Field |
|---|---|
type: "string" with oneOf (or enum) | single; oneOf[].const → value, title → label |
type: "array" with items.anyOf (or items.enum) | multi |
type: "string" whose _meta._askUserQuestionCustomAnswer.questionId names a choice field | not a field: sets allowFreeText on that field; its text goes back under this property |
other type: "string" | text |
type: "boolean" | boolean |
type: "number" / "integer" | number |
prompt is the property description; a lone field without one takes
the elicitation message (claude-agent-acp puts a single question
there), else its title. header is the title when it is not the
prompt. required comes from the schema's required list, preview
from the option's _meta["_claude/askUserQuestionOption"].preview.
{ answers } is sent back as an accept whose content holds a string
per single field, a string array per multi field and the typed text
under the companion property; the skip option becomes decline and a
cancel becomes cancel. A client SHOULD advertise
elicitation.form only when someone can answer the prompt: without it
the harness keeps its own fallback. mode: "url" elicitations are out
of scope here.
Lifecycle
Discover (manifest in registry)
↓
Install (run install method matching host OS/arch)
↓
Version-check (regex against `bin_args + version_check.cmd`)
↓
Spawn subprocess (apply sandbox + auth env)
↓
Handshake (per protocol arm)
↓
Open session (session/new or equivalent)
↓
LOOP: send turn → consume stream events → emit AIP-7 audit
↓
Close session (session/close or equivalent)
↓
Tear down subprocess (SIGTERM 5s → SIGKILL escalation)Capabilities
capabilities is a manifest-declared mirror of behaviours (separate
from the runtime-negotiated ACP capabilities). It tells the host what
to expect before boot:
capabilities:
streaming: boolean # streams text-delta events
tool_calls: boolean # emits tool-call events
sub_agents: boolean # may delegate to other agents
file_io: boolean # may read/write workspace files
multimodal: boolean # accepts non-text input
resumable: boolean # supports session/load semantics
bidirectional: boolean # may emit agent-prompt
mode_events: boolean # emits mode-changed (session modes)
typed_prompts: boolean # types agent-prompt requests (question, plan-approval)
hooks: # optional AIP-71 native hook declaration
- event: tool-call # portable AIP-37 event
native_event: PreToolUse
path: admission
can_block: true
handlers: [command, mcp]
memory: # optional AIP-72 memory projection declaration
inject: native-dir # native-dir | system-prompt | none
capture: native-dir-diff # native-dir-diff | nonecapabilities.hooks is an open list of native hook declarations defined by
AIP-71. It advertises what the harness can project natively
before boot. It does not enable a hook, install user code, or grant a
permission by itself.
Each entry MUST satisfy the four declaration rules of AIP-71 section 3:
no whitespace in event or native_event, a non-empty handlers,
can_block: false on a lifecycle entry, and no two entries sharing an
(event, native_event) pair. HARNESS.schema.json encodes the first
three; a reader enforces the pair rule.
capabilities.memory declares how the harness can receive memory items
and give its own memory writes back, as defined by the
AIP-72 projection (section 9):
| Field | Values | Meaning |
|---|---|---|
inject | native-dir | system-prompt | none | How a digest of in-force items reaches a session at spawn: written into the harness's native memory location, appended to the system prompt, or not at all. |
capture | native-dir-diff | none | Whether the native memory location can be diffed after the session so its changes become store proposals. |
An absent memory reads as { inject: none, capture: none }. Like
hooks, it is metadata: the host resolves the effective projection
(native first, system prompt as the fallback) and does not enable one
because of the declaration alone.
capabilities.mode_events and capabilities.typed_prompts let a caller
feature-detect the two contracts of § Stream event taxonomy before boot:
| Field | Meaning when true |
|---|---|
mode_events | The harness exposes session modes and emits mode-changed for every change of the current mode that the caller did not make itself (and, as a SHOULD, for the caller's own setSessionMode too). |
typed_prompts | The harness sets request on agent-prompt and carries the question or planApproval payload for those kinds. |
An absent flag reads as false. A caller MUST NOT assume either contract
from a harness that does not declare it: without mode_events it reads
the current mode from the session's state, and without typed_prompts it
treats every agent-prompt as tool-permission, whatever _meta says.
When protocol: "acp", protocol capabilities MUST be a subset of the ACP
capabilities the bound AIP-44 manifest declares; the runner enforces this at
load time. hooks (AIP-71), memory (AIP-72), mode_events and
typed_prompts are harness-extension capabilities, not ACP wire
capabilities, and are therefore excluded from that subset check.
Modes
modes is OPTIONAL. When present, it declares the set of mutually-
exclusive operation profiles the CLI exposes. The host picks at
most one mode per turn via OPERATOR.runtime.config.mode (AIP-9).
Each mode may patch the spawn bin_args and env; the runner applies
mode patches AFTER the manifest's default bin_args and BEFORE option
patches.
modes:
- id: default
description: Standard interactive session
- id: plan
description: Plan-only mode — no edits, no commands
bin_args_append: ["--permission-mode", "plan"]
- id: accept-edits
bin_args_append: ["--permission-mode", "acceptEdits"]
- id: bypass-permissions
bin_args_append: ["--permission-mode", "bypassPermissions"]Mode ids MUST be unique. The default mode (when the operator omits
config.mode) is "no patch applied" — the manifest's bin_args run
verbatim. Hosts MUST reject an OPERATOR.runtime.config.mode value
that is not in the manifest's modes[].id list.
Besides bin_args_append and env, a mode MAY declare:
| Field | Type | Description |
|---|---|---|
bin_args_prepend | string[] | Extra argv prepended before the manifest's bin_args when the mode is active. |
env_unset | string[] | Env keys to DELETE from the spawn env when the mode is active. Applied at the runtime's env-merge point, after ambient process.env and mode/option env are combined, so a mode can scrub a credential that must never reach a non-native endpoint (e.g. a gateway mode scrubbing ANTHROPIC_API_KEY). Deletion is the only safe semantics for scrubbing; env cannot express it. |
kind | "context" | Which session-config axis the mode expresses. Narrowed to context (what enters context) — the only concern with no ACP-protocol home. Route is derived from the model catalog; posture comes from the harness's own ACP mode registry. Omitted ⇒ inferred from the id. |
status | active | noop | planned | Honest support status surfaced to clients. active does what its description claims; noop is declared and accepted but measured to have no effect; planned is declared but not wired yet. Absent ⇒ active. |
status_note | string | Human-readable reason backing status (e.g. what was measured). |
Options
options is OPTIONAL. When present, it declares typed knobs the CLI
accepts. Unlike modes, options are independent — multiple may be
active in the same turn. Each option declares a type (boolean |
integer | string | enum) and how its value patches bin_args /
env.
options:
- id: model
type: enum
enum: [claude-sonnet-4-6, claude-opus-4-7, claude-haiku-4-5]
bin_args_template: ["--model", "{value}"]
- id: max_turns
type: integer
min: 1
max: 200
bin_args_template: ["--max-turns", "{value}"]
- id: auto
type: boolean
bin_args_append_when_true: ["--auto"]Patch semantics:
bin_args_template— appended when the value is non-default. The literal token{value}is replaced with the option's value (stringified). Use for value-bearing flags.bin_args_append_when_true— applies only totype: boolean. Value must betrue. Use for bare flags.bin_args_prepend— argv template prepended before the manifest'sbin_argswhen the value is non-default;{value}is replaced as inbin_args_template.env— merged into the spawn env. Values may contain{value}.env_unset— env keys to DELETE from the spawn env when the value is non-default. Symmetric withmodes[].env_unsetand applied at the same env-merge point, so a value-bearing option (e.g. abase_urlpointing at a third-party Anthropic-compatible gateway) can scrub the ambient credential it displaces without also selecting a preset mode.
Hosts MUST validate OPERATOR.runtime.config.options.<id> against the
matching option's type / enum / bounds before spawn. Unknown ids are a
hard load-time error.
Gateways (added 2026-10-23)
Draft AIP-45 amendment (2026-10-23). Normative identifiers (field names, literals, tool names) are English and final.
gateways is OPTIONAL. Each entry declares a gateway endpoint, a backend
an Anthropic/OpenAI-compatible client can front, so the gateway catalog
surfaces harness-contributed gateways alongside the built-in registry.
The field was named presets before this amendment, because "preset" now
means a saved session configuration (AIP-70 GLOSSARY,
agentproto/agentproto#91).
presets remains accepted as a legacy alias with the same fields. A
manifest MUST NOT carry both gateways and presets.
The catalog dedupes by id; a harness-declared id that collides with
a built-in is ignored in favour of the built-in.
| Field | Required | Description |
|---|---|---|
id | Yes | Stable gateway id. SHOULD equal the mode id when the harness projects this gateway as a mode. |
label | Yes | Human label for the catalog UI. |
schemaFlavor | Yes | anthropic | openai. Selects which harness family can consume the gateway. |
baseUrl | Yes | Base URL the client hits. |
keyEnv | Yes | Conventional env var holding the provider's API key. Catalog status is derived from its presence in the daemon's environment (ready vs available). |
description | No | Free text. |
scrubEnv | No | Env vars to scrub when the gateway is active. Not surfaced to catalog clients. |
defaultModel | No | Conventional default model id for this provider. |
homepage | No | Homepage/docs URL for the catalog UI. |
A gateway carries no harness projection (env / env_unset / bin_args);
that stays in modes / options.
Continuation
continuation is OPTIONAL but RECOMMENDED. It declares how prior
conversation turns reach the CLI on subsequent invocations. The
driver hosts a strategy registry; this block names which strategies
fit this CLI and which is the default.
continuation:
default: pinned-session
supported: [pinned-session, transcript, none]
pinned_session:
idle_timeout_ms: 1800000
key_scope: [conversation, operator]Built-in strategy ids (continuationStrategyId enum):
| Id | Behaviour | Best for |
|---|---|---|
none | Fresh session per turn, no prior context. Current behaviour. | One-shot tools; debugging |
pinned-session | Driver keeps the spawned child process alive across turns; subsequent session.send calls hit the SAME child, so the CLI's in-memory model context carries over. Idle TTL eviction. | CLIs declaring session.mode: persistent AND context_carryover: true (Claude Code, OpenCode, ...) |
transcript | Caller (host) supplies the last N turns as text; the strategy prepends them as a preamble before the current message. Token-costly but stateless and survives process restarts. | CLIs with resumable: false AND ephemeral session model; debugging when pinning misbehaves |
native-resume | Caller passes a prior session id; the strategy passes it to the CLI's own --resume/--continue flag at start. Requires capabilities.resumable: true. | CLIs with first-class durable sessions |
Hosts MUST refuse to dispatch with a strategy outside supported. The
operator MAY override default via OPERATOR.runtime.config.continuation
provided the chosen id is in supported.
pinned_session.key_scope is the composite key the driver uses to
decide whether two turns share the same pinned child process. Default
[conversation, operator] means: different conversations get different
children; one operator-per-conversation reuses one child across turns.
Sandbox integration
sandbox is REQUIRED. AIP-45 inherits AIP-36 verbatim — the same
provider (local, mastra-modal, mastra-daytona, mastra-e2b,
node-permission, etc.), network.egress, mounts, limits, env
fields apply. The runner passes the resolved sandbox to the protocol
arm; the protocol arm decides how to expose it (e.g. ACP's cwd
parameter on session/new).
confinedReadPaths is OPTIONAL. It lists READ-only paths an
OS-confined spawn needs in order to boot — typically the CLI's own
global config files under $HOME, which an OS-level sandbox profile
denies by default. A ~/... entry anchors at the operator's home; a
leading $VAR/${VAR} is resolved from the per-spawn env and dropped
when unset. The grant is READ-only: it never widens write access, and
mutable harness state belongs in the harness's state home, not here.
Auth surface
auth is OPTIONAL but RECOMMENDED. When present, follows AIP-29's
schema verbatim: ref to an AIP-19 SECRETS.md, state.{paths,env},
login.cmd, refresh.cmd, expiry. The runner resolves secrets via
@agentproto/secrets and passes them to the subprocess via
sandbox.env.set (never argv, never logs).
Presentable auth methods per route (added 2026-10-23)
Draft AIP-45 amendment (2026-10-23). Normative identifiers (field names, literals, tool names) are English and final.
auth MAY carry a methods block mapping each route the harness can be
pointed at to the credential methods it can present on that route:
auth:
methods:
<route>: ["api-key" | "oauth-bearer" | <string>, ...]The route key names a billing route: one of the harness's
gateways[].id, or the reserved key default for the route the harness
uses when no gateway is selected. The value lists every method the harness accepts on
that route, in no priority order. api-key and oauth-bearer are the
two normative values; any other string is reserved for a future method
and hosts MUST treat an unknown value as unsupported rather than as a
wildcard. A route key not declared here has no presentable methods, so a
host MUST NOT point the harness at it.
The consumer is the host. The auth profile primitive (proposed in
agentproto/agentproto#87)
describes a credential and the method it presents. Before a session
starts, the host selects an auth profile only if that profile's method
appears in auth.methods for the session's route. If the method is
absent, the host MUST fall back to a profile that matches, or refuse to
start the session; it MUST NOT present a credential the harness cannot
consume on that route.
When auth.methods is absent, the host falls back to its own
per-harness table of presentable methods. In that case the host MUST be
able to show that table to the user, so the choice of method per
route stays inspectable even without a manifest declaration.
# Claude Code: its own Anthropic route accepts either method; an
# OpenAI-compatible gateway accepts an API key only.
auth:
methods:
default: [oauth-bearer, api-key]
openai-compatible: [api-key]
gateways:
- id: openai-compatible
label: OpenAI-compatible gateway
schemaFlavor: openai
baseUrl: https://gateway.example.com/v1
keyEnv: OPENAI_API_KEYSetup surface
setup is OPTIONAL. When present, mirrors
AIP-29 § Setup verbatim — an ordered, idempotent
pipeline of post-install configuration steps the host runs once per
(bundle.id, workspace.id, user.id) after install and before the
agent is considered ready. Step kinds: cmd (e.g. openclaw onboard --install-daemon), prompt (e.g. gateway URL, default channel),
oauth (AIP-19 driver), external (browser-based pickers).
Use setup for one-time concerns the auth state machine isn't
designed to model: sidecar daemons, bind-time configuration choices,
secret pastes from web consoles, Discord-channel / Slack-workspace
selection. Recurring credential rotation stays in auth.refresh.
Lifecycle integration:
install → version_check → setup → auth.login → spawn(bin) → handshake → sessionWhen the manifest declares setup, the runner MUST refuse to spawn
the binary until every step has either succeeded or matched its
skip_if. Headless callers receive error.code = "setup_required"
with the pending step list.
Rationale
Why a sibling of AIP-29, not an extension. AIP-29's central
abstraction is commands — a tree mapping subcommand paths to
TOOL.md refs. A harness has no commands tree (or a degenerate
one with one entry, "talk"). Stretching commands to model
session-based interaction would either make AIP-29 schema bloat or
make commands ambiguous. A sibling spec keeps both clean.
Why a protocol discriminator, not separate AIPs per protocol.
The install / version / auth / sandbox / capabilities / session
fields are 90% of a harness manifest. Splitting per protocol
would force four near-duplicate schemas and four runners. One
runner with four protocol arms keeps the integration surface one
package.
Why a declarative print arm. A whole class of harnesses
(Claude Code's --print, mastracode) are best driven headless: one
subprocess per turn, events on stdout. Giving them a dedicated arm
keeps them out of the proprietary arm — which exists for
in-process harness packages, a different integration shape — and
out of long-lived ACP connections, whose stale-proxy failure modes
the per-turn subprocess simply doesn't have.
Why ACP is the default. Network effects: 14k weekly TS-SDK downloads, multi-vendor adoption, a growing IDE ecosystem. New agent CLIs increasingly ship ACP support out of the box (Claude Code, OpenCode, Cursor announced). Treating ACP as the default and MCP / proprietary as fallbacks tracks where the ecosystem is going.
Why declarative capabilities mirror runtime capabilities. Hosts need to make routing decisions before boot — "send this user to Hermes (multimodal) or Goose (text-only)?" — without spawning every candidate. Manifest-declared capabilities give pre-flight visibility; runtime negotiation is the verification step.
Why stream events are normalised. A consumer (Guilde Shell view,
Katchy workflow runner) doesn't care that Hermes uses ACP and Goose
uses MCP — it cares that both produce text-delta and tool-call
events. Normalising at the protocol-arm boundary lets every consumer
ship one renderer.
Why mode-changed mirrors ACP current_mode_update. ACP already
lets an agent switch modes by itself and tell the client with a
current_mode_update session update carrying currentModeId. AIP-45
keeps that meaning and adds the two fields a caller cannot recover on
its own: previousModeId (so a consumer that joins late or replays a
log needs no prior state) and cause (so a UI can tell "you switched"
from "the agent switched"). A proprietary arm gets the same event an
ACP arm does, instead of a thought notice a caller would have to
parse.
Why the caller's own switch is a SHOULD, not a MUST. The caller
already learns the outcome of setSessionMode from its return value, so
the event adds nothing for it. Other consumers of the same stream (a
second UI on the session, a recorder, a supervisor) do not see that
return value, which is why emitting is recommended. It is not required
because some arms cannot tell an echoed current_mode_update from an
agent switch without tracking their own pending calls, and a missed
caller-caused event costs nothing to the caller that made the switch.
The agent-caused case is a MUST because no other signal reports it.
Why request instead of a new event. A question and a plan approval
have the same lifecycle as a tool permission: the turn parks, the caller
picks an option, the harness resumes. Reusing agent-prompt and
respondPermission keeps one parking and answering path, and keeps
every existing caller working, since the options list stays the
complete answer surface. The field is named request because kind
already names the event. ACP's elicitation request (a form or URL the
agent asks the client to fill) is marked unstable in the ACP SDK
(@agentclientprotocol/sdk 0.21.1), so AIP-45 does not bind to it;
an ACP arm MAY map a future stable elicitation to request: "question".
Why plan approval names its option ids. Approve and reject could be
inferred from option kinds (allow_once, reject_once), but a harness
may offer more than one option of a kind (for example an approve that
also grants future edits). Naming the two ids removes the guess while
the kinds keep a generic caller correct.
Reference Implementation
@agentproto/harness
— TypeScript runner that loads a HARNESS.md manifest, applies
the sandbox + auth, spawns the binary, dispatches to the protocol
arm, and emits normalised stream events.
The package exposes defineHarness as its canonical entry point; compatibility exports include:
defineAgentCli({...})— validates manifest, returns anAgentCliHandlewith astart(opts) → Sessionmethod.Session.send(message) → AsyncIterable<StreamEvent>— write a turn, consume normalised events.Session.cancel()— abort the in-flight turn (forwardssession/cancelfor ACP, equivalent for other protocols).Session.close()— tear down the session and (if last) the subprocess.- Protocol arms under
src/protocol/{acp,mcp,proprietary,print}.ts. The ACP arm delegates to@agentproto/acp(AIP-44).
The reference impl is the source of truth for the schema during the
Draft phase; spec changes propagate through scaffold-aip regen.
Backward compatibility
Not applicable — first agentproto AIP for interactive harnesses.
AIP-29 stays correct for tool CLIs; AIP-45 covers the harness case
that AIP-29 wasn't designed for. AGENT-CLI.md is accepted as a legacy file name (AIP-70).
The 2026-10-28 mode-changed and typed agent-prompt amendment (draft)
Additive. mode-changed is a new event: a consumer that does not know
it MUST ignore it, as for any unknown event. request, question and
planApproval are new OPTIONAL fields of agent-prompt; an absent
request reads as tool-permission, which is what every agent-prompt
meant before. A caller that ignores them still answers with an
optionId from options. capabilities.mode_events and
capabilities.typed_prompts are OPTIONAL and read as false when
absent, so existing manifests keep validating and keep their meaning.
The 2026-11-03 multi-field questions amendment (draft)
Additive. fields is a new OPTIONAL member of QuestionRequest and
{ answers } a new resolution, valid only for a prompt that carries
fields. Such a prompt still fills the legacy members and offers a
skip option of kind reject_once, so a caller that ignores fields
can still answer a lone single-choice question by optionId, or skip
the form.
The 2026-10-23 presentable auth methods amendment (draft)
auth.methods is OPTIONAL. A manifest that omits it keeps working: the
host falls back to its own per-harness table of presentable methods and
MUST be able to show that table. A manifest that adds it gains stricter
route matching, since a host then selects an auth profile only when the
profile's method is listed for the session's route.
The 2026-10-23 gateways rename amendment (draft)
gateways replaces presets with identical entry fields. presets
stays accepted as a legacy alias, so existing manifests load unchanged; a
manifest MUST NOT carry both fields. Consumers that read presets SHOULD
read gateways first and fall back to presets.
The 2026-11-08 harness-rename amendment (draft)
The adapter manifest field is now harness, with the same meaning (the
NPM package that implements AgentCliClient) and the same requirement (when
protocol=proprietary). adapter is removed, not kept as an alias: a
manifest that still carries it fails validation, and the fix is a rename of
the key. The reference implementation keeps reading adapter until its next
breaking release (AIP-70 §4). The canonical package prefix is
@agentproto/harness-<slug> (AIP-52 §Terminology
reconciliation); @agentproto/adapter-<slug> names are legacy.
Security considerations
Inherits AIP-29's threat surface (install/version/auth/sandbox) and adds the bidirectional-protocol surface.
- Untrusted agent output as prompt. The agent's
text-deltaandagent-promptevents end up in the host's UI. They are attacker-controlled if the agent's model was compromised by upstream prompt injection. Hosts MUST apply the same prompt- injection mitigations as for any user input. - Agent-caused mode changes. A
mode-changedevent withcause: "agent"reports a switch; it does not authorize one. A host that ties permissions to the current mode MUST apply its own policy to the new mode (for example, re-check that an executing mode is allowed for this session) rather than trust the agent's choice. - Plan text and question text.
planApproval.plan,question.promptand choice labels come from the agent and are attacker-controlled under prompt injection, liketext-delta. Hosts MUST render them as untrusted content and MUST NOT resolveplanRefoutside the session's sandbox. - Tool calls from the subprocess. Events of type
tool-callask the host to do something. Hosts MUST gate every tool call through AIP-7 governance — the manifest'scapabilities.tool_callsflag is permission to emit, not permission to auto-execute. - Sandbox bypass via auth env. Secrets passed via
sandbox.env.setmay leak into the agent's tool calls (e.g.bashinvocations) if the sandbox provider doesn't isolate child env. Sandbox providers that don't isolate child env MUST NOT be used withauth. - Resumable sessions and replay. A
session: { mode: resumable }manifest persists conversation state. If the persistence store is shared, a malicious actor with read access can inject prior turns into the agent's context. Hosts MUST scope persistent session storage to the authenticated identity. harnesspackages from npm. Whenprotocol: proprietary, the manifest names an NPM package the runner imports. Hosts MUST treat these the same as any other dependency — pin versions, audit publishers, prefer first-party packages.
See also
- AIP-29 — CLI.md — tool CLIs (one-shot
cmd → output); shares install/version/auth blocks via$ref - AIP-44 — ACP.md — wire protocol when
protocol: acp - AIP-9 — OPERATOR.md — runtime that consumes a harness via the optional
runtime: { kind: "agent-cli" }binding - AIP-17 — RUNNER.md — process boundary
- AIP-19 — SECRETS.md — auth surface
- AIP-36 — SANDBOX.md — sandbox profile
./HARNESS.schema.json— JSON Schema validator./STREAM-EVENTS.schema.json: JSON Schema for theagent-promptandmode-changedevents./EXAMPLES.md— Hermes (acp), Goose (mcp), Gemini CLI (proprietary)./ADAPTER.md— implementer's guide
Resources
Supporting artifacts for AIP-45. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →
AIP-44: ACP (acp/v1): Agent Client Protocol profile
An agentproto profile of the upstream Agent Client Protocol (agentclientprotocol.com) that defines how agentproto operators (AIP-9) participate in ACP — both as clients driving subprocess agents and as servers exposed to ACP-speaking IDEs (Zed, VSCode, JetBrains, Cursor). Pins the upstream protocol revision, layers governance/audit hooks, and standardises operator-binding extensions under metadata.aip44.*.
AIP-46: SESSION (session/v1): long-running multi-turn agent orchestration
A generic session-management protocol for orchestrating long-running, multi-turn harnesses (Hermes, Claude Code, OpenCode, …) on a host. Standardises the lifecycle (spawn → multi-turn → kill), the data model (sessions[] with status / ground / workspace bindings, nested via parentSessionId), the over-the-wire surface (HTTP + SSE + MCP tools), the workspace-resolution pattern that lets a single host serve many bound directories, the per-workspace state partitioning that keeps one workspace's history from evicting another's, and the spawn gate that decides whether a session may delegate to further sessions. Layers over AIP-45 (AGENT-CLI) for the per-harness spawn semantics and AIP-44 (ACP) for the wire format inside one turn; binds AIP-42 (AGENT) as the session's definition, AIP-38 (POLICY) as the delegation authority, and AIP-54 (REF) as the session's ground.