M4: Agent-to-Agent Communication

2026-02-20T20:24:59Z by Showboat 0.6.0

BD_ACTOR=pm-agent bd create "Implement OAuth login" --labels dev -d "Add OAuth2 login flow for the frontend" --json

warning: beads.role not configured. Run 'bd init' to set.
{
  "id": "beads-pen",
  "title": "Implement OAuth login",
  "description": "Add OAuth2 login flow for the frontend",
  "status": "open",
  "priority": 2,
  "issue_type": "task",
  "owner": "test@b4arena.dev",
  "created_at": "2026-02-20T20:25:49.24306Z",
  "created_by": "pm-agent",
  "updated_at": "2026-02-20T20:25:49.24306Z"
}

PM agent created bead beads-pen with label dev. Note: created_by shows pm-agent — BD_ACTOR provides audit trail.

BD_ACTOR=dev-agent bd update beads-pen --claim --json

[
  {
    "id": "beads-pen",
    "title": "Implement OAuth login",
    "description": "Add OAuth2 login flow for the frontend",
    "status": "in_progress",
    "priority": 2,
    "issue_type": "task",
    "assignee": "dev-agent",
    "owner": "test@b4arena.dev",
    "created_at": "2026-02-20T20:25:49Z",
    "created_by": "pm-agent",
    "updated_at": "2026-02-20T20:25:57Z",
    "labels": [
      "dev"
    ]
  }
]

Dev agent claimed the bead atomically: status → in_progress, assignee → dev-agent. The --claim flag is an optimistic lock.

echo 'ASK beads-pen "Which OAuth provider should we use?"' | BD_ACTOR=dev-agent bash scripts/agent-comm.sh

Comment added to beads-pen

Dev used the ASK command via agent-comm.sh. The script translates it into bd comments add with a QUESTION: prefix.

BD_ACTOR=dev-agent bd comments beads-pen --json

[
  {
    "id": 1,
    "issue_id": "beads-pen",
    "author": "dev-agent",
    "text": "QUESTION: Which OAuth provider should we use?",
    "created_at": "2026-02-20T20:26:06Z"
  }
]

Comment stored with author dev-agent and the QUESTION: prefix. This structured format lets agents parse comment types programmatically.

echo 'ANSWER beads-pen "Use Google OAuth with PKCE flow"' | BD_ACTOR=pm-agent bash scripts/agent-comm.sh

Comment added to beads-pen

BD_ACTOR=pm-agent bd comments beads-pen --json

[
  {
    "id": 1,
    "issue_id": "beads-pen",
    "author": "dev-agent",
    "text": "QUESTION: Which OAuth provider should we use?",
    "created_at": "2026-02-20T20:26:06Z"
  },
  {
    "id": 2,
    "issue_id": "beads-pen",
    "author": "pm-agent",
    "text": "ANSWER: Use Google OAuth with PKCE flow",
    "created_at": "2026-02-20T20:26:21Z"
  }
]

Comment round-trip complete: dev asked (comment #1, author dev-agent), PM answered (comment #2, author pm-agent). Both preserve identity and maintain chronological order.

echo 'DELEGATE beads-pen qa "Review OAuth login implementation"' | BD_ACTOR=dev-agent bash scripts/agent-comm.sh

Dev delegated a review to QA. The DELEGATE command creates a new follow-up bead with label qa and a description referencing the original bead ID.

bd list --status open --json

[
  {
    "id": "beads-zz0",
    "title": "Review OAuth login implementation",
    "description": "Follow-up from beads-pen. Created by dev-agent.",
    "status": "open",
    "priority": 2,
    "issue_type": "task",
    "owner": "test@b4arena.dev",
    "created_at": "2026-02-20T20:26:32Z",
    "created_by": "dev-agent",
    "updated_at": "2026-02-20T20:26:32Z",
    "labels": [
      "qa"
    ],
    "dependency_count": 0,
    "dependent_count": 0,
    "comment_count": 0
  }
]

Follow-up bead beads-zz0 created with label qa. Description references origin: "Follow-up from beads-pen. Created by dev-agent." QA can discover this via bd list --status open or bd ready --label qa.

BD_ACTOR=dev-agent bash scripts/check-comments.sh

COMMENT beads-pen dev-agent "QUESTION: Which OAuth provider should we use?"
COMMENT beads-pen pm-agent "ANSWER: Use Google OAuth with PKCE flow"

check-comments.sh found dev-agent's in-progress bead and output both comments in structured COMMENT <id> <author> "<text>" format. An agent can parse this to detect answers to its questions.

bd show beads-pen --json

[
  {
    "id": "beads-pen",
    "title": "Implement OAuth login",
    "description": "Add OAuth2 login flow for the frontend",
    "status": "in_progress",
    "priority": 2,
    "issue_type": "task",
    "assignee": "dev-agent",
    "owner": "test@b4arena.dev",
    "created_at": "2026-02-20T20:25:49Z",
    "created_by": "pm-agent",
    "updated_at": "2026-02-20T20:25:57Z",
    "labels": [
      "dev"
    ],
    "comments": [
      {
        "id": 1,
        "issue_id": "beads-pen",
        "author": "dev-agent",
        "text": "QUESTION: Which OAuth provider should we use?",
        "created_at": "2026-02-20T20:26:06Z"
      },
      {
        "id": 2,
        "issue_id": "beads-pen",
        "author": "pm-agent",
        "text": "ANSWER: Use Google OAuth with PKCE flow",
        "created_at": "2026-02-20T20:26:21Z"
      }
    ]
  }
]

Original bead beads-pen remains in_progress with assignee dev-agent. Delegation created a separate follow-up bead — it does not change the original bead's status.

Summary

All M4 communication patterns verified:

Comment round-trip: dev-agent asked a question, pm-agent answered — both comments stored with correct author and chronological order.
Identity preservation: BD_ACTOR flows through to comment author field, providing a reliable audit trail.
Delegation: DELEGATE created a new follow-up bead (beads-zz0) with label qa, referencing the original bead in its description.
Non-destructive: The original bead stayed in_progress after delegation — follow-ups are independent beads.
Discovery: check-comments.sh outputs structured COMMENT lines, enabling agents to poll for responses without LLM tokens (Tier 1).
Role routing: The follow-up bead has label qa, so QA agents can discover it via standard label-based routing.

The agent-comm.sh and check-comments.sh scripts provide a zero-token communication layer between agents using beads as the coordination substrate.

Summary​

Summary