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

# Tools, Permissions, Commands und UI

> Mit SessionRpc des Laravel Copilot SDK behandeln Sie Tools, Berechtigungen, Befehle und UI-Anfragen.

## Tools, Permissions, Commands und UI

Geltungsbereich: SessionRpc (sessionbezogene Operationen, die an eine Session gebunden sind)

Eine Übersicht über RPC und die Liste aller RPC-Seiten finden Sie unter [RPC](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc.md).

```php theme={null}
// tools (Protokoll v3+: Antwort auf external_tool.requested-Events)
// Runtime-Toolset vor dem Senden initialisieren und validieren (experimental, u. a. für Subagent-Sessions)
$session->rpc()->tools()->initializeAndValidate();
// Gibt ein leeres ToolsInitializeAndValidateResult zurück

// Aktuell in der Session bereitgestellte Tools über die native Aufrufpipeline ausführen (experimental)
use Revolution\Copilot\Types\Rpc\ToolsExecuteRequest;

$result = $session->rpc()->tools()->execute(new ToolsExecuteRequest(
    name: 'search',
    arguments: ['query' => 'Laravel'],
    toolCallId: 'call-123', // Optional. Zur Korrelation mit dem Aufruf
));

if (is_string($result)) {
    // Einfaches Textergebnis
    echo $result;
} else {
    // ToolResultExpanded: textResultForLlm, resultType, newMessages,
    // mcpMeta, structuredContent, taskCompletionDecision usw.
    echo $result->textResultForLlm;
    // resultType enthält ToolResultType oder einen string mit einem unbekannten Wert
}

// Auch als Array möglich. toolCallId kann weggelassen werden; sessionId wird mit dem Wert dieser Session überschrieben
$session->rpc()->tools()->execute([
    'name' => 'search',
    'arguments' => ['query' => 'Copilot'],
]);
// arguments: [] wird als JSON-Objekt {} gesendet; scalar/null/nicht leere Arrays behalten ihren JSON-Wert

// execute() durchläuft die normale native Tool-Aufrufpipeline und umgeht daher keine Berechtigungsprüfungen.
// Wenn ein Tool eine Genehmigung benötigt, wird dies wie gewohnt vom onPermissionRequest-Handler der SessionConfig verarbeitet.
$session->rpc()->tools()->handlePendingToolCall(new HandlePendingToolCallRequest(
    requestId: '...',
    result: 'Tool execution result',
));
// Aktuelle Tool-Metadaten der Session abrufen (experimental)
$session->rpc()->tools()->getCurrentMetadata();
// Die von dieser Verbindung bereitgestellten externen Tools vollständig ersetzen (experimental)
$session->rpc()->tools()->set(['tools' => [
    ['name' => 'search', 'description' => 'Search documents', 'parameters' => ['type' => 'object']],
]]);
// Auf die aktuelle Session angewendete Subagent-Einstellungen abrufen (experimental)
$settings = $session->rpc()->tools()->getSubagentSettings();
// $settings->subagents ist SubagentSettings oder null, wenn kein Einstellungsblock vorhanden ist
// Einstellungen für Subagents aktualisieren (experimental)
use Revolution\Copilot\Enums\SubagentSettingsEntryContextTier;
use Revolution\Copilot\Types\Rpc\SubagentSettings;
use Revolution\Copilot\Types\Rpc\SubagentSettingsEntry;
use Revolution\Copilot\Types\Rpc\UpdateSubagentSettingsRequest;

$result = $session->rpc()->tools()->updateSubagentSettings(new UpdateSubagentSettingsRequest(
    subagents: new SubagentSettings(agents: [
        'my-agent' => new SubagentSettingsEntry(
            contextTier: SubagentSettingsEntryContextTier::Default,
            model: 'gpt-5',
        ),
    ]),
));
// Das Anwenden der Einstellungen gibt ein leeres ToolsUpdateSubagentSettingsResult zurück

// permissions (Protokoll v3+: Antwort auf permission.requested-Events)
use Revolution\Copilot\Types\Rpc\FolderTrustAddParams;
use Revolution\Copilot\Types\Rpc\PermissionLocationAddToolApprovalParams;
use Revolution\Copilot\Types\Rpc\PermissionLocationApplyParams;
use Revolution\Copilot\Types\Rpc\PermissionLocationResolveParams;
use Revolution\Copilot\Types\Rpc\PermissionsLocationsAddToolApprovalDetailsCommands;
use Revolution\Copilot\Types\Rpc\SessionPermissionsManagedReviewRequiredRequest;

$session->rpc()->permissions()->handlePendingPermissionRequest(new PermissionDecisionRequest(
    requestId: '...',
    result: PermissionDecision::approveOnce(),
));
// Alle Berechtigungsanfragen in der Session automatisch genehmigen
$session->rpc()->permissions()->setApproveAll(new PermissionsSetApproveAllRequest(enabled: true));
// Berechtigungsmodus festlegen (manual / assisted / allow-all)
$session->rpc()->permissions()->setMode(new PermissionsSetModeRequest(mode: PermissionMode::AllowAll));
// Aktuellen Berechtigungsmodus abrufen
$mode = $session->rpc()->permissions()->getMode();
// Wurde permissionMode beim Erstellen/Fortsetzen der Session angegeben, kann das Ergebnis von der Session abgerufen werden
$result = $session->permissionModeResult();
// $result->success - Ob die Anwendung erfolgreich war
// $result->mode - Berechtigungsmodus nach der Anwendung
// Unter der aktuellen Richtlinie verfügbare Genehmigungsmodi abrufen (experimental)
$capabilities = $session->rpc()->permissions()->getCapabilities();
// $capabilities->assistedApproval - Ob die LLM-gestützte Genehmigung aktiviert ist
// $capabilities->bypassPermissions - Ob die verwaltete Richtlinie bedingungslose Genehmigung erlaubt
// Aktive Berechtigungseskalation und die Ausgangsbasis beim Start abrufen
$allowAll = $session->rpc()->permissions()->getAllowAll();
// $allowAll->active / $allowAll->baseline->tools
// Abrufen, ob Events für Berechtigungsanfragen erforderlich sind
$required = $session->rpc()->permissions()->getRequired();
// Abrufen, ob eine verwaltete Richtlinie die Prüfung der angegebenen Berechtigungsanfrage erfordert
$reviewRequired = $session->rpc()->permissions()->managedReviewRequired(
    new SessionPermissionsManagedReviewRequiredRequest(request: ['kind' => 'tool', 'toolName' => 'bash'])
);
// Zusätzliche Verzeichnisse im Modellkontext abrufen
$additionalDirectories = $session->rpc()->permissions()->additionalDirectories()->list();
// Session-bezogene Berechtigungsfreigaben zurücksetzen
$session->rpc()->permissions()->resetSessionApprovals();
// Liste der aktuell ausstehenden Berechtigungsanfragen abrufen
$pending = $session->rpc()->permissions()->pendingRequests();
// Event-Bridge für Berechtigungsanfragen aktivieren/deaktivieren
$session->rpc()->permissions()->setRequired(new PermissionsSetRequiredRequest(required: true));
// Berechtigungsregeln hinzufügen/entfernen
$session->rpc()->permissions()->modifyRules(new PermissionsModifyRulesParams(
    scope: PermissionsModifyRulesScope::SESSION,
    add: [['tool' => 'bash', 'decision' => 'allow']],
));
// Mitteilen, dass ein Berechtigungs-Prompt angezeigt wurde
$session->rpc()->permissions()->notifyPromptShown(new PermissionPromptShownNotification(message: 'tool permission prompt'));
// Beim Fortsetzen aus dem Verlauf wiederhergestellte Berechtigungseskalationen im Speicher aufheben
$result = $session->rpc()->permissions()->clearResumeEscalation();
// $result->success
// Pfadberechtigungen
$paths = $session->rpc()->permissions()->paths()->list();
$session->rpc()->permissions()->paths()->add(new PermissionPathsAddParams(path: '/path/to/allow'));
$session->rpc()->permissions()->paths()->updatePrimary(new PermissionPathsUpdatePrimaryParams(path: '/path/to/allow'));
$session->rpc()->permissions()->paths()->isPathWithinAllowedDirectories(new PermissionPathsAllowedCheckParams(path: '/path/to/allow/file.txt'));
$session->rpc()->permissions()->paths()->isPathWithinWorkspace(new PermissionPathsWorkspaceCheckParams(path: '/path/to/allow/file.txt'));
// URL-Berechtigungen
$session->rpc()->permissions()->urls()->setUnrestrictedMode(
    new PermissionUrlsSetUnrestrictedModeParams(enabled: true)
);
// Berechtigungs-Location des Arbeitsverzeichnisses auflösen und gespeicherte Regeln anwenden
$location = $session->rpc()->permissions()->locations()->resolve(
    new PermissionLocationResolveParams(workingDirectory: '/path/to/repo')
);
$session->rpc()->permissions()->locations()->apply(
    new PermissionLocationApplyParams(workingDirectory: '/path/to/repo')
);
// Tool-Freigabe dauerhaft in der Berechtigungs-Location speichern
$session->rpc()->permissions()->locations()->addToolApproval(
    new PermissionLocationAddToolApprovalParams(
        approval: new PermissionsLocationsAddToolApprovalDetailsCommands(commandIdentifiers: ['bash']),
        locationKey: $location->locationKey,
    )
);
// Ordner-Vertrauensstatus prüfen und hinzufügen
$trusted = $session->rpc()->permissions()->folderTrust()->isTrusted(['path' => '/path/to/repo']);
$session->rpc()->permissions()->folderTrust()->addTrusted(new FolderTrustAddParams(path: '/path/to/repo'));

// commands: Liste der in der Session verfügbaren Slash-Befehle abrufen
use Revolution\Copilot\Types\Rpc\CommandsListRequest;

$list = $session->rpc()->commands()->list();
// $list->commands - Array von SlashCommandInfo
// $list->commands[0]->name - Befehlsname (ohne Schrägstrich)
// $list->commands[0]->description - Befehlsbeschreibung
// $list->commands[0]->kind - Befehlskategorie (builtin, skill, client)
// $list->commands[0]->allowDuringAgentExecution - Ob der Befehl während der Agent-Ausführung verwendbar ist

// Liste mit Filter abrufen
$list = $session->rpc()->commands()->list(new CommandsListRequest(
    includeBuiltins: true,
    includeSkills: false,
));

// commands: Slash-Befehl aufrufen
use Revolution\Copilot\Types\Rpc\CommandsInvokeRequest;

$result = $session->rpc()->commands()->invoke(new CommandsInvokeRequest(
    name: 'help',
    input: 'optional input text',
));

// commands: Antwort auf ein Befehlsaufruf-Event
$session->rpc()->commands()->handlePendingCommand(new CommandsHandlePendingCommandRequest(
    requestId: '...',
));

// commands: Slash-Befehl synchron ausführen
use Revolution\Copilot\Types\Rpc\ExecuteCommandParams;

$result = $session->rpc()->commands()->execute(new ExecuteCommandParams(
    commandName: 'review',
    args: 'src/',
), timeout: 120.0); // Wartezeit auf die CLI-Antwort (Sekunden). Standardmäßig 30 Sekunden
// $result->error - Fehlermeldung bei fehlgeschlagener Ausführung (bei Erfolg null)

// commands: Antwort auf einen in die Warteschlange gestellten Befehl
$session->rpc()->commands()->respondToQueuedCommand(new CommandsRespondToQueuedCommandRequest(
    requestId: '...',
    result: new QueuedCommandResult(handled: true),
));

// ui: Antwort auf eine UI-Elicitation-Anfrage
$session->rpc()->ui()->elicitation(new UIElicitationRequest(
    message: 'Question for the user',
    requestedSchema: ['type' => 'object', 'properties' => [...]],
));

// ui: Temporäre Abfrage, die nicht zum Gesprächsverlauf hinzugefügt wird
$result = $session->rpc()->ui()->ephemeralQuery(new UIEphemeralQueryRequest(
    question: 'Summarize the key points of the conversation so far.',
));
// $result->answer

// ui: Antwort auf eine ausstehende Elicitation-Anfrage (über das elicitation.requested-Event)
$session->rpc()->ui()->handlePendingElicitation(new UIHandlePendingElicitationRequest(
    requestId: '...',
    result: ['action' => 'accept', 'content' => ['name' => 'John']],
));

// ui: Über Broadcast-Events auf ausstehende Anfragen antworten
use Revolution\Copilot\Enums\UIAutoModeSwitchResponse;
use Revolution\Copilot\Types\Rpc\UIExitPlanModeResponse;
use Revolution\Copilot\Types\Rpc\UIHandlePendingAutoModeSwitchRequest;
use Revolution\Copilot\Types\Rpc\UIHandlePendingExitPlanModeRequest;
use Revolution\Copilot\Types\Rpc\UIHandlePendingSamplingRequest;
use Revolution\Copilot\Types\Rpc\UIHandlePendingUserInputRequest;
use Revolution\Copilot\Types\Rpc\SessionUiRegisterDirectAutoModeSwitchHandlerRequest;
use Revolution\Copilot\Types\Rpc\UIUnregisterDirectAutoModeSwitchHandlerRequest;
use Revolution\Copilot\Types\Rpc\UIUserInputResponse;

$registration = $session->rpc()->ui()->registerDirectAutoModeSwitchHandler(
    new SessionUiRegisterDirectAutoModeSwitchHandlerRequest(autoModeRecovery: true),
);
// Wenn Sie autoModeRecovery anfordern, aktivieren Sie die Wiederherstellung erst, nachdem Sie bestätigt haben, dass der Rückgabewert true ist.
// Den eigentlichen Event-Listener separat registrieren. Um den Handler zu entfernen, melden Sie ihn mit demselben Handle ab.
$session->rpc()->ui()->unregisterDirectAutoModeSwitchHandler(
    new UIUnregisterDirectAutoModeSwitchHandlerRequest(handle: $registration->handle),
);

$result = $session->rpc()->ui()->handlePendingUserInput(new UIHandlePendingUserInputRequest(
    requestId: '...',
    response: new UIUserInputResponse(answer: 'blue', wasFreeform: false),
));

$result = $session->rpc()->ui()->handlePendingExitPlanMode(new UIHandlePendingExitPlanModeRequest(
    requestId: '...',
    response: new UIExitPlanModeResponse(approved: true, selectedAction: 'autopilot_fleet'),
));

$result = $session->rpc()->ui()->handlePendingAutoModeSwitch(new UIHandlePendingAutoModeSwitchRequest(
    requestId: '...',
    response: UIAutoModeSwitchResponse::Yes,
));

// Auf data.requestId von auto_mode_recovery_consent.requested wird mit demselben RPC geantwortet.
// Wiederholungen und Rücksprünge bei der Wiederherstellung übernimmt die Runtime, daher den Prompt nicht aus der App erneut senden.

$result = $session->rpc()->ui()->handlePendingSampling(new UIHandlePendingSamplingRequest(
    requestId: '...',
    response: ['result' => '...'],
));
// Jede Methode gibt UIHandlePendingResult zurück. Über $result->success prüfen Sie, ob die Antwort angenommen wurde.

// onExitPlanModeRequest / onAutoModeSwitchRequest in SessionConfig antworten automatisch per reverse-RPC.
// Wenn Sie dieselbe Anfrage manuell über Events beantworten, verwenden Sie nicht beide Wege gleichzeitig.
```

