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.

FieldValue
AIP45
TitleHARNESS (harness/v1): interactive harness manifest
StatusReview
TypeSchema
Domaincli.sh
RequiresAIP-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:

  1. Its frontmatter validates against ./resources/aip-45/draft/HARNESS.schema.json.
  2. Its install, version_check, auth blocks satisfy AIP-29's schemas (referenced via $ref).
  3. When protocol: "acp", the binary's ACP server satisfies the upstream ACP specification at the AIP-44 acp_rev declared by the bound ACP.md.
  4. When protocol: "mcp", the binary speaks MCP-over-stdio per modelcontextprotocol.io.
  5. When protocol: "proprietary", the manifest's harness package (harness field) implements the AgentCliClient interface from @agentproto/harness.
  6. When modes is present, every entry has a unique id matching ^[a-z0-9][a-z0-9\-]*$; mode patches reference no symbols beyond bin_args_append and env.
  7. When options is present, every entry has a unique id matching ^[a-z0-9][a-z0-9_]*$; type: enum entries declare an enum array; min/max only appear on type: integer.
  8. When continuation is present, default is in supported; if default == "native-resume" then capabilities.resumable: true MUST also be declared.
  9. When protocol: "print", the manifest MAY omit the print block (Claude Code defaults apply); when print.event_schema is declared, it MUST be one of the closed enum values listed in § The print arm below.

Frontmatter

The full schema lives in ./resources/aip-45/draft/HARNESS.schema.json. Top-level fields (informative summary):

