Approve a tool call
Release a tool call that is parked waiting for human approval. Deny it instead, with a memo, and the agent reads the memo and picks another path.
requiresApproval, the objective parks. The call sits at TOOL_CALL_STATUS_WAITING_FOR_APPROVAL and nothing runs until you approve it or deny it.
Approve takes no body. Deny takes an optional memo, which is the interesting one.
Denying steers, it does not stop
A denial is not a failure. Cadenya hands the agent the rejected call back as its tool result, wrapping your memo:GetFakerOptions call produced this timeline:
STATE_RUNNING throughout. Write the memo as an instruction to the agent, not as an audit note to yourself: it is prompt text, and it steers the next attempt.
memo reaches the agent through the tool result, but the toolDenied event’s own memo field comes back empty. Read the memo from the toolResult that follows, or store it yourself when you send the denial.Find the parked call
Three ways, depending on how your system is shaped. A webhook, when you want to be told. Theobjective_event.tool_approval_requested delivery carries toolCallId, and the approval guide walks the full handler including signature verification.
The event stream, when a person is already watching. A toolApprovalRequested event arrives with a toolApprovalRequested.toolCallId and nothing else.
Polling, when you want no inbound plumbing at all. The list endpoint takes a status filter:
data.callable, and the exact data.arguments the agent proposed.
The two status fields
A tool call tracks approval and execution separately, and both matter.WAITING_FOR_APPROVAL to APPROVED, while execution walks PENDING to COMPLETED.
What marks a tool for approval
One field decides at run time:requiresApproval on the tool. Nothing else is consulted.
You set it two ways. By hand, when you define a tool. Or through the tool set adapter’s toolApprovals filter, which stamps requiresApproval onto tools as they sync:
always for only with a filter to mark a subset. The filter runs on every sync, so a hand-edited requiresApproval gets overwritten the next time the tool set syncs, unless the adapter carries no toolApprovals at all.
The 24-hour clock
A parked call waits 24 hours. Nothing approves or denies it for you: the wait expires, the call fails, and the objective surfaces an error. The window is fixed and takes no configuration. Do not confuse it with two other 24-hour timers:contentTimeouton a bare adapter also defaults to 24 hours, but it resolves gracefully, writing a synthesized result that says no content arrived. The objective survives.inactivityTimeouton a variation’s constraints finalizes an idle objective asSTATE_TIMED_OUT. It counts objective activity, not approvals.
Related
Approving a tool
Deny a tool call
memo that steers the agent.Bare tools
setContent.Stream objective events
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
The ID of the objective. Supports "external_id:" prefix for external IDs.
"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"
The ID of the tool call to approve
"toolcall_01HXKD2E5NQM3T9AYWCFTANFGV"
Body
The body is of type object.
Response
OK
ObjectiveToolCall is a record of a tool call made during an objective's execution. Tool calls are mutable — their status changes as they are approved, denied, or executed.
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
Current status of the tool call
TOOL_CALL_STATUS_UNSPECIFIED, TOOL_CALL_STATUS_AUTO_APPROVED, TOOL_CALL_STATUS_WAITING_FOR_APPROVAL, TOOL_CALL_STATUS_APPROVED, TOOL_CALL_STATUS_DENIED TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED, TOOL_CALL_EXECUTION_STATUS_PENDING, TOOL_CALL_EXECUTION_STATUS_RUNNING, TOOL_CALL_EXECUTION_STATUS_COMPLETED, TOOL_CALL_EXECUTION_STATUS_ERRORED, TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT