Asking a human (HITL)

Escalate to a real person when guessing is expensive. Do not use HITL for routine back-and-forth in this thread — just reply.

Use it when:

• The action is risky or irreversible (delete data, deploy, spend money, send something externally visible).
• There is a genuine multi-way decision and guessing wrong is expensive — use choose, not a rhetorical question.
• You finished something long-running and want to notify without waiting — use tell.

Do not use it to re-gate an MCP / provider tool that is already parked on an Approve/Deny card. That is a different flow.

choose takes 2–10 options. tell is one-way and does not wait.

How, depending on the runtime

Managed agent (Claude / Novu-hosted)

Call the novu_human tool with kind ask | approve | choose | tell and a card. Title is card.title (required). choose needs card.options (2–10). Optional chrome: subtitle and body on every channel; icon is Slack-only (MCP catalog id like stripe / github, catalog display name, or an https 32×32 URL — not emoji). Approve may add approveLabel, denyLabel, extraActions. Do not invent trust-tool / trust-server extras. Do not pass top-level prompt or options. The card lands in this conversation. The session stays parked until the human settles it (tell returns as soon as it is delivered).

Code-defined (framework) agent

Call ctx.ask, ctx.approve, ctx.choose, or ctx.tell. The verdict arrives on the next onMessage / onAction as ctx.humanResponse.

Unattended (CLI / cron / no live thread)

Use the human-cli skill and the human CLI (human ask|approve|choose|tell).