Hooks de sesión

Con hooks puedes insertar lógica en cada punto del ciclo de vida de una sesión de Copilot.
Puedes añadir control de ejecución de herramientas, log de auditoría, enriquecimiento de prompts, manejo de errores, etc., sin tocar la implementación principal. Esta función es distinta de los hooks declarativos dentro de la definición de un agente personalizado y de la carga de hooks basados en archivos. Para la configuración por agente, consulta Agentes personalizados.

Detección de hooks basados en archivos

En hookDirectories puedes indicar raíces explícitas donde detectar hooks basados en archivos. Solo sirve para la detección y no otorga al agente permisos generales de acceso a archivos. Las raíces explícitas se pueden usar aunque enableConfigDiscovery o enableFileHooks estén deshabilitados. Las rutas relativas se resuelven una sola vez tomando como base el workingDirectory vigente en el momento de indicarlas.

Omitido o null: no cambia las demás fuentes de detección
[]: borra solo las raíces del SDK indicadas explícitamente

Los ajustes de deshabilitación por fuente de hooks y los Managed Settings siguen aplicándose. enableFileHooks controla los hooks de archivo procedentes del repositorio (.github/hooks/ y las raíces de la configuración de repositorios de confianza). No deshabilita los hookDirectories explícitos ni los hooks con callbacks de PHP.

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    workingDirectory: '/workspace/project',
    enableFileHooks: false,
    hookDirectories: ['../shared-hooks'],
);

Flujo de los hooks

Uso básico

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionHooks;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookInput;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookOutput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\SessionEndHookInput;
use Revolution\Copilot\Types\Hooks\SessionEndHookOutput;
use Revolution\Copilot\Types\Hooks\SessionStartHookInput;
use Revolution\Copilot\Types\Hooks\SessionStartHookOutput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookInput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookOutput;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: 'READMEの要点をまとめて');
    dump($response->content());
}, config: [
    'model' => 'gpt-5',
    'hooks' => new SessionHooks(
        onSessionStart: function (SessionStartHookInput $input): ?SessionStartHookOutput {
            return new SessionStartHookOutput(
                additionalContext: "Project root: {$input->cwd}",
            );
        },

        onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
            if (str_starts_with($input->prompt, '/fix')) {
                return new UserPromptSubmittedHookOutput(
                    modifiedPrompt: '現在のエラーを修正して、変更点を要約して。',
                );
            }

            return null;
        },

        onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
            $blocked = ['bash', 'shell', 'delete_file'];

            if (in_array($input->toolName, $blocked, true)) {
                return new PreToolUseHookOutput(
                    permissionDecision: 'deny',
                    permissionDecisionReason: "{$input->toolName} はこの環境では許可されていません",
                );
            }

            return new PreToolUseHookOutput(permissionDecision: 'allow');
        },

        onPostToolUse: function (PostToolUseHookInput $input): ?PostToolUseHookOutput {
            if ($input->toolName === 'read_file') {
                return new PostToolUseHookOutput(
                    additionalContext: '必要なら関連ファイルも探索して比較してください。',
                );
            }

            return null;
        },

        onErrorOccurred: function (ErrorOccurredHookInput $input): ?ErrorOccurredHookOutput {
            if ($input->errorContext === 'model_call' && $input->recoverable) {
                return new ErrorOccurredHookOutput(
                    errorHandling: 'retry',
                    retryCount: 2,
                    userNotification: '一時的なモデルエラーのためリトライします。',
                );
            }

            return null;
        },

        onSessionEnd: function (SessionEndHookInput $input): ?SessionEndHookOutput {
            if ($input->reason !== 'complete') {
                return new SessionEndHookOutput(
                    sessionSummary: "Session ended with reason: {$input->reason}",
                );
            }

            return null;
        },
    ),
]);

Hooks disponibles

Hook	Momento en el que se dispara	Uso principal
`onSessionStart`	Inicio de sesión (`new` / `resume` / `startup`)	Inyectar contexto inicial, sobreescribir configuración
`onUserPromptSubmitted`	Al enviar un prompt del usuario	Enriquecer el prompt, expandir plantillas, filtrar entradas
`onPreToolUse`	Antes de ejecutar una herramienta	Permitir / denegar / requerir confirmación, modificar argumentos, silenciar salida
`onPostToolUse`	Después de ejecutar una herramienta	Modificar resultados, enmascarar información sensible, log de auditoría
`onErrorOccurred`	Al producirse un error en la sesión	Reintentar, notificar, clasificar el error
`onSessionEnd`	Al terminar la sesión	Limpieza, métricas, resumen final

Si devuelves null, se mantiene el comportamiento por defecto.

