feat: define MiniMax Hooks 0.1 contribution contract

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,16 +4,18 @@
 
 ## User value
 
-<!-- What can a MiniMax Code user do after this change? Include an example prompt. -->
+<!-- What can a MiniMax Code user do after this change? Include an example prompt or lifecycle reproduction. -->
 
 ## Plugin submission checklist
 
 - [ ] Plugin lives at `plugins/<github-owner>/<plugin-name>`.
 - [ ] `plugin.json` name matches the Plugin directory.
-- [ ] `README.md` includes a real example prompt and expected result.
+- [ ] Plugin exposes at least one valid Skill, MCP server, or MiniMax Code Hook.
+- [ ] `README.md` includes a real example prompt or lifecycle reproduction and expected result.
 - [ ] `LICENSE` and `plugin.json` declare an open-source license.
 - [ ] Required executables, accounts, paid services, and supported platforms are disclosed.
 - [ ] Network destinations and data handled by the plugin are disclosed.
+- [ ] Hook events, commands, implicit side effects, and stored data locations are disclosed.
 - [ ] No credentials, private endpoints, hidden telemetry, installers, symlinks, or native binaries are included.
 - [ ] Every scaffold `TODO` has been replaced.
 - [ ] `npm run check` passes.

CONTRIBUTING.md

@@ -14,15 +14,21 @@ npm run create -- <github-owner>/<plugin-name>
 The command creates `plugins/<github-owner>/<plugin-name>` with a portable `plugin.json`, README,
 Apache-2.0 license, and starter Skill.
 
+For a Hook-only Plugin, start from [`examples/hello-mcode-hooks`](examples/hello-mcode-hooks/) and
+keep the same hosted README, LICENSE, and manifest requirements.
+
 ## 2. Make it real
 
 Replace every scaffold `TODO`. Your Plugin must:
 
-- expose at least one Skill or MCP server;
+- expose at least one Skill, MCP server, or MiniMax Code Hook;
 - use the supported package shape in [`docs/plugin-compatibility.md`](docs/plugin-compatibility.md);
+- follow the versioned [`Hooks 0.1 contract`](docs/hooks.md) for every Hook;
 - include `README.md`, `LICENSE`, and a matching open-source license in `plugin.json`;
-- explain the user problem, an example prompt, and the expected result;
+- explain the user problem, a copyable prompt or lifecycle reproduction, and the expected result;
 - disclose required executables, accounts, paid services, platforms, network destinations, and data;
+- for Hooks, disclose every event, command, implicit side effect, received data category, and stored
+  data location;
 - contain no credentials, private endpoints, hidden telemetry, installers, native binaries, or symlinks.
 
 Keep source and docs inside your Plugin directory. Do not edit another contributor's Plugin in the
@@ -34,23 +40,26 @@ same pull request.
 npm run check
 ```
 
-The validator checks the hosted directory, Manifest, Skills, MCP transports, required docs,
-placeholders, and path safety. CI runs the same command.
+The validator checks the hosted directory, Manifest, Skills, MCP transports, Hooks, required docs,
+placeholders, and path safety. CI parses Hook configuration and source as data and never executes a
+contributed Hook command.
 
 ## 4. Open the pull request
 
 Include:
 
 - the problem your Plugin solves;
-- a copyable example prompt;
+- a copyable example prompt or lifecycle reproduction;
 - the expected result;
 - dependencies and supported platforms;
 - network and data behavior;
 - automated and manual test evidence.
 
-Review covers usefulness, reproducibility, clear ownership, data flow, dependency risk, and obvious
-supply-chain issues. Acceptance means “available as community software”; it is not a MiniMax
-endorsement or a complete security audit.
+Review covers usefulness, reproducibility, clear ownership, implicit execution, data flow,
+dependency risk, and obvious supply-chain issues. Acceptance means “available as community
+software”; it is not a MiniMax endorsement or a complete security audit. Hook acceptance confirms
+the staged registry declaration only. It does not establish runtime availability until this
+repository links a compatible MiniMax Code implementation and end-to-end conformance evidence.
 
 ## Update or remove a Plugin
 

README.md

@@ -18,9 +18,9 @@
 
 ## One folder is the release
 
-MiniMax Code Plugins is the community home for Agent Plugins that run in MiniMax Code. Put a
-portable Plugin under `plugins/<github-owner>/<plugin-name>`, open a pull request, and let CI check
-the package users will actually install.
+MiniMax Code Plugins is the community home for Agent Plugins that run in MiniMax Code. Put a Plugin
+under `plugins/<github-owner>/<plugin-name>`, open a pull request, and let CI check the package users
+will actually install.
 
 ```text
 fork  →  create  →  build  →  check  →  pull request  →  discover
