Plugins: hooks and points

A plugin is a directory with a grid-plugin.json and an entry point that exports activate(context). It runs in its own process, fenced by what its manifest declares, and reaches Grid Console two ways: transition hooks, which can refuse a card's move, and extension points, which are lists that core reads. Writing and sideloading your own is free on every tier, including Free.

Two mechanisms

A hook is a function. It runs when a card crosses an arrow and answers with a verdict. An extension point is a registry: a plugin contributes a payload once, at activation, and the subsystem that owns the point reads the list. Hooks are named in the manifest's hooks array and points in its points array. The loader refuses a name outside either vocabulary, and the host refuses a registration the manifest did not declare.

A third manifest block, capabilities, states facts rather than code: isolation and errors, read straight off the manifest by the session engine. See manifest, permissions and trust. It follows its own rule about names. A hook or a point outside the vocabulary is a load error; an unrecognised key inside capabilities is logged once and ignored, so a manifest declaring a capability only a newer Grid reads still loads here.

"use strict";

module.exports = {
  activate(context) {
    context.hooks.on("before:deliver", (ctx) => {
      const body = ctx.card.body ?? ctx.body ?? "";
      if (!/^## Ticket\b/m.test(body)) {
        ctx.block({
          reason: "No ticket reference on the card",
          fix: "Add a \"## Ticket\" section naming the issue this card resolves.",
        });
        return;
      }
      ctx.pass();
    });
  },
};

With "hooks": ["before:deliver"] in the manifest, that is a complete plugin. The manifest itself is in manifest, permissions and trust.

Transition hooks

Every stage change goes through one place in the engine, whether you dragged the card, pressed approve, or the agent wrote status: into the card file. Hooks register on arrow endpoints.

<stage> is one of inbox, prepare, doing, review, deliver, verify and closed. A move from Doing to Review runs after:doing and then before:review, in registration order, and stops at the first block.

The context carries the card as the contract describes it and nothing more: card.slug, card.title, card.state, card.project, card.thread, the markdown body and the parsed frontmatter, plus from, to, reason, observed, hook and plugin. The host reads the body and frontmatter for you, so a stage contract needs no filesystem permission. Read the body as ctx.card.body ?? ctx.body: which of the two arrives depends on how the host loaded you.

Three rules keep a hook from wedging the pipeline. A hook that throws is logged and treated as a pass. A hook that has not answered after 5 seconds is skipped and the move proceeds. And a move the agent already wrote to disk is observed instead of executed: the hooks still run, but a block on an observed move is recorded as an advisory on the card rather than a revert, because the write has already happened.

Settings › SDLC draws a MUST BE TRUE TO PASS list on every arrow. Each check is the workflow plugin's own wording, and it gets a tick only when a hook is really registered on that arrow, attributed to the plugin that registered it. Today one arrow has a gate: Doing to Review, where grid-sdlc-default holds a card to its Review contract. A manifest that declares a hook and never registers it, as that plugin does for before:deliver, gets no tick.

Extension points

Sixteen point names are accepted by the loader. Five have a reader in core today, five are claimed by a bundled descriptor plugin while the behaviour lives in core, and six are vocabulary only. That count is about the POINT mechanism specifically. For agent.provider it is no longer the whole story: since plugin API 0.2 a manifest can also declare permissions.spawn, a signed permission rather than a point, which is what lets a provider plugin actually start its own process instead of only supplying wording for one core already knows how to run.

What is core, and what is a plugin

Grid keeps what you must be able to trust, and everything with an opinion in it is meant to ship as a plugin. The alpha is part way there: the bundled plugins own the words and the tables, and several behaviours they describe still run in core.

The nine bundled plugins are listed with what each really owns in bundled plugins. grid-explain is the one descriptor whose contribution does something today: a menu row, a keymap entry and a command behind them. copilot-provider goes further still, since its manifest is what actually starts its session; see Adding a provider.

The process sandbox

