Permission requests

Default behavior (`deny-all`)

When permission_approve in config/copilot.php is "deny-all" (the default), permission requests during Copilot::run() and Copilot::start() are automatically denied. This is a safe default because text-generation use cases usually don’t require permissions.

// config/copilot.php
'permission_approve' => env('COPILOT_PERMISSION_APPROVE', 'deny-all'),

Available values

Value	Behavior
`"deny-all"`	Auto-deny every request (default)
`"approve-safety"`	Deny only `shell` and `write`; auto-approve everything else
`"approve-all"`	Auto-approve every request
`false`	No handler. `onPermissionRequest` is required (same as the official SDK)

// .env
COPILOT_PERMISSION_APPROVE="approve-safety"

"approve-safety" and "approve-all" are dangerous when accepting user-supplied prompts. Always use false or "deny-all" in those cases. Even read-only permissions may allow Laravel project code to be read.

`PermissionHandler::approveAll()`

PermissionHandler::approveAll() auto-approves every request.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
);

$response = Copilot::run(prompt: 'Hello', config: $config);

`PermissionHandler::approveSafety()`

PermissionHandler::approveSafety() denies only the high-risk permissions (shell and write) and auto-approves everything else.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveSafety(),
);

$response = Copilot::run(prompt: 'Hello', config: $config);

This still isn’t perfectly safe. For strict control, implement a custom handler and inspect $request['kind'] to decide.

`PermissionHandler::denyAll()`

PermissionHandler::denyAll() denies everything.

use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::denyAll(),
);

Using the client directly

When using CopilotClient directly, specifying onPermissionRequest is required, just like the official SDK.

use Revolution\Copilot\Client;
use Revolution\Copilot\Support\PermissionHandler;

$client = new Client([
    'cli_path' => 'copilot',
    'cli_args' => [],
    'cwd' => base_path(),
    'log_level' => 'info',
    'env' => null,
]);
$client->start();

// onPermissionRequest is required
$session = $client->createSession([
    'onPermissionRequest' => PermissionHandler::approveSafety(),
]);

// Omitting it throws InvalidArgumentException
// $session = $client->createSession([]); // Error!

Custom handler

To control approvals by request kind, pass a closure. $request and $invocation are arrays with roughly the following shape.

use Illuminate\Support\Facades\Artisan;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionRequestResultKind;
use Revolution\Copilot\Types\SessionConfig;

use function Laravel\Prompts\{confirm, note, spin, text};

Artisan::command('copilot:chat', function () {
    $config = new SessionConfig(
        onPermissionRequest: function (array $request, array $invocation) {
            $confirm = confirm(
                label: 'Do you accept the requested permissions?',
            );
            if ($confirm) {
                return PermissionRequestResultKind::approveOnce();
            } else {
                return PermissionRequestResultKind::reject();
            }
        },
    );

    Copilot::start(function (CopilotSession $session) use ($config) {
        while (true) {
            $prompt = text(
                label: 'Enter your prompt',
                placeholder: 'Ask me anything...',
                required: true,
                hint: 'Ctrl+C to exit',
            );

            $response = spin(
                callback: fn () => $session->sendAndWait($prompt),
                message: 'Waiting for Copilot response...',
            );

            note($response->content());
        }
    }, config: $config);
});

`$request`

Fields other than kind and toolCallId vary based on kind.

kind: "shell" | "write" | "mcp" | "read" | "url" | "custom-tool" | "memory" | "hook"

[
  "kind" => "shell",
  "toolCallId" => "toolu_...",
  "fullCommandText" => "...",
  "intention" => "Run copilot:ping to test permission request",
  "commands" => [
    [
      "identifier" => "bash",
      "readOnly" => false,
    ]
  ]
  "possiblePaths" => [],
  "possibleUrls" => [],
  "hasWriteFileRedirection" => false,
  "canOfferSessionApproval" => false,
]

If $request['managedApprovalRequired'] is true, your organization’s Managed Settings prevent this request from being auto-approved. In this case, PermissionHandler::approveAll() returns no-result and defers to the standard Copilot CLI flow.

`$invocation`

[
  "sessionId" => "...",
  // Optionally included only by newer CLI runtimes
  "promptRequest" => [
    "kind" => "read",
    "managedApprovalRequired" => false,
  ],
]

Prompt context (`promptRequest`)

With newer CLI runtimes, $invocation['promptRequest'] may contain the context of the user-facing prompt. Custom handlers can use this value to decide whether a human response is required. PermissionHandler::approveAll() gives precedence to promptRequest['managedApprovalRequired'] when all of the following conditions are met:

promptRequest['kind'] is one of commands / read / write / url / workflow
promptRequest['managedApprovalRequired'] is a boolean

This allows auto-approval when the prompt does not require a human response, even if $request['managedApprovalRequired'] remains as a policy-derived marker. The raw marker in $request is still preserved. With older CLIs that do not send promptRequest, unsupported kinds, or when there is no valid boolean value, the decision falls back to $request['managedApprovalRequired'] as before.

use Revolution\Copilot\Support\PermissionRequestResultKind;

onPermissionRequest: function (array $request, array $invocation) {
    $prompt = $invocation['promptRequest'] ?? null;

    if (is_array($prompt) && ($prompt['managedApprovalRequired'] ?? null) === true) {
        // A human response is required, so defer to the standard CLI flow
        return PermissionRequestResultKind::noResult();
    }

    return PermissionRequestResultKind::approveOnce();
},

Response

Return the permission decision as an array. Using the PermissionRequestResultKind class makes the intent easier to read.

return PermissionRequestResultKind::approveOnce();
return PermissionRequestResultKind::reject();

Protocol details

In Protocol v3 (the current default), permission requests are delivered as session events (permission.requested) rather than JSON-RPC requests. The SDK handles this internally and responds via the session.permissions.handlePendingPermissionRequest RPC. The usage of SessionConfig does not change. Pass a handler to onPermissionRequest and the SDK absorbs any protocol differences.

PermissionRequestResultKind

You can return ['kind' => 'approve-once'] directly, but PermissionRequestResultKind makes it clearer.

use Revolution\Copilot\Support\PermissionRequestResultKind;

$confirm = confirm(
    label: 'Do you accept the requested permissions?',
);

if ($confirm) {
    return PermissionRequestResultKind::approveOnce();
} else {
    return PermissionRequestResultKind::reject();
}

Available methods

Method	Value	Description
`approveOnce()`	`approve-once`	Approve only this specific request
`approveForSession()`	`approve-for-session`	Approve every request of this kind for the whole session
`approveForLocation()`	`approve-for-location`	Approve every request of this kind from this location (file path, etc.)
`reject()`	`reject`	Reject the request
`userNotAvailable()`	`user-not-available`	The user cannot respond (non-interactive environment, etc.)
`noResult()`	`no-result`	The handler cannot produce a result (skip the RPC call)

To use Laravel\Prompts\select, retrieve the options via PermissionRequestResultKind::select().

use Revolution\Copilot\Support\PermissionRequestResultKind;
use function Laravel\Prompts\select;

$select = select(
    label: 'Do you accept the requested permissions?',
    options: PermissionRequestResultKind::select(),
);

return ['kind' => $select];

no-result

If the handler cannot produce a result (for example, in a non-interactive environment), return no-result. Returning no-result skips the RPC call, and the Copilot CLI’s default deny applies.

return PermissionRequestResultKind::noResult();
// Or ['kind' => 'no-result']

For the latest updates, see the GitHub repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

Permission requests