Lifecycle Hooks

Extensions subscribe to lifecycle events with fp.on(event, handler). Hooks fall into two categories:

Pre-hooks run before the action is committed. Return a HookValidationError to block the operation, or undefined to allow it.

Post-hooks run after the action succeeds. They return void and are used for side effects.

Event List

See the Lifecycle Events section in the API Reference for the complete table of events, context types, and descriptions.

on() also accepts arbitrary event strings for forward compatibility with future events.

Blocking with HookValidationError

Pre-hooks can return an error object to prevent the operation:

fp.on("issue:status:changing", ({ issue, from, to }) => {
  if (from === "todo" && to === "done") {
    return {
      code: "NO_SKIP_IN_PROGRESS",
      message: "Issues must go through in-progress before done",
    };
  }
  return undefined;
});

The HookValidationError shape:

interface HookValidationError {
  code: string;
  message: string;
  details?: Record<string, unknown>;
}

Execution Order

When multiple extensions register the same pre-hook, they run in discovery order. The first rejection stops remaining hooks.

Post-hooks are fire-and-forget. Uncaught exceptions are logged but don’t crash the extension.

Hook Selection Guidelines

• Use pre-hooks for validation, post-hooks for side effects.
• Avoid heavy work (network calls, spawning processes) in pre-hooks. Keep them fast.
• Do not mutate state in pre-hooks. They are for gating only.
• Register the narrowest hook possible. Use issue:status:changing rather than issue:updating when you only care about status transitions.