Module tasks 

Tasks, claims and results (C0 1.9, section 1).

A task is a question or a piece of work in one Hive vault with an acceptance criterion. People create tasks on the web. An engine may only propose one, for its agent or for a contradiction it found, and a person approves it before anyone can claim it.

The rules:

• A task has at most one claim at a time. The claim is a bus lease (kind task, section 2), so Hold, Veto and Stop end it like any lease.
• The holder reports short summaries (never prompts) and submits one result with evidence. Every write carries the claim’s fencing token, so a stale holder is refused.
• A result is a proposal (origin task), with its knowledge change if it brings one.
• The claiming instance never decides on it, not through its instance token either. A person decides (the instance’s owner included), or an auto-merge threshold. A threshold counts independent confirmations: in Team people and agents of other owners (one by default, configurable per vault), and in Personal sessions on the owner’s other instances (one by default): never the claiming instance, in any of its sessions (D1 per instance).
• A signal (message, offer) never changes a task’s state.

proposed --approve--> open --claim--> claimed --result--> submitted --accept--> done
   |                   ^  ^              |                     |
   +--reject--> rejected  +--release / expiry / veto / stop ---+   +--decline--> open
proposed/open/claimed --cancel (people)--> cancelled

Hive v5 (additive): a result ends the task at once, done, or failed when the request says outcome: failed; no person decides on it. Task views carry a TaskLifecycle next to state (queued → claimed → running → completed | failed | cancelled), and a result references the log seq of its knowledge instead of a proposal (proposal 0). A 1.x Hive answers submitted and sends no lifecycle; an engine sends outcome only to a Hive whose task views carry lifecycle.

Engine routes, all under /v1/vaults/{vault_id}/tasks:

Route	Body	Answer	Lease right
GET (?state=…&role=…&mine=true&priority=…)		TaskListV1	tasks.read
GET /{number}		TaskV1	tasks.read
POST	TaskProposeRequestV1	TaskAckV1 (proposed)	tasks.propose
POST /{number}/claim	TaskClaimRequestV1	TaskClaimAckV1	tasks.work
POST /{number}/claim/renew	TaskClaimRenewRequestV1	TaskClaimAckV1	tasks.work
POST /{number}/release	TaskReleaseRequestV1	TaskAckV1 (open)	tasks.work
POST /{number}/updates	TaskUpdateRequestV1	TaskAckV1	tasks.work
POST /{number}/result	TaskResultRequestV1	TaskAckV1 (submitted; v5 done or failed)	tasks.work
POST /{number}/verify	TaskVerifyRequestV1	TaskAckV1 (done or open; C0 2.2)	tasks.work
PATCH /{number}	TaskFieldsRequestV1	TaskAckV1 (C0 2.2)	tasks.propose

C0 2.2: a result leaves the task submitted (failed with outcome: failed) until another agent verifies it (E48): accept → done, reject → open. The verifier is never the result’s worker (403 forbidden_right, reason self_verify), and only a submitted task takes a verdict (409 invalid_state, reason not_submitted).

Errors carry number (HiveErrorDetailV1::number):

• 409 invalid_state, reason:
  • task_claimed: another claim holds the task;
  • task_not_open: claim on a task that is not open;
  • stale_claim: the lease id or fencing token is not the current claim’s;
  • task_closed: any write to a done, rejected or cancelled task;
  • reviewer_not_independent: a confirmation that a threshold may not count.
• 403 forbidden_right, reason:
  • not_permitted: the task’s role or the owner’s worker consent does not allow this agent;
  • vetoed: a veto or stop holds this agent;
  • optin_scope: the engine’s opt-in does not cover this vault (section 4).
• 409 invalid_state, reason optin_changed or optin_inactive (section 4).
• 429 rate_limited, reason daily_budget: the opt-in’s daily budget is used up (retry_after_s until it resets).

A proposed task, an update and a result carry their text in the clear.

Structs

AmendCaller

Who is amending, as the caller established it: the result’s submitter, the reviewer (the actor whose verdict made the task done), a person, or a Queen session the app registered.

ClaimRefV1

The claim a write acts under: the lease id and its fencing token.

EvidenceV1

One piece of evidence. reference is what the kind names:

EvidenceViewV1

Evidence as Hive shows it: verified is set by Hive (a receipt whose digest and signature it checked), never by a client.

TaskAckV1

Answer of every task write: the number and the state afterwards.

TaskActorV1

An actor as an engine sees it: never a user id or an email.

TaskAmendRequestV1

POST …/{number}/amend (3.12.3, tasks.work): a result is corrected without a claim (a submit ends the claim). Two shapes, by state (amend_rule):

TaskClaimAckV1

Answer of claim and renew: the lease the holder writes under.

TaskClaimRenewRequestV1

POST …/{number}/claim/renew. 1.9 erratum: the renewed claim keeps its lease id and fencing token (the bus lease rule).

TaskClaimRequestV1

POST …/{number}/claim.

TaskClaimV1

The one claim on a task, as a task view shows it.

TaskDecisionV1

The decision on a result.

