> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks Manager

> Intercept agent operations with pre/post hooks

Intercept and modify agent operations with lifecycle hooks.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agent[Agent] --> Hooks[Hooks Manager]
    Hooks --> Ops([Operations])

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff

    class Agent,Hooks agent
    class Ops tool
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import { createHooksManager } from 'praisonai';

    const hooks = createHooksManager();

    // Log all LLM calls
    hooks.register('pre_llm_call', async (context) => {
      console.log('LLM Request:', context.prompt);
      return context;
    });

    // Validate tool calls
    hooks.register('pre_tool_call', async (context) => {
      if (context.toolName === 'dangerous_tool') {
        console.warn('Blocked dangerous tool');
        return null; // Block the operation
      }
      return context;
    });
    ```
  </Step>
</Steps>

## Hook Events

### Operation Hooks (Python Parity)

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Code operations
hooks.register('pre_read_code', handler);
hooks.register('post_read_code', handler);
hooks.register('pre_write_code', handler);
hooks.register('post_write_code', handler);

// Command operations
hooks.register('pre_run_command', handler);
hooks.register('post_run_command', handler);

// Prompt operations
hooks.register('pre_user_prompt', handler);
hooks.register('post_user_prompt', handler);

// MCP operations
hooks.register('pre_mcp_tool_use', handler);
hooks.register('post_mcp_tool_use', handler);
```

### LLM/Tool Hooks (CrewAI/Agno Parity)

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// LLM call hooks
hooks.register('pre_llm_call', async (ctx) => {
  // Modify prompt, add context, etc.
  return ctx;
});

hooks.register('post_llm_call', async (ctx) => {
  // Log response, filter content, etc.
  return ctx;
});

// Tool call hooks  
hooks.register('pre_tool_call', async (ctx) => {
  // Validate arguments, block dangerous tools
  return ctx;
});

hooks.register('post_tool_call', async (ctx) => {
  // Log results, modify output
  return ctx;
});
```

### Lifecycle Hooks

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Agent lifecycle
hooks.register('agent_start', (ctx) => console.log('Agent started'));
hooks.register('agent_complete', (ctx) => console.log('Agent completed'));

// Run lifecycle
hooks.register('run_started', handler);
hooks.register('run_completed', handler);
```

## Blocking Operations

Return `null` from a hook to block the operation:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
hooks.register('pre_tool_call', async (context) => {
  const dangerousTools = ['delete_file', 'execute_shell'];
  
  if (dangerousTools.includes(context.toolName)) {
    console.warn(`Blocked: ${context.toolName}`);
    return null; // Block the operation
  }
  
  return context; // Allow the operation
});
```

## Modifying Context

Return modified context to change the operation:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
hooks.register('pre_llm_call', async (context) => {
  // Add system context
  context.prompt = `[Safety Mode Active]\n${context.prompt}`;
  return context;
});

hooks.register('post_llm_call', async (context) => {
  // Redact sensitive info
  context.response = context.response.replace(/\b\d{16}\b/g, '****');
  return context;
});
```

## Factory Functions

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { createLoggingOperationHooks, createValidationOperationHooks } from 'praisonai';

// Pre-configured logging
const loggingHooks = createLoggingOperationHooks((event, ctx) => {
  console.log(`[${event}]`, ctx);
});

// Pre-configured validation
const validationHooks = createValidationOperationHooks((event, ctx) => {
  if (!ctx.agentId) {
    return { valid: false, reason: 'Missing agentId' };
  }
  return { valid: true };
});
```

## Hook Priority

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Higher priority runs first
hooks.register('pre_llm_call', handler1, { priority: 10 });
hooks.register('pre_llm_call', handler2, { priority: 5 });
// handler1 runs before handler2
```

## Hook Timeout

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
hooks.register('pre_llm_call', slowHandler, {
  timeout: 5000 // 5 second timeout
});
```

## Related

<CardGroup cols={2}>
  <Card title="Callbacks" icon="bell" href="/docs/js/callbacks">
    Display and approval callbacks
  </Card>

  <Card title="Workflow Hooks" icon="webhook" href="/docs/js/workflow-hooks">
    Workflow lifecycle hooks
  </Card>

  <Card title="Guardrails" icon="shield" href="/docs/js/guardrails">
    Input/output validation
  </Card>
</CardGroup>