From 7f3ea59b76d307350c613f80790a0559ad764aaf Mon Sep 17 00:00:00 2001 From: adhamvapi <256238690+adhamvapi@users.noreply.github.com> Date: Wed, 22 Apr 2026 16:09:22 +0000 Subject: [PATCH 1/4] 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 --- fern/security-and-privacy/PCI.mdx | 104 +++++++++++++++++++++++++++++- fern/squads/handoff.mdx | 18 ++++++ 2 files changed, 121 insertions(+), 1 deletion(-) diff --git a/fern/security-and-privacy/PCI.mdx b/fern/security-and-privacy/PCI.mdx index 3a6ab8726..f83619508 100644 --- a/fern/security-and-privacy/PCI.mdx +++ b/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,108 @@ 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. +## Securing Handoffs with Sensitive Data + +When using squads or the handoff tool with PCI-mode assistants, it is important to control what conversation context is forwarded to the next assistant. By default, handoffs use `contextEngineeringPlan` type `all`, which transfers the **entire** conversation history -- including tool call results that may contain sensitive data such as card numbers. + +### What Vapi has fixed + +Vapi has deployed a server-side fix to ensure that sensitive data is no longer stored in internal systems or logs for any assistant that has PCI mode enabled, logging disabled, or zero data retention (ZDR) configured. This fix applies automatically to all qualifying assistants. + +### What you need to do + +As a defense-in-depth measure, if your flow uses assistant handoffs -- particularly handing off **from** a card-collection (or similarly sensitive) assistant **to** another assistant -- you should configure the `contextEngineeringPlan` on the handoff destination to prevent sensitive tool call data from being forwarded. + + +If your sensitive assistant uses the default `contextEngineeringPlan` (type `all`), the full conversation context -- including tool call results containing card numbers or other sensitive data -- will be forwarded to the next assistant. Always set an appropriate context engineering plan on handoff destinations from sensitive assistants. + + +#### Step 1: Identify your sensitive assistant handoffs + +Review your squad or handoff tool configuration. Look for any assistant that collects sensitive data (card numbers, SSNs, etc.) and has `assistantDestinations` or handoff tool `destinations` pointing to another assistant. + +#### Step 2: Set the context engineering plan + +On each destination **from** a sensitive assistant, add a `contextEngineeringPlan` that excludes tool call data. The recommended options are: + +| Type | Behavior | When to use | +|------|----------|-------------| +| `previousAssistantMessages` | Forwards only the conversation history from **before** the current (sensitive) assistant's session. Excludes the sensitive assistant's own messages and tool calls entirely. | **Recommended.** Preserves useful pre-payment context while fully excluding sensitive data. | +| `userAndAssistantMessages` | Forwards only user and assistant spoken messages, stripping out all tool calls and tool results. | Good alternative when you want the next assistant to see the conversational flow but not internal tool data. | +| `none` | Starts the next assistant with a blank conversation. No prior context is forwarded. | Maximum isolation. Use when the next assistant does not need any prior context. | + + +For a full reference on all context engineering plan types, see the [Handoff Tool - Context Engineering](/squads/handoff#context-engineering) documentation. + + +#### Step 3: Apply the configuration + +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" + } + } + ] +} +``` + +#### Step 4: Use 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. + + +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. + + ## 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. diff --git a/fern/squads/handoff.mdx b/fern/squads/handoff.mdx index fcc763470..43177551c 100644 --- a/fern/squads/handoff.mdx +++ b/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. +### 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. + + +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 - Securing Handoffs](/security-and-privacy/pci#securing-handoffs-with-sensitive-data) guide for a complete walkthrough. + + ### No context Starts the next assistant with a blank conversation: From 3b9264575165ce35194ba8ec477ba76f9ea45f93 Mon Sep 17 00:00:00 2001 From: adhamvapi <256238690+adhamvapi@users.noreply.github.com> Date: Wed, 22 Apr 2026 16:17:18 +0000 Subject: [PATCH 2/4] 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 --- fern/security-and-privacy/PCI.mdx | 28 +++++++++------------------- fern/squads/handoff.mdx | 2 +- 2 files changed, 10 insertions(+), 20 deletions(-) diff --git a/fern/security-and-privacy/PCI.mdx b/fern/security-and-privacy/PCI.mdx index f83619508..1f83aa96e 100644 --- a/fern/security-and-privacy/PCI.mdx +++ b/fern/security-and-privacy/PCI.mdx @@ -227,33 +227,23 @@ 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. -## Securing Handoffs with Sensitive Data +## Handoff Context Configuration -When using squads or the handoff tool with PCI-mode assistants, it is important to control what conversation context is forwarded to the next assistant. By default, handoffs use `contextEngineeringPlan` type `all`, which transfers the **entire** conversation history -- including tool call results that may contain sensitive data such as card numbers. +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. -### What Vapi has fixed - -Vapi has deployed a server-side fix to ensure that sensitive data is no longer stored in internal systems or logs for any assistant that has PCI mode enabled, logging disabled, or zero data retention (ZDR) configured. This fix applies automatically to all qualifying assistants. - -### What you need to do - -As a defense-in-depth measure, if your flow uses assistant handoffs -- particularly handing off **from** a card-collection (or similarly sensitive) assistant **to** another assistant -- you should configure the `contextEngineeringPlan` on the handoff destination to prevent sensitive tool call data from being forwarded. +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. -If your sensitive assistant uses the default `contextEngineeringPlan` (type `all`), the full conversation context -- including tool call results containing card numbers or other sensitive data -- will be forwarded to the next assistant. Always set an appropriate context engineering plan on handoff destinations from sensitive assistants. +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. -#### Step 1: Identify your sensitive assistant handoffs - -Review your squad or handoff tool configuration. Look for any assistant that collects sensitive data (card numbers, SSNs, etc.) and has `assistantDestinations` or handoff tool `destinations` pointing to another assistant. - -#### Step 2: Set the context engineering plan +### Recommended context types -On each destination **from** a sensitive assistant, add a `contextEngineeringPlan` that excludes tool call data. The recommended options are: +The following `contextEngineeringPlan` types are well-suited for PCI and other sensitive data flows: | Type | Behavior | When to use | |------|----------|-------------| -| `previousAssistantMessages` | Forwards only the conversation history from **before** the current (sensitive) assistant's session. Excludes the sensitive assistant's own messages and tool calls entirely. | **Recommended.** Preserves useful pre-payment context while fully excluding sensitive data. | +| `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. | | `userAndAssistantMessages` | Forwards only user and assistant spoken messages, stripping out all tool calls and tool results. | Good alternative when you want the next assistant to see the conversational flow but not internal tool data. | | `none` | Starts the next assistant with a blank conversation. No prior context is forwarded. | Maximum isolation. Use when the next assistant does not need any prior context. | @@ -261,7 +251,7 @@ On each destination **from** a sensitive assistant, add a `contextEngineeringPla For a full reference on all context engineering plan types, see the [Handoff Tool - Context Engineering](/squads/handoff#context-engineering) documentation. -#### Step 3: Apply the configuration +### Configuring the context engineering plan Set the `contextEngineeringPlan` on the handoff destination from your sensitive assistant. Here is an example using `previousAssistantMessages`: @@ -296,7 +286,7 @@ Or equivalently, when using the handoff tool: } ``` -#### Step 4: Use variable extraction for safe data passing +### 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: diff --git a/fern/squads/handoff.mdx b/fern/squads/handoff.mdx index 43177551c..9213807c9 100644 --- a/fern/squads/handoff.mdx +++ b/fern/squads/handoff.mdx @@ -452,7 +452,7 @@ Transfers only the conversation history from **before** the current assistant's 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. -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 - Securing Handoffs](/security-and-privacy/pci#securing-handoffs-with-sensitive-data) guide for a complete walkthrough. +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. ### No context From 0e271beceb60a609d23f48f3cd9ee38aaf982a39 Mon Sep 17 00:00:00 2001 From: adhamvapi <256238690+adhamvapi@users.noreply.github.com> Date: Wed, 22 Apr 2026 17:23:32 +0000 Subject: [PATCH 3/4] fix: correct PCI recommendation for userAndAssistantMessages context type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- fern/security-and-privacy/PCI.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/fern/security-and-privacy/PCI.mdx b/fern/security-and-privacy/PCI.mdx index 1f83aa96e..c7adfe3b3 100644 --- a/fern/security-and-privacy/PCI.mdx +++ b/fern/security-and-privacy/PCI.mdx @@ -239,13 +239,13 @@ If a sensitive assistant uses the default `contextEngineeringPlan` (type `all`), ### Recommended context types -The following `contextEngineeringPlan` types are well-suited for PCI and other sensitive data flows: +The following table describes the `contextEngineeringPlan` types relevant to PCI and other sensitive data flows: -| Type | Behavior | When to use | +| 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. | -| `userAndAssistantMessages` | Forwards only user and assistant spoken messages, stripping out all tool calls and tool results. | Good alternative when you want the next assistant to see the conversational flow but not internal tool data. | -| `none` | Starts the next assistant with a blank conversation. No prior context is forwarded. | Maximum isolation. Use when the next assistant does not need any prior context. | +| `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. | +| `userAndAssistantMessages` | Forwards only user and assistant spoken messages, stripping out all tool calls and tool results. | **Not recommended for PCI flows** — spoken sensitive data (e.g., card numbers read aloud) appears in user messages and would be forwarded to the next assistant. | For a full reference on all context engineering plan types, see the [Handoff Tool - Context Engineering](/squads/handoff#context-engineering) documentation. From 39fbe457e4500a18a7bf873cf9ef62b1d3617f97 Mon Sep 17 00:00:00 2001 From: adhamvapi <256238690+adhamvapi@users.noreply.github.com> Date: Wed, 22 Apr 2026 18:04:20 +0000 Subject: [PATCH 4/4] fix: remove userAndAssistantMessages row from PCI docs table Co-Authored-By: Claude Opus 4.6 --- fern/security-and-privacy/PCI.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/fern/security-and-privacy/PCI.mdx b/fern/security-and-privacy/PCI.mdx index c7adfe3b3..4aed23785 100644 --- a/fern/security-and-privacy/PCI.mdx +++ b/fern/security-and-privacy/PCI.mdx @@ -245,7 +245,6 @@ The following table describes the `contextEngineeringPlan` types relevant to PCI |------|----------|-------------| | `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. | -| `userAndAssistantMessages` | Forwards only user and assistant spoken messages, stripping out all tool calls and tool results. | **Not recommended for PCI flows** — spoken sensitive data (e.g., card numbers read aloud) appears in user messages and would be forwarded to the next assistant. | For a full reference on all context engineering plan types, see the [Handoff Tool - Context Engineering](/squads/handoff#context-engineering) documentation.