Ask | AGI Cockpit Documentation

Ask lets an AI agent pause its work and hand a confirmation or decision to a person. Cockpit returns the answer to the original task as a structured event, then resumes that same task from where it stopped.

When to use Ask

A person must make the final decision before publishing, deleting, purchasing, or taking another consequential action.
Several approaches have clear trade-offs.
A person needs to inspect an image, listen to audio, or watch a video before deciding.
Several related decisions should be reviewed together.

Ask is more than a notification. The question remains available until it is answered, and a person can respond in the dedicated Desktop Ask window or the right-side-panel Ask tab, from Inbox in the PWA, or through a configured Discord or Slack relay.

The PWA Inbox combines Asks, read-only Display notices, and one-time password input requests. An Ask returns an answer to its original task and resumes that task. Closing a Display notice sends nothing and resumes no task. A password input request is not an Ask; it delivers a value once to the specified browser field. All three let you open the originating task while that task is still available.

How Ask differs from other confirmations

Mechanism	Purpose	After the response
Ask	An agent explicitly hands a decision to a person	The answer returns to the original task and resumes it automatically
Normal reply	A person sends the next instruction to a task	The task starts a new turn
Agent-specific question	The running agent asks for input	The response answers that agent's question
Tool approval	Decides whether a file change, command, or other tool action may run	Returns an allow, always allow, or reject decision
`cockpit display`	Puts information in front of the person	Does not wait for a response or resume the task

An Ask answer is not itself permission to operate on the OS or an external service. An action that needs permission can still trigger a separate tool approval after the person confirms the direction through Ask.

How password input requests differ

A request from cockpit secret request appears in a dedicated Desktop window, the right side panel's Ask tab, and the PWA Inbox. Its dedicated window follows the Ask-window setting, and the request uses the Ask notification sound and a Normal priority badge. As soon as input completes, fails, is cancelled, or expires, its input surface disappears everywhere. Check the result through cockpit secret status or the notification sent to the requesting task.

Sharing presentation does not make it an Ask. It is absent from cockpit ask list, cannot be answered with cockpit ask answer, and is never sent to Discord or Slack. It also does not fire an ask.* Hook or cockpit.ask.resolved event and accepts no attachments. Never put a password or another secret in an Ask answer; use the dedicated input request. See Security and data for destination and storage boundaries.

Question and answer formats

Ask can combine:

single choice
multiple choice
free-form input
several related questions
an outcome or trade-off description for each choice
clickable HTTP or HTTPS URLs in the Ask summary or an individual question
image, audio, or video attached to the question
images, text, source code, JSON, CSV, PDFs, audio, video, or office documents attached to an answer

Free-form input is available by default even when choices are provided. Write the question so it can stand on its own: identify the subject, the current state, and the result of each choice.

For one question, a person can select an option and add free text as a condition, reason, or supplement before sending. Cockpit keeps the selection and text as separate structured fields in the same answer. For an Ask with two or more questions, a person can answer individual questions and add one reply addressed to the whole Ask in the same submission. A whole-Ask reply can also stand alone; when it is present, questions left blank remain unanswered instead of receiving an invented value. Without a whole-Ask reply, every question still requires an answer.

Desktop opens a clicked Ask URL in the system browser without navigating the Ask window. The PWA opens it in a new browser tab. Desktop accepts only http and https links from the Ask surface; other URL schemes are not opened.

Desktop and PWA Ask surfaces include a button that opens the task that created the question. Navigating there does not answer or close the Ask. The button is unavailable after the source task has been deleted.

In the PWA task list, a question bubble labelled Waiting for an Ask answer identifies a task with an unanswered Ask. It follows the open Ask itself rather than an ordinary task question state, and disappears after the Ask is answered or closed. The task row still opens task details; answer the Ask from Inbox in the PWA.

When switching to another Ask in the PWA, the question starts at the top and the media strip starts at its left edge. An update to the same Ask does not reset your reading position.

Review an HTML explanation

An Ask can include an HTML explanation when a comparison table, design options, or a before-and-after preview makes the choice easier to understand. The dedicated Desktop Ask window, the right-side-panel Ask tab, and the PWA Inbox show it in a bounded, independently scrolling area between the summary and choices. If loading fails, the question and answer controls remain available and the explanation can be retried.

The explanation is not an answer surface. Scripts, forms, and data-cockpit-action do not run, CSS stays isolated, and only HTTP or HTTPS links open in the system browser. Submit the answer through the existing Ask choices and inputs. Discord, Slack, Hooks, and cockpit ask list do not receive the HTML body, so put anything essential to the decision in the summary or choice descriptions too.

From the CLI, supply exactly one of --html, --html-file, or --html-stdin, with a 512 KiB UTF-8 limit. Cockpit copies the content when the Ask is created, keeps it with the open Ask across restarts, and deletes it when the Ask is answered or closed. See the cockpit ask reference for exact input rules.

Review the answer order by priority

Each Ask has a priority that describes how urgently its answer is needed, not how important the task itself is. Omitting it uses medium.

