# Decapod Control Plane API

## Scope

This document defines the stable API contract for agents and wrappers integrating with Decapod.

## Stable Surfaces

CLI contract:

- `decapod validate`
- `decapod rpc --stdin`
- `decapod handshake --scope <scope> --proof <cmd>...`
- `decapod session init`
- `decapod release check`

RPC envelope (v1):

Request fields:

- `id` (request_id)
- `op`
- `params`
- `session` (optional)

Response fields:

- `id`
- `success`
- `receipt`
- `result`
- `allowed_next_ops`
- `blocked_by`
- `error`

See golden vectors:

- `tests/golden/rpc/v1/agent_init.request.json`
- `tests/golden/rpc/v1/agent_init.response.json`

## Interface Stability Policy

SemVer policy:

- Patch: bug fixes, no schema-breaking envelope changes.
- Minor: backward-compatible additive fields/ops.
- Major: breaking CLI flags, breaking RPC envelope/schema, breaking compatibility guarantees.

Compatibility guarantees:

- Existing envelope fields MUST NOT be removed in minor/patch versions.
- New fields MUST be additive and optional for older clients.
- Golden vectors are required contract anchors.

## Agent Handshake Protocol

A compliant agent handshake MUST:

1. Declare it read `CLAUDE.md` and contract docs.
2. Report Decapod repo version.
3. Declare intended scope.
4. Declare proof commands it will run.
5. Emit a hashed handshake record in the repo store directory (`.decapod/records/handshakes/`).

Command:

```bash
decapod handshake --scope "<scope>" --proof "decapod validate"
```
