Skip to main content

How tool approval works

This page is about the why and how of Human-in-the-Loop. It's not a how-to — you won't enable anything by reading it. Its purpose is to give you the mental model so that when you see something unexpected in a conversation or the Dashboard, you can reason about it instead of guessing.

The one-paragraph version​

When your AI Agent decides to use a tool that needs a human, it stops and waits. The conversation is parked in a waiting state. As soon as you act — approve, dismiss, or answer — everything that was parked is woken back up, in the right order, and the conversation resumes. This works even when the pause happens deep inside an AI Team, and even when many things are parked at once.

Two moments your AI Agent can pause​

There are two fundamentally different moments a pause can happen. Both feel similar from inside the chat — a card appears, you click a button — but under the hood they're different, and it's useful to know which is which.

Before the tool runs (pre-execution approval). You marked this tool as needs approval. When your AI Agent wants to call it, Cubeo AI stops right before execution. The tool has not run. Nothing has been written, sent, or deleted. You see the exact input the tool would receive. When you Approve, the tool runs. When you Dismiss, the tool is skipped entirely.

After the tool starts (mid-execution question). The tool has started running, and it's the tool itself that decided to ask you something. The Ask User Questions tool works this way: it runs, produces a question card, and waits. You answer; the tool uses your answer to produce its final result; the conversation continues.

Both cases look like "AI Agent waiting for you" in the chat and the Dashboard. The difference matters when you read task statuses — approvals transition pending → waiting_for_human → approved → in_progress → success, while questions transition pending → in_progress → waiting_for_human → approved → in_progress → success.

What a "task" is​

Every time your AI Agent uses a tool, calls another AI Agent, or runs a batch, a task is created. A task is a small record that tracks: what was run, with what inputs, what came back, and what its current status is.

Most tasks live for seconds and you never notice them. A task becomes interesting to you when it pauses, either because it needs your approval or because it's asking you something.

Tasks form a tree:

  • An AI Agent turn creates one parent task.
  • Every tool call inside that turn is a child task.
  • A batch is a parent task with one child per row.
  • A subagent call is a child of the tool call that invoked it — and starts a whole new subtree.

Every task has a status (see Task statuses) and is visible from the Dashboard.

The cascade: why the whole AI Team can wait for one approval​

This is the part that often surprises people the first time they see it.

Imagine this setup:

  1. Your Lead Intake AI Agent calls its subagent HubSpot Writer (via the AI Agent tool).
  2. HubSpot Writer decides to call the Create Contact tool.
  3. Create Contact is marked as "needs approval".

What happens:

  • Cubeo AI creates a Create Contact task that is waiting_for_human.
  • Its parent — the HubSpot Writer's AI Agent turn — can't finish, so it becomes waiting_for_children.
  • The HubSpot Writer call itself is also a task inside Lead Intake's turn, so Lead Intake's turn also becomes waiting_for_children.
  • The pause bubbles up all the way to your main chat, where the approval card appears.

When you click Approve:

  • The Create Contact task goes waiting_for_human → approved → in_progress → success.
  • Its parent in HubSpot Writer wakes up: waiting_for_children → in_progress.
  • HubSpot Writer finishes its turn and returns a result.
  • Lead Intake wakes up: waiting_for_children → in_progress, sees the result, and replies to you.

This is the cascade. It works at any depth. The user-facing consequence: you always see the approval in your main chat, never buried inside a hidden subagent conversation. And you only need to resolve it once — the whole tree wakes up from one click.

info

If a parent task looks stuck in waiting_for_children, it's because at least one of its descendants is in waiting_for_human. Find that descendant in the Dashboard and resolve it — the parent will wake up automatically.

What "Dismiss" really means​

Dismissing isn't an error. It's a negative approval — a deliberate choice to skip this action.

  • The task goes to the terminal dismissed status. It never runs.
  • Your AI Agent knows you dismissed, including any feedback you typed.
  • Because your AI Agent knows, it can adapt: it might ask a clarifying question, try a different tool, or stop and wait for new instructions.
  • If the dismissed task was inside a batch or a subagent, the cascade continues — the parent doesn't fail, it just continues without that one child's result.

This is why dismissing is safe by design: it's a decision, not a crash.

What "cannot time out" means​

A task in waiting_for_human does not time out. If you leave it overnight, or for a week, it's still there when you come back. This is deliberate: we would rather have you resolve a stale task than silently drop an action you might have meant to take.

The consequence: clean up your pending queue. If you leave hundreds of tasks waiting, the Dashboard gets noisy. Dismiss the ones you no longer want; the ones you still need can wait.

tip

Check the Pending Approvals view regularly so pending tasks don't accumulate unseen.

Transport-independence: why it works the same everywhere​

You can resolve a task from the chat or from the Dashboard. The underlying task moves through the exact same statuses regardless of where the click came from. That's why the chat and the Dashboard stay in sync in real time — they're both views of the same task.

You never need to worry about "where did I approve that?". The task is the source of truth.