hooks: decide Cursor behavior for hook events and matchers Cursor does not map

Parent

Problem

Cursor loads our plugins' hooks/hooks.json and runs the mapped events. The probe saw SessionStart and PreToolUse with the Bash matcher fire, with CLAUDE_PLUGIN_ROOT set. It did not see UserPromptSubmit fire in headless runs.

Cursor's mapping table at https://cursor.com/docs/reference/third-party-hooks.md (read 2026-11-02) covers these events only: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact and UserPromptSubmit. It marks Notification and PermissionRequest as not supported, and maps tools Bash to Shell and Edit to Write, with Glob not supported.

From plugins/*/hooks/hooks.json on main, these plugins depend on events or matchers outside that table, so in Cursor they are expected to do nothing. This is a docs-based expectation and was not probed per plugin:

PostToolBatch: bash-format, biome-format, eol-normalizer, go-format, markdown-format, ruff-format. The formatters would not run in Cursor.
Notification: desktop-notification. Documented as not supported.
PostCompact: context-guard.
StopFailure: harness-ops, rate-limit-guard.
UserPromptExpansion: disk-hygiene, harness-ops.
ConfigChange, InstructionsLoaded, PermissionDenied, PostToolUseFailure: harness-ops.
WorktreeCreate and WorktreeRemove: source-control.
Tool matchers with no Cursor mapping: NotebookEdit, PowerShell, Skill, Workflow, Artifact and mcp__* names. These are used by guardrails, disk-hygiene, context-budget, review, harness-ops and source-control.
SessionStart source matchers (startup|resume|clear|fork): the docs say nothing about them. Used by disk-hygiene and harness-ops.

Outcome

Decide, for each affected plugin, whether its Cursor behavior is accepted as a no-op, documented, or reworked onto a mapped event (for example, a formatter on PostToolUse instead of PostToolBatch). Do this without Cursor-specific files. Confirm the UserPromptSubmit result in the Cursor IDE, since the probe ran only the headless CLI.

Out of scope

Cursor-specific files or a forked plugin.

Done when

Decision: comment.

docs/cursor-compatibility.md exists as the one marketplace-level note. It lists the events and matchers above that Cursor does not map, each stated as an accepted no-op, with no Cursor-specific files and no per-plugin edits.
The six formatters stay on PostToolBatch, and the note says they do not run in Cursor.
The note records UserPromptSubmit as not observed in headless Cursor CLI runs (8 runs, marketplace: research Cursor plugin import with no fork and no Cursor specifics #7556) and unverified in the IDE. No manual check is added.
The note lists the SessionStart source matchers as undocumented by Cursor and unprobed.
Each claim in the note cites https://cursor.com/docs/reference/third-party-hooks.md or the marketplace: research Cursor plugin import with no fork and no Cursor specifics #7556 probe.

Proposed work class: work-class: scoped
Basis: automated intake triage; the lanes App applied this class.

Size: Small
Complexity: Low
Uncertainty: Known
Flags: none
Blocked by: none

Understood: record how Cursor treats hook events and matchers it does not map, with no Cursor-specific files and no plugin rework.

Decision recorded. Accept the triage recommendations, with one change to item 4. (1) Hooks on events or matchers Cursor does not map are accepted as no-ops and documented, with no rework and no Cursor-specific files. (2) The six formatters stay on PostToolBatch: moving them to PostToolUse would change Claude Code behavior by running them per edit. (3) One marketplace-level note, docs/cursor-compatibility.md, lists the unmapped events and matchers and also holds #12483's tool-limit facts. (4) No manual IDE check: the note records UserPromptSubmit as not observed in headless Cursor CLI runs (8 runs, #7556), unverified in the IDE. The owner's direction is to add no recurring manual steps. (5) SessionStart source matchers are noted as undocumented by Cursor and unprobed. Basis: #7556 probe and https://cursor.com/docs/reference/third-party-hooks.md (read 2026-11-02). Decided under the owner's standing direction.

#12484 (comment)

This decision settles the open questions. The remaining work is writing the one docs note.

_{Automated triage, applied by the lanes App.}

The latest triage verdict holds nothing: admission moved the issue to status: confirmed; its comment says why.

Refinement. A read-only run explored this repository, searched its issues and pull requests, and read the allowed docs to draft what follows. On an issue a listed human filed, it counts as the issue's spec once posted, while unedited; it is still model text, so check it.

Intended outcome: Accept unmapped Cursor hooks as no-ops, document them once in a marketplace-level compatibility note, leave PostToolBatch formatters unchanged, and confirm UserPromptSubmit in the Cursor IDE by hand.

Related work

marketplace: research Cursor plugin import with no fork and no Cursor specifics #7556 (related): Parent research issue holding the Cursor probe result.
plugins: decide tool-restriction behavior in Cursor, which ignores disallowed-tools and agent tool lists #12483 (related): Sibling decision on Cursor tool restrictions; not a duplicate.
skills: carry when_to_use trigger text into Cursor, which ignores the key #12482 (related): Sibling Cursor gap on when_to_use; not a duplicate.

Open questions

What default applies to hooks on events or matchers Cursor does not map: accept as a no-op, document, or rework onto a mapped event?
RECOMMENDED: Accept as a no-op and document it, with no rework and no Cursor-specific files. Basis: judgment
Should the six formatters (bash-format, biome-format, eol-normalizer, go-format, markdown-format, ruff-format) move from PostToolBatch to PostToolUse?
RECOMMENDED: No. It would change Claude Code behavior by running them per edit. Revisit only after measuring the cost. Basis: plugins/ruff-format/hooks/hooks.json:4
Where should the Cursor compatibility documentation live?
RECOMMENDED: One marketplace-level compatibility note listing the unmapped events and matchers, not per-plugin edits. Basis: judgment
Is the UserPromptSubmit check in the Cursor IDE a done-when item of this issue, or a separate manual check?
RECOMMENDED: Make it a separate manual check a person runs. An unattended run cannot do it, and the headless result stays recorded as not observed. Basis: https://github.com/marketplace: research Cursor plugin import with no fork and no Cursor specifics #7556
Do the SessionStart source matchers (startup|resume|clear|fork) need a probe before the note says anything about them?
RECOMMENDED: Note them as undocumented by Cursor and unprobed, with no per-plugin action until a probe exists. Basis: judgment

Sources read

plugins/ruff-format/hooks/hooks.json:4: registers its formatter on PostToolBatch, an event the issue says Cursor does not map.
refine-data/context.json: no **Decision recorded.** comment exists, so the owner has settled none of the open questions.

To answer, post a comment that starts with this line:

**Decision recorded.** <answer>

_{Automated refinement by the lanes App. Answer with a comment whose first line is **Decision recorded.**.}

Agent choice, not an owner answer. The owner did not answer this question. Lane 2 chose on the #7556 evidence, and Issue Triage owns the question. Accept the triage recommendations, with one change to item 4. (1) Hooks on events or matchers Cursor does not map are accepted as no-ops and documented, with no rework and no Cursor-specific files. (2) The six formatters stay on PostToolBatch: moving them to PostToolUse would change Claude Code behavior by running them per edit. (3) One marketplace-level note, docs/cursor-compatibility.md, lists the unmapped events and matchers and also holds #12483's tool-limit facts. (4) No manual IDE check: the note records UserPromptSubmit as not observed in headless Cursor CLI runs (8 runs, #7556), unverified in the IDE. The owner's direction is to add no recurring manual steps. (5) SessionStart source matchers are noted as undocumented by Cursor and unprobed. Basis: #7556 probe and https://cursor.com/docs/reference/third-party-hooks.md (read 2026-11-02). Decided under the owner's standing direction.

This records a re-fire of an earlier refusal, not a new refusal. The lanes kill switch stopped run 41522475675, the work-resolve-issue run that agent-ready started, before it did any work; that run ended at 2026-11-02T20:50:00Z. work-unblock has now removed and added agent-ready back to start a fresh run. A kill-switch refusal is no fault in this issue or the lanes, so it never counts against later re-fires; after limits.limit-stops-per-issue of them since a person last added agent-ready or a run last reported, work-unblock waits longer before each one, up to 24 hours.

No description provided.

The work-resolve-issue lane stopped on this issue (split-required): the issue's Size is too large for one run, and intake's split (owner Q93) files its sub-issues.
Its Size is too large for one run: intake splits it into sub-issues (owner Q93).
It removed agent-ready and status: ready, so the hourly triage sweep sends it back through intake triage, and it waits on no decision from a person.

Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/41523564235

The triage sweep dispatched intake triage for this issue (attempt 1 of 2).

Not admitted to the issue lane: no trusted-human acceptance criteria: a listed human must put the confirmed - [ ] criteria in the body or post them as their own comment, or, on an issue a listed human filed, intake's newest refinement comment must hold them unedited. Admission takes the issue once each of those is met, when intake triages it again (.github/actions/resolve-config/admission-rules.json).

No description provided.

Navigation Menu

Repository navigation

hooks: decide Cursor behavior for hook events and matchers Cursor does not map #12484

Parent

Problem

Outcome

Out of scope

Done when

1 remaining item

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

hooks: decide Cursor behavior for hook events and matchers Cursor does not map #12484

Description

Parent

Problem

Outcome

Out of scope

Done when

Activity

github-actions commented on Nov 2, 2026

melodic-automation-lanes commented on Nov 2, 2026

melodic-automation-lanes commented on Nov 2, 2026

kyle-sexton commented on Nov 2, 2026

melodic-automation-lanes commented on Nov 2, 2026

1 remaining item

github-actions commented on Nov 2, 2026

melodic-automation-lanes commented on Nov 2, 2026

github-actions commented on Nov 2, 2026

melodic-automation-lanes commented on Nov 2, 2026

github-actions commented on Nov 2, 2026

github-actions commented on Nov 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions