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 name, version, owner, permissions, slash commands, lifecycle hooks, dashboard contributions, and distribution metadata.

plugin:
  name: weekly-review
  version: 0.1.0
  owner: ops
  permissions:
    - runs:read
    - reports:write
  commands:
    - name: /weekly-review
      route: handlers.weekly_review
  hooks:
    - event: session:start
      handler: hooks.seed_context
    - event: tool:pre-call
      handler: hooks.policy_check
    - event: tool:result
      handler: hooks.redact_result
  dashboard:
    - tab: Weekly Review
      component: dashboard.weekly_review

Runtime hooks

Hook	Fires when	Arguments	Can modify
session:start	A run session begins	workspace, run, agent	Seed context or attach metadata
tool:pre-call	Before a tool executes	tool, arguments, run	Veto, rewrite arguments, or require approval
tool:result	After a tool returns	tool, result, correlation_id	Transform, redact, or annotate results
approval:request	A gated output is queued	approval, output, policy	Route or enrich approval requests
run:complete	A run finishes	run, output, costs	Emit summaries or archive evidence

Hook examples

export async function policy_check({ tool, arguments, run }) {
  if (tool.name === "send_email" && !run.approval_id) {
    return { veto: true, reason: "Email requires approval" };
  }
  return { allow: true, correlation_id: run.id };
}

export async function redact_result({ result }) {
  return { result: redactSecrets(result) };
}

Commands

Slash commands register in the manifest, route to a handler, and pass the invocation text, user, channel, workspace, and correlation ID to the agent runtime. Handlers can create a run, attach context, request approval, or return an immediate response.

Permission boundary

Plugins receive only the scopes declared in their manifest and can be blocked by workspace policy before activation. Test 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, owner metadata, changelog, required scopes, and rollback instructions.

Next:

Security · Deployment · Headmaster Core