coordinate-agent-work

Coordinate Agent Work

Use the journal as a compact coordination record. Keep the host responsible for spawning, steering, waking, reconnecting, waiting for, and stopping agents.

DEVELOPMENT BUILD 0.5.1-dev.0 (unreleased): 33 local MCP tools, including collab_events_wait, plus the unreleased host doorbell wait between turns. Collab 0.5.0 is released on GitHub only, not on npm; the next npm candidate is 0.5.1. This source does not establish publication; verify the protected receipt and registry separately. Published npm 0.4.0 has 32 tools and does not gain this wait from these source edits. One MCP process has one bound session; independent child attribution needs independent MCP processes. Preserve native dispatcher, persona, memory, permissions and lifecycle in Claude, Codex, Hermes and OpenClaw. Connection or arrival does not prove that a model read feedback, consented, or acted.

The ordinary loop

Most sessions need only this loop. Read the applicable repository instructions and inspect existing work first.

1. Start. Call collab_session_start once per independent agent process or conversation, with the repository root_path, an actor label, an optional free-text role, and, for a delegated child, parent_session_id. It opens the workspace, creates a credential-bound session and binds this MCP process. Never open or read the credential file.
2. Poll and acknowledge. Call collab_next at the start of each turn, after local work, before relying on shared state, and whenever the host wakes you. Process one page, then call collab_cursor_ack with its exact terminal next_anchor ({ epoch_id, sequence, hash }); poll again while has_more is true. Handle your own entries in recovery_required first.
3. Split and claim. Create bounded coordination, read_only, or edit tasks with collab_task_create: dependencies, completion tests in the description, and conservative repository-relative path_scopes. Inspect claimable and conflicted projections; dependency-ready is not the same as safely claimable. Call collab_task_claim with the version just read and begin edits only after it succeeds.
4. Work. Stay within the task, path, data and external-action scope. Renew with collab_task_renew before the lease expires and post compact collab_task_progress. On a version or claim conflict, poll and re-read instead of forcing a mutation.
5. Attach. Call collab_artifact_attach for each file, commit, test, data or URL reference. For a file, use its repository-relative path inside the task's path scopes as uri and the SHA-256 of the bytes you wrote as sha256. Do not paste content or raw output.
6. Complete. Call collab_task_complete with a summary, confidence, confidence_basis, limits and evidence_refs. Optionally name review_requested_session_id. An edit task stays pending until a distinct session accepts it.
7. Review. For someone else's completed task, inspect its artifacts, checkpoint drift and completion tests, then call collab_task_review with accept or request_changes, a summary, evidence, and your own confidence, confidence_basis and limits. A late reviewer concurs or disagrees by report.
8. End. Call collab_session_end with a reason, release_leases: true and an optional release_summary when this session will not resume.