AIP-66: Managed cloud agents (the `cloud:<vendor>` execution target)

AbstractCopy Anchor Link

An agentproto host runs an agent session in one of three places:

A managed cloud agent is a session that a vendor hosts end to end: the vendor boots the machine, runs its own harness in it, and exposes the session through its own client and API. Examples: Claude Code cloud sessions (Anthropic), Codex cloud tasks (OpenAI).

This AIP fixes how a host exposes such a session as an ordinary agentproto session (listed, promptable, observable, with turn ends and usage), and what it MUST refuse, given that it controls neither the machine nor the harness.

MotivationCopy Anchor Link

AIP-36 assumes the host boots a box and installs its own daemon and the caller's chosen harness inside it. A managed cloud agent breaks both assumptions: nothing can be installed in it, and the harness is fixed by the vendor. Modelling it as a sandbox provider would make boot() lie and would let callers pass fields (installAdapters, mounts, network) that can never take effect.

The value is real anyway: the vendor's compute and credits, a session the user can also open in the vendor's own UI, and no box to keep alive. So it gets its own target with an honest, smaller contract.

SpecificationCopy Anchor Link

1. The targetCopy Anchor Link

A spawn names the target with a vendor slug:

agent_start({ adapter: "claude-code", cloud: "anthropic", prompt: "..." })

• cloud is a vendor slug from the host's vendor registry.
• cloud and sandbox are mutually exclusive. A spawn that sets both MUST be refused.
• AIP-36 is not extended by this AIP. A sandbox provider MUST NOT be used to represent a managed cloud agent.

2. Vendor to harness bindingCopy Anchor Link

Each registry entry declares the harness or harnesses the vendor runs and the adapter that relays to it:

interface CloudVendor {
  slug: string            // "anthropic"
  harnesses: string[]     // ["claude-code"]
  adapter: string         // "claude-code-cloud"
}

• When adapter (or its alias harness) is set and is not in harnesses, and is not the vendor's relay adapter itself, the host MUST refuse the spawn before any side effect, with an error that names the vendor and the allowed harnesses.
• When adapter is unset, the host resolves it to the vendor's relay adapter.
• An unknown vendor slug MUST be refused, never mapped to a default.

3. Repo sourceCopy Anchor Link

A managed cloud agent runs on a git remote and ref, not on a host path.

• The host resolves the spawn's cwd (or workspace) to its git remote and the commit at HEAD.
• The host MUST refuse the spawn when the working tree is dirty or when HEAD is not reachable from the remote. It MUST NOT let a vendor client upload a local working tree as a fallback.
• A cwd that is not a git checkout with a remote MUST be refused.

4. Refused spawn fieldsCopy Anchor Link

The following fields have no meaning for this target. A host MUST refuse a cloud spawn that sets any of them, rather than ignore them:

sandbox, worktree, commandSandbox, mcpServers, daemonMount, bundles, browser, appServe, inference.

A field set to its neutral value counts as unset and is not refused: commandSandbox: "off", browser: false, daemonMount: false, and an empty mcpServers or bundles list.

The refusal names the offending field. The relay adapter SHOULD repeat the mcpServers check when the session is created, so that a host that forwards the field anyway still fails closed.

A host MAY support a vendor-specific subset of model, effort and mode when the vendor client accepts them, and MUST refuse a value the vendor cannot apply.

5. Session identity and re-attachCopy Anchor Link

• One agentproto session maps to exactly one vendor session.
• The host MUST persist the mapping on the session descriptor as meta.cloud = { vendor, sessionId, url } as soon as the vendor returns the id.
• After a host restart, a session whose descriptor carries meta.cloud MUST be re-attached to the same vendor session. The host MUST NOT start a new vendor session to replace it.
• The vendor id usually exists only after the first prompt reaches the vendor, which can be long after the spawn. The host MUST keep waiting for it for as long as the session is alive, not for a fixed delay. How the relay hands the id to the host is implementation-defined (Appendix A shows one way).
• Re-attach goes through the harness wire's own resume verb, carrying the vendor session id rather than the host's or the wire's own id. For an ACP relay (AIP-44) that verb is session/load. On load, the relay adopts the vendor session, and the next prompt is a follow-up turn on it.
• A relay that is asked to load an id the vendor could not have issued MUST fail the load. It MUST NOT start a new vendor session in its place.

6. Lifecycle verbsCopy Anchor Link

