cockpit ask

このReference本文は、アプリが配布するcockpit CLIヘルプと同じ英語の正本から自動生成されています。日本語の概念説明と安全な使い方はcockpit CLIを参照してください。

list, answer, and close support --host <host|alias>, --port, and --https, and preserve device: { host, ip, name } in remote responses, including authentication failures while looking up an Ask to answer. Ask creation and relay commands remain local-only and return host_not_supported with --host, naming the unsupported operation as ask create or ask relay.

Remote Ask control authenticates like remote task commands: a verified Tailscale peer with the same owner, or a loopback connection, needs no token; any other connection needs a paired bearer token in AGI_COCKPIT_TASK_REMOTE_TOKEN or AGI_COCKPIT_SYNC_TOKEN. The target's Tailscale-only restriction still applies. Answer validation and the rule against a task answering its own Ask also apply remotely. Answer attachment paths refer to files on the target host.

cockpit ask list --host build-host
cockpit ask answer <askId> --choice "Continue" --host build-host
cockpit ask close <askId> --host build-host

Usage: cockpit ask --summary <text> [--choice <text> [--choice-description <text>]]... [--multiple] [--priority low|medium|high|xhigh] [--title <title>] [--directory <path>] [--media <path>]... [--html <html>|--html-file <path>|--html-stdin]

Operate open Asks: cockpit ask list [--task <taskId>] / cockpit ask answer <askId> ... / cockpit ask close <askId> | --all | --task <taskId> (see "Operating asks" below).

Inspect and exercise the Discord and Slack relays: cockpit ask relay status [discord|slack] [--verbose] / cockpit ask relay test [discord|slack] (see "Relaying asks to Discord and Slack" below).

Schedule a persistent question for the user. The command returns immediately with an Ask ID; Cockpit keeps the question until the user answers or closes it. Answering resumes the same task automatically. The desktop close button (including its tooltip) and the PWA action are labeled Close (閉じる in Japanese). Closing removes the Ask without sending a message or resuming the waiting task. Free-form input is enabled by default for every question.

Answering saves the response before delivery. If queue registration fails, the saved answer remains in the open Ask list until registration succeeds; re-presentation and restart retry registration of that original answer. If the task is running, the answer joins the same persistent message Queue as ordinary queued messages. Desktop and Remote Access show the same registration order, question/answer details, attachments, and delivery state. Closing a client or restarting Cockpit does not discard registered answers. Queue entries send one turn at a time; accepting a send is not turn completion. An idle task with an empty Queue receives the answer immediately through this same path.

An Ask answer in the Queue is already answered, so it no longer appears in the open Ask list. Its structured cockpit.ask.resolved event, responder provenance, per-question answers, whole answer, and attachments remain intact. Ask Queue entries can be inspected and a known failed delivery can be retried; they cannot be edited, removed, or sent as an interrupt. Ordinary queued messages retain their edit, remove, and explicit Send now actions. Unconfirmed delivery stays visible and blocks automatic resend to prevent duplicates. After checking the conversation, use Mark as handled without resending for a failed or unconfirmed item to unblock the next item without sending that answer again. Accepted items remain delivered across restart; retiring their runtime releases the queue without resending them. Native permission and tool-question responses, and Asks with delivery: none, keep their own response contracts. Completing or deleting a task cancels its remaining Queue without marking those answers delivered.

After a successful cockpit ask, end the current agent turn. Do not poll, call wait, or continue work that depends on the answer. Only one Ask can be active for a task at a time.

cockpit ask --summary "Choose the deployment target" --choice "staging" --choice "production"
cockpit ask --summary "Select checks to run" --choice "lint" --choice "tests" --choice "build" --multiple
cockpit ask --summary "Choose checks" --choice "lint" --choice-description "Fast syntax and style checks" --choice "build" --choice-description "Production build verification" --multiple
cockpit ask --summary "Enter the branch name"
cockpit ask --summary "Release checklist" --question "Deployment target" --question-choice "staging" --question-choice "production" --question "Run migrations?" --question-choice "yes" --question-choice "no"
cockpit ask --summary "Release checklist" --question "Deployment target" --question-choice "staging" --question-choice "production" --question "Checks to run" --question-choice "lint" --question-choice "tests" --question-choice "build" --question-multiple
cockpit ask --summary "Does this design look correct?" --choice "yes" --choice "no" --media screenshot.png
cockpit ask --summary "Which design should ship?" --html-file comparison.html --choice "A" --choice "B"
cat comparison.html | cockpit ask --summary-file question.md --html-stdin --choice "A" --choice "B"
cat summary.md | cockpit ask --stdin --choice "yes" --choice "no"   # Long summary, no shell quoting
cockpit ask --summary-file summary.md --questions-file questions.json
cat questions.json | cockpit ask --summary-file summary.md --questions-stdin

