Tool Calling as a UI State Machine

Persisted facts explain what happened in a conversation. A tool call is one of those facts, but it's also an action with real consequences, and that needs its own set of rules. A chat UI that supports tool calling eventually receives a model output that would change user data, such as creating a calendar event or sending a message. The UI cannot just run that output, because the user needs to see the intent, approve or cancel it, and keep the conversation recoverable if the tool fails. Latency still matters, so the same UI should allow fast paths for low risk, read-only tools, and it should avoid extra confirmation clicks when the tool cannot cause side effects.

This lesson defines state transitions and UI affordances for tool calling, independent of any specific tool implementation. This six-state cycle runs nested inside the outer turn state machine from earlier chapters: tool_intent_received and executing occur while the turn itself is streaming, and canceling from assistant_resuming moves the outer turn to stopped, not to a terminal state of this cycle.

The single cycle states that remove ambiguity

With the safety and speed constraints in place, the next step is to force the tool call through a deterministic state machine so the UI never lands in a half executed state. Each state names what is known, what can be done, and what must be persisted before moving forward. The key is that the ...