Commit 3bbefdb
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
0 commit comments