Agent Host Protocol turns persistent agents into a state-authority problem

The editor window is no longer the agent runtime

Persistent agent sessions are distributed systems. The moment one task can continue after a folder closes, appear in a second window, accept input from a browser, and execute beside a remote workspace, the product needs one durable authority for state and side effects.

Visual Studio Code introduced its Agent Host architecture on August 26, 2026. Instead of keeping each local harness inside an editor window's extension host, VS Code runs a dedicated process that owns agent sessions. Editor windows, the Agents window, and remote clients connect to that process. Copilot and Claude retain their own SDKs, loops, tools, commands, and provider-specific behavior; adapters translate their events into a common client-facing session model.

The open Agent Host Protocol, or AHP, defines that model. Its useful claim is narrow: multiple independent clients can share a synchronized view of one long-running agent session. It does not standardize how the model reasons, choose a safe tool policy, isolate a shell, make generated code correct, or prove that a human approval was appropriate. Those controls remain above and below the protocol.

This distinction prevents a common architecture error. Teams see a portable protocol and assume the agent itself is portable. What actually moves is a normalized session representation: chats, turns, terminals, changesets, automation runs, and ordered state changes. A harness adapter still has to preserve provider behavior, and the host still needs access to the real workspace and tools. A different client can observe the same session without understanding every backend event, but it cannot safely invent a capability the host did not expose.

Current community discovery for the exact protocol is limited. The strongest signal is the first-party repository, specification, release activity, and open implementation work, not broad independent adoption. That makes AHP worth studying as an emerging systems design, not declaring as an established industry standard.

AHP standardizes channels, snapshots, and ordered actions

AHP uses JSON-RPC messages routed by a universal channel URI. A root channel exposes host-level state such as available agents and session summaries. Session channels contain chat catalogs, connected clients, changesets, and aggregate status. Chat, terminal, automation, resource-watch, and telemetry channels give each concern its own lifecycle and message vocabulary.

A connection begins with initialize. The client offers supported protocol versions, a stable client identifier, optional metadata, locale, and initial subscriptions. The server selects one compatible version and returns its sequence number plus initial snapshots. If there is no common version, the server must reject the connection rather than letting both sides guess.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "channel": "ahp-root://",
    "protocolVersions": ["0.9.0", "0.8.0"],
    "clientId": "review-ui-7f3c",
    "clientInfo": {"name": "Acme Review", "version": "2.4.1"},
    "initialSubscriptions": ["ahp-root://"]
  }
}

After subscribing to a stateful channel, a client receives a snapshot and then ordered action envelopes. Shared pure reducers apply those actions so clients converge on the same view. The server sequence is the ordering authority. A UI timestamp, arrival time, or locally generated identifier must not replace it.

Not every event is durable. Protocol notifications can describe ephemeral events and are not necessarily stored in state or replayed after reconnection. That difference matters. A progress frame, authentication challenge, or catalog event can disappear during a disconnect even while durable session state remains correct. Client code must know which data can be reconstructed from a snapshot and which condition must be actively re-queried.

Optimistic clients are fast because the host can overrule them

AHP's write-ahead reconciliation lets a client apply its own action immediately instead of waiting for a network round trip. The client maintains three concepts: the last state acknowledged by the server, a queue of local pending actions, and a computed optimistic state produced by replaying pending actions over confirmed state. The UI renders the optimistic result.

When the host echoes the client's action with an authoritative sequence, the client removes the matching head from its pending queue and applies the confirmed action. Actions from other clients or from the agent are first applied to confirmed state, then local pending actions are rebased. Most chat events are append-only, which makes this tractable. True conflicts, such as two clients aborting the same turn, use server-wins behavior.

function receive(envelope) {
  requireMonotonic(envelope.serverSeq, state.lastServerSeq);

  if (isEchoOfPendingHead(envelope, state.pendingActions)) {
    state.pendingActions.shift();
  }

  state.confirmed = reducer(state.confirmed, envelope.action);
  state.lastServerSeq = envelope.serverSeq;
  state.optimistic = state.pendingActions.reduce(reducer, state.confirmed);
  render(state.optimistic);
}

