xz_agent_hooks/
lib.rs

1//! Lifecycle hooks for agent extension hosts.
2//!
3//! This crate is **product-agnostic**: it defines the contract, merge rules, wire
4//! parsing, context buffer, and an ordered registry. Consumers (e.g. xz-code,
5//! writer) discover handlers, map domain tool calls onto [`serde_json::Value`]
6//! arguments, and fire events through [`HookRegistry`].
7//!
8//! # Layers
9//!
10//! | Module | Role |
11//! |--------|------|
12//! | [`contract`] | Event kinds, outcomes, typed merge effects |
13//! | [`registry`] | Ordered registration and `fire` |
14//! | [`wire`] | Claude/Codex-shaped decision JSON + exit codes |
15//! | [`runner`] | [`ExternalHookRunner`] + [`ExternalHookHandler`] adapter |
16//! | [`context`] | [`ContextInjectionBuffer`] for turn-scoped injects |
17//!
18//! # Design rules
19//!
20//! - **No product tool names** hard-coded (no `BashExec`, no TUI).
21//! - **Fail-open** on handler errors (except explicit [`HookOutcome::Deny`]).
22//! - **Deny short-circuits** PreTool chains; **MutateArgs chains** in order.
23//!
24//! # Minimal product integration
25//!
26//! ```ignore
27//! use xz_agent_hooks::{HookEvent, HookRegistry, ExternalHookHandler, ExternalHookRunner};
28//! // 1. implement ExternalHookRunner for your shell/HTTP
29//! // 2. register ExternalHookHandler into HookRegistry
30//! // 3. fire_pre_tool / fire_post_tool around tool execution
31//! // 4. apply PreToolEffect::into_final_args / PostToolEffect::effective_result
32//! ```
33
34#![deny(missing_docs)]
35#![forbid(unsafe_code)]
36
37pub mod context;
38pub mod contract;
39pub mod registry;
40pub mod runner;
41pub mod wire;
42
43pub use context::ContextInjectionBuffer;
44pub use contract::{
45    apply_pre_tool_args, contexts_for_channel, merge_inject, merge_outcomes, merge_permission,
46    merge_post_tool, merge_pre_tool, ContextChannel, HookEvent, HookEventKind, HookOutcome,
47    InjectEffect, MergeMode, MergedEffect, PermissionDecision, PermissionEffect, PostToolEffect,
48    PreToolEffect,
49};
50pub use registry::{glob_match, HookFireResult, HookHandler, HookRegistry};
51pub use runner::{
52    event_json, ExternalHookHandler, ExternalHookRequest, ExternalHookRunner,
53    ExternalHookRunnerError,
54};
55pub use wire::parse_handler_output;
xz_agent_hooks/lib.rs

xz_agent_hooks/
lib.rs
