Cursor Hooks: как пользоваться хуками агента

Cursor Hooks — это способ наблюдать, блокировать и расширять agent loop своими скриптами. Хуки описываются в hooks.json (project или user), запускаются как процессы и обмениваются JSON через stdin/stdout. Канон: cursor.com/docs/hooks. Не путать с Rules (текст инструкций) и Skills (процедуры для агента) — hooks исполняют код на событиях.

Соседи: Cursor для начинающих, Cursor CLI, Cloud Agents, Bugbot. Pillar — n8n / автоматизация.

Для кого Cursor Hooks

Берите hooks, если нужны guardrails: запрет опасного shell, аудит MCP, автоформат после правок, политика для subagent. Если достаточно «помни про стиль» — rules. Если нужен чеклист деплоя — skill. Built-in skill /create-hook помогает сгенерировать конфиг.

*По cursor.com/docs/hooks (август 2026). Таблица support для cloud — из официальной доки. Партнёрские интеграции security/governance — в разделе Partner Integrations той же страницы.

Как пользоваться: маршрут на 1 вечер

1. Создайте .cursor/hooks.json в корне репозитория (или ~/.cursor/hooks.json для глобальных user hooks).
2. Добавьте скрипт, например .cursor/hooks/format.sh, сделайте executable (chmod +x).
3. Для project hooks указывайте путь от корня проекта: .cursor/hooks/format.sh (не ./hooks/...).
4. Подпишитесь на событие, начните с безопасного afterFileEdit или matcher на beforeShellExecution.
5. Проверьте exit codes: 0 ок, 2 блок, иное — fail-open.
6. Для Cloud Agents коммитьте project hooks; user-level с ноутбука в VM не приедет.

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      { "command": ".cursor/hooks/format.sh" }
    ],
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/approve-network.sh",
        "timeout": 30,
        "matcher": "curl|wget|nc"
      }
    ]
  }
}

Agent, Tab и Cloud

Agent hooks покрывают sessionStart/End, pre/postToolUse, shell, MCP, read/edit, submit prompt, compact, stop, afterAgentResponse/Thought, subagentStart/Stop. Tab hooks отдельно — только для Tab completions. Cloud: работают command hooks вроде beforeShellExecution, afterFileEdit, pre/postToolUse, subagent*, stop; не работают sessionStart/End, Tab, workspaceOpen; MCP hooks отложены. Prompt-based hooks в cloud не поддерживаются.

Третьесторонние хуки (Claude Code и др.) — см. docs reference/third-party-hooks. Enterprise может раздавать team/enterprise hooks через dashboard.

Сильные стороны

• Реальный контроль исполнения, не только «просьба» в промпте.
• Matcher на команды — узкий scope без шума на каждый tool call.
• JSON stdin/stdout — удобно для политики allow/deny и аудита.
• Одинаковый project-конфиг подхватывают Cloud Agents из репо.
• Можно комбинировать с partner integrations (security/secrets).

Типичные ошибки

• Путь ./hooks/... в project hooks.json — скрипт не находится (нужен путь от корня проекта).
• Считать, что user ~/.cursor/hooks.json работает в Cloud Agent.
• Писать prompt-hook и ждать его на cloud — там только command-based.
• Игнорировать exit 2 vs fail-open: сломанный хук может молча пропускать действие.
• Путать hooks с Automations/Bugbot — это разные контуры продукта.

FAQ: Cursor Hooks

Вывод

Cursor Hooks — исполняемый слой контроля agent loop. Старт: один project hook на afterFileEdit или beforeShellExecution → проверка локально → commit для Cloud Agents. Инструкции агенту — в Rules и Skills; общий вход — гайд новичка.