docs: add v0.4.0+ plugin format and hook usage spec

[antianqi]

What this PR adds

A single reference for Plugin authors who need to target the mcode 0.4.0+ plugin format. The v0.4.0+ runtime (@minimax-ai/code@0.4.0, 2026-09-11) adopts the Claude Code compatible plugin shape: the manifest moves to .claude-plugin/plugin.json, Hooks are inlined on the manifest, and a skills field replaces the implicit skills/<name>/SKILL.md discovery of the v0.3.x spec. Today there is no documentation of that layout in this repository; Plugin authors migrating from v0.3.x are forced to reverse-engineer the format from the runtime source.

Scope

• New proposals/hooks-v0.4-spec.md (324 lines): package shape, manifest schema, Skills layout (with the silent-drop warning for nested subdirectory paths that do not match the frontmatter name), inline Hooks (12 PascalCase events, matcher, timeout, per-handler shape), hook script conventions, migration from v0.3.x, five common pitfalls, test evidence, open questions, primary sources. Companion to proposals/hooks-detailed-spec.md; does not supersede it for the 0.3.x runtime.
• docs/plugin-compatibility.md: added a v0.4.0+ plugin format section, marked io.minimax.mcode/hooks/hooks.json as v0.3.x-only, and clarified that Hooks are accepted by mcode 0.4.0+ via the inline manifest field. Portable Agent Plugins 1.0 section unchanged.
• CONTRIBUTING.md: added a "Choose a runtime layout" subsection in step 2 pointing new contributors at the two layouts and the cross-runtime dual-shipment recommendation.
• New examples/hello-mcode-hooks-v04/ (6 files): the v0.4.0+ counterpart of examples/hello-mcode-hooks/. Demonstrates a .claude-plugin/plugin.json manifest with three inline hook handlers, a top-level Skill, a byte-identical subdir Skill copy for the validator and the v0.3.x runtime, and a PowerShell observer script that records events to ${PLUGIN_DATA}/state.json via staging-file rename.

Design compliance

• File additions only; the v0.3.x example and the v0.3.x spec are unchanged.
• No hard-coded host-absolute paths in the example; all paths use ${PLUGIN_ROOT} and ${PLUGIN_DATA}.
• No credentials, no network, no telemetry, no third-party services in the example; disclosure repeated in README.md and both SKILL.md files.
• Atomic state writes via staging-file rename; UTF-8 without BOM.
• 1 commit, 1 branch, 1 PR; no unrelated validator hardening or plugin changes mixed in.

Test evidence

• plugin.json parses as valid JSON.
• record-event.ps1 parses clean under the PowerShell AST parser.
• The two SKILL.md files are byte-identical (sha256 6502DF1DDACAFF116BB1E0328016D50994F170B8164C3BF8C9D7579653C17A31).
• The top-level Skill frontmatter name matches the manifest name and the subdir name (hello-mcode-hooks-v04).
• Path sweep (C:\, D:\, /Users/, /home/) is clean.
• Network-call sweep (Invoke-WebRequest, Invoke-RestMethod, curl, wget, http://, https:// outside the docs comment) is clean.
• Scaffold-marker sweep (TODO, FIXME, XXX, TBD, REPLACE_ME, scaffold) is clean (the one existing match in CONTRIBUTING.md is the original "Replace every scaffold TODO." instruction, unchanged by this PR).
• Negative-injection self-audit: injecting a hard-coded C:\Users\Administrator\...\evil-staging.json into record-event.ps1 was caught by the path sweep; restoring the staging-file expression brought the file back to clean.
• The empirical A/B test that proves the silent-drop failure mode and the correct layout is the mcode-island v1.0.0 release (proposal/mcode-island-0.4-hooks-rebuilt branch, PR feat(mcode-island)!: rewrite plugin manifest for mcode 0.4.0+ runtime (v1.0.0) #38): skills: ["./skills/mcode-island"] -> no hook fire; skills: ["./skills"] + top-level skills/SKILL.md -> all 12 events fire. Verified on mcode 0.4.2 (Windows 11, PowerShell 5.1).

Open questions (also captured in the proposal)

• Confirm the top-level skills/SKILL.md layout is acceptable for portable cross-runtime Plugins, or whether a separate per-Skill subdirectory is mandatory for Agent Plugins 1.0.
• Confirm hooks.timeout units (seconds vs milliseconds) for the inline shape; the current validator accepts both, but the portable shape should pin one.
• Decide whether io.minimax.mcode/hooks/hooks.json is deprecated in 0.4.0+ or merely ignored. Empirical answer: "ignored"; policy answer proposed: "deprecated for new Plugins, retained for cross-runtime compatibility".

Relationship to PR #38

PR #38 is the mcode-island v1.0.0 plugin rewrite that produced the empirical evidence this proposal documents. This PR is documentation only; it does not modify the mcode-island plugin, the validator, or any other hosted Plugin. Plugin authors who want to read about a working example of the v0.4.0+ format alongside the spec should follow the cross-links between this PR and PR #38.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}