Every ordinary command supports a versioned JSON envelope:

```sh
agent-comms --project /srv/project --actor <agent-id> --json status
```

Successful responses include `api_version`, `ok`, `command`, and `result`. Mutations may also include delivery, receipt, consistency, server sequence, cache sequence, connectivity, and warnings.

`--json` is a compatibility alias for `--output json`. Bounded commands emit
exactly one JSON document. Natural streams opt into JSONL explicitly:

```sh
agent-comms watch --output jsonl
agent-comms invocation listen --runtime runtime-builder --output jsonl
```

Each JSONL record includes `api_version`, `command`, `event`, `timestamp`, and
typed `data`. Bounded commands reject JSONL instead of silently changing their
document contract. MCP, shell completion, exports, and provider attachment
retain their native protocol or pass-through output.

## Treat warnings as data

An invocation request exits successfully when the governed obligation commits, even if wake-up delivery is unavailable. Inspect `delivery.outcome` and warnings separately from the command result.

## Preserve idempotency

Every mutation uses an idempotency key internally. CLI and TUI actions generate and reuse it across their own retries. Custom service clients must do the same; a timeout does not prove the command failed.

## Bound reads

History, search, message, task, and MCP result surfaces use explicit limits and opaque cursors where supported. Do not construct or edit cursors. Treat cursor rejection as stale or tampered input and restart pagination.

## Use exit classes

Automation should branch on the stable error code in JSON and the documented exit-status class, not parse English error messages. Common classes distinguish validation, authorization, integrity, offline/unavailable, conflict/stale state, rate limiting, and project lifecycle failures.

## Non-interactive execution

```sh
agent-comms --non-interactive --json --timeout 15s task list
```

`--non-interactive` prevents prompts. Sensitive actions requiring an elevated passphrase will fail rather than reading from an agent process.