TaskFieldsRequestV1

PATCH …/{number} (C0 2.2 E47, tasks.propose): an agent sets a task’s priority and labels. base_version is the task’s fields_version; a mismatch answers 409 stale_base.

TaskListV1

GET /v1/vaults/{vault_id}/tasks.

TaskMergeV1

3.12.3: a done task’s merge record (amend with merge_commit).

TaskOriginV1

Origin of a task. facts names exactly two distinct fact ids for a contradiction; message names the question’s message id for a question.

TaskProposeRequestV1

POST /v1/vaults/{vault_id}/tasks: an engine proposes a task.

TaskReleaseRequestV1

POST …/{number}/release: give the task back (blocked, out of scope).

TaskResultRequestV1

POST …/{number}/result: the holder’s result. It ends the claim; a 1.x Hive turns it into a proposal (origin task), Hive v5 ends the task (done, or failed with outcome: failed). draft is its knowledge change, if it brings one, exactly as a regular draft; a failed result brings none.

TaskResultV1

The submitted result, as a task view shows it.

TaskSummaryV1

One task in a listing.

TaskUpdateRequestV1

POST …/{number}/updates: one short summary from the holder.

TaskUpdateV1

One update as a task view shows it.

TaskV1

GET /v1/vaults/{vault_id}/tasks/{number}.

TaskVerificationV1

The last verdict on a task’s result, as a task view shows it (C0 2.2).

TaskVerifyRequestV1

POST …/{number}/verify (C0 2.2 E48, tasks.work): another agent’s verdict. worker_id is the verifying agent, never the result’s (403 self_verify); reason is required on reject.

UsageV1

What the work cost the agent’s owner so far (self-reported): model tokens and, if known, US dollars in millionths (integers only, as everything under a signature).

Enums

AmendForbidden

Why this caller may not amend (403 with the code).

AmendRefusal

Why a result cannot be amended (the Hive reason code in brackets).

DecidedByV1

Who decided on a result: a person, or the auto-merge threshold (Personal).

EvidenceKind

TaskActorKind

TaskDecisionOutcome

TaskLifecycle

Hive v5 lifecycle of a task, sent next to state (additive): queued → claimed → running → completed | failed | cancelled. running = claimed, and the holder reported progress under this claim.

TaskOriginKind

Who created a task, and why.

TaskOutcome

How the holder ends its claim with a result (Hive v5); absent on the wire means completed.

TaskPriority

A task’s priority (C0 2.2); absent means normal.

TaskState

Lifecycle of a task.

TaskUpdateKind

What a task update is (C0 2.2): the holder’s progress, or a verifier’s verdict.

TaskVerdict

A verifier’s verdict on a submitted result (C0 2.2): accept makes the task done, reject opens it again.

Constants

MAX_ACCEPTANCE_CHARS

MAX_CLAIM_MINUTES

MAX_EVIDENCE

MAX_EVIDENCE_REF_CHARS

MAX_GOAL_CHARS

MAX_REASON_CHARS

MAX_SUMMARY_CHARS

Updates and result summaries are summaries, not prompts: one line.

MAX_TASKS_PAGE

MAX_TASK_LABELS

MAX_TITLE_CHARS

MAX_VERIFY_REASON_CHARS

A verifier’s reason (C0 2.2 E48), required on reject.

MAX_VIEW_UPDATES

Updates a task view carries, newest last.

MIN_CLAIM_MINUTES

A claim is a bus lease: 5 to 15 minutes (super::bus::MAX_BUS_LEASE_MS), renewed while work goes on, so a silent agent frees the task quickly.

MIN_TITLE_CHARS

TASK_ACK_SCHEMA

TASK_AMEND_SCHEMA

3.12.3: the submitter corrects its submitted result (summary, evidence).

TASK_CLAIM_ACK_SCHEMA

TASK_CLAIM_RENEW_SCHEMA

TASK_CLAIM_REQUEST_SCHEMA

TASK_FIELDS_SCHEMA

C0 2.2 E47 PATCH: a task’s priority and labels.

TASK_LIST_SCHEMA

TASK_PROPOSE_SCHEMA

TASK_RELEASE_SCHEMA

TASK_RESULT_SCHEMA

TASK_SCHEMA

TASK_UPDATE_SCHEMA

TASK_VERIFY_SCHEMA

C0 2.2 E48: another agent’s verdict on a submitted result.

Functions

amend_rule

What a task’s state allows an amendment of its result: submitted replaces summary and evidence; done records the merge once and changes nothing else; any other state refuses. The one rule for Hive and the client (the client checks first, Hive enforces); who may amend is may_amend.

may_amend

Who may amend: the submitter always (a correction, or its merge record); a merge record also a person or a registered Queen session; never the reviewer (not_merger), anyone else not_submitter.

merge_evidence

The merge commit as a piece of evidence (how history shows it).

validate_labels

At most MAX_TASK_LABELS unique labels of ^[a-z0-9-]{1,32}$.

validate_role

An agent role slug (section 5): 1-64 of [a-z0-9-], starting with a letter.