small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs hooks.md
4.9 kB · 93 lines
Markdown
at main

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.