## ui handlePendingSessionLimitsExhausted (auf ein erreichtes Limit antworten)

Wenn eine Session ihr AI-Credit-Limit erreicht, senden Sie die Entscheidung des Benutzers mit `ui()->handlePendingSessionLimitsExhausted()` an die Runtime zurück. Setzen Sie `action` auf einen Case von `SessionLimitsExhaustedResponseAction`: `Add` fügt dem Limit die angegebenen Credits hinzu, `Set` setzt das Limit auf einen absoluten Wert, `Unset` entfernt das Limit, und `Cancel` bricht die blockierte Anfrage ab, ohne das Limit zu ändern.

```php theme={null}
use Revolution\Copilot\Enums\SessionLimitsExhaustedResponseAction;
use Revolution\Copilot\Types\Rpc\UIHandlePendingSessionLimitsExhaustedRequest;
use Revolution\Copilot\Types\Rpc\UISessionLimitsExhaustedResponse;

$session->rpc()->ui()->handlePendingSessionLimitsExhausted(
    new UIHandlePendingSessionLimitsExhaustedRequest(
        requestId: $requestId,
        response: new UISessionLimitsExhaustedResponse(
            action: SessionLimitsExhaustedResponseAction::Add,
            additionalAiCredits: 10.0,
        ),
    ),
);
```

Details finden Sie unter [AI-Credit-Limits für Sessions](https://kawax.biz/de/packages/laravel-copilot-sdk/session-limits.md).

## commands enqueue (einen Befehl in die Warteschlange stellen)

```php theme={null}
use Revolution\Copilot\Types\Rpc\EnqueueCommandParams;

$session->rpc()->commands()->enqueue(new EnqueueCommandParams('/compact'));
```


## Related topics

- [SessionRpc-Übersicht](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc/session-overview.md)
- [RPC (Remote Procedure Call)](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc.md)
- [Tools](https://kawax.biz/de/packages/laravel-copilot-sdk/tools.md)
- [Streaming-Ereignisse](https://kawax.biz/de/packages/laravel-copilot-sdk/streaming-events.md)
- [Modelle, Tools und Konten](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc/server-models.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.