Ask

When you want to know how the CSV export validates a date range, why the team chose one library over another, what an initiative actually says, or which plans drove the implementation of a feature you are about to touch, the answer is somewhere in your project. Some of it is in the code; some of it is in the planning records; the most useful answers are usually a thread that runs through both. You could grep the repo, click through the initiatives, and assemble the story yourself. Or you could ask.

Ask is the surface for that question. Ask is your "Ask the engineer": the platform's agent reads the actual code in your repo, reads the initiatives and plans that drove the implementation, and writes back a cited answer that ties the two together. You can ask a pure code question, a pure planning question, or the one that matters most for understanding a system: how does this work, and why was it built this way?

The agent is in read-only mode the whole time. Nothing in your work model changes, no plan gets created, no status gets flipped, no file gets edited. The answer is yours to read, save, or turn into a real piece of work later if you decide to.

Ask is deliberately a separate surface from Chat. Chat is multi-turn planning work where the agent can mutate records, kick off Flows, and write files in your sandbox. Ask is the inquiry that does not need to become a change, with a tool surface narrow enough that read-only is the structural truth of what the agent can do, not a promise we ask you to trust.

Ask vs Chat at a glance

The two surfaces share the same conversational shape and the same underlying chat infrastructure. They differ in the ceiling.

The same conversational shape; different ceilings.

What you can ask

Ask is built for three shapes of question. Most real inquiries land in one of them; the most useful inquiries land in all three at once.

Ask the codebase

How does the CSV export endpoint validate the date range parameter? Where is the timeout enforced? What's the largest range we test against?

The agent has the project's repo (or repos) mounted as a read-only inquiry workspace. It uses Read, Grep, and Glob to investigate the code the way an engineer would: search by pattern, enumerate files, read the relevant ones, and cite specific lines in its answer. There is no need to point the agent at a file; you describe what you want to understand and the agent finds the code.

The agent answers well when you describe a behavior, name a file you suspect, or anchor on a concrete code path. It does less well when you ask it to run the code (it cannot), reason about runtime values it has not seen, compare two branches (it sees only the default branch the workspace was cloned from), or infer intent the comments do not state.

This is the "Ask the engineer" mode. A new hire onboarding onto a codebase, an engineer about to touch unfamiliar code, a tech lead doing pre-PR review, a product manager confirming a behavior before talking to a customer: every one of these is a question the agent can answer by reading the real code, not by guessing at what the code probably does.

Ask the records

What's the current status and target date for the CSV Export initiative? What are the three plans under it? Which one is blocking the others?

The agent has the platform's planning records available through one tool, fetch_related_planning_artifacts: initiatives, plans, and the related-context graph around them (parent initiatives, sibling plans, historical context). It reads what you wrote, what your team wrote, what the agent wrote on previous turns, and writes back a summary with the records cited.

The records this tool reaches are initiatives and plans. Bugs, sprints, goals, test cases, documents, and other record types are not reachable through this tool today; if you need to know about a bug related to a feature, the Bugs tab on the initiative is the canonical place to look (or, if your team commits bug references into Markdown files in the repo, the agent will find them through Grep). The fetch is capped at six calls per turn, which comfortably covers an initiative plus its plans; a sweeping "show me everything in the project" inquiry will hit the cap and surface a partial picture.

This is the "verify before the meeting" mode. The records are the source of truth for what the team committed to; Ask makes them legible without you having to click through them yourself.

Tie code to decisions

Why does the export use streaming instead of buffered output? Which initiative drove that choice? Where in the spec was the decision made?

This is where Ask earns its keep. The agent reads the code, reads the planning records, and threads them together in one answer. The result reads as a paragraph or two that says the streaming implementation lives in server/reports/export.ts:120; it was introduced by the CSV Export on the Reporting Page initiative under plan CSV server endpoint; the design choice traces back to the open question in the initiative body about handling 200k-row exports.

A senior PM evaluating a feature, an engineer inheriting a codebase, a tech lead writing a quarterly retro: the answer to "how did we get here" is in the code and the records together, and Ask is the surface that returns both with one question.

Example questions by mode

Where Ask lives

