{"meta":{"title":"Trabajar con enlaces","intro":"Los enlaces permiten conectar lógica personalizada en cada fase de una sesión de Copilot, desde el momento en que se inicia, a través de cada solicitud de usuario y llamada a herramienta, hasta el momento en que finaliza. En esta guía se describen casos de uso prácticos para que pueda enviar permisos, auditorías, notificaciones y mucho más sin modificar el comportamiento del agente principal.","product":"GitHub Copilot","breadcrumbs":[{"href":"/es/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/es/enterprise-cloud@latest/copilot/how-tos","title":"Procedimientos"},{"href":"/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"SDK de Copilot"},{"href":"/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"Características"},{"href":"/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/hooks","title":"Hooks"}],"documentType":"article"},"body":"# Trabajar con enlaces\n\nLos enlaces permiten conectar lógica personalizada en cada fase de una sesión de Copilot, desde el momento en que se inicia, a través de cada solicitud de usuario y llamada a herramienta, hasta el momento en que finaliza. En esta guía se describen casos de uso prácticos para que pueda enviar permisos, auditorías, notificaciones y mucho más sin modificar el comportamiento del agente principal.\n\n\n\n\n\n## Visión general\n\nUn gancho es un callback que se registra una vez al crear una sesión. El SDK lo invoca en un punto bien definido en el ciclo de vida de la conversación, pasa la entrada contextual y, opcionalmente, acepta la salida que modifica el comportamiento de la sesión.\n\n![Diagrama: Diagrama de flujo que muestra el proceso descrito.](/assets/images/help/copilot/copilot-sdk/features-hooks-diagram-0.png)\n\n| Enlace | Cuando se activa | Qué puede hacer |\n| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------- |\n| [Enlaces de ciclo de vida de sesión](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-start) | Comienza la sesión (nueva o reanudada) | Insertar contexto, preferencias de carga |\n| [Enlace enviado de la solicitud de usuario](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted) | El usuario envía un mensaje | Reescribir avisos, añadir contexto, filtrar entrada |\n| [Gancho de transformación de la solicitud al usuario](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed) | El entorno de ejecución construye el prompt del modelo. | Inspeccionar o sustituir contenido orientado al modelo |\n| [Gancho previo al uso de la herramienta](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/pre-tool-use) | Antes de que se ejecute una herramienta | Permitir, denegar o modificar la llamada |\n| [Enlace de uso posterior a la herramienta](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/post-tool-use) | Después de que una herramienta devuelva el resultado (solo en caso de éxito) | Transformación de resultados, redacción de secretos, auditoría |\n| [Enlace de uso posterior a la herramienta](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/post-tool-use#failure-variant) | Después de que una herramienta devuelva un error | Insertar directrices de reintento, registrar fallos |\n| [Enlaces de ciclo de vida de sesión](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-end) | Finaliza la sesión | Limpieza y registro de métricas |\n| [Gancho de manejo de errores](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/error-handling) | Se genera un error | Registro personalizado, lógica de reintento, alertas |\n\nTodos los hooks son **opcionales**: registre solo los que necesite. Al retornar `null` (o el equivalente en el idioma) desde cualquier enlace, se indica al SDK que continúe con el comportamiento predeterminado.\n\n## Registro de enlaces\n\nPase un `hooks` objeto al crear (o reanudar) una sesión. Cada ejemplo siguiente sigue este patrón.\n\n
\n
TypeScript
\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nawait client.start();\n\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input, invocation) => {\n /* ... */\n },\n onPreToolUse: async (input, invocation) => {\n /* ... */\n },\n onPostToolUse: async (input, invocation) => {\n /* ... */\n },\n // ... add only the hooks you need\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import CopilotClient, PermissionDecisionApproveOnce\n\nclient = CopilotClient()\nawait client.start()\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\n \"on_session_start\": on_session_start,\n \"on_pre_tool_use\": on_pre_tool_use,\n \"on_post_tool_use\": on_post_tool_use,\n # ... add only the hooks you need\n },\n)\n```\n\n
\n\n
Go
\n\n```golang\nclient := copilot.NewClient(nil)\n\nsession, err := client.CreateSession(ctx, &copilot.SessionConfig{\n Hooks: &copilot.SessionHooks{\n OnSessionStart: onSessionStart,\n OnPreToolUse: onPreToolUse,\n OnPostToolUse: onPostToolUse,\n // ... add only the hooks you need\n },\n OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {\n return &rpc.PermissionDecisionApproveOnce{}, nil\n },\n})\n```\n\n
\n\n
.NET
\n\n```csharp\nvar client = new CopilotClient();\n\nvar session = await client.CreateSessionAsync(new SessionConfig\n{\n Hooks = new SessionHooks\n {\n OnSessionStart = onSessionStart,\n OnPreToolUse = onPreToolUse,\n OnPostToolUse = onPostToolUse,\n // ... add only the hooks you need\n },\n OnPermissionRequest = (req, inv) =>\n Task.FromResult(PermissionDecision.ApproveOnce()),\n});\n```\n\n
\n\n
Java
\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\nimport java.util.concurrent.CompletableFuture;\n\ntry (var client = new CopilotClient()) {\n client.start().get();\n\n var hooks = new SessionHooks()\n .setOnSessionStart((input, inv) -> CompletableFuture.completedFuture(null))\n .setOnPreToolUse((input, inv) -> CompletableFuture.completedFuture(null))\n .setOnPostToolUse((input, inv) -> CompletableFuture.completedFuture(null));\n // ... add only the hooks you need\n\n var session = client.createSession(\n new SessionConfig()\n .setHooks(hooks)\n .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n ).get();\n}\n```\n\n
\n\n
\n\n> \\[!TIP]\n> Cada controlador de enlace recibe un `invocation` parámetro que contiene el `sessionId`, lo cual resulta útil para correlacionar registros y mantener el estado por sesión.\n\n## Caso de uso: control de permisos\n\nUse `onPreToolUse` para crear una capa de permisos que decida qué herramientas puede ejecutar el agente, qué argumentos se permiten y si se debe solicitar al usuario antes de la ejecución.\n\n### Permitir una lista segura de herramientas\n\n
\n
TypeScript
\n\n```typescript\nconst READ_ONLY_TOOLS = [\"read_file\", \"glob\", \"grep\", \"view\"];\n\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n if (!READ_ONLY_TOOLS.includes(input.toolName)) {\n return {\n permissionDecision: \"deny\",\n permissionDecisionReason: `Only read-only tools are allowed. \"${input.toolName}\" was blocked.`,\n };\n }\n return { permissionDecision: \"allow\" };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import PermissionDecisionApproveOnce\n\nREAD_ONLY_TOOLS = [\"read_file\", \"glob\", \"grep\", \"view\"]\n\nasync def on_pre_tool_use(input_data, invocation):\n if input_data[\"toolName\"] not in READ_ONLY_TOOLS:\n return {\n \"permissionDecision\": \"deny\",\n \"permissionDecisionReason\":\n f'Only read-only tools are allowed. \"{input_data[\"toolName\"]}\" was blocked.',\n }\n return {\"permissionDecision\": \"allow\"}\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\"on_pre_tool_use\": on_pre_tool_use},\n)\n```\n\n
\n\n
Go
\n\n```golang\nreadOnlyTools := map[string]bool{\"read_file\": true, \"glob\": true, \"grep\": true, \"view\": true}\n\nsession, _ := client.CreateSession(ctx, &copilot.SessionConfig{\n Hooks: &copilot.SessionHooks{\n OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {\n if !readOnlyTools[input.ToolName] {\n return &copilot.PreToolUseHookOutput{\n PermissionDecision: \"deny\",\n PermissionDecisionReason: fmt.Sprintf(\"Only read-only tools are allowed. %q was blocked.\", input.ToolName),\n }, nil\n }\n return &copilot.PreToolUseHookOutput{PermissionDecision: \"allow\"}, nil\n },\n },\n})\n```\n\n
\n\n
.NET
\n\n```csharp\nvar readOnlyTools = new HashSet { \"read_file\", \"glob\", \"grep\", \"view\" };\n\nvar session = await client.CreateSessionAsync(new SessionConfig\n{\n Hooks = new SessionHooks\n {\n OnPreToolUse = (input, invocation) =>\n {\n if (!readOnlyTools.Contains(input.ToolName))\n {\n return Task.FromResult(new PreToolUseHookOutput\n {\n PermissionDecision = \"deny\",\n PermissionDecisionReason = $\"Only read-only tools are allowed. \\\"{input.ToolName}\\\" was blocked.\",\n });\n }\n return Task.FromResult(\n new PreToolUseHookOutput { PermissionDecision = \"allow\" });\n },\n },\n});\n```\n\n
\n\n
Java
\n\n\n\n```java\nimport java.util.Set;\nimport java.util.concurrent.CompletableFuture;\n\nimport com.github.copilot.rpc.PermissionHandler;\nimport com.github.copilot.rpc.SessionConfig;\nimport com.github.copilot.rpc.SessionHooks;\nimport com.github.copilot.rpc.PreToolUseHookOutput;\nvar readOnlyTools = Set.of(\"read_file\", \"glob\", \"grep\", \"view\");\n\nvar hooks = new SessionHooks()\n .setOnPreToolUse((input, invocation) -> {\n if (!readOnlyTools.contains(input.getToolName())) {\n return CompletableFuture.completedFuture(\n PreToolUseHookOutput.deny(\n \"Only read-only tools are allowed. \\\"\" + input.getToolName() + \"\\\" was blocked.\")\n );\n }\n return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());\n });\n\nvar session = client.createSession(\n new SessionConfig()\n .setHooks(hooks)\n .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n).get();\n```\n\n
\n\n
\n\n### Restricción del acceso a archivos a directorios específicos\n\n```typescript\nconst ALLOWED_DIRS = [\"/home/user/projects\", \"/tmp\"];\n\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n if ([\"read_file\", \"write_file\", \"edit\"].includes(input.toolName)) {\n const filePath = (input.toolArgs as { path: string }).path;\n const allowed = ALLOWED_DIRS.some((dir) => filePath.startsWith(dir));\n\n if (!allowed) {\n return {\n permissionDecision: \"deny\",\n permissionDecisionReason: `Access to \"${filePath}\" is outside the allowed directories.`,\n };\n }\n }\n return { permissionDecision: \"allow\" };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n### Preguntar al usuario antes de las operaciones destructivas\n\n```typescript\nconst DESTRUCTIVE_TOOLS = [\"delete_file\", \"shell\", \"bash\"];\n\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n if (DESTRUCTIVE_TOOLS.includes(input.toolName)) {\n return { permissionDecision: \"ask\" };\n }\n return { permissionDecision: \"allow\" };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\nAl devolver `\"ask\"`, se delega la decisión al usuario en tiempo de ejecución, lo cual resulta útil para acciones destructivas en las que se desea la intervención directa del usuario.\n\n## Caso de uso: auditoría y cumplimiento\n\nCombine `onPreToolUse`, `onPostToolUse`y los enlaces del ciclo de vida de la sesión para crear una pista de auditoría completa que registre todas las acciones que realiza el agente.\n\n### Registro de auditoría estructurado\n\n
\n
TypeScript
\n\n```typescript\ninterface AuditEntry {\n timestamp: Date;\n sessionId: string;\n event: string;\n toolName?: string;\n toolArgs?: unknown;\n toolResult?: unknown;\n prompt?: string;\n}\n\nconst auditLog: AuditEntry[] = [];\n\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"session_start\",\n });\n return null;\n },\n onUserPromptSubmitted: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"user_prompt\",\n prompt: input.prompt,\n });\n return null;\n },\n onPreToolUse: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"tool_call\",\n toolName: input.toolName,\n toolArgs: input.toolArgs,\n });\n return { permissionDecision: \"allow\" };\n },\n onPostToolUse: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"tool_result\",\n toolName: input.toolName,\n toolResult: input.toolResult,\n });\n return null;\n },\n onSessionEnd: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"session_end\",\n });\n\n // Persist the log — swap this with your own storage backend\n await fs.promises.writeFile(\n `audit-${invocation.sessionId}.json`,\n JSON.stringify(auditLog, null, 2),\n );\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n\n\n```python\nimport json, aiofiles\nfrom copilot import PermissionDecisionApproveOnce\n\naudit_log = []\n\nasync def on_session_start(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"session_start\",\n })\n return None\n\nasync def on_user_prompt_submitted(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"user_prompt\",\n \"prompt\": input_data[\"prompt\"],\n })\n return None\n\nasync def on_pre_tool_use(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"tool_call\",\n \"tool_name\": input_data[\"toolName\"],\n \"tool_args\": input_data[\"toolArgs\"],\n })\n return {\"permissionDecision\": \"allow\"}\n\nasync def on_post_tool_use(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"tool_result\",\n \"tool_name\": input_data[\"toolName\"],\n \"tool_result\": input_data[\"toolResult\"],\n })\n return None\n\nasync def on_session_end(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"session_end\",\n })\n async with aiofiles.open(f\"audit-{invocation['session_id']}.json\", \"w\") as f:\n await f.write(json.dumps(audit_log, indent=2))\n return None\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\n \"on_session_start\": on_session_start,\n \"on_user_prompt_submitted\": on_user_prompt_submitted,\n \"on_pre_tool_use\": on_pre_tool_use,\n \"on_post_tool_use\": on_post_tool_use,\n \"on_session_end\": on_session_end,\n },\n)\n```\n\n
\n\n
\n\n### Redactar secretos en los resultados de la herramienta\n\n```typescript\nconst SECRET_PATTERNS = [\n /(?:api[_-]?key|token|secret|password)\\s*[:=]\\s*[\"']?[\\w\\-\\.]+[\"']?/gi,\n];\n\nconst session = await client.createSession({\n hooks: {\n onPostToolUse: async (input) => {\n if (typeof input.toolResult !== \"string\") return null;\n\n let redacted = input.toolResult;\n for (const pattern of SECRET_PATTERNS) {\n redacted = redacted.replace(pattern, \"[REDACTED]\");\n }\n\n return redacted !== input.toolResult\n ? { modifiedResult: redacted }\n : null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Caso de uso: notificaciones y sonidos\n\nLos enlaces se activan en el proceso de su aplicación para que pueda desencadenar cualquier efecto secundario, como notificaciones de escritorio, sonidos, mensajes de Slack o llamadas de webhook.\n\n### Notificación de escritorio en eventos de sesión\n\n
\n
TypeScript
\n\n```typescript\nimport notifier from \"node-notifier\"; // npm install node-notifier\n\nconst session = await client.createSession({\n hooks: {\n onSessionEnd: async (input, invocation) => {\n notifier.notify({\n title: \"Copilot Session Complete\",\n message: `Session ${invocation.sessionId.slice(0, 8)} finished (${input.reason}).`,\n });\n return null;\n },\n onErrorOccurred: async (input) => {\n notifier.notify({\n title: \"Copilot Error\",\n message: input.error.slice(0, 200),\n });\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n```python\nimport subprocess\nfrom copilot import PermissionDecisionApproveOnce\n\nasync def on_session_end(input_data, invocation):\n sid = invocation[\"session_id\"][:8]\n reason = input_data[\"reason\"]\n subprocess.Popen([\n \"notify-send\", \"Copilot Session Complete\",\n f\"Session {sid} finished ({reason}).\",\n ])\n return None\n\nasync def on_error_occurred(input_data, invocation):\n subprocess.Popen([\n \"notify-send\", \"Copilot Error\",\n input_data[\"error\"][:200],\n ])\n return None\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\n \"on_session_end\": on_session_end,\n \"on_error_occurred\": on_error_occurred,\n },\n)\n```\n\n
\n\n
\n\n### Reproducir un sonido cuando una herramienta finaliza\n\n```typescript\nimport { exec } from \"node:child_process\";\n\nconst session = await client.createSession({\n hooks: {\n onPostToolUse: async (input) => {\n // macOS: play a system sound after every tool call\n exec(\"afplay /System/Library/Sounds/Pop.aiff\");\n return null;\n },\n onErrorOccurred: async () => {\n exec(\"afplay /System/Library/Sounds/Basso.aiff\");\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n### Enviar a Slack sobre errores\n\n```typescript\nconst SLACK_WEBHOOK_URL = process.env.SLACK_WEBHOOK_URL!;\n\nconst session = await client.createSession({\n hooks: {\n onErrorOccurred: async (input, invocation) => {\n if (!input.recoverable) {\n await fetch(SLACK_WEBHOOK_URL, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n text: `🚨 Unrecoverable error in session \\`${invocation.sessionId.slice(0, 8)}\\`:\\n\\`\\`\\`${input.error}\\`\\`\\``,\n }),\n });\n }\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Caso de uso: enriquecimiento de mensajes\n\nUse `onSessionStart` y `onUserPromptSubmitted` para insertar automáticamente el contexto para que los usuarios no tengan que repetirse.\n\n### Inserción de metadatos del proyecto en el inicio de sesión\n\n```typescript\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input) => {\n const pkg = JSON.parse(\n await fs.promises.readFile(\"package.json\", \"utf-8\"),\n );\n return {\n additionalContext: [\n `Project: ${pkg.name} v${pkg.version}`,\n `Node: ${process.version}`,\n `Working directory: ${input.workingDirectory}`,\n ].join(\"\\n\"),\n };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n### Expansión de comandos abreviados en mensajes\n\n```typescript\nconst SHORTCUTS: Record = {\n \"/fix\": \"Find and fix all errors in the current file\",\n \"/test\": \"Write comprehensive unit tests for this code\",\n \"/explain\": \"Explain this code in detail\",\n \"/refactor\": \"Refactor this code to improve readability\",\n};\n\nconst session = await client.createSession({\n hooks: {\n onUserPromptSubmitted: async (input) => {\n for (const [shortcut, expansion] of Object.entries(SHORTCUTS)) {\n if (input.prompt.startsWith(shortcut)) {\n const rest = input.prompt.slice(shortcut.length).trim();\n return { modifiedPrompt: rest ? `${expansion}: ${rest}` : expansion };\n }\n }\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Caso de uso: control de errores y recuperación\n\nEl `onErrorOccurred` enlace le da la oportunidad de reaccionar a los errores, ya sea que eso significa reintentar, notificar a un humano o cerrar correctamente.\n\n### Reintentar errores de modelo transitorio\n\n```typescript\nconst session = await client.createSession({\n hooks: {\n onErrorOccurred: async (input) => {\n if (input.errorContext === \"model_call\" && input.recoverable) {\n return {\n errorHandling: \"retry\",\n retryCount: 3,\n userNotification: \"Temporary model issue — retrying…\",\n };\n }\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n### Mensajes de error amigables\n\n```typescript\nconst FRIENDLY_MESSAGES: Record = {\n model_call: \"The AI model is temporarily unavailable. Please try again.\",\n tool_execution: \"A tool encountered an error. Check inputs and try again.\",\n system: \"A system error occurred. Please try again later.\",\n};\n\nconst session = await client.createSession({\n hooks: {\n onErrorOccurred: async (input) => {\n return {\n userNotification: FRIENDLY_MESSAGES[input.errorContext] ?? input.error,\n };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Caso de uso: métricas de sesión\n\nRealice un seguimiento de cuánto tiempo las sesiones se ejecutan, cuántas herramientas se invocan y por qué las sesiones finalizan, lo cual es útil para paneles de control y monitoreo de costos.\n\n
\n
TypeScript
\n\n```typescript\nconst metrics = new Map<\n string,\n { start: Date; toolCalls: number; prompts: number }\n>();\n\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input, invocation) => {\n metrics.set(invocation.sessionId, {\n start: input.timestamp,\n toolCalls: 0,\n prompts: 0,\n });\n return null;\n },\n onUserPromptSubmitted: async (_input, invocation) => {\n metrics.get(invocation.sessionId)!.prompts++;\n return null;\n },\n onPreToolUse: async (_input, invocation) => {\n metrics.get(invocation.sessionId)!.toolCalls++;\n return { permissionDecision: \"allow\" };\n },\n onSessionEnd: async (input, invocation) => {\n const m = metrics.get(invocation.sessionId)!;\n const durationSec =\n (input.timestamp.getTime() - m.start.getTime()) / 1000;\n\n console.log(\n `Session ${invocation.sessionId.slice(0, 8)}: ` +\n `${durationSec.toFixed(1)}s, ${m.prompts} prompts, ` +\n `${m.toolCalls} tool calls, ended: ${input.reason}`,\n );\n\n metrics.delete(invocation.sessionId);\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import PermissionDecisionApproveOnce\n\nsession_metrics = {}\n\nasync def on_session_start(input_data, invocation):\n session_metrics[invocation[\"session_id\"]] = {\n \"start\": input_data[\"timestamp\"],\n \"tool_calls\": 0,\n \"prompts\": 0,\n }\n return None\n\nasync def on_user_prompt_submitted(input_data, invocation):\n session_metrics[invocation[\"session_id\"]][\"prompts\"] += 1\n return None\n\nasync def on_pre_tool_use(input_data, invocation):\n session_metrics[invocation[\"session_id\"]][\"tool_calls\"] += 1\n return {\"permissionDecision\": \"allow\"}\n\nasync def on_session_end(input_data, invocation):\n m = session_metrics.pop(invocation[\"session_id\"])\n duration = (input_data[\"timestamp\"] - m[\"start\"]).total_seconds()\n sid = invocation[\"session_id\"][:8]\n print(\n f\"Session {sid}: {duration:.1f}s, {m['prompts']} prompts, \"\n f\"{m['tool_calls']} tool calls, ended: {input_data['reason']}\"\n )\n return None\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\n \"on_session_start\": on_session_start,\n \"on_user_prompt_submitted\": on_user_prompt_submitted,\n \"on_pre_tool_use\": on_pre_tool_use,\n \"on_session_end\": on_session_end,\n },\n)\n```\n\n
\n\n
\n\n## Combinación de enlaces\n\nLos hooks se integran de manera natural. Un único objeto `hooks` puede gestionar permisos **y** auditoría **y** notificaciones: cada hook cumple su propia función.\n\n```typescript\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input) => {\n console.log(`[audit] session started in ${input.workingDirectory}`);\n return { additionalContext: \"Project uses TypeScript and Vitest.\" };\n },\n onPreToolUse: async (input) => {\n console.log(`[audit] tool requested: ${input.toolName}`);\n if (input.toolName === \"shell\") {\n return { permissionDecision: \"ask\" };\n }\n return { permissionDecision: \"allow\" };\n },\n onPostToolUse: async (input) => {\n console.log(`[audit] tool completed: ${input.toolName}`);\n return null;\n },\n onErrorOccurred: async (input) => {\n console.error(`[alert] ${input.errorContext}: ${input.error}`);\n return null;\n },\n onSessionEnd: async (input, invocation) => {\n console.log(\n `[audit] session ${invocation.sessionId.slice(0, 8)} ended: ${input.reason}`,\n );\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## procedimientos recomendados\n\n1. **Mantenga los enlaces rápidos.** Cada enlace se ejecuta en línea: los enlaces lentos retrasan la conversación. Descargue trabajos pesados (escrituras en bases de datos, llamadas HTTP) a una cola en segundo plano cuando sea posible.\n\n2. **Vuelva `null` cuando no tenga nada que cambiar.** Esto indica al SDK que continúe con los valores predeterminados y evite la asignación de objetos innecesaria.\n\n3. **Sea explícito con las decisiones de permisos.** Devolver `{ permissionDecision: \"allow\" }` es más claro que devolver `null`, aunque ambos permiten la herramienta.\n\n4. **No trague errores críticos.** Está bien suprimir los errores de herramientas recuperables, pero siempre registre o alerte sobre los que no son recuperables.\n\n5. **Use `additionalContext` en lugar de `modifiedPrompt` cuando sea posible.** Agregar contexto conserva la intención original del usuario mientras sigue guiando el modelo.\n\n6. **Estado de ámbito por identificador de sesión.** Si realiza un seguimiento de los datos por sesión, úselo como clave `invocation.sessionId` y limpie durante `onSessionEnd`.\n\n## Reference\n\nPara obtener definiciones de tipo completas, tablas de campos de entrada y salida y ejemplos adicionales para cada enlace, consulte la referencia de API:\n\n* [Enlaces de sesión](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/hooks-overview)\n* [Gancho previo al uso de la herramienta](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/pre-tool-use)\n* [Enlace de uso posterior a la herramienta](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/post-tool-use)\n* [Enlace enviado de la solicitud de usuario](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted)\n* [Gancho de transformación de la solicitud al usuario](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed)\n* [Enlaces de ciclo de vida de sesión](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/session-lifecycle)\n* [Gancho de manejo de errores](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/error-handling)\n\n## Consulte también\n\n* [Crea tu primera aplicación con tecnología Copilot](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/getting-started)\n* [Agentes personalizados y orquestación de subagentes](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/custom-agents)\n* [Eventos de la sesión de transmisión](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/streaming-events)\n* [Guía de depuración](/es/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/debugging)"}