Skip to content

feat: define MiniMax Hooks 0.1 contribution contract - #19

Closed
hetaoBackend wants to merge 2 commits into
mainfrom
proposal/portable-hooks-extension
Closed

feat: define MiniMax Hooks 0.1 contribution contract#19
hetaoBackend wants to merge 2 commits into
mainfrom
proposal/portable-hooks-extension

Conversation

@hetaoBackend

@hetaoBackend hetaoBackend commented Aug 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Define MiniMax Code Hooks 0.1 as a staged, contributor-facing registry contract instead of a proposal-only document.

  • publish the immutable io.minimax.mcode/hooks/hooks.json schema and normative author/runtime contract;
  • define six observe-only lifecycle events, occurrence/cardinality rules, process semantics, limits, and failure boundaries;
  • validate Hooks in repository tooling, reject ambiguous root hooks.json, and accept Hook-only Plugin contributions;
  • add a dependency-free Hook-only example with bounded, concurrent-safe record storage;
  • update contribution, compatibility, security, architecture, and bilingual project documentation; and
  • test schema/validator agreement with a standard JSON Schema engine plus hosted-package and concurrent-example regressions.

Standards boundary

Agent Plugins 1.0 standardizes Skills and MCP, not Hooks. Hooks 0.1 therefore uses the Agent Plugins client-extension namespace rather than changing the root manifest. Its six-event observe-only shape aligns with the active Portable Hooks Component Type discussion, but it is not presented as portable Agent Plugins core.

This repository does not yet link a certified MiniMax Code runtime implementation and end-to-end conformance fixture. Registry acceptance means the declaration can be contributed and statically validated; it does not claim that a current MiniMax Code release executes Hooks.

Validation

  • npm ci --ignore-scripts --registry=https://registry.npmjs.org/
  • npm run check — 17 hosted Plugins and all examples validated; 119/119 tests passed
  • git diff --check
  • independent standards and requirements reviews: no findings after fixes

@hetaoBackend
hetaoBackend force-pushed the proposal/portable-hooks-extension branch from efe11c1 to d86625d Compare August 25, 2026 14:13
@antianqi antianqi mentioned this pull request Aug 26, 2026
Open
antianqi added a commit to antianqi/MiniMax-Code-Plugins-1 that referenced this pull request Aug 26, 2026
@antianqi
feat(mcode-island): v0.3.0 — io.minimax.mcode Hooks extension
7f15cf1 
Adds a Plugin-format Hooks declaration under `io.minimax.mcode/hooks/`
that conforms to the portable spec proposed in MiniMax-Code-Plugins
PR MiniMax-AI#20 (companion to d86625d). mcode 0.2.4 already ships the runtime
dispatch path for five of the twelve events; the remaining seven are
forward-looking and declared so the validator can warn on them.

The agent does not need to call `notify-island.ps1` manually when
the runtime wires the Hooks path. The detector-based fallback in
`mcode-status-detect.ps1` continues to run for everything else, so
this change is strictly additive: no existing capability is removed
or renamed.

## What changed

