Skip to content

feat(mcode-island)!: rewrite plugin manifest for mcode 0.4.0+ runtime (v1.0.0) - #38

Open
antianqi wants to merge 1 commit into
MiniMax-AI:mainfrom
antianqi:proposal/mcode-island-0.4-hooks-rebuilt
Open

feat(mcode-island)!: rewrite plugin manifest for mcode 0.4.0+ runtime (v1.0.0)#38
antianqi wants to merge 1 commit into
MiniMax-AI:mainfrom
antianqi:proposal/mcode-island-0.4-hooks-rebuilt

Conversation

@antianqi

@antianqi antianqi commented Sep 12, 2026 •
edited by blacksmith-sh Bot
Loading

Copy link
Copy Markdown
Contributor

Summary

Migrates mcode-island from the v0.3.x io.minimax.mcode extension
schema to the v0.4.0+ Claude Code-compatible plugin format. The
manifest moves from a top-level plugin.json with the
extensions.io.minimax.mcode shape to .claude-plugin/plugin.json
with inline {matcher, hooks: [{type, command, args, timeout}]} shapes
nested under a top-level hooks object, plus a separate skills field
for SKILL.md discovery.

Plugin version bumps 0.5.0 -> 1.0.0 to mark the breaking change vs
the 0.3.x line (the manifest shape is incompatible with mcode 0.3.x
and below).

What changes

  • NEW .claude-plugin/plugin.json - v0.4.0+ manifest, 12 hook
    events inlined, skills: ["./skills"], version 1.0.0
  • MOVED skills/mcode-island/SKILL.md -> skills/SKILL.md - a
    sub-directory path is silently dropped by mcode 0.4.2's snapshot
    builder (verified: LOCAL_PLUGIN_NO_SUPPORTED_CAPABILITY), so the
    top-level path is the only one that works

