Хуки

Хуки позволяют отслеживать, контролировать и расширять цикл Agent с помощью пользовательских скриптов. Определяйте хуки в файлах hooks.json на уровне проекта или пользователя либо устанавливайте их через плагины в разделе Настроить. Хуки — это отдельные процессы, обменивающиеся данными через stdio в формате JSON. Они запускаются до или после определённых этапов цикла Agent и могут отслеживать, блокировать или изменять поведение.

С помощью хуков можно:

• Запускать форматтеры после изменений
• Добавлять аналитику событий
• Проверять наличие персональных данных или секретов
• Ограничивать рискованные операции (например, запись в SQL)
• Контролировать выполнение субагентов (инструмент Task)
• Добавлять контекст в начале сессии

Категории хуков

Хуки делятся на три категории в зависимости от события, которое их вызывает:

Хуки Agent (Cmd+K/Agent Chat) срабатывают во время сессии агента:

• sessionStart / sessionEnd - Управление жизненным циклом сессии
• preToolUse / postToolUse / postToolUseFailure - Общие хуки использования инструментов (срабатывают для всех инструментов)
• subagentStart / subagentStop - Жизненный цикл субагента (инструмент Task)
• beforeShellExecution / afterShellExecution - Управление shell-командами
• beforeMCPExecution / afterMCPExecution - Управление использованием инструментов MCP
• beforeReadFile / afterFileEdit - Управление доступом к файлам и правками
• beforeSubmitPrompt - Проверка промптов перед отправкой
• preCompact - Отслеживание сжатия контекстного окна
• stop - Обработка завершения работы агента
• afterAgentResponse / afterAgentThought - Отслеживание ответов агента

Хуки Tab (встроенные дополнения) срабатывают при автономных операциях Tab:

• beforeTabFileRead - Управление доступом к файлам для Tab completions
• afterTabFileEdit - Постобработка правок Tab

Хуки жизненного цикла приложения срабатывают вне сессий агента:

• workspaceOpen - Срабатывает при открытии рабочего пространства в Cursor и при каждом изменении папки рабочего пространства. Может возвращать дополнительные пути к плагинам для загрузки в текущем рабочем пространстве.

Эти отдельные типы хуков позволяют применять разные политики к автономным операциям Tab, операциям Agent, инициированным пользователем, и запуску рабочего пространства.

Поддержка облачных агентов

Облачные агенты запускают хуки на основе команд из вашего репозитория. Если в корне проекта в файле .cursor/hooks.json определены хуки, облачные агенты обнаружат и запустят их в процессе работы.

На тарифах Enterprise облачные агенты также запускают хуки команды и хуки, управляемые на уровне Enterprise, настроенные через веб-дашборд.

Иногда на первых этапах исследования облачные агенты работают в среде только для чтения. В это время хуки не запускаются. Они начинают работать, когда агент получает среду с возможностью записи.

Поддерживаемые хуки

В облачных агентах поддерживаются следующие хуки:

Хуки, недоступные в облачных агентах

Некоторые хуки недоступны для облачных агентов из-за различий в среде выполнения:

Источники конфигурации

Облачные агенты загружают хуки из следующих источников:

• Хуки проекта (.cursor/hooks.json в вашем репозитории): загружаются и выполняются во время работы облачного агента.
• Хуки команды (Enterprise): распространяются через дашборд и выполняются в облачных агентах.
• Хуки Enterprise (Enterprise): управляемые системные хуки, выполняемые в облачных агентах.

Хуки уровня пользователя (~/.cursor/hooks.json) недоступны в облачных агентах. ВМ облачных агентов не имеют доступа к конфигурации в вашем локальном домашнем каталоге.

Ограничения по типам выполнения

Облачные агенты поддерживают только хуки на основе команд. Для хуков на основе промптов требуется настроить аутентификацию между хуком и циклом агента, что недоступно в облачной среде выполнения.

Быстрый старт

Создайте файл hooks.json. Его можно создать на уровне проекта (<project>/.cursor/hooks.json) или в домашнем каталоге (~/.cursor/hooks.json). Хуки уровня проекта действуют только в конкретном проекте, а хуки из домашнего каталога — глобально.

{  "version": 1,  "hooks": {    "afterFileEdit": [{ "command": "./hooks/format.sh" }]  }}