FieldRequiredDescription
nameYesKebab id matching parent dir
idYesStable runtime id
descriptionYesOne-paragraph purpose
versionYesSemver of this manifest
binYesPath to the binary
bin_argsNoDefault argv (e.g. ["acp"] for hermes acp)
envNoStatic, 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.
installYesArray of install methods (AIP-29 $ref)
version_checkYesVersion detection (AIP-29 $ref)
setupNoPost-install configuration steps (AIP-29 $ref) — daemons, bind-time prompts, OAuth, external pickers
authNoAuth 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.
sandboxYesSandbox profile (AIP-36 $ref)
confinedReadPathsNoREAD-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.
protocolYesacp | mcp | proprietary | print
acpWhen protocol=acpRef to AIP-44 ACP.md describing the wire profile
mcpWhen protocol=mcpInline MCP server config
harnessWhen protocol=proprietaryNPM package implementing AgentCliClient. Named adapter in earlier drafts; adapter is removed (AIP-70 §4).
printWhen protocol=printInline print surface config (optional — Claude Code defaults when omitted)
sessionNoSession settings: mode, idle_timeout_ms, max_turns
modelsNoModel 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.
gatewaysNoGateway endpoints (Anthropic/OpenAI-compatible backends) this harness can be pointed at. Formerly presets, which remains a legacy alias. See § Gateways.
capabilitiesNoDeclarative capability flags (mirror of ACP capability map for non-ACP runtimes)
modesNoMutually-exclusive operation modes (e.g. claude-code's plan / accept-edits / bypass-permissions). One active per turn.
optionsNoIndependent typed knobs (model, max-turns, auto, ...). Multiple may be active per turn.
continuationNoHow prior turns reach the CLI. Declares default + supported strategies.
runnerNoAIP-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-jsonl

Runtimes 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 enum z.enum(["acp", "mcp", "proprietary", "print"]) in packages/harness/src/schema.ts and driven by packages/harness/src/protocol/print-arm.ts in 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:

FieldDescription
prompt_flagHow 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_formatOutput-format flags appended before the prompt. Default ["--output-format", "stream-json"] (Claude Code); e.g. Mastra Code uses ["--output", "jsonl"].
pre_promptExtra flags inserted between output_format and the prompt (e.g. Claude Code's ["--no-interactive"]).
resumeResume/continue flag for reattaching to a prior session: flag plus kind — "value" passes --flag <sessionId>, "boolean" passes the bare flag.
event_schemaClosed 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 session

ephemeral 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:

EventDescription
text-deltaStreaming agent message text chunk
tool-callAgent invoking a tool — args + tool id
tool-resultTool's response delivered back to the agent
thoughtAgent's internal reasoning (when capability declared)
agent-promptAgent asking the user / client to choose: a tool permission, a question, or a plan approval
mode-changedThe session's current mode changed (when capabilities.mode_events declared)
turn-endAgent has finished the current turn
errorOut-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:

  1. A harness that exposes session modes and declares capabilities.mode_events: true MUST emit mode-changed with cause: "agent" whenever the current mode changes for any reason other than the caller's own setSessionMode call. This includes a switch that follows the caller's answer to a plan-approval request (see below): the caller approved a plan, but the harness picked the target mode and made the switch.
  2. The harness SHOULD also emit mode-changed with cause: "caller" once a caller's setSessionMode call has been applied. A refused or no-op call emits nothing.
  3. A harness MUST NOT emit mode-changed when modeId equals previousModeId. The mode a session starts in is reported by the session's initial state (ACP SessionModeState.currentModeId), not by an event.
  4. modeId MUST be one of the session's available modes.
  5. 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.
  6. When protocol: "acp", the arm translates an ACP current_mode_update session update into mode-changed. It fills previousModeId from the mode it tracked before the update, and sets cause: "caller" only when the update confirms a session/set_mode the arm itself sent and has not seen applied yet; otherwise cause: "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.

requestMeaningTyped payload
tool-permissionMay the agent run this tool call? (toolName, rawInput)none
questionThe agent asks the user a questionquestion
plan-approvalThe agent submits a plan and waits for approval before acting on itplanApproval
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:

  1. A harness that sets request to question or plan-approval MUST carry the matching typed payload, and MUST declare capabilities.typed_prompts: true.
  2. Every option a typed payload refers to MUST also be in options, with a human-readable name. Every typed request MUST offer at least one option of kind reject_once or reject_always, so a caller can always refuse.
  3. Question. The caller answers a choice by selecting its optionId. When allowFreeText is true, the caller answers with free text by selecting freeTextOptionId and putting the text in feedback. A free-text selection without feedback is an empty answer; the harness MUST NOT invent one.
  4. Plan approval. A plan-approval request MUST carry plan, planRef, or both. Selecting approveOptionId approves the plan. Selecting rejectOptionId rejects it, and feedback, when present, is the reason handed back to the agent. When targetModeId is set and the plan is approved, the harness switches to that mode and emits mode-changed with cause: "agent" (rule 1 of the previous subsection) when it declares mode_events. A rejected plan leaves the mode unchanged.
  5. { cancelled: true } declines any request kind.
  6. _meta stays the place for vendor extras. A harness SHOULD NOT carry in _meta what request, question or planApproval already 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:

  1. When fields is present it is the source of truth. prompt is then the overall message, and choices, allowFreeText and freeTextOptionId are a projection for callers that predate fields: filled from the only field when the form is exactly one single field (one option per choice, plus the free-text option when that field allows free text, every one of them in options), and choices: [], allowFreeText: false otherwise.
  2. A prompt with fields MUST offer a submit option of kind allow_once and a skip option of kind reject_once, so a caller that only understands options can always unblock the harness. The projection of rule 1 MAY add more.
  3. The caller submits the form with { answers }. selected holds choices[].values (at most one for single), text the typed answer (only where allowFreeText is true, or for a text / number field), value a boolean or number answer. A harness MUST reject answers naming an unknown field or value, and MUST reject { answers } on a prompt without fields. Selecting the skip option declines the whole form; { cancelled: true } cancels it.
  4. recommended is 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:

PropertyField
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 fieldnot 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 | none

capabilities.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):

FieldValuesMeaning
injectnative-dir | system-prompt | noneHow 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.
capturenative-dir-diff | noneWhether 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:

FieldMeaning when true
mode_eventsThe 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_promptsThe 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:

FieldTypeDescription
bin_args_prependstring[]Extra argv prepended before the manifest's bin_args when the mode is active.
env_unsetstring[]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.
statusactive | noop | plannedHonest 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_notestringHuman-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 to type: boolean. Value must be true. Use for bare flags.
  • bin_args_prepend — argv template prepended before the manifest's bin_args when the value is non-default; {value} is replaced as in bin_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 with modes[].env_unset and applied at the same env-merge point, so a value-bearing option (e.g. a base_url pointing 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.

FieldRequiredDescription
idYesStable gateway id. SHOULD equal the mode id when the harness projects this gateway as a mode.
labelYesHuman label for the catalog UI.
schemaFlavorYesanthropic | openai. Selects which harness family can consume the gateway.
baseUrlYesBase URL the client hits.
keyEnvYesConventional env var holding the provider's API key. Catalog status is derived from its presence in the daemon's environment (ready vs available).
descriptionNoFree text.
scrubEnvNoEnv vars to scrub when the gateway is active. Not surfaced to catalog clients.
defaultModelNoConventional default model id for this provider.
homepageNoHomepage/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):

IdBehaviourBest for
noneFresh session per turn, no prior context. Current behaviour.One-shot tools; debugging
pinned-sessionDriver 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, ...)
transcriptCaller (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-resumeCaller 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_KEY

Setup 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 → session

When 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 an AgentCliHandle with a start(opts) → Session method.
  • Session.send(message) → AsyncIterable<StreamEvent> — write a turn, consume normalised events.
  • Session.cancel() — abort the in-flight turn (forwards session/cancel for 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-delta and agent-prompt events 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-changed event with cause: "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.prompt and choice labels come from the agent and are attacker-controlled under prompt injection, like text-delta. Hosts MUST render them as untrusted content and MUST NOT resolve planRef outside the session's sandbox.
  • Tool calls from the subprocess. Events of type tool-call ask the host to do something. Hosts MUST gate every tool call through AIP-7 governance — the manifest's capabilities.tool_calls flag is permission to emit, not permission to auto-execute.
  • Sandbox bypass via auth env. Secrets passed via sandbox.env.set may leak into the agent's tool calls (e.g. bash invocations) if the sandbox provider doesn't isolate child env. Sandbox providers that don't isolate child env MUST NOT be used with auth.
  • 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.
  • harness packages from npm. When protocol: 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

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 →