Message Types

OACP defines 12 message types that cover task coordination, code review, handoffs, and open-ended collaboration. Every message must include a type field set to one of the values below.

For the full message schema and field reference, see Message Schema.

---

Task Coordination

task_request

Assign a unit of work to another agent.

Property	Value
Direction	Any agent to any agent
Expected response	Recipient acknowledges with a notification (status update) or begins work
Priority	Typically P1 or P2

Body: Free-form description of the task. Include enough context for the recipient to begin work without follow-up questions.

type: task_request
subject: "Implement rate limiting middleware"
body: |
  Add rate limiting to the /api/v1/* routes.
  Requirements:
  - Token bucket algorithm, 100 req/min per API key
  - Return 429 with Retry-After header
  - Add unit tests

---

question

Request information or a decision from another agent.

Property	Value
Direction	Any agent to any agent
Expected response	Recipient replies with a notification containing the answer
Priority	Varies; P1 if blocking current work

Body: Free-form. State the question clearly and provide relevant context.

type: question
subject: "Auth strategy for service-to-service calls"
body: |
  Should we use mTLS or signed JWTs for internal service auth?
  Context: 3 services, all in the same VPC, latency-sensitive.

---

notification

Send a non-actionable status update or informational message.

Property	Value
Direction	Any agent to any agent
Expected response	None required — notifications are FYI
Priority	Typically P2 or P3

Body: Free-form. Describe what happened or changed.

type: notification
subject: "CI pipeline green on feat/auth"
body: |
  All 142 tests pass. Build artifact published to staging.
  Ready for review when you are.

---

follow_up

Track deferred work or risk items that need future attention.

Property	Value
Direction	Any agent to any agent (often self-addressed)
Expected response	Owner picks up the item according to its risk tier
Priority	Derived from risk_tier

Body schema (required fields):

Field	Type	Description
source_type	string	Where this follow-up originated: review, task, deploy, incident, or other
source_ref	string	Reference to the originating artifact (PR number, message ID, file path)
risk_tier	string	Risk classification: P2 or P3
summary	string	Brief description of the deferred item
next_action	string	Concrete next step to resolve it
owner	string	Agent responsible for follow-through

Optional fields: tracking_issue, due_hint.

type: follow_up
subject: "Deferred: input validation on /upload endpoint"
body:
  source_type: review
  source_ref: "PR #42"
  risk_tier: P3
  summary: "File upload endpoint accepts any MIME type"
  next_action: "Add allowlist for MIME types, write test"
  owner: claude
  tracking_issue: "#56"
  due_hint: "next sprint"

---

Handoffs

handoff

Transfer ownership of a task or context to another agent.

Property	Value
Direction	Current owner to new owner
Expected response	Recipient replies with handoff_complete when done
Priority	Typically P1

Body schema (required fields):

Field	Type	Description
source_agent	string	Agent transferring ownership
target_agent	string	Agent receiving ownership
intent	string	What the recipient should accomplish
artifacts_to_review	list	Files, PRs, or documents to examine (non-empty)
definition_of_done	list	Criteria for completion (non-empty)
context_bundle.files_touched	list	Files modified during this work (non-empty)
context_bundle.decisions_made	list	Key decisions with rationale (non-empty)
context_bundle.blockers_hit	list	Blockers encountered and resolutions (non-empty)
context_bundle.suggested_next_steps	list	Recommended actions for the recipient (non-empty)

type: handoff
subject: "Handoff: auth middleware to codex for review"
body:
  source_agent: claude
  target_agent: codex
  intent: "Review and merge the auth middleware PR"
  artifacts_to_review:
    - "PR #42"
    - "src/middleware/auth.ts"
    - "tests/middleware/auth.test.ts"
  definition_of_done:
    - "All review findings addressed"
    - "PR merged to main"
  context_bundle:
    files_touched:
      - "src/middleware/auth.ts"
      - "src/middleware/index.ts"
      - "tests/middleware/auth.test.ts"
    decisions_made:
      - "RS256 over HS256 for key rotation support"
      - "Token expiry check before signature verification for fast-path rejection"
    blockers_hit:
      - "Key rotation endpoint not documented — inferred from source code"
    suggested_next_steps:
      - "Review token refresh flow edge cases"
      - "Add integration test for key rotation scenario"

---

handoff_complete

Confirm that a handoff has been fully processed.

Property	Value
Direction	Handoff recipient back to original sender
Expected response	None — this closes the handoff loop
Priority	Same as the originating handoff

Body schema (required fields):

Field	Type	Description
issue	string	Related issue number or URL
pr	string	Pull request number or URL
branch	string	Branch name
tests_run	boolean	Whether tests were executed
next_owner	string	Who owns the work going forward

type: handoff_complete
subject: "Handoff complete: auth middleware merged"
body:
  issue: "#38"
  pr: "#42"
  branch: feat/auth-middleware
  tests_run: true
  next_owner: claude

---

Code Review

The review types form a lifecycle: review_request -> review_feedback -> review_addressed -> review_lgtm.

review_request

Request a code review from another agent.

Property	Value
Direction	Author to reviewer
Expected response	review_feedback with findings
Priority	Typically P1

Body schema:

Field	Type	Required	Description
pr	string	Yes	PR number or URL
branch	string	Yes	Branch name
diff_summary	string	Yes	High-level summary of the changes
max_turns_reviewer	integer	No	Maximum review rounds before escalation
max_runtime_s_reviewer	integer	No	Time budget in seconds for the reviewer

type: review_request
subject: "Review: rate limiting middleware"
body:
  pr: "#55"
  branch: feat/rate-limit
  diff_summary: |
    Adds token bucket rate limiter to API routes.
    3 new files, 1 modified. 280 lines added.
  max_turns_reviewer: 3
  max_runtime_s_reviewer: 600

---

review_feedback

Return review findings to the PR author.

Property	Value
Direction	Reviewer to author
Expected response	review_addressed with fixes, or question for clarification
Priority	Same as the originating review_request

Body schema:

Field	Type	Required	Description
findings_packet	string	Yes	Path or reference to the findings packet file
round	integer	Yes	Review round number (starts at 1)
blocking_count	integer	Yes	Number of findings that block merge

type: review_feedback
subject: "Review feedback: rate limiting (round 1)"
body:
  findings_packet: packets/review/pr-55-round-1.yaml
  round: 1
  blocking_count: 2

---

review_addressed

Notify the reviewer that feedback has been addressed.

Property	Value
Direction	Author to reviewer
Expected response	Another review_feedback or review_lgtm
Priority	Same as the originating review_request

Body schema:

Field	Type	Required	Description
commit_sha	string	Yes	SHA of the commit that addresses the findings
changes_summary	string	Yes	What was changed in response to feedback
round	integer	Yes	Review round being addressed
touched_files	list	Yes	Files modified to address findings
addressed_finding_ids	list	Yes	IDs of findings that were resolved

type: review_addressed
subject: "Addressed review feedback (round 1)"
body:
  commit_sha: "a1b2c3d"
  changes_summary: |
    Fixed race condition in token bucket reset.
    Added mutex around counter increment.
  round: 1
  touched_files:
    - src/middleware/rate-limit.ts
    - tests/middleware/rate-limit.test.ts
  addressed_finding_ids:
    - finding-001
    - finding-002

---

review_lgtm

Approve the PR and signal merge readiness.

Property	Value
Direction	Reviewer to author
Expected response	Author merges the PR
Priority	Same as the originating review_request

Body schema:

Field	Type	Required	Description
quality_gate_result	string	Yes	pass or fail
merge_ready	boolean	Yes	Whether the PR is cleared to merge
nits	list	No	Non-blocking style or preference notes

type: review_lgtm
subject: "LGTM: rate limiting middleware"
body:
  quality_gate_result: pass
  merge_ready: true
  nits:
    - "Consider renaming `rl` to `rateLimiter` for readability"

---

Brainstorming

brainstorm_request

Initiate open-ended research or exploration.

Property	Value
Direction	Any agent to any agent
Expected response	notification with research findings, or brainstorm_followup to narrow scope
Priority	Typically P2 or P3

Body: Free-form. Describe the problem space, constraints, and what kind of output is expected.

type: brainstorm_request
subject: "Research: caching strategies for the query layer"
body: |
  We need to reduce P99 latency on the /search endpoint from 800ms to under 200ms.
  Constraints:
  - Must work with our existing PostgreSQL backend
  - Budget for one additional service (Redis, Memcached, etc.)
  Please research options and recommend an approach with tradeoffs.

---

brainstorm_followup

Amend or narrow the scope of an active brainstorm.

Property	Value
Direction	Original requester to brainstorm agent
Expected response	Updated research findings via notification
Priority	Same as the originating brainstorm_request

Body: Free-form. Provide additional constraints, redirect focus, or ask for deeper analysis on a specific option.

type: brainstorm_followup
subject: "Narrowing: focus on Redis with read-through cache"
body: |
  Your Redis recommendation looks promising. Please go deeper on:
  - Read-through vs write-behind for our write patterns
  - Cache invalidation strategy for real-time consistency
  - Memory sizing estimates for 10M cached queries

---

Summary Table

Type	Purpose	Response Type
task_request	Assign work	notification
question	Request info/decision	notification
notification	FYI update	None
follow_up	Track deferred work	Varies
handoff	Transfer ownership	handoff_complete
handoff_complete	Confirm handoff done	None
review_request	Request code review	review_feedback
review_feedback	Return findings	review_addressed
review_addressed	Feedback addressed	review_feedback or review_lgtm
review_lgtm	Approve PR	Author merges
brainstorm_request	Open-ended research	notification or brainstorm_followup
brainstorm_followup	Amend brainstorm scope	notification