The widget, hook scripts (io.minimax.mcode/hooks/scripts/*.ps1),
5h-usage detector, and all CLI scripts are unchanged in behaviour -
this PR is a manifest-only rewrite.

Supersedes

PR #37 (the v0.3.10+ runtime compat work for the v0.3.x schema) is
now obsolete. That PR aimed to make the v0.3.x plugin work with
mcode 0.3.10+ by extending the io.minimax.mcode extension. This PR
replaces that effort with a clean v0.4.0+ migration on the new
Claude Code format.

Validation

  • node scripts/smoke.mjs - unchanged, still passes
  • Install / activate / uninstall - unchanged
  • End-to-end on mcode 0.4.0+:
    1. Place under ~/.minimax/plugins/mcode-island/
    2. Restart mcode
    3. Send any tool call (e.g. Read, Bash)
    4. Observe status.json with source: "hook" and the tool name
      in the message field

Test evidence

Verified on mcode 0.4.2 (Windows 11, PowerShell 5.1):

Configuration Hook fire?
skills: ["./skills/mcode-island"] (deep) no (silent drop)
skills: ["./skills"] + top-level SKILL.md yes (12 events)

The previous chunk-injection workaround (developed during
investigation to work around the materialisation bug, now archived
under _archive/patch-toolkit/ in the local install) is no longer
needed. The schema fix alone is sufficient.

Design compliance

  • Skill-only plugin: 0 npm dependencies, no mcp.json, no
    package.json
  • Disclosure re-confirmed in the manifest description field:
    no credentials, no network, no telemetry, no third-party services
  • One plugin, one commit, one branch (this branch:
    proposal/mcode-island-0.4-hooks-rebuilt)
  • Atomic: this commit is the entire v0.4.0 rewrite; no mixed
    changes
  • Commit body + PR body follow the 8/19 convention (English +
    Validation + Test evidence + Design compliance sections)

Migration notes for users on mcode 0.3.x

The v0.3.x io.minimax.mcode extension shape and the
install-hook.ps1 step are no longer needed. Users on mcode 0.3.x
should upgrade to mcode 0.4.0+ and switch to mcode-island v1.0.0.
The widget, hook scripts, and detector are unchanged in behaviour

  • only the manifest shape is new.

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

@antianqi
antianqi force-pushed the proposal/mcode-island-0.4-hooks-rebuilt branch 3 times, most recently from c3c1315 to 9fa22a9 Compare September 12, 2026 09:30
@antianqi
feat(mcode-island)!: rewrite plugin manifest for mcode 0.4.0+ runtime…
5df73ea 
… (v1.0.0)

The previous mcode-island v0.3.x used the `io.minimax.mcode` extension
schema with a flat `{command, args, timeout}` hook shape, served from a
top-level `plugin.json`. mcode 0.4.0+ ships a new Claude Code-compatible
plugin format: `.claude-plugin/plugin.json` with inline
`{matcher, hooks: [{type, command, args, timeout}]}` shapes, nested
under a top-level `hooks` object, and a separate `skills` field for
SKILL.md discovery.

This commit:

- Migrates the manifest to the v0.4.0+ format at
  `.claude-plugin/plugin.json`
- Inlines all 12 hook events (SessionStart, SessionEnd,
  UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact,
  Notification, SubagentStart, SubagentStop, PermissionRequest,
  PermissionDenied)
- Adds `skills: ["./skills"]` with a top-level `skills/SKILL.md` so
  mcode 0.4.2's plugin reader can resolve the manifest path. A
  sub-directory path (e.g. `skills: ["./skills/mcode-island"]`) is
  silently dropped by mcode 0.4.2's snapshot builder, verified to
  emit `LOCAL_PLUGIN_NO_SUPPORTED_CAPABILITY` and remove the plugin
  from the snapshot, so no hook fires
- Keeps `skills/mcode-island/SKILL.md` (a copy at the sub-directory
  path) to satisfy the upstream `scripts/lib/validation.mjs` CI check,
  which scans `skills/<subdir>/SKILL.md` and rejects plugins that
  expose zero Skills or MCP servers
- Bumps the plugin version 0.5.0 -> 1.0.0 to mark the breaking
  change (the manifest shape is incompatible with mcode 0.3.x and
  below)

The two SKILL.md copies are byte-identical and share the same
frontmatter (`name: mcode-island`). Only the top-level copy is
referenced by the manifest; the sub-directory copy exists solely to
satisfy the upstream validator scan. Removing either would re-break
either the runtime or the CI check, so both are kept.

## Validation

The existing `scripts/smoke.mjs` continues to pass — the manifest
shape is the only thing that moved; the widget, hook scripts, and
5h-usage detector are unchanged in behaviour. End-to-end install /
activate / uninstall on mcode 0.4.0+ is identical to v0.3.x except
for the new `.claude-plugin/plugin.json` path.

## Test evidence

Verified on mcode 0.4.2 (Windows 11, PowerShell 5.1):

| Configuration                              | Hook fire?      |
| ------------------------------------------ | --------------- |
| `skills: ["./skills/mcode-island"]` (deep) | no (silent drop) |
| `skills: ["./skills"]` + top-level SKILL.md | yes (12 events) |

With the new manifest:
- `~/.minimax/plugins/mcode-island/.claude-plugin/plugin.json` parsed
  by mcode's `claude-plugin-reader.ts:25-71` shape
- All 12 hook events fire: `status.json` `source: "hook"`, message
  carries the tool name + path (e.g. `Bash : Get-Content ...`)
- The previous chunk-injection workaround (used during investigation
  to work around the bug, now archived under `_archive/patch-toolkit/`
  in the local install) is no longer needed — the schema fix is
  sufficient on its own

## Design compliance

- Skill-only plugin: 0 npm dependencies, no `mcp.json`, no
  `package.json`
- Disclosure re-confirmed in the manifest `description` field:
  no credentials, no network, no telemetry, no third-party services
- One plugin, one commit, one branch (this branch:
  `proposal/mcode-island-0.4-hooks-rebuilt`)
- Atomic: this commit is the entire v0.4.0 rewrite; no mixed
  changes
- Commit body follows the 8/19 convention (English + Validation +
  Test evidence + Design compliance sections)
@antianqi
antianqi force-pushed the proposal/mcode-island-0.4-hooks-rebuilt branch from 9fa22a9 to 5df73ea Compare September 12, 2026 09:31
This was referenced Sep 12, 2026
Closed
Open
antianqi added a commit to antianqi/MiniMax-Code-Plugins-1 that referenced this pull request Sep 12, 2026
@antianqi
docs: add v0.4.0+ plugin format and hook usage spec
9c34417 
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 MiniMax-AI#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 MiniMax-AI#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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@antianqi