Hooks

Intercept messages, tool calls, and lifecycle events

Plugins can register hooks to intercept and modify messages, tool calls, and lifecycle events.

Available Hooks

Hook	When	Can modify/block?	Use cases
prePrompt	Before user message → LLM	Transform message, block it	Content filtering, prompt injection detection
postResponse	After LLM response, before delivery	Transform response, block it	Content filtering, post-processing
preToolExec	Before a tool executes	Allow/deny	Policy enforcement, audit
postToolExec	After a tool executes	Transform result	Audit, caching
sessionCreated	New session created	Observe only	Analytics, welcome messages
sessionDisposed	Session cleaned up	Observe only	Cleanup
modelSwitched	Model changed (fallback or user override)	Observe only	Notifications, analytics
gatewayStarted	All plugins loaded + started	Observe only	Health checks
gatewayShutdown	Before gateway shuts down	Observe only	Cleanup

Execution Order

Hooks execute sequentially in plugin config order. If you have:

plugins: {
  logger: { ... },      // registered first
  filter: { ... },      // registered second
}

Then logger’s hooks run before filter’s hooks.

Hook Flow

Channel plugins (Telegram, etc.)

For channels that run in-process with the gateway, hooks execute as part of the AgentManager.prompt() / promptStreaming() call:

User message arrives
  │
  ▼
prePrompt hooks (can transform/block)
  │
  ▼
LLM call with tool loop
  │ (for each tool call)
  ├── preToolExec hooks (can deny)
  ├── tool execution
  └── postToolExec hooks (can transform result)
  │
  ▼
postResponse hooks (can transform/block)
  │
  ▼
Response delivered to channel

TUI (separate process)

For the TUI, LLM calls are proxied through the gateway’s /api/chat/stream endpoint. Hooks execute server-side in the gateway, not in the TUI process:

User types message in TUI
  │
  ▼
TUI sends POST /api/chat/stream to gateway
  │
  ▼
Gateway: prePrompt hooks (can transform/block)
  │ (if blocked → sends "blocked" event → TUI aborts)
  ▼
Gateway: streams LLM call back to TUI (with fallback model logic)
  │
  ▼
Gateway: postResponse hooks (fire-and-forget, response already streamed)
  │
  ▼
TUI renders streamed response

Note: preToolExec/postToolExec hooks run on tool calls made through the AgentManager path (channel plugins). For TUI tool calls (which go through /api/agents/:name/exec), tools execute directly in the sandbox — preToolExec/postToolExec hooks apply to plugin tool calls routed through the Unix socket, not to core tool execution.

Registering Hooks

export function createPlugin(config, ctx) {
  return {
    register(reg) {
      // Content filter: block messages containing forbidden patterns
      reg.hook("prePrompt", async (event) => {
        for (const pattern of config.blockedPatterns) {
          if (event.message.includes(pattern)) {
            return { message: "", block: true, reason: `Blocked: contains "${pattern}"` };
          }
        }
        return { message: event.message };
      });

      // Audit: log every tool call
      reg.hook("preToolExec", async (event) => {
        console.log(`[AUDIT] ${event.agentName} calling ${event.toolName}`);
        return { allow: true };
      });

      // Post-processing: strip sensitive data from responses
      reg.hook("postResponse", async (event) => {
        const cleaned = event.response.replace(/\b\d{3}-\d{2}-\d{4}\b/g, "***-**-****");
        return { response: cleaned };
      });
    },
  };
}

Hook Event Types

prePrompt

interface PrePromptEvent {
  message: string;       // The user's message
  sessionKey: string;    // Session identifier
  agentName: string;     // Target agent
  channel: string;       // Which channel sent this
}

// Return: { message, block?, reason? }

postResponse

interface PostResponseEvent {
  response: string;      // The LLM's response
  sessionKey: string;
  agentName: string;
  channel: string;
}

// Return: { response, block? }

preToolExec / postToolExec

interface PreToolExecEvent {
  toolName: string;
  args: string[];
  sessionKey: string;
  agentName: string;
}

// preToolExec return: { allow, reason? }
// postToolExec return: { result? }

Lifecycle hooks

interface SessionLifecycleEvent {
  sessionKey: string;
  agentName: string;
  channel: string;
}

// sessionCreated / sessionDisposed: return void

interface GatewayLifecycleEvent {}

// gatewayStarted / gatewayShutdown: return void

modelSwitched

Fired when a session uses a different model than the primary — either due to automatic fallback (rate limit, error, timeout) or an explicit user override (e.g. /model command).

interface ModelSwitchedEvent {
  sessionKey: string;
  agentName: string;
  channel: string;
  previousModel: { provider: string; modelId: string };
  newModel: { provider: string; modelId: string };
  reason: "fallback_rate_limit" | "fallback_error" | "fallback_timeout" | "user_override";
}

// return void

Example: send a Telegram notification when a fallback occurs:

reg.hook("modelSwitched", async (event) => {
  if (event.reason === "user_override") return; // user chose this, no alert needed
  const from = `${event.previousModel.provider}/${event.previousModel.modelId}`;
  const to = `${event.newModel.provider}/${event.newModel.modelId}`;
  ctx.log.warn(`Model switched from ${from} to ${to} (${event.reason})`);
});