> ## 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, permisos, comandos y UI

> Usa SessionRpc en Laravel Copilot SDK para gestionar tools, permisos, comandos y peticiones de UI.

## Tools, Permissions, Commands y UI

Ámbito: SessionRpc (operaciones por sesión vinculadas a una Session)

Para una visión general de RPC y la lista de todas las páginas de RPC, consulta [RPC](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc.md).

```php theme={null}
// tools (protocolo v3+: respuesta a eventos external_tool.requested)
// Inicializar y validar el conjunto de herramientas del runtime antes del envío (experimental, se usa en sesiones de subagentes, etc.)
$session->rpc()->tools()->initializeAndValidate();
// Devuelve un ToolsInitializeAndValidateResult vacío

// Ejecutar con el pipeline de llamadas nativo una herramienta expuesta actualmente a la sesión (experimental)
use Revolution\Copilot\Types\Rpc\ToolsExecuteRequest;

$result = $session->rpc()->tools()->execute(new ToolsExecuteRequest(
    name: 'search',
    arguments: ['query' => 'Laravel'],
    toolCallId: 'call-123', // Opcional. Se usa para correlacionarlo con la llamada
));

if (is_string($result)) {
    // Resultado de texto simple
    echo $result;
} else {
    // ToolResultExpanded: textResultForLlm, resultType, newMessages,
    // mcpMeta, structuredContent, taskCompletionDecision, etc.
    echo $result->textResultForLlm;
    // resultType contiene un ToolResultType o un string con un valor desconocido
}

// También se puede indicar como array. toolCallId se puede omitir, y sessionId se sobrescribe con el valor de esta sesión
$session->rpc()->tools()->execute([
    'name' => 'search',
    'arguments' => ['query' => 'Copilot'],
]);
// arguments: [] se envía como el objeto JSON {}, y los scalar/null/arrays no vacíos conservan su valor JSON

// execute() pasa por el pipeline normal de llamadas a herramientas nativas, por lo que no omite la comprobación de permisos.
// Si la herramienta requiere aprobación, la gestiona como siempre el handler onPermissionRequest de SessionConfig.
$session->rpc()->tools()->handlePendingToolCall(new HandlePendingToolCallRequest(
    requestId: '...',
    result: 'Tool execution result',
));
// Obtener los metadatos de herramientas actuales de la sesión (experimental)
$session->rpc()->tools()->getCurrentMetadata();
// Reemplazar por completo las herramientas externas que proporciona esta conexión (experimental)
$session->rpc()->tools()->set(['tools' => [
    ['name' => 'search', 'description' => 'Search documents', 'parameters' => ['type' => 'object']],
]]);
// Obtener la configuración de subagentes aplicada a la sesión actual (experimental)
$settings = $session->rpc()->tools()->getSubagentSettings();
// $settings->subagents es SubagentSettings, o null si no hay bloque de configuración
// Actualizar la configuración de subagentes (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',
        ),
    ]),
));
// Al aplicar la configuración se devuelve un ToolsUpdateSubagentSettingsResult vacío

// permissions (protocolo v3+: respuesta a eventos permission.requested)
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(),
));
// Aprobar automáticamente todas las solicitudes de permisos de la sesión
$session->rpc()->permissions()->setApproveAll(new PermissionsSetApproveAllRequest(enabled: true));
// Establecer el modo de permisos (manual / assisted / allow-all)
$session->rpc()->permissions()->setMode(new PermissionsSetModeRequest(mode: PermissionMode::AllowAll));
// Obtener el modo de permisos actual
$mode = $session->rpc()->permissions()->getMode();
// Si se especificó permissionMode al crear o reanudar la sesión, el resultado aplicado se obtiene de la sesión
$result = $session->permissionModeResult();
// $result->success - Si se aplicó correctamente
// $result->mode - Modo de permisos tras aplicarlo
// Obtener los modos de aprobación disponibles con la política actual (experimental)
$capabilities = $session->rpc()->permissions()->getCapabilities();
// $capabilities->assistedApproval - Si la aprobación asistida por LLM está habilitada
// $capabilities->bypassPermissions - Si la política gestionada permite la aprobación incondicional
// Obtener la escalación de permisos activa y la línea base de arranque
$allowAll = $session->rpc()->permissions()->getAllowAll();
// $allowAll->active / $allowAll->baseline->tools
// Obtener si se requieren eventos de petición de permiso
$required = $session->rpc()->permissions()->getRequired();
// Obtener si la política gestionada requiere revisar la petición de permiso indicada
$reviewRequired = $session->rpc()->permissions()->managedReviewRequired(
    new SessionPermissionsManagedReviewRequiredRequest(request: ['kind' => 'tool', 'toolName' => 'bash'])
);
// Obtener los directorios adicionales incluidos en el contexto del modelo
$additionalDirectories = $session->rpc()->permissions()->additionalDirectories()->list();
// Restablecer las aprobaciones de permisos con ámbito de sesión
$session->rpc()->permissions()->resetSessionApprovals();
// Obtener la lista de solicitudes de permisos actualmente pending
$pending = $session->rpc()->permissions()->pendingRequests();
// Activar/desactivar el puente de eventos de solicitudes de permisos
$session->rpc()->permissions()->setRequired(new PermissionsSetRequiredRequest(required: true));
// Añadir/eliminar reglas de permisos
$session->rpc()->permissions()->modifyRules(new PermissionsModifyRulesParams(
    scope: PermissionsModifyRulesScope::SESSION,
    add: [['tool' => 'bash', 'decision' => 'allow']],
));
// Notificar que se ha mostrado el prompt de permisos
$session->rpc()->permissions()->notifyPromptShown(new PermissionPromptShownNotification(message: 'tool permission prompt'));
// Borrar en memoria las escalaciones de permisos restauradas desde el historial al reanudar
$result = $session->rpc()->permissions()->clearResumeEscalation();
// $result->success
// Permisos de rutas
$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'));
// Permisos de URL
$session->rpc()->permissions()->urls()->setUnrestrictedMode(
    new PermissionUrlsSetUnrestrictedModeParams(enabled: true)
);
// Resolver la ubicación de permisos del directorio de trabajo y aplicar las reglas guardadas
$location = $session->rpc()->permissions()->locations()->resolve(
    new PermissionLocationResolveParams(workingDirectory: '/path/to/repo')
);
$session->rpc()->permissions()->locations()->apply(
    new PermissionLocationApplyParams(workingDirectory: '/path/to/repo')
);
// Persistir la aprobación de herramientas en la ubicación de permisos
$session->rpc()->permissions()->locations()->addToolApproval(
    new PermissionLocationAddToolApprovalParams(
        approval: new PermissionsLocationsAddToolApprovalDetailsCommands(commandIdentifiers: ['bash']),
        locationKey: $location->locationKey,
    )
);
// Comprobar y añadir el estado de confianza de carpetas
$trusted = $session->rpc()->permissions()->folderTrust()->isTrusted(['path' => '/path/to/repo']);
$session->rpc()->permissions()->folderTrust()->addTrusted(new FolderTrustAddParams(path: '/path/to/repo'));

// commands: obtener la lista de comandos slash disponibles en la sesión
use Revolution\Copilot\Types\Rpc\CommandsListRequest;

$list = $session->rpc()->commands()->list();
// $list->commands - array de SlashCommandInfo
// $list->commands[0]->name - nombre del comando (sin barra)
// $list->commands[0]->description - descripción del comando
// $list->commands[0]->kind - categoría del comando (builtin, skill, client)
// $list->commands[0]->allowDuringAgentExecution - si se puede usar durante la ejecución del agente

// Obtener la lista indicando filtros
$list = $session->rpc()->commands()->list(new CommandsListRequest(
    includeBuiltins: true,
    includeSkills: false,
));

// commands: invocar un comando slash
use Revolution\Copilot\Types\Rpc\CommandsInvokeRequest;

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

// commands: responder a un evento de invocación de comando
$session->rpc()->commands()->handlePendingCommand(new CommandsHandlePendingCommandRequest(
    requestId: '...',
));

// commands: ejecutar un comando slash de forma síncrona
use Revolution\Copilot\Types\Rpc\ExecuteCommandParams;

$result = $session->rpc()->commands()->execute(new ExecuteCommandParams(
    commandName: 'review',
    args: 'src/',
), timeout: 120.0); // Tiempo de espera de la respuesta del CLI (segundos). Por defecto, 30 segundos
// $result->error - Mensaje de error si la ejecución falló (null si tuvo éxito)

// commands: responder a un comando encolado
$session->rpc()->commands()->respondToQueuedCommand(new CommandsRespondToQueuedCommandRequest(
    requestId: '...',
    result: new QueuedCommandResult(handled: true),
));

// ui: responder a una solicitud de elicitation de UI
$session->rpc()->ui()->elicitation(new UIElicitationRequest(
    message: 'Question for the user',
    requestedSchema: ['type' => 'object', 'properties' => [...]],
));

// ui: consulta temporal que no se añade al historial de la conversación
$result = $session->rpc()->ui()->ephemeralQuery(new UIEphemeralQueryRequest(
    question: 'Summarize the key points of the conversation so far.',
));
// $result->answer

// ui: responder a una solicitud de elicitation pendiente (mediante el evento elicitation.requested)
$session->rpc()->ui()->handlePendingElicitation(new UIHandlePendingElicitationRequest(
    requestId: '...',
    result: ['action' => 'accept', 'content' => ['name' => 'John']],
));

// ui: responder a solicitudes pendientes mediante eventos broadcast
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),
);
// Si solicitas autoModeRecovery, habilita el manejo de recuperación solo después de confirmar que el valor devuelto es true.
// Registra el listener de eventos real por separado. Para quitar el handler, anula su registro con el mismo handle.
$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,
));

// Responde también a data.requestId de auto_mode_recovery_consent.requested con la misma RPC.
// El runtime se encarga de los reintentos y retrocesos de la recuperación, así que no reenvíes el prompt desde la aplicación.

$result = $session->rpc()->ui()->handlePendingSampling(new UIHandlePendingSamplingRequest(
    requestId: '...',
    response: ['result' => '...'],
));
// Cada método devuelve UIHandlePendingResult. Comprueba $result->success para saber si se aceptó la respuesta.

// onExitPlanModeRequest / onAutoModeSwitchRequest de SessionConfig responden automáticamente mediante reverse-RPC.
// Si respondes manualmente a la misma petición mediante eventos, no uses ambas vías a la vez.
```

## ui handlePendingSessionLimitsExhausted (responder a un límite agotado)

Cuando una sesión alcanza su límite de créditos de IA, devuelve la elección del usuario al runtime con `ui()->handlePendingSessionLimitsExhausted()`. Asigna a `action` un caso de `SessionLimitsExhaustedResponseAction`: `Add` añade los créditos indicados al límite, `Set` cambia el límite a un valor absoluto, `Unset` elimina el límite y `Cancel` cancela la petición bloqueada sin cambiar el límite.

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

Para más detalles, consulta [Límites de créditos de IA de la sesión](https://kawax.biz/es/packages/laravel-copilot-sdk/session-limits.md).

## commands enqueue (encolar un comando)

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

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


## Related topics

- [Resumen de SessionRpc](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc/session-overview.md)
- [RPC (Remote Procedure Call)](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc.md)
- [Solicitudes de permiso](https://kawax.biz/es/packages/laravel-copilot-sdk/permission-request.md)
- [Laravel MCP](https://kawax.biz/es/mcp.md)
- [Laravel AI SDK](https://kawax.biz/es/ai-sdk.md)


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