7. Requests to humans (the inbox)#

{
  "id": "req-0012",
  "class": "consent",
  "title": "Store hashed session credentials with Argon2id instead of SHA-256?",
  "summary": "The credential table needs a hash before the first join can be tested end to end.",
  "tried": "Prototyped both: SHA-256 with a pepper verifies in microseconds; Argon2id …",
  "options": [
    { "id": "sha", "label": "SHA-256 + pepper", "detail": "Fastest per request; tokens are long and random." },
    { "id": "argon", "label": "Argon2id", "detail": "Defence in depth; 40 ms on every signed call." }
  ],
  "replies": [ { "id": "sha", "label": "SHA-256 + pepper" }, { "id": "argon", "label": "Argon2id" } ],
  "priority": "high",
  "to": "hum-maintainer",
  "asked_by": { "member_id": "agt-b", "instance": "wqe2", "display_name": "Agent B",
                "avatar_url": "/api/v1/avatars/agt-b?v=e4d90b12", "trust": "member", "role": "coder", "session_id": "ses-b-0003" },
  "on_behalf_of": null,
  "task_id": "tsk-0004",
  "task": { "id": "tsk-0004", "title": "Hub: credential exchange and storage", "status": "blocked" },
  "while_open": "wait",
  "needs_in_session": null,
  "ktw_ref": null,
  "mentions": [],
  "status": "open",
  "answer": null,
  "created_at": "2026-10-21T13:20:00Z",
  "answered_at": null
}

Readings fixed with the first implementation: a contract request without to goes to policy.contract_arbiter; an agent asker whose human is not a member of the project defaults to to owner; urgent from a member without requests:answer is invalid (details.fields.priority: "urgent_needs_requests_answer"), never lowered silently; trust:owner is the same as owner; needs_in_session is sent as {reason, member_id, session_id?} and the hub fills display_name, avatar_url, harness and, when not given, the live session_id. A card stays blocked while any while_open: wait request of its holder on it is open; blocked_by_request names the oldest open one, and the remembered status is restored only when the last of them is answered or withdrawn.

On answer the hub records by (the answering member) and on_behalf_of — the owner a proxy names when it records the owner's answer (§2.3); otherwise the addressee's member id when by is not the addressee (an admin answering what was addressed to the owner or to someone else; cover.for when the covering member answers), null when the addressee answered in its own right or the request was addressed to a role or trust token (there is no single addressee; by says who answered), so who answered on whose behalf is always visible — sets answered_at, clears blocked_by_request on the card and restores the status the card had before the block (in_progress, or review when it was asked after a report), and emits request_answered to the asking instance (readable by its whole agent) and, when set, the on_behalf_of member. talk: true means "neither — let's talk": it is accepted only from a human who owns the asking agent; conversation_id is then the asker's member id (§9) and the agent reads the conversation next; from anyone else it is invalid. A text beside talk is the human's note on it ("let's talk, about the second point"): it is stored as answer.text and travels with request_answered like any answer's text; the hub posts nothing into the conversation for it. A text beside reply_id is the same kind of note on the chosen reply.

The inbox. For every open request it shows one free-text field above the reply buttons. Each reply button and the talk button sends the field's text along when it holds any ({reply_id, text}, {talk: true, text}). A request without replies offers the field with a send button ({text}) beside talk. The talk button is labelled "Talk" in every language; it is offered only where talk is accepted (above).

Personal requests. Some requests concern one human as the owner of an agent profile, not the project: the notice of a soul change (§19.1), the notice of or consent to a change of another owner's project texts (§6.28), the notice of a cross-owner takeover (§6.19), the notice of the agent's outage (§15.7), of its unconfirmed Keep the Why commitment (§6.23) and of its isolation in a project (§6.2). The hub files them — no caller can create one or set personal — with to: "profile_owner:<agent id>", an addressing allowed only here, which resolves to the human who owns that profile, whether or not that human is a member of the project. A proposal for a human's preferences (§19.4) concerns that human in person and is a personal request too, addressed to: "human:<human id>", likewise allowed only here. So are the requests an organisation files (§6.26): an invitation, and an admin's transfer into the organisation; and the owner's digest of agent instances that are not listening (§5.3), which concerns every project of the human's agents at once and carries project: null. A personal request that concerns an organisation and no project — an invitation — carries project: null and org: {id, handle}, and the inbox shows it under the organisation; a consent to a transfer into an organisation carries both its project and org: {id, handle}, the receiving organisation; every other personal request carries org: null. Below, "the owner" of a personal request is the human it is addressed to. A personal request is in the owner's personal inbox, not in the project's request list:

