---
title: "Hooks and Events Code Agent SDK"
source: https://docs.autohand.ai/agent-sdk/concepts/hooks-and-events
---

# Hooks and Events

The Autohand Code Agent SDK streams every meaningful moment in an agent run as an event. You can observe these events for logging, react to them to update a UI, or intercept them with hooks to change behavior.

## Events are the SDK contract

The Autohand CLI runs the reasoning loop. The SDK opens a JSON-RPC or stdio connection to the CLI and receives a stream of events. Your application never needs to host the model or implement tool calling itself; it only needs to understand the events.

This design keeps SDKs thin, consistent across languages, and safe. The CLI enforces permissions and file access; the SDK observes and responds.

## Common event types

Event names are stable across all SDK languages. The payload shape is normalized so the same handler logic works in TypeScript, Python, Go, Java, and Swift.

| Event | When it fires | Key fields |
|---|---|---|
| turn_start | A new reasoning turn begins | turn, iteration |
| message_update | The model streams a token or fragment | delta, message |
| tool_start | A tool is about to run | toolName, args |
| tool_end | A tool has finished | toolName, result, duration |
| permission_request | The CLI needs user approval | requestId, tool, action, resource |
| hook_invoked | A configured shell hook ran | event, command, exitCode |
| session_start | A session was created | sessionId, project |
| session_end | The session closed | sessionId, duration |
| error | An unrecoverable error occurred | message, context |

## Stream events

Every SDK provides a streaming prompt method that yields events. The following examples show the same logic in TypeScript and Python.

### TypeScript

### Python

## Intercept behavior with hooks

In addition to observing events, you can register SDK hooks that run before or after specific events and optionally veto the action. This is useful for guardrails, audit logging, and custom integrations.

A hook handler returns an object. Return `{ allow: true }` or `undefined` to proceed. Return `{ allow: false, reason: '...' }` to block the action and surface a message to the model.

## Event ordering guarantees

-   Events for a single turn are delivered in order.
-   `tool_start` always precedes `tool_end` for the same invocation.
-   `permission_request` is emitted before the action is taken. The loop waits until the SDK responds or a timeout occurs.
-   Hook events are emitted after the shell command completes.

## Best practices

-   Handle events asynchronously. Do not block the event stream with network calls unless the event requires a decision, such as permission\_request.
-   Persist important events outside the process. The stream ends when the session closes.
-   Use typed SDK clients when available so event fields are validated at compile time or runtime.
-   Keep hook handlers stateless. The SDK may retry a call if the CLI restarts.