Berechtigungsanfragen

Standardverhalten (`deny-all`)

Wenn permission_approve in config/copilot.php auf "deny-all" steht (Standard), werden Berechtigungsanfragen bei Copilot::run() und Copilot::start() automatisch abgelehnt. Da Anwendungen mit Fokus auf Textgenerierung häufig keine Berechtigungen benötigen, ist dies eine sichere Voreinstellung.

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

Mögliche Werte

Wert	Verhalten
`"deny-all"`	Alles automatisch ablehnen (Standard)
`"approve-safety"`	Nur `shell` und `write` ablehnen, alles andere automatisch erlauben
`"approve-all"`	Alles automatisch erlauben
`false`	Kein Handler. `onPermissionRequest` ist erforderlich (wie beim offiziellen SDK)

// .env
COPILOT_PERMISSION_APPROVE="approve-safety"

Wenn Sie Nutzer-Prompts entgegennehmen, sind "approve-safety" und "approve-all" riskant. Verwenden Sie in diesem Fall unbedingt false oder "deny-all". Auch Read-Only-Berechtigungen können dazu führen, dass Code aus dem Laravel-Projekt gelesen wird.

`PermissionHandler::approveAll()`

PermissionHandler::approveAll() erlaubt automatisch alle Anfragen.

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() lehnt ausschließlich risikoreiche Berechtigungen (shell, write) ab und erlaubt alles andere automatisch.

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

Auch damit ist die Sicherheit nicht vollständig gewährleistet. Für strengere Kontrolle implementieren Sie einen benutzerdefinierten Handler und werten $request['kind'] aus.

`PermissionHandler::denyAll()`

PermissionHandler::denyAll() lehnt alles ab.

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

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

Bei direkter Verwendung des Client

Wenn Sie CopilotClient direkt verwenden, ist die Angabe von onPermissionRequest – wie beim offiziellen SDK – erforderlich.

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

// Bei Weglassen wird eine InvalidArgumentException geworfen
// $session = $client->createSession([]); // Error!

Benutzerdefinierter Handler

Um Genehmigungen und Ablehnungen je nach Anfrageart zu steuern, übergeben Sie eine Closure. $request und $invocation sind Arrays wie folgt.

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`

Neben kind und toolCallId variieren die Felder je nach 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,
]

Wenn $request['managedApprovalRequired'] true ist, kann diese Anfrage aufgrund der Managed Settings der Organisation nicht automatisch genehmigt werden. PermissionHandler::approveAll() gibt in diesem Fall no-result zurück und überlässt die Entscheidung dem Standardablauf der Copilot CLI.

`$invocation`

[
  "sessionId" => "...",
  // Nur in neueren CLI-Runtimes optional enthalten
  "promptRequest" => [
    "kind" => "read",
    "managedApprovalRequired" => false,
  ],
]

Prompt-Kontext (`promptRequest`)

In neueren CLI-Runtimes kann $invocation['promptRequest'] den Kontext des an den Nutzer gerichteten Prompts enthalten. In eigenen Handlern können Sie anhand dieses Werts entscheiden, ob eine menschliche Antwort erforderlich ist. PermissionHandler::approveAll() bevorzugt promptRequest['managedApprovalRequired'], wenn alle folgenden Bedingungen erfüllt sind:

promptRequest['kind'] ist einer von commands / read / write / url / workflow
promptRequest['managedApprovalRequired'] ist ein Boolean

Dadurch kann automatisch genehmigt werden, wenn im Prompt keine menschliche Antwort nötig ist, selbst wenn $request['managedApprovalRequired'] als richtlinienbasierte Markierung bestehen bleibt. Die rohe Markierung in $request bleibt weiterhin erhalten. Bei älteren CLIs ohne promptRequest, nicht unterstützten Arten oder ohne gültigen Boolean-Wert wird wie bisher anhand von $request['managedApprovalRequired'] entschieden.

use Revolution\Copilot\Support\PermissionRequestResultKind;

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

    if (is_array($prompt) && ($prompt['managedApprovalRequired'] ?? null) === true) {
        // Eine menschliche Antwort ist erforderlich, daher an den Standardablauf der CLI übergeben
        return PermissionRequestResultKind::noResult();
    }

    return PermissionRequestResultKind::approveOnce();
},

Antwort

Die Entscheidung wird als Array zurückgegeben. Mit der Klasse PermissionRequestResultKind bleibt der Code lesbar.

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

Protokoll-Details

Ab Protocol v3 (aktueller Standard) werden Berechtigungsanfragen nicht als JSON-RPC-Requests, sondern als Session-Events (permission.requested) ausgeliefert. Das SDK verarbeitet dies intern und antwortet über den RPC-Aufruf session.permissions.handlePendingPermissionRequest. Die Verwendung von SessionConfig ändert sich dabei nicht. Übergeben Sie einfach einen Handler an onPermissionRequest; die Protokollunterschiede fängt das SDK ab.

PermissionRequestResultKind

Sie können direkt ['kind' => 'approve-once'] zurückgeben, aber mit PermissionRequestResultKind wird der Code verständlicher.

use Revolution\Copilot\Support\PermissionRequestResultKind;

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

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

Verfügbare Methoden

Methode	Wert	Beschreibung
`approveOnce()`	`approve-once`	Nur diese Anfrage erlauben
`approveForSession()`	`approve-for-session`	Alle gleichartigen Anfragen in dieser Session erlauben
`approveForLocation()`	`approve-for-location`	Alle gleichartigen Anfragen von diesem Ort (z. B. Dateipfad) erlauben
`reject()`	`reject`	Anfrage ablehnen
`userNotAvailable()`	`user-not-available`	Nutzer kann nicht antworten (z. B. nicht-interaktive Umgebung)
`noResult()`	`no-result`	Handler kann kein Ergebnis liefern (überspringt den RPC-Aufruf)

Wenn Sie Laravel\Prompts\select verwenden möchten, können Sie die Auswahloptionen über PermissionRequestResultKind::select() abrufen.

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

Wenn der Handler kein Ergebnis liefern kann (z. B. in nicht-interaktiven Umgebungen), können Sie no-result zurückgeben. Bei no-result wird der RPC-Aufruf übersprungen, und die Copilot-CLI-seitige Standardablehnung greift.

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

Aktuelle Informationen finden Sie im GitHub-Repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds und RSS

Middleware

Berechtigungsanfragen