@@ -71,15 +71,24 @@ good prompt pattern to a capability anyone can install.
 Connect MiniMax Code to local tools or remote services with `stdio`, `streamable-http`, or `sse`.
 Dependencies, accounts, network destinations, and data handling must be visible before install.
 
-### Both
+### Hooks
 
-Use a Skill to teach the workflow and MCP to provide the tools. The portable package stays small:
+Declare observe-only commands for six MiniMax Code lifecycle points with the staged, versioned
+[`io.minimax.mcode` Hooks 0.1 client extension](docs/hooks.md). The registry validates explicit
+commands, arguments, and disclosures. Runtime execution remains unavailable as a documented public
+capability until a compatible MiniMax Code build and end-to-end evidence are linked.
+
+### Combine them
+
+Use Skills to teach the workflow, MCP to provide tools, and Hooks for bounded lifecycle side effects:
 
 ```text
 plugin-root/
 ├── plugin.json
 ├── mcp.json                  # optional
-└── skills/                   # optional
+├── skills/                   # optional
+└── io.minimax.mcode/         # optional MiniMax Code extension
+    └── hooks/hooks.json
 ```
 
 This repository is for **Agent capabilities**. TUI Extensions are a separate system and are not
@@ -91,7 +100,7 @@ A contribution must:
 
 - live at `plugins/<github-owner>/<plugin-name>`;
 - include `plugin.json`, `README.md`, and `LICENSE`;
-- expose at least one valid Skill or MCP server;
+- expose at least one valid Skill, MCP server, or MiniMax Code Hook;
 - document a copyable example, requirements, network access, and data use;
 - contain no secrets, private endpoints, hidden telemetry, native binaries, or symlinks;
 - pass `npm run check` and human review.
@@ -104,16 +113,19 @@ or a complete security audit. Read the source and requested capabilities before
 - [`plugins/`](plugins/) — community Plugin source
 - [`examples/hello-mcode`](examples/hello-mcode/) — smallest Skill Plugin
 - [`examples/hello-mcode-mcp`](examples/hello-mcode-mcp/) — dependency-free stdio MCP
+- [`examples/hello-mcode-hooks`](examples/hello-mcode-hooks/) — smallest Hook-only Plugin
 - [`docs/plugin-compatibility.md`](docs/plugin-compatibility.md) — exact supported contract
+- [`docs/hooks.md`](docs/hooks.md) — MiniMax Code Hooks 0.1 author and runtime contract
 - [`docs/security-model.md`](docs/security-model.md) — validation and trust model
 - [`docs/architecture.md`](docs/architecture.md) — hosted contribution architecture
 - [`GOVERNANCE.md`](GOVERNANCE.md) — decisions and maintainer responsibilities
 
 ## Community preview
 
-The contract is intentionally narrow while MiniMax Code's public Plugin surface stabilizes. Hooks,
-custom Agents, Commands, LSP, Apps, generic OAuth, and TUI Extensions are not advertised as current
-Agent Plugin capabilities.
+The contract is intentionally narrow while MiniMax Code's public Plugin surface stabilizes. Hooks
+0.1 is accepted as a staged registry declaration; this repository does not yet certify a runtime
+build that executes it. Custom Agents, Commands, LSP, Apps, generic OAuth, blocking Hooks, and TUI
+Extensions are not advertised as current Agent Plugin capabilities.
 
 Bring one useful capability. Make the example undeniable. Ship it in one pull request.
 

README.zh-CN.md

@@ -69,15 +69,23 @@ npm run check
 通过 `stdio`、`streamable-http` 或 `sse` 连接本地工具和远程服务。依赖、账号、网络目标和数据处理必须
 在安装前说清楚。
 
-### Skill + MCP
+### Hooks
 
