# Escalating a call to a person

An escalation phrase queues a transfer and puts the call in front of a colleague, who can steer, pause or take it over from the supervisor panel while it is still live. What it does not do on the live carrier is hand the caller to a person's handset: a completed warm transfer depends on a provider capability that is not enabled. The escalation is real; the handover is narrower than the word suggests.

- **Status:** Foundation
- **Audience:** both
- **Channels:** phone
- **In the app:** #/calls, #/needs-you
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/call-escalation/

## The chain, when the caller wants a human

1. Trigger — the caller asks for a person, or the conversation crosses an escalation rule.
2. User event — the phrase is heard in the caller's own words, mid-call.
3. Authentication and workspace resolution — the call is already inside its workspace; so is the colleague who joins.
4. Ingest — the turn is recorded like any other; nothing about it is special until it is classified.
5. Canonical record — a transfer is queued against the `calls` row.
6. Reasoning — the escalation rule and the line's behaviour block decide what the voice says next.
7. Knowledge, memory and rules — the escalation text is part of the behaviour block, not improvised per call.
8. Autonomy and approval — a colleague may pause the voice, take the call over, or leave it running.
9. Action through a provider — supervisor controls ride the guidance log: hang up, transfer, tones, mute.
10. Result — the caller is helped by a person on the panel, or is called back; a completed carrier transfer is not available.
11. Relationship, timeline and memory — the escalation and its reason land on the person's record.
12. Audit, usage and Needs You — the decision log answers who took the call over, and when.

> **Careful** Read the status word literally. Call transfer is a **foundation** capability: the model, the queueing and the panel exist, and the provider capability that would complete a warm transfer on the live carrier is not enabled. A page, a script or a promise to a customer that says "we will put you through" is describing something the line cannot currently do.

## What a colleague can actually do to a live call

The supervisor panel is how a person steers a call that is happening. Two rules shape everything it does.

**Guidance never reaches the caller** — An instruction goes into the system prompt and nowhere else — not into the spoken reply, not into the turn record, not onto the wire. A colleague can tell the voice what to emphasise without the caller hearing an aside.
**Control state is derived, not stored** — Pause, take over and release end in a state no single row describes, so the state is computed from the guidance log rather than kept beside it. The log is the truth; the panel is a reading of it.

| Stage | What you see | What changes | What can fail |
|---|---|---|---|
| Guide | The next reply reflects the instruction | A guidance entry in the log | On the default model the session is immutable, so guidance is recorded as undeliverable rather than silently dropped |
| Pause | The voice stops replying | The reply becomes empty text and a listen state | Silence must render as no speech element at all; a stray element is a caller hearing nothing while the line stays open |
| Take over | The colleague is handling it | Derived control state moves | Nothing in the model's own state changes — the derivation is what makes this coherent |
| Hang up, tones, mute | The call ends or the line changes | Control entries consumed by the worker's poll | A control is never spoken; anything that leaks into speech is a defect, not a feature |

## What the caller experiences

The honest version: the voice acknowledges the request in the line's own words and keeps the caller with it while a colleague reads the conversation and decides. If nobody is available, the call ends with a commitment rather than a promise — a follow-up on the phone channel for a call-back, or a task for the person who must do the work. That commitment obeys the same evidence rule as any other: a time nobody named and nobody agreed is not booked.

What the caller does not experience is hold music followed by a disconnection, which is what a queued transfer against a capability the carrier does not offer would produce.

## Where the escalation lands

- On the call record, with the phrase that triggered it and the time.
- On the person's timeline, so the next conversation starts knowing they asked for someone.
- In Needs You, when it needs a decision rather than only a record.
- In the call review, if the voice handled it badly — a stock phrase or a wrong script is a deterministic finding, not an opinion.

The one thing it must never land as is a silent nothing. An escalation that produced no record is worse than a voice that said no, because nobody learns the line is being asked for something it cannot yet give.

## Questions

### Can the caller be put through to somebody's phone?

Not on the live carrier. Transfer is asked of the provider through a capability check rather than assumed, and it is not enabled, so a completed warm transfer is not available today. The escalation queues, the panel gives a colleague live control, and a call-back is the reliable handover.

### Does a colleague's instruction ever get read out?

No. Guidance goes into the system prompt only. It does not enter the spoken reply, the turn record or the wire. That separation is deliberate — the panel would be unusable if every instruction risked becoming an aside the caller heard.

### Why is the control state calculated instead of stored?

Because pause, take over and release compose into states that no single stored flag describes correctly. Deriving the state from the guidance log means the panel and the worker cannot disagree about who is holding the call.

## Related

- [Inbound phone call, end to end](https://connectbyjbrh.com/docs/workflows/inbound-phone-call/)
- [A promised call-back, end to end](https://connectbyjbrh.com/docs/workflows/phone-follow-up-execution/)
- [Deriving control state from the log instead of storing it](https://connectbyjbrh.com/research/derived-control-state/)
- [What Connect may do](https://connectbyjbrh.com/docs/autonomy/)
- [The call ended early](https://connectbyjbrh.com/docs/troubleshooting/call-cut-short/)

## What this page is based on

- AGENTS.md §9a — the live supervisor panel and its two rules
- `backend/app/supervisor.py`, `telephony.py` CAPABILITIES
- Connect capability registry (docs-source/facts.py)