Transport & Wire Format

CKP uses JSON-RPC 2.0 as its wire format for communication between Agents and other actors. This is consistent with MCP and enables interoperability across the ecosystem.

Actor Model

CKP defines a closed vocabulary of five actors. Every JSON-RPC method declares its direction using exactly two of these actors.

Actor	Definition
Operator	Human or automation managing the agent lifecycle (start, stop, configure)
User	Human interacting with the agent via a Channel
Agent	The Claw runtime instance executing the agent loop
Peer	Another Agent participating in a Swarm
Service	External system: MCP server, memory backend, registry, sandbox runtime

Protocol messages MUST NOT use ad-hoc actor names.

JSON-RPC 2.0

All CKP messages follow standard JSON-RPC 2.0 framing:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "claw.tool.call",
  "params": {
    "name": "web-fetch",
    "arguments": {
      "url": "https://example.com/data.json"
    },
    "context": {
      "identity": "research-assistant",
      "sandbox": "network-sandbox",
      "policy": "standard-policy",
      "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Methods

CKP defines 15 protocol methods across four groups:

WorldModel in CKP 0.3.0 is intentionally manifest- and runtime-profile-level only. It does not add new JSON-RPC methods in this release.

Agent Management

Method	Direction	Type	Purpose
`claw.initialize`	Operator —> Agent	Request	Start agent with manifest. MUST be the first message in a session.
`claw.initialized`	Operator —> Agent	Notification	Confirm handshake complete.
`claw.status`	Operator —> Agent	Request	Query agent lifecycle state.
`claw.shutdown`	Operator —> Agent	Request	Graceful shutdown with drain timeout.
`claw.heartbeat`	Agent —> Operator	Notification	Proactive liveness signal (default: every 30s).

Tool Execution

Method	Direction	Type	Purpose
`claw.tool.call`	Agent —> Service	Request	Execute a tool. MUST include `request_id` for idempotency.
`claw.tool.approve`	User —> Agent	Request	Approve a pending tool execution.
`claw.tool.deny`	User —> Agent	Request	Deny a pending tool execution.

Swarm Coordination

Method	Direction	Type	Purpose
`claw.swarm.delegate`	Agent —> Peer	Request	Assign a task to a peer agent.
`claw.swarm.report`	Peer —> Agent	Request	Return task results.
`claw.swarm.broadcast`	Agent —> Peer*	Notification	Send message to all peers.
`claw.swarm.discover`	Agent —> Service	Request	Find available peers.

Memory Operations

Method	Direction	Type	Purpose
`claw.memory.query`	Agent —> Service	Request	Search memory stores (semantic, key, time-range).
`claw.memory.store`	Agent —> Service	Request	Persist information. MUST include `request_id`.
`claw.memory.compact`	Agent —> Service	Request	Trigger memory compaction.

Initialize Contract

claw.initialize is the protocol handshake. The Operator sends the protocol version, client identity, manifest, and capability request. The Agent responds with its identity, negotiated capabilities, and runtime metadata.

Two rules matter for interoperability:

claw.initialize MUST be the first request in a session
top-level capabilities: {} means the Operator is not restricting the response

That second rule is easy to misread. An empty top-level capabilities object does not mean “support nothing.” It means “report everything you actually support.” If the Operator sends explicit keys such as {"tools":{}}, the Agent should respond with the intersection of those requested groups and its real support.

Example unrestricted request:

{
  "jsonrpc": "2.0",
  "id": "req-init-1",
  "method": "claw.initialize",
  "params": {
    "protocolVersion": "0.3.0",
    "clientInfo": {
      "name": "ckp-test",
      "version": "0.3.0"
    },
    "manifest": {
      "kind": "Claw",
      "metadata": {
        "name": "demo-agent",
        "version": "1.0.0"
      }
    },
    "capabilities": {}
  }
}

Example restricted request:

{
  "jsonrpc": "2.0",
  "id": "req-init-2",
  "method": "claw.initialize",
  "params": {
    "protocolVersion": "0.3.0",
    "clientInfo": {
      "name": "ckp-test",
      "version": "0.3.0"
    },
    "manifest": {
      "kind": "Claw",
      "metadata": {
        "name": "demo-agent",
        "version": "1.0.0"
      }
    },
    "capabilities": {
      "memory": {}
    }
  }
}

In the second case, an L3 agent should report only memory in the response capabilities object.

Method Support by Conformance Level

Method Group	Level 1	Level 2	Level 3
`claw.initialize`, `claw.status`, `claw.shutdown`	MUST	MUST	MUST
`claw.heartbeat`	SHOULD	SHOULD	MUST
`claw.initialized`	SHOULD	SHOULD	SHOULD
`claw.tool.call`, `claw.tool.approve`, `claw.tool.deny`	—	MUST	MUST
`claw.swarm.*` methods	—	—	MUST
`claw.memory.*` methods	—	—	MUST

If an Agent receives a method it does not support, it MUST respond with error code -32601 (Method not found).

Error Codes

Core CKP Errors

Code	Name	Meaning
`-32001`	Protocol version not supported	`claw.initialize` version mismatch
`-32010`	Sandbox denied	Tool execution blocked by Sandbox constraints
`-32011`	Policy denied	Tool execution blocked by Policy rule
`-32012`	Approval timeout	User did not approve within the configured timeout
`-32013`	Approval denied	User explicitly denied the tool execution
`-32014`	Tool execution timeout	Tool exceeded its configured `timeout_ms`
`-32021`	Provider quota exceeded	Token or cost limit reached

Standard JSON-RPC Errors

Code	Name	Meaning
`-32700`	Parse error	Invalid JSON received
`-32600`	Invalid request	Malformed JSON-RPC structure
`-32601`	Method not found	Unknown method name
`-32602`	Invalid params	Params do not match method schema

Error codes in the range [-32000, -32099] are reserved for CKP-specific errors. Implementations MUST NOT use codes in this range for custom purposes.

Error responses MUST include a message field with a human-readable description. Error responses SHOULD include a data field with structured context:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32011,
    "message": "Policy denied: rule sec-003 blocks destructive file operations",
    "data": {
      "rule_id": "sec-003",
      "tool": "file-delete",
      "action": "deny"
    }
  }
}

The extended error catalog (provider errors, memory errors, swarm errors) is defined in the Runtime Profile.

Supported Transports

Transport	Use Case	MCP Compatible
stdio	Local process communication	Yes
HTTP/SSE (Streamable HTTP)	Remote agents, registries	Yes
WebSocket	Real-time bidirectional (swarm coordination)	Extension
Message Queue (NATS, Redis)	Distributed swarms	Extension
Filesystem	Container IPC	Extension

The first two transports (stdio and HTTP/SSE) are MCP-compatible. The remaining three are CKP extensions. See the Runtime Profile for framing guidance on WebSocket, Message Queue, and Filesystem transports.