#!/bin/bash# Прочитайте входные данные, выполните нужные действия и завершите работу с кодом 0cat > /dev/nullexit 0

chmod +x ~/.cursor/hooks/format.sh

Cursor отслеживает файлы конфигурации хуков и автоматически перезагружает их. Хук запускается после каждого редактирования файла.

Типы хуков

Хуки поддерживают два типа выполнения: командный (по умолчанию) и промптовый (с оценкой LLM).

Хуки на основе команд

Командные хуки выполняют скрипты оболочки, получающие входные данные в формате JSON через stdin и возвращающие выходные данные в формате JSON через stdout.

{  "hooks": {    "beforeShellExecution": [      {        "command": "./scripts/approve-network.sh",        "timeout": 30,        "matcher": "curl|wget|nc"      }    ]  }}

Поведение кодов выхода:

• Код выхода 0 — хук успешно выполнен, используйте выходные данные JSON
• Код выхода 2 — заблокировать действие (эквивалентно возврату permission: "deny")
• Другие коды выхода — хук завершился с ошибкой, действие выполняется (по умолчанию ошибка не блокирует выполнение)

Промпт-хуки

Промпт-хуки используют LLM для проверки условия, сформулированного на естественном языке. Они позволяют применять политики без написания пользовательских скриптов.

{  "hooks": {    "beforeShellExecution": [      {        "type": "prompt",        "prompt": "Does this command look safe to execute? Only allow read-only operations.",        "timeout": 10      }    ]  }}

Функции:

• Возвращает структурированный ответ { ok: boolean, reason?: string }
• Использует быструю модель для быстрой оценки
• Заполнитель $ARGUMENTS автоматически заменяется JSON входных данных хука
• Если $ARGUMENTS отсутствует, входные данные хука добавляются автоматически
• Необязательное поле model для переопределения LLM-модели по умолчанию

Примеры

{  "version": 1,  "hooks": {    "sessionStart": [      {        "command": "./hooks/session-init.sh"      }    ],    "sessionEnd": [      {        "command": "./hooks/audit.sh"      }    ],    "beforeShellExecution": [      {        "command": "./hooks/audit.sh"      },      {        "command": "./hooks/block-git.sh"      }    ],    "beforeMCPExecution": [      {        "command": "./hooks/audit.sh"      }    ],    "afterShellExecution": [      {        "command": "./hooks/audit.sh"      }    ],    "afterMCPExecution": [      {        "command": "./hooks/audit.sh"      }    ],    "afterFileEdit": [      {        "command": "./hooks/audit.sh"      }    ],    "beforeSubmitPrompt": [      {        "command": "./hooks/audit.sh"      }    ],    "preCompact": [      {        "command": "./hooks/audit.sh"      }    ],    "stop": [      {        "command": "./hooks/audit.sh"      }    ],    "beforeTabFileRead": [      {        "command": "./hooks/redact-secrets-tab.sh"      }    ],    "afterTabFileEdit": [      {        "command": "./hooks/format-tab.sh"      }    ]  }}

Хук автоматизации stop на TypeScript

Выберите TypeScript, если в одном хуке нужны типизированный JSON, надёжные файловые операции и HTTP-вызовы. Этот хук stop на базе Bun отслеживает на диске количество сбоев в каждом диалоге, отправляет структурированные телеметрические данные во внутренний API и может автоматически запланировать повторную попытку, если Agent дважды подряд завершится с ошибкой.

{  "version": 1,  "hooks": {    "stop": [      {        "command": "bun run .cursor/hooks/track-stop.ts --stop"      }    ]  }}

Задайте для AGENT_TELEMETRY_URL внутренний endpoint для получения сводок о запусках.

Хук защиты манифестов Kubernetes на Python

Python особенно удобен, когда нужны мощные библиотеки для парсинга. Этот хук использует pyyaml для проверки манифестов Kubernetes перед запуском kubectl apply; Bash было бы сложно безопасно обработать YAML с несколькими документами.

{  "version": 1,  "hooks": {    "beforeShellExecution": [      {        "command": "python3 .cursor/hooks/kube_guard.py"      }    ]  }}

Установите PyYAML (например, pip install pyyaml) везде, где запускаются скрипты хуков, чтобы импорт парсера выполнялся успешно.

