# Human Escalation

Escalate blockers, decisions, and status updates to a human, either as an in-session message or as an external email.

## When to use

- A task is blocked on missing access, an approval, or information only a human has.
- An API call fails with 401/403 (unauthorized/forbidden) and no Integration row exists for the required service.
- A change requires PATCH/PUT/DELETE on a SaaS record, which no available tool can perform.
- You need to notify or ask a human, or an external recipient, before proceeding further.

## Tools

- `send-message`: notify or ask a human, or another agent, in-session about a blocker, decision, or status update.
- `send-email`: send a message to a human or external recipient outside the session, for example a summary, an approval request, or a heads-up.

## Playbook

1. Confirm the escalation is real: you have hit a blocker (missing Integration, ambiguous instruction, required approval, or an unsupported PATCH/PUT/DELETE change) that you cannot resolve with the tools available to you.
2. Write down, in plain language, what happened, what you tried, and exactly what decision or action you need from the human.
3. If the recipient is in-session (the requester, an orchestrator, or another agent on the board), send the summary via `send-message`.
4. If the recipient is external or not present in the session, send the summary via `send-email`, including a clear subject line and next-step ask.
5. If the blocker is a missing Integration for a SaaS host, name the exact service and the required scopes in your message so the human can create it.
6. If the blocker is an unsupported update operation (PATCH/PUT/DELETE), compile the exact list of proposed changes into the message body so the human can apply them manually — never claim the change was made.
7. State a clear deadline or urgency level in the message when the blocker is time-sensitive, so the human can prioritize.
8. Wait for a reply or confirmation before resuming dependent work; do not silently proceed as if the escalation was resolved.
9. Once a response arrives, note the outcome and continue the original task, or hand it off if it remains blocked.

## Failure modes

- 401/403 (unauthorized/forbidden) on a SaaS call -> missing Integration row; escalate via `send-message`, naming the service and scopes needed.
- Empty or unexpected result from an escalation-adjacent lookup -> verify the endpoint and parameters before assuming a human is required.
- Rate limit hit while gathering context for the escalation -> back off, retry later, and note the delay in your `send-message` or `send-email`.
- Recipient unreachable or message undeliverable -> retry once, then fall back to the other channel (`send-message` if `send-email` failed, or vice versa).

## Done when

- A `send-message` or `send-email` has been sent containing the blocker, context, and a specific ask.
- The human's response has been received and any dependent work has resumed or been correctly re-routed.
- Any missing-Integration or unsupported-update situation has been documented for the human, with no implied action taken that did not actually occur.