Send an agent's decision to the right reviewer

A tool that needs a decision declares who takes it. The person whose conversation raised it, one named person, or anyone holding a role in the organization. The pause writes the route with the decision, the reviewer finds it in an inbox read from the server, and the answer releases the action under the authority of whoever asked for it.

The problem it solves

A pause only helps when the person who can decide sees it. When the only possible approver is the person talking to the agent, the requester approves their own action, which is not a review. A firm needs the decision to reach someone qualified to take it, and needs the requester kept out of that decision.

The second half is authority. A reviewer usually holds wider rights than the requester. If the approved action ran as the reviewer, approving would become a way to act beyond what the requester may do.

What it does

Three routes. An owner route goes back to the person whose turn raised the decision. A role route goes to anyone holding the declared role in the decision’s organization, except the requester. An assignee route goes to the one person a declared resolver names from the call’s arguments, who must hold the role.

A pending decision can be acted on, not only answered. A holder of the role can claim it and give it back. An answerer can reassign it, and an organization administrator can take it over. It can be escalated to a declared target. Every move is checked against the same eligible role, so nobody can hand a decision to someone the gate would not have admitted.

The inbox is the server’s answer, not the screen’s. Each person sees only the decisions they may act on. A person who may not act on one gets the same answer as for a decision that does not exist, so the inbox does not reveal work the person cannot touch.

The answer decides whether the action runs, not whose rights it uses. The action runs under the requester’s authority, which is checked again when the answer arrives. If that authority has gone in the meantime, the outcome is recorded as such and nothing runs. The outcomes are kept distinct: accepted, accepted with modifications (the changed arguments recorded by name only), rejected, lapsed, withdrawn, and requester authority lapsed.

What you decide

Declare humanApproval on the tool with its route and eligible role, and optionally an assignee resolver and an escalation target. A declaration nobody could answer, such as a role route with no role, stops the application at startup. Place the inbox component where reviewers work.

Wonder Todos routes the assistant’s deletion of a todo to the organization’s administrators. Selected from delete-todo-tool.ts; the description, input schema and execute function are omitted.

export const deleteTodoTool: FunctionTool = {
  functionRef: DELETE_TODO_TOOL_REF,
  // …
  /*
   * Routed to a ROLE: any administrator of the conversation's organization may answer, except the member
   * who asked. `ORG_ADMIN` is met by an owner too, through the organization role hierarchy. No
   * `escalateTo`: nobody ranks above an organization's administrators within it, so escalation is not
   * offered on this decision.
   */
  humanApproval: {
    route: HumanDecision_RouteKind.ROLE,
    eligibleRole: CORE_ORG_ROLES.ORG_ADMIN,
  },
  // …
};

The ROLE route sends the decision to anyone holding ORG_ADMIN in the conversation’s organization, and the member who asked cannot answer it. The gate declares no escalateTo, so this decision offers no escalation.

Limits

A role or assignee route needs an organization. A decision with none is refused at the pause and the call is denied.

A decision concerns one proposed call. Approving it does not approve later calls of the same tool.