Help Needed: Public API for Tool Approval Request Lookup and Response Creation

[1448376744 (soul-soft)]

We are integrating ToolApprovalAgent into a frontend/backend application and are trying to design a clean approval flow for tool calls.

Our frontend is not a good place to send back a full ToolApprovalRequestContent, because that object includes the original ToolCall with the tool name and arguments. For security reasons, the backend should not trust a tool call object that comes back from the frontend. Ideally, the frontend should only send a lightweight approval decision, such as:

{
  "sessionId": "session-id",
  "requestId": "approval-request-id",
  "approved": true,
  "mode": "once"
}

The framework appears to keep approval requests in session state internally. For example, ApprovalResponseBindingChatClient stores pending approval requests under an internal key, and ToolApprovalAgent also keeps its own internal approval state for queued requests, surfaced requests, collected responses, and standing approval rules. This is useful for framework internals, but the relevant state keys and state types are not exposed as public API.

What we are missing is a public, supported mechanism to take a frontend-submitted requestId, find the corresponding server-side ToolApprovalRequestContent from the active AgentSession, and create the correct approval response. This matters especially for these cases:

• Approving or denying a single tool call.
• Creating an AlwaysApproveToolApprovalResponseContent for "always approve this tool".
• Creating an AlwaysApproveToolApprovalResponseContent for "always approve this tool with these arguments".
• Avoiding any need for the frontend to send the full tool call back to the backend.
• Avoiding reliance on internal session state keys such as _pendingApprovalRequests or toolApprovalState.

Today, the safest workaround seems to be for our backend to maintain its own approval store keyed by (sessionId, requestId), populated from ToolApprovalRequestContent values found in AgentResponse.Messages or streaming updates. The frontend only receives a safe display DTO and later sends back the requestId plus the approval decision. The backend then uses its own stored ToolApprovalRequestContent to call CreateResponse, CreateAlwaysApproveToolResponse, or CreateAlwaysApproveToolWithArgumentsResponse.

Is this the intended integration pattern for frontend/backend applications? Or is there a supported API we should use to retrieve the pending approval request from AgentSession and construct the corresponding response from only a requestId and an approval decision?

[Vlad Shulcz (vshulcz)]

You may not need the lookup API you're describing, because the harness already refuses to trust the tool call that comes back.

In ToolApprovalAgent.CollectApprovalResponsesFromMessages, an inbound response is only honored when its request id matches something the harness itself surfaced, and the tool call is then replaced with the server side one:

if (surfaced.TryGetValue(response.RequestId, out var surfacedRequest))
{
    surfaced.Remove(response.RequestId);
    // Rebind to the surfaced request's tool call and record for injection.
    state.CollectedApprovalResponses.Add(
        new ToolApprovalResponseContent(response.RequestId, response.Approved, surfacedRequest.ToolCall)
        {
            Reason = response.Reason,
        });
}

Anything whose id was not surfaced is dropped rather than collected, and the surfaced entry is consumed on match, so a replayed response for the same id has no effect.

So your backend can take the lightweight payload from the frontend, build a ToolApprovalResponseContent with that requestId and approved, and pass whatever tool call it likes, including an empty placeholder: the name and arguments from the client never reach the inner agent. The one thing the client controls is the id and the boolean, which is exactly the surface you wanted.

Two caveats. mode: "once" versus a standing rule is separate: standing rules live in ToolApprovalState.Rules and are created through AlwaysApproveToolApprovalResponseContent, not through the plain response type. And SurfacedApprovalRequests is keyed by request id per session, so the session the response is submitted against has to be the same one that surfaced the request.