cockpit ask | AGI Cockpit公式ドキュメント

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

Usage: cockpit ask --summary <text> [--choice <text> [--choice-description <text>]]... [--multiple] [--title <title>] [--directory <path>] [--media <path>]...

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. Closing removes the Ask without resuming the task. Free-form input is enabled by default for every question.

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
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 and --questions-stdin fills the --questions JSON array — 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.

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 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"}]}]}

Single-question answers omit question_id. Multiple questions include it to preserve the correspondence between questions and answers. Answers use choice, choices, or input:

{"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"}]}

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 --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.
--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, supported images, text and source files, JSON, CSV, PDFs, audio, video, and office documents only; archives and executables are rejected. 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.

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, 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, and test outcomes) from ~/.agi-tools/data/cockpit/logs/ask-relay.jsonl. That file rotates at 5 MB and keeps two archives, like the other jsonl logs. 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. 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