Hook System — Agent Manager Docs

Overview

The hook system bridges Claude Code's lifecycle events to Agent Manager via Unix socket IPC at /tmp/agent-manager/hooks.sock, using newline-delimited JSON.

Event Types

PermissionRequest — Tool execution approval routed through connectors
PostToolUse — Tool results forwarded to messaging platforms
Notification — Agent responses and status changes relayed to connectors
Stop — Session stop events

Protocol

Messages are newline-delimited JSON sent over a Unix domain socket. Each connection handles a single request-response cycle.

Message Types

// Hook → Manager
interface HookMessage {
  type: "permission_request" | "post_tool_use" | "stop" | "notification";
  payload: Record<string, unknown>;
}

// Manager → Hook
interface HookResponse {
  type: "permission_reply" | "ack";
  payload: Record<string, unknown>;
}

TypeScript

For permission_request, the manager waits for a response from the configured connector (e.g., a Slack reply) and sends back a permission_reply. All other message types receive an immediate ack.

Hook Server

The HookServer class runs inside the agent-manager process. It creates a Unix socket at /tmp/agent-manager/hooks.sock and listens for incoming connections.

class HookServer extends EventEmitter {
  get socketPath(): string;
  async start(): Promise<void>;
  async stop(): Promise<void>;

  // Events emitted:
  // "permission_request" — (payload, respond) => void
  // "post_tool_use"      — (payload) => void
  // "stop"               — (payload) => void
  // "notification"       — (payload) => void
}

TypeScript

Client Function

Hooks use sendToHookServer() to communicate with the manager:

async function sendToHookServer(
  msg: HookMessage,
  timeoutMs?: number  // default: 10000
): Promise<HookResponse | null>;

// Returns null if the manager isn't running

TypeScript

Installation

Install hooks with:

npm run install-hooks

bash

This registers three hooks in ~/.claude/settings.json: a permission request handler, a post-tool-use handler, and a notification handler. Each hook sends events through IPC to the manager, which routes them to connectors.

To remove hooks:

npm run uninstall-hooks

bash