v2 Permission Requests - Agent Client Protocol

Elevator pitch

What are you proposing to change?

ACP v2 should make session/request_permission extensible beyond tool calls by giving every permission prompt a required title and optional structured subject context. Tool-call permissions use subject.type: "tool_call", command permissions use subject.type: "command", and permission requests that are not tied to a structured subject omit subject. Permission prompt copy should live in common title and description fields rather than in subject-specific data.

Status quo

How do things work today and what problems does this cause? Why would we change things?

In v1, permission requests are tied directly to a toolCall field. This works for tool execution approvals, but it makes the method harder to extend to other approval-like decisions. It also tempts agents to put permission prompt text into ToolCallUpdate.title or ToolCallUpdate.content. In v2, those fields are patch state for the displayed tool call. Using them for permission-only UI copy can accidentally change the tool call shown elsewhere.

What we propose to do about it

What are you proposing to improve the situation?

RequestPermissionRequest should have these common fields:

sessionId
title
description
options
subject
_meta

title is required and is the minimum user-visible prompt text. description is optional explanatory text. Omitted and null descriptions are equivalent and mean no extra detail was provided. subject is optional structured context and uses a tagged union when present:

{
  "title": "Approve file edit?",
  "description": "Allow the agent to edit src/main.rs?",
  "subject": {
    "type": "tool_call",
    "toolCall": {
      "toolCallId": "call_001"
    }
  }
}

Command permissions carry a self-contained description of the proposed execution:

{
  "title": "Run the test suite?",
  "subject": {
    "type": "command",
    "command": "cargo test",
    "cwd": "/workspace/project",
    "toolCallId": "call_001",
    "terminalId": "term_001"
  }
}

For a command subject, command and cwd are required, and cwd MUST be absolute. toolCallId, terminalId, and _meta are optional and nullable; omission and null are equivalent and mean the value was not provided. The IDs associate the request with displayed state when known; they do not change that state. The command describes what the Agent wants permission to execute and never asks the Client to execute it.

{
  "title": "Continue with elevated permissions?"
}

Omitted and null subjects are equivalent and mean no structured subject was provided. A missing subject is not a separate subject variant. Unknown future subject types should be preserved by clients that proxy, store, replay, or forward permission requests. Clients that cannot understand the subject should show a generic permission prompt or decline according to policy.

Shiny future

How will things play out once this feature exists?

Agents can request permission for tool calls without conflating permission UI text with tool-call state. Command approvals can show the exact command and working directory without hiding them in generic tool-call input. Agents can also request permission for operations that have no structured subject, and future structured subjects can be added without changing the common permission request fields.

Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?

Replace the v1-style top-level toolCall request field in v2 with an optional subject tagged union.
Add the tool_call subject variant.
Add the command subject variant with a required command and absolute working directory plus optional associations.
Add common required title and optional description fields.
Keep options as the required list of choices the user can select.
Preserve unknown subject variants while keeping known subject payloads distinct from unknown fallback variants.

Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

Why require `title`?

The title is the minimum text a client can display when asking the user to choose an option. Requiring it keeps subject-less permission requests usable without requiring clients to synthesize prompt copy.

Why make `subject` optional?

Some permission requests are valid without a structured target. In those cases, title, description, and options are the permission request, while subject is additional context for clients that can render a richer prompt.

Why not flatten subject fields into the request?

title, description, and options describe the permission prompt. subject describes what the permission is about. Keeping the subject nested avoids collisions between common request fields and future subject-specific fields.

Why not use `ToolCallUpdate.title` or `ToolCallUpdate.content` for permission copy?

Those fields patch the displayed tool call. Permission-only prompt copy belongs in the common title and description fields so a permission request does not accidentally replace tool-call title or content. It’s quite common to have a reason you want to display for the permission request itself without updating the persisted tool call for the rest of the session.

Revision history

2026-07-14: Added the command permission subject for Agent-executed commands.
2026-07-02: Initial draft

​Elevator pitch

​Status quo

​What we propose to do about it

​Shiny future

​Implementation details and plan

​Frequently asked questions

​Why require title?

​Why make subject optional?

​Why not flatten subject fields into the request?

​Why not use ToolCallUpdate.title or ToolCallUpdate.content for permission copy?

​Revision history