A PendingToolCall holds a tool invocation that must wait for user approval. It preserves the original ToolCall in `tool_call` and adds a `confirmation_message` explaining the proposed action. This lets an agent ask before executing an irreversible operation, such as deleting a file. section 6.3.5 section 6.3.7
In an asynchronous approval workflow:
- A tool marked `requires_confirmation` supplies a message generated from its name and arguments. The agent wraps its ToolCall and that message in a PendingToolCall instead of executing the tool. section 6.3.6 section 6.3.7
- The agent stores pending calls in `context.state` and returns an AgentResult with `status="pending_confirmation"` and a `pending_tool_calls` list. Pydantic’s `model_dump()` and `model_validate()` make the calls saveable and restorable across a pause. section 6.3.5 section 6.3.7
- On resumption, ToolConfirmation decisions are matched to pending calls by `tool_call_id`. Approved calls can execute; calls omitted from the approval list are rejected. Processed pending state is then cleared. section 6.3.5 section 6.3.7
Approve a file deletion
A request to delete `temp.txt` returns `pending_confirmation` with one PendingToolCall. Its message asks whether to delete the file and warns that the action cannot be undone. The application takes its `tool_call_id`, creates `ToolConfirmation(tool_call_id=..., approved=True)`, and calls `run()` again with the same session ID. The agent then executes the deletion and returns `complete`. section 6.3.8
# Saving: when pending occurs in act()
pending_calls = [PendingToolCall(tool_call=tc, confirmation_message=msg)]
context.state["pending_tool_calls"] = [p.model_dump() for p in pending_calls]
# Restoring: when resuming run()
raw_pending = context.state.get("pending_tool_calls", [])
pending_calls = [PendingToolCall.model_validate(d) for d in raw_pending]
The save-and-restore code shows why a pending call is a model rather than an unsaved in-memory marker: the agent can recover its approval request when execution resumes. section 6.3.5
