# SwarmForge Handoff Protocol Message Types: A Complete Reference

> Explore SwarmForge handoff protocol message types including handshake task task-ack result error ready shutdown and heartbeat for JSON communication between daemon and agents.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: api-reference
- Published: 2026-08-11

---

**The SwarmForge handoff protocol defines eight core message types—`handshake`, `task`, `task-ack`, `result`, `error`, `ready`, `shutdown`, and optional `heartbeat`—that enable JSON-based communication between the SwarmForge daemon and worker agents.**

The SwarmForge handoff protocol is a lightweight, language-agnostic messaging specification used to coordinate work between the central daemon and distributed worker processes. According to the `unclebob/swarm-forge` source code, this protocol is deliberately minimal to ensure reliable inter-process communication over Unix domain sockets or standard I/O streams. All messages share a common JSON structure with a required `type` field and payload-specific additional fields.

## Core Message Types in the SwarmForge Handoff Protocol

The protocol specification in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) defines a fixed taxonomy of message types. Each type serves a distinct purpose in the task lifecycle, from connection establishment through result delivery.

### handshake: Connection Negotiation

The **`handshake`** message initiates communication between the SwarmForge daemon and a worker. It negotiates protocol version and capability exchange.

```json
{
  "type": "handshake",
  "protocol_version": "1.0",
  "supported_message_types": [
    "handshake",
    "task",
    "task-ack",
    "result",
    "error",
    "ready",
    "shutdown"
  ]
}

```

Direction: Daemon → Worker (initial connection)

### task: Work Unit Distribution

The **`task`** message carries the complete description of a work unit, including prompt, script, or batch configuration.

```json
{
  "type": "task",
  "task_id": "c7f8a9e2-3d1b-4f6e-9a2b-0d5e7c1f9b34",
  "payload": {
    "prompt": "Write a short essay on the benefits of test-driven development.",
    "language": "en"
  }
}

```

Direction: Daemon → Worker

### task-ack: Receipt Confirmation

The **`task-ack`** message acknowledges task receipt and signals worker readiness to begin execution.

```json
{
  "type": "task-ack",
  "task_id": "c7f8a9e2-3d1b-4f6e-9a2b-0d5e7c1f9b34",
  "status": "accepted"
}

```

Direction: Worker → Daemon

### result: Outcome Delivery

The **`result`** message returns completed task output, execution status, and any generated data.

```json
{
  "type": "result",
  "task_id": "c7f8a9e2-3d1b-4f6e-9a2b-0d5e7c1f9b34",
  "output": "Test-driven development (TDD) encourages ...",
  "exit_code": 0
}

```

Direction: Worker → Daemon

### error: Failure Reporting

The **`error`** message communicates task processing failures with diagnostic context.

```json
{
  "type": "error",
  "task_id": "c7f8a9e2-3d1b-4f6e-9a2b-0d5e7c1f9b34",
  "message": "Unable to spawn subprocess: file not found",
  "code": 101
}

```

Direction: Worker → Daemon

### ready: Worker Availability Signal

The **`ready`** message announces idle status and capacity to accept new tasks.

```json
{
  "type": "ready",
  "worker_id": "worker-42"
}

```

Direction: Worker → Daemon

### shutdown: Graceful Termination

The **`shutdown`** message requests orderly connection closure from either party.

```json
{
  "type": "shutdown",
  "reason": "normal termination"
}

```

Direction: Bidirectional (Daemon ↔ Worker)

### heartbeat: Connection Maintenance (Optional)

The **`heartbeat`** message keeps connections alive and enables health monitoring.

```json
{
  "type": "heartbeat",
  "timestamp": 1723589123
}

```

Direction: Bidirectional (Daemon ↔ Worker)

## Implementation Files and Test Coverage

The SwarmForge handoff protocol is implemented across several source files with comprehensive test coverage:

- **[`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md)** — Formal specification documenting all SwarmForge handoff protocol message types and their schemas
- **`swarmforge/scripts/handoff_lib.bb`** — Babashka implementation of protocol serialization, deserialization, and helper functions used by daemon scripts
- **`test/swarmforge/script_test.clj`** — Integration test suite validating end-to-end message handling workflows
- **`test/swarmforge/handoff_test.clj`** — Unit tests focused specifically on protocol compliance and edge case handling

## Summary

- The SwarmForge handoff protocol uses **eight core message types**: `handshake`, `task`, `task-ack`, `result`, `error`, `ready`, `shutdown`, and optional `heartbeat`
- All messages are **JSON-encoded** with a mandatory `type` field and payload-specific additional fields
- The protocol supports **bidirectional communication** between daemon and workers over Unix domain sockets or standard I/O
- **Complete specification** lives in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) with reference implementation in `handoff_lib.bb`

## Frequently Asked Questions

### What is the minimum required field for every SwarmForge handoff protocol message?

Every message must include a `type` field containing one of the defined message type strings. The protocol rejects any JSON object lacking this field. Additional required fields vary by message type—for example, `task` messages require `task_id` and `payload`, while `result` messages require `task_id` and `output`.

### How does the SwarmForge daemon discover worker capabilities?

Capability discovery occurs during the `handshake` exchange. The daemon sends its `supported_message_types` array, and the worker responds with its own capabilities. Both parties must agree on protocol version (currently `"1.0"`) before task distribution begins. This negotiation prevents version mismatch errors during active work distribution.

### Can workers send tasks to other workers using this protocol?

No. The SwarmForge handoff protocol defines an asymmetric communication pattern where only the daemon originates `task` messages. Workers operate in a request-response model: they signal `ready` state, receive `task` assignments, and return `result` or `error` responses. Peer-to-peer task delegation is not supported by the current protocol specification.