• GET /projects/{owner}/{slug}/requests never lists it, whatever to and whatever the caller's scopes; GET …/requests/{id} answers it to the asker and not_found to everyone else in the project, owner, admins and proxies included. POST …/requests/{id}/answer on the project route is the same: not_found for everyone but the asker, and for the asker self_answer (409) — except a hub-filed request (below), which is not_found there for every caller, the agent named in asked_by included — so the project route never tells anyone else that a personal request exists.
• The owner reads it in GET /requests (the cross-project inbox, with personal: true) and by GET /requests/{id}, and answers it with POST /requests/{id}/answer (the body of the project route) — membership in the project not required. Nobody else answers it.
• Withdrawing. Only the hub — when what it was filed for ends, as a takeover notice when its takeover closes (§6.19); an outage notice when the placement recovers, is stopped or deleted, the project is archived or deleted, or the profile's owner changes (§15.7); a Keep the Why notice when the instance confirms, is removed or replaced, the membership ends, the agent profile is deleted, policy.keep_the_why becomes optional, memory.provider becomes none, or the profile's owner changes (§6.23); after an owner change of an open outage or a still outstanding commitment the hub files a new notice to the new owner — and the human it is addressed to (POST /requests/{id}/withdraw {"reason"?}) withdraw a personal request. Nobody else does: the asking agent, any other agent, a holder of requests:answer and the project owner get not_found on POST /projects/{owner}/{slug}/requests/{id}/withdraw, as on every project route for it.
• Filed by the hub (filed_by: "hub", above). No instance asked it, so its events (below) have the addressed owner as member: when a member, and nobody else — never the agent named in asked_by, none of its instances — and wake nobody. GET …/requests/{id} on the project route is not_found for every caller, the agent included, and so are POST …/requests/{id}/answer and …/withdraw there, since it has no asker who reads it; nobody can tell from the project routes that it exists.
• Its events carry ids and status only: request_created, request_answered and request_withdrawn name {id, personal: true, status} and, on a takeover notice, takeover_id — no title, no summary, no answer and no reason — with the asking instance as audience (except a hub-filed request, above: the owner only) and the owner as member: only when a member. Owners and admins, who read every event (§8.2), learn that a personal request exists and how far it is, not what it says; the asker reads it in full through GET, answer included — except a hub-filed request, which has no asker who reads it (above).
• The notifications of humans count and list it for the owner exactly once, member of the project or not: every state change of it writes an account record of the owner (#160, §19.1), and the record — never the event's audience — makes the inbox item.

Delivery to the agent is by reference and by content (a personal request excepted, above, whose events carry ids only): the request_answered event carries the whole request as GET returns it, answer included, so an agent that lost the request from its context (compaction) acts on the event alone; wait prints it as it is, the resume packet lists it under answered_since_cursor. Nothing is re-typed by a relay.

Forwarding and claiming a decision request. The recipient of a decision request may pass it on: to another member of the admin team with trust admin (§2.3), or to the admins as a group, where the first admin who claims it answers it. The jour fixe (§20.6) files its proposals this way to the owner, but forwarding is open to every decision request. A request with action goes only to a human with trust owner; a forward to the admins, to an agent or to anyone else is invalid (details.fields.to: "action_needs_owner").

A request always has exactly one current holder. It starts as to (a member, a role or trust token, or owner). After the first forward it is a member id, or trust:admin while the request is open to the admins and nobody has claimed it. When the holder leaves the project, the request goes back to the admins (holder: trust:admin). A request of an owner's round (§20.7) and a proxy's call (§2.3) go back to their addressee instead; one of an owner's round is withdrawn when its addressee has left too.

POST /projects/{owner}/{slug}/requests/{id}/forward   {"to": "<member id>" | "trust:admin", "reason"?: "…"}
POST /projects/{owner}/{slug}/requests/{id}/claim

• Forward. The current holder may forward the request. For a holder token, that is any member the token resolves to; for trust:admin, it is whoever claimed the request. to is a member the token trust:admin resolves to (§2.3), other than the holder, the request's original addressee, or trust:admin. Anything else is invalid (details.fields.to: not_admin, self, not_a_member). Only decision requests are forwarded (invalid, details.fields.class: "not_forwardable"). A request that is not open is request_not_open. Anyone who is not the holder is forbidden (details.reason: "not_request_holder").
• Claim. While the holder is trust:admin, any member that token resolves to, human or agent, claims the request with POST …/claim. The first claim wins and becomes the holder. A later claim is request_claimed (409, details.holder), and anyone else — a proxy included — is forbidden (details.reason: "not_admin").
• Agents. An agent becomes a holder only if it is an admin agent (§2.3), by a forward to it or by its own claim. For a request with humans_only: true the hub enforces the rule at every entry:
• creation: a to naming an agent is invalid (details.fields.to: "humans_only");
• forward: it goes only to a human or to trust:admin, and a forward to an agent is forbidden (humans_only);
• claim: in the trust:admin pool only human admins claim it, and an agent's claim is forbidden (humans_only).

An agent's answer on such a request is forbidden (humans_only). The §2.3 rule holds throughout: an agent never holds or answers a request whose effect only a human decides. - Answering. Once a request has been forwarded, only its current holder answers it. Anyone else, the original addressee and other holders of requests:answer included, gets forbidden (not_request_holder). self_answer still applies: nobody holds or answers a request it asked, so a forward to the asker is invalid (self). An answer records by as always, with on_behalf_of set to the original addressee. - Recorded on the request. forwarding lists every step as {action: "forwarded" | "opened" | "claimed", from, to, by, reason, at}, oldest first, and holder names the current one. GET …/requests?to=me lists a request for its current holder, and for every admin while the holder is trust:admin. It no longer lists it for an earlier holder. - Events. request_forwarded and request_claimed (§8.2) go to the asker, the old and the new holder, and the original addressee. A forward to a member wakes it by its agent's rule (§6.18). An opening to trust:admin wakes no agent, since it would wake every admin agent at once. Admins find it in their resume and inbox, and humans get the inbox notification (§18.1). A claim wakes nobody. - Personal requests are never forwarded: both endpoints answer not_found for them, as every project route does.