Proposal: Adding Function Call Approvals in OpenResponses

[bbqiu]

Adding Tool Call Approvals in OpenResponses

Description

Agents require user approval for state-changing operations and reads of sensitive data. We propose adding tool call approvals as a subtype of a new generic elicitation item type, with options to approve once, approve for all sessions, approve for this session, or deny the request.

The OpenAI Responses API has types mcp_approval_request and mcp_approval_response, but as server side tool execution increases in popularity, a generic, non-MCP specific option will unlock additional capabilities for server-side tool execution. When/if MCP specific events are added to the OpenResponses spec, we should reuse these events for MCP approvals as well.

The elicitation Item Type

This proposal introduces a generic elicitation item type to the Responses API. The elicitation type uses an elicitation_type field as a discriminator to support different kinds of server-to-client interactions that require user input. Tool call approvals are the first subtype (elicitation_type: "tool_call_approval"), and this same pattern is reused by the OAuth Logins proposal (elicitation_type: "oauth_login").

All elicitation items share a common structure:

Field	Type	Required	Description
id	string	Yes	Unique identifier for this elicitation
type	string	Yes	Always "elicitation"
elicitation_type	string	Yes	Discriminator: "tool_call_approval", "oauth_login", or future types
message	string	Yes	Human-readable explanation of why the interaction is needed

All elicitation responses share a common structure:

Field	Type	Required	Description
id	string	Yes	Unique identifier for this response
type	string	Yes	Always "elicitation_response"
elicitation_id	string	Yes	References the elicitation item being responded to
action	string	Yes	One of "accept", "decline", "cancel"
reason	string	No	Optional reason for the action

Subtype-specific fields are added alongside these common fields. This design is forward-compatible with the MCP Elicitation specification:

• The action field uses the same vocabulary as MCP elicitation responses (accept, decline, cancel).
• The message field matches MCP's requirement for a human-readable explanation.
• Future MCP elicitation subtypes (e.g. elicitation_type: "form" for MCP form mode, elicitation_type: "url" for MCP URL mode) can be added without breaking changes.

Example

When adding a comment to a GitHub PR, an agent will ask for permission before adding.

Requirements

• Applicable for all tool calls (including MCP tools if compatibility is added in the future)
• For the response fields of a tool call approval elicitation_response:
  • action determines the user's choice:
    • accept: approve the tool call (requires a scope)
    • decline: deny this singular call to the specified tool
    • cancel: user dismissed the prompt without making a choice
  • scope (required when action is accept) determines the duration of the approval:
    • once: approve this singular call to the specified tool
    • session: for followup messages within the same session (i.e. one multi-turn chat thread), all calls to the specified tool are approved
    • always: for all invocations of the agent loop in the future from this user, all calls to the specified tool are approved
• Server-side agent loop requirements:
  • When attempting any tool calls that require permission, scan the list of input Items for any accept + always or accept + session approvals. Also check if this user has ever selected always in previous conversations with this agent for this tool. Providers will need to maintain this mapping (user <> tool approval status).
    • If this tool has been pre-approved, proceed in the agent loop.
    • If the tool has not been pre-approved, break out of the agent loop and yield control back to the client.
  • If a tool call has been approved, run the server-side tool and continue the agent loop.
  • If a tool call has been declined, pass the decline reason (if available) to the LLM to decide the next step.
  • If a tool call has been cancelled, treat it as an implicit decline with no reason.
  • For requests with parallel tool calls, any requests lacking an explicit response are implicitly declined.
• Client-side requirements:
  • Present the user with options for approval. Clearly explain the implication behind each option of this approval request.
  • Send the payload with the action and scope fields filled out.
  • Elicitation items and responses should be kept in client history in a multi-turn conversation.
  • For responses with multiple elicitation items, clients should not send a request until all items have been responded to OR the user has explicitly submitted the request.

Open Questions

• Can we change function_call_output to tool_call_output? Per the Responses API docs, Functions are meant to be client-side tools, but we hope to allow provider-specific tools to be outputted as well. This would influence the naming of the elicitation_type field on the tool_call_approval elicitation.

Sample Spec

TODO link to PR with spec in code

Tool Call Approval Elicitation Fields

In addition to the common elicitation fields, tool_call_approval adds:

Field	Type	Required	Description
name	string	Yes	Name of the tool being called
arguments	string	Yes	JSON-encoded arguments of the tool call

In addition to the common elicitation response fields, the response adds:

Field	Type	Required	Description
scope	string	When action is accept	One of "once", "session", "always"

Streaming Response

// response.created
// response.in_progress
{
  "type": "response.output_item.added",
  "item": {
    "id": "elicit_123",
    "type": "elicitation",
    "elicitation_type": "tool_call_approval",
    "message": "The agent wants to add a comment to PR #123",
    "name": "add_pr_comment",
    "arguments": "{\"pr_number\": 123, \"body\": \"Looks good!\"}"
  },
  "output_index": 0,
  "sequence_number": 2
}
{
  "type": "response.output_item.done",
  "item": {
    "id": "elicit_123",
    "type": "elicitation",
    "elicitation_type": "tool_call_approval",
    "message": "The agent wants to add a comment to PR #123",
    "name": "add_pr_comment",
    "arguments": "{\"pr_number\": 123, \"body\": \"Looks good!\"}"
  },
  "output_index": 0,
  "sequence_number": 3
}
// response.completed

Non-Streaming Response

