Hooks

Synchronous interceptors that run inside an agent's loop at a lifecycle point and can change what happens next — block it, ask for approval, or inject context.

A hook is not a webhook. A webhook is an async notification sent out to your server after the fact. A hook runs synchronously in the loop and its decision is applied before the run continues.

Create a hook

A hook is an event plus an action.

import { Theazo } from 'theazo'

const theazo = new Theazo({ apiKey: process.env.THEAZO_API_KEY })

// Require human approval before every tool call
const hook = await theazo.hooks.create({
  name: 'Approve all actions',
  event: 'pre_tool_use',
  action: { type: 'ask', reason: 'A human must approve tool use for this agent.' },
})

// Or add standing context at the start of every run
await theazo.hooks.create({
  name: 'Date context',
  event: 'session_start',
  action: { type: 'inject_context', message: 'Today is the start of Q3. Prioritize renewals.' },
})

Field	Type	Required	Description
`name`	`string`	yes	Human label, unique within (platform, kind).
`description`	`string`	—	Label; for skills this is the runtime gate (required there).
`enabled`	`boolean`	—	Default true.
`event`	`'session_start' \| 'user_prompt' \| 'pre_tool_use' \| 'post_tool_use' \| 'pre_compact' \| 'subagent_start' \| 'subagent_stop' \| 'stop'`	yes	Agent-run lifecycle point the hook fires at.
`action`	`object \| object \| object`	yes	What the hook does when it fires. v1: block \| ask \| inject_context.

Events

A hook fires at one lifecycle point:

session_start

The agent run begins.

live

user_prompt

A prompt / task is submitted.

live

pre_tool_use

Before the agent invokes a tool.

live

post_tool_use

After a tool completes.

planned

pre_compact

Before long-running context is compacted.

planned

subagent_start

A team member / fleet task spawns.

planned

subagent_stop

A team member / fleet task finishes.

planned

stop

The agent run ends.

planned

Actions

block

Stop the run with a reason. A session_start block is a kill-switch. Reuses Guardrails.

ask

Require human approval before continuing. On pre_tool_use, gates every tool call. Reuses Approvals.

inject_context

Add a message into the prompt at that point (e.g. standing context at the start).

Hooks reuse existing engines rather than adding a new one: block → Guardrails, ask → Approvals.

SDK methods

theazo.hooks.create(opts)HookCreate a hook.

theazo.hooks.list()Hook[]List all hooks on the platform.

theazo.hooks.get(id)HookFetch one by id.

theazo.hooks.update(id, opts)HookUpdate event or action.

theazo.hooks.delete(id)voidDelete. Blocked (409) if still attached.

See also: Instructions, Skills, Approvals.