Refresh Cursor plugin contract coverage against current public docs

[ScriptedAlchemy]

Summary

The Cursor adapter is pinned to the full Cursor Plugin contract from PR #131, but Cursor's public plugin reference now documents additional surfaces and exposes at least one incorrect capability claim in the current table. Track those deltas as one host umbrella under #100/#107.

Observed 2026-09-01:

• https://cursor.com/docs/plugins
• https://prod.cursor.com/docs/reference/plugins
• https://cursor.com/docs/agent/hooks

Confirmed mismatch

adapters/capabilities/cursor-2026-08-28.json and cursor.ts mark marketplace support unavailable, while the public reference defines .cursor-plugin/marketplace.json for multi-plugin repositories, its fields, component overrides, and merge/resolution behavior.

workspaceOpen is marked supported as a canonical route, but its native contract is distinct: it fires outside an agent session, omits conversation fields, and returns pluginPaths. The current shared Cursor wrapper/result vocabulary does not model that output. Do not retain a supported claim without a fixture proving the actual envelope.

The running SubagentStart/SubagentStop correction lane remains authoritative for those two events.

Checklist

Every item must become implemented, credited to an active lane, or explicitly unavailable/deferred in the capability table with a reason.

Plugin formats and components

• Record both formats explicitly: portable Agent Plugin (plugin.json, skills/MCP) and full Cursor Plugin (.cursor-plugin/plugin.json)
• Full Cursor Plugin metadata, minClientVersions, logo/assets, category/tags/publisher where schema-supported
• Rules, agents, and commands discovery/path lowering (already in Compile capability-aware host component bundles #100 stage 3; Cursor rules first)
• Complete variables schema and secret-value separation; every ${VAR} used by MCP config declared
• Default discovery versus manifest replacement for skills/rules/agents/commands/hooks/MCP/root SKILL.md
• .cursor-plugin/marketplace.json schema, max entries, entry component overrides, manifest merge precedence, and resolution
• Marketplace install modes (Default Off, Default On, Required), scope/access, local-import admin control, Git auto-refresh, and manual review/publish flow
• Local physical install under ~/.cursor/plugins/local, while preserving PR fix(cursor): conform local plugin artifacts to real host #131's realpath/symlink safety finding

Hooks

• Pin all documented Agent events: sessionStart, sessionEnd, preToolUse, postToolUse, postToolUseFailure, subagentStart, subagentStop, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, preCompact, stop, afterAgentResponse, afterAgentThought
• Pin Tab events beforeTabFileRead/afterTabFileEdit and app event workspaceOpen
• Model cloud-agent event/handler availability separately from desktop/CLI availability
• Support or explicitly reject prompt hooks, failClosed, loop_limit, timeout, and matcher semantics by event
• Correct workspaceOpen input/output (pluginPaths) and prove it independently of agent-session wrappers
• Treat shell/MCP/read/edit specialty hooks as selector-rich native variants of canonical tool routes where semantics align; otherwise record why a dedicated route family is required
• Keep response/thought and Tab events deferred unless a canonical consumer need is accepted; capability rows must still name them

Acceptance

• The marketplace capability claim matches the public reference.
• Every documented Cursor component and hook event has a supported/degraded/unavailable/prohibited state with dated evidence.
• workspaceOpen, subagent lifecycle, and tool lifecycle each have native fixture replay using their actual distinct payloads and output channels.
• No Agent Plugin and Cursor Plugin paths/tokens are mixed.

Related: #107 #100 #97 #101 #108 #131 #133 #181

[ScriptedAlchemy]

The public Plugins overview also advertises prebuilt plugin canvases, but the Cursor Plugin manifest/reference read on 2026-09-01 does not define a canvas component field or file contract. Add an explicit unavailable/deferred capability row for plugin canvases until Cursor publishes a schema-backed authoring contract; do not infer one from marketplace examples.

Source: https://cursor.com/docs/plugins (read 2026-09-01).

[ScriptedAlchemy]

Two of the confirmed mismatches are corrected on main by #221 (merged as 49281f1):

Marketplace — corrected to supported with pinned evidence. .cursor-plugin/marketplace.json is real: schemas/marketplace.schema.json exists in cursor/plugins at the exact commit #131 pinned for the plugin schema (070189284e702e8a4d2e3cc8913994b204c5337a). The official schema is now vendored (sha256 1aae96a24c2796419933bc8bfe3a1255394e7199c35740b36325e0ce6dbc253d, recorded in schemas/cursor/PROVENANCE.json), the cursor target and the unified bundle emit a schema-validated marketplace document when marketplace: true, and the capability row is supported. This checks off the marketplace acceptance criterion; the broader marketplace items (max entries, component overrides, merge precedence, install modes, Git auto-refresh) remain open for the umbrella.

workspaceOpen — supported claim removed. Per this issue's requirement not to retain a supported claim without a fixture proving the actual envelope: the native contract is sessionless (no session/conversation fields) and its response must return pluginPaths; both generated Cursor wrappers hard-require session_id/conversation_id on stdin and have no pluginPaths output channel. workspace/open is now unavailable on Cursor with that exact reason in cursor-2026-08-28.json, a plain workspaceOpen hook now produces a cursor.hook.event.workspace-open diagnostic instead of silently lowering a broken wrapper, and the event-family matrix in the example README is corrected. A future native fixture replay of the real sessionless envelope can re-admit it honestly.

Also fixed in the same PR (from the #173 review thread): the unified plugin adapter's composite capabilities now intersect Cursor alongside Claude and Codex — event families fail closed on table divergence, and the composite metadata fingerprint covers all three host pins.

Checklist impact: “.cursor-plugin/marketplace.json schema” is now schema-pinned and emitted; “Correct workspaceOpen input/output (pluginPaths)” is resolved as explicit unavailable with the documented reason (native fixture replay still outstanding before any supported claim).