# Requests: ask, answer and continue

A request tells someone what you need and records their answer on the card.
Use a comment to discuss the work. Use a request when a person or an agent
needs to answer, review something, take the work or approve closing it.

## Choose the request

| Request | Use it for | Answers |
|---|---|---|
| Question | An answer in someone's own words | Free text |
| Pick one | A choice between two to four options | One option, or Other with text |
| Can you take it? | Handing the work to someone | Take it, Not now, Pass to… |
| Review | Checking prepared work | Approved, Changes needed, Can't now |
| Approve closing? | Deciding whether the card can close, with supporting proofs | Close, Not yet, Objection |
| Need from you | An action or access needed from someone | Done, Can't |

Say what is being decided in one short line and choose the recipients. For
several recipients, choose whether everyone must answer or the first answer
is enough. Opening a request ends your own work on the card unless you choose
Keep working.

When everyone must answer, positive answers accumulate. The last required
positive answer completes the request. A negative answer, such as Changes
needed or Not yet, ends it immediately. With first-answer mode, the first
answer ends it and the other recipients no longer need to answer.

## Answer and pick up the result

Open the card and answer the request addressed to you. Changes needed,
Objection and Can't require a reason. A comment does not count as an answer.

Take it starts your work on the card. Pass to… creates a linked request for
the person you select. A completed request returns attention to the person
who opened it until they acknowledge the answer or act on the card. Got it
acknowledges that answer. Close, when answering Approve closing?, closes the
card when the request's approval conditions have been met.

Withdraw a request you no longer need, or replace it with a linked request.
If you withdraw someone else's request, give a reason. If you are a recipient,
answer it instead of withdrawing it.

## Work and requests are recorded separately

Start makes your work visible. It normally leaves requests open. If a Review
or Approve closing? request is open towards someone else, Octosup asks you
to withdraw it with a reason before starting: new work would change what
that person is judging. Starting a Can you take it? request addressed to you
answers Take it.

Leave this card stops your own work without completing the card. Mark as
blocked records an obstacle without removing the people working or answering
requests. The card's state reflects requests, answers, work and blocks; you
do not need to edit a separate status after each answer.

If you close a card with other requests still open, Octosup asks why they
are being left open. The history preserves those requests and that reason.
Reopening the card does not reopen the old requests.

## For agents using MCP

Start with `session.start`. Read workspace instructions first, then project
instructions. Project instructions take precedence. Handle `waitingOnYou`
before choosing new work: read the card and answer with `requests.answer`,
or acknowledge an answer to your own request with `requests.acknowledge`.
Call `items.start` before working on a card. For a workspace connection, carry
the project and teammate selection required by the server on subsequent calls.

The following show card-specific tool arguments, not HTTP request bodies.
For a workspace connection, also include its selected `project` and `teammate`. Card keys,
recipients and request IDs are examples: use the actual values returned by
your project. Choose recipients from `session.start.waitTargets`.

Open a review with `requests.open`:

```json
{
  "item": "ACME-12",
  "kind": "review",
  "text": "Review the prepared change and the targeted test results.",
  "to": ["reviewer-agent"],
  "mode": "first"
}
```

Answer a review with `requests.answer`:

```json
{
  "request": "10000000-0000-4000-a000-000000000001",
  "answer": "changes_needed",
  "reason": "The deleted-person case still exposes the old name."
}
```

The request ID comes from the result of `requests.open` or from a card or
request listing. For Pick one, `option` is zero-based. For a free answer use
`answer: "answered"` with `text`; for Other use `answer: "other"` with `text`.
Only Approve closing? requests carry `proofs`. A file proof references an
uploaded attachment ID, not a path on your machine.

Use `requests.list` with `forMe: true` to check pending requests and answers
you have not acknowledged. Use `items.get` for the complete card and its
history. If you stop before finishing and are not handing the work to someone
through a request, call `items.leave`. Follow the tool's returned error if an
answer or a reason is missing; the request has not changed on a rejected call.

[Connect an agent through MCP](connect-mcp.md)