The word “optimistic” must never leak into authorization. A client can optimistically show “cancel requested” or render a draft message. It cannot assume that a tool permission, terminal claim, file mutation, credential grant, or payment is complete until the host and target system confirm it. The UI state is a responsiveness technique; the host receipt is the control fact.

Add stable client action IDs and preserve origin metadata. A retry after a timeout must not create a second user message or execute a command twice. The host should deduplicate an action within a bounded window, return the prior result when safe, and record whether an effect is idempotent, retryable, compensatable, or irreversible. AHP provides coordination primitives; the application still owns effect semantics.

Reconnect is a protocol path, not an exception handler

A reconnect request carries the original client ID, the last server sequence the client observed, and the channels it wants to resume. If the missing interval remains in the host's replay buffer, the server returns missed actions. If the gap is too old, it returns fresh snapshots. In either case the client replaces confirmed state, clears pending actions according to the protocol result, and rebuilds its view.

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "reconnect",
  "params": {
    "channel": "ahp-root://",
    "clientId": "review-ui-7f3c",
    "lastSeenServerSeq": 1842,
    "subscriptions": [
      "ahp-root://",
      "ahp-session:/7b45...",
      "ahp-chat:/91aa..."
    ]
  }
}

A production client should tell the operator which recovery occurred. “Replayed 17 actions” and “snapshot replaced local state because the replay gap expired” have different forensic meaning. Store the disconnect interval, prior and resulting sequence, discarded pending actions, restored subscriptions, and any resource state that must be refreshed.

Ephemeral notifications need explicit recovery. The AHP authentication documentation notes that auth/required is not replayed, so a client must re-check protected resources after reconnecting. Root catalog notifications are also not durable; a client should re-list or rely on the fresh snapshot. Treat every notification type as either reconstructible, re-queryable, or lossy, and make the classification part of the client contract.

Durable errors are another important improvement. The 0.9.0 .NET changelog records turn errors as response parts and adds chat/turnResume for resumable failures. That permits a disconnected reviewer to see why a turn stopped and continue the same turn instead of creating a new ambiguous run. The application should still define which failures are resumable and what preconditions must be revalidated before resumption.

Session synchronization does not grant tool authority

AHP authentication discovery follows OAuth protected-resource metadata concepts. Each agent can advertise resources, authorization servers, scopes, and whether authentication is required. A client obtains a credential and pushes it to the host with an authentication command. If a token expires, the client must obtain a new one rather than replaying the rejected token.

This flow does not make every connected client equally trusted. A monitoring client may read status but not approve tools. A review client may approve one bounded action but not claim a terminal. A desktop client may contribute an interactive tool that a remote browser cannot. Model client identity, channel permission, action type, session, workspace, target, and time separately. Capability negotiation describes what an endpoint implements; authorization decides what this identity may do now.

VS Code's harness documentation makes another crucial distinction: a Git worktree isolates code changes, not commands, network access, or files outside that worktree. A remote Agent Host should therefore run beside the workspace inside an operating-system security boundary appropriate to the task. Do not treat a remote connection or a separate process as a sandbox.

Terminal and client-contributed tools deserve extra scrutiny. Bind each terminal claim to one owning chat, one authenticated client, one workspace, and a short lease. Validate every call on the host even when the UI already displayed an approval. Keep reusable secrets out of session state, action provenance, logs, and extension metadata.

AHP coordinates the session layer; ACP and MCP solve different problems

A real system may use all four. AHP keeps desktop and browser clients synchronized around the session. An adapter uses ACP to communicate with a coding harness. That harness discovers a database or browser tool through MCP. It delegates a bounded task through A2A. The protocols compose only when identity, authority, correlation IDs, budgets, and receipts cross the seams deliberately.

Do not tunnel everything through one generic message. A tool call should remain distinguishable from a client action; a delegation should remain distinguishable from a UI subscription; a session snapshot should not carry a bearer token. Clear layer boundaries make retry and incident analysis possible.

Build the smallest host that can recover honestly

Start with one host, one workspace boundary, root/session/chat channels, a durable action log, version negotiation, and a single test client. Keep the first reducer model append-heavy. Add terminals, changesets, automations, client-contributed tools, and multi-host aggregation only after reconnect behavior is measurable.

