xz-agent-hooks 0.1.0

Lifecycle hook contract, ordered registry, and wire parsers for agent extension hosts
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

//! 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
//!
//! ```ignore
//! 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
//! ```

#![deny(missing_docs)]
#![forbid(unsafe_code)]

pub mod context;
pub mod contract;
pub mod registry;
pub mod runner;
pub mod wire;

pub use context::ContextInjectionBuffer;
pub use contract::{
    apply_pre_tool_args, contexts_for_channel, merge_inject, merge_outcomes, merge_permission,
    merge_post_tool, merge_pre_tool, ContextChannel, HookEvent, HookEventKind, HookOutcome,
    InjectEffect, MergeMode, MergedEffect, PermissionDecision, PermissionEffect, PostToolEffect,
    PreToolEffect,
};
pub use registry::{glob_match, HookFireResult, HookHandler, HookRegistry};
pub use runner::{
    event_json, ExternalHookHandler, ExternalHookRequest, ExternalHookRunner,
    ExternalHookRunnerError,
};
pub use wire::parse_handler_output;