Bloquear prompts

onUserPromptSubmitted puede rechazar un prompt devolviendo decision: 'block'. Si se rechaza, no se inicia el turn del modelo ni se registra el mensaje del usuario. Si indicas reason, su contenido se incluye en un evento session.warning temporal con warningType: "policy_blocked".

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: 'Este prompt no está permitido.',
        );
    }

    return null;
},

Casos de uso típicos

1) Permission control (control de ejecución)

Convierte las herramientas permitidas en una allow-list con onPreToolUse
Para operaciones destructivas, requiere aprobación humana con permissionDecision: 'ask'
Explicita el motivo del rechazo con permissionDecisionReason
Consulta los posibles toolName en el listado de Tools (por ejemplo view, glob, bash)

2) Auditing / compliance (auditoría)

Combina los hooks del ciclo de vida para recolectar eventos de auditoría
Persiste los datos recolectados por session ID

3) Prompt enrichment (enriquecer entradas)

En onSessionStart añade a additionalContext información del proyecto (lenguaje, framework, convenciones)
En onUserPromptSubmitted expande atajos como /fix o /test

4) Result filtering (formatear resultados)

En onPostToolUse enmascara API keys, tokens, contraseñas, etc.
Resume resultados demasiado largos y devuelve detalles solo cuando sea necesario

5) Error recovery (recuperación ante fallos)

En onErrorOccurred, haz retry solo si model_call y recoverable=true
Para errores no recuperables, notifica al usuario de forma concisa con userNotification

6) Session metrics (medición)

Registra la hora de inicio en onSessionStart
Incrementa contadores en onPreToolUse / onUserPromptSubmitted
Emite duración, número de herramientas y razón de finalización en onSessionEnd

Tipos de input / output de los hooks

Input común (`BaseHookInput`)

Propiedad	Tipo	Descripción
`sessionId`	`string`	ID de la sesión de runtime relacionada. En los hooks de herramientas hijas es la sesión hija; en los hooks de inicio/parada de subagentes es el ID de la sesión padre
`timestamp`	`int`	Momento en que se disparó el hook (Unix ms)
`cwd`	`string`	Directorio de trabajo actual
`agentId`	`?string`	ID de actor del subagente que ejecuta el hook
`agentType`	`?string`	Tipo de subagente
`parentAgentId`	`?string`	ID de actor del padre inmediato

agentId / agentType / parentAgentId están disponibles en los hooks en los que un subagente es el actor. No se incluyen en los hooks del agente raíz. En runtimes antiguos, los campos se omiten por completo cuando no hay información. Por eso, cualquiera de ellos puede ser null.

onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
    if ($input->agentId !== null) {
        logger()->info('Subagent tool use', [
            'agentId' => $input->agentId,
            'agentType' => $input->agentType,
            'parentAgentId' => $input->parentAgentId,
            'tool' => $input->toolName,
        ]);
    }

    return null;
},

`PreToolUseHookInput`

Propiedad	Tipo	Descripción
`toolName`	`string`	Nombre de la herramienta que se va a ejecutar
`toolArgs`	`mixed`	Argumentos previstos

`PreToolUseHookOutput`

Propiedad	Tipo	Descripción
`permissionDecision`	`?string`	`allow` / `deny` / `ask`
`permissionDecisionReason`	`?string`	Motivo del rechazo o confirmación
`modifiedArgs`	`mixed`	Argumentos sobreescritos
`additionalContext`	`?string`	Contexto adicional
`suppressOutput`	`?bool`	Silencia la salida de la herramienta

`PostToolUseHookInput`

Propiedad	Tipo	Descripción
`toolName`	`string`	Nombre de la herramienta ejecutada
`toolArgs`	`mixed`	Argumentos utilizados
`toolResult`	`ToolResultObject\|array`	Resultado de la herramienta

`PostToolUseHookOutput`

Propiedad	Tipo	Descripción
`modifiedResult`	`ToolResultObject\|array\|null`	Resultado modificado
`additionalContext`	`?string`	Contexto adicional
`suppressOutput`	`?bool`	Silencia la visualización del resultado

`UserPromptSubmittedHookInput`

Propiedad	Tipo	Descripción
`prompt`	`string`	Prompt introducido por el usuario

`UserPromptSubmittedHookOutput`

Propiedad	Tipo	Descripción
`modifiedPrompt`	`?string`	Prompt modificado
`additionalContext`	`?string`	Contexto complementario
`suppressOutput`	`?bool`	Silencia la visualización de la respuesta
`decision`	`?string`	Con `block` rechaza el prompt y evita el turn del modelo y el registro del mensaje del usuario
`reason`	`?string`	Motivo del rechazo. Se incluye en el evento `session.warning`

