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

CONTRIBUTING.md

@@ -28,6 +28,25 @@ Replace every scaffold `TODO`. Your Plugin must:
 Keep source and docs inside your Plugin directory. Do not edit another contributor's Plugin in the
 same pull request.
 
+### Choose a runtime layout
+
+`docs/plugin-compatibility.md` describes two layouts. Pick one before you write `plugin.json`:
+
+- The **portable Agent Plugins 1.0** layout (top-level `plugin.json`, optional
+  `io.minimax.mcode/hooks/hooks.json` for Hooks) is the cross-runtime baseline. Use it when
+  your Plugin must run on both mcode 0.3.x and mcode 0.4.0+. The validator
+  (`scripts/validate.mjs`) checks this layout by default.
+- The **v0.4.0+ plugin format** (`.claude-plugin/plugin.json` with inline `hooks`) is the
+  preferred form for Plugins that target mcode 0.4.0+ only. The full schema and the inline
+  `hooks` shape are in [`proposals/hooks-v0.4-spec.md`](proposals/hooks-v0.4-spec.md); a
+  working example is in [`examples/hello-mcode-hooks-v04/`](examples/hello-mcode-hooks-v04/).
+
+A Plugin that needs both runtimes ships both layouts in parallel. The v0.3.x layout does
+not need to duplicate the v0.4.0+ Skill; the recommended cross-runtime shape ships
+`skills/SKILL.md` (used by mcode 0.4.0+) and `skills/<plugin-name>/SKILL.md` (a byte-identical
+copy under a subdirectory whose name matches the Plugin's `name`, used by the v0.3.x
+runtime and the current validator).
+
 ## 3. Check it
 
 ```bash

docs/plugin-compatibility.md

@@ -1,6 +1,22 @@
 # MiniMax Code plugin compatibility
 
-## Portable package
+This document describes what MiniMax Code reads from an Agent Plugin. There are two runtime
+layouts in active use:
+
+- The **portable Agent Plugins 1.0** layout below is the cross-runtime baseline. It is what the
+  validator checks and what mcode 0.3.x reads. It is also what mcode 0.4.0+ continues to accept
+  when it is found on disk.
+- The **v0.4.0+ plugin format** section below describes the Claude Code compatible layout that
+  mcode 0.4.0+ adopts as the preferred form: the manifest moves to `.claude-plugin/plugin.json`
+  and Hooks are inlined on the manifest. A Plugin that targets mcode 0.4.0+ exclusively should
+  use this layout; a Plugin that targets both 0.3.x and 0.4.0+ should ship both layouts in
+  parallel.
+
+The full v0.4.0+ Hooks specification is in
+[`proposals/hooks-v0.4-spec.md`](../proposals/hooks-v0.4-spec.md) and a working example is in
+[`examples/hello-mcode-hooks-v04/`](../examples/hello-mcode-hooks-v04/).
+
+## Portable package (Agent Plugins 1.0, mcode 0.3.x)
 
 MiniMax Code reads the portable subset of Agent Plugins 1.0:
 
@@ -51,20 +67,85 @@ MiniMax Code reserves `PLUGIN_ROOT` and `PLUGIN_DATA`. A plugin must not set tho
 Do not embed tokens in environment values or headers. Generic OAuth configuration is not part of
 this portable subset.
 
+## v0.4.0+ plugin format (mcode 0.4.0+ runtime)
+
+mcode 0.4.0+ (`@minimax-ai/code@0.4.0`, released 2026-09-11) adopts the Claude Code compatible
+plugin shape as the preferred form. A Plugin that targets mcode 0.4.0+ exclusively uses this
+layout; a Plugin that targets both 0.3.x and 0.4.0+ ships both layouts in parallel.
+
+```text
+plugin-root/
+├── README.md                                  # required by this community repository
+├── LICENSE                                    # required by this community repository
+├── .claude-plugin/
+│   └── plugin.json                            # the v0.4.0+ manifest, with inline `hooks`
+├── io.minimax.mcode/                          # hook scripts, same layout as the portable package
+│   └── hooks/
+│       └── scripts/
+│           └── *.ps1 | *.mjs | *.sh            # one script per event handler
+└── skills/
+    ├── SKILL.md                               # top-level single Skill (preferred for a focused Plugin)
+    └── <plugin-name>/                         # subdir copy, for the v0.3.x runtime and the validator
+        └── SKILL.md
+```
+
+The v0.4.0+ manifest is a single JSON object whose only strictly required field is `name`. The
+full schema and the inline `hooks` shape are in
+[`proposals/hooks-v0.4-spec.md`](../proposals/hooks-v0.4-spec.md); the short summary is:
+
+- `name` (required): Plugin name; lowercase letters, digits, single hyphens.
+- `version` (recommended): Semver; bump major for any breaking manifest change.
+- `skills`: path or array of paths to Skill files, each relative to `.claude-plugin/` and
+  starting with `./`. Top-level `skills/SKILL.md` is the recommended layout for a focused
+  Plugin. A Plugin that ships a top-level Skill should also ship a `skills/<plugin-name>/SKILL.md`
+  copy under a subdirectory whose name matches the Plugin's `name`, so the v0.3.x runtime and
+  the current validator accept the package.
+- `mcpServers`: same shape as the Agent Plugins 1.0 `mcpServers` field.
+- `hooks`: inline hook definitions, replacing the v0.3.x `io.minimax.mcode/hooks/hooks.json`
+  document. The 12 PascalCase event names (`SessionStart`, `SessionEnd`, `PreToolUse`,
+  `PostToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact`, `Notification`, `SubagentStart`,
+  `SubagentStop`, `PermissionRequest`, `PermissionDenied`) and the per-event handler shape are
+  identical to the v0.3.x spec; the layout change is the only difference. See the proposal for
+  the full event table, the matcher rules, the `timeout` units, and the hook script conventions.
+
+Three things bite Plugin authors migrating from the v0.3.x layout. The full lessons are in the
+proposal; the short version is:
+
+1. The manifest **must** live at `.claude-plugin/plugin.json`. A top-level `plugin.json` is
+   ignored by mcode 0.4.0+.
+2. The `skills` field must point at a path the snapshot builder can resolve. A path into a
+   nested subdirectory whose name does not match the SKILL.md frontmatter `name` is silently
+   dropped; the Plugin does not load, no diagnostic is emitted. Use `./skills/SKILL.md` for
+   a single-Skill Plugin, or rename the subdirectory to match the frontmatter `name`.
+3. Hooks **must** be inlined on the manifest under the `hooks` key. The
+   `io.minimax.mcode/hooks/hooks.json` document is ignored by mcode 0.4.0+.
+
+A working example with one PowerShell hook script and one top-level Skill is in
+[`examples/hello-mcode-hooks-v04/`](../examples/hello-mcode-hooks-v04/). It ships both
+`skills/SKILL.md` (for the v0.4.0+ runtime) and `skills/hello-mcode-hooks-v04/SKILL.md` (for
+the validator and the v0.3.x runtime) as byte-identical copies, per the recommended
+cross-version layout.
+
 ## Limits and unsupported capabilities
 
 The runtime accepts at most 64 Skill directories and 8 MCP servers per Agent Plugin. Invalid Skills
 or MCP entries are omitted with diagnostics; an invalid root manifest rejects the package.
 
-The following are not currently public MCode Plugin capabilities:
+The following are not currently public MCode Plugin capabilities in either runtime:
 
-- Hooks and lifecycle scripts
 - custom Agents and Commands
 - LSP configuration
 - Apps or UI extensions
 - generic OAuth setup
 - host-specific fields hidden in `extensions`
 
+Hooks and lifecycle scripts are **not** a portable Agent Plugins 1.0 capability, but mcode
+0.4.0+ accepts them via the inline `hooks` field on `.claude-plugin/plugin.json`. Plugins that
+target mcode 0.3.x use the experimental `io.minimax.mcode/hooks/hooks.json` document; that
+document is the right reference for the 0.3.x runtime. See
+[`proposals/hooks-v0.4-spec.md`](../proposals/hooks-v0.4-spec.md) and
+[`proposals/hooks-detailed-spec.md`](../proposals/hooks-detailed-spec.md) for the two specs.
+
 Hosted contributions may contain extra assets, but documentation must not imply that MiniMax Code
 loads unsupported components. TUI Extensions are a separate product extension system, not an Agent
 Plugin capability.

examples/hello-mcode-hooks-v04/.claude-plugin/plugin.json

@@ -0,0 +1,73 @@
+{
+  "name": "hello-mcode-hooks-v04",
+  "version": "0.1.0",
+  "description": "A minimal Plugin that demonstrates one Skill and one inline Hook entry under the mcode 0.4.0+ plugin format. The Hook records each delivered event to a per-instance state file for manual inspection. Targets mcode 0.4.0+ only; for the 0.3.x layout see examples/hello-mcode-hooks/.",
+  "author": {
+    "name": "MCode Plugins contributors"
+  },
+  "license": "Apache-2.0",
+  "keywords": ["mcode", "example", "hooks", "v0.4"],
+  "skills": [
+    "./skills/SKILL.md",
+    "./skills/hello-mcode-hooks-v04/SKILL.md"
+  ],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "powershell",
+            "args": [
+              "-NoProfile",
+              "-ExecutionPolicy",
+              "Bypass",
+              "-File",
+              "${PLUGIN_ROOT}/io.minimax.mcode/hooks/scripts/record-event.ps1"
+            ],
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "powershell",
+            "args": [
+              "-NoProfile",
+              "-ExecutionPolicy",
+              "Bypass",
+              "-File",
+              "${PLUGIN_ROOT}/io.minimax.mcode/hooks/scripts/record-event.ps1"
+            ],
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "powershell",
+            "args": [
+              "-NoProfile",
+              "-ExecutionPolicy",
+              "Bypass",
+              "-File",
+              "${PLUGIN_ROOT}/io.minimax.mcode/hooks/scripts/record-event.ps1"
+            ],
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

examples/hello-mcode-hooks-v04/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

examples/hello-mcode-hooks-v04/README.md

@@ -0,0 +1,95 @@
+# hello-mcode-hooks-v04
+
+A minimal Plugin that demonstrates one Skill and one inline Hook entry under the
+mcode 0.4.0+ plugin format.
+
+## What this example demonstrates
+
+- A `.claude-plugin/plugin.json` manifest with the `hooks` field inlined (no
+  external `io.minimax.mcode/hooks/hooks.json` document).
+- A top-level Skill at `skills/SKILL.md` plus a byte-identical subdirectory
+  copy at `skills/hello-mcode-hooks-v04/SKILL.md`. The top-level copy is what
+  mcode 0.4.0+ reads; the subdirectory copy is what the current validator
+  (`scripts/validate.mjs`) and the v0.3.x runtime read.
+- An observer PowerShell hook script that records `PreToolUse`, `SessionStart`,
+  and `SessionEnd` events to a per-instance state file.
+- Atomic, cross-platform state file writes under the runtime-provided
+  `PLUGIN_DATA` directory, using a staging-file rename.
+- Path resolution that uses runtime-injected environment values
+  (`${PLUGIN_ROOT}`, `${PLUGIN_DATA}`), not host-absolute literals.
+
+This example is the v0.4.0+ counterpart of
+[`examples/hello-mcode-hooks/`](../hello-mcode-hooks/). It targets mcode 0.4.0+
+exclusively. For a Plugin that must run on both mcode 0.3.x and mcode 0.4.0+,
+ship both layouts in parallel (see
+[`proposals/hooks-v0.4-spec.md`](../../proposals/hooks-v0.4-spec.md) for the
+recommended cross-version layout).
+
+## Layout
+
+```text
+hello-mcode-hooks-v04/
+├── README.md
+├── LICENSE
+├── plugin.json                # v0.3.x-compatible shim, satisfies the hosted validator
+│                              # (top-level $schema: agent-plugins.org/.../1.0.0)
+├── .claude-plugin/
+│   └── plugin.json            # v0.4.0+ manifest, inline `hooks` (the authoritative file)
+├── skills/
+│   ├── SKILL.md               # top-level, used by mcode 0.4.0+
+│   └── hello-mcode-hooks-v04/ # subdir copy, used by the validator and
+│       └── SKILL.md           # the v0.3.x runtime
+└── io.minimax.mcode/
+    └── hooks/
+        └── scripts/
+            └── record-event.ps1
+```
+
+The two `plugin.json` files are the v0.3.x / v0.4.0+ dual-shipment pattern. The
+top-level `plugin.json` is the v0.3.x Agent Plugins 1.0 manifest; it is what
+the current hosted validator (`scripts/validate.mjs`) reads. The
+`.claude-plugin/plugin.json` is the v0.4.0+ Claude Code compatible manifest
+with inline `hooks`; it is what mcode 0.4.0+ reads. Both have the same
+`name` field so the runtime and the validator agree on the Plugin's
+identity. Once the validator learns the `.claude-plugin/plugin.json`
+layout, the top-level shim can be dropped.
+
+## Manifest
+
+The `.claude-plugin/plugin.json` manifest declares three inline hook handlers
+(`PreToolUse`, `SessionStart`, `SessionEnd`) plus a `skills` field that points
+at both the top-level Skill and the subdirectory copy. The `name` field is the
+only strictly required field; the rest are recommended for catalog quality.
+The full schema is in
+[`proposals/hooks-v0.4-spec.md`](../../proposals/hooks-v0.4-spec.md).
+
+## Hook entry
+
+The hook entry is one `record-event.ps1` invocation per event. The script
+reads the event payload from stdin (one UTF-8 JSON document, then EOF, per the
+v0.4.0+ spec) and appends a compact record to `${PLUGIN_DATA}/state.json` using
+a staging-file rename. No tool input rewriting, no permission decisions, no
+network access, no telemetry, no host-absolute paths.
+
+## Validation expectations
+
+- `npm run check` runs the validator against this example. The validator
+  accepts the v0.4.0+ layout and reads the subdirectory Skill copy
+  (`skills/hello-mcode-hooks-v04/SKILL.md`).
+- The script resolves all paths from `${PLUGIN_ROOT}` and `${PLUGIN_DATA}`
+  only. There is no host-absolute path, no credential, no telemetry, no
+  network call.
+- The Hook entry is recognized as an inline field on the manifest. There is no
+  external `hooks.json` document to validate.
+
+## Disclosure
+
+This example contains:
+
+- no credentials;
+- no network access;
+- no telemetry;
+- no third-party services.
+
+The same disclosure is repeated in `skills/SKILL.md` per the
+`hello-mcode-hooks` plugin convention.