Ask has its own area in the navigation. The list lives at Planning → Ask, with two tabs.

• Recent is the list of inquiry conversations you have opened. Your teammates' inquiries also appear here if your role grants conversations.read.any; without that scope you see only your own.
• Saved is the list of individual answers you have pinned for reference. Saved is per-user; the list shows your pins, not your team's.

The two tabs are two views over the same data. Recent counts whole conversations; Saved counts individual messages. A conversation can have zero, one, or many pinned messages; a pinned message keeps its parent conversation reachable from Saved even if it would otherwise drop off the bottom of Recent.

A single Ask opens at Planning → Ask → <conversation>. The page is a chat transcript scoped to one inquiry; you can ask follow-up questions in the same session and they continue the same conversation. The agent has the prior turn's context, so "Which plans are still in progress?" reads naturally after "What's the current status and target date for CSV Export?"

To start a new Ask, open the Ask area and type your question directly into the hero textarea on the empty state, or click "Ask a question" to land on a fresh conversation page with the input ready. The empty state also offers a small grid of suggested questions curated per project; clicking one starts a fresh inquiry with that question as the seed. To end an inquiry, open its detail page, click Delete in the page header, and confirm the inline prompt; the conversation is preserved for history while the sandbox is released. Inquiry conversations are project-scoped only; unlike Chat, they are not bound to a specific initiative or plan.

The read-only contract

Ask answers from a structurally narrower agent than Chat. The platform does not enforce read-only by promising not to call mutate tools; it enforces it by not handing those tools to the agent in the first place.

The tool ceiling

The agent in an Ask session can call six core tools. Three are platform tools the host runs:

• ask_user lets the agent pause and ask you a clarifying question with two to four choices. The Ask page shows the choices as buttons; your answer comes back as the user's reply and the agent continues.
• present_plan lets the agent pause and surface a structured summary for you to read. In Ask, this is most often used to lay out a multi-paragraph investigative answer with sources before continuing.
• fetch_related_planning_artifacts lets the agent read initiatives and plans, plus the related-context graph around them (sibling plans, historical context). The fetch is capped at six calls per turn so a single question cannot pull in unbounded planning context.

Three are sandbox tools the agent runs against a read-only inquiry workspace. The workspace is a fresh clone of every repo the project's sandbox profile defines (primary plus any context or reference repos), on the default branch, with no per-conversation branch and no platform planning artifacts materialized into it. These three are how the agent investigates the real code in your repo, the same way an engineer would:

• Read lets the agent read any file from the inquiry workspace.
• Grep lets the agent search the workspace by pattern. This is how the agent finds where a function is implemented, where a type is used, where a string appears in tests, where a config value is referenced.
• Glob lets the agent enumerate files matching a path pattern. This is how the agent finds the relevant files before reading them.

That is the surface. The agent does not have Write. It does not have Edit. It does not have Bash. It does not have TodoWrite or WebFetch. It does not have start_flow. It does not have any of the tools that create or update planning records. The list above is the structural ceiling, with one carve-out: if the project's resolved sandbox profile declares managed commands, the agent can also call managed_command_exec to run those commands. Managed commands are a sandbox-profile setting and are themselves bounded; they extend the baseline rather than dissolve it.

The fixed inquiry-mode investigator persona

The persona the agent runs as in an Ask session is also fixed. Every inquiry turn loads the built-in ask command template, which casts the agent as a read-only repo investigator with a set of standing instructions: cite every claim with a file path (and a line number when relevant), prefer admitting it does not know over guessing, ask clarifying questions when the request is ambiguous, summarize at the end of long answers, never propose code changes or mutate state, never run builds or tests, never pretend to have run something it did not, and never start a Flow. The persona is force-loaded; you cannot override it with a different command. One persona, one tool surface, one promise.

How citations work

Every Ask answer is supposed to carry its sources, and the inquiry-mode investigator persona is explicit about it: every factual statement about the code or the project references a specific file, with a line number where applicable, formatted inline in the answer's prose.

