Module 08: Permissions

Handle permission requests from agents on the client side.

What You’ll Learn

Registering a requestPermissionHandler
PermissionOption and PermissionOptionKind types
Permission outcomes: selected vs cancelled

The Code

When an agent wants to perform a sensitive operation (like writing a file or running a command), it can ask the client for permission first. The client registers a requestPermissionHandler that receives the request details and a list of options (allow once, allow always, reject). Your handler decides which option to select — typically by showing a dialog to the user:

AcpSyncClient client = AcpClient.sync(transport)
    .requestPermissionHandler(req -> {
        System.out.println("Agent wants to: " + req.toolCall().title());
        System.out.println("Options:");
        for (var option : req.options()) {
            System.out.println("  " + option.id() + ": " +
                option.name() + " (" + option.kind() + ")");
        }
        // Auto-approve with first option
        return new RequestPermissionResponse(
            req.options().getFirst().id());
    })
    .readTextFileHandler(req -> /* file handler */)
    .writeTextFileHandler(req -> /* file handler */)
    .build();

Permission Option Kinds

Kind	Description
`ALLOW_ONCE`	Allow this specific operation
`ALLOW_ALWAYS`	Allow all similar operations
`REJECT_ONCE`	Deny this specific operation
`REJECT_ALWAYS`	Deny all similar operations

The agent sends a RequestPermissionRequest containing the tool call details and a list of options. The client presents choices to the user and returns the selected option ID. This completes the bidirectional request flow (with Module 07 for files).

Source Code

View on GitHub

Running the Example

Requires the Grok CLI on your PATH, signed in once with grok login. The module launches it as grok agent stdio; no API key is needed. The prompt asks Grok to create hello.txt. In Grok’s default (ask) mode it sends session/request_permission before the write, and the client prints the options and reads your choice. Grok also reads Claude Code’s settings: if ~/.claude/settings.json sets "defaultMode" to "auto" or "acceptEdits", Grok writes the file without asking, and no permission request appears.

./mvnw exec:java -pl module-08-permissions

Next Module

Module 09: Session Resume — load and resume existing sessions.

Projects

AgentWorks

Supporting Projects

Migration

Explorations

Older / Inactive Projects

08 permissions

Module 08: Permissions

What You’ll Learn

The Code

Permission Option Kinds

Source Code

Running the Example

Next Module

​Module 08: Permissions

​What You’ll Learn

​The Code

​Permission Option Kinds

​Source Code

​Running the Example

​Next Module

Module 08: Permissions

What You’ll Learn

The Code

Permission Option Kinds

Source Code

Running the Example

Next Module