{
  "id": "resp_0a31882ebb2d3b550069cc629e73",
  "object": "response",
  "output": [
    {
      "id": "elicit_123",
      "type": "elicitation",
      "elicitation_type": "tool_call_approval",
      "message": "The agent wants to add a comment to PR #123",
      "name": "add_pr_comment",
      "arguments": "{\"pr_number\": 123, \"body\": \"Looks good!\"}"
    }
  ]
}

Client Follow-Up Request

{
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "<user input>"
        }
      ]
    },
    {
      "id": "elicit_123",
      "type": "elicitation",
      "elicitation_type": "tool_call_approval",
      "message": "The agent wants to add a comment to PR #123",
      "name": "add_pr_comment",
      "arguments": "{\"pr_number\": 123, \"body\": \"Looks good!\"}"
    },
    {
      "id": "elicit_resp_123",
      "type": "elicitation_response",
      "elicitation_id": "elicit_123",
      "action": "accept",
      "scope": "once",
      "reason": "optional reason for approving or declining"
    }
  ]
}

Decline Example

{
  "id": "elicit_resp_123",
  "type": "elicitation_response",
  "elicitation_id": "elicit_123",
  "action": "decline",
  "reason": "I don't want to comment on this PR"
}

Cancel Example

{
  "id": "elicit_resp_123",
  "type": "elicitation_response",
  "elicitation_id": "elicit_123",
  "action": "cancel"
}

[tv42]

Why does this belong in the protocol for harness<->LLM, when to me it sounds like a concern between the harness and the end user?

[ankmathur96]

@bbqiu , can we also include in this proposal some description on the tool definitions as well so that we can holistically model it?

[rpelevin]

The protocol does not need to own the approval UI, but I think it does need to model the pause/resume object.

Otherwise every harness invents a different hidden contract for the same state machine: a tool call is proposed, execution is blocked, a human or policy decision happens, and the run resumes or terminates.

I would keep the protocol primitive small:

• proposed action id;
• tool definition id or function name;
• canonical args digest;
• display summary;
• risk or sensitivity hint from the tool definition;
• requested approval scope: once, session, workflow, or persistent;
• decision: approve, deny, expire, cancel;
• decision id;
• expiry;
• result binding back to the proposed action id.

The tool definition side should say which calls can require approval and what scope can be requested. The runtime item should carry the exact call instance being approved.

Acceptance tests:

• approval for one proposed action cannot authorize a different action;
• session approval cannot silently become persistent approval;
• denial returns a terminal result that the model can observe;
• expired approval cannot resume execution;
• changed args produce a different proposed action id or digest;
• MCP-specific approvals can map onto the same generic lifecycle without losing server/tool identity.

That answers the harness-versus-user concern by keeping UI out of protocol while keeping the execution boundary interoperable.

[HarperZ9]

One detail I would separate in the spec: the approval response item in conversation history is not the same thing as a reusable approval grant.

For scope: once, the response item can be the whole authority: it binds to one elicitation_id / proposed call instance.

For scope: session or scope: always, I would model the durable part as a provider-side grant with its own identity and constraints, then let future calls reference it. Otherwise a transcript item starts doing too much work.

Useful grant fields:

type ToolApprovalGrant = {
  grant_id: string;
  subject: { user_id?: string; agent_id?: string; session_id?: string };
  tool_name: string;
  tool_definition_digest?: string;
  allowed_arg_digest?: string;
  allowed_arg_schema_digest?: string;
  scope: 'session' | 'always';
  created_from_elicitation_id: string;
  created_from_response_id: string;
  expires_at?: string;
  revoked_at?: string;
};

Then the runtime can emit, for a pre-approved call, something like approval_grant_id plus the current arguments_digest. That gives verifiers a crisp rule: the grant is valid only if the tool definition and the argument boundary still match the grant constraints.

A few concrete acceptance cases I would add beyond the current proposal:

• A session/persistent grant is not valid after the tool definition changes unless the grant was explicitly definition-agnostic.
• A grant created for one argument digest cannot approve a materially different argument payload.
• Revoked or expired grants are visible to the agent loop as a denial/cancel path, not silently ignored.
• Parallel tool calls must each carry their own elicitation id and either their own response or a matching reusable grant id.
• The elicitation item should allow arguments_digest and arguments_redacted so clients do not have to persist sensitive raw arguments just to keep auditability.

This is the boundary we use in Project Telos/Gather-style receipts: keep the human approval event, the reusable grant, the argument digest, and the execution receipt as separate records. It makes the protocol easier to audit without forcing the protocol to own the approval UI.

[armorer-labs]

I would separate three records here, otherwise the approval primitive can become hard to replay safely:

1. the conversation item that pauses the run and asks for approval;
2. the decision item that resumes or rejects that exact pending request;
3. any reusable grant created as a side effect of a broader scope choice.

The first two should be protocol history. The third should be a referenceable authority object, not just old transcript text.

A testable shape I would want in the spec:

• elicitation_id is unique per proposed tool call and is single-use;
• the approval request carries a stable proposed-call envelope: tool/function name, call id, canonical args digest, display summary, requested scope, and sensitivity hint from the tool definition;
• the approval response binds to that elicitation_id and records approved, denied, revised, or expired;
• if the user chooses session/always-style approval, the response may mint or reference a grant_id, but future calls still need to prove they match the grant constraints;
• replaying a transcript with a consumed elicitation_id must not re-execute the tool. It should either reference the prior terminal result or fail closed as already-consumed/stale.

The negative cases matter as much as the happy path: changed args after approval, a reused approval response on a new call id, a session grant applied to a different tool definition version, and a denied/expired decision accidentally becoming an executable assistant/tool message. Those are the cases where an approval feature stops being a UI affordance and becomes an authority boundary.

Disclosure: I work on Armorer Labs.