Value	Label	Use when
`low`	Low	A suggestion, optional check, or question that can wait or be worked around
`medium`	Normal	An ordinary decision. This is the default
`high`	High	A late answer misses a deadline or holds up several tasks or people
`xhigh`	Urgent	A late answer lets an outage, data loss, or financial loss grow

The Desktop Ask tab and dedicated windows, the PWA Inbox, Discord, and Slack show the priority label. Waiting lists put Urgent, High, Normal, then Low first, with older Asks first within one level. Low never skips or auto-answers an Ask and does not change how the task resumes.

Do not use High or Urgent merely because the agent's own task is waiting. For either level, begin the question with a short reason such as the deadline or the impact of delay.

Review Asks on Desktop

The right-side-panel Ask tab lists every Ask waiting for an answer on this device. Open it from its count badge to answer or close an Ask with the same choices, free-form input, multi-question and whole-Ask replies, attachments, and media as the dedicated window. From the CLI, use cockpit side-panel ask.

By default, Cockpit also opens a dedicated window for every new Ask. Turn off Ask windows on this device under Settings → Notifications to close open Ask windows without closing their Asks or changing relay and answer delivery. Continue answering from the side-panel Ask tab, PWA, CLI, Discord, or Slack. The preference is stored per device. Turning it back on reopens windows for Asks that are still waiting. From the CLI, use cockpit settings set notifications.askWindow false or true.

Hide for now in the dedicated window hides only that window for the current app session. It does not close the Ask or resume its task. While the Ask-window setting is on, use Open in a separate window in the side panel to show it again. Close is a separate operation that removes the Ask itself.

Selections, free-form input, a whole-Ask reply, and attachments are shared between the dedicated window and the side panel before submission. Editing either view updates the latest draft for that Ask in the other. This sharing is limited to an unanswered Ask inside the same Desktop app; it does not synchronize an unsent draft to the PWA, CLI, Discord, Slack, or another device. Answering or closing the Ask discards the draft, and it does not persist after the app exits.

When several dedicated windows are open, higher-priority Asks start in front. An Ask or Display notice that the user clicked or operated with the keyboard, or an Ask opened from the side panel, stays in front when a new Ask arrives. Restacking the windows does not move keyboard focus.

Adjust the Ask window

Drag the handle in the lower-right corner of a Desktop Ask window to change its width and height. Cockpit saves that size for the next Ask window and constrains it to the screen's working area.

Use A− and A+ in the header to change the text size of questions, choices, descriptions, and input fields. This is the same chat text-size setting exposed under Settings → Display, so a change also applies to other Ask windows and the main conversation view.

In the PWA Inbox, the Ask summary, questions, choices, descriptions, and the HTML explanation's base text follow that same chat text size. A font size explicitly authored in the HTML remains unchanged. Text inputs keep a 16 px minimum to prevent mobile browser focus zoom. Long choices and unbroken strings wrap inside their answer cards instead of overflowing horizontally.

What happens before and after an answer

The agent creates an Ask.
Cockpit saves the question and displays it in the Desktop Ask tab, in an Ask window when enabled, and in the PWA. When an Ask relay is enabled, it also posts to the configured Discord or Slack channel.
A person answers with a choice, optional supplementary text, an optional whole-Ask reply for a multi-question Ask, and supported file attachments as needed.
Cockpit delivers a cockpit.ask.resolved event to the original task.
The agent receives the answer and continues the same work.

Until the answer reaches the task, the queue labels it as an Ask and summarizes its selections, free-form input, and attachments first. After delivery, the conversation history also presents the answer first; expand Question and details to inspect the original question, responder, and raw payload.

If the task is running, the answer enters the shared Queue as Answered · waiting to send and leaves the open Ask list. On Desktop and the PWA, surfaces with interrupt support offer the lightning button, Interrupt and send this queued message now, to send the selected answer immediately. Its structured answer, responder, and attachments stay intact, and the remaining queue order is preserved. A pending approval, tool question, or unavailable session shows a reason and leaves the answer queued for automatic delivery. Answers cannot be edited or removed; sending, delivered, and unconfirmed answers cannot be interrupted again. See Task details for recovery after failed or unconfirmed delivery.

Closing an Ask without answering removes the Ask, but it does not resume the original task automatically. A person can resume the task later with a normal message if needed.

Answer attachments can be added with the paperclip or by dragging files onto the answer surface. With multiple questions, a drop attaches to the question under the pointer; a drop elsewhere attaches to the first question. Dropping files never submits the answer.

Relay Asks to Discord and Slack

In Desktop, Settings → Ask notifications configures Discord and Slack independently, and both can be enabled at the same time. Both are off by default. Cockpit makes outbound connections to the Discord Gateway or Slack Socket Mode.

For Discord, create a bot in the Developer Portal, paste its token, and invite it to the server. For Slack, create an app from the manifest copied from Settings, then paste its bot token (xoxb-) and an app-level token (xapp-) with connections:write.
Choose the destination channel and one Who can answer user. The relay does not start without an allowed user, and Cockpit refuses interactions from other server or workspace members.
Optionally choose whether to send Ask images and videos and whether files posted in the channel by the allowed user can be attached to the answer.
Send a Test Ask, answer it from the selected service, and confirm that a round-trip time appears before enabling the relay.

