Skip to content
Docs menu

Approvals and questions

Answer a venom serve session's permission requests and its ask_user questions from your own code, with timeouts, remembered rules and remote policies.

View .md

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

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:

{
  "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):

curl -s -X POST $S/v1/sessions/$SID/approvals/a_19c -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"action": "allow-session"}'
client.decide(sid, "a_19c", "deny", feedback="Don't write files outside src/.")
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

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

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)
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

When the model calls ask_user, the server publishes question_request:

{
  "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).

curl -s -X POST $S/v1/sessions/$SID/questions/q_4e -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"answers": [{"selected": ["Postgres"]}]}'
client.answer_question(sid, "q_4e", [{"selected": ["Postgres"], "text": "use the staging DB"}])
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.

  • Events: approval_resolved and question_resolved
  • Phone inbox: answer approvals from a phone
  • Sessions: rules, mode and approvalTimeoutMs