`SessionStartHookInput`

Propiedad	Tipo	Descripción
`source`	`string`	`startup` / `resume` / `new`
`initialPrompt`	`?string`	Prompt inicial

`SessionStartHookOutput`

Propiedad	Tipo	Descripción
`additionalContext`	`?string`	Contexto inicial de la sesión
`modifiedConfig`	`?array`	Sobreescritura parcial de la configuración de la sesión

`SessionEndHookInput`

Propiedad	Tipo	Descripción
`reason`	`string`	`complete` / `error` / `abort` / `timeout` / `user_exit`
`finalMessage`	`?string`	Mensaje final
`error`	`?string`	Error en el momento de la finalización. Si el runtime pasa un objeto de error, es el valor de `message` si es una cadena; si no, la cadena JSON del objeto

`SessionEndHookOutput`

Propiedad	Tipo	Descripción
`suppressOutput`	`?bool`	Silencia la salida final
`cleanupActions`	`?array`	Información de las acciones de limpieza realizadas
`sessionSummary`	`?string`	Resumen de la sesión

`ErrorOccurredHookInput`

Propiedad	Tipo	Descripción
`error`	`string`	Mensaje de error. Si el runtime pasa un objeto de error, es el valor de `message` si es una cadena; si no, la cadena JSON del objeto
`errorContext`	`string`	Uno de `model_call` / `tool_execution` / `system` / `user_input`
`recoverable`	`bool`	Si es recuperable

`ErrorOccurredHookOutput`

Propiedad	Tipo	Descripción
`suppressOutput`	`?bool`	Silencia la visualización del error
`errorHandling`	`?string`	`retry` / `skip` / `abort`
`retryCount`	`?int`	Número de reintentos
`userNotification`	`?string`	Texto de notificación al usuario

ToolResultObject

Objeto estándar del resultado de ejecución de una herramienta.

Propiedad	Tipo	Descripción
`textResultForLlm`	`?string`	Resultado en texto que se pasa al LLM
`resultType`	`?string`	`success` / `failure` / `rejected` / `denied`
`resultForAssistant`	`?array`	Datos del resultado para el assistant

Buenas prácticas

No ejecutes directamente en el hook procesos síncronos pesados. Hazlos asíncronos cuando sea necesario.
Cuando no necesites cambiar nada, devuelve null y deja que actúe el comportamiento por defecto.
Explicita permissionDecision siempre que puedas.
No silencies en exceso los errores críticos; ten una vía de log/notificación.
Gestiona el estado por sesión basándote en el session id y límpialo en onSessionEnd.

Consulta la información más reciente en el repositorio de GitHub.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds y RSS

Middleware

Hooks de sesión

Hooks de sesión

Detección de hooks basados en archivos

Flujo de los hooks

Uso básico

Hooks disponibles

Bloquear prompts

Casos de uso típicos

1) Permission control (control de ejecución)

2) Auditing / compliance (auditoría)

3) Prompt enrichment (enriquecer entradas)

4) Result filtering (formatear resultados)

5) Error recovery (recuperación ante fallos)

6) Session metrics (medición)

Tipos de input / output de los hooks

Input común (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Buenas prácticas

​Hooks de sesión

​Detección de hooks basados en archivos

​Flujo de los hooks

​Uso básico

​Hooks disponibles

​Bloquear prompts

​Casos de uso típicos

​1) Permission control (control de ejecución)

​2) Auditing / compliance (auditoría)

​3) Prompt enrichment (enriquecer entradas)

​4) Result filtering (formatear resultados)

​5) Error recovery (recuperación ante fallos)

​6) Session metrics (medición)

​Tipos de input / output de los hooks

​Input común (BaseHookInput)

​PreToolUseHookInput

​PreToolUseHookOutput

​PostToolUseHookInput

​PostToolUseHookOutput

​UserPromptSubmittedHookInput

​UserPromptSubmittedHookOutput

​SessionStartHookInput

​SessionStartHookOutput

​SessionEndHookInput

​SessionEndHookOutput

​ErrorOccurredHookInput

​ErrorOccurredHookOutput

​ToolResultObject

​Buenas prácticas

Hooks de sesión

Detección de hooks basados en archivos

Flujo de los hooks

Uso básico

Hooks disponibles

Bloquear prompts

Casos de uso típicos

1) Permission control (control de ejecución)

2) Auditing / compliance (auditoría)

3) Prompt enrichment (enriquecer entradas)

4) Result filtering (formatear resultados)

5) Error recovery (recuperación ante fallos)

6) Session metrics (medición)

Tipos de input / output de los hooks

Input común (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Buenas prácticas