> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Berechtigungsanfragen

> Steuern Sie Berechtigungsanfragen im Laravel Copilot SDK über Standardwerte, integrierte Handler und benutzerdefinierte Genehmigungs-Callbacks.

## 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.

```php theme={null}
// 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) |

```php theme={null}
// .env
COPILOT_PERMISSION_APPROVE="approve-safety"
```

<Warning>
  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.
</Warning>

## `PermissionHandler::approveAll()`

`PermissionHandler::approveAll()` erlaubt automatisch alle Anfragen.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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**.

```php theme={null}
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.

```php theme={null}
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`.

```text theme={null}
kind: "shell" | "write" | "mcp" | "read" | "url" | "custom-tool" | "memory" | "hook"
```

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

### `$invocation`

```php theme={null}
[
  "sessionId" => "...",
]
```

## Antwort

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

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
return PermissionRequestResultKind::noResult();
// oder ['kind' => 'no-result']
```

<Info>
  Aktuelle Informationen finden Sie im [GitHub-Repository](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Cloud Sessions](/de/packages/laravel-copilot-sdk/cloud-sessions.md)
- [Erste Schritte - GitHub Copilot SDK für Laravel](/de/packages/laravel-copilot-sdk/getting-started.md)
- [GitHub Copilot SDK für Laravel](/de/packages/laravel-copilot-sdk/index.md)