Партнёрские интеграции

Мы сотрудничаем с поставщиками в экосистеме, которые добавили поддержку хуков в Cursor. Эти интеграции включают сканирование безопасности, управление, управление секретами и многое другое.

Управление MCP и прозрачность

Безопасность кода и рекомендации по лучшим практикам

Безопасность зависимостей

Безопасность и защита Agent

Управление секретами

Подробнее о наших партнёрах по хукам читайте в статье «Хуки для команд безопасности и платформ».

Конфигурация

Определяйте хуки в файле hooks.json. Конфигурация может задаваться на нескольких уровнях. Выполняются все подходящие хуки из всех источников; при конфликте ответов при слиянии приоритет имеют источники более высокого уровня:

~/.cursor/├── hooks.json└── hooks/    ├── audit.sh    └── block-git.sh

• Enterprise (управляемые через MDM, общесистемные):
  • macOS: /Library/Application Support/Cursor/hooks.json
  • Linux/WSL: /etc/cursor/hooks.json
  • Windows: C:\\ProgramData\\Cursor\\hooks.json
• Команда (распространяемые через Cloud, только для Enterprise):
  • Настраиваются в веб-дашборде и автоматически синхронизируются со всеми участниками команды
• Проект (для конкретного проекта):
  • <project-root>/.cursor/hooks.json
  • Хуки проекта запускаются в любом доверенном рабочем пространстве и добавляются в систему контроля версий вместе с проектом
• Пользователь (для конкретного пользователя):
  • ~/.cursor/hooks.json

Порядок приоритета (от высшего к низшему): Enterprise → Команда → Проект → Пользователь

Объект hooks сопоставляет имена хуков с массивами определений хуков. Каждое определение в настоящее время поддерживает свойство command, которое может быть строкой для оболочки, абсолютным или относительным путём. Рабочий каталог зависит от источника хука:

• Хуки проекта (.cursor/hooks.json в репозитории): Запускаются из корня проекта
• Хуки пользователя (~/.cursor/hooks.json): Запускаются из ~/.cursor/
• Хуки Enterprise (общесистемная конфигурация): Запускаются из каталога конфигурации Enterprise
• Хуки команды (распространяемые через Cloud): Запускаются из каталога управляемых хуков

Для хуков проекта используйте пути вроде .cursor/hooks/script.sh (относительно корня проекта), а не ./hooks/script.sh (который будет искать <project>/hooks/script.sh).

Файл конфигурации

В этом примере показан файл пользовательских хуков (~/.cursor/hooks.json). Для хуков на уровне проекта замените пути, например ./hooks/script.sh, на .cursor/hooks/script.sh:

{  "version": 1,  "hooks": {    "sessionStart": [{ "command": "./session-init.sh" }],    "sessionEnd": [{ "command": "./audit.sh" }],    "preToolUse": [      {        "command": "./hooks/validate-tool.sh",        "matcher": "Shell|Read|Write"      }    ],    "postToolUse": [{ "command": "./hooks/audit-tool.sh" }],    "subagentStart": [{ "command": "./hooks/validate-subagent.sh" }],    "subagentStop": [{ "command": "./hooks/audit-subagent.sh" }],    "beforeShellExecution": [{ "command": "./script.sh" }],    "afterShellExecution": [{ "command": "./script.sh" }],    "afterMCPExecution": [{ "command": "./script.sh" }],    "afterFileEdit": [{ "command": "./format.sh" }],    "preCompact": [{ "command": "./audit.sh" }],    "stop": [{ "command": "./audit.sh", "loop_limit": 10 }],    "beforeTabFileRead": [{ "command": "./redact-secrets-tab.sh" }],    "afterTabFileEdit": [{ "command": "./format-tab.sh" }],    "workspaceOpen": [{ "command": "./register-workspace-plugins.sh" }]  }}

Хуки Agent (sessionStart, sessionEnd, preToolUse, postToolUse, postToolUseFailure, subagentStart, subagentStop, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, preCompact, stop, afterAgentResponse, afterAgentThought) применяются к операциям Cmd+K и Agent Chat. Хуки Tab (beforeTabFileRead, afterTabFileEdit) применяются только к встроенным автодополнениям Tab. Хук жизненного цикла приложения (workspaceOpen) срабатывает при открытии рабочего пространства и изменении его папок независимо от сессии агента.