Long summaries and shell quoting:

A summary that spans several lines or contains backticks, quotes, $, or a code fence must not be embedded in --summary "...". The shell runs backticked spans as command substitution and rewrites $... before cockpit receives the argument, so the question arrives damaged, and an unbalanced quote aborts the command so no Ask is created at all. Pass it with --stdin or --summary-file <path> instead; both deliver the text byte for byte.

There is only one standard input, so --stdin fills the summary, --questions-stdin fills the --questions JSON array, and --html-stdin fills the HTML explanation — use at most one of them per command. To keep both long parts free of the shell, combine --summary-file with --questions-stdin (or use --questions-file). Inside the JSON array, quoting is JSON's problem rather than the shell's, so question summaries, choices, and choice descriptions can contain anything.

Options:

• Pass choices with repeated --choice (or --question-choice) flags so each choice is a separate argument.
• Add --choice-description immediately after a --choice, or --question-choice-description immediately after a --question-choice, to show explanatory text under that choice.
• Bundle related decisions into one dialog with repeated --question "..." --question-choice "..." groups instead of asking one by one. Use --question-multiple after a --question for a per-question multi-select.
• --multiple makes the top-level single question multi-select.
• --questions '[...]' also accepts a JSON array where each item can include choices: string[], choiceDescriptions: Record<string,string>, and multiple: true. --questions-file <path> and --questions-stdin read the same array without going through the shell.
• --summary, --summary-file, and --stdin are mutually exclusive, as are --questions, --questions-file, and --questions-stdin; passing two sources for the same value fails instead of silently picking one. --stdin with nothing piped in fails immediately rather than waiting for input.
• --media <path> attaches files and can be repeated. Supported: png, jpg, jpeg, gif, webp, mp3, wav, ogg, aac, m4a, flac, mp4, webm, mov.
• Up to 8 media files can be attached. Each file can be up to 512 MB, with a 1 GB total per Ask. Files are uploaded as streams and loaded only when the Ask is viewed.
• --stdin, --summary-file, and --summary carry the summary text only. Choices never travel through them: give choices with --choice, or put a question array in --questions-stdin / --questions-file.
• Recovery fallback, not an input format: if a JSON blob does arrive as the summary, two shapes are recovered into a structured Ask instead of being shown raw — the Cockpit Ask shape {"summary": "...", "choices": ["a", {"label": "b", "description": "..."}], "multiple": false, "title": "..."} (multiple and title optional) and Claude Code AskUserQuestion JSON ({"questions":[{question, header, multiSelect, options[{label, description}]}]} or the bare questions array), either optionally wrapped in a fenced code block. Do not rely on this; pass choices with --choice or --questions-stdin. Any other JSON, including one of these shapes with a wrong field type, is shown verbatim.
• Legacy --choices "a,b,c" and --question-choices "a,b,c" are comma-separated only; do not use | as a separator.

HTML explanation:

Add an HTML explanation when the decision is easier with a comparison table, design options, or a before/after preview in view. Pass it with exactly one of --html <html>, --html-file <path> (--file <path> is the same option, as in cockpit display), or --html-stdin. It is optional; an Ask without it works exactly as before.