Every plugin, bundled ones included, activates in a child process of the daemon rather than inside the daemon itself. The process is started with Node's permission flags derived from the manifest: --permission, --allow-fs-read for the plugin's own directory and every declared filesystem root, --allow-fs-write for the declared roots, and --allow-child-process only when shell is true. Network is fenced inside the process: http, https, net, tls and fetch are wrapped before the plugin is loaded and refuse any host not covered by permissions.network, where a declared domain covers its subdomains. cardWrite, points, hooks and commands are checked on the host's side of the boundary, where a compromised child has no vote.

Plugins with identical grants share one process, so the bundled set, which declares nothing, costs one locked-down process. Each row on the Plugins page says how well it is fenced: full means the flags were applied, partial means this Node runtime refused the flags and only the boundary holds, and none means the in-process escape hatch (GRID_PLUGIN_INPROC=1) is on. A process that crashes is restarted once; a second crash within 30 seconds leaves its plugins down with the reason on the row.

This enforces declared rights without claiming to be a hostile-code sandbox. The network fence holds an honest plugin to what it declared and catches a buggy one; it does not stop code that has decided to get out. Native addons are refused at pack and add time, and node_modules never travels, so bundle your dependencies.

Settings from the manifest

A plugin declares its settings in grid-plugin.json. Grid renders the controls itself, so a plugin does not have to be loaded, or even enabled, for its settings to be visible or changed. Values live in <workspace>/.grid/plugin-settings.json and reach the plugin as context.settings, a frozen snapshot taken at activation. Saving a value disposes and re-activates that one plugin, so activate() runs again with the new object.

"configuration": {
  "model": {
    "type": "enum",
    "title": "Summary model",
    "default": "haiku",
    "options": ["fable", "opus", "sonnet", "haiku"]
  },
  "inlineNotes": { "type": "bool", "title": "Inline notes", "default": true },
  "prompts.build": { "type": "prompt", "title": "Build prompt", "default": "Settings › SDLC" }
}

scope accepts workspace or project. Only workspace is honoured: this build stores values and enablement per workspace, and the row says so rather than pretending. There is no secret type. Do not put a key in a setting.

The six stage prompts are the case that matters most. The providers declare them as prompt links, and you edit the text on the arrow in Settings › SDLC. What you type there is an override, and Restore default deletes it. There is no diff view against the shipped text.

Commands

A contribution to a UI point is static data, so it can name what it does but cannot be what it does. The other half is a command: declare "commands": ["<pluginId>:<name>"] in the manifest, register it with context.commands.register(name, fn), and the UI reaches it over POST /api/plugins/<id>/invoke. Arguments in and the answer out are plain JSON, and a command that has not answered after 15 seconds is reported as such rather than swallowed. The prefix is mandatory so a plugin command can never collide with one of Grid's own in the keymap. grid-explain:describe-selection is the shipped example.

The SDK

@gridconsole/plugin in the plugins repository ships the type definitions for everything above and four test helpers, so a hook or an activate() runs under node --test without the engine.

const { fakeCtx } = require("@gridconsole/plugin");
const ctx = fakeCtx({ from: "review", to: "deliver", body: "## Summary\n..." });
await hook(ctx);
assert.strictEqual(ctx.verdict.kind, "block");

Packaging, signing and the CLI

A pinned plugin whose files no longer hash to the pin refuses to load and reads TAMPERED until you grid plugin add it again. A .gridplugin is one JSON file: the manifest, every file with its own digest, the content hash, a manifest digest and, when signed, the public key, an Ed25519 signature over all of those and a timestamp. The key that makes a plugin official ships inside the app. What the three trust states mean is in manifest, permissions and trust.

The Plugins pane

Settings › Plugins lists the bundled plugins, then anything installed, then the catalogue.

MCP servers and skills

MCP servers and skills stay where the CLI keeps them. The provider's settings rows point at the config file and the skills folder, and claude mcp remains the way to add a server, because adding one means handling its keys, and Grid never holds those.