Глобальные параметры конфигурации

Параметры конфигурации отдельных скриптов

Конфигурация matcher

Matcher позволяет указать, при каких условиях запускается hook. Поле, к которому применяется matcher, зависит от hook:

{  "hooks": {    "preToolUse": [      {        "command": "./validate-shell.sh",        "matcher": "Shell"      }    ],    "subagentStart": [      {        "command": "./validate-explore.sh",        "matcher": "explore|shell"      }    ],    "beforeShellExecution": [      {        "command": "./approve-network.sh",        "matcher": "curl|wget|nc "      }    ]  }}

• subagentStart: сопоставитель проверяет тип субагента (например, explore, shell, generalPurpose). Используйте его, чтобы запускать хуки только при запуске субагента определённого типа. В примере выше validate-explore.sh запускается только для субагентов типа explore или shell.
• beforeShellExecution: сопоставитель проверяет строку команды оболочки. Используйте его, чтобы запускать хуки только когда команда соответствует шаблону (например, выполняет сетевые вызовы или удаляет файлы). В примере выше approve-network.sh запускается только если команда содержит curl, wget или nc .

Доступные сопоставители для каждого хука:

• preToolUse / postToolUse / postToolUseFailure: фильтрация по типу инструмента. Возможные значения: Shell, Read, Write, Grep, Delete, Task и инструменты MCP в формате MCP:<tool_name>.
• subagentStart / subagentStop: фильтрация по типу субагента (generalPurpose, explore, shell и т. д.).
• beforeShellExecution / afterShellExecution: фильтрация по тексту команды оболочки; сопоставитель проверяет полную строку команды.
• beforeReadFile: фильтрация по типу инструмента (TabRead, Read и т. д.).
• afterFileEdit: фильтрация по типу инструмента (TabWrite, Write и т. д.).
• beforeSubmitPrompt: сопоставляется со значением UserPromptSubmit.
• stop: сопоставляется со значением Stop.
• afterAgentResponse: сопоставляется со значением AgentResponse.
• afterAgentThought: сопоставляется со значением AgentThought.

Распространение в команде

Хуки можно распространять среди участников команды через хуки проекта (с помощью системы контроля версий), инструменты MDM или систему облачного распространения Cursor.

Хуки проекта (контроль версий)

Хуки проекта — самый простой способ поделиться хуками с командой. Поместите файл hooks.json в <project-root>/.cursor/hooks.json и закоммитьте его в репозиторий. Когда участники команды открывают проект в доверенном рабочем пространстве, Cursor автоматически загружает и запускает хуки проекта.

Облачные агенты также загружают эти хуки проекта, когда работают с вашим репозиторием в облаке.

Хуки проекта:

• Хранятся в системе контроля версий вместе с кодом
• Автоматически загружаются для всех участников команды в доверенных рабочих пространствах
• Могут быть настроены для конкретного проекта (например, обеспечивать соблюдение стандартов форматирования в определённой кодовой базе)
• Для запуска требуют доверенного рабочего пространства (в целях безопасности)

Распространение через MDM

Распространяйте хуки в своей организации с помощью инструментов управления мобильными устройствами (MDM). Разместите файл hooks.json и скрипты хуков в соответствующих каталогах на каждом компьютере.

Домашний каталог пользователя (распространение для отдельных пользователей):

• ~/.cursor/hooks.json
• ~/.cursor/hooks/ (для скриптов хуков)

Глобальные каталоги (распространение для всей системы):

• macOS: /Library/Application Support/Cursor/hooks.json
• Linux/WSL: /etc/cursor/hooks.json
• Windows: C:\\ProgramData\\Cursor\\hooks.json

Примечание: распространением через MDM полностью управляет ваша организация. Cursor не развертывает файлы и не управляет ими через ваше MDM-решение. Убедитесь, что ваша внутренняя ИТ-команда или команда безопасности выполняет настройку, развертывание и обновление в соответствии с политиками вашей организации.

Облачное распространение (только для Enterprise)

Команды Enterprise могут использовать встроенное облачное распространение Cursor для автоматической синхронизации хуков со всеми участниками команды. Настройте хуки в веб-дашборде. Cursor автоматически доставляет настроенные хуки на все клиентские компьютеры, когда участники команды входят в систему.