-Skill 教会 Agent 怎么做，MCP 给它真正的工具。可移植包结构保持简单：
+通过分阶段、版本化的 [`io.minimax.mcode` Hooks 0.1 客户端扩展](docs/hooks.md)，声明 MiniMax Code
+六个生命周期点的只观察命令。仓库会校验 command、args 和披露内容；在链接兼容的 MiniMax Code 构建及
+端到端证据前，不把运行时执行宣传为已公开可用能力。
+
+### 组合使用
+
+Skill 教会 Agent 怎么做，MCP 提供工具，Hook 负责有边界的生命周期副作用：
 
 ```text
 plugin-root/
 ├── plugin.json
 ├── mcp.json                  # 可选
-└── skills/                   # 可选
+├── skills/                   # 可选
+└── io.minimax.mcode/         # 可选的 MiniMax Code 扩展
+    └── hooks/hooks.json
 ```
 
 这个仓库只承接 **Agent 能力**。TUI Extension 是另一套独立扩展体系，不使用这里的包格式和加载流程。
@@ -88,7 +96,7 @@ plugin-root/
 
 - 位于 `plugins/<GitHub 用户名>/<Plugin 名>`；
 - 包含 `plugin.json`、`README.md` 和 `LICENSE`；
-- 至少提供一个有效的 Skill 或 MCP Server；
+- 至少提供一个有效的 Skill、MCP Server 或 MiniMax Code Hook；
 - 写清示例、依赖、网络访问和数据用途；
 - 不包含密钥、私有地址、隐藏遥测、原生二进制或 symlink；
 - 通过 `npm run check` 和人工 Review。
@@ -101,15 +109,18 @@ plugin-root/
 - [`plugins/`](plugins/)：社区 Plugin 源码
 - [`examples/hello-mcode`](examples/hello-mcode/)：最小 Skill Plugin
 - [`examples/hello-mcode-mcp`](examples/hello-mcode-mcp/)：零依赖 stdio MCP
+- [`examples/hello-mcode-hooks`](examples/hello-mcode-hooks/)：最小 Hook-only Plugin
 - [`docs/plugin-compatibility.md`](docs/plugin-compatibility.md)：当前支持的精确契约
+- [`docs/hooks.md`](docs/hooks.md)：MiniMax Code Hooks 0.1 作者与运行时契约
 - [`docs/security-model.md`](docs/security-model.md)：校验与信任模型
 - [`docs/architecture.md`](docs/architecture.md)：中央托管架构
 - [`GOVERNANCE.md`](GOVERNANCE.md)：决策与维护者职责
 
 ## Community Preview
 
-MiniMax Code 的公开 Plugin 能力仍在稳定中，所以首版契约刻意保持克制。Hooks、自定义 Agent、Commands、
-LSP、Apps、通用 OAuth 和 TUI Extension 暂不作为当前 Agent Plugin 能力宣传。
+MiniMax Code 的公开 Plugin 能力仍在稳定中，所以契约刻意保持克制。仓库接受 Hooks 0.1 的分阶段声明，
+但尚未认证并链接可以执行它的运行时构建。自定义 Agent、Commands、LSP、Apps、通用 OAuth、阻断型
+Hooks 和 TUI Extension 暂不作为当前 Agent Plugin 能力宣传。
 
 带来一个真的有用的能力，给出一个无法误解的示例，然后用一个 PR 把它发布出来。
 

docs/architecture.md

@@ -4,7 +4,7 @@ MiniMax Code Plugins keeps contribution and review in one repository.
 
 ```text
 plugins/<owner>/<plugin>
-  plugin.json + README + LICENSE + Skills and/or MCP
+  plugin.json + README + LICENSE + Skills, MCP, and/or Hooks
           |
           v
 local validation -> pull request CI -> human review
@@ -16,9 +16,10 @@ main branch -> catalog consumers / MiniMax Code discovery
 The hosted directory is the publication unit. Reviewers inspect the exact files that enter `main`;
 contributors do not create a second repository or maintain a separate catalog record.
 
-Static validation reads package metadata and text contracts without executing Plugin code. Human
-review covers usefulness, dependencies, data flow, and reproducibility. MCP runtime behavior and
-external service quality still require explicit test evidence.
+Static validation reads package metadata and text contracts without executing Plugin code. In
+particular, CI never executes contributed Hook commands. Human review covers usefulness,
+dependencies, implicit execution, data flow, and reproducibility. MCP and Hook runtime behavior and
+external service quality still require explicit test evidence from a compatible client.
 
 The first version intentionally optimizes for a low-friction community path. External source
 registries, release mirroring, and Marketplace publishing interfaces can be proposed later without