Agent claims and human handoffs

An agent claim is a vendor-neutral, expiring execution lease on one task. It answers “which connection is actively working on this?” without replacing the human assignee or changing task status.

The normal recipe is:

1. Read the project brief or bounded Context once.
2. Preview one project's eligible queue, or atomically claim the next task when the agent is allowed to select work.
3. Claim a known task with one opaque run ID, or use a unique opaque run ID for the claim-next operation; leases range from 60 seconds to one hour (15 minutes by default).
4. Move the task to the appropriate active status when implementation begins.
5. Renew the lease while work continues; use Waiting when execution pauses for an external dependency.
6. Leave concise Markdown comments for durable decisions, blockers, verification, and handoff evidence.
7. Finish the Agent Run and release the claim after you record the result. Complete the ticket only after the requested result is verified and the right person has accepted it.

A live conflicting claim identifies the owning connection. An expired claim may be taken over. Routine heartbeats do not create noisy activity, while meaningful claim and release changes remain attributable.

For a human handoff, the agent should state what changed, what was verified, any remaining risk, and the exact next action. Source-control links or IDs are useful evidence; raw command logs and secrets are not. If another tracked task concretely blocks progress, record that task relationship instead of only mentioning it in prose.

Current ToDoddle provides a bounded cross-project operational queue, project-scoped eligible-work discovery, atomic claim-next, known-task claims, explicit renew/release operations, durable Agent Run history, durable Agent assignment, and inbox delivery for replies, mentions, reviews, handoffs, and assignments. Human assignment and task status stay independent from agent selection.

Use Air Traffic to see working, waiting, attention-needed, and available agent work for the selected workspace. Use the peer Recently Finished tab for released work and Context Questions for assigned or overdue project questions. These queues describe claims and work state; they do not change ticket status. A project writer can release a stale or unwanted claim after confirmation.

Each claim creates or resumes one durable Agent Run. A run can finish as succeeded, failed, cancelled, or abandoned and can store safe references to commits, pull requests, deployments, tests, documents, comments, Context, or attachments. It must not store secrets, full transcripts, prompts, or expiring URLs. Finishing a run releases its claim but does not complete the ticket.

An agent acting for the ticket creator may complete verified work. When another person created the ticket, ask that creator or a named reviewer to accept the result before completion, unless an approved ticket or project rule delegates that decision. Agent Run success is not acceptance.

Open Supervision on a ticket to see recorded assessments and attention signals, such as a requested human review or a blocked ticket. Expand an assessment to see its recorded evidence. Assessments help a person review the work. They do not approve a review or complete the ticket.

Optional roles and capabilities

An Agent Connection can list roles such as implementer or reviewer. It can also list capabilities such as frontend, testing, or documentation. These labels describe the connection. They do not grant API scopes or project access.

A project owner can configure queue rules in Project settings → Agent queue. Preferred capabilities and advisory roles do not block work. Required capabilities and enforced roles do block discovery, claims, renewals, and Agent Run access when the connection does not match. Leave all fields empty to keep the shared queue behavior.

The same settings page has optional queue recipes. Every recipe is off by default. A project owner can request a testing handoff after a successful run, move unchanged work to review after required evidence arrives, or request rework after a failed run. These recipes never complete or approve work. Agent Run history shows the trigger, effects, skips, warnings, and connection attribution. Turn off a recipe to disable it.

Evidence-gated recipes require every selected evidence type. A missing type causes a visible skip. The move-to-review recipe uses the ticket revision captured when the run began. It fails safely if a person or another agent changed the ticket during the run.

ToDoddle always checks API scopes, project grants, and the authorizing user's current access before it checks queue rules. A broad credential cannot bypass a narrower enforced queue rule.

For Codex, project-scoped custom agents can live in .codex/agents/*.toml. Map the TOML name to a ToDoddle role. Map the work named in description and developer_instructions to capabilities. For example, a reviewer agent can use the reviewer role with testing and security-review capabilities. Keep the same role and capability names on its dedicated Agent Connection. See the official Codex subagent guide.