Buttons, select menus, and free-input modals can answer an Ask. A multi-question Ask is submitted only after every question has an answer. Answering or closing from Desktop, the PWA, CLI, Discord, or Slack updates the other relayed messages to Answered or Closed. Discord displays the first 25 choices and Slack the first 100; use a Cockpit surface when the needed choice is beyond that service's limit.

After a temporary Discord disconnect, Cockpit resumes the same Gateway session when possible and receives events delivered during the gap. Cockpit still applies an Ask answer when Discord cannot acknowledge the button interaction, including when Discord's three-second response window has expired. Discord may show that the interaction failed; use the Ask message's answered state and Cockpit's state as the result.

The CLI can inspect connection state and run the same round-trip test:

cockpit ask relay status --verbose
cockpit ask relay test discord
cockpit ask relay test slack

Constraints

A task can hold only one active Ask at a time.
A completed task cannot create an Ask.
Ask is available to resumable AI-agent tasks, not Terminal tasks.
After creating an Ask, the agent waits and does not continue work that depends on the answer.
A question can attach up to eight files, with a limit of 512 MB per file and 1 GB in total.
Answer attachments have the same eight-file, 512 MB per-file, and 1 GB total limits. A JSON file is limited to 25 MB.
Archives and executable formats are rejected. Cockpit validates the extension, MIME type, actual size, and content, and stores the upload under a randomized name rather than its original file name.
Cockpit does not expand attachment contents into the prompt automatically. The agent receives a local path and metadata for the name, MIME type, and size.

Create an Ask from the CLI

cockpit ask \
  --summary "The production release is ready. All tests passed and only documentation changed. Publish it?" \
  --priority high \
  --choice "Publish" \
  --choice-description "Commit, push, and deploy to production" \
  --choice "Revise" \
  --choice-description "Do not publish and wait for another instruction"

cat summary.md | cockpit ask --stdin --choice "Publish" --choice "Revise"
cockpit ask --summary-file summary.md --questions-file questions.json

Pass a multiline summary or text that the shell could interpret with --stdin or --summary-file. A multi-question JSON array can also come from --questions-stdin or --questions-file. Only one value can consume standard input, so use a file for one part when both the summary and questions need external input. Do not combine command-line, standard-input, and file sources for the same value.

When JSON is passed through --summary, --summary-file, or --stdin, Cockpit recovers a structured Ask only from a strict supported shape. It accepts a Cockpit Ask object with summary and choices, or a Claude Code AskUserQuestion object or bare questions array, including fenced JSON. JSON whose types or structure cannot recover choices, descriptions, and single- or multi-select mode remains visible as the summary instead of being converted. Prefer explicit --choice or --questions-stdin input for ordinary use.

When the command succeeds, it returns an Ask ID. The agent ends its turn at that point and does not poll for the answer.

Use --priority low|medium|high|xhigh to set the priority. cockpit ask list returns priority for each Ask. An unsupported value prevents creation.

Operate open Asks from the CLI

Starting with v4.39.0, the CLI can list, answer, or close open Asks in addition to creating them.

cockpit ask list
cockpit ask list --task <task-id>
cockpit ask answer <ask-id> --choice "Publish"
cockpit ask answer <ask-id> --choice "Publish" --input "Ask me again before changing production data"
cockpit ask answer <ask-id> --question approach --choice "Plan A" --question environment --input "Staging first" --whole-answer "Finish before Friday"
cockpit ask answer <ask-id> --input "Review the image" --attachment ./screenshot.png
cockpit ask close <ask-id>

Add --host <host-or-alias> to list, answer, or close to operate an Ask on another registered Cockpit computer. The target must have member-only Remote Access enabled. Remote control authenticates like remote tasks: a computer on the same tailnet with the same Tailscale owner needs no token, and other connections need the paired bearer token. In Tailscale-only mode, connections that are neither a Tailscale peer nor loopback are refused. Ask creation and relay settings remain local-only. Paths passed to --attachment refer to files on the target computer.

list inspects the question, choices, and attached-media metadata. answer acts on the user's behalf and resumes the task that created the Ask. For one question, combine --choice or --choice-index with --input to send a selection and supplementary text together. For several questions, group answers under --question <id> and add --whole-answer when one reply should apply to the Ask as a whole. --attachment imports a local file into the originating task's managed uploads and delivers it in the same format as a UI answer attachment. In a multi-question answer, place the attachment after its target --question; an attachment before the first group belongs to the whole-Ask reply.

Use proxy answering only when the answering agent has both the context and the authority to relay the decision, such as a voice agent conveying an explicit answer from the user. Do not answer an Ask with media until the user or proxy has actually inspected that media.

close removes an unanswered Ask without resuming its originating task. Use it to clear a stale Ask, not to bypass a decision that still needs an answer.