doctor: AB7320/AB6027 false positive — Cursor static validation checks hooks/hooks.json (Claude format) instead of the file the Cursor manifest references (hooks-cursor.json)

[ScriptedAlchemy]

Summary

agent-bundle doctor reports a freshly installed Cursor plugin as invalid, three times, even though the install came straight from a bundle that agent-bundle validate accepted and install.mjs wrote byte-for-byte.

AB7320: Static validation of cursor bytes at "/home/zack/.cursor/plugins/local/cargo-hauler" reported AB6027: hooks/hooks.json/hooks: must NOT have additional properties.
Recovery: Reinstall the Cursor plugin from a freshly validated bundle, then rerun Doctor.

(repeated 3× — presumably once per hook event.)

Cause

The plugin target emits one bundle for Claude, Codex, and Cursor. The bundle's hooks/ directory contains both hook manifests:

• hooks/hooks.json — Claude format (PreToolUse/PostToolUse/Stop, ${CLAUDE_PLUGIN_ROOT}), referenced by .claude-plugin/plugin.json
• hooks/hooks-cursor.json — Cursor format (preToolUse/postToolUse/stop, version: 1, ${CURSOR_PLUGIN_ROOT}), referenced by .cursor-plugin/plugin.json → "hooks": "./hooks/hooks-cursor.json"

Doctor's Cursor static validation validates hooks/hooks.json against the Cursor hooks schema regardless of what .cursor-plugin/plugin.json#hooks points to. The PascalCase Claude event names are the "additional properties". The file the Cursor loader actually reads (hooks-cursor.json) is valid.

Expected

Doctor should validate the hooks file named by each host manifest's hooks field, and only that file. (The emitter could alternatively avoid placing the other host's manifest at the assumed path, but the manifest-driven lookup is the right fix: the install tree is exactly what the framework emitted.)

Repro

cargo-hauler 0.3.5 (framework mode, targets: ['plugin', 'portable'], three event routes with targets: ['plugin']), agent-bundle 0.0.0-preview-105c65d:

pnpm build && node artifact/plugin/install.mjs     # installs to ~/.cursor/plugins/local/cargo-hauler
pnpm exec agent-bundle doctor                       # → 3× AB7320/AB6027 as above
jq .hooks ~/.cursor/plugins/local/cargo-hauler/.cursor-plugin/plugin.json   # "./hooks/hooks-cursor.json"

The suggested recovery (reinstall from a validated bundle) cannot resolve it, since that is exactly what was done.

Also observed in the same run (minor)

AB7303 for Claude and Codex ("no pinned read-only inventory verb") is counted as an error-level finding; it is a known framework limitation rather than a problem with the install, so info/warning level would keep the Doctor summary error count meaningful.

[ScriptedAlchemy]

Fixed in #442 (merged as 10a98a0fb).

Root cause confirmed: validateCursorPluginFiles hard-coded hooks/hooks.json as the Cursor hooks document and parsed it with the pinned Cursor hooks schema, ignoring .cursor-plugin/plugin.json#hooks. The unified plugin target emits the Claude/Codex-format document at hooks/hooks.json and points Cursor at hooks/hooks-cursor.json (Cursor's documented "manifest field replaces folder discovery" rule), so the PascalCase Claude events were the "additional properties". The emitter is not defective: the standalone cursor target emits only the Cursor-format document at hooks/hooks.json, and the unified bundle's dual layout is exactly what the Cursor manifest pointer exists for.

Fix: the validator now resolves the hooks source from the manifest (resolveCursorHooksSource): a string is a plugin-root-relative file validated under its own path (missing or escaping the plugin root → AB6027 error), an object is validated inline (.cursor-plugin/plugin.json#/hooks), and only an absent field falls back to hooks/hooks.json. The same resolver drives doctor inventory (AB7320), doctor --from (AB7319), the AB7322 hook-registration proof, and the agent-bundle/test installed-host check, so all four agree.

Evidence — a targets: ['plugin', 'portable'] project with three plugin-only hooks (the cargo-hauler shape), built with the repo CLI and installed with the emitted install.mjs into an isolated HOME:

Command	Before	After
agent-bundle doctor --host cursor	3 error(s): AB7320 … AB6027: hooks/hooks.json/hooks: must NOT have additional properties ×3	0 error(s); AB7322 info: registers preToolUse, sessionStart, stop (3 command(s)) through the manifest
agent-bundle doctor --host cursor --from artifact/plugin	3× AB7319 (same text), bundle.state = corrupt	0 AB7319/AB7320, bundle.state = installed

Tests: 6 new validator cases (5 fail on the pre-fix source), 3 new Doctor cases, and the Cursor host-install proof now installs the plugin bundle into a fresh isolated home and asserts zero AB7320/AB6027 findings with hooks registered from hooks/hooks-cursor.json (it reproduces the exact issue message against the pre-fix source). Docs: docs/diagnostics.md AB6027/AB7320/AB7322 now name the manifest-driven resolution.

Not addressed here (minor note in the issue): the AB7303 severity for Claude/Codex ("no pinned read-only inventory verb") is a separate diagnostic outside this lane; it would need its own issue/PR.