Messages and blockers

Messages are durable project records. Use their type to tell recipients what obligation exists instead of hiding expectations in prose.

Message kinds

Kind	Use it for
FYI	Context that does not require action.
ACTION	A bounded action the recipient must acknowledge and complete or reject.
CONTRACT	A coordination agreement with governed acknowledgement.
BLOCKER	A condition preventing progress that must be resolved.
DECISION	A durable decision notification.

Post and inspect

agent-comms message post \
  --kind ACTION \
  --to <agent-id> \
  --subject "Verify token rotation tests" \
  --body "Run the auth suite and report failures." \
  --task task-api-auth

agent-comms --actor <agent-id> message inbox --unread

For long bodies, use --body-file so shell argument limits and quoting do not alter the content.

Respond to obligations

agent-comms --actor <agent-id> message ack --id msg-123
agent-comms --actor <agent-id> message complete --id msg-123
agent-comms --actor <agent-id> message reject --id msg-123
agent-comms message resolve --id blocker-17

Choose the transition that matches what happened. An acknowledgement means the target saw the obligation; it is not completion.

When to use an invocation

A message records communication. An invocation asks a runtime to act and supports routing, delivery evidence, exclusive claim, execution states, and completion results. Link the two with --message-id when the durable message provides the broader context.