Облачное распространение обеспечивает:

• Автоматическую синхронизацию со всеми участниками команды каждые тридцать минут
• Выбор целевой операционной системы для платформозависимых хуков
• Централизованное управление через дашборд

Администраторы Enterprise могут создавать, редактировать и управлять командными хуками через дашборд без доступа к отдельным компьютерам.

Свяжитесь с отделом продаж, чтобы подключить облачное распространение хуков Enterprise.

Справочник

Общая схема

Входные данные (все хуки)

Помимо полей, специфичных для каждого хука, все хуки получают базовый набор полей:

{  "conversation_id": "string",  "generation_id": "string",  "model": "string",  "model_id": "string",  "model_params": [{ "id": "string", "value": "string" }],  "hook_event_name": "string",  "cursor_version": "string",  "workspace_roots": ["<path>"],  "user_email": "string | null",  "transcript_path": "string | null"}

События хуков

preToolUse

Вызывается перед выполнением любого инструмента. Это универсальный хук, который срабатывает для всех типов инструментов (Shell, Read, Write, MCP, Task и т. д.). Используйте сопоставители, чтобы отфильтровать конкретные инструменты.

// Входные данные{  "tool_name": "Shell",  "tool_input": { "command": "npm install", "working_directory": "/project" },  "tool_use_id": "abc123",  "cwd": "/project",  "model": "claude-opus-4-7-thinking-max",  "model_id": "claude-opus-4-7",  "model_params": [    { "id": "thinking", "value": "true" },    { "id": "context", "value": "1m" },    { "id": "effort", "value": "max" }  ],  "agent_message": "Installing dependencies..."}// Выходные данные{  "permission": "allow" | "deny",  "user_message": "<message shown in client when denied>",  "agent_message": "<message sent to agent when denied>",  "updated_input": { "command": "npm ci" }}

postToolUse

Вызывается после успешного выполнения инструмента. Используется для аудита, аналитики и добавления контекста.

// Входные данные{  "tool_name": "Shell",  "tool_input": { "command": "npm test" },  "tool_output": "{\"exitCode\":0,\"stdout\":\"All tests passed\"}",  "tool_use_id": "abc123",  "cwd": "/project",  "duration": 5432,  "model": "claude-opus-4-7-thinking-max",  "model_id": "claude-opus-4-7",  "model_params": [    { "id": "thinking", "value": "true" },    { "id": "context", "value": "1m" },    { "id": "effort", "value": "max" }  ]}// Выходные данные{  "updated_mcp_tool_output": { "modified": "output" },  "additional_context": "Test coverage report attached."}

postToolUseFailure

Вызывается, если инструмент завершился с ошибкой, превысил время ожидания или получил отказ. Используется для отслеживания ошибок и логики восстановления.

// Входные данные{  "tool_name": "Shell",  "tool_input": { "command": "npm test" },  "tool_use_id": "abc123",  "cwd": "/project",  "error_message": "Command timed out after 30s",  "failure_type": "timeout" | "error" | "permission_denied",  "duration": 5000,  "is_interrupt": false}// Выходные данные{  // Выходные поля пока не поддерживаются}

subagentStart

Вызывается перед созданием субагента (инструмент Task). Позволяет разрешить или запретить его создание.

// Входные данные{  "subagent_id": "abc-123",  "subagent_type": "generalPurpose",  "task": "Explore the authentication flow",  "parent_conversation_id": "conv-456",  "tool_call_id": "tc-789",  "subagent_model": "claude-sonnet-4-20250514",  "is_parallel_worker": false,  "git_branch": "feature/auth"}// Выходные данные{  "permission": "allow" | "deny",  "user_message": "<message shown when denied>"}

subagentStop

Вызывается, когда субагент завершает работу, завершается с ошибкой или прерывается. Может запускать последующие действия.

// Входные данные{  "subagent_type": "generalPurpose",  "status": "completed" | "error" | "aborted",  "task": "Explore the authentication flow",  "description": "Exploring auth flow",  "summary": "<subagent output summary>",  "duration_ms": 45000,  "message_count": 12,  "tool_call_count": 8,  "loop_count": 0,  "modified_files": ["src/auth.ts"],  "agent_transcript_path": "/path/to/subagent/transcript.txt"}// Выходные данные{  "followup_message": "<auto-continue with this message>"}

