The inquiry system allows agents to escalate decisions when they exceed their authority or need human input. Unlike talk_to, which delegates work to another agent, an inquiry asks a question and waits for a response.

Sending an inquiry

An agent sends an inquiry with a markdown-formatted question, optional suggestions, and a priority level:

response = await ctx.inquire(
    content_markdown="## Which database should I use?\n\nThe project needs a database...",
    suggestions=["PostgreSQL", "SQLite", "MongoDB"],
    priority="normal",
    timeout_hours=72,
)

print(response.text)             # The responder's answer
print(response.suggestion_index) # Index of the chosen suggestion, if any

Inquiry parameters

Parameter	Description
`content_markdown`	The question, formatted in Markdown.
`suggestions`	Optional list of 2-4 predefined options the responder can pick from.
`priority`	`"normal"` or `"high"`. High-priority inquiries generate more urgent notifications.
`timeout_hours`	How long to wait for a response before timing out.

Escalation chain

When an agent sends an inquiry, it travels up the hierarchy until someone responds:

Agent sends inquiry

The agent creates an inquiry and blocks, waiting for a response.

Supervisor receives it

If the agent has a supervisor, the supervisor receives the inquiry first. The supervisor can respond directly or escalate further.

Escalation continues upward

If the supervisor cannot handle the inquiry, it escalates to its own supervisor, and so on up the tree.

Human notification

If no supervisor can handle the inquiry, or the agent is the root agent, the inquiry becomes a push notification to the user's devices.

Authority boundaries

You can define an agent's authority scope during setup. The agent is instructed to escalate anything outside that scope:

ctx.setup(
    system_prompt="You are a backend engineer.",
    authority="You may refactor code and fix bugs. Escalate API changes and database migrations.",
)

The authority string becomes part of the agent's system prompt. When the agent encounters a task that falls outside its stated authority, it sends an inquiry rather than acting on its own.

Blocking behavior

Inquiries block the agent until a response is received. Plan authority boundaries carefully to minimize unnecessary escalations.

Inquiry with file context

Agents can attach file paths to an inquiry for additional context:

response = await ctx.inquire(
    content_markdown="This migration will drop the `users` table. Should I proceed?",
    suggestions=["Proceed", "Abort", "Modify migration"],
    file_paths=["/workspace/migrations/005_drop_users.sql"],
    priority="high",
)

The attached files are displayed alongside the inquiry in the d:spatch app, giving the responder full context without needing to look up the files manually.

Design considerations

Keep authority boundaries specific. Vague boundaries lead to either too many escalations or agents overstepping.
Use suggestions to constrain responses. When the decision is between a few options, suggestions make it faster to respond.
Set appropriate timeouts. Short timeouts for time-sensitive decisions, longer ones for architectural questions.

Inquiry System