Hooks

What hooks are

Hooks are programmable extension points in the Agent lifecycle. Beyond the platform’s default behavior, the system lets you inject custom logic at 28 key events—change how the Agent behaves without changing platform code.

Hooks vs event triggers

28 hook events

Grouped by lifecycle stage:

Session layer

Agent layer

Message layer

Tool layer

Memory layer

Skill layer

See AgentFlow/src/hooks/ in the codebase for the full list of 28 events.

Five handler types

The same hook event can attach multiple handlers, chained by priority:

Blocking pre-hooks

Pre hooks such as PreToolUse are blocking: if a handler returns block, the original action is rejected.

Typical pattern:

# Example: security audit before tool use
hooks:
  - event: PreToolUse
    handler:
      type: python
      code: |
        if tool_name == "execute_code" and "rm -rf" in tool_args.get("code", ""):
            return {"action": "block", "reason": "Destructive command not allowed"}
        return {"action": "allow"}

Typical scenarios

Scenario 1: Security audit (PreToolUse)

Log every execute_code call before execution; block high-risk commands.

Scenario 2: Cross-session memory guardian (MemoryGuardian)

When a session ends, scan the Ledger, extract fact / preference / error_pattern into LTM so other sessions can reuse them.

Scenario 3: Dynamic skill injection (SkillInjector)

Match the most relevant skills from the current message semantics; skip loading irrelevant ones (saves tokens).

Scenario 4: Compliance on output (PreAssistantMessage)

Before replying, check banned words or format rules; request revision when needed.

Scenario 5: Cost monitoring (SessionStop)

At session end, aggregate tokens, duration, and tool calls; alert when thresholds are exceeded.

Three-tier matching

Hooks do not run globally by default—they match across three tiers:

Related docs

• 📖 Event triggers
• 📖 Memory
• 📖 Skills
• 🧩 Source entry: AgentFlow/src/hooks/