Confirmations

When a destructive (or chain) action would run, the web-kernel intercepts it, shows the user a confirmation card, and only executes after the user clicks "yes". This page explains the flow, the federal guarantees, and how your extension participates.

The user-facing flow

You: clear my done tasks

Webbee: "This will delete 3 completed tasks. Confirm?" — [✅ Yes] [✗ Cancel]

You: (clicks ✅)

Webbee: ✓ Cleared 3 completed task(s).

What happened end to end:

What you do

Just declare action_type="destructive":

@chat.function(
    description="Permanently delete a folder and all its contents.",
    action_type="destructive",
    id_projection="folder_id",
)
async def delete_folder(ctx, params: DeleteFolderParams):
    await ctx.http.delete(f"/folders/{params.folder_id}")
    return {"text": "Folder deleted."}

That's it. The web-kernel handles the rest.

What the user sees

The confirmation card includes:

Example for a chain (multiple destructive calls in one user turn):

Confirm 3 actions:
  1. delete_note(note_id="note_abc")
  2. delete_note(note_id="note_def")
  3. archive_thread(thread_id="thr_123")

[✅ Confirm all]   [✗ Cancel]

Federal I-CONFIRMATION-EXECUTES-WHAT-USER-SAW means: all three run with those exact args, in that order, on accept. No re-planning, no LLM rerun.

The federal core

Multi-step chains and confirmations

When a user says "check my unread mail and delete the spam":

1. Classifier emits a 2-step chain: [mail.list_unread → mail.delete_spam]
2. Web-kernel runs step 1 (read-only — fires immediately)
3. Step 2 is destructive — web-kernel pauses, intercepts args, shows card with the actual count to be deleted (precondition_iterate kind)
4. User accepts → step 2 runs typed-iterate

The card shows real numbers ("Delete 7 spam threads?"), not placeholders ("Delete some threads?"). Federal Phase 3 of Pre-Authorized Action Execution covers this.

What you should NOT do

Per-action override (rare)

You can force confirmation on a write tool with confirm: True in panel actions:

from imperal_sdk import ui

@ext.panel("items", slot="left", title="Items")
async def items_sidebar(ctx, **kwargs):
    items = await ctx.store.query("items", limit=50)
    return ui.List(items=[
        ui.ListItem(
            id=str(item["id"]),
            title=item["name"],
            actions=[{
                "label": "Move to trash",
                "on_click": ui.Call("archive_item", item_id=item["id"], confirm=True),
            }],
        )
        for item in items.data
    ])

Original (legacy @panels.sidebar + dict-shape) for reference:

# LEGACY — pre-v4 SDK. Does NOT work today. Kept for context.
@panels.sidebar(...)
async def items_sidebar(ctx):
    return {
        "type": "list",
        "items": [
            {"label": item.name, "actions": [
                {"label": "Move to trash", "tool": "items.archive",
                 "args": {"item_id": item.id}, "confirm": True},
            ]}
        ],
    }

Useful for write actions that aren't strictly destructive but the UI wants to double-check.

Where to next