In v1 the citations land as plain text. A citation reads as path/to/file.ts:42 or path/to/file.ts:42-58 for a range, embedded in the assistant's sentence. The agent writes the citations the way it would write a footnote; the surface treats them as text. There is no clickable chip, no hover preview, no jump-to-source, and no automatic verification that the cited path exists in the workspace.

The plain-text rendering is the right model for v1 because the inquiry surface is for reading, not for navigation. A senior PM glancing at a pinned answer wants to read the text that summarized the work at the time; the click-through experience belongs to Chat, where the agent can act on a file and the affordance is meaningful. Structured citations are on the roadmap for a future release; v1 keeps the rendering simple and the snapshot stable.

The Recent and Saved lists

Recent is the working list. The toolbar carries a search input and a single "Asked by" filter populated from the unique askers across the loaded conversations. The list is scoped to your active project; switching projects switches the list. Click a row and the inquiry opens.

Saved is the reference list. Each row is an individual pinned answer, not a whole conversation, so a single conversation that produced three pinned answers shows up three times. The list is sorted by when each message was pinned; the same "Asked by" filter narrows by who did the asking. Click a row and you land on the parent conversation with the pinned answer highlighted.

Acting on an answer

An Ask answer often ends with the user wanting to do something with what they just learned. The page makes three follow-ups easy without making any of them the default.

Pin it

Inside an Ask conversation, every completed assistant message (that has actually rendered content; mid-streaming messages do not have it yet) carries a kebab menu on the right edge with five actions: Create Initiative, Create Plan, File Bug, Pin (or Unpin), and Copy text. The Pin gesture bookmarks the answer to your personal Saved list. The pinned message gets a gold left edge and a Saved badge on the message's action row, so you can see at a glance which answers in the thread are saved.

Ask a follow-up in Ask

Type the follow-up question into the input. The agent continues the same conversation, the prior turn's context is preserved, and the second answer can build on the first without you re-stating what you were asking about. This is the right path when the second question is also a question.

Move to Chat to act on what you learned

