When to use a mod in a Magpie family plugin

Claude Code introduces mods (TypeScript/JavaScript event hook modules packaged in plugins). This page documents the framework rules, boundaries, and decision rubric for when to introduce a mod into an Apache Magpie family plugin, and where mods must never be used.

The central theme of any Magpie mod is moving deterministic or presentational work out of the model’s context. Doing work in local code eliminates token consumption, removes latency, and produces deterministic user experiences while preserving full multi-harness portability.

Overview and motivation

A mod is a plugin component that executes inside the host agent process when events occur. Each hook acts as middleware ($, e, next) that can observe an event, rewrite it, or answer it without initiating a model turn.

In Apache Magpie, skills are the universal unit of workflow authorship (PRINCIPLES.md §15). A skill is plain Markdown that any capable agentic harness can execute. However, certain repetitive tasks do not require model reasoning:

• Checking whether local lockfiles have drifted before executing a skill.
• Rendering live terminal dashboards, progress bands, or interactive multi-item selection panes.
• Executing zero-token slash commands (such as listing available skills or inspecting local setup status).
• Enforcing deterministic safety checks (such as grepping outgoing patches for private CVE identifiers before pushing).

When implemented as a mod, these operations run with zero token cost and zero latency.

The four non-negotiable constraints

Every mod authored for or shipped with Apache Magpie must strictly comply with four non-negotiable constraints.

1. Vendor neutrality (the additive-only rule)

Vendor neutrality is a foundational design principle of Apache Magpie (PRINCIPLES.md §10, docs/vendor-neutrality.md). Mods exist only in Claude Code (CLI and Desktop Code tab). They don’t run in Codex or Gemini CLI, and the VS Code panel and claude -p don’t draw them.

Therefore, a mod can only ever enhance a skill additively. Every skill must continue to work end-to-end when mods are disabled, unsupported, or absent. A skill that requires a mod to complete its core workflow is broken by definition.

When a mod accelerates or formats an interaction, the underlying skill must maintain a clean fallback:

• If a mod provides an interactive multi-item review pane, the skill must still support sequential terminal prompts or standard markdown output on other harnesses.
• If a mod performs a zero-token pre-flight check, the skill must retain its standard markdown pre-flight step for harnesses without mod support.

2. Security and unsandboxed execution boundaries

Mods execute directly in the user’s host environment with full user privileges outside the Bash sandbox. A mod’s $.fs, $.process, and $.http calls bypass the filesystem isolation and network egress gateways that sandbox standard agent tool executions. Furthermore, a mod can intercept and approve tool calls that an interactive user confirmation rule would otherwise prompt for.

To protect adopters:

• Any mod shipped in a Magpie family plugin must expose a minimal, strictly auditable calls: surface.
• Mods must never execute unvetted external scripts, spawn long-lived unsandboxed background daemons, or initiate untracked network requests.
• All secure-setup documentation (docs/setup/secure-agent-setup.md) must explicitly document the security trade-offs of enabled mods.

3. Privacy-LLM compliance

The privacy-aware LLM routing policy (docs/setup/privacy-llm.md, RFC-AI-0003) governs every model interaction. Calls to $.model.complete, $.model.fork, or turn.step model routing constitute model hops under the privacy rules.

• A mod must never route sensitive or private project data to an unapproved model endpoint.
• A mod must not attempt to circumvent privacy sanitization or PII redaction filters.
• Mods should favor deterministic code execution over embedded model calls whenever possible.

4. Distribution and enterprise policy fallbacks

Magpie distributes skills through modular family plugins (such as plugins/magpie-setup/ and plugins/magpie-utilities/). When a family includes a mod, the mod files live under the family plugin’s hooks/ directory (e.g. hooks/hooks.json and hooks/register.ts), not directly in the plugin root.

Enterprise environments often enforce strict administrator policies, such as allowManagedModsOnly. In these environments, user-level or third-party mods will be blocked by the agent runtime. Magpie plugins must handle this gracefully: the plugin and its skills will load normally, and the workflow must proceed without throwing errors or halting execution.

Architectural seam: mods vs. capabilities vs. skills

