Tool reference

Assignment and acceptance-contract mutations take a base_revision and reject stale writes. Run-scoped agent writes enforce active-run ownership instead; Brief and Attention writes also use client_update_id for idempotency. These tools only change local lanes and the event timeline — they never execute commands, resume threads, or touch files.

Coordination

Tool	Role	Purpose
register_actor	any	register/refresh an actor profile
register_workspace	any	create/refresh a workspace record (idempotent)
create_team	any	create/refresh a team (auto-creates its workspace)
create_assignment	integrator	create a task (optional workspace/team/paths/criteria)
list_workspaces / get_workspace_detail	any	compact workspace discovery and per-workspace team/count detail
cancel_assignment	integrator	void a task (mistake/scope dropped); releases any lease
supersede_assignment	integrator	retire a task replaced by another (superseded_by)
claim_assignment	agent	claim a lease; records run/session/worktree metadata
heartbeat_run	agent	report run liveness
checkpoint_run	agent	refresh the latest human-only Brief without changing run status
raise_attention	agent	write yellow/green non-blocking Attention; green resolves a dedupe key
record_run_binding	agent / integrator	update active run communication metadata and append an observed binding event
request_intervention / respond_intervention	agent / human	use the red/blocking path (optionally with a Decision Packet) and move a run to/from an awaiting-human lane
append_event / submit_handoff	agent	append evidence / submit a reviewable handoff
list_pending_reviews / get_event_detail	any	compact team-scoped review summaries / one complete selected event
review_event / accept_event / reject_event	integrator	record a review decision
get_team_board / get_assignment_detail / get_run_detail	any	coordination read models
get_human_brief / get_attention_board	any	reconstruct the latest human projections from the event ledger
get_snapshot / export_git_projection	integrator	accepted projection

Compact discovery and high-volume reads

Start with list_workspaces to discover compact workspace IDs. Then call get_workspace_detail (workspace_id) for compact teams and assignment counts. Choose one exact team before high-volume reads and pass its required team_id to get_team_board, list_pending_reviews, get_snapshot, list_contracts, and get_attention_board. These reads do not use pagination: do not pass pagination controls.

get_team_board is an agent-orientation read model. It returns a flat assignments array whose items contain only assignment_id, title, and status. Its status is an optional, one exact status filter; omitting it excludes accepted, rejected, cancelled, and superseded. After choosing a specific ID from a compact read, use get_event_detail, get_assignment_detail, get_run_detail, or get_contract_detail for full detail.

Only these eleven Ack tools return a compact acknowledgement without a payload echo: append_event, submit_handoff, heartbeat_run, checkpoint_run, raise_attention, record_run_binding, request_intervention, respond_intervention, review_event, accept_event, and reject_event. The acknowledgement contains sequence, event_id, assignment_id, run_id, event_type, status, reviewed_event_id, assignment_revision, current_assignment_revision, and created_at.

claim_assignment and actor/workspace/team/assignment/contract mutations retain their existing responses. In particular, keep using active_run_id from the full claim_assignment response.

record_run_binding

Updates metadata for one active run and appends a run_binding_recorded observed event. Agents may update only their own active runs; integrators may update any active run. This is intended for adapter kind, thread cursor, turn cursor, and idempotency metadata. It does not change accepted state and rejects terminal runs.

Human Brief and Attention

checkpoint_run refreshes a human-only latest Brief and never changes run status. The source_event_sequence must identify an event from that run, while client_update_id makes retries idempotent:

Brief freshness defaults to 30 minutes. A team's freshness_window_minutes setting may only shorten that window: positive integers are capped at 30, while invalid values (including booleans) fall back to 30. Age alone does not make a Brief stale; the window must have elapsed and a later event for the same run other than human_brief_updated must exist.

Checkpoints are mandatory for phase_changed, milestone_completed, plan_changed, decision_made, risk_changed, intervention_requested, handoff, and run_finished. Team settings cannot disable these triggers.

{
  "run_id": "run_123",
  "actor_id": "agent-a",
  "actor_role": "agent",
  "client_update_id": "brief-7",
  "source_event_sequence": 42,
  "brief": {
    "schema_version": 1,
    "current_goal": "Expose human attention APIs",
    "current_stage": "implementing",
    "recent_progress": ["Added the read routes"],
    "decisions_and_risks": [],
    "human_intervention": {"needed": false, "blocking": false},
    "next_steps": ["Run verification"],
    "context_refs": ["task-3-brief"]
  }
}

raise_attention writes yellow/green non-blocking Attention. A later green item with the same run and dedupe_key resolves the visible yellow item:

{
  "run_id": "run_123",
  "actor_id": "agent-a",
  "actor_role": "agent",
  "client_update_id": "attention-4",
  "level": "yellow",
  "target": "human",
  "dedupe_key": "review-api",
  "reason_code": "review_soon",
  "why_now": "The API surface is ready",
  "recommended_action": "Review in the next digest",
  "source_event_ids": []
}

request_intervention remains the red/blocking path and may include a Decision Packet. It moves the run to awaiting_human; use it only when work cannot safely continue without a response:

{
  "run_id": "run_123",
  "actor_id": "agent-a",
  "actor_role": "agent",
  "prompt": "Choose the rollout policy",
  "intervention_kind": "decision_required",
  "decision_packet": {"options": ["canary", "all-at-once"], "recommended": "canary"}
}

get_human_brief and get_attention_board reconstruct the latest projections from the event ledger. The dashboard exposes the same read-only projections:

GET /api/runs/run_123/brief
GET /api/attention?team_id=<team_id>&target=human&include_green=false

include_green=true includes resolved green items in items; counts always cover red, yellow, and green items for the selected target.

Acceptance contracts

create_acceptance_contract, add_invariant, bind_assignment_to_contract, seal_contract, report_verification, evaluate_contract, accept_contract, reject_contract, raise_deviation, waive_deviation, reopen_contract, get_contract_detail, list_contracts.

See concepts for how the three gates fit together.