Examples

These show the shape of the tool calls. Argument names match the MCP tools; every mutating call carries the current base_revision.

Assignment loop (create → claim → handoff → accept)

# Integrator sets up identities and a task
register_actor(actor_id="alice", actor_kind="human", display_name="Alice")
register_actor(actor_id="builder-1", actor_kind="ai", display_name="Builder")
register_workspace(workspace_id="proj", repo_root="/abs/proj", default_branch="main")
create_team(team_id="core", workspace_id="proj", name="Core", owner_actor_id="alice")
create_assignment(
    assignment_id="task-1", title="Add rate limiting",
    actor_id="alice", actor_role="integrator", base_revision=0,
    team_id="core", workspace_id="proj",
    acceptance_criteria=["unit tests pass", "p95 latency < 200ms"],
)

# Agent does the work
claim_assignment(assignment_id="task-1", actor_id="builder-1",
                 actor_role="agent", base_revision=1, branch="feat/ratelimit")
append_event(assignment_id="task-1", event_type="progress", status="observed",
             actor_id="builder-1", actor_role="agent", base_revision=2,
             payload={"summary": "added token bucket"})
submit_handoff(assignment_id="task-1", actor_id="builder-1", actor_role="agent",
               base_revision=3, payload={"summary": "done", "evidence": {...}})
# -> event status: completed_gate_passed  (NOT accepted yet)

# Integrator reviews
list_pending_reviews()
accept_event(event_id="evt_...", actor_id="alice", actor_role="integrator",
             base_revision=4, decision_note="criteria verified")
# -> status: integrator_accepted  (now it is accepted truth)

If a write returns a stale-revision error, re-read with get_assignment_detail and retry with the new base_revision.

Acceptance contract (goal-level)

create_acceptance_contract(contract_id="c1", goal_statement="Login is rate-limited",
                           actor_id="alice", actor_role="integrator", ...)
add_invariant(contract_id="c1", probe_kind="command",
              probe_spec={"ref": "probes/tests.sh"}, ...)        # positive test
add_invariant(contract_id="c1", probe_kind="http", is_negative=True, ...)  # deny test
add_invariant(contract_id="c1", is_second_instance=True, ...)   # second-instance test
seal_contract(contract_id="c1", ...)        # refuses without deny + second-instance
report_verification(contract_id="c1", invariant_key="...", outcome="passed", ...)
evaluate_contract(contract_id="c1", ...)    # all green + no blocker -> awaiting_acceptor
accept_contract(contract_id="c1", ...)      # independent acceptor signs off

A runner bound to the contract cannot evaluate or accept it — sign-off is independent by construction. See concepts for the full model.

Keep a human informed without stopping the run

After a meaningful run event, the owning agent can refresh the latest human Brief. source_event_sequence points back to the event the summary describes; the write is idempotent through client_update_id and does not change run status.

checkpoint_run(
    run_id="run_123", actor_id="builder-1", actor_role="agent",
    client_update_id="brief-7", source_event_sequence=42,
    brief={
        "schema_version": 1,
        "current_goal": "Add rate limiting",
        "current_stage": "verifying",
        "recent_progress": ["Load tests pass"],
        "decisions_and_risks": ["Canary rollout still needs review"],
        "human_intervention": {"needed": false, "blocking": false},
        "next_steps": ["Review canary metrics"],
        "context_refs": ["docs/rate-limit-plan.md"]
    },
)

Use yellow Attention when work can continue but a person should know. Resolve the same issue with a later green item using the same dedupe_key:

raise_attention(
    run_id="run_123", actor_id="builder-1", actor_role="agent",
    client_update_id="attention-1", level="yellow", target="human",
    dedupe_key="canary-review", reason_code="review_soon",
    why_now="Canary metrics are available",
    recommended_action="Review in the next digest", source_event_ids=[]
)
raise_attention(..., client_update_id="attention-2", level="green",
                dedupe_key="canary-review", reason_code="review_complete", ...)

If progress cannot safely continue, call request_intervention instead. That is the red path and may include a Decision Packet. Read the current human views with get_human_brief(run_id="run_123") and get_attention_board(team_id="core", target="human").