approval_request
tools/call
Request a human decision. Advisory proposals record the decision but execute nothing; supported command proposals execute atomically only after approval. Link the request to your session with sessionId so the session shows as waiting. An agent_request may ask a question instead: send question {} for a free-text answer or { choices } for up to 6 options. The answer appears in approval_status and, with a sessionId, as an instruction on your next session_heartbeat. With expiresInMinutes, an unresolved request expires and a command proposal never executes.
Scopes
request:approvals
A command proposal also needs read:work. Once approved, the command runs as the person who resolved it, with their write:work.
Inputs
- kind"work_change" | "memory_change" | "life_change" | "agent_request"Required
- titlestringRequired
- Approval title
- descriptionstring
- What will change and why
- targetTypestring
- Optional target type
- targetIdstring
- Optional target ID
- proposalobjectRequired
- Explicitly advisory, or a typed command from the supported executable subset.
- sessionIdstring
- Optional ID of one of this agent's open sessions
- expiresInMinutesinteger
- Optional. Minutes until the request expires, from 5 to 10,080 (7 days).
- questionobject
- Optional, agent_request with an advisory proposal only. The title is the question.
- idempotencyKeystringRequired
- Unique retry key
Returns
The pending approval request. A call returns content[0].text with the JSON result and structuredContent.result with the same value.
Listed when
The key has agent access.