Struct HooksConfig 

pub struct HooksConfig {
    pub cwd_changed: Vec<HookDef>,
    pub file_changed: Option<FileChangedConfig>,
    pub permission_denied: Vec<HookDef>,
    pub turn_complete: Vec<HookDef>,
    pub hook_block_cap: usize,
    pub pre_tool_use: Vec<HookMatcher>,
    pub post_tool_use: Vec<HookMatcher>,
}

Top-level hooks configuration section.

Each sub-section corresponds to a lifecycle event. All sections default to empty (no hooks). Events fire in the order hooks are listed.

Hooks are declared inline in config.toml under the [hooks] table. No separate settings.json or external file is required. Both command and mcp_tool action types are supported for every event.

Examples

[[hooks.pre_tool_use]]
matcher = "Edit|Write"
[[hooks.pre_tool_use.hooks]]
type = "command"
command = "echo pre $ZEPH_TOOL_NAME"
timeout_secs = 5
fail_closed = false

[[hooks.turn_complete]]
type = "mcp_tool"
server = "notifier"
tool = "notify"
[hooks.turn_complete.args]
channel = "desktop"

Fields

cwd_changed: Vec<HookDef>

Hooks fired when the agent’s working directory changes via set_working_directory.

file_changed: Option<FileChangedConfig>

File-change watcher configuration with associated hooks.

permission_denied: Vec<HookDef>

Hooks fired when a tool execution is blocked by a RuntimeLayer::before_tool check.

Environment variables set for Command hooks:

• ZEPH_DENIED_TOOL — the name of the tool that was blocked.
• ZEPH_DENY_REASON — human-readable reason string from the layer.

turn_complete: Vec<HookDef>

Hooks fired after each agent turn completes (#3327).

Runs regardless of the [notifications] config. When a [notifications] notifier is also configured, these hooks share its should_fire gate (respecting min_turn_duration_ms, only_on_error, and enabled). When no notifier is configured, hooks fire on every completed turn.

Use min_duration_ms in a wrapper script or the [notifications].min_turn_duration_ms gate to avoid firing on trivial responses.

Environment variables set for Command hooks:

• ZEPH_TURN_DURATION_MS — wall-clock duration of the turn in milliseconds.
• ZEPH_TURN_STATUS — "success" or "error".
• ZEPH_TURN_PREVIEW — redacted first ≤ 160 chars of the assistant response.
• ZEPH_TURN_LLM_REQUESTS — number of completed LLM round-trips this turn.

hook_block_cap: usize

Maximum number of PreToolUse hook blocks allowed per turn before the turn is ended with a warning message. Counts individual tool blocks — if a tier has N blocked tools, the counter increments by N. Default: 8. Use 0 for no cap (unlimited blocks).

pre_tool_use: Vec<HookMatcher>

Hooks fired before each tool execution, matched by tool name pattern.

Uses pipe-separated pattern matching (same as subagent hooks). Hooks fire before the RuntimeLayer::before_tool permission check — they observe every attempted tool call, including calls that will be subsequently blocked.

Hook serialization within a tier: hooks for tools in the same dependency tier are dispatched sequentially (one tool’s hooks complete before the next tool’s hooks start). Hooks for tools in different tiers may overlap.

Hooks are fail-open: errors are logged but do not block tool execution.

Environment variables set for Command hooks:

• ZEPH_TOOL_NAME — name of the tool being invoked.
• ZEPH_TOOL_ARGS_JSON — JSON-serialized tool arguments (truncated at 64 KiB).
• ZEPH_SESSION_ID — current conversation identifier, omitted when unavailable.

post_tool_use: Vec<HookMatcher>

Hooks fired after each tool execution completes, matched by tool name pattern.

Fires after the tool result is available. Same pattern matching and fail-open semantics as pre_tool_use.

Environment variables set for Command hooks:

• ZEPH_TOOL_NAME — name of the tool that was invoked.
• ZEPH_TOOL_ARGS_JSON — JSON-serialized tool arguments (truncated at 64 KiB).
• ZEPH_SESSION_ID — current conversation identifier, omitted when unavailable.
• ZEPH_TOOL_DURATION_MS — wall-clock execution time in milliseconds.

Implementations

impl HooksConfig

pub fn is_empty(&self) -> bool

Returns true when no hooks are configured (all sections are empty or absent).

Examples

use zeph_config::hooks::HooksConfig;

assert!(HooksConfig::default().is_empty());

Trait Implementations

impl Clone for HooksConfig

fn clone(&self) -> HooksConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HooksConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for HooksConfig

fn default() -> HooksConfig

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for HooksConfig

where HooksConfig: Default,

fn deserialize<__D>( __deserializer: __D, ) -> Result<HooksConfig, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for HooksConfig

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.