Inter-Agent Comms

Inter-Agent Communication Protocol

Version: 2.0 — 2026-03-08 — Tila ⚡️

All agent-to-agent communication routes through two patterns. Choosing the wrong one wastes tokens and breaks delivery. There is no middle ground.

Pattern 1: `sessions_send` — Persistent Named Agents

Use for: Tila, Frankel, Vinyl, Claw, CC Guru, Coach. These agents run persistent sessions with memory.

sessions_send(
  sessionKey="agent:<agentId>:main",
  message="...",
  timeoutSeconds=0   # ALWAYS — fire-and-forget
)

Examples:

sessions_send(sessionKey="agent:vinyl:main", message="...", timeoutSeconds=0)
sessions_send(sessionKey="agent:frankel:main",   message="...", timeoutSeconds=0)
sessions_send(sessionKey="agent:openclaw-support:main",       message="...", timeoutSeconds=0)

Rules:

timeoutSeconds=0 is MANDATORY. Without it, concurrent runs will timeout and appear to fail (message still delivered but error thrown).
Returns { status: "accepted" } — this means queued and delivered.
To check the result later: sessions_history(sessionKey="agent:<id>:main", limit=5)
Never wait for a result inline — cross-agent runs share a single-concurrency lane.

Pattern 2: `sessions_spawn` — Spawn-Only Worker Templates

Use for: dev, research. These are stateless workers — no persistent memory.

sessions_spawn(
  agentId="dev",             # or research
  task="...",
  label="short-label",       # REQUIRED: for tracking
  runTimeoutSeconds=600,     # REQUIRED: always set a timeout
  cleanup="keep",            # REQUIRED: so output is readable
  model="github-copilot/claude-sonnet-4.6"  # optional override
)

Mandatory spawn contract — every spawn MUST include:

label — short descriptive name (e.g. "r6-discogs-setup")
runTimeoutSeconds — max execution time. Use 300 for S tasks, 600 for M, 1200 for L.
cleanup="keep" — retains transcript for debugging
Disk-write instruction in task brief: "Write results to /home/chrisr6/.openclaw/workspace/checkpoints/subagent-<label>.md"

BASS — Task System

All tasks follow: todo → in_progress → review → done

Transition	Who does it	When
todo → in_progress	Agent claiming the task	At start of work
in_progress → review	Agent completing the task	Work done, needs Chris review
in_progress → done	Agent (if no review needed)	Ops/infra tasks, auto-completeable
review → done	Chris or Tila	After human sign-off
any → blocked	Any agent	When blocked; add blocker note

API pattern:

# Claim
bass task update <ID> '{"status":"in_progress","agent":"<Name>"}'

# Complete
bass task update <ID> '{"status":"done","agent":"<Name>"}'

Who updates what:

Named agents (Tila, PMs) → update their own tasks directly via BASS CLI
Sub-agents (dev, research) → spawning agent updates BASS after receiving results
Heartbeat → Tila syncs her active task status at each 30m tick

Agent Directory

Agent ID	Type	How to reach
`main`	Named (Tila)	`sessions_send(sessionKey="agent:main:main", ...)`
`frankel`	Named (Frankel)	`sessions_send(sessionKey="agent:frankel:main", ...)`
`vinyl`	Named (Vinyl)	`sessions_send(sessionKey="agent:vinyl:main", ...)`
`openclaw-support`	Named (Claw)	`sessions_send(sessionKey="agent:openclaw-support:main", ...)`
`cc-guru`	Named (CC Guru)	`sessions_send(sessionKey="agent:cc-guru:main", ...)`
`coach`	Named (Coach)	`sessions_send(sessionKey="agent:coach:main", ...)`
`dev`	Spawn-only	`sessions_spawn(agentId="dev", ...)`
`research`	Spawn-only	`sessions_spawn(agentId="research", ...)`

Escalation Flow

Sub-agent result → spawning agent verifies → updates BASS → notifies PM if needed
PM decision → Tila (sessions_send) → Chris if blocked
System alert → Tila (sessions_send) → Chris if critical

Anti-Patterns (never do these)

❌ sessions_send without timeoutSeconds=0 — will appear to fail under load
❌ sessions_spawn without label, runTimeoutSeconds, cleanup — loses output
❌ Busy-polling sub-agents — one check after timeout + 2m max
❌ Sub-agent updates BASS directly — spawning agent owns BASS transitions
❌ sessions_send to spawn-only workers — they have no persistent session
❌ Named agent announcing during DND (03:00–08:00) — write to disk, morning brief handles it