The session is projected onto ACP (AIP-44): the vendor's events become agent message chunks and tool call updates, and the vendor's own end-of-turn event ends the ACP prompt. A turn MUST NOT be reported as ended on a timer or on silence alone.

A turn ends only on an end-of-turn event emitted after that turn's prompt. After a re-attach, the vendor's history already holds earlier end-of-turn events, and the relay MUST NOT end the next turn on any of them. The relay SHOULD therefore mark the whole existing history as seen, across every page, before sending the first prompt after the load.

A transient read failure while observing (a network error or a vendor 5xx) SHOULD be retried with backoff before the turn is failed. The vendor keeps working whether or not the host is reading.

7. UsageCopy Anchor Link

• When the vendor's end-of-turn event carries cost or token usage, the host MUST report it as the turn's usage.
• When it does not, the host MUST mark usage as unmeasured. It MUST NOT report zero.

8. CredentialsCopy Anchor Link

• The vendor login (typically OAuth, owned by the vendor's client) is the credential. The host MUST NOT copy it into session descriptors, logs, events or transcripts.
• The host MUST remove from the vendor client's environment any variable that would make the client use a different credential (for Anthropic: ANTHROPIC_API_KEY, plus provider redirect toggles).
• When the vendor login is missing, the spawn MUST fail with an error that tells the user how to log in.

ConformanceCopy Anchor Link

A conformant host:

1. refuses a harness the vendor does not run, before any side effect;
2. refuses cloud together with sandbox or any field of section 4;
3. refuses a dirty or unpushed repo and never uploads a working tree;
4. persists meta.cloud, waits for the vendor id for as long as the session is alive, and re-attaches after a restart through the wire's resume verb with the vendor id, never by starting a new vendor session;
5. ends a turn only on an end-of-turn event emitted after that turn's prompt, never on one already in the history;
6. reports vendor usage, or marks it unmeasured;
7. never exposes the vendor credential.

Appendix A (informative): Anthropic, Claude Code cloud sessionsCopy Anchor Link

Observed with Claude Code CLI 2.1.296 to 2.1.299 (2026-10-14). These are vendor surfaces, partly undocumented, and may change.

Requests carry Authorization: Bearer <claude.ai OAuth access token>, anthropic-version: 2023-06-01 and x-organization-uuid. The CLI refuses cloud sessions when it is authenticated by an API key, and refuses to upload a working tree whose git object store holds lock files or hardlinked objects, which section 3 makes moot.

Reference implementation (agentproto/ts)Copy Anchor Link

• Relay. @agentproto/adapter-claude-code-cloud is an ACP stdio relay (agentproto/ts#1947). It reuses the stream-json to ACP mapping of @agentproto/adapter-claude-sdk.
• Spawn wiring. @agentproto/runtime adds a vendor registry and resolveCloudSpawn. It refuses §2 and §4 violations before any side effect, with the code cloud_spawn_refused (agentproto/ts#1950).
• Id handoff (§5). The host passes the relay a file path through AGENTPROTO_CLOUD_SESSION_META_FILE, inside the session's isolated config directory. Once the vendor returns the id, the relay writes exactly { vendor, sessionId, url } to that file, and never a credential. The host watches the file while the session is alive and merges it into meta.cloud. On resume, it reads the id from meta.cloud, or from the file if the merge never happened, and passes it to ACP session/load.

Security considerationsCopy Anchor Link

• The vendor runs code from the user's repo on the vendor's machines, with the vendor's network policy. Hosts SHOULD surface the session URL so the user can inspect what ran.
• Section 3 exists to stop silent exfiltration of uncommitted files, local secrets and gitignored content through a vendor upload path.
• The OAuth credential grants broad account access. Section 8 forbids persisting it anywhere the host writes.
• Vendor APIs used in Appendix A are undocumented: a host SHOULD pin the vendor client version it was tested with and fail closed on unknown event shapes.

Open questionsCopy Anchor Link

1. Prompting through the API. Whether follow-up turns can be posted to the sessions API directly, removing the CLI from the prompt path.
2. Streaming. Whether /events/stream should replace polling as the default observe path.
3. Second vendor. Codex cloud tasks are expected to fit sections 1 to 8 unchanged; to be confirmed when its adapter lands.

See alsoCopy Anchor Link

• AIP-36: SANDBOX.md: host-controlled compute, the target this one is not
• AIP-44: ACP.md: the wire a cloud session is projected onto
• AIP-45: AGENT-CLI.md: the harness manifests a vendor binds to