Interface PermissionHandler

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface PermissionHandler
Functional interface for handling permission requests from the AI assistant.

When the assistant needs permission to perform certain actions (such as executing tools or accessing resources), this handler is invoked to approve or deny the request. The raw request's managed-approval marker preserves policy provenance and one-shot restrictions. Newer runtimes also expose the derived promptRequest through PermissionInvocation; handlers should prefer that prompt when deciding whether Assisted approval still requires a human response and remain conservative when it is absent.

Example Implementation

PermissionHandler handler = (request, invocation) -> {
	var prompt = invocation.getPromptRequest();
	var assistedApprovalClearsManagedRequirement = prompt != null
			&& ("commands".equals(prompt.getKind()) || "read".equals(prompt.getKind())
					|| "write".equals(prompt.getKind()) || "url".equals(prompt.getKind())
					|| "workflow".equals(prompt.getKind()))
			&& !Boolean.TRUE.equals(prompt.getManagedApprovalRequired());
	if (Boolean.TRUE.equals(request.getManagedApprovalRequired()) && !assistedApprovalClearsManagedRequirement) {
		return requestHumanApproval(request);
	}

	// Check the permission kind
	if ("dangerous-action".equals(request.getKind())) {
		// Deny dangerous actions
		return CompletableFuture
				.completedFuture(new PermissionRequestResult().setKind(PermissionRequestResultKind.REJECTED));
	}

	// Approve other requests
	return CompletableFuture
			.completedFuture(new PermissionRequestResult().setKind(PermissionRequestResultKind.APPROVED));
};

Event-based permission dispatch can use PermissionRequestResult.noResult() to let another connected client answer a pending request. Legacy protocol-v2 callbacks require a decision and cannot abstain.

A pre-built handler that approves all requests is available as APPROVE_ALL.

Since:
1.0.0
See Also:

  • Field Details

    • APPROVE_ALL

      static final PermissionHandler APPROVE_ALL
      A pre-built handler that approves permission requests when managed settings are disabled.
      Since:
      1.0.11

  • Method Details

    • handle

      CompletableFuture<PermissionRequestResult> handle(PermissionRequest request, PermissionInvocation invocation)
      Handles a permission request from the assistant.

      The handler should evaluate the request and return a result indicating whether the permission is granted or denied.

      Parameters:
      request - the permission request details
      invocation - the invocation context with session information
      Returns:
      a future that completes with the permission decision