Поле followup_message поддерживает циклические сценарии, в которых завершение работы субагента запускает следующую итерацию. К последующим действиям применяется то же настраиваемое ограничение числа циклов, что и к хуку stop (по умолчанию — 5, настраивается через loop_limit).

beforeShellExecution / beforeMCPExecution

Вызывается перед выполнением любой shell-команды или инструмента MCP. Верните решение о предоставлении права доступа.

// Входные данные beforeShellExecution{  "command": "<full terminal command>",  "cwd": "<current working directory>",  "sandbox": false}// Входные данные beforeMCPExecution{  "tool_name": "<tool name>",  "tool_input": "<json params>"}// А также одно из:{ "url": "<server url>" }// Или:{ "command": "<command string>" }// Выходные данные{  "permission": "allow" | "deny" | "ask",  "user_message": "<message shown in client>",  "agent_message": "<message sent to agent>"}

afterShellExecution

Срабатывает после выполнения команды в оболочке; используется для аудита или сбора метрик из выходных данных команды.

// Входные данные{  "command": "<full terminal command>",  "output": "<full terminal output>",  "duration": 1234,  "sandbox": false}

afterMCPExecution

Срабатывает после выполнения инструмента MCP; содержит входные параметры инструмента и полный результат в формате JSON.

// Входные данные{  "tool_name": "<tool name>",  "tool_input": "<json params>",  "result_json": "<tool result json>",  "duration": 1234}

afterFileEdit

Срабатывает после редактирования файла Agent; полезно для форматтеров или учёта кода, написанного агентом.

// Входные данные{  "file_path": "<absolute path>",  "edits": [{ "old_string": "<search>", "new_string": "<replace>" }]}

beforeReadFile

Вызывается перед тем, как Agent читает файл. Используйте для контроля доступа, чтобы предотвратить отправку конфиденциальных файлов в модель.

// Входные данные{  "file_path": "<absolute path>",  "content": "<file contents>",  "attachments": [    {      "type": "file" | "rule",      "file_path": "<absolute path>"    }  ]}// Выходные данные{  "permission": "allow" | "deny",  "user_message": "<message shown when denied>"}

beforeTabFileRead

Вызывается перед тем, как Tab (встроенные дополнения) читает файл. Настройте редактирование или контроль доступа до того, как Tab получит доступ к содержимому файла.

Ключевые отличия от beforeReadFile:

• Срабатывает только для Tab, не для Agent
• Не содержит поля attachments (Tab не использует вложения в промптах)
• Позволяет применять отдельные политики к автономным операциям Tab

// Входные данные{  "file_path": "<absolute path>",  "content": "<file contents>"}// Выходные данные{  "permission": "allow" | "deny"}

afterTabFileEdit

Вызывается после того, как Tab (встроенные дополнения) вносит изменения в файл. Полезно для форматтеров и аудита кода, записанного Tab.

Ключевые отличия от afterFileEdit:

• Срабатывает только при использовании Tab, а не Agent
• Включает подробные сведения об изменениях: range, old_line и new_line для точного отслеживания правок
• Полезно для детального форматирования или анализа правок, внесённых Tab

// Входные данные{  "file_path": "<absolute path>",  "edits": [    {      "old_string": "<search>",      "new_string": "<replace>",      "range": {        "start_line_number": 10,        "start_column": 5,        "end_line_number": 10,        "end_column": 20      },      "old_line": "<line before edit>",      "new_line": "<line after edit>"    }  ]}// Выходные данные{  // Выходные поля пока не поддерживаются}

beforeSubmitPrompt

Вызывается сразу после нажатия пользователем кнопки отправки, но до запроса к бэкенду. Может отменить отправку.

// Входные данные{  "prompt": "<user prompt text>",  "attachments": [    {      "type": "file" | "rule",      "file_path": "<absolute path>"    }  ]}// Выходные данные{  "continue": true | false,  "user_message": "<message shown to user when blocked>"}

afterAgentResponse

Вызывается после того, как агент завершил формирование сообщения ассистента.

// Входные данные{  "text": "<assistant final text>"}

afterAgentThought

