> ## Documentation Index
> Fetch the complete documentation index at: https://docs.littlespaces.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports and asks: how agents tell you what they need

> What a report from an agent contains, the four kinds of ask (question, approval, review and merge), and how long each ask stays open in Little Spaces.

Agents send Little Spaces a **report** at each milestone of their work, and attach an **ask** to a report when they need something from you. This page explains what a report holds, the four kinds of ask, how an agent says how urgent an ask is, and when an ask closes.

## Reports

A report is a short factual note from the agent: what happened, in a sentence or two, with the project, the session it came from (its run ID) and the app that sent it. It can also say what happens next and link the pull requests or issues it is about.

Agents connected through the [Agents page prompt](https://docs.littlespaces.dev/quickstart.md) are told how to report when each session starts, so you don't set anything up. The [report fields](https://docs.littlespaces.dev/reference/report-fields.md) page lists every field and its limits.

Each report has a kind:

| Kind | Meaning |
| - | - |
| `started` | The agent began a piece of work. |
| `progress` | A step along the way. This is the default. |
| `finding` | The agent found something, such as the cause of a bug. |
| `output` | The agent produced something, such as a pull request. |
| `blocked` | The agent is waiting on something other than you: CI, another person or a service. |
| `finished` | The agent reports that its run is done. This is the agent's own account, not proof that a feature shipped. |

Reports are kept as they were sent. Little Spaces groups them into workstreams, which you can rename, move and merge in [Activity](https://docs.littlespaces.dev/how-it-works/views.md#activity).

## Asks

When an agent needs a decision, it adds an ask to a report. There are four kinds:

| Ask | What the agent needs | What you do |
| - | - | - |
| **Question** | An answer or a choice. | Pick one of its options, or write your own answer. |
| **Approval** | Permission to continue, for example to spend money, change scope or take a destructive step. | Approve or decline, with an optional note. |
| **Review** | Your review of a pull request. | Open the pull request from the card and review it on GitHub. |
| **Merge** | A pull request is ready and only needs merging. | Open the pull request from the card and merge it on GitHub. |

A good ask stands on its own, because you read it without the agent's transcript. It has:

* **The ask itself:** one line saying exactly what the agent needs.
* **A recommendation** (questions and approvals): what the agent recommends and why. When it names one of the options, the card marks that option **Recommended**.
* **Options** (questions only): two to six answers the agent can act on. You answer with one click, and the agent receives that option's exact text.

The agent is also told to state each ask in full in its reply to you, so you never need Little Spaces to read it.

### How urgent it is

An agent can say how much an ask matters, and the inbox sorts by it:

* **Stopped:** the agent cannot go on until you answer, with a line saying why. The thread goes under **Stopped on you**.
* **Holds up:** up to five short names of the work waiting on the answer, while the agent carries on with the rest. The thread goes under **Holding up work**.
* **Neither:** the thread goes under **Waiting on you**.

A session whose app reports it is waiting for you (for a permission prompt, say) also goes under **Stopped on you** while it has no open ask.

### Several asks at once

A report can carry up to six asks. Each one can have a **key**, a short name such as `pricing-tier`, and asks with keys stay open side by side: each is answered, resolved and tracked on its own. At most one ask in a report goes without a key. A new question or approval without a key replaces the session's earlier one without a key; an ask with a key is never replaced.

## When an ask closes

**A question or approval** stays open while the agent keeps working and reporting. It closes when:

* you answer it, or mark it resolved;
* the agent withdraws it, or retires its key, because it no longer needs the answer;
* the agent reports that you answered it in the session itself (see [answering asks](https://docs.littlespaces.dev/how-it-works/answering-asks.md#answer-in-the-session));
* for an ask without a key, the same session raises a new question or approval without a key, which replaces it.

**A review or merge ask** is a hand-off:

* Without a key, it closes with the next report from the same session.
* With a key, it stays open while the agent keeps working, until its pull requests are merged or closed, the agent retires it, or you resolve it.
* Either way, it closes once every pull request it names is merged or closed.

### No longer waiting

Some asks stop needing you without closing. They move to a collapsed **No longer waiting** group, where you can still read, answer or resolve them:

* a question or approval whose session has ended, so it won't pick up an answer;
* a question or approval whose pull requests have all merged or closed since it asked;
* any ask whose session has ended or has no hooks, when nothing has been heard from it for over a day.

A session that is still live never ages out this way, however old the ask.

> [!NOTE]
>
> An answer is an instruction for that ask only. It grants nothing beyond what it says, and never approves other work.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.