# Approvals for apps

Your own app can run your agents through Languid's XRPC API and answer the calls they ask you about, the way the web chat does. This page covers starting a run that asks, showing what's waiting, and answering it.

## How approvals work

Some calls need your yes before they run: `bash`, `edit` and `write` on a computer, record writes from a script that your agent's policy says to ask about, and sharing error reports. Your rules for a computer decide first. A call they allow runs without asking, and a call they deny is refused without asking.

When a run asks, Languid writes an `ai.languid.approval.request` record in the agent's space. Your answer is an `ai.languid.tool.approval` record, written under the request's own record key, so a request has one answer at most. See [Records](/docs/records).

- **Approve:** the call runs, and the run goes on.
- **Deny:** the agent gets an error result saying you denied it, and decides what to do next.
- **No answer in 5 minutes:** the call is denied with "no answer in time", and a later answer is refused.

A tool call that's waiting survives a restart of the service. After a restart, the question comes back under a new run. A script that asks partway through doesn't survive one: the script stops, and its call ends as interrupted.

## Sign in

Sign people in with [atproto OAuth](https://atproto.com/specs/oauth) and call Languid through their PDS. Ask for an `rpc` scope for each method you call, with Languid as the audience:

```
rpc:ai.languid.agent.run?aud=did:web:languid.ai%23languid
rpc:ai.languid.agent.getRun?aud=did:web:languid.ai%23languid
rpc:ai.languid.approval.list?aud=did:web:languid.ai%23languid
rpc:ai.languid.approval.answer?aud=did:web:languid.ai%23languid
```

Send each call to the person's PDS with this header:

```http
atproto-proxy: did:web:languid.ai#languid
```

Their PDS forwards the call to Languid with a token for that one call. Apps can call only these four methods, and only on that person's own agents: any other agent's name gets `404 AgentNotFound`.

Scripts you run yourself can send `Authorization: Bearer` with the token from `languid login` instead:

```sh
jq -r .server.token ~/.languid/state.json
```

## Start a run that asks

```http
POST /xrpc/ai.languid.agent.run
{ "agent": "scout", "prompt": "Tidy the notes folder", "thread": "3n2js7khmj2aq", "approval": "ask" }
```

The response is `{ run, thread, accepted, since, message }`. With `accepted: "queued"`, the thread already had a run: follow that one from `since`.

`approval` sets what happens to calls that need your yes:

| `approval` | Calls that need your yes |
|---|---|
| `"ask"` | wait for your answer |
| `"allow"` | run without asking (not sharing error reports, which always asks) |
| `"auto"` | are approved when a classifier model finds them reversible and covered by the owner's latest message, and wait for your answer otherwise (see [Auto](/docs/computers#auto)) |
| `"deny"` | are refused with "no one was asked: this run was started with changes denied" |

Without `approval`, `approveWrites: true` means `"allow"`, and anything else means `"deny"`. If you send both, `approval` wins. A message sent into a thread that already has a run goes by that run's mode.

The other fields are optional: `thread` (or `continue: true` for the latest thread; leave both out for a new thread), `computer`, `via` (your app's name), and `clientMessageId` (send it again and the message isn't recorded twice).

Attach images with `images: [{ data, mimeType }]`, where `data` is base64 (without a data-URL prefix). Send up to four PNG, JPEG, GIF or WebP images, each at most 5 MB. `prompt` may be empty for an image-only message. Images are saved as private blobs; authenticated `agent.getContext` returns hydrated image parts for history, including after a service restart.

## Follow the run

```http
GET /xrpc/ai.languid.agent.getRun?run=<run>&since=<next>
```

This returns `{ run, thread, status, events, next, … }`. `status` is `running`, `done` or `error`. Poll with `since` set to the last `next`. Two events matter here:

```json
{ "seq": 4, "type": "approval", "id": "toolu_01…", "tool": "bash", "arguments": "{\"call_intention\":\"Delete old drafts\",\"command\":\"rm drafts/*.md\"}", "computer": "laptop", "always": { "command": "rm" }, "request": "at://did:plc:…/ai.languid.approval.request/3n2mivd4nlscu" }
{ "seq": 5, "type": "decision", "id": "toolu_01…", "approved": true }
```

- **`approval`:** a call is waiting. Answer it with its `request`. `arguments` is a JSON string, and its `call_intention` is the agent's own words for what the call is for. For a script's write, `tool` is the XRPC method (such as `com.atproto.repo.putRecord`) and the event has no `computer` or `always`.
- **`decision`:** the call was answered. `reason` is present when the answer didn't come from a person: `"no answer in time"`, `"the run was stopped"`, `"approved by Auto"` (with no `approval` event before it), or the rule an "Always allow" saved.

## List what's waiting

When your page loads, list what's waiting rather than replaying old events:

```http
GET /xrpc/ai.languid.approval.list?agent=scout&thread=3n2js7khmj2aq
```

`thread` is optional. The response lists open requests that something still waits on, newest first:

```json
{ "approvals": [{
  "uri": "at://did:plc:…/ai.languid.approval.request/3n2mivd4nlscu",
  "cid": "bafyrei…",
  "thread": "3n2js7khmj2aq",
  "call": { "uri": "at://…/ai.languid.tool.call/3n2mivcwwy2cu", "cid": "bafyrei…" },
  "tool": "bash",
  "arguments": "{\"call_intention\":\"Delete old drafts\",\"command\":\"rm drafts/*.md\"}",
  "intention": "Delete old drafts",
  "computer": "laptop",
  "always": { "command": "rm" },
  "expiresAt": "2026-11-18T21:35:00.000Z",
  "createdAt": "2026-11-18T21:30:00.000Z",
  "run": "a04b7288-9a98-43e5-927d-37e65d054fa0"
}] }
```

`intention`, `computer` and `always` are present only when they apply. A script's write also has `n` (which of the script's asks it is) and `method`. Follow `run` with `getRun` to see what happens after you answer.

## Answer

```http
POST /xrpc/ai.languid.approval.answer
{ "agent": "scout", "request": "at://did:plc:…/ai.languid.approval.request/3n2mivd4nlscu", "approved": true, "via": "my-app" }
```

The response is `{}`, or `{ "rule": { "computer", "tool", "command"? } }` when you sent `always: true`.

- `via` names your app in the approval record, in 64 characters at most. It defaults to `"xrpc"`.
- **`409 NotWaiting`:** the request is unknown, already answered, past its `expiresAt`, or nothing waits on it any more. Drop it from your page.
- **`400`:** `approved` isn't a boolean, `always` is sent with `approved: false`, or `always` is sent for a request that has no rule to save.

### Always allow

Offer it only when the request has `always`. `always: true` approves the call and saves a rule for that computer:

- with `always.command` (bash), that command's leading words run there without asking;
- without it (`edit`, `write`), the whole tool runs there without asking.

The rule also approves any other call in the same run that is waiting and that the rule now covers. A script's record writes have no `always`: which writes need no asking is set on the agent's settings page, under **Record writes**.

## A page that answers

1. Start runs with `approval: "ask"`.
2. On load, call `approval.list` for the thread. While a run goes on, add a card for each `approval` event, and remove it on the matching `decision`.
3. On each card, show the intention as the heading, then the tool, the computer and the command (or the record being written).
4. Offer **Allow** and **Deny**, plus **Always allow** when `always` is present (for example "Always allow `rm` on laptop"). Show the time left until `expiresAt`.
5. Answer from your server, so the token stays there. On a 409, drop the card.
