# Hooks Hooks let extensions answer turn events. [`hook.gleam`](../src/albedo/harness/sdk/hook.gleam) defines the events and merge rules. The [runtime](runtime.md) exposes the composed hook to turns and kernel calls. ## Events `Prompted` carries user text before a turn's first model call. `Calling` carries a tool call before execution. `Called` carries the call, output, and start and finish times. Outer model calls report refusals through `Called`. An inner Python call refused before execution raises without that follow-up report. `Stopping` carries the reply and the number of times hooks have held the turn open. See [`hook.Event` and `hook.Call`](../src/albedo/harness/sdk/hook.gleam), [the model loop](../src/albedo/harness/loop.gleam), and [Python reporting](../priv/python/albedo_plugins/hook.py). ## Hook context A hook is a `fn(hook.Context, hook.Event) -> hook.Verdict`. An extension declares one with `HookPlugin`, or sets `hook` on a managed contribution when the hook needs something only preparation supplies, as the agents extension's needs `Preparation.letters`. The host asks both kinds the same way. Its [`hook.Context`](../src/albedo/harness/sdk/hook.gleam) carries the session whose turn asks, the workspace that session loaded, and the hook's own extension's storage handle, bound to that session and limited to the extension's declared capabilities. [`composition.hooks`](../src/albedo/harness/extension/composition.gleam) builds the context with `extension.hook_context` each time it reads the hooks, for the turn's session or for the session of a kernel's report. Read the handle, the session, and the workspace from the context. Do not capture a handle when the hook is prepared: the composition is copied between processes, and a captured handle is copied with it. See [extension storage](extensions.md#extension-storage). ## Combining verdicts A `Verdict` can block, replace call arguments, add context or notes, or halt the turn. [`hook.ask`](../src/albedo/harness/sdk/hook.gleam) calls every hook in order. [`composition.hooks`](../src/albedo/harness/extension/composition.gleam) alone defines that order: extensions in composition order, the harness base first and then the selection in registry order. Within one extension its `HookPlugin` hooks come in plugin order, before its managed contribution's hook. Whether a hook is static or managed never moves it past another extension's hook. Do not reorder hooks elsewhere. The first block, argument replacement, and halt each win in the final verdict. Each hook's replacement updates the event passed to the next hook, even if an earlier replacement already won. Context and notes accumulate. A crashed hook adds a note and otherwise proceeds. `hook.route` handles kernel inner-call reports and returns a halt as a refusal. Outer notes are published to the user by [the model loop](../src/albedo/harness/loop.gleam). [Python reporting](../priv/python/albedo_plugins/hook.py) prints inner notes and context into cell output, making both model-visible. Synchronous host reporting has a 30-second wait in [`host_now`](../priv/python/albedo_cells.py). Asynchronous reporting waits on its host reply without that deadline. Ordinary reporting errors fail open. Inner output is capped at 65,536 Python string characters, not bytes. ## Command hooks The [hooks extension](../src/albedo/harness/extensions/hooks/extension.gleam) reads `$ALBEDO_HOME/hooks.json` and maps events to `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop`. Inner `run`, `files.edit`, and `files.write` calls are named `Bash`, `Edit`, and `Write` for matchers. [`albedo_hook_command.py`](../priv/python/albedo_hook_command.py) runs matching command hooks with JSON on stdin. The default timeout is 600 seconds. Exit status 2 blocks. Other failures and invalid output fail open with a note. Commands run in separate process groups, which the helper kills after completion or timeout. The helper merges results in configuration order and limits additional context. Command hooks are therefore not a fail-closed security boundary. Commands use the session workspace when it exists as a directory, otherwise the helper's inherited working directory. The [hooks extension](../src/albedo/harness/extensions/hooks/extension.gleam) stops waiting for the entire helper after 660 seconds. The [SDK helper owner](../src/albedo/harness/sdk/helper.gleam) sends cancellation when that wait expires or the calling turn dies, then waits up to five seconds for cleanup acknowledgment. The Python helper serializes command creation with cancellation, kills registered groups, and reaps their leaders. Cleanup failure is returned as `StartFailed`. Commands that deliberately leave their registered process groups are outside this guarantee. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Agents](agent-sessions.md) - [Plugins](plugins.md)