• The desktop Ask window, the side panel Ask tab, and Remote Access show the explanation between the summary and the choices, in a bounded area that scrolls on its own so the choices, free-form input, and Submit stay reachable. The answer still comes only from those existing controls, and the cockpit.ask.resolved event never contains the HTML.
• The explanation is display-only, rendered the same way as an HTML cockpit display: scripts and forms do not run, data-cockpit-action does nothing, its CSS stays inside its frame, and http and https links open in the system browser. It cannot answer, submit, or operate Cockpit.
• Keep --summary as the short question. Discord and Slack relays, Hooks, and cockpit ask list carry the summary, questions, and choices, plus htmlExplanation: { size } in list and Hooks, never the HTML itself; the relays add a line saying the explanation is viewable in Cockpit. Put anything the answer must not miss in the summary or choice descriptions too.
• Cockpit copies the HTML when the Ask is created, so later edits to the source file do not change it. It is kept with the open Ask across restarts and deleted once the Ask is answered or closed. Clients load it on demand, so large explanations do not slow Remote Access sync.
• The limit is 512 KiB of UTF-8. Larger, empty, whitespace-only, missing, or unreadable input fails before anything is created, with code ask_html_too_large, ask_html_blank, file_not_found, file_empty, or stdin_no_input. Attach large screenshots with --media instead of inlining them.
• If an open Ask's explanation cannot be loaded, the Ask says so and offers Retry; the question and answer controls stay usable.

Priority:

--priority tells the user which open Ask to answer first. It describes how urgently this answer is needed, not how important the task is. Omitting it means medium.

• Being blocked yourself is not a reason for high or xhigh; almost every Ask blocks its own task.
• With high or xhigh, start --summary with the reason in one short sentence: the deadline or the impact, for example "The release window closes at 15:00".
• Priority never changes how the Ask works. A low Ask still waits for an answer, is never skipped or auto-answered, and resumes the task the same way. It never moves keyboard focus, never reopens an Ask window the user hid, and never raises a window above the level every Ask window already uses.
• On the desktop and in Remote Access, each Ask shows a priority badge with its label, and lists show xhigh, high, medium, then low, oldest first within one level. When several Ask windows appear together, higher priorities are stacked in front, but the window the user last clicked or opened stays in front and a new Ask never covers it. Discord and Slack messages show the label too. cockpit ask list returns priority on each Ask.
• Any other value fails with code: "option_value_invalid" and no Ask is created.

cockpit ask --summary "Production checkout returns 500 for every user since 14:02. Roll back release 4.12?" --choice "Roll back" --choice "Keep investigating" --priority xhigh
cockpit ask --summary "The release window closes at 15:00. Ship with the known layout glitch on Safari?" --choice "Ship" --choice "Postpone" --priority high
cockpit ask --summary "Rename the helper to formatDuration while I am here?" --choice "Rename" --choice "Leave it" --priority low

Writing self-contained asks:

The user answers from the dialog alone — often from a phone notification, without the chat view open. Assume nothing you wrote in the chat has been read.

• Put everything needed to decide into --summary: what you were doing, what you found, and what happens after each answer.
• Never refer to the chat ("as shown above", "the error I mentioned", "option B from my last message"). Name things concretely: file paths, branch names, URLs, error text, numbers.
• Give each non-obvious choice a --choice-description that states its consequence or trade-off, so the choice labels can stay short.
• When the decision hinges on something visual, attach it with --media instead of describing it.

Bad: --summary "Which approach should I take?" --choice "A" --choice "B"

Good: --summary "The signup form (src/pages/Signup.tsx) fails validation on empty email. Fix by validating in the frontend or the API?" --choice "Frontend" --choice-description "Faster feedback in the form; API stays unchanged" --choice "API" --choice-description "One source of truth; every client gets the fix"

Immediate command response:

{"ok": true, "data": {"askId": "ask_abc123", "status": "scheduled"}}

When the user answers, Cockpit starts a new turn in the originating task with a compact, language-independent cockpit.ask.resolved JSON event. The original question is not repeated because it remains in the task context. The event includes answered_by showing who answered: "user" for the Ask window, the side panel Ask tab, or PWA, a task ID for another Cockpit task answering via CLI, or "cli" for a task-external process such as a voice agent.

Free-form input produces:

{"event":"cockpit.ask.resolved","version":1,"ask_id":"ask_abc123","outcome":"answered","answers":[{"type":"input","value":"Use blue"}]}

