Richieste di permesso

Comportamento predefinito (`deny-all`)

Quando permission_approve in config/copilot.php vale "deny-all" (default), le richieste di permesso vengono automaticamente rifiutate in Copilot::run() e Copilot::start(). Per gli usi centrati sulla generazione di testo spesso non servono permessi, quindi è un default sicuro.

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

Valori configurabili

Valore	Comportamento
`"deny-all"`	Rifiuta automaticamente tutto (default)
`"approve-safety"`	Rifiuta solo `shell` e `write`, gli altri sono autorizzati automaticamente
`"approve-all"`	Autorizza automaticamente tutto
`false`	Nessun handler. `onPermissionRequest` diventa obbligatorio (come nell’SDK ufficiale)

// .env
COPILOT_PERMISSION_APPROVE="approve-safety"

Se accetti prompt utente, "approve-safety" e "approve-all" sono pericolosi. Usa sempre false oppure "deny-all". Anche i permessi read-only potrebbero leggere il codice del progetto Laravel.

`PermissionHandler::approveAll()`

PermissionHandler::approveAll() autorizza automaticamente tutte le richieste.

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() rifiuta solo i permessi ad alto rischio (shell, write) e autorizza automaticamente gli altri.

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);

Neanche questo è del tutto sicuro. Se vuoi un controllo rigoroso, implementa un handler personalizzato e valuta usando $request['kind'].

`PermissionHandler::denyAll()`

PermissionHandler::denyAll() rifiuta tutto.

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

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

Uso diretto di Client

Quando usi direttamente CopilotClient, come nell’SDK ufficiale è obbligatorio specificare onPermissionRequest.

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 è obbligatorio
$session = $client->createSession([
    'onPermissionRequest' => PermissionHandler::approveSafety(),
]);

// Se lo ometti, InvalidArgumentException
// $session = $client->createSession([]); // Error!

Handler personalizzato

Per controllare autorizzazione/rifiuto in base al tipo di richiesta, passa una closure. $request e $invocation sono array come i seguenti.

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`

I campi oltre a kind e toolCallId variano a seconda di 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,
]

Se $request['managedApprovalRequired'] è true, le Managed Settings dell’organizzazione impediscono l’approvazione automatica di questa richiesta. In questo caso PermissionHandler::approveAll() restituisce no-result e lascia la decisione al flusso standard di Copilot CLI.

`$invocation`

[
  "sessionId" => "...",
  // Incluso facoltativamente solo nei runtime CLI più recenti
  "promptRequest" => [
    "kind" => "read",
    "managedApprovalRequired" => false,
  ],
]

Contesto del prompt (`promptRequest`)

Nei runtime CLI più recenti, $invocation['promptRequest'] può contenere il contesto del prompt rivolto all’utente. Negli handler personalizzati puoi usare questo valore per stabilire se è necessaria una risposta umana. PermissionHandler::approveAll() dà priorità a promptRequest['managedApprovalRequired'] quando sono soddisfatte tutte le condizioni seguenti.

promptRequest['kind'] è uno tra commands / read / write / url / workflow
promptRequest['managedApprovalRequired'] è un boolean

In questo modo, anche se $request['managedApprovalRequired'] rimane come marcatore derivato dalla policy, la richiesta può essere approvata automaticamente quando il prompt non richiede una risposta umana. Il marcatore grezzo in $request viene comunque conservato. Con CLI meno recenti senza promptRequest, tipi non supportati o in assenza di un valore boolean valido, la decisione si basa come prima su $request['managedApprovalRequired'].

use Revolution\Copilot\Support\PermissionRequestResultKind;

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

    if (is_array($prompt) && ($prompt['managedApprovalRequired'] ?? null) === true) {
        // Serve una risposta umana, quindi si lascia la decisione al flusso standard della CLI
        return PermissionRequestResultKind::noResult();
    }

    return PermissionRequestResultKind::approveOnce();
},

Risposta

Il risultato della decisione sul permesso viene restituito come array. La classe PermissionRequestResultKind la rende più leggibile.

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

Dettagli di protocollo

Nel Protocol v3 (default attuale) le richieste di permesso vengono consegnate come eventi di sessione (permission.requested) anziché come richieste JSON-RPC. L’SDK le gestisce internamente e risponde con l’RPC session.permissions.handlePendingPermissionRequest. L’utilizzo di SessionConfig non cambia. Basta passare un handler a onPermissionRequest: le differenze di protocollo sono assorbite dall’SDK.

PermissionRequestResultKind

Puoi restituire direttamente ['kind' => 'approve-once'], ma PermissionRequestResultKind è più chiaro.

use Revolution\Copilot\Support\PermissionRequestResultKind;

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

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

Metodi disponibili

Metodo	Valore	Descrizione
`approveOnce()`	`approve-once`	Autorizza solo questa richiesta
`approveForSession()`	`approve-for-session`	Autorizza tutte le richieste dello stesso tipo durante questa sessione
`approveForLocation()`	`approve-for-location`	Autorizza tutte le richieste dello stesso tipo da questa posizione (percorso file, ecc.)
`reject()`	`reject`	Rifiuta la richiesta
`userNotAvailable()`	`user-not-available`	L’utente non può rispondere (ad es. ambienti non interattivi)
`noResult()`	`no-result`	Se l’handler non può restituire un risultato (salta la chiamata RPC)

Se vuoi usare Laravel\Prompts\select, con PermissionRequestResultKind::select() ottieni le opzioni.

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

Se l’handler non può restituire un risultato (ad es. ambiente non interattivo) puoi restituire no-result. Restituendo no-result la chiamata RPC viene saltata e viene applicato il rifiuto predefinito di Copilot CLI.

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

Per le informazioni più recenti fai riferimento al repository GitHub.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kit

Feed e RSS

Middleware

Richieste di permesso