Skip to main content

Hook Types Reference

Complete reference for the Agentrix-supported Claude SDK hook types.

Overview​

  • 11 Claude SDK Hooks: From @anthropic-ai/claude-agent-sdk

Import Types​

Claude SDK hooks:

import type {
  PreToolUseHookInput,
  PostToolUseHookInput,
  SessionStartHookInput,
  SessionEndHookInput,
  UserPromptSubmitHookInput,
  StopHookInput,
  SubagentStartHookInput,
  SubagentStopHookInput,
  PreCompactHookInput,
  NotificationHookInput,
  PermissionRequestHookInput,
} from '@anthropic-ai/claude-agent-sdk';

Tool Control Hooks​

PreToolUse​

Trigger: Before each tool execution

interface PreToolUseHookInput {
  hook_event_name: 'PreToolUse';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
}

type PreToolUseResult = {
  decision?: 'approve' | 'block';
  systemMessage?: string;
  hookSpecificOutput?: {
    hookEventName: 'PreToolUse';
    permissionDecision?: 'allow' | 'deny' | 'ask';
    permissionDecisionReason?: string;
    updatedInput?: Record<string, unknown>;
  };
};

PostToolUse​

Trigger: After each tool execution

interface PostToolUseHookInput {
  hook_event_name: 'PostToolUse';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  tool_name: string;
  tool_input: unknown;
  tool_response: unknown;
  tool_use_id: string;
}

type PostToolUseResult = {
  hookSpecificOutput?: {
    hookEventName: 'PostToolUse';
    additionalContext?: string;
    updatedMCPToolOutput?: unknown;
  };
};

Session Lifecycle Hooks​

SessionStart​

Trigger: Agent session begins

interface SessionStartHookInput {
  hook_event_name: 'SessionStart';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  source: 'startup' | 'resume' | 'clear' | 'compact';
}

type SessionStartResult = {
  hookSpecificOutput?: {
    hookEventName: 'SessionStart';
    additionalContext?: string;
  };
};

SessionEnd​

Trigger: Agent session ends

interface SessionEndHookInput {
  hook_event_name: 'SessionEnd';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  reason: string;
}

type SessionEndResult = {};

UserPromptSubmit​

Trigger: User submits a prompt

interface UserPromptSubmitHookInput {
  hook_event_name: 'UserPromptSubmit';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  prompt: string;
}

type UserPromptSubmitResult = {
  hookSpecificOutput?: {
    hookEventName: 'UserPromptSubmit';
    additionalContext?: string;
  };
};

Stop​

Trigger: Agent is stopping

interface StopHookInput {
  hook_event_name: 'Stop';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  stop_hook_active: boolean;
}

type StopResult = {};

SubagentStart​

Trigger: Subagent starts

interface SubagentStartHookInput {
  hook_event_name: 'SubagentStart';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  agent_id: string;
  agent_type: string;
}

type SubagentStartResult = {
  hookSpecificOutput?: {
    hookEventName: 'SubagentStart';
    additionalContext?: string;
  };
};

SubagentStop​

Trigger: Subagent completes

interface SubagentStopHookInput {
  hook_event_name: 'SubagentStop';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  stop_hook_active: boolean;
  agent_id: string;
  agent_transcript_path: string;
}

type SubagentStopResult = {};

Context Management Hooks​

PreCompact​

Trigger: Before context compaction

interface PreCompactHookInput {
  hook_event_name: 'PreCompact';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  trigger: 'manual' | 'auto';
  custom_instructions: string | null;
}

type PreCompactResult = {};

System Event Hooks​

Notification​

Trigger: System notifications

interface NotificationHookInput {
  hook_event_name: 'Notification';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  message: string;
  title?: string;
  notification_type: string;
}

type NotificationResult = {};

PermissionRequest​

Trigger: When permission is needed for a tool call

interface PermissionRequestHookInput {
  hook_event_name: 'PermissionRequest';
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
  tool_name: string;
  tool_input: unknown;
  permission_suggestions?: PermissionUpdate[];
}

type PermissionRequestResult = {
  hookSpecificOutput?: {
    hookEventName: 'PermissionRequest';
    decision: {
      behavior: 'allow';
      updatedInput?: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
    } | {
      behavior: 'deny';
      message?: string;
      interrupt?: boolean;
    };
  };
};

Hook Execution Order​

SessionStart
  ↓
UserPromptSubmit (each message)
  ↓
PreToolUse (each tool)
  ↓
PermissionRequest (if needed)
  ↓
[Tool Executes]
  ↓
PostToolUse (each result)
  ↓
PreCompact (if needed)
  ↓
Stop / SessionEnd

Special:

  • SubagentStart/SubagentStop: When subagents start/complete
  • Notification: On system events