The user can attach supported images, text and source files, JSON, CSV, PDFs, audio, video, and office documents to any answer. Archives and executable formats are rejected. Attachments arrive as absolute paths in attachments with display name, MIME, size, and kind in attachment_metadata. File contents are never expanded into the event:

{"event":"cockpit.ask.resolved","version":1,"ask_id":"ask_abc123","outcome":"answered","answers":[{"type":"input","value":"Review this report","attachments":["/tmp/agi-cockpit-uploads/5c1f.../upload_a1b2c3d4.pdf"],"attachment_metadata":[{"id":"upload_a1b2c3d4","path":"/tmp/agi-cockpit-uploads/5c1f.../upload_a1b2c3d4.pdf","name":"report.pdf","mime":"application/pdf","size":245760,"kind":"pdf"}]}]}

question_id is present only on per-question answers of a multi-question Ask, where it preserves the correspondence between questions and answers; a single-question answer and a whole-Ask reply (below) omit it. Answers use choice, choices, input, or whole_answer:

{"event":"cockpit.ask.resolved","version":1,"ask_id":"ask_abc123","outcome":"answered","answers":[{"question_id":"target","type":"choice","value":"staging"},{"question_id":"checks","type":"choices","values":["lint","tests"],"input":"typecheck"}]}

A selection and free text on the same question arrive in one entry and stay separate fields: value (or values) is the selection and the optional input is the free text the user added to that question as a supplement, condition, or reason. input on a choice entry is present only when the user wrote something, so a choice-only answer keeps the shape above. An input entry is free text with no selection.

{"event":"cockpit.ask.resolved","version":1,"ask_id":"ask_abc123","outcome":"answered","answers":[{"type":"choice","value":"Plan A","input":"Check with me once before publishing"}]}

For an Ask with two or more questions, the user can also reply to the whole Ask — for example when the premise behind the questions is wrong, one explanation covers all of them, or an instruction applies on top of the individual answers. That reply arrives as a single whole_answer entry with no question_id. Treat it as the answer to the Ask as a whole, not to any one question. It may carry attachments and attachment_metadata like input:

{"event":"cockpit.ask.resolved","version":1,"ask_id":"ask_abc123","outcome":"answered","answers":[{"type":"whole_answer","value":"Neither applies: the release is postponed until the migration review finishes"}]}

The whole-Ask reply can accompany per-question answers in the same event. The per-question entries come first with their question_id, and the whole_answer entry is last with none, so the three parts never share a field: the selection is value/values, the per-question free text is that entry's input, and the Ask-wide reply is the whole_answer entry's value. When a whole-Ask reply is present, the user may have left some questions blank; those questions have no entry, and nothing is filled in for them.

{"event":"cockpit.ask.resolved","version":1,"ask_id":"ask_abc123","outcome":"answered","answers":[{"question_id":"approach","type":"choice","value":"Plan A","input":"Keep the old endpoint for one release"},{"question_id":"environment","type":"input","value":"Development first"},{"type":"whole_answer","value":"Have this ready before next week's review"}]}

Closing the dialog without answering removes the Ask without sending a message to the agent or resuming the task. The task can still be resumed later with a regular user message.

cockpit ask requires a Cockpit task context so the later response always has one unambiguous destination. It is available for resumable agent tasks, not Terminal tasks, because Cockpit cannot safely restore a Terminal shell and deliver the continuation to the process that created the Ask.

Operating asks:

list, answer, and close operate Asks that other tasks created. They exist so an agent can act as the user's proxy — for example a voice agent relaying the user's spoken decision, or a coordinating task resolving a subtask's question it clearly has the context and authority to decide. Never answer an Ask just to clear it; when in doubt, leave it for the user.

cockpit ask list                                  # all open Asks with questions, choices, and media metadata
cockpit ask list --task task_3                    # only Asks from one task
cockpit ask answer ask_abc123 --choice "staging"  # answer a single-question Ask
cockpit ask answer ask_abc123 --choice-index 1    # same, by 1-based choice number
cockpit ask answer ask_abc123 --input "Use blue"  # free-form answer
cockpit ask answer ask_abc123 --question target --choice "staging" --question checks --choice "lint" --choice "tests" --input "typecheck"
cockpit ask answer ask_abc123 --choice "Plan A" --input "Check with me before publishing"  # selection plus free text on the same question
cockpit ask answer ask_abc123 --whole-answer "Neither applies: the release is postponed"  # one reply to a whole multi-question Ask
cockpit ask answer ask_abc123 --question approach --choice "Plan A" --question environment --input "Development first" --whole-answer "Ready before next week's review"  # per-question answers plus a whole-Ask reply
cockpit ask answer ask_abc123 --input "See the screenshot" --attachment ./shot.png  # attach local files to the answer
cockpit ask close ask_abc123                      # close one Ask without answering
cockpit ask close --all                           # close every open Ask
cockpit ask close --task task_3                   # close all Asks from one task

• answer resumes the originating task exactly like a user answer, with answered_by in the event. A task cannot answer its own Ask (the server rejects it); closing its own Ask is allowed.
• Multi-question Asks must be answered in one command: prefix each answer group with --question <questionId> (ids come from list). Multi-select questions accept repeated --choice.
• --choice (or --choice-index) and --input may be given together for one question when it accepts free-form input: the selection arrives as value/values and the text as input on the same entry. Either one alone works as before.
• --whole-answer <text> replies to a whole multi-question Ask; it arrives as one whole_answer entry with no question_id. Alone, it answers the Ask without answering each question. Combined with --question groups, both are delivered in one event, and the groups may then cover only some of the questions; without --whole-answer, every question still needs a group. With --whole-answer, --choice, --choice-index, and --input must follow a --question. The text must not be empty, and it is rejected for a single-question Ask (use --input). An --attachment placed before the first --question belongs to the whole-Ask reply, with the same limits as any other answer.
• --attachment <path> attaches a local file to the answer and repeats; inside a multi-question command, place it after the --question group it belongs to. Files are imported into the asking task's uploads and reach the task exactly like a UI attachment, in attachments with attachment_metadata. The same limits apply: at most 8 files per response across every question, all file types are accepted and stored unchanged, including archives and files with unknown extensions. An answer may consist of attachments alone when the question accepts free-form input; omit --choice and --input in that group.
• --choice must match the choice text exactly; use --choice-index (1-based, per list order) to avoid transcription mismatches. Mismatch errors return the valid choices.
• Asks with media are asking for a visual judgment. Do not answer one unless the content has actually been checked — by the user looking at the Ask window, or by you if you can view the files. If it has not been checked, tell the user it is waiting on screen instead.
• close never resumes the task; the asking task stays waiting until the user resumes it. Use it to clear stale Asks, not to skip questions that still need answers.
• If the user answers on screen first, answer returns {"ok":false} with "Ask not found" — that is a race, not a failure; check cockpit ask list for what is still open.

Where Asks appear on the desktop:

Each new Ask opens a small Ask window unless notifications.askWindow is false (Settings > Notifications, or cockpit settings set notifications.askWindow false). The side panel Ask tab (cockpit side-panel ask) always lists every open Ask and answers or closes it the same way the window does. Turning the window off never drops an Ask, its relay, or its answer handling. A new Ask also plays a short Ask chime, distinct from the general notification sound, unless notifications.askSound is false; it plays once per new Ask, even with windows off, and never again for the same Ask. Preview it with cockpit settings preview-sound ask.

Relaying asks to Discord and Slack:

Settings > Ask notifications forwards every Ask to a Discord channel, a Slack channel, or both, where buttons, select menus, and modals answer it through exactly the same path as cockpit ask answer, with answered_by set to discord or slack. Answering anywhere — the Ask window, the side panel Ask tab, Remote Access, the CLI, or the other relay — updates every relayed message to "Answered" or "Closed". Files the allowed user posts in the channel are staged and attached to the next answer. Both relays are off by default and connect outbound only, through the Discord Gateway and Slack Socket Mode.

cockpit ask relay status           # both relays: connected / reconnecting / stopped, target channel, last error, recent round trips
cockpit ask relay status slack     # one relay only
cockpit ask relay status --verbose # same, plus the tail of ~/.agi-tools/data/cockpit/logs/ask-relay.jsonl
cockpit ask relay test             # test every relay in parallel and report each one
cockpit ask relay test discord     # post a real test Ask and report the round-trip time once it is answered

