PXI Approval Flow#

The PXI approval flow is the accept/reject pending-diff interaction pattern that gates all write operations in the PXI (Phoenix Agent UI) tool system behind explicit user confirmation. Every tool that mutates state — editing prompts, modifying tool definitions, managing datasets, creating annotation configs — stages a diff for the user to review before any change is applied.

Approval behavior is controlled by the user's edit_permission setting:

• manual — shows an inline approval card with Accept/Reject buttons
• bypass — applies changes immediately; agent receives auto-approved status

The pattern was introduced for playground prompt editing 1, then extended to prompt tool writes 2, dataset management 3, and annotation configs 4.

Lifecycle#

All approval-gated tools share the same five-step lifecycle 3:

Propose → Display → [Accept | Reject | Cancel]

1. Propose — Tool stages a pending entry (diff preview, summary grid, etc.) in the Zustand agentStore slice keyed by toolCallId. Fail-fast validation runs here; invalid batches never register a pending diff 2.
2. Display — UI renders an approval card (e.g., WritePromptToolsToolDetails, DatasetWriteApprovalCard). Cards are editable before commit — users can refine the proposal before accepting 4.
3. Accept — Commit callback re-validates the expectedRevision token against live store state. If the revision has drifted, a stale error is returned and nothing is applied 1 2.
4. Reject — Pending entry is cleared, playground/store state is unchanged, agent receives rejected output status 1.
5. Cancel — If the owning editor unmounts mid-review (user navigates away), a cancellation error is emitted to the agent rather than leaving the chat stuck 1.

Pending state is stored per-tool in agentStore.ts (e.g., pendingPromptEdits, pendingPromptToolWritesByToolCallId, pendingDatasetWritesByToolCallId), allowing multiple concurrent proposals to coexist and be individually resolved 2 3.

Diffs are rendered in display format — the exact format the user would edit in the JSONToolEditor or dataset form — so the user sees precisely what will change 2.

Agent Behavior After Rejection#

Tool instruction templates (e.g., WRITE_PROMPT_TOOLS_TOOL_INSTRUCTIONS.xml.j2) explicitly direct agent behavior for each outcome:

Key rules enforced by the instructions:

• Never assume success until the output status is confirmed 3
• Rejected batches are discarded entirely — the prior batch cannot be re-submitted; the agent must start from a fresh read 2
• Read before write — tools like edit_prompt_instance require calling read_prompt_instance first to capture the expectedRevision 1
• Vendor/passthrough tools are read-only — tools with kind: "raw" (e.g., web_search) cannot be created or edited via PXI, only deleted 2

Covered Tools & Source Pointers#

Approval-Gated Tools#

Key Source Files#

Frontend (TypeScript)

• Shared approval infrastructure: app/src/agent/shared/pendingApproval/ 3
• Agent store slices: app/src/store/agentStore.ts 2 3
• Playground prompt tools: app/src/agent/tools/playgroundPrompt/ 1
• Prompt tools write: app/src/agent/tools/playgroundPromptTools/ — pendingPromptToolWrite.ts, diffSummary.ts, clientActions.ts 2
• Dataset tools: app/src/agent/tools/{listDatasets,createDataset,datasetEdit,...}/ 3
• Annotation config tools: app/src/agent/tools/annotationConfig/ 4

Backend (Python)

• Dataset capability tools: src/phoenix/server/agents/capabilities/tools/external/ 3
• Annotation config tools: src/phoenix/server/agents/capabilities/tools/external/{create,update}_annotation_config.py 4
• Span note internal tool: src/phoenix/server/agents/capabilities/tools/internal/write_span_note.py 4
• Agent instructions template: src/phoenix/server/agents/prompts/tools/WRITE_PROMPT_TOOLS_TOOL_INSTRUCTIONS.xml.j2 2
• Playground chat tools: src/phoenix/server/agents/chat_v2/tools/{read_prompt,clone_prompt_instance,edit_prompt}.py 1
• Span coding skill: src/phoenix/server/agents/skills/span_coding.py 4

Tool State UI Indicators#

The terminal UI (ToolStateIndicator) reflects approval state visually 5: