---
title: Approvals and questions
description: Answer a venom serve session's permission requests and its ask_user questions from your own code, with timeouts, remembered rules and remote policies.
section: server-api
order: 30
audience: [builder, agent]
sources: [packages/harness-server/openapi.yaml, packages/harness-server/src/approvals.ts, packages/harness-server/src/questions.ts]
features: [server-api.sessions-approvals, server-api.sessions-questions]
---

A served session has no terminal to ask in. When its permission policy says "ask", or when the model calls its `ask_user` tool, the server publishes an event and waits for a client to answer. This is where your app applies its own policy: allow `npm test`, deny pushes, show the question to a person.

## Approvals {#approvals}

The harness asks only when the rules and mode say "ask"; `yolo` and allow rules never reach you. Each request becomes an `approval_request` event:

```json
{
  "seq": 57, "source": "server", "type": "approval_request",
  "approvalId": "a_19c", "tool": "bash", "toolCallId": "call_7",
  "input": { "command": "npm test | tee out.txt" },
  "summary": "npm test | tee out.txt", "reason": "no rule allows bash(npm test)",
  "mode": "default", "suggestions": ["bash(npm test:*)"],
  "rules": ["bash(npm test:*)", "bash(tee out.txt:*)"],
  "createdAt": "2026-11-03T10:00:00Z", "expiresAt": "2026-11-03T10:01:00Z"
}
```

`toolCallId` is the id of the call's `tool_execution_start` event, so you can attach the question to the call you already show. A subagent's call carries `agent` and `parentToolCallId`, the parent's `task` call. `GET /v1/sessions/{sessionId}/approvals` (`listApprovals`) returns the same objects for every request still pending, for a client that connects late.

Answer with `POST /v1/sessions/{sessionId}/approvals/{approvalId}` (`decideApproval`):

```bash
curl -s -X POST $S/v1/sessions/$SID/approvals/a_19c -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"action": "allow-session"}'
```

```python
client.decide(sid, "a_19c", "deny", feedback="Don't write files outside src/.")
```

```ts
await client.decide(sid, "a_19c", { action: "allow-once" });
```

| Field | Type | What |
|---|---|---|
| `action` | `allow-once`, `allow-session`, `allow-project`, `deny` | required |
| `feedback` | string | Returned to the model with a denial, so it can change course. |
| `rule` | string | The rule to remember for `allow-session` / `allow-project`. `edit(<workspace>)` allows every edit in the workspace for the session and is never persisted. |
| `rules` | string array | Several rules to remember together; wins over `rule`. |

Without `rule` or `rules`, `allow-session` and `allow-project` store the request's `rules`: every rule the call needs, one per segment of a compound command that asked. An empty `rules` means no rule can cover the call; offer only `allow-once`. The answer is `{approvalId, action}`; the stream then shows `approval_resolved`.

**No answer is a denial.** A request not answered before `expiresAt` is denied with feedback the model reads; so is one whose run was aborted or whose session closed. The wait is `--approval-timeout` (60 s by default) or the session's `approvalTimeoutMs`. Approvals are serialized per session, subagents included. A late answer gets 404 `approval_not_found`.

## A remote policy {#policy}

The clients' `run` helpers follow a prompt to its end and call your function for each request:

```python
def approve(req):
    if req["tool"] == "bash" and req["input"].get("command", "").startswith("npm test"):
        return "allow-once"
    if req["tool"] in ("read", "grep", "find", "ls"):
        return True                      # allow once
    return {"action": "deny", "feedback": "Only reads and npm test are allowed here."}

result = run(client, "/home/me/work/app", "Make the failing test pass.", approve=approve)
```

```ts
const { text } = await client.run(sid, "Make the failing test pass.", {
  approve: (req) =>
    req.tool === "bash" && String(req.input.command ?? "").startsWith("npm test")
      ? { action: "allow-once" }
      : { action: "deny", feedback: "Only npm test is allowed here." },
});
```

Return `None` / `undefined` to leave a request to the timeout. In Python, a run without `approve` denies every request at once.

## Questions {#questions}

When the model calls `ask_user`, the server publishes `question_request`:

```json
{
  "type": "question_request", "questionId": "q_4e",
  "questions": [{
    "header": "Database", "question": "Which database should the migration target?",
    "options": [{ "label": "Postgres", "description": "production" }, { "label": "SQLite", "description": "tests" }],
    "multiSelect": false
  }],
  "createdAt": "2026-11-03T10:02:00Z", "expiresAt": "2026-11-03T10:03:00Z"
}
```

`GET /v1/sessions/{sessionId}/questions` (`listQuestions`) lists the pending ones. Answer with `POST /v1/sessions/{sessionId}/questions/{questionId}` (`answerQuestion`) and one answer per question, in order: `selected` (option labels) and optional `text` (the person's own words).

```bash
curl -s -X POST $S/v1/sessions/$SID/questions/q_4e -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"answers": [{"selected": ["Postgres"]}]}'
```

```python
client.answer_question(sid, "q_4e", [{"selected": ["Postgres"], "text": "use the staging DB"}])
```

```ts
await client.answerQuestion(sid, "q_4e", [{ selected: ["Postgres"] }]);
// or in run(): { answer: (req) => req.questions.map(() => ({ selected: [], text: "your call" })) }
```

The answer is `{questionId, answers}` (the count). Unanswered by `expiresAt` (the same timeout as approvals), aborted or closed, the model is told nobody answered and decides itself, stating its assumption. A late answer gets 404 `question_not_found`. Scheduled runs decline every question at once.

## Related pages

- [Events](/docs/server-api/events.md#server): `approval_resolved` and `question_resolved`
- [Phone inbox](/docs/server-api/mobile-and-inbox.md): answer approvals from a phone
- [Sessions](/docs/server-api/sessions.md#create): `rules`, `mode` and `approvalTimeoutMs`
