Hooks #
Hooks let extensions answer turn events.
hook.gleam defines the events and
merge rules. The runtime 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,
the model loop, and
Python reporting.
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 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 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.
Combining verdicts #
A Verdict can block, replace call arguments, add context or notes, or halt the
turn. hook.ask calls every hook in
order. composition.hooks
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.
Python reporting prints inner notes and
context into cell output, making both model-visible.
Synchronous host reporting has a 30-second wait in
host_now. 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
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 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 stops
waiting for the entire helper after 660 seconds. The
SDK helper owner 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.