Skip to main content
Some agent actions — deploying to production, restarting a service, deleting data — should not happen without explicit user consent. Human in the Loop lets the harness pause the agent before a sensitive tool call, surface the tool name and arguments to the user, and resume only after an approval decision. This keeps the agent autonomous for safe operations while giving users a checkpoint before anything destructive or irreversible runs.

​
How it works

When the agent requests a tool call that requires approval, the harness does not execute the tool. Instead, it emits tool.approval_required, finishes the current turn, and waits. Resume by starting a new turn in the same session with a UserToolApprovalEvent (user.tool_approval) for each pending tool call. Approvals are derived from the tool metadata exposed by the MCP server. Tools marked as destructive or not read-only can require approval before execution.
Approvals do not replace authorization. The user still needs permission to call the underlying tool; approval only controls whether the pending tool call should proceed.
Subagents can also request approval. When a subagent’s tool call requires approval, the harness finishes the current turn and emits tool.approval_required. Sending a user.tool_approval input in the next turn resumes the subagent from where it paused.

​
When to use Tool Call Approvals

Use approvals for tool calls that change state, are irreversible, or affect production — for example, mutating data, modifying infrastructure, sending external communications, or triggering expensive operations.
Skip approvals for safe read-only tools — listing resources, fetching metrics, searching docs, or reading status — where confirmation adds friction without reducing risk.

​
Example in the playground

When the agent calls a tool that requires approval, the playground pauses the run and shows the tool name, the request payload, and Approve / Deny buttons. A “1 tool needs your input” banner stays at the bottom of the chat until you decide.
Agent Playground showing a paused tool call for create_or_update_environment with the request body and Approve and Deny action buttons

Tool Approval Required for create_or_update_environment, with the request payload and Approve / Deny buttons

After you approve, the harness executes the tool, returns the response to the agent, and the run continues to completion.
Agent Playground showing Tool Approved for create_or_update_environment, the tool response payload, and the assistant's confirmation that the environment was created

After approval, the tool executes and the agent finishes the task

​
Handling approvals from the API

For the streaming events, JSON payloads, and a full client that handles tool.approval_required and resumes with UserToolApprovalEvent, see Use an agent — Approvals and Turn events — ToolApprovalRequiredEvent.