Hooks and Events | Autohand Code Agent SDK

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.