<!-- source: https://deepwiki.com/qhkm/zeptoclaw/3.5-hooks-system -->

# Hooks System

- src/audit.rs
- src/cli/common.rs
- src/kernel/gate.rs
- src/lib.rs
- src/safety/chain_alert.rs
- src/safety/mod.rs
- src/security/shell.rs
- src/tools/mod.rs

The hooks system provides config-driven interception points in the agent loop that fire before, after, and during tool execution failures. Hooks enable logging, blocking, and notification actions based on tool name and channel patterns, allowing runtime control over tool behavior without modifying code.

For tool security policies based on agent mode and tool categories, see [6.3 Agent Mode Policies](https://github.com/qhkm/zeptoclaw/blob/2c743d31/6.3 Agent Mode Policies) For broader safety mechanisms including injection detection and leak scanning, see [6.2 SafetyLayer Components](https://github.com/qhkm/zeptoclaw/blob/2c743d31/6.2 SafetyLayer Components)

## Purpose and Design

The hooks system operates as a rules engine evaluated at three points in the tool execution lifecycle:

1. before_tool — Evaluated before the approval gate and tool execution. Can log or block execution src/hooks/mod.rs 5
2. after_tool — Evaluated after successful tool completion. Can log or send notifications src/hooks/mod.rs 6
3. on_error — Evaluated when a tool returns an error. Can log or send notifications src/hooks/mod.rs 7

Each hook point contains a list of rules (`HookRule`) evaluated in order [src/hooks/mod.rs76-79](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L76-L79) Rules match tool names and channels via glob patterns and perform one of three actions: `Log`, `Block`, or `Notify` [src/hooks/mod.rs60-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L60-L70)

**Sources:** [src/hooks/mod.rs1-79](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L1-L79)

## Architecture Overview

### Hook Evaluation Pipeline

The following diagram illustrates how the `HookEngine` intercepts the standard `AgentLoop` execution flow.

**Diagram: HookEngine Integration Flow**

```

```

**Sources:** [src/hooks/mod.rs170-267](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L170-L267) [src/agent/loop.rs1373-1412](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/loop.rs#L1373-L1412)

## Configuration Structure

### HooksConfig Schema

The hooks configuration is defined in `HooksConfig` [src/hooks/mod.rs132-151](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L132-L151) and embedded in the main `Config` [src/config/types.rs90-91](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L90-L91):

```

```

**Sources:** [src/hooks/mod.rs132-151](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L132-L151) [src/config/types.rs90-91](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L90-L91)

### HookRule Schema

Each hook rule is defined by `HookRule` [src/hooks/mod.rs76-113](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L76-L113):

**Sources:** [src/hooks/mod.rs76-113](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L76-L113)

### HookAction Enum

Three actions are supported [src/hooks/mod.rs60-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L60-L70):

**Sources:** [src/hooks/mod.rs60-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L60-L70)

## Execution Model

### Rule Evaluation Order

Rules are evaluated in the order they appear in the configuration. For `before_tool` hooks [src/hooks/mod.rs269-351](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L269-L351):

1. Log rules — Always execute without short-circuiting.
2. Block rules — First matching rule returns immediately with HookResult::Block(message) .
3. Notify rules — Always execute without short-circuiting.

For `after_tool` and `on_error` hooks, all matching rules execute in order (no blocking possible) [src/hooks/mod.rs372-452](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L372-L452)

**Sources:** [src/hooks/mod.rs269-452](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L269-L452)

### Pattern Matching

#### Tool Matching

The `HookRule::matches_tool` method checks if a rule applies to a given tool name [src/hooks/mod.rs117-119](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L117-L119):

- Exact match : "shell" matches "shell" only.
- Wildcard : "*" matches all tools.

#### Channel Matching

The `HookRule::matches_channel` method checks if a rule applies to a given channel [src/hooks/mod.rs121-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L121-L125):

- Exact match : "telegram" matches "telegram" only.
- Empty list : Matches all channels (default permissive).

**Sources:** [src/hooks/mod.rs117-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L117-L125)

## Integration Points

### Agent Loop Integration

Hooks are evaluated at three points in the agent loop's tool execution path. This is implemented in `AgentLoop::process_message` and its tool handling subroutines.

**Diagram: AgentLoop Hook Sequence**

```

```

**Sources:** [src/agent/loop.rs1373-1412](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/loop.rs#L1373-L1412) [src/agent/loop.rs1741-1756](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/loop.rs#L1741-L1756)

### HookEngine Construction

The `HookEngine` [src/hooks/mod.rs170-191](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L170-L191) is constructed from the configuration and optionally wired with a `MessageBus` for `notify` actions:

```

```

In the agent loop, the engine is created once per agent instance and reused across all tool calls [src/agent/loop.rs1361-1364](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/loop.rs#L1361-L1364):

```

```

**Sources:** [src/hooks/mod.rs170-191](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L170-L191) [src/agent/loop.rs1361-1364](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/loop.rs#L1361-L1364)

## Notify Action Routing

The `notify` action sends outbound messages via the `MessageBus` to alert users or external systems.

### Target Resolution

The `emit_notify` method [src/hooks/mod.rs218-267](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L218-L267) resolves the target:

1. rule.channel — If set, overrides the current tool call's channel src/hooks/mod.rs 198-203
2. rule.chat_id — If set, overrides the current tool call's chat_id src/hooks/mod.rs 204-209
3. Fallback — Uses the current tool call's channel and chat_id.

### Message Publishing

The message is published synchronously via `try_publish_outbound` [src/hooks/mod.rs256-259](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L256-L259):

```

```

**Sources:** [src/hooks/mod.rs193-267](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L193-L267)

## Code Entities Reference

### Key Types

**Sources:** [src/hooks/mod.rs60-180](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L60-L180)

## Safety and Auditing Context

While Hooks provide a manual, rule-based way to monitor tools, ZeptoClaw also includes automated safety mechanisms that complement hooks:

- Taint Tracking : Prevents sensitive data from flowing into dangerous "sinks" (e.g., shell tools) src/kernel/gate.rs 157-168
- Tool Chain Alerting : Detects suspicious sequences of tool calls, such as filesystem_write followed by shell_execute src/safety/chain_alert.rs 12-25
- Audit Chain : Records all tool invocations and security blocks in an immutable hash chain for forensic analysis src/audit.rs 147-185

**Sources:** [src/kernel/gate.rs157-168](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L157-L168) [src/safety/chain_alert.rs12-25](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L12-L25) [src/audit.rs147-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/audit.rs#L147-L185)

## Environment Overrides

The hooks system supports a single environment variable override:

**Sources:** [src/config/mod.rs258-260](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L258-L260)

## Testing

The hooks module includes comprehensive unit tests covering:

- Rule matching logic src/hooks/mod.rs 518-574
- Engine evaluation src/hooks/mod.rs 576-716
- Notify action integration src/hooks/mod.rs 730-822

**Sources:** [src/hooks/mod.rs464-822](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hooks/mod.rs#L464-L822)
