Plugin System

Headmaster plugins extend the agent runtime with commands, hooks, tools, dashboard surfaces, and policy checks without changing core agent code.

Plugin architecture

Manifest

Each plugin declares its name, version, permissions, commands, hooks, and dashboard contributions in a manifest.

Runtime hooks

Hooks can observe or modify lifecycle events such as session start, tool pre-call, tool result, approval request, and run completion.

Permission boundary

Plugins receive only the scopes declared in their manifest and can be blocked by workspace policy before activation.

Development guide

Create a plugin

Start with a manifest, add a command or hook handler, then test it in a local workspace before distributing it to a team.

plugin:
  name: weekly-review
  version: 0.1.0
  permissions:
    - runs:read
    - reports:write
  commands:
    - /weekly-review

Test safely

Run plugins in a sandbox workspace first, confirm their audit events, then promote them to production after approval.

Distribution

Private marketplace

Organizations can maintain an internal plugin catalog with approved versions and owner metadata.