# Voice handoff context envelope

Use this contract when a call moves between voice models, specialist agents, tools, SIP destinations, or a human contact centre. All values below are fictional. Keep only the fields each receiver is allowed to see.

## Rules before the schema

- Every value has a source: caller, model inference, tool, policy service, identity service, or human.
- Verified facts and model-written summaries are stored separately.
- The envelope is versioned, signed, short-lived, and accepted once by the destination.
- A stale identity check or tool result is labelled, not silently trusted.
- Full transcripts are referenced under access control rather than copied into every handoff.

## Example envelope

```json
{
  "schema_version": "1.0",
  "envelope_id": "hnd_example_91",
  "conversation_id": "conv_example_7q2",
  "version": 4,
  "created_at": "2026-07-15T14:33:10Z",
  "expires_at": "2026-07-15T14:38:10Z",
  "destination": {
    "queue": "partner_reissue",
    "reason_code": "TOOL_POLICY_BOUNDARY"
  },
  "verified_state": {
    "customer_ref": "C-1842",
    "identity_level": "approved_level_2",
    "identity_expires_at": "2026-07-15T14:41:00Z",
    "language": "en-IN"
  },
  "caller_goal": {
    "summary": "Move affected Bengaluru to Delhi booking to any flight after 18:00 today",
    "source": "model_summary",
    "evidence_turns": [42, 44, 51]
  },
  "tool_state": [
    {
      "tool": "booking_lookup",
      "result_ref": "result_example_331",
      "status": "success",
      "observed_at": "2026-07-15T14:32:00Z",
      "fresh_until": "2026-07-15T14:37:00Z"
    }
  ],
  "open_work": {
    "attempted": "Automated reissue",
    "blocked_by": "Partner-airline manual approval",
    "next_allowed_action": "Human partner reissue review"
  },
  "caller_corrections": [
    {
      "field": "departure_after",
      "value": "18:00",
      "source": "caller",
      "evidence_turn": 51
    }
  ],
  "transcript_ref": {
    "uri": "secure://transcripts/conv_example_7q2#turns=42-57",
    "required_role": "partner_reissue_agent"
  }
}
```

## Receiver checks

- [ ] Signature and tenant match.
- [ ] Envelope has not expired or already been accepted.
- [ ] Destination matches the current queue.
- [ ] Identity state is still valid; otherwise show the approved re-verification step.
- [ ] Tool results are fresh enough for the next action.
- [ ] Model summaries are visibly labelled as summaries.
- [ ] Receiver can open the needed record before greeting the caller.
- [ ] Unauthorized transcript and sensitive fields remain hidden.

## Transfer failure drills

1. Context arrives, SIP transfer fails. Return safely or offer an approved callback.
2. SIP connects, context fetch fails. Receiver must not pretend to know the case.
3. Caller changes the date during the transfer message. Create a new envelope version.
4. Identity expires in queue. Require re-verification without discarding the caller’s goal.
5. Two queues accept the same envelope. One-time ownership must reject the second claim.
6. Tool data expires while the call rings. Mark it stale and refresh before action.

## Outcome record

```text
Transfer decision time:
Envelope acknowledgement time:
Destination answer time:
First useful receiver audio:
Context visible before greeting: yes / no
Caller repeated goal: yes / no
Final owner:
Final business state:
Failure path used:
Trace reference:
```