docs(agents): ask takes an optional context, shown above the question

[ZIJ]

Symptom

An agent that reads code before asking tends to write its findings only in its thinking and call ask with no message. On Slack the question card then shows whatever the turn wrote before its first tool call, or nothing, above the question:

I'll take a look at the repo first.

Straight through to a draft PR, or show me the plan first?

The person sees the question without the findings it depends on. Rewording the agent's instructions did not change this across eight sessions; tool arguments, by contrast, are filled reliably.

The change (docs only)

Documents the new optional context argument of ask (diggerhq/blue#181):

• docs/agents/tools.mdx: the context row in the ask argument table (at most 4000 characters of Markdown: what the person needs to know to decide), and two sentences: on Slack it posts above the question in the same message, in place of the asking turn's text; Linear shows the question alone.
• docs/agents/events.mdx: question.asked carries context when the agent gave one.
• docs/agents/api.mdx: the session's question is { id, text, options, context?, askedAt }.

Not in this PR

The TypeScript SDK's SessionQuestion type (and the React hook's Question) do not name context yet. The SDK's shape validator passes unknown keys through, so the field already reaches callers untyped; typing it needs a version bump and follows separately (open draft #853 bumps those packages).

Merge order

Merge only after the blue change is deployed. Touches the same ask section as #852 and #851 but different lines.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
opencomputer	🟢 Ready	View Preview	Oct 8, 2026, 4:55 PM

💡 Tip: Enable Automations to automatically generate PRs for you.