Вызывается после того, как Agent завершает блок мышления. Позволяет отслеживать ход рассуждений Agent.

// Входные данные{  "text": "<fully aggregated thinking text>",  "duration_ms": 5000}// Выходные данные{  // Выходные поля пока не поддерживаются}

stop

Вызывается при завершении цикла Agent. При необходимости может автоматически отправить следующее сообщение пользователя, чтобы продолжить итерации.

// Входные данные{  "status": "completed" | "aborted" | "error",  "loop_count": 0}

// Выходные данные{  "followup_message": "<message text>"}

• Необязательное поле followup_message содержит строку. Если оно задано и не пустое, Cursor автоматически отправит её как следующее сообщение пользователя. Это позволяет создавать циклические сценарии (например, выполнять итерации до достижения цели).
• Поле loop_count показывает, сколько раз хук stop уже автоматически отправлял следующее сообщение в этом диалоге (начиная с 0). По умолчанию для каждого скрипта разрешено не более 5 автоматических последующих сообщений; это ограничение можно настроить параметром loop_limit. Задайте loop_limit значение null, чтобы снять ограничение. То же ограничение действует для последующих сообщений subagentStop.

sessionStart

Вызывается при создании нового диалога в composer. Этот хук работает по принципу fire-and-forget: цикл Agent не ожидает и не требует блокирующего ответа. Используйте его, чтобы задать переменные среды для конкретной сессии или добавить дополнительный контекст.

// Входные данные{  "session_id": "<unique session identifier>",  "is_background_agent": true | false,  "composer_mode": "agent" | "ask" | "edit"}

// Выходные данные{  "env": { "<key>": "<value>" },  "additional_context": "<context to add to conversation>"}

sessionEnd

Вызывается при завершении диалога в composer. Это хук типа fire-and-forget, полезный для логирования, аналитики или очистки. Ответ записывается в журнал, но не используется.

// Входные данные{  "session_id": "<unique session identifier>",  "reason": "completed" | "aborted" | "error" | "window_close" | "user_close",  "duration_ms": 45000,  "is_background_agent": true | false,  "final_status": "<status string>",  "error_message": "<error details if reason is 'error'>"}

// Выходные данные{  // Выходных полей нет — отправил и забыл}

preCompact

Вызывается перед сжатием или суммированием контекстного окна. Это наблюдательный хук: он не может блокировать или изменять процесс сжатия. Полезен для логирования сжатия или уведомления пользователей.

// Входные данные{  "trigger": "auto" | "manual",  "context_usage_percent": 85,  "context_tokens": 120000,  "context_window_size": 128000,  "message_count": 45,  "messages_to_compact": 30,  "is_first_compaction": true | false}

// Выходные данные{  "user_message": "<message to show when compaction occurs>"}

workspaceOpen

Срабатывает при открытии рабочей области в Cursor и при каждом изменении папок рабочей области. Не срабатывает, если в окне нет папок рабочей области. Работает в приложении Cursor для компьютера и CLI.

// Входные данные{  "hook_event_name": "workspaceOpen",  "cursor_version": "string",  "workspace_roots": ["<absolute path>"],  "user_email": "string | null"}// Выходные данные{  "pluginPaths": ["<absolute path>", "..."]}

Переменные среды

При выполнении скриптам хуков передаются переменные среды:

Переменные среды уровня сессии, заданные хуками sessionStart, передаются при всех последующих запусках хуков в этой сессии.

Устранение неполадок

Как проверить, активны ли хуки

Во вкладке Hooks раздела Настроить и канале выходных данных Hooks можно отлаживать настроенные и выполненные хуки, а также просматривать ошибки.

Если хуки не работают

• Cursor отслеживает файлы hooks.json и перезагружает их при сохранении. Если хуки по-прежнему не загружаются, перезапустите Cursor.
• Проверьте правильность относительных путей к исходным файлам хуков:
  • Для хуков проекта пути задаются относительно корня проекта (например, .cursor/hooks/script.sh)
  • Для пользовательских хуков пути задаются относительно ~/.cursor/ (например, ./hooks/script.sh или hooks/script.sh)

Блокировка по коду выхода

Код выхода 2 командного хука блокирует действие (эквивалентно возврату permission: "deny"). Это соответствует поведению Claude Code для совместимости.