docs: add previousAssistantMessages handoff mode to PCI docs (#1026)

* docs: add previousAssistantMessages handoff mode to PCI and handoff docs

Add a new "Securing Handoffs with Sensitive Data" section to the PCI
compliance documentation explaining the security concern with forwarding
full conversation context (including sensitive tool call data) during
assistant handoffs, the server-side fix Vapi deployed, and the
customer-side steps to configure contextEngineeringPlan appropriately.

Also document the previousAssistantMessages context engineering plan type
in the handoff tool documentation, which was the only type not yet
covered there.

Update the existing Payment Collection Squad example to use
previousAssistantMessages instead of none for a more practical default.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: reframe PCI handoff docs to neutral feature documentation

Remove incident-response framing ("What happened", "What we've fixed",
"What you need to do") from PCI.mdx and present previousAssistantMessages
as a standard feature for controlling handoff context in sensitive flows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: correct PCI recommendation for userAndAssistantMessages context type

The table previously described userAndAssistantMessages as a "good
alternative" for PCI flows. This is incorrect — if a user speaks
sensitive data (e.g., card numbers) aloud, those appear in user messages
and would be forwarded to the next assistant. Updated the table to mark
it as not recommended for PCI flows, reordered rows to list safe options
first, and renamed the column header from "When to use" to
"PCI Recommendation" for clarity.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: remove userAndAssistantMessages row from PCI docs table

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: adhamvapi <256238690+adhamvapi@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: adhamvapi

fern/security-and-privacy/PCI.mdx

@@ -161,7 +161,7 @@ Here's a complete squad configuration that demonstrates this approach:
                     "assistantName": "Assistant 3",
                     "description": "Transfer the caller to the payment confirmation assistant.",
                     "contextEngineeringPlan": {
-                        "type": "none"
+                        "type": "previousAssistantMessages"
                     },
                     "variableExtractionPlan": {
                         "schema": {
@@ -227,6 +227,97 @@ The key component is the `artifactPlan` in Assistant 2:
 
 This ensures that sensitive payment information is never recorded, logged, or transcribed, while still allowing you to maintain call quality data for the non-sensitive portions of the conversation.
 
+## Handoff Context Configuration
+
+When using squads or the handoff tool, you can control what conversation context is forwarded to the next assistant using `contextEngineeringPlan`. This is particularly important for PCI-compliant flows where an assistant handles sensitive data such as payment card numbers.
+
+By default, handoffs use `contextEngineeringPlan` type `all`, which transfers the entire conversation history -- including tool call results. For assistants that process sensitive data, you should choose a more restrictive context type to ensure that tool call results (which may contain card numbers or other sensitive values) are not forwarded.
+
+<Warning>
+If a sensitive assistant uses the default `contextEngineeringPlan` (type `all`), the full conversation context -- including tool call results -- will be forwarded to the next assistant. Always set an appropriate context engineering plan on handoff destinations from assistants that handle sensitive data.
+</Warning>
+
+### Recommended context types
+
+The following table describes the `contextEngineeringPlan` types relevant to PCI and other sensitive data flows:
+
+| Type | Behavior | PCI Recommendation |
+|------|----------|-------------|
+| `previousAssistantMessages` | Forwards only the conversation history from **before** the current assistant's session. Excludes the current assistant's own messages and tool calls entirely. | **Recommended.** Preserves useful pre-payment context while fully excluding the sensitive assistant's data. |
+| `none` | Starts the next assistant with a blank conversation. No prior context is forwarded. | **Safe.** Maximum isolation. Use when the next assistant does not need any prior context. |
+
+<Note>
+For a full reference on all context engineering plan types, see the [Handoff Tool - Context Engineering](/squads/handoff#context-engineering) documentation.
+</Note>
+
+### Configuring the context engineering plan
+
+Set the `contextEngineeringPlan` on the handoff destination from your sensitive assistant. Here is an example using `previousAssistantMessages`:
+
+```json
+"assistantDestinations": [
+    {
+        "type": "assistant",
+        "assistantName": "Confirmation Assistant",
+        "description": "Transfer to the confirmation assistant after payment collection.",
+        "contextEngineeringPlan": {
+            "type": "previousAssistantMessages"
+        }
+    }
+]
+```
+
+Or equivalently, when using the handoff tool:
+
+```json
+{
+    "type": "handoff",
+    "destinations": [
+        {
+            "type": "assistant",
+            "assistantName": "Confirmation Assistant",
+            "description": "Transfer to the confirmation assistant after payment collection.",
+            "contextEngineeringPlan": {
+                "type": "previousAssistantMessages"
+            }
+        }
+    ]
+}
+```
+
+### Using variable extraction for safe data passing
+
+If the next assistant needs specific data from the sensitive session (such as the last four digits of a card number for confirmation), use `variableExtractionPlan` instead of relying on full context forwarding. This extracts only the structured fields you define:
+
+```json
+"assistantDestinations": [
+    {
+        "type": "assistant",
+        "assistantName": "Confirmation Assistant",
+        "contextEngineeringPlan": {
+            "type": "previousAssistantMessages"
+        },
+        "variableExtractionPlan": {
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "lastFourDigits": {
+                        "type": "string",
+                        "description": "Last four digits of the card number"
+                    }
+                }
+            }
+        }
+    }
+]
+```
+
+The extracted variables are available in the next assistant's system prompt using Liquid template syntax (e.g., `{{lastFourDigits}}`). This is the pattern used in the [Payment Collection Squad Example](#payment-collection-squad-example) above.
+
+<Tip>
+Combining `contextEngineeringPlan` with `variableExtractionPlan` gives you the best of both worlds: sensitive tool call data is excluded from the forwarded context, while the specific data points the next assistant needs are passed through as named variables.
+</Tip>
+
 ## Can PCI be used alongside HIPAA?
 Yes, you can enable both HIPAA and PCI compliance for an assistant. In this case, the restrictions from both compliances will apply, meaning that no recordings or transcripts will be stored or transmitted, even if you have specified cloud storage endpoints or webhooks for storing transcripts.
 

fern/squads/handoff.mdx

@@ -437,6 +437,24 @@ Transfers only user and assistant messages, filtering out system messages, tool
 Use `userAndAssistantMessages` when the destination assistant does not need to see tool call history or system prompts from the previous assistant. This produces a cleaner context and reduces token usage.
 </Tip>
 
+### Previous assistant messages
+
+Transfers only the conversation history from **before** the current assistant's session. This excludes the current assistant's own messages, tool calls, and tool results entirely, forwarding only the context that existed when the current assistant first received the call.
+
+```json
+{
+  "contextEngineeringPlan": {
+    "type": "previousAssistantMessages"
+  }
+}
+```
+
+This mode is particularly useful when the current assistant handles sensitive data (such as payment card numbers in a PCI-compliant flow). By excluding the current assistant's session from the forwarded context, you prevent sensitive tool call results from reaching the next assistant.
+
+<Tip>
+Use `previousAssistantMessages` when handing off from a sensitive assistant (e.g., one collecting payment data) to a non-sensitive assistant. It preserves useful conversation context from earlier in the call while ensuring the sensitive assistant's tool call data is not forwarded. See the [PCI Compliance - Handoff Context Configuration](/security-and-privacy/pci#handoff-context-configuration) guide for a complete walkthrough.
+</Tip>
+
 ### No context
 
 Starts the next assistant with a blank conversation: