Hooks

Hooks register lifecycle callbacks inside a session. The registration lifecycle is registerHook(), hookCount(), and unregisterHook().

Events

Supported event types are:

pre_tool_use
post_tool_use
generate_start
generate_end
session_start
session_end
skill_load
skill_unload
pre_prompt
post_response
on_error

Registration Example

session.registerHook(
  'release-publish-observer',
  'pre_tool_use',
  { tool: 'bash', commandPattern: 'npm publish|twine upload|cargo publish' },
  { priority: 50, timeoutMs: 1000 },
  () => ({ action: 'continue' }),
);

A handler may return { action: 'continue' }, { action: 'skip' }, { action: 'block', reason }, or null/undefined to continue. Validate the specific event path you depend on before using a hook as a production gate.

Propagation

Delegation and automatic subagent fan-out use the task and parallel_task tools. When a product depends on hook behavior across delegated runs, cover that product path with an integration test.

Management

console.log(session.hookCount());
session.unregisterHook('release-publish-observer');