Struct PendingApproval 

pub struct PendingApproval {
    pub occurrence_turn_id: Option<String>,
    pub id: String,
    pub name: String,
    pub args_json: String,
    pub title: String,
    pub sandbox_mode: String,
    pub reason: String,
    pub missing_capabilities: Vec<String>,
    pub computed_preview: String,
}

One tool call awaiting human-in-the-loop approval.

Emitted by run_turn when ToolExecutor::needs_approval returns true for a tool the model wants to call. The caller surfaces these to the human / approver, persists an approval_request event per entry, and re-drives the loop once a matching approval_response event lands.

id matches the provider’s tool-call id (so the assistant’s tool-use content block lines up with the eventual tool-result), and is also used as the request_id on the wire approval_request event payload.

Fields

occurrence_turn_id: Option<String>

Turn that first emitted this approval occurrence. None for a new call in the turn that is currently running; set when replay re-pauses an earlier dangling call.

id: String

Provider-assigned tool-call id; also used as the approval request_id.

name: String

Tool name, as advertised by ToolExecutor::specs. Raw machine identifier; the field of record for trust/audit (unchanged in the event log).

args_json: String

Arguments as a JSON string (opaque at this layer).

title: String

Human display label (MCP-style title) for the tool, carried from the harness wire for presentation in the approval prompt. May be empty when the harness produced no label; renderers derive one from name then.

sandbox_mode: String

The sandbox/permission mode (POLYCHROME_SANDBOX_MODE) the harness was running under when it paused this call. Empty at the agent layer (the agent is sandbox-unaware); the harness stamps it onto the wire payload so the control plane can bind a remembered approval to the mode it was granted under.

reason: String

Why this specific call is being routed through the approval gate.

Empty for an ordinary gated call (the tool’s intrinsic needs_approval, the operator allow-list, or a sandbox-denial escalation) — those need no extra explanation and the edge renders its default prompt. Non-empty when the escalation is the containment path (the call requires a capability that untrusted content in context revoked): a distinct, human-readable sentence from the one shared copy helper (polyc_capability::escalation_reason), so a human decides before bytes can leave. Surfaced on the chat approval card and persisted on the durable approval_request event.

missing_capabilities: Vec<String>

The capability shortfall that paused this call (#595): the stable kebab-case names of the capabilities the gate found required-but-not-granted. Persisted on the durable approval_request and signed into a “don’t ask again” response as its covered set, so a session grant is keyed by (caller, tool, covered capabilities). Empty for an ordinary policy/sandbox gate.

computed_preview: String

A routine_delete call’s pre-resolved computed preview (#1643), as JSON. The agent loop never sets this — it is filled in afterward by the control plane (resolve_delete_previews in polyc-control-plane) before either the durable approval_request payload or the live wire card is built, since resolving one needs provider I/O neither of those synchronous steps can perform. Empty for every tool but routine_delete, and for a routine_delete call the control plane could not resolve (falls open to the generic card).

Trait Implementations

impl Clone for PendingApproval

fn clone(&self) -> PendingApproval

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PendingApproval

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PendingApproval

fn default() -> PendingApproval

Returns the “default value” for a type.