status without a target reports both relays under discord and slack; with a target it reports that one. Each status carries state, error, botName, guildName (the Slack workspace name for Slack), channelName, the stored config, and the last 10 roundTrips; each round trip records who resolved the Ask, so an Ask answered on the desktop shows up there too. A round trip that never posted records status: "failed" with reason. --verbose adds logs, the recent structured Ask relay log lines (state transitions, post attempts with HTTP status, queue/drop events, test outcomes, Discord Gateway lifecycle events, and interaction handling) from ~/.agi-tools/data/cockpit/logs/ask-relay.jsonl. That file rotates at 5 MB and keeps two archives, like the other jsonl logs. A gateway line records hello, ready, resumed with the number of replayed events, reconnect_requested (op 7), invalid_session (op 9, with resumable), heartbeat_ack_missed, or closed, plus closedBy, closeCode, and sinceLastAckMs. An interaction line records received, acknowledged, ack_skipped (a button acknowledgement skipped because the interaction was over 30 seconds old), ack_failed (with httpStatus and Discord's apiErrorCode, such as 10062), in_flight, applied, or apply_failed, with the interaction's ageMs. Log lines carry IDs only, never tokens or message text. A button pressed while the Discord connection was briefly down is still applied when Discord delivers it, even after Discord's 3-second reply window has passed; Discord then shows that the interaction failed, and the Ask message itself shows the result. test posts a test Ask, starts the relay temporarily if it is configured but disabled, and blocks until the Ask is resolved or 5 minutes pass. test without a target exercises both relays at once and returns { discord, slack }, where each entry is either a result or { error, code } for a relay that refused the test. With a target it returns that relay's result directly. A test Ask is delivered only to the relay being tested. A result is { askId, answered, outcome, durationMs } where outcome is answered only for a real round trip through the tested relay; answering the same Ask on the desktop or in Remote reports answered_elsewhere, and dismissed, timeout, not_delivered, and superseded cover the other endings. The UI describes dismissed as closed. Existing HTTP /asks/<id>/dismiss, IPC/WebSocket ask:dismiss and ask:dismissed, hook event ask.dismissed, and stored/JSON dismissed outcome, reason, and status values remain unchanged for compatibility; the CLI verb is already close. A relay with no channel, no token, or no allowed answerer refuses the test instead of waiting. Changing the relay configuration while a test is waiting ends that test as superseded and does not later restart an already-enabled relay.

Configure the relays from Settings > Ask notifications. cockpit settings exposes the same values under notifications.askRelay.discord.* and notifications.askRelay.slack.*, and the tokens live only in the secure store. The relay answers only interactions from allowedUserId; clearing that key stops the relay rather than opening it to every member of the server. The bot needs View Channels, Send Messages, Attach Files, Add Reactions, and Manage Channels. If files posted in the channel are not picked up as answer attachments, enable the Message Content Intent for the bot in the Developer Portal — Discord omits attachments from gateway message events for some applications without it.

The Slack relay uses Socket Mode: create the app from the manifest offered in Settings, install it, and paste the bot token (xoxb-) and the app-level token (xapp-, scope connections:write). It posts Block Kit buttons, a multi_static_select for multi-select questions, and modals for free input, joins the chosen channel automatically, and stages files shared in the channel by the allowed user through files.info. Only the Slack user in allowedUserId can answer; everyone else gets an ephemeral refusal.

Example uses:

• Choose among multiple implementation approaches
• Gather information that requires user judgment, such as a deployment target or branch name
• Final confirmation before a destructive operation
• Review screenshots, generated images, audio, or video

Passwords and other secrets must use the separate cockpit secret request flow (cockpit help secret), which delivers once to a fixed browser password field and returns only status. Never put a secret in an Ask answer. A secure input request is shown in the same places as an Ask (its own window, the side panel Ask tab, and the PWA Inbox), but it is not an Ask: cockpit ask list never lists it, cockpit ask answer cannot answer it, Discord and Slack never receive it, and it never fires ask.* Hooks or cockpit.ask.resolved.