---
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

The TypeScript, Python, Go, Java, Rust, Ruby, C#/.NET, and C++ CLI-backed wrappers support the same current CLI notification families. String-event SDKs use normalized snake-case names; Java exposes corresponding typed records. The native Swift SDK has its own event transport and should be treated as a separate contract.

| Event | When it fires | Key fields |
|---|---|---|
| turn_start | A new reasoning turn begins | turnId, 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, output, success |
| permission_request | The CLI needs user approval | requestId, tool, description |
| file_modified | A tool created, modified, or deleted a file | filePath, changeType, toolId |
| error | A runtime or transport error occurred | message, recoverable |

## Complete CLI hook notification set

The CLI-backed wrappers now expose all 16 hook notifications as typed events instead of dropping them into a generic fallback.

| Normalized event | What it reports |
|---|---|
| hook_pre_tool | A tool is about to run, including its name and arguments. |
| hook_post_tool | A tool completed, including success, output, and duration. |
| file_modified | A CLI hook reports a created, modified, or deleted path. |
| hook_pre_prompt | The CLI accepted an instruction and its mentioned files. |
| hook_post_response | A response completed with usage, tool-call count, and duration. |
| hook_session_error | The active session reports an error and optional context. |
| hook_stop | The runtime stop hook reports final usage and duration. |
| hook_session_start | A startup, resume, or clear session lifecycle begins. |
| hook_session_end | A session ends because of quit, clear, exit, or error. |
| hook_subagent_stop | A subagent completes or fails. |
| hook_permission_request | A hook observes the tool action awaiting permission. |
| hook_notification | A configured notification hook emits a typed message. |
| hook_context_compacted | Context was compacted, including usage and cropped-message counts. |
| hook_context_overflow | Context overflow recovery cropped messages. |
| hook_context_warning | Context use crossed the warning threshold. |
| hook_context_critical | Context use crossed the critical threshold. |

## MCP and learning notifications

| Normalized event | What your host should do |
|---|---|
| mcp_invoke_request | Review an MCP tool invocation request and respond through the SDK's MCP response API. |
| mcp_tools_changed | Refresh the MCP tool catalog exposed by the host UI. |
| learn_progress | Render progress while the CLI analyzes, loads, evaluates, generates, or updates learned material. |

C#/.NET currently names the first normalized string `mcp_invocation_request`; its typed `McpInvocationRequestEvent` carries the same CLI notification. Unknown or malformed newer notifications remain available through each wrapper's unknown-event fallback instead of being discarded.

## Stream events

Every SDK provides a streaming prompt method that yields events. These examples demonstrate the same event-loop shape in a representative set of SDKs; use the language reference for its native event type names.

## 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.
-   Pre-action hook notifications arrive before their matching action; post-action hook notifications include the completed result.
-   Unknown notification fallbacks preserve the original RPC method and payload so a newer CLI does not silently lose data.

## 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.