Agent

Answer a parked interactive tool approval

Resolves a tool call the agent kernel parked for a human decision (B2). A tool-call frame on GET /v1/agent/stream with approvalRequired:true is the prompt; this endpoint answers it. The parked call resumes at once (the tool's result rides the SSE stream). A parked approval also denies on idle timeout, SSE disconnect, or turn Stop. Idempotent: a second answer for the same call (already resolved / unknown / expired) loses with 409. Only the conversation's own client, or the person at the Mac, may answer; another client is refused with 403.

always-allow is saved as a standing rule only after the device owner authenticates on the Mac, so a bearer's always-allow response waits for that authentication for up to 45 seconds. Without it the tool is allowed for this session and nothing is saved. An exec-class tool is never saved as always allowed: it runs this once, and so does a call a firewall Ask rule asks for, since the rule asks again on every call it matches. always-deny is saved at once, shown in the Security pane with the client that set it, where the person can revert it. standing_grant reports which happened.

post/v1/agent/approve

Request

  • Base URL: http://localhost:9998
  • URL: http://localhost:9998/v1/agent/approve
  • Auth: HTTP bearer

Request body

session_idstring required

The session the approval belongs to

tool_call_idstring required

The proposed call's id (from its tool-call frame)

decision'allow-once' | 'allow-session' | 'always-allow' | 'deny' | 'always-deny' required
run_idstring

Optional. The run the approval belongs to. Tool-call ids repeat across turns, so an answer naming a run that is not the running one is refused with 409 instead of answering a later call of the same id.

tool_namestring

Optional. The tool the prompt showed. Tool-call ids repeat within a turn too, so an answer naming another tool than the pending call's is refused with 409.

argumentsstring

Optional. The arguments the prompt showed, as the tool-call frame's arguments text. An answer whose arguments differ from the pending call's is refused with 409.

Response

Approval resolved; the turn resumes over SSE

oktrue
session_idstring
tool_call_idstring
decisionstring
standing_grant'recorded' | 'session_only' | 'once' | 'pending'

Present for always-allow and always-deny. recorded: the standing rule was saved. session_only: the owner did not authenticate within the bound, so the tool is allowed for this session only. once: an exec-class tool ran this once and nothing was saved. pending: the call was still running when the reply stopped waiting; its Always allow is saved when it ends, after the owner confirms where the Security level asks.

Changes

No recorded changes to this operation across all 1 revision of this API.