Confirmation Design

Overview

PCP uses multi-modal user confirmation to gate sensitive actions. Not every intent requires user input before execution. The confirmation requirement is determined by two properties of the target capability: its side_effects classification and its auth_level. Together, these produce a confirmation threshold that ranges from no confirmation at all to a combined voice-plus-visual prompt.

The design goal is to keep routine interactions frictionless while ensuring that destructive, high-privilege, and system-level operations receive explicit user consent. Confirmation is not a blanket gate. It is a graded response calibrated to the risk profile of each action.

The System Intelligence (SI) layer coordinates confirmation flows. When the execution pipeline determines that an intent requires confirmation, it hands control to SI, which presents the appropriate modalities, collects the user’s response, and either forwards the intent for execution or logs a denial.

Three Modalities

PCP supports three confirmation modalities. The execution pipeline selects which modality or combination to present based on the confirmation threshold for the intent’s capability.

Voice

Voice confirmation uses spoken interaction. The SI layer asks a question like “Should I delete this file?” and waits for a verbal response: “yes,” “no,” “cancel,” or an equivalent phrase. The tone is calm, direct, and non-urgent. Voice is the fastest modality for hands-free spatial computing, and it pairs naturally with the SI layer’s existing speech pipeline.

Voice confirmation requires the audio subsystem to be active and the user’s voice to be detectable. If the system cannot confidently parse a response within a configurable timeout (default: 10 seconds), the confirmation expires and the intent is denied. The denial is logged with a reason code of confirmation.timeout.

Visual

Visual confirmation presents an on-screen overlay containing three elements: a description of the pending action, the target of that action, and explicit approve and deny controls. The overlay appears on the display surface closest to the user’s current focal point.

Visual confirmation is used when voice is unavailable, when the action is complex enough to warrant a detailed description, or when the confirmation threshold requires more than one modality. Multi-step actions, for example, always get a visual prompt so the user can review the full sequence before approving.

The overlay is non-blocking in the sense that other compositor operations continue while it is displayed, but the pending intent cannot proceed until the user interacts with the approve or deny control. A configurable inactivity timeout (default: 30 seconds) dismisses the overlay and denies the intent.

Haptic

Haptic confirmation uses a vibration pattern on touch-capable surfaces. A confirmation sequence typically consists of two quick taps on the relevant surface, separated by a short interval. The system emits an initial vibration to signal that confirmation is needed, then listens for the double-tap response.

Haptic confirmation is reserved for quick, low-risk operations on hardware that supports it. It is never used as the sole modality for destructive or system-level actions. It is most useful for confirmations during gesture-based workflows where looking at a screen or speaking aloud would break the user’s flow.

Haptic confirmation is hardware-dependent. If the device does not support touch-surface vibration, the pipeline falls back to visual confirmation automatically.

Confirmation Thresholds

The confirmation threshold for an intent is derived from the capability’s side_effects classification and its auth_level. These two properties produce a lookup result:

Side Effect	Auth Level	Confirmation
none/read	any	None
write	user	None (routine)
write	privileged	Visual prompt
destructive	any	Voice + Visual
network	user	None
network	privileged	Visual prompt
system	any	Voice + Visual

Read-only operations and routine writes at the user auth level require no confirmation. The pipeline executes these immediately. Write operations at the privileged level trigger a visual prompt. Any destructive action, regardless of auth level, requires both voice and visual confirmation. Network access follows a similar split: user-level network calls are routine, while privileged network calls get a visual prompt. System-level actions always require the highest confirmation level.

The “Voice + Visual” threshold means both modalities must succeed. The user must verbally affirm the action and interact with the visual approve control. This dual requirement eliminates ambiguous voice responses and provides a clear audit trail that the user saw and acknowledged the pending action.

Friction Adaptation

The confirmation system adapts based on the user’s interaction history. Not all confirmations carry the same weight over time. A user who routinely approves a particular action should not be interrupted every single time, provided the action’s risk profile allows it.

The adaptation rules are straightforward:

First occurrence. When a user performs a specific action for the first time, the full confirmation threshold applies. If the threshold is “Voice + Visual,” both modalities are presented. If the threshold is “Visual prompt,” the overlay appears. This ensures the user is fully informed the first time they encounter a particular operation.

Repeated identical actions. As the user repeatedly performs the same action with the same parameters, friction decreases. A “Visual prompt” threshold may degrade to an implicit confirmation, where the system executes the action without an explicit prompt but logs it as confirmed-by-history. The degradation is gradual and bounded.

Novel parameter combinations. When the user performs a familiar action but with different parameters, friction resets to the full threshold for that action. A user who routinely moves windows to the left might not be prompted for that, but moving a window to an unfamiliar workspace or a new display triggers a fresh confirmation.

Destructive actions. Friction for destructive actions never degrades below the visual prompt level. Even if a user routinely deletes files, the system always presents at least a visual confirmation. The voice component may be dropped after repeated identical deletions, but the visual gate remains permanent.

Persistence. Adaptation state is per-user and per-capability. It persists across sessions through the compositor’s state storage. When a user switches profiles, the new profile starts with default friction levels for all actions. When a capability is updated, its adaptation history is reset.

The net effect is a confirmation system that stays out of the way for routine operations but remains vigilant for novel, destructive, or high-privilege actions. The user builds trust with the system over time, and the system responds by reducing unnecessary interruptions without ever eliminating safeguards for actions that carry real risk.