---
title: "ACP agents"
description: "Accepted design, ADR 0065: independent off-by-default ACP client and agent roles beside the voice path; exact human-owned permission scopes, managed child confinement, herdr-fenced attachment, bounded lifecycle and unknown dispatch retention. Sixty-nine abstract qualification scenarios, including mandatory resource links without implicit fetching; no runtime implementation or activation."
type: "living"
source: "docs/contracts/acp-integration.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

acp-integration.v1 — the opt-in boundary between operator pi and ACP agents

**Accepted design. Not activated: both directions are off by default.** This is Vulpine's local policy and lifecycle
contract around stable ACP v1, not a new ACP wire version. ADR 0070 owns the architecture. The
Scenario vectors are normative inputs. Their `given`, `when` and
`expect` fields describe state-machine events, not raw ACP packets.


## Native invocation lifetime

The native GPUI host owns the invocation and UI, the controller and the sole provider writer. Retirement is
synchronous, permanent and serialized on that owner with bounded nonblocking write admission; after it, no effecting
write is admitted. Node is a bound request/progress client. Its death or channel loss triggers retirement when
observed, so writes may still be admitted in that interval, and writes admitted earlier may complete. Neither
retirement nor host exit recalls buffered bytes or proves provider quiescence.


## Roles and admission

- **Outbound:** the operator's Pi invokes Vulpine's ACP client to use a registered provider. Fresh local children are
  `managed`; existing agents are `attached` through herdr. Outbound has no connection to the gateway's brain pool.
- **Inbound:** an external ACP client invokes Vulpine's ACP agent, which owns a separate restricted Pi RPC child. The
  client's human UI owns interactive approvals; Vulpine's local loadout ceiling still applies. Unsupported methods
  refuse explicitly. The agent advertises no auth methods and no optional recovery.
- **Voice:** not an ACP initiating interface. No route to remote shell, close, kill or gateway-only tools is added.

| outbound_enabled | inbound_enabled | Admitted role |
|---|---|---|
| false | false | none; no ACP child, listener, discovery polling or model work |
| true | false | outbound only |
| false | true | inbound only |
| true | true | both; independent generations and allocations, shared installation resource ceiling |

The flags are adapter policy; the gateway's config does not read them, and no installed entry point takes them yet. Missing policy means both off; malformed
policy refuses startup. Reconfiguration validates a complete snapshot before publishing it. A disable latches before
the drain, and no invalid replacement undoes it. Only the operator config interface, never a tool call, can enable a
direction, raise a ceiling or register a provider.

The effective tool policy intersects the tool registry's door policy. Enabling the transport does not make a deferred
or off tool callable. Disabling a direction invalidates its sessions' interactive grants at once.

## Provider binding

Each registry entry carries these typed fields, decoded before any spawn or attach:

| Field | Meaning |
|---|---|
| id, version, provenance | Stable provider ID, adapter version and review/license provenance; never chosen from prose |
| exec, sha256, argv | Operator-registered absolute executable, immutable digest and literal argument template; no shell/PATH lookup or unverified downloader |
| roles, protocol_version | Qualified client/agent roles and stable wire version 1 |
| capabilities | Declared operations, negotiation requirements, implementation support and qualification receipt per operation |
| loadout_id, loadout_digest | Mandatory for managed children; names immutable effective tool, extension, fs, network, credential and process policy |
| attachment | Optional herdr backend/address binding and writer/callback proof; absent means no attach |
| platform_profile | Host enforcement implementation and qualification receipt, or unavailable |
| limits | Positive finite limits, no greater than installation ceilings |
| authentication | Explicit credential references and permitted human-interface binding; never literal secrets in discovery metadata |

Runtime capability = implemented ∩ enabled ∩ authorized ∩ negotiated ∩ qualified. A change of provider version or
executable digest invalidates readiness. Warm identity includes provider/digest, role, model/config digest, loadout
digest, principal, machine, workspace scope and authority generation. Policy-incompatible sessions never share a warm
entry. A failed or unknown cleanup is never a reusable entry.


## Capability matrix

`baseline` must pass before a role is ready. `conditional` is advertised and qualified separately. `held` is absent or
unsupported in the initial profile. Outbound support describes the Vulpine client, not every target's promises.

| Surface | Outbound client | Inbound Pi agent | Required behavior |
|---|---|---|---|
| initialize / version / capability exchange | baseline | baseline | Agent returns requested version if supported, otherwise its latest supported version (initially 1); client refuses an unsupported response version. Retain negotiated facts; no mutation before initialized |
| session/new | baseline | baseline | Scope and budget admission before allocation; bind opaque session to principal/generation |
| text and resource_link session/prompt; session/update | baseline | baseline | Both prompt block kinds are mandatory in stable v1, without optional capability flags; ordered bounded updates, one prompt per session, preserved tool-call IDs and stop reason |
| session/cancel | baseline | baseline | Cancel pending permissions, retain prompt slot until remote settlement or verified teardown |
| session/request_permission | baseline handler | baseline caller | Exact offered IDs and scope; nested `selected`/`cancelled` shape; UI not available → `cancelled` |
| session/load and history | conditional | held initially | No fabricated resume; ownership, workspace and authority revalidation; bounded replay with no duplicate live events |
| session/list / fork / resume extensions | held | held | Not baseline; explicit unsupported response if requested |
| modes / model or config changes | conditional | held initially | Enumerated known IDs only, cannot widen loadout; invalidates warm identity; no successful no-op |
| fs/read_text_file and fs/write_text_file | conditional callbacks | conditional delegation | Resource checks independent of tool permission; delegated denial never falls back to local disk |
| terminal/create, output, wait_for_exit, kill, release | conditional callbacks | conditional delegation | Session-owned terminal identity; output and execution budgets; release is not proof of process death |
| image/audio/embedded resource content | held initially | held initially | Optional image, audio and embeddedContext capabilities remain false/absent; reject unsupported blocks before dispatch, never silently discard them. Embedded resource is not resource_link |
| MCP servers in session/new | conditional | held initially | Validate/admit every requested server or reject setup; never accept then ignore |
| authenticate | conditional | conditional | Advertise only real flows; absent auth capability does not mean anonymous remote authorization |
| usage / child-agent extensions | held | held | Bilateral named/versioned negotiation; unknown usage is not zero or complete |
| draft v2 / HTTP or private carriers | held | held | Separate negotiation and qualification; never label them stable-v1 stdio conformance |

Forwarding keeps unknown optional fields within bounded payloads; absent, null and value stay distinct. Unknown
methods get method-not-found. Malformed known tags or outcomes are protocol errors. Unknown notifications may be
ignored with a bounded diagnostic, never read as permission or completion. stdout carries only protocol frames. Wire
errors and stop reasons keep their schema meanings; local refusals are separate typed receipts, never new wire enum
values.

### Baseline resource links

A valid `resource_link` is accepted beside `text` with no optional prompt capability. Block order, the required `uri`
and `name`, schema-valid metadata (`title`, `description`, `mimeType`, `size`, `annotations`, `_meta`) and bounded
unknown fields are preserved. A link is a reference, not embedded `resource` content and not access to its target.

Outbound forwards the link block without dereferencing it. Inbound turns it into a labeled, JSON-escaped untrusted
resource-reference record in Pi's user input, keeping its fields and optional-field presence; metadata never becomes
system instructions, tool configuration or grants. Nothing fetches the URI, opens a local file, resolves DNS or invokes
a URI handler. Later model-requested access is a separate operation under the authority intersection. URI values and
metadata follow the no-full-prompt logging policy.

The whole prompt is validated before dispatch against the selected schema. An unsupported embedded `resource`, image
or audio block rejects the whole prompt, even after valid blocks. Frame, depth and node bounds cover all metadata, and
the translated pi prompt, JSON escaping included, must fit the frame-byte ceiling. Over-budget translation is rejected
before dispatch: nothing is truncated or dropped, and no grant is inferred from a URI scheme or size.

## Authority and human interaction

Effective operation authority is:

`installation policy ∩ immutable loadout ∩ invocation scope ∩ current writer/allocation ownership ∩ applicable grant`.

A preauthorized operation runs only inside the configured restricted scope. Escalation needs a human grant and
overrides no other term. No model judge, title match, keyword rule, mode flag or cache grants wider rights. An unknown
operation or resource classification refuses.

Each pending human interaction records:

- fresh unpredictable local nonce; authenticated principal and initiating interface binding;
- direction, machine/address, connection generation, allocation generation and prompt identity;
- peer session/call IDs, exact offered option IDs with semantic kinds, and canonical operation/resource digest;
- creation time, fixed expiry and a single-use consumed state.

The UI shows the requested operation, target, once/persistent scope and consequences, and returns the nonce with the
exact selected option ID. Commit atomically rechecks freshness, ownership, capability, ceiling and scope, consumes the
nonce and records the selection sent on the wire. A once-only grant offered only a persistent allow answers
`cancelled`; nothing widens, invents a once ID or reads denial into unknown vocabulary. Initial managed profiles permit
only once grants; persistent options show as unavailable.

