SDK Hook Examples

Examples of SDK-side hook callbacks using hookCallbacks in QueryOptions.

Audit logger

Log every tool call:


import { query, type HookCallback } from '@protolabsai/sdk';
 
const auditLogger: HookCallback = async (input, toolUseId) => {
  const data = input as { tool_name?: string };
  console.log(
    JSON.stringify({
      timestamp: new Date().toISOString(),
      event: 'PreToolUse',
      tool: data.tool_name,
      toolUseId,
    }),
  );
  return {};
};
 
const session = query({
  prompt: 'Refactor the auth module',
  options: { hookCallbacks: { PreToolUse: auditLogger } },
});

Security gate

Block dangerous commands:


const securityGate: HookCallback = async (input) => {
  const data = input as {
    tool_name?: string;
    tool_input?: Record<string, unknown>;
  };
 
  if (data.tool_name === 'Bash') {
    const cmd = String(data.tool_input?.command ?? '');
    if (cmd.includes('rm -rf') || cmd.includes('sudo')) {
      return {
        shouldSkip: true,
        message: 'Destructive or privileged commands are not allowed',
      };
    }
  }
 
  return {};
};
 
const session = query({
  prompt: 'Clean up temporary files',
  options: { hookCallbacks: { PreToolUse: [auditLogger, securityGate] } },
});

PostToolUse result validator

Interrupt if a tool output contains unexpected content:


const resultValidator: HookCallback = async (input) => {
  const data = input as { tool_response?: string };
  if (data.tool_response?.includes('FATAL')) {
    return {
      shouldInterrupt: true,
      message: 'Fatal error detected in tool output — stopping agent',
    };
  }
  return {};
};
 
const session = query({
  prompt: 'Run the test suite',
  options: {
    hookCallbacks: { PostToolUse: resultValidator },
  },
});

Multiple callbacks per event

Pass an array — callbacks execute in order. First shouldSkip or shouldInterrupt short-circuits the rest:


const session = query({
  prompt: '...',
  options: {
    hookCallbacks: {
      PreToolUse: [auditLogger, securityGate],
      PostToolUse: resultValidator,
    },
  },
});

Callback return values

Field	Type	Effect
`shouldSkip`	boolean	Skip this tool call (PreToolUse only)
`shouldInterrupt`	boolean	Stop the agent immediately
`suppressOutput`	boolean	Suppress tool output from the conversation
`message`	string	Feedback sent to the agent

Return {} to let the tool proceed normally.

Supported events

PreToolUse, PostToolUse, Stop, Notification, SubagentStop.

See Guides → Use Hooks for shell/HTTP hook configuration.