Crate xz_agent_hooks 

Lifecycle hooks for agent extension hosts.

This crate is product-agnostic: it defines the contract, merge rules, wire parsing, context buffer, and an ordered registry. Consumers (e.g. xz-code, writer) discover handlers, map domain tool calls onto serde_json::Value arguments, and fire events through HookRegistry.

Layers

Module	Role
contract	Event kinds, outcomes, typed merge effects
registry	Ordered registration and fire
wire	Claude/Codex-shaped decision JSON + exit codes
runner	ExternalHookRunner + ExternalHookHandler adapter
context	ContextInjectionBuffer for turn-scoped injects

Design rules

• No product tool names hard-coded (no BashExec, no TUI).
• Fail-open on handler errors (except explicit HookOutcome::Deny).
• Deny short-circuits PreTool chains; MutateArgs chains in order.

Minimal product integration

use xz_agent_hooks::{HookEvent, HookRegistry, ExternalHookHandler, ExternalHookRunner};
// 1. implement ExternalHookRunner for your shell/HTTP
// 2. register ExternalHookHandler into HookRegistry
// 3. fire_pre_tool / fire_post_tool around tool execution
// 4. apply PreToolEffect::into_final_args / PostToolEffect::effective_result

Re-exports

pub use context::ContextInjectionBuffer;

pub use contract::apply_pre_tool_args;

pub use contract::contexts_for_channel;

pub use contract::merge_inject;

pub use contract::merge_outcomes;

pub use contract::merge_permission;

pub use contract::merge_post_tool;

pub use contract::merge_pre_tool;

pub use contract::ContextChannel;

pub use contract::HookEvent;

pub use contract::HookEventKind;

pub use contract::HookOutcome;

pub use contract::InjectEffect;

pub use contract::MergeMode;

pub use contract::MergedEffect;

pub use contract::PermissionDecision;

pub use contract::PermissionEffect;

pub use contract::PostToolEffect;

pub use contract::PreToolEffect;

pub use registry::glob_match;

pub use registry::HookFireResult;

pub use registry::HookHandler;

pub use registry::HookRegistry;

pub use runner::event_json;

pub use runner::ExternalHookHandler;

pub use runner::ExternalHookRequest;

pub use runner::ExternalHookRunner;

pub use runner::ExternalHookRunnerError;

pub use wire::parse_handler_output;

Modules

context

Context injection buffer for hosts that accumulate hook text across a turn.

contract

Hook events, outcomes, and merge semantics.

registry

Ordered hook registration and firing.

runner

External handler abstraction (command / HTTP / in-process).

wire

Parse Claude Code / Codex-shaped hook handler output.