OCP Method Reference
All 42 methods in protocol: 1. See Control Protocol for framing, transports and the handshake.
Every method is answered by this build. Four are gated behind --allow-host-mutations and answer unsupported without it.
Scope describes blast radius: connection affects this connection, session affects this conversation, host affects the machine.
Handshake
| Method | Scope | Purpose |
|---|---|---|
hello | connection | Begin the connection. Returns the protocol version and features[], the methods this build answers. The only method accepted before the handshake |
Sessions
| Method | Scope | Purpose |
|---|---|---|
session.create | host | Create a conversation, or continue a saved one |
session.attach | session | Attach to the live event stream. Takes fromSeq |
session.detach | session | Detach without ending the session |
session.list | host | List saved conversations |
session.close | session | End the session |
session.info | session | Current state of this session |
There is no session.resume
Continuing a saved conversation is session.create with a prior session id. Use session.list to find one.
Reading
| Method | Scope | Purpose |
|---|---|---|
session.poll | session | Cursor pattern. {fromSeq, waitMs} → events plus nextSeq. waitMs: 0 is a plain poll; waitMs > 0 parks until an event arrives or the deadline passes |
transcript.get | session | Read the conversation transcript. Pages, rather than risking frame_too_large on a long history |
There is no transcript.edit. History is append-only, and compaction is its only sanctioned mutation.
Turns
| Method | Scope | Purpose |
|---|---|---|
turn.send | session | Send a user message into the conversation. Accepts an idempotencyKey, echoed on turn_started, so a client that retried after a timeout can tell its own turn from a duplicate |
turn.queue | session | Queue a message to become the next prompt when the current turn ends |
turn.cancel | session | Cancel the running turn. The session stays alive |
Consent
| Method | Scope | Purpose |
|---|---|---|
permission.respond | session | Answer a permission.required frame |
permission.setMode | session | Change the permission mode mid-session |
elicitation.respond | session | Answer an elicitation.required frame, where the agent asked a question |
permission.respond takes one of:
| Verdict | Effect |
|---|---|
allow_once | Approve this call |
allow_always | Approve this call and stop asking for its shape |
reject_once | Refuse this call |
reject_always | Refuse this call and stop asking |
permission.setMode accepts plan, manual, accept_edits, auto or dangerous. See Permission Model.
Hard-stop tools always ask
A permission.required frame carrying tier hard_stop is raised in every mode, including dangerous. A client cannot pre-approve it, and neither can permission.setMode.
Plan mode
| Method | Scope | Purpose |
|---|---|---|
plan.list | session | The model's current plan items |
plan.setMode | session | Turn read-only plan mode on or off |
Accounting
| Method | Scope | Purpose |
|---|---|---|
cost.get | session | Token and cost totals for this session |
context.get | session | Context-window occupancy and the compaction trigger |
Background agents
The REPL calls these "background" and "agents". The protocol calls a dispatched conversation an agent. "background" describes where it runs rather than what it is, and a client that is not a terminal has no foreground to contrast it with.
| Method | Scope | Purpose |
|---|---|---|
agents.list | host | Running, stopped and blocked agents |
agents.dispatch | session | Dispatch a detached agent |
agents.attach | session | Attach to a dispatched agent's event stream |
agents.stop | host | Stop an agent by id |
Jobs
| Method | Scope | Purpose |
|---|---|---|
jobs.list | host | Running background jobs |
jobs.tail | host | Tail a job's output |
jobs.kill | host | Kill a job |
jobs.detach | host | Detach a job so the turn stops waiting on it. The job keeps running |
Configuration
| Method | Scope | Gated | Purpose |
|---|---|---|---|
config.schema | host | No | Which keys are writable, which are refused, and why |
config.get | host | No | The resolved configuration |
config.set | host | Yes | Write a configuration key |
config.get reports whether api_key is set, never what it is. A settings dump is exactly the shape of thing that ends up in a bug report.
Keys config.set always refuses
skip_permissions, mode, cwd, api_key, actor
These decide how much the model may do without asking, and they persist. config.schema names them and the reason, so a client can explain the refusal rather than looking broken.
Memory
| Method | Scope | Purpose |
|---|---|---|
memory.list | host | List persistent per-project notes |
memory.get | host | Read one entry |
memory.delete | host | Delete one entry |
Entries resolve through the same realpath check the Memory tool uses.
Modules and assessment
| Method | Scope | Gated | Purpose |
|---|---|---|---|
modules.list | host | No | Which capability packs this build has, and which are active |
checks.list | host | No | The check catalogue |
checks.run | host | Yes | Run conformance checks |
audit.run | host | Yes | Run a profile and return the report |
See Conformance Checks and Audit Reports.
MCP
| Method | Scope | Purpose |
|---|---|---|
mcp.servers | host | Connected MCP servers and their tools |
There is no mcp.login
An OAuth browser flow needs a browser and a terminal a served process does not have. Run oasis-agent --mcp-login out of band instead. See MCP Integration.
Adding the method later would be additive; shipping it early would be a permanent commitment made before anyone asked for it.
Host lifecycle
| Method | Scope | Gated | Purpose |
|---|---|---|---|
version | host | No | Version, commit and build date |
doctor | host | No | Installation report: versions on disk, active version, setting provenance |
update.check | host | No | Whether a newer version is published |
update.apply | host | Yes | Install and activate the newest version |
Host-mutating methods
Four methods reshape the host and are off by default:
| Method | Why it is gated |
|---|---|
config.set | Writes settings that outlive the session |
checks.run | Executes probes against the machine |
audit.run | Executes probes against the machine |
update.apply | Replaces the running binary |
Enable them explicitly:
oasis-agent serve --unix /run/oasis.sock --allow-host-mutationsWithout the flag they are declared, absent from features[], and answer unsupported with a reason naming the flag.
Errors
| Reason | Meaning |
|---|---|
frame_too_large | The frame exceeded 16 MiB. Typed, not a disconnect |
unsupported | The method is declared but not enabled in this build |
| Timeout on consent | Nobody answered a permission.required within the window |
Discovering what a build answers
Do not infer the method set from the protocol version. Read features[] from the hello response. It lists exactly the wire names this build answers, with gated methods excluded.