Skip to main content
Human attention pauses one agent execution at needs_human and records the information a human needs to act. The request and execution transition are atomic. Generic execution transitions cannot enter or leave needs_human.

​
Endpoints

Create requests require an execution ID, expected execution state version, kind, bounded text fields, one exact target, and an idempotency key. Targets are a member, team, or project administrators. Resolve, cancel, and retarget requests include both expected versions. Reuse of an idempotency key with the same input returns the original result; a different input returns 409.

​
Lifecycle

The create operation moves the execution to needs_human and creates one open attention item. Resolve and cancel close the item and move the execution to waiting. Approval and destructive-action items accept approved or rejected; access items accept provided or denied; clarification, decision, and other items require an answered outcome with a summary. mode=recovery lists open items whose original target is no longer eligible and is available only to authorized human administrators. Stale versions, invalid lifecycle edges, and ineligible targets return stable 409 errors. Request text is bounded and rejects secret-like content. Public responses contain current and immutable actor/target snapshots, execution state, issue, and project context. They omit provenance, hashes, prompts, logs, credentials, and local paths. See the endpoint reference and field reference for the complete REST contract.

​
Typed MCP requester tools

The full/private and public plugin MCP profiles expose atoll_list_attention, atoll_get_attention, atoll_create_attention, atoll_cancel_attention, and atoll_ack_attention. These tools use the same REST authorization and lifecycle checks. The list tool returns the relevant requester view only. Create accepts one exact target and atomically moves an eligible execution to needs_human. The requester can cancel an open request with both observed versions or acknowledge a resolved receipt with its exact close versions. MCP does not resolve requests for humans, expose administrator retarget/cancel or recovery filters, or resume an execution. Public calls require the selected connection-scoped profile_ref on actor-dependent requests. Transport failures and HTTP 5xx responses on MCP lifecycle writes return lifecycle_write_uncertain with readback guidance; they do not trigger an automatic retry.

​
Requester receipt acknowledgement

When a human resolves an item, private heartbeat creates one requester-scoped receipt. The resolved answer stays in the requester’s execution_attention queue until the requester consumes it. Use the exact attention version and execution_state_version_at_close from the heartbeat item:
Only the live requesting agent with current issue/project read access can acknowledge the receipt. Same-key and same-body retries return the stored response. A reused key with a different body returns a stable conflict. Stale attention or close-state versions always return a stable conflict, including after another acknowledgement or resume has consumed the receipt. A request with the current versions after another consumer returns already_consumed: true; it does not consume the receipt again. Acknowledgement changes the receipt only. It does not resume the execution; a separate exact waiting -> running transition is required. Human and administrator resolution does not consume the receipt.