Skip to content

Commit 817eb16

Browse files
antianqiantianqi
committed
docs: add v0.4.0+ plugin format and hook usage spec
Document the mcode 0.4.0+ plugin layout that @minimax-ai/code@0.4.0+ adopts as the Claude Code compatible preferred form. Plugin authors migrating from the v0.3.x portable Agent Plugins 1.0 layout need a single reference that captures the manifest location, the inline `hooks` shape, the new `skills` field semantics, and the three failure modes that bit mcode-island during the upgrade (PR #38). Scope - New proposal `proposals/hooks-v0.4-spec.md` (324 lines) — the authoritative spec for the v0.4.0+ plugin format. Covers 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 the v0.3.x `proposals/hooks-detailed-spec.md` which it does not supersede for the 0.3.x runtime. - Update `docs/plugin-compatibility.md` to add a v0.4.0+ plugin format section, mark `io.minimax.mcode/hooks/hooks.json` as v0.3.x-only, and clarify that Hooks are accepted by mcode 0.4.0+ via the inline manifest field. The portable Agent Plugins 1.0 section is unchanged. - Update `CONTRIBUTING.md` step 2 to add a "Choose a runtime layout" subsection pointing new contributors at the two layouts and the cross-runtime dual-shipment recommendation. - New example `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. Validation - `plugin.json` parses as valid JSON. - `record-event.ps1` parses clean under the PowerShell AST parser (`[System.Management.Automation.Language.Parser]::ParseFile`). - 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`). - All paths use ${PLUGIN_ROOT} / ${PLUGIN_DATA}; no host-absolute literals, no C:\ or /Users/ or /home/ paths. - No network calls (no Invoke-WebRequest, Invoke-RestMethod, curl, wget, http://...). - No scaffold markers (no TODO, FIXME, XXX, TBD, REPLACE_ME). - Disclosure: no credentials, no network, no telemetry, no third-party services; repeated in README.md and both SKILL.md files per the hello-mcode-hooks convention. - Negative-injection self-audit: injecting a hard-coded `C:\Users\Administrator\...` path into `record-event.ps1` was caught by the path sweep; restoring the staging-file expression brought the file back to clean. Test evidence - 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 #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). - This PR does not change the validator (`scripts/validate.mjs`). The recommended cross-runtime dual-Skill layout (top-level + byte-identical subdir) is the validator-compatible workaround until the validator learns the top-level layout. Design compliance - No hard-coded host-absolute paths. - No credentials, no network, no telemetry, no third-party services in the example. - Atomic state writes via staging-file rename; UTF-8 without BOM. - 1 commit, 1 branch, 1 PR. No unrelated validator hardening or plugin changes. - File additions only (no removals, no renames), preserving the v0.3.x example and the v0.3.x spec unchanged.
1 parent dda9e0b commit 817eb16

9 files changed

Lines changed: 780 additions & 3 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,25 @@ Replace every scaffold `TODO`. Your Plugin must:
2828
Keep source and docs inside your Plugin directory. Do not edit another contributor's Plugin in the
2929
same pull request.
3030

31+
### Choose a runtime layout
32+
33+
`docs/plugin-compatibility.md` describes two layouts. Pick one before you write `plugin.json`:
34+
35+
- The **portable Agent Plugins 1.0** layout (top-level `plugin.json`, optional
36+
`io.minimax.mcode/hooks/hooks.json` for Hooks) is the cross-runtime baseline. Use it when
37+
your Plugin must run on both mcode 0.3.x and mcode 0.4.0+. The validator
38+
(`scripts/validate.mjs`) checks this layout by default.
39+
- The **v0.4.0+ plugin format** (`.claude-plugin/plugin.json` with inline `hooks`) is the
40+
preferred form for Plugins that target mcode 0.4.0+ only. The full schema and the inline
41+
`hooks` shape are in [`proposals/hooks-v0.4-spec.md`](proposals/hooks-v0.4-spec.md); a
42+
working example is in [`examples/hello-mcode-hooks-v04/`](examples/hello-mcode-hooks-v04/).
43+
44+
A Plugin that needs both runtimes ships both layouts in parallel. The v0.3.x layout does
45+
not need to duplicate the v0.4.0+ Skill; the recommended cross-runtime shape ships
46+
`skills/SKILL.md` (used by mcode 0.4.0+) and `skills/<plugin-name>/SKILL.md` (a byte-identical
47+
copy under a subdirectory whose name matches the Plugin's `name`, used by the v0.3.x
48+
runtime and the current validator).
49+
3150
## 3. Check it
3251

3352
```bash

‎docs/plugin-compatibility.md‎

Lines changed: 84 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,22 @@
11
# MiniMax Code plugin compatibility
22

3-
## Portable package
3+
This document describes what MiniMax Code reads from an Agent Plugin. There are two runtime
4+
layouts in active use:
5+
6+
- The **portable Agent Plugins 1.0** layout below is the cross-runtime baseline. It is what the
7+
validator checks and what mcode 0.3.x reads. It is also what mcode 0.4.0+ continues to accept
8+
when it is found on disk.
9+
- The **v0.4.0+ plugin format** section below describes the Claude Code compatible layout that
10+
mcode 0.4.0+ adopts as the preferred form: the manifest moves to `.claude-plugin/plugin.json`
11+
and Hooks are inlined on the manifest. A Plugin that targets mcode 0.4.0+ exclusively should
12+
use this layout; a Plugin that targets both 0.3.x and 0.4.0+ should ship both layouts in
13+
parallel.
14+
15+
The full v0.4.0+ Hooks specification is in
16+
[`proposals/hooks-v0.4-spec.md`](../proposals/hooks-v0.4-spec.md) and a working example is in
17+
[`examples/hello-mcode-hooks-v04/`](../examples/hello-mcode-hooks-v04/).
18+
19+
## Portable package (Agent Plugins 1.0, mcode 0.3.x)
420

521
MiniMax Code reads the portable subset of Agent Plugins 1.0:
622

@@ -51,20 +67,85 @@ MiniMax Code reserves `PLUGIN_ROOT` and `PLUGIN_DATA`. A plugin must not set tho
5167
Do not embed tokens in environment values or headers. Generic OAuth configuration is not part of
5268
this portable subset.
5369

70+
## v0.4.0+ plugin format (mcode 0.4.0+ runtime)
71+
72+
mcode 0.4.0+ (`@minimax-ai/code@0.4.0`, released 2026-09-11) adopts the Claude Code compatible
73+
plugin shape as the preferred form. A Plugin that targets mcode 0.4.0+ exclusively uses this
74+
layout; a Plugin that targets both 0.3.x and 0.4.0+ ships both layouts in parallel.
75+
76+
```text
77+
plugin-root/
78+
├── README.md # required by this community repository
79+
├── LICENSE # required by this community repository
80+
├── .claude-plugin/
81+
│ └── plugin.json # the v0.4.0+ manifest, with inline `hooks`
82+
├── io.minimax.mcode/ # hook scripts, same layout as the portable package
83+
│ └── hooks/
84+
│ └── scripts/
85+
│ └── *.ps1 | *.mjs | *.sh # one script per event handler
86+
└── skills/
87+
├── SKILL.md # top-level single Skill (preferred for a focused Plugin)
88+
└── <plugin-name>/ # subdir copy, for the v0.3.x runtime and the validator
89+
└── SKILL.md
90+
```
91+
92+
The v0.4.0+ manifest is a single JSON object whose only strictly required field is `name`. The
93+
full schema and the inline `hooks` shape are in
94+
[`proposals/hooks-v0.4-spec.md`](../proposals/hooks-v0.4-spec.md); the short summary is:
95+
96+
- `name` (required): Plugin name; lowercase letters, digits, single hyphens.
97+
- `version` (recommended): Semver; bump major for any breaking manifest change.
98+
- `skills`: path or array of paths to Skill files, each relative to `.claude-plugin/` and
99+
starting with `./`. Top-level `skills/SKILL.md` is the recommended layout for a focused
100+
Plugin. A Plugin that ships a top-level Skill should also ship a `skills/<plugin-name>/SKILL.md`
101+
copy under a subdirectory whose name matches the Plugin's `name`, so the v0.3.x runtime and
102+
the current validator accept the package.
103+
- `mcpServers`: same shape as the Agent Plugins 1.0 `mcpServers` field.
104+
- `hooks`: inline hook definitions, replacing the v0.3.x `io.minimax.mcode/hooks/hooks.json`
105+
document. The 12 PascalCase event names (`SessionStart`, `SessionEnd`, `PreToolUse`,
106+
`PostToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact`, `Notification`, `SubagentStart`,
107+
`SubagentStop`, `PermissionRequest`, `PermissionDenied`) and the per-event handler shape are
108+
identical to the v0.3.x spec; the layout change is the only difference. See the proposal for
109+
the full event table, the matcher rules, the `timeout` units, and the hook script conventions.
110+
111+
Three things bite Plugin authors migrating from the v0.3.x layout. The full lessons are in the
112+
proposal; the short version is:
113+
114+
1. The manifest **must** live at `.claude-plugin/plugin.json`. A top-level `plugin.json` is
115+
ignored by mcode 0.4.0+.
116+
2. The `skills` field must point at a path the snapshot builder can resolve. A path into a
117+
nested subdirectory whose name does not match the SKILL.md frontmatter `name` is silently
118+
dropped; the Plugin does not load, no diagnostic is emitted. Use `./skills/SKILL.md` for
119+
a single-Skill Plugin, or rename the subdirectory to match the frontmatter `name`.
120+
3. Hooks **must** be inlined on the manifest under the `hooks` key. The
121+
`io.minimax.mcode/hooks/hooks.json` document is ignored by mcode 0.4.0+.
122+
123+
A working example with one PowerShell hook script and one top-level Skill is in
124+
[`examples/hello-mcode-hooks-v04/`](../examples/hello-mcode-hooks-v04/). It ships both
125+
`skills/SKILL.md` (for the v0.4.0+ runtime) and `skills/hello-mcode-hooks-v04/SKILL.md` (for
126+
the validator and the v0.3.x runtime) as byte-identical copies, per the recommended
127+
cross-version layout.
128+
54129
## Limits and unsupported capabilities
55130

56131
The runtime accepts at most 64 Skill directories and 8 MCP servers per Agent Plugin. Invalid Skills
57132
or MCP entries are omitted with diagnostics; an invalid root manifest rejects the package.
58133

59-
The following are not currently public MCode Plugin capabilities:
134+
The following are not currently public MCode Plugin capabilities in either runtime:
60135

61-
- Hooks and lifecycle scripts
62136
- custom Agents and Commands
63137
- LSP configuration
64138
- Apps or UI extensions
65139
- generic OAuth setup
66140
- host-specific fields hidden in `extensions`
67141

142+
Hooks and lifecycle scripts are **not** a portable Agent Plugins 1.0 capability, but mcode
143+
0.4.0+ accepts them via the inline `hooks` field on `.claude-plugin/plugin.json`. Plugins that
144+
target mcode 0.3.x use the experimental `io.minimax.mcode/hooks/hooks.json` document; that
145+
document is the right reference for the 0.3.x runtime. See
146+
[`proposals/hooks-v0.4-spec.md`](../proposals/hooks-v0.4-spec.md) and
147+
[`proposals/hooks-detailed-spec.md`](../proposals/hooks-detailed-spec.md) for the two specs.
148+
68149
Hosted contributions may contain extra assets, but documentation must not imply that MiniMax Code
69150
loads unsupported components. TUI Extensions are a separate product extension system, not an Agent
70151
Plugin capability.

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

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
{
2+
"name": "hello-mcode-hooks-v04",
3+
"version": "0.1.0",
4+
"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/.",
5+
"author": {
6+
"name": "MCode Plugins contributors"
7+
},
8+
"license": "Apache-2.0",
9+
"keywords": ["mcode", "example", "hooks", "v0.4"],
10+
"skills": [
11+
"./skills/SKILL.md",
12+
"./skills/hello-mcode-hooks-v04/SKILL.md"
13+
],
14+
"hooks": {
15+
"PreToolUse": [
16+
{
17+
"matcher": "*",
18+
"hooks": [
19+
{
20+
"type": "command",
21+
"command": "powershell",
22+
"args": [
23+
"-NoProfile",
24+
"-ExecutionPolicy",
25+
"Bypass",
26+
"-File",
27+
"${PLUGIN_ROOT}/io.minimax.mcode/hooks/scripts/record-event.ps1"
28+
],
29+
"timeout": 5
30+
}
31+
]
32+
}
33+
],
34+
"SessionStart": [
35+
{
36+
"matcher": "*",
37+
"hooks": [
38+
{
39+
"type": "command",
40+
"command": "powershell",
41+
"args": [
42+
"-NoProfile",
43+
"-ExecutionPolicy",
44+
"Bypass",
45+
"-File",
46+
"${PLUGIN_ROOT}/io.minimax.mcode/hooks/scripts/record-event.ps1"
47+
],
48+
"timeout": 5
49+
}
50+
]
51+
}
52+
],
53+
"SessionEnd": [
54+
{
55+
"matcher": "*",
56+
"hooks": [
57+
{
58+
"type": "command",
59+
"command": "powershell",
60+
"args": [
61+
"-NoProfile",
62+
"-ExecutionPolicy",
63+
"Bypass",
64+
"-File",
65+
"${PLUGIN_ROOT}/io.minimax.mcode/hooks/scripts/record-event.ps1"
66+
],
67+
"timeout": 5
68+
}
69+
]
70+
}
71+
]
72+
}
73+
}

‎examples/hello-mcode-hooks-v04/LICENSE‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Apache License
2+
Version 2.0, January 2004
3+
http://www.apache.org/licenses/
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.

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

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# hello-mcode-hooks-v04
2+
3+
A minimal Plugin that demonstrates one Skill and one inline Hook entry under the
4+
mcode 0.4.0+ plugin format.
5+
6+
## What this example demonstrates
7+
8+
- A `.claude-plugin/plugin.json` manifest with the `hooks` field inlined (no
9+
external `io.minimax.mcode/hooks/hooks.json` document).
10+
- A top-level Skill at `skills/SKILL.md` plus a byte-identical subdirectory
11+
copy at `skills/hello-mcode-hooks-v04/SKILL.md`. The top-level copy is what
12+
mcode 0.4.0+ reads; the subdirectory copy is what the current validator
13+
(`scripts/validate.mjs`) and the v0.3.x runtime read.
14+
- An observer PowerShell hook script that records `PreToolUse`, `SessionStart`,
15+
and `SessionEnd` events to a per-instance state file.
16+
- Atomic, cross-platform state file writes under the runtime-provided
17+
`PLUGIN_DATA` directory, using a staging-file rename.
18+
- Path resolution that uses runtime-injected environment values
19+
(`${PLUGIN_ROOT}`, `${PLUGIN_DATA}`), not host-absolute literals.
20+
21+
This example is the v0.4.0+ counterpart of
22+
[`examples/hello-mcode-hooks/`](../hello-mcode-hooks/). It targets mcode 0.4.0+
23+
exclusively. For a Plugin that must run on both mcode 0.3.x and mcode 0.4.0+,
24+
ship both layouts in parallel (see
25+
[`proposals/hooks-v0.4-spec.md`](../../proposals/hooks-v0.4-spec.md) for the
26+
recommended cross-version layout).
27+
28+
## Layout
29+
30+
```text
31+
hello-mcode-hooks-v04/
32+
├── README.md
33+
├── LICENSE
34+
├── .claude-plugin/
35+
│ └── plugin.json # v0.4.0+ manifest, inline `hooks`
36+
├── skills/
37+
│ ├── SKILL.md # top-level, used by mcode 0.4.0+
38+
│ └── hello-mcode-hooks-v04/ # subdir copy, used by the validator and
39+
│ └── SKILL.md # the v0.3.x runtime
40+
└── io.minimax.mcode/
41+
└── hooks/
42+
└── scripts/
43+
└── record-event.ps1
44+
```
45+
46+
## Manifest
47+
48+
The `.claude-plugin/plugin.json` manifest declares three inline hook handlers
49+
(`PreToolUse`, `SessionStart`, `SessionEnd`) plus a `skills` field that points
50+
at both the top-level Skill and the subdirectory copy. The `name` field is the
51+
only strictly required field; the rest are recommended for catalog quality.
52+
The full schema is in
53+
[`proposals/hooks-v0.4-spec.md`](../../proposals/hooks-v0.4-spec.md).
54+
55+
## Hook entry
56+
57+
The hook entry is one `record-event.ps1` invocation per event. The script
58+
reads the event payload from stdin (one UTF-8 JSON document, then EOF, per the
59+
v0.4.0+ spec) and appends a compact record to `${PLUGIN_DATA}/state.json` using
60+
a staging-file rename. No tool input rewriting, no permission decisions, no
61+
network access, no telemetry, no host-absolute paths.
62+
63+
## Validation expectations
64+
65+
- `npm run check` runs the validator against this example. The validator
66+
accepts the v0.4.0+ layout and reads the subdirectory Skill copy
67+
(`skills/hello-mcode-hooks-v04/SKILL.md`).
68+
- The script resolves all paths from `${PLUGIN_ROOT}` and `${PLUGIN_DATA}`
69+
only. There is no host-absolute path, no credential, no telemetry, no
70+
network call.
71+
- The Hook entry is recognized as an inline field on the manifest. There is no
72+
external `hooks.json` document to validate.
73+
74+
## Disclosure
75+
76+
This example contains:
77+
78+
- no credentials;
79+
- no network access;
80+
- no telemetry;
81+
- no third-party services.
82+
83+
The same disclosure is repeated in `skills/SKILL.md` per the
84+
`hello-mcode-hooks` plugin convention.

0 commit comments

Comments
 (0)