- `plugin.json`: bumped 0.2.1 → 0.3.0, declared
  `extensions.io.minimax.mcode.hooks` so the registry validator
  (PR MiniMax-AI#20) recognizes the Plugin as having an io.minimax.mcode
  client extension.
- `io.minimax.mcode/hooks/hooks.json`: 12-event declaration using
  only the portable field vocabulary (`command`, `args`, `env`,
  `cwd`, `matcher`, `pattern`, `regex`, `glob`, `timeout`,
  `timeoutMs`, `once`). No reserved fields. `PLUGIN_ROOT` is used
  for the script path; no host-absolute literals.
- `io.minimax.mcode/hooks/scripts/_lib.ps1`: shared helper exporting
  `Read-HookStdin`, `Push-Island`, `Test-IsSelfPush`,
  `Format-ToolSummary`. Loaded via dot-source from every event
  script. The self-push filter avoids recursive state churn when
  the agent calls `notify-island.ps1` directly through Bash.
- `io.minimax.mcode/hooks/scripts/<event>.ps1` x 12: one script
  per event. State mapping:

  | event             | pill state  | notes |
  | ----------------- | ----------- | ----- |
  | SessionStart      | idle        | |
  | SessionEnd        | idle        | |
  | UserPromptSubmit  | thinking    | |
  | PreToolUse        | working     | skips self-push |
  | PostToolUse       | done/error  | heuristic on tool_result |
  | Stop              | done        | |
  | PreCompact        | thinking    | |
  | Notification      | idle        | |
  | SubagentStart     | working     | CODEX only |
  | SubagentStop      | done        | CODEX only |
  | PermissionRequest | waiting     | returns `ask` (observer opt-in, see PR MiniMax-AI#20 §Decision semantics) |
  | PermissionDenied  | error       | |

- `permission-request.ps1`: returns `{"decision":"ask",...}`, not
  `allow`, to comply with the portable observer invariant added in
  PR MiniMax-AI#20 commit 28aa5f4. The 0.2.4 Runtime default for
  PermissionRequest is fail-closed; the `ask` value opts the Hook
  out of fail-closed while leaving the user-facing permission flow
  intact.
- `scripts/smoke.mjs`: pre-submit self-check. Zero dependencies
  (Node 18+ stdlib only), cross-platform. Validates `plugin.json`
  shape, the `extensions.io.minimax.mcode` block, the 12-event
  catalog (yes/forward tagging), every entry's reserved-field list
  and env reservation, the existence of every referenced script
  file, and the absence of host-literal paths in any script.
- `SKILL.md` / `README.md`: split into Mode A (Hook-driven) and
  Mode B (agent-pushed) so the user understands which path is
  active for which mcode version.
- `.gitattributes`: force LF for all source files. PowerShell 5.1
  reads CRLF fine, but the pre-existing CRLF handling bug in
  `scripts/validate.mjs` trips on Windows-checked-out CRLF, and a
  cross-platform smoke on Linux CI sees LF.

## Test evidence

End-to-end smoke (15/15) at @minimax-ai/code@0.2.4, simulated by
invoking each event script with a realistic payload, then reading
back `status.json` and verifying the multi-writer semantics with
the Runtime's own status detector:

    step=SessionStart           got=idle       src=agent      OK
    step=UserPromptSubmit       got=thinking   src=agent      OK
    step=PreToolUse-Bash        got=working    src=agent      OK
    step=PostToolUse-Bash       got=done       src=agent      OK
    step=PreToolUse-Read        got=working    src=agent      OK
    step=PostToolUse-Read       got=done       src=agent      OK
    step=PreCompact             got=thinking   src=agent      OK
    step=Stop                   got=done       src=agent      OK
    step=SubagentStart          got=working    src=agent      OK
    step=SubagentStop           got=done       src=agent      OK
    step=PermissionRequest      got=waiting    src=agent      OK
    step=PermissionDenied       got=error      src=agent      OK
    step=PreToolUse-self-push   got=error      src=agent      OK   (no change, filter applied)
    step=Notification           got=idle       src=agent      OK
    step=SessionEnd             got=idle       src=agent      OK
    ----
    summary: 15 pass, 0 fail

`scripts/smoke.mjs` on the in-repo tree:

    mcode-island v0.3.0 self-check
    [OK  ] plugin.json parses
    [OK  ] plugin.json: $schema is agent-plugins 1.0.0
    [OK  ] plugin.json: version is "0.3.0"
    [OK  ] plugin.json: extensions.io.minimax.mcode is present
    [OK  ] plugin.json: extensions.io.minimax.mcode.hooks resolves to io.minimax.mcode/hooks/hooks.json
    [OK  ] io.minimax.mcode/hooks/hooks.json parses
    [WARN] event "Stop"             is "forward" (not confirmed in @minimax-ai/code@0.2.4)
    [WARN] event "PreCompact"       is "forward" (not confirmed in @minimax-ai/code@0.2.4)
    [WARN] event "Notification"     is "forward" (not confirmed in @minimax-ai/code@0.2.4)
    [WARN] event "SubagentStart"    is "forward" (not confirmed in @minimax-ai/code@0.2.4)
    [WARN] event "SubagentStop"     is "forward" (not confirmed in @minimax-ai/code@0.2.4)
    [WARN] event "PermissionRequest" is "forward" (not confirmed in @minimax-ai/code@0.2.4)
    [WARN] event "PermissionDenied"  is "forward" (not confirmed in @minimax-ai/code@0.2.4)
    [OK  ] hooks.json[<event>]: script <name>.ps1 exists   x 12
    [OK  ] _lib.ps1: shared helper present
    [OK  ] <script>.ps1: no hardcoded host paths   x 13
    ----
    summary: 39 pass, 7 warn, 0 fail

The 7 WARN entries are the spec allowlist tagging (PR MiniMax-AI#20
"Empirical event catalog" table); they are expected and warn-only.

## Design compliance

- Agent Plugins 1.0 conformance preserved. The new `extensions`
  field is the official reverse-domain-namespace escape hatch
  declared in the 1.0 spec; no root-manifest field is overloaded.
- Cross-platform. Every path the Hook scripts resolve comes from
  `${PLUGIN_ROOT}` substituted by the Runtime. No host-absolute
  literals, no drive letters, no `/Users/` or `/home/` paths.
  `.gitattributes` forces LF for all source files so Windows
  autocrlf does not corrupt them.
- Self-disclosure. `SKILL.md`, `plugin.json` description, and
  `README.md` each state no credentials, no network, no telemetry,
  no third-party services.
- Atomic write. The `notify-island.ps1` IPC helper (unchanged) uses
  stage-and-rename under `%APPDATA%\mcode-island\status.json`; the
  previous state file is preserved on failure.
- Companion (not replacement) of the proposal. The Hook extension
  follows PR MiniMax-AI#20's portable spec verbatim. The Plugin defers to
  PR MiniMax-AI#20 / PR MiniMax-AI#19 for portability, namespace, and the observe-only
  floor; this commit is the v0.3.0 instantiation.

## Out of scope (intentionally)

- Does not modify `docs/plugin-compatibility.md` to claim Hook
  support. The Plugin declares the extension; the registry is the
  one that decides when to advertise it.
- Does not modify `docs/security-model.md`.
- Does not propose a different namespace or event catalog.
- Does not add runtime code to mcode 0.2.4; the Plugin runs against
  the existing Runtime.
- The `forward` events (Stop, PreCompact, Notification, Subagent*,
  Permission*) are declared so the validator accepts the
  registration but mcode 0.2.4 may or may not dispatch them. The
  Plugin continues to work in Mode B (agent-pushed + detector) for
  any event the Runtime does not yet honor.

## Refs

- MiniMax-Code-Plugins PR MiniMax-AI#20 (companion proposal,
  proposals/hooks-detailed-spec.md) — portable spec, validator,
  example fixture.
- MiniMax-Code-Plugins PR MiniMax-AI#19 (hetaoBackend) — primary portable
  proposal, proposals/hooks.md.
- @minimax-ai/code@0.2.4 (npm, 2026-08-24) — Runtime release notes.
- Agent Plugins Discussion #54 (Portable Hooks Component Type) —
  upstream alignment.
- MiniMax-Code-Plugins PR MiniMax-AI#17 (previous mcode-island v0.2.1) —
  baseline that this commit supersedes.
@hetaoBackend hetaoBackend changed the title docs: propose portable Hooks preview feat: define MiniMax Hooks 0.1 contribution contract Aug 26, 2026
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

@hetaoBackend