Use the kebab on the answer that prompted the action and pick Create Initiative, Create Plan, or File Bug. The action launcher opens as a slide-in drawer with the answer pre-filled as the starting context (the inquiry's title prefixes the description so the provenance reads inline). You accept the form, the record is created, and from there you can open Chat on the new record to give the agent the planning surface to do the work. The action launcher stages a source-conversation back-link on the new record today; the persistence onto the Initiative, Plan, and Bug schemas is a near-term follow-up that closes the provenance loop both ways.

The split between Ask and Chat shows up in this handoff. The platform never silently promotes an inquiry into an authoring session; you make the decision, the action launcher captures it, the new record carries the context.

Three worked examples

Sarah verifies an initiative before her meeting

Sarah is preparing for her Tuesday meeting with Marcus and wants to verify what the CSV Export initiative currently says before she walks in. She opens Planning → Ask and types into the hero textarea:

What's the current status and target date for CSV Export on the Reporting Page, and what plans are under it?

She hits Enter. The platform creates a new inquiry conversation scoped to the Insights project, routes her to the conversation page, and the agent starts working. The agent calls fetch_related_planning_artifacts twice (once for the initiative, once for its plans), reads the materialized records out of the inquiry workspace, and writes a two-paragraph answer with inline citations in the prose:

CSV Export on the Reporting Page is currently at status Approved, with target date 2026-06-30 (initiatives/csv-export.md:14). Three plans sit underneath it: CSV server endpoint (Implementation, Complete; plans/csv-server-endpoint.md:1), CSV download button (Implementation, In progress; plans/csv-download-button.md:1), and CSV format verification (Verification, Draft; plans/csv-format-verification.md:1). Plans progress reads 1 of 3 (33%) against the four shipped Plan statuses.

Sarah reads the answer, opens the kebab on it, and picks Pin. The message gets the gold edge and the Saved badge. She closes the tab.

Tuesday morning she opens Ask → Saved, clicks her pinned answer, and the conversation reopens with the pinned message highlighted. She wants one more thing before the meeting and asks a follow-up in the same conversation:

Which of those three plans is blocking the others?

The agent calls fetch_related_planning_artifacts once more, reads the plans' dependencies, and answers with another cited paragraph. She does not pin the follow-up because she only needed it for the meeting context. She closes the page; the conversation stays in Recent.

A new hire learns how authentication works

Maya is a new engineer on the Analytics team in her first week. She has been asked to add a new endpoint to the reporting service and wants to understand how authentication works in the app before she writes anything. She opens Planning → Ask and types:

How does authentication work in this app? Which middleware enforces it, and where do unauthenticated requests get rejected?

The agent runs Glob on server/auth/ to find the auth module, runs Glob on server/middleware/ to find the request-level enforcement, Greps for the relevant strategy registration, and Reads the three or four files that carry the answer. It writes back a paragraph that walks Maya through the strategy chain, names the middleware function that gates protected routes, points her at the bypass list for unauthenticated endpoints, and cites every file and line so she can open them in her editor next.

Maya pins the answer to her own Saved list (her pins are hers; nothing pollutes the team's view). She closes the tab and opens her IDE with confidence she did not have ten minutes ago. The agent gave her the tour an experienced engineer on the team would have given her, without taking that engineer's afternoon.

Priya investigates the export-timeout bug before she fixes it

Priya is the engineer assigned to fix the Export timeout on large date ranges bug. She has not worked on the export endpoint before and does not want to dive in blind. Before she opens her editor, she opens Planning → Ask and types:

How does the CSV export endpoint stream rows to the response? Where is the timeout actually enforced? And which initiative drove the streaming implementation in the first place?

She hits Send. The agent works through the question in two threads at once. On the code side it runs Glob to find every file under server/reports/, runs Grep for the export route handler, and reads the relevant source files with Read. On the records side it calls fetch_related_planning_artifacts to pull the initiative and plans that drove the export feature. After a handful of tool calls, the agent writes a two-paragraph answer with citations to both:

The streaming implementation lives in server/reports/export.ts:120, where the route iterates over the report query result set in chunks of 5,000 rows and writes each chunk to the response stream. The HTTP timeout is enforced by the Express server config at server/index.ts:48 (90 seconds), not inside the export route itself; the route does not currently respect a per-request timeout override. The streaming design was introduced by the CSV Export on the Reporting Page initiative under plan CSV server endpoint (now Complete); the choice to stream rather than buffer the full result was driven by the open question in the initiative body about handling 200k-row exports, which the team committed to before the implementation started.

Priya now knows three things she did not know thirty seconds ago: where the streaming code is, where the timeout is actually enforced, and that the team committed to the streaming approach for a documented reason she should not undo lightly. She glances at the initiative's Bugs tab in a separate browser tab to confirm her assigned bug is one of the open ones tied to this code path. She comes back to Ask, picks Pin on the answer so she can come back to the file references while she is in her editor, opens the kebab on the same answer, and picks Create Plan. The action launcher opens with the cited paragraph pre-filled and the parent initiative defaulted to CSV Export. She titles the new plan "Per-request timeout override for large exports" and accepts. The plan lands under the original initiative with the source-conversation context threaded in.

Priya is now ready to write code. She opens Chat on the new plan to give the agent the planning surface to break the work into steps. The whole loop, from "I have not seen this code before" to "I have a plan with the right context," took one Ask conversation; the agent never touched a file along the way.

Ask sessions in the broader picture

A finished Ask is a row in the unified Sessions list alongside your Flow runs and planning chats. From Sessions you can see your agent activity in one place and click into the inquiry detail the same way you would click into a Flow run.

The agent in an Ask session runs in a sandboxed container per session, the same way Chat and Flow runs do. The container is disposable, the agent has no host credentials, and the sandbox is destroyed when the conversation soft-ends. The narrow tool surface is layered on top of the same sandbox-isolation guarantees the rest of the platform relies on; together they form the structural reviewable-autonomy contract Ask presents to the planner.

Ask sessions consume AI spend the same way Chat does. Per-turn cost and token counts are tracked against your tenant's AI budget and visible on the Sessions detail page. The cost of a typical inquiry is small (one or two fetch_related_planning_artifacts calls plus a single response), but the spend is real and the budget applies.

Boundaries

A few things v1 does not do today. We list them so you can plan around them.

• Citations are plain text. Inline file paths render as prose, not as clickable chips with hover previews or jump-to-source. Structured citations are on the roadmap.
• A pinned answer is a snapshot of the agent's reading, not a live view. The save records the message id; if the underlying record changes later, the saved text is unchanged.
• Pins are per-user. There is no team-level pin today; if the team wants to share an answer, the conversation itself is shareable by URL to anyone with the right read scope.
• The "Asked by" facet only spans loaded conversations. It is populated from the rows on the current page, not from the tenant directory.
• Conversation kind is immutable. An inquiry conversation cannot be upgraded into a planning chat; create a new conversation on the affected record from the kebab menu instead.
• Inquiries are project-scoped. They are not bound to a specific initiative or plan; Recent cannot be filtered by record.
• Source-conversation back-links on created records are staged. The action launcher captures the link from the kebab; the persistence onto the Initiative, Plan, and Bug schemas is a near-term follow-up.
• The workspace is a clone of the default branch. Work in flight on feature branches is invisible until merge; the agent cannot read what is not on the default branch.
• The agent does not run the code. No build tools, no test runner, no Bash. The agent reads what is on disk; it does not execute to verify behavior.
• The workspace is per-conversation and disposable. The clone is a fresh snapshot at conversation start; if the repo advances during a long-running inquiry, the agent's view stays at the snapshot it cloned. By default the clone is shallow (depth 1); a workspace admin can switch the profile to full-history clones if your team needs the agent to walk git history.
• The 6-call fetch cap is per turn. A multi-turn inquiry can pull more planning context across turns; no single answer can fan out beyond six fetches.
• fetch_related_planning_artifacts reaches initiatives and plans only. Bugs, sprints, goals, test cases, and documents are not in the related-context graph today; the agent reads those records only if they appear in repo files the agent can Grep or Read.

Permissions

Opening Ask requires the standard chat.use scope, which ships on every content-facing built-in role. Listing your own conversations requires conversations.read.own, which is on every content-facing role. Reading or managing saved answers (the Saved tab) requires saved-answers.manage, which ships on Member, Lead, Workspace Operator, Admin, and Owner; Viewer, Planner, and Billing Manager do not have it by default and cannot pin answers or use the Saved tab. Reading inquiry conversations created by other users requires conversations.read.any, which ships on Lead, Admin, and Owner only; Member, Viewer, Planner, and Workspace Operator see only the inquiries they created.

A user without chat.use does not see the Ask area at all. Ask is also per-project: you need an active project selected to open it. A project without an associated sandbox profile cannot run inquiries; in that state the Ask area replaces its empty state with a "This project has no sandbox profile" card and an "Open project settings" button that takes you to the Projects list, where you can pick the project and configure a profile before returning to Ask.

Why the shape is what it is

A serious software organization needs a place to ask the engineer. Every team has a person who knows where the timeout is enforced, why the export streams instead of buffering, which initiative drove the design, and what plans are tied to the code path; the rest of the team interrupts that person to ask. The platform's answer is to make the agent that person, on demand, with access to the actual code and the actual planning records, and to put the conversation in a surface where the question stays a question.

The structural enforcement is what makes the surface trustworthy. If the only place that talks to the agent was one where the agent can change your work, every question would carry a small risk: maybe the agent helpfully edits something while you were just trying to understand. Giving the inquiry its own surface with its own tool ceiling means the question is a question and the answer is an answer, full stop. The agent reads the repo. The agent reads the records. The agent writes back a paragraph with citations. Nothing it does touches anything you did not ask it to touch.

For a senior PM evaluating Disco Parrot against tools that conflate inquiry with action, Ask is the answer to "can the agent read my work, my code, and the story between them without touching anything?" The answer is yes, because the agent cannot touch them; the tools that would let it are not on the surface. For an engineer about to inherit code they did not write, a tech lead doing pre-PR review, a product manager confirming a feature behavior before talking to a customer, a new hire onboarding onto a codebase, or a planner verifying a fact before a meeting, Ask is the place that respects every one of those gestures as legitimate ends in themselves. The handoff to Chat is one click away when the answer needs to become work; the handoff stays one click away rather than happening automatically. That is the design.