Hooks Node

Hooks run scripts at specific points in your agent’s lifecycle.

Overview

Purpose: Execute scripts on lifecycle events (before/after tool use, session start, etc.) Connection: Top-left handle of main agent card Color: Yellow Icon: 🪝 Required: Optional (0 to many)

What are Hooks?

Hooks are scripts (shell, Python, Node.js) that run automatically when events occur:

Before tool execution (logging, validation)
After tool execution (notifications, cleanup)
On session start (initialization)
On user input (filtering, preprocessing)

Hook Types

10 Event Types

Event	When It Runs	Use Case
PreToolUse	Before tool execution	Logging, validation, rate limiting
PostToolUse	After tool execution	Notifications, cleanup, metrics
UserPromptSubmit	On user input	Filter profanity, preprocess
PermissionRequest	On permission check	Custom approval logic
SessionStart	Agent session begins	Initialize connections, load context
SessionEnd	Agent session ends	Cleanup resources, save state
Stop	Agent stopped by user	Cancel operations, rollback
SubagentStop	Sub-agent stopped	Sub-agent cleanup
Notification	Status message	Log to external system
PreCompact	Before conversation trim	Archive conversation

Hook Structure

Hooks are shell scripts that receive event data via stdin:

#!/bin/bash
# pre-tool-use-logger.sh

# Read event data
read -r EVENT_DATA

# Parse tool name
TOOL=$(echo "$EVENT_DATA" | jq -r '.tool_name')

# Log to file
echo "[$(date)] Tool called: $TOOL" >> /var/log/agent-tools.log

Creating Hooks

Via Settings → Node Managers → Hooks:

Click “Add New Hook”
Enter name (e.g., “Tool Logger”)
Select event type (e.g., PreToolUse)
Write script (bash, Python, Node.js)
Save to workspace library

Hook appears in sidebar → drag to canvas.

Hook Examples

Example 1: Tool Call Logger (PreToolUse)

Purpose: Log all tool calls to file

#!/bin/bash
# log-tool-calls.sh

read -r EVENT

TOOL=$(echo "$EVENT" | jq -r '.tool_name')
TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")

echo "[$TIMESTAMP] Tool: $TOOL" >> ~/agent-logs/tools.log

Use case: Audit trail of agent actions

Example 2: Cost Tracker (PostToolUse)

Purpose: Track API costs per tool

#!/usr/bin/env python3
# track-costs.py

import json
import sys

event = json.load(sys.stdin)
tokens = event.get('metadata', {}).get('tokens', 0)
cost_per_token = 0.00001

cost = tokens * cost_per_token

with open('costs.csv', 'a') as f:
    f.write(f"{event['tool_name']},{tokens},{cost}\n")

Use case: Monitor spending

Example 3: Session Initializer (SessionStart)

Purpose: Load user preferences on session start

#!/bin/bash
# init-session.sh

USER_ID=$(echo "$1" | jq -r '.user_id')

# Load user preferences
PREFS=$(cat ~/users/$USER_ID/preferences.json)

# Set environment variables
export USER_PREFS="$PREFS"

echo "Session initialized for user $USER_ID"

Use case: Personalized agent behavior

Example 4: Profanity Filter (UserPromptSubmit)

Purpose: Filter inappropriate user input

#!/usr/bin/env python3
# filter-profanity.py

import json
import sys

event = json.load(sys.stdin)
message = event.get('message', '')

# Check for profanity (simple example)
profanity_list = ['badword1', 'badword2']

for word in profanity_list:
    if word in message.lower():
        # Replace with asterisks
        message = message.replace(word, '*' * len(word))

# Output filtered message
print(json.dumps({'message': message}))

Use case: Content filtering

Event Data Structure

Each hook receives JSON event data:

PreToolUse Event

{
  "event": "pre_tool_use",
  "tool_name": "read_file",
  "parameters": {
    "file_path": "/path/to/file.txt"
  },
  "timestamp": "2025-01-10T10:30:00Z"
}

PostToolUse Event

{
  "event": "post_tool_use",
  "tool_name": "read_file",
  "result": "File content here...",
  "metadata": {
    "tokens": 150,
    "duration_ms": 250
  },
  "timestamp": "2025-01-10T10:30:01Z"
}

SessionStart Event

{
  "event": "session_start",
  "agent_id": "email-summarizer",
  "user_id": "user-123",
  "timestamp": "2025-01-10T10:30:00Z"
}

Configuration

When clicked on canvas:

Edit hook script
Select event type
Configure environment variables
Test hook execution

Best Practices

✅ Do:

Keep hooks fast (< 100ms)
Handle errors gracefully
Log to files, not stdout (except results)
Use async operations when possible
Test hooks thoroughly

❌ Don’t:

Block agent execution with slow hooks
Modify global state unexpectedly
Ignore errors
Use hooks for complex logic (use skills instead)

Common Patterns

Pattern 1: Audit Logging

[PreToolUse Hook] → Log tool call
[Agent executes tool]
[PostToolUse Hook] → Log result + duration

Use case: Compliance, debugging

Pattern 2: Rate Limiting

[PreToolUse Hook] → Check rate limit
If exceeded: Cancel tool execution
If OK: Allow + increment counter

Use case: Prevent API abuse

Pattern 3: Cost Control

[PostToolUse Hook] → Track token usage
If monthly budget exceeded: Alert user

Use case: Budget management

Security Considerations

⚠️ Important:

Hooks run with same permissions as agent
Can access environment variables (including secrets)
Validate hook scripts before use
Avoid executing untrusted code
Use hooks for read-only operations when possible

Next Steps

Sub-agents Node - Specialized agents

← MCPs Node | Agent Node | Sub-agents Node →

Getting Started

Node Types

AI Tools

Hooks Node

Hooks Node

Overview

What are Hooks?

Hook Types

10 Event Types

Hook Structure

Creating Hooks

Hook Examples

Example 1: Tool Call Logger (PreToolUse)

Example 2: Cost Tracker (PostToolUse)

Example 3: Session Initializer (SessionStart)

Example 4: Profanity Filter (UserPromptSubmit)

Event Data Structure

PreToolUse Event

PostToolUse Event

SessionStart Event

Configuration

Best Practices

Common Patterns

Pattern 1: Audit Logging

Pattern 2: Rate Limiting

Pattern 3: Cost Control

Security Considerations

Next Steps

​Hooks Node

​Overview

​What are Hooks?

​Hook Types

​10 Event Types

​Hook Structure

​Creating Hooks

​Hook Examples

​Example 1: Tool Call Logger (PreToolUse)

​Example 2: Cost Tracker (PostToolUse)

​Example 3: Session Initializer (SessionStart)

​Example 4: Profanity Filter (UserPromptSubmit)

​Event Data Structure

​PreToolUse Event

​PostToolUse Event

​SessionStart Event

​Configuration

​Best Practices

​Common Patterns

​Pattern 1: Audit Logging

​Pattern 2: Rate Limiting

​Pattern 3: Cost Control

​Security Considerations

​Next Steps

Hooks Node

Overview

What are Hooks?

Hook Types

10 Event Types

Hook Structure

Creating Hooks

Hook Examples

Example 1: Tool Call Logger (PreToolUse)

Example 2: Cost Tracker (PostToolUse)

Example 3: Session Initializer (SessionStart)

Example 4: Profanity Filter (UserPromptSubmit)

Event Data Structure

PreToolUse Event

PostToolUse Event

SessionStart Event

Configuration

Best Practices

Common Patterns

Pattern 1: Audit Logging

Pattern 2: Rate Limiting

Pattern 3: Cost Control

Security Considerations

Next Steps