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