agent-hooks

agent-hooks manages shell hooks, which are user-provided scripts that run at fixed points in an agent's lifecycle to block a dangerous action, rewrite an input or outbound message, inject context into the model, or warn the user. Scripts can be written in any language and communicate with the agent over a simple JSON-on-stdin, JSON-on-stdout protocol, and are managed through the /hooks command.

Reach for hooks when a user wants the agent to automatically enforce a rule or react to an event without being asked each time, for example blocking destructive rm -rf bash via a pre_tool_call hook, preventing a private key from being pushed to a chat channel via on_outbound_message, logging every tool call via post_tool_call, or forcing a redo when an answer fails a quality check via on_stop. One-off checks are not hooks; hooks are for recurring, automatic lifecycle enforcement.

The skill can install and activate a hook end to end with zero user copy-paste: it writes the script, adds the config entry, and calls a loopback self-approve API that enables the master switch, approves the script for every event it is wired to, and hot-mounts it live without a restart. A critical rule is that both the YAML command and the approval call must use an absolute path under /data/workspace, because a relative path resolves against the server cwd and fails open, silently protecting nothing. The standard install therefore copies templates into /data/workspace/hooks/.

Internally a hook fires only when two gates hold, namely the master switch is on and the event-command pair is approved with the script's recorded mtime, but the self-approve API flips both in one shot so the user never sees them. The skill documents twelve lifecycle events (such as on_user_message, pre_tool_call, pre_llm_call, on_response_end, on_stop, on_outbound_message, and on_completion_claim) and distinguishes the three end-of-turn levers for fixing output, since on_response_end can only rewrite while on_stop and on_completion_claim can force a redo.