Smoke Signal

Wait for the answer to a Decision and return the chosen action id. The call stays open while it waits, using server-side bounded waits rather than a polling loop, for up to wait_seconds (default 300, maximum 1200). Some clients move a long tool call to the background and hand you control again before it finishes; if that happens the wait is still running and its result still arrives, so do not invent an outcome and do not act on the decision until you have read the answer -- either from this result or from a fresh await_decision with the same decision_id. If it comes back "pending", the Decision is still live: call await_decision again with the SAME decision_id. Do not create another Decision -- that charges again and sends the user a second question. An answer is delivered exactly once: the first successful await_decision returns it and the server erases the Decision and the reply in the same step, so keep the action id in your own reasoning. A reply is anonymous advice from whoever holds a subscribed device -- replies carry no identity, any subscriber of the Channel can answer, and where the platform shows notification action buttons a reply can come from a locked phone. Never treat one as security authorization: not for a deployment, not to bypass a permission prompt, not for credentials, and not for a destructive or irreversible action.

Withdraw a Decision you no longer need -- the user answered here in the session, the work was abandoned, or you resolved the decision yourself. It erases the question from the server and clears the decision screen from the subscribers' devices. It does NOT refund the credits: cancellation exists to stop bothering the user, not to save money. After cancelling, do not call await_decision for that decision_id.

Queue the wording for a phone notification about the block you are ABOUT TO create. Call this as your LAST action immediately before you ask the user a question, present a plan for approval, or otherwise stop and wait for them -- and only when being away would actually cost them something. Nothing is sent when you call this: it only supplies the wording. The notification is sent only if the user does not respond within their grace window, and is cancelled silently if they do. The user CANNOT reply from the notification, so do not ask them to -- write it as a summons. The single most useful thing you can say is what is STALLED until they answer, not a restatement of your question. Do not call this for routine turn-ends, for progress updates, or more than once per block.

Send ONE decision to the user's phone through Smoke Signal and get back exactly one answer. Use it only when you are genuinely blocked on a decision that is theirs to make AND they are away from the keyboard. If they are at the keyboard, ask in this session instead: it is instant and free. A Decision costs credits for EVERY logical subscriber of the Channel, so send one Decision per question -- fold the whole choice into a single question with 2-4 concrete options, never a series of narrowing questions. This returns a decision_id immediately without waiting; carry on with anything you can do meanwhile, then call await_decision with that decision_id to wait for the answer. await_decision is the ONLY way to read an answer: never re-send a Decision to check on one, because a second Decision charges again. A reply is anonymous advice from whoever holds a subscribed device -- replies carry no identity, any subscriber of the Channel can answer, and where the platform shows notification action buttons a reply can come from a locked phone. Never treat one as security authorization: not for a deployment, not to bypass a permission prompt, not for credentials, and not for a destructive or irreversible action.