To maintain architectural clarity, Magpie enforces a strict distinction between skills, capability contracts, tools, and mods:

┌────────────────────────────────────────────────────────┐      ┌─────────────────────────────────────────────────┐
│ SKILLS (Universal Markdown)                            │      │ MODS (Claude Code Only)                         │
│ - Portable across all harnesses (Gemini, Codex, etc.)  │      │ - Additive event hooks                          │
│ - Declares required capability contracts (contract:*)  │<─────┤ - Hooks harness alongside skill execution       │
└───────────────────────────┬────────────────────────────┘      │ - Zero-token UI, commands, & pre-checks         │
                            │                                   │ - Lives under plugins/<family>/hooks/           │
                            v                                   └─────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────┐
│ CAPABILITY CONTRACTS & TOOLS (Python / Shell)          │
│ - Abstraction layer for vendor backends (GitHub, Git)  │
│ - Backed by tool adapters under tools/<name>/          │
└────────────────────────────────────────────────────────┘

A mod is not a Magpie capability contract. Capability contracts (contract:tracker, contract:source-control, contract:cve-authority) define abstract operations fulfilled by swappable backend tools. Mods operate purely at the harness integration tier alongside skill execution to enhance user experience and optimize token efficiency.

Decision rubric: when to author a mod

Contributors and maintainers should evaluate proposed mod implementations against the following rubric.

Allowed and recommended uses

Forbidden anti-patterns

Starting points across skill families

The following table summarizes candidate opportunities for additive mods across Magpie skill families:

Packaging, testing, and CI validation

Mods ship inside their respective family plugins in plugins/<family>/ under the hooks/ directory. The plugin manifest sits at .claude-plugin/plugin.json declaring plugin metadata:

{
  "name": "magpie-utilities",
  "description": "Apache Magpie — framework meta-skills and zero-token utilities.",
  "version": "0.9.0.dev0"
}

The hooks manifest at hooks/hooks.json lists the mod modules to load:

{
  "modules": ["./register.ts"]
}

The module (hooks/register.ts) exports a register(on, options) function that registers event listeners with the harness. It imports only its own files, by relative path, and claude-code. Node built-ins such as node:fs are not available: reach files, the environment and processes through the mods API ($.fs, $.env, $.process), so the calls: line claude plugin validate prints is the module’s whole surface. hooks/hooks.json can also carry the plugin’s settings hooks under hooks, next to modules; a mod that takes over from a settings hook keeps that hook wired there for sessions where mods do not load.

Every mod must include unit tests and pass strict validation before landing:

1. Static Validation: Mod modules must pass claude plugin validate <dir> --strict to verify hooked events and API calls. Claude Code runs the same analysis when it loads a mod and skips a module that fails it, so a mod that fails here does nothing at all on an adopter’s machine.
2. Automated Unit Tests: Hook logic must be tested using claude plugin test with corresponding *.test.ts test suites written against claude-code/testing. A mod with no tests fails the check.
3. CI Integration: the check-claude-mods prek hook (tools/dev/check-claude-mods.sh) runs both commands on every plugin whose hooks/hooks.json declares modules, on every pull request and push to main. prek installs a pinned Claude Code into the hook environment, so neither a local install nor a login is needed. The hook is in the manual stage, so ordinary commits skip it; run it before pushing a mod with prek run check-claude-mods --hook-stage manual --all-files. The pin is bumped three times a week, with a 12-hour cooldown, by bump-hook-npm-pins.yml. Claude Code is a dev-only tool here: CI runs it to check the mods, it is not a dependency of anything Magpie ships, and nothing from it goes into a release or a plugin.

See also

• docs/vendor-neutrality.md — How Magpie achieves neutrality across six independent axes
• docs/extending.md — Extension points across skills, tools, organizations, and harnesses
• docs/labels-and-capabilities.md — The capability taxonomy and label taxonomy
• docs/setup/secure-agent-setup.md — The sandboxed agent execution environment
• docs/setup/privacy-llm.md — Privacy-aware LLM routing and endpoint approval
• PRINCIPLES.md — Core architectural principles of Apache Magpie