Hooks

A hook is a handler zidane calls at a step of the turn loop. Most hooks only observe. Mutable hooks can block a tool call, substitute a result, or rewrite messages and the system prompt. The behavior options for budgets, dedup and tool concurrency are at the end of this page.

This page is for code that builds an agent. An extension uses ctx.hooks.on to observe these hooks, and ctx.hooks.intercept in place of the mutable ones: tool.call for tool:gate, tool.result for tool:transform, and so on (extension hooks).

How hooks work#

Hooks run on hookable. zidane awaits handlers in registration order. They share one context object per firing, so the last write to a field wins.

agent.hooks.hook('tool:gate', (ctx) => {
  if (ctx.name === 'shell' && String(ctx.input.command).includes('rm -rf')) {
    ctx.block = true
    ctx.reason = 'dangerous command'
  }
})

Hook reference#

Turn and stream#

Tool and MCP#

MCP connection and skills#

Session and background tasks#

Decisions#

Every other hook context carries ctx.decide, bound to the active run. It never throws (decisions).

Budgets and guards#

Provider, cache and repair#

cache:break and cache:drift fire only with the cache telemetry module installed (installCacheBreakLogger). systemSections lists skillsCatalog, toolsCatalog, mcpInstructions, rules (contextSections.rulesBlock), hostStatic or hostDynamic (the rest of the prompt above or below SYSTEM_PROMPT_BOUNDARY). The logger keeps its baseline per session id (sessionBaseline, default on, top-level runs only), so a rebuilt agent's first request is compared with the previous agent's last one. replay:done comes from durable-runtime adapters, never from the core loop.

Sub-agent bubble events#

spawn:queued, spawn:before, spawn:complete and spawn:error fire on the parent for its own spawn calls. These child events re-fire on the parent with a child: prefix plus childId and depth:

• stream text, thinking, end, error, retry and server-tool events,
• tool:dispatched / before / after / error / cancelled,
• validation:reject, repeat-guard:exceeded, background:*, turn:after and artifact:recorded.

The child's own spawns arrive as child:spawn:*. To gate and rewrite a child's tool calls (child:tool:gate and siblings), see observing children. An extension's tool.call and tool.result interceptors already see sub-agents' calls (extension hooks).

Examples#

// Substitute a no-op instead of a repeat call (block wins if both are set).
agent.hooks.hook('tool:gate', (ctx) => {
  if (ctx.name === 'todowrite' && (ctx.runToolCounts.todowrite ?? 0) > 0)
    ctx.result = 'Already recorded; no-op.'
})

// Redact secrets before the model sees a tool result.
agent.hooks.hook('tool:transform', (ctx) => {
  if (typeof ctx.result === 'string')
    ctx.result = ctx.result.replace(/\b(API_KEY|TOKEN|PASSWORD)\s*=\s*\S+/gi, '$1=<redacted>')
})

// Truncate large MCP results (sizes vary too much for a built-in default).
agent.hooks.hook('mcp:tool:transform', (ctx) => {
  if (ctx.outputBytes <= 8192 || typeof ctx.result !== 'string')
    return
  const tail = ctx.result.slice(-4096)
  ctx.result = `…(${ctx.outputBytes - tail.length} bytes truncated from head)…\n${tail}`
})

// Answer a hallucinated tool name instead of erroring.
agent.hooks.hook('tool:unknown', (ctx) => {
  if (ctx.name === 'EnterPlanMode') {
    ctx.result = 'EnterPlanMode is not available. Use shell to draft a plan as comments.'
    ctx.suppressError = true
  }
})

// Drop old turns past a soft cap.
agent.hooks.hook('context:transform', (ctx) => {
  const KEEP_RECENT = 30
  if (ctx.messages.length > KEEP_RECENT) {
    const trimmed = [ctx.messages[0], ...ctx.messages.slice(-KEEP_RECENT + 1)]
    ctx.messages.splice(0, ctx.messages.length, ...trimmed)
  }
})

// Append to the system prompt on later turns.
agent.hooks.hook('system:transform', (ctx) => {
  if (ctx.session && ctx.turn > 1)
    ctx.system += `\n\n## Reminder: keep responses concise after turn ${ctx.turn}.`
})

// Observe.
agent.hooks.hook('turn:after', (ctx) => { /* ctx.turn, ctx.usage, ctx.message; always fires */ })
agent.hooks.hook('stream:text', (ctx) => { /* ctx.delta, ctx.text */ })
agent.hooks.hook('agent:done', (ctx) => { /* AgentStats, cumulative incl. children */ })

zidane has no built-in handler for the mcp:tool:transform, tool:unknown and context:transform cases above. Most production agents need one of each.

Output and context budgets#

All options in this and the next sections live on behavior.

Read dedup and read-before-edit guard#

Tracking and dedup are independent: with dedupReads off, requireReadBeforeEdit still works. Keys are canonical absolute paths, so read_file('src/x') and edit('./src/x', …) match.

Tool dispatch#

Each ToolDef has isConcurrencySafe?: boolean | ((input) => boolean), default false.

Safe calls run in parallel, up to behavior.maxConcurrentTools (default 10). An unsafe call waits for in-flight calls, runs alone, then releases the queue. Results come back in submission order.

Set maxConcurrentTools: 1 to run calls one at a time when debugging.

behavior.dedupTools dedups any tool through a hasher keyed by canonical name. A returned string is a cache key, and equal keys replay the earlier result. undefined skips dedup for that call. Never list tools with side effects or changing output.

behavior: {
  dedupTools: {
    todowrite: input => JSON.stringify(input),
    run_query: (input) => {
      const q = typeof input.query === 'string' ? input.query.trim().toLowerCase() : undefined
      if (!q || q.includes('now()') || q.includes('random()')) return undefined  // non-cacheable
      return q
    },
  },
}

behavior.toolBudgets caps calls per tool per run. 'steer' lets the call run, then nudges the model once to commit. 'block' refuses with Blocked: <reason>.

behavior: {
  toolBudgets: {
    todowrite: { max: 6, onExceed: 'steer' },
    run_query: { max: 3, onExceed: 'block' },
  },
}

behavior.repeatGuard (off in the SDK, on in chat profiles) breaks streaks of identical consecutive calls to shell and read_file. It blocks the Nth call with a pivot suggestion (blockThreshold, default 4, or 6 for read_file). It aborts the run at the Mth (abortThreshold, default 8, or 12 for read_file).

behavior.thinkingDecay lowers the thinking budget on later turns:

behavior: {
  thinkingBudget: 8192,
  thinkingDecay: { afterTurn: 5, floor: 1024 },  // turns 1-5: 8192, 6+: 1024
}

With prompt caching on, use this step form over a per-turn function. The thinking budget is part of Anthropic's cache key, so each new value re-bills the full prefix.

Reference#

• Extension hooks: hooks.on and the interceptors, for extensions.
• zidane/agent
• zidane/types