session_contract:
  authority: host_only
  protocol_versions: ["0.9.0"]
  replay:
    retention_actions: 50000
    gap_behavior: fresh_snapshot
    notify_operator_on_snapshot_reset: true
  client_actions:
    idempotency_key_required: true
    optimistic_display_allowed: [chat_append, cancel_request]
    optimistic_authorization_allowed: false
  authentication:
    tokens_in_state: prohibited
    recheck_after_reconnect: required
  side_effects:
    receipt_required: true
    retry_class_required: true
  isolation:
    worktree_is_security_boundary: false

1. Define authority. The host owns session state, action sequence, effect dispatch, and automation scheduling. Clients own presentation and local pending intent.
2. Pin and negotiate versions. Reject unsupported major versions, log the selected version, and test additive unknown fields and enum values.
3. Classify every message. Decide whether it is durable state, a replayable action, an ephemeral notification, or a request that must return a receipt.
4. Separate capability from permission. Negotiate channel support, then run a host-side policy decision for the exact identity, session, tool, target, and effect.
5. Instrument convergence. Measure sequence gaps, pending queue age, reducer failures, replay counts, snapshot fallbacks, duplicate actions, and cross-client state hashes.
6. Bind effects to evidence. Record the initiating turn, policy version, approval, target-system request ID, outcome check, and recovery class.

A custom client should use the official libraries when practical, but library availability is not uniform. The repository publishes clients across several languages while open issues document missing transports and server packages. Treat the matrix as current implementation status, not a promise that every language offers identical features.

Eight failure modes appear before model quality matters

The repository's active issue list is useful precisely because it reveals protocol edges: read-watermark persistence, transport-neutral server packages, unknown enum handling, per-chat configuration, progress messages, and client completeness. An early adopter should convert relevant issues into compatibility tests and pin the exact protocol and library versions used in production.

Test disconnects, conflicts, and stale authority on purpose

A happy-path demo proves that two screens can display one chat. A production test proves that they converge after loss, duplication, reordering, partial capability, credential expiry, host restart, and conflicting operator actions.

• Disconnect one client for less than the replay window, mutate the session elsewhere, reconnect, and verify exact sequence and state-hash convergence.
• Repeat after the replay window expires; require a visible snapshot reset and confirm no stale pending action is silently re-applied.
• Send the same client action twice with one idempotency key; verify one durable action and one effect.
• Abort the same turn from two clients; verify deterministic host-wins behavior and a clear losing-client state.
• Expire an agent credential during disconnection; reconnect and confirm the client re-checks authentication instead of replaying the rejected token.
• Connect an older compatible client and introduce unknown optional fields; verify forward compatibility. Connect an unsupported version and require a clean rejection.
• Kill the host during a tool effect; restart and reconcile host action state with the target system before retrying.
• Schedule one automation from two clients; verify the host stores one definition and triggers one run.
• Run two sessions against one worktree; verify the system warns or blocks conflicting mutation even though both AHP sessions are individually valid.

Release only when the test report records protocol and library versions, host build, client matrix, transport, replay retention, fault injection, observed sequences, final hashes, duplicate-effect count, unresolved gaps, and reviewer. Repeat the suite after every protocol upgrade.

Frequently asked questions

Is the Agent Host Protocol only for VS Code?

No. VS Code ships a host and client, but Microsoft publishes the protocol and client libraries under an MIT license. Other applications can implement either side. Production interoperability still depends on the exact version and capabilities implemented.

Can an AHP client control multiple hosts?

Several official client libraries expose multi-host concepts. That is useful for local and remote session catalogs, but each host remains authoritative for its own sessions. A multi-host UI must not merge authority or reuse approvals across hosts.

Does a fresh snapshot guarantee no work was lost?

No. It restores current durable state. Ephemeral notifications may not replay, external effects may require reconciliation, and discarded local pending actions may need user review. Report the recovery mode instead of presenting all reconnects as equivalent.

Should clients persist bearer tokens in session state?

No. Protected-resource metadata can be synchronized, but reusable credentials should stay in an approved credential boundary and never appear in replayable state, action origin, logs, or exported session records.

When should a team adopt AHP?

Adopt or prototype it when several clients must observe one persistent local or remote session and you are prepared to test versioning, reconnect, auth, and effect recovery. A single embedded chat with no continuity requirement may not need this layer.