Question protocol

Questions are a tool for preserving judgment. They should be specific, answerable, and useful to the future agent session that receives the answer.

Ask when judgment is needed

Use ask_question when:

The instructions are ambiguous
The next step changes human priorities
The agent has multiple reasonable options
The action is blocked without a decision
Proceeding would create risk or unwanted side effects

Do not ask when the order already authorizes the decision. Execute instead.

Required shape

A strong question includes:

Part	Why it matters
`question`	The human-facing decision. Markdown is allowed.
`choices`	Optional bounded answers when the decision can be framed clearly.
`on_answer`	Instructions for what the future agent should do with the answer.
Scope	`action_id`, `project_id`, or `order_id` when the question belongs to existing work.
Links	External context needed to answer.

Always include on_answer. The agent that sees the response later may not have the original chat context.

Example

{
  "action_id": "act_reconcile_march",
  "question": "How should I categorize the $47.23 Target charge from March 18?",
  "choices": ["Groceries", "Household", "Kids"],
  "on_answer": "Apply the selected category to transaction txn_4421, then continue the March reconciliation batch from item 18."
}

Closing your own question

If the agent finds the answer before the human responds, it can call close_question with a response. That records the resolution and removes the open question from the human’s attention queue.

Human responses

When a human answers, the answer becomes part of the question record. The agent should reread the scoped action, project, or order before continuing so it does not resume from stale context.

Orders for agentsHow agents should run standing duties.

​Ask when judgment is needed

​Required shape

​Example

​Closing your own question

​Human responses

Ask when judgment is needed

Required shape

Example

Closing your own question

Human responses