Skip to content

Commit 3bbefdb

Browse files
authored
docs(static-variables): add prompt-injection threat model and trust tiers (#1035)
## Description Stacked on top of #1033 (`dr/squads-passing-data-between-assistants`). Targets the static-variables-and-aliases page; the squads page in #1033 stays scoped to its own concern. Surfaced by an FDE conversation with **Mudflap** asking how to do progressive authentication on inbound calls without giving the LLM a path to forward a fake caller-ID. The current page documents the mechanics of static `parameters` correctly but doesn't frame it as a security boundary, and doesn't address the failure modes that break that boundary in practice. This PR adds that framing. ### What changes in `fern/tools/static-variables-and-aliases.mdx` - **Naming distinction** added at the top: `function.parameters` (LLM-facing JSON schema, model fills it) vs. top-level `parameters` (server-merged, LLM never sees it). The dashboard surfaces both as similarly-named sections (just **Parameters** vs **Static Body Fields**), which is the most common cause of customers accidentally exposing trusted fields to the model. - **Trust tiers for the Liquid variable bag.** Tier 1 (server-trusted: `customer.*`, `phoneNumber.*`, `transport.*`, `call.*`, `assistant.*`, time variables, `assistantOverrides.variableValues` set at call start). Tier 2 (conversation-derived, not safe as a security boundary: `messages`, `transcript`, `prompt`). Tier 3 (LLM-derived, never trustworthy: `variableExtractionPlan` aliases from non-trusted sources, handoff arguments, handoff schema extraction). - **Five common failure modes** with bad/good code pairs: defining the trusted field in `function.parameters`; body-default leak; system-prompt forwarding; unsafe alias chains; mid-call bag mutation. - **Worked example** for caller-ID-based progressive authentication (the Mudflap pattern). - **Tool-type support matrix** plus an explicit warning that legacy `assistant.model.functions[]` does **not** support static parameters (the converter zeroes them out at request time, so customers on the deprecated shape have no orchestration-layer injection at all). - **Handoff section** cross-linking to `/squads/passing-data-between-assistants` (#1033). Documents that `tool.parameters` doesn't exist on handoff and explains why it doesn't need to: call-level Liquid variables persist across handoffs; aliases from server-trusted sources persist via `allMessagesContext.variablesAdd`; `destination.assistantOverrides.variableValues` is merged at handoff time bypassing the LLM. Flags that #1033's *Approach 1* (handoff arguments via `function.parameters`) is correct for **LLM-derived** values like sentiment/intent but is **not** a security boundary for signaling-derived values like caller-ID. - **Known limitation** flagged: Liquid templates inside `destination.assistantOverrides.variableValues` are not currently resolved at handoff time (values spread verbatim into the bag). - **Dashboard mental model** section: how the API request and function tool forms surface the two `parameters` fields, with a step-by-step for the caller-ID pattern. ### Skipped - **Workflows extraction failure mode** -- workflows are deprecated, intentionally not addressed. - **test-writer / code-reviewer** -- docs-only PR. ## Testing Steps - [x] `fern check` -- 0 errors - [x] All JSON code blocks validate (15/15 OK) - [x] All internal links resolve (5/5: `/squads/passing-data-between-assistants` resolves via the parent branch in this stack; `/tools/code-tool`, `/tools/custom-tools`, `/tools/tool-rejection-plan`, `/api-reference/tools/create` all resolve) - [ ] Verify the page renders correctly in the preview deployment, especially the trust-tier tables and the bad/good code-pair sections - [ ] Confirm the new section anchors render (`#the-variable-bag`, `#forwarding-trusted-data-across-handoffs`) so the cross-references inside the page resolve - [ ] Sanity-check the dashboard section against the live ToolsV2 form -- verify section labels still read "Parameters" and "Static Body Fields" - [x] Style guide compliance (active voice, present tense, no marketing language) - [x] Code examples use realistic placeholders (`YOUR_API_KEY`, etc.) ## Related - Stacked on #1033 ("Passing data between assistants" page) -- merge order: #1033 first, then this PR rebases onto main; or merge this into #1033's branch first to land as a single combined PR. - Source: FDE conversation with Mudflap (Steffen) about progressive caller-ID authentication. - Follow-up worth filing: `destination.assistantOverrides.variableValues` should support Liquid template resolution at handoff time -- usability gap, not a security gap.
1 parent f10efa0 commit 3bbefdb

1 file changed

Lines changed: 277 additions & 14 deletions

File tree

0 commit comments

Comments
 (0)