With a usable transport, a missing UI route, delivery error, expiry, cancellation, transport loss or flag-off settles
the permission as `cancelled`. A duplicate or stale UI response after completion has no wire, audit or effect; the
original `selected`/`cancelled` result stands. Invalid input before the first completion may settle it as `cancelled`
once. Transport failure leaves delivery unknown, not approved. Human text inside a model message is not a UI response.
Logs carry no secrets, full prompts, environment values or credentials; receipts hold scoped identities, typed
reasons, digests and monotonic durations. Private request IDs are never spoken.

Outbound interactions route to the operator's Pi UI bound at invocation. Inbound requests route over the client's ACP
connection only when the launch or registration establishes the initiating human interface; owning the connection does
not prove a human. An automated client has no escalation route. A machine or principal change needs a new session.

A default-off unattended approval flag uses its own preauthorized scope. It never fabricates a human response, widens
the intersection or changes the semantics above.


## Managed child loadouts

A named loadout defines effective argv, model/provider, tools/extensions, workspace roots, writable scratch, isolated
HOME/state, allowed environment keys, credential references, executable/process bounds and network destinations. The
child inherits no ambient environment, user extension discovery, login-shell PATH, SSH agent or gateway credentials.
Pi extensions are selected explicitly; caller overrides intersect policy. Child loadouts have no ACP delegation: depth
is one edge, and invocation lineage rejects inbound/outbound re-entry.

Only explicit model-provider destinations and role-scoped credentials are admitted; the real user HOME is never an
implicit auth source. Credential preparation is outside model control, and diagnostics carry no secret. Downloads,
installation, self-update and model loading are operator actions, never handshake capabilities.

Filesystem enforcement covers parent/symlink replacement and subprocess access, not only canonicalize-then-open.
Terminal and filesystem callbacks each recheck capability, ownership, path/resource scope and budget, and a denied
delegated read or write stays denied. The same ceiling binds child-native tools. Without platform enforcement that
denies raw escape routes, `platform_profile` is unavailable and no managed child starts. The macOS mechanism is not yet
chosen; profiles alone do not confine Pi.

Attached agents are labeled **external profile, not managed confinement**. Only bridge operations are constrained. A
request that needs the managed guarantee refuses attached mode.

## Herdr attachment and cross-host callbacks

Discovery, observation, authenticated transport and exclusive writer acquisition are four separate steps. A record
binds fleet machine, hc terminal address, provider session, connection/allocation generations and a fencing token from
the authoritative owner. Labels and PIDs are evidence inputs, never a lock. Takeover is explicit, revokes the old owner
and cannot replay its pending sends.

A callback stays on the allocation's duplex ACP stream. For an attached remote agent, the provider bridge on that host
binds it to the same session and fenced writer and carries it over the authenticated herdr machine route. A local hook
path or env variable is not a cross-host channel, and no HTTP listener, raw ssh, terminal scraping or unguarded keys
stand in. Without a demonstrated hc/provider primitive, that attachment capability is unavailable.

On severance, snapshots are readable with their age; mutations and approvals refuse before send. An ambiguous send
stays `dispatch_unknown` and never replays. Cancel targets only the captured allocation. Detach drops our writer and
transport only; shutdown never closes or kills the user's existing agent. Voice remote close/kill stays forbidden.

## Lifecycle, drain and uncertainty

Each direction moves `off → starting → ready → draining → off`; a startup failure returns to off. Admission checks the
current generation atomically with the reservation, before any effect. Flag-off linearizes at the admission fence: it
invalidates callbacks before teardown begins, so a concurrent approval cannot commit afterward.

Each prompt records four facts separately:

1. dispatch: `not_sent | sent | dispatch_unknown`;
2. local response: `pending | returned` (exactly once);
3. remote prompt: `running | settled | unknown`;
4. execution: `active | quiescent | unknown`.

`agent_end` may precede a Pi retry; only `agent_settled` settles the Pi prompt. A remote agent's prompt response is a
settlement claim, not proof its subprocesses stopped. Cancel acks, EOF, timeout, synthetic canceled results and a
dropped task future are not quiescence. The prompt/admission permit is held until settlement or verified owned
teardown, even after a local timeout.

Drain closes admission, revokes pending grants, cancels active prompts and waits within the fixed deadline. Managed
children then get TERM, then KILL, only under verified allocation/birth ownership, with reaping and descendant
accounting. Attached agents are detached, never killed; unsettled work stays unknown. Stale identity or unproved
cleanup records `cleanup_unknown`, keeps the capacity reservation and needs reconciliation. The outcome survives a
supervisor crash; a missing ledger record never means idle.

Before OS spawn, the allocation, capacity and terminal-record space are reserved durably under a unique launch intent.
A platform-qualified launch gate holds the child from provider, model or tool effects until its birth identity and
containment handle are bound to that intent. Recovery tells intent-before-spawn, spawn-before-identity-bind and
bound-child-before-first-write apart. A platform that cannot recover or contain a child in that window has no managed
launch. Reconciliation uses only the captured allocation and containment/birth evidence, never a PID or name scan. An
unreadable, corrupt or missing journal refuses admission.

Before the first protocol write, dispatch intent is journaled with space reserved for its terminal outcome. Dispatch,
write and ack are separate facts. Startup reads unresolved records before admitting work. A full journal refuses new
work and never evicts unresolved records. Resolved entries may be pruned; unresolved ones need verified reconciliation
or an operator disposition that records the uncertainty. An ambiguous mutation is never retried automatically.

## Installation admission ownership

One installation is the operator-configured state root and its authenticated owner, shared by every adapter process on
that host; callers cannot pick another root. One logical admission authority owns transactional durable reservations
under it, serializes across OS processes and fences stale generations. It is local accounting, not a fleet plane or
listener. After authority loss, no reservation is reused until recovery reconciles it. If authority or storage is
unavailable, new work refuses. Both-off runs no admission worker and no polling.

A connection is reserved before an outbound provider launches or an inbound decoder, queue or handler is allocated.
Refusal exits or closes without a session or provider child. The quota bounds admitted adapter work, not processes a
user launches; a rejected entrypoint uses only bounded state and exits. Pre-initialize and sessionless connections share
the installation connection cap. Connection memory is freed on verified local teardown; prompt and child reservations
stay held, and reclaiming a connection proves no remote settlement. Handshake and sessionless idle expiry never reset on
notifications or repeated initialize.

## Initial design limits

Conservative defaults, not measured capacity. Limits compose across both roles. Lower overrides are allowed; raising
an installation ceiling is an operator policy edit and needs requalification. Zero, negative, non-finite and unknown
values refuse configuration.

| Bound | Default | Exhaustion behavior |
|---|---|---|
| Connections per installation, including pre-session | 8 | Cross-process reservation before decoder/queue allocation; immediate refusal, no wait queue |
| Initialized sessionless connection idle deadline | 30 s | Close unless a session is admitted; starts at initialize completion, not reset by traffic |
| Sessions / owned children / active prompts per installation | 4 / 2 / 2 | Reserve atomically before spawn/write; immediate busy refusal, no waiting admission queue |
| Active prompts per session | 1 | Busy until settlement/verified teardown, including after local timeout |
| Pending outbound requests / inbound reverse handlers per connection | 16 / 8 | Busy or close for unbounded unsolicited work; no detached uncapped tasks |
| Pending human interactions | 1 per session, 4 total | Cancel excess; reserve before UI publication |
| Frame bytes / decoded depth / decoded nodes | 1 MiB / 32 / 65536 | Reject before unbounded allocation; close malformed/oversize stream |
| Data event queue per connection | 128 entries AND 4 MiB | Bounded backpressure with deadline, then cancel/close; never drop semantic events silently |
| Control reserve per connection | 16 entries AND 64 KiB | Separate from data; exhausted control channel closes rather than deadlocks cancellation |
| Streamed output per prompt / stderr tail per child | 8 MiB / 64 KiB | Output limit cancels; stderr ring retains bounded redacted diagnostics |
| Terminals per session / total | 2 / 4 | Reserve before create; descendants share child enforcement budget |
| Child process memory / descendants | 512 MiB / 16 | Host enforcement required; no profile readiness without it |
| Handshake / write stall / ordinary RPC deadline | 10 s / 5 s / 30 s | Includes queue wait; prompt and permission RPCs use their specific deadlines below |
| Prompt absolute deadline / human interaction expiry | 300 s / 60 s | Fixed, not reset by updates, retries or in-flight UI; human wait counts toward prompt deadline |
| Drain / TERM grace inside drain | 10 s / 2 s | Owned escalation only; deadline returns unknown if not verified |
| Resolved tombstones per connection | 256 | Never reuse a request ID within the connection generation; old/unknown reply cannot affect a new request |
| Journal | 1024 records AND 8 MiB, reserve terminal space before send | Unresolved records never evicted; admission stops before either cap |
| Resolved retention / delegation depth | 7 days / 1 edge | No recursive child delegation; no automatic expiry of unresolved records |

A permission RPC expires at the earlier of interaction creation + the configured human expiry (60 s by default) and the parent prompt's absolute deadline, including queue/UI delivery time; it is exempt from the ordinary 30 s RPC timeout, not from the 5 s write-stall limit. At the deadline, expiry wins over a concurrent selection. No peer notification, retry or UI activity extends either deadline.

Retained maps, mailboxes, promise/event chains, timers, reverse callbacks and replay buffers all count toward these
budgets. Filesystem reads, prompt content and terminal output share the frame and output bounds. The control reserve
does not admit unlimited cancellation frames.

