---
title: "Safety Gates -- Live Claude Hook Routing"
description: "A fail-closed Claude Code controller with 6 lifecycle events, 35 live hook entries, 20 registered handlers, 15 routed batches, and 37 explicit main-path checks."
---

# Safety Gates -- Live Claude Hook Routing

The old public docs collapsed everything into one flattened gate number. The live Claude controller is more layered than that now.

Current audit of the live Claude system:

| Surface | Live Count |
|---|---:|
| Claude lifecycle events | 6 |
| Live Claude hook entries | 35 |
| AI-controller-owned hook entries | 25 |
| Registered controller handlers | 20 |
| Routed batch aliases | 15 |
| Explicit main-path `pretooluse.py` checks | 37 |
| Top-level hook/runtime files | 61 |
| Top-level hook Python lines | 103,794 |
| `pretooluse.py` lines | 32,785 |
| State-like directories | 24 |

## What Gates Are

Gates are fail-closed checks that run before or after Claude Code acts. The most important path is `PreToolUse`, where Bash, read, web, search, agent, and write calls are routed into different handler batches instead of one slow universal path.

If a gate fails, crashes, or cannot prove the action is safe, edits stop.

## Live Event Wiring

| Event | Claude Entries | Controller-Owned Entries | Purpose |
|---|---:|---:|---|
| `SessionStart` | 6 | 3 | Bootstrap, continuity, memory, plugin patches |
| `UserPromptSubmit` | 5 | 2 | Prompt classification, memory injection, skill routing |
| `PreToolUse` | 10 | 10 | Blocks unsafe tool calls before execution |
| `PostToolUse` | 8 | 6 | Tracks edits, results, learning, and sync |
| `Stop` | 2 | 2 | Blocks unfinished work and writes final learning |
| `PreCompact` | 4 | 2 | Preserves state before context compaction |

## Routed Batch Aliases

The registry defines 15 batch aliases. Bash gets the richest routing because Bash can read, write, deploy, launch browsers, or bypass file tools if left unchecked.

Examples:

| Batch | Handler Count | Includes |
|---|---:|---|
| Full Bash batch | 7 | skill gate, repo boundary, server backup, `pretooluse.py`, RTK rewrite, search strategy, browser swarm |
| Write batch | 3 | skill gate, repo boundary, `pretooluse.py` |
| Agent batch | 5 | skill gate, read gate, `pretooluse.py`, search strategy, search reset |
| Search/read batch | 3 | skill gate, read gate, search strategy |
| Web batch | 2 | skill gate, read gate |

## Main Checks

`pretooluse.py` currently contains 37 explicit main-path checks. The major surfaces are:

- memory acknowledgement before action
- plan-mode authority for code and plan files
- read-only research mutation guard
- canonical source registry
- project analyzer and dependency map gates
- thinking partner and confidence enforcement
- post-failure research
- read-before-edit for config files
- hedging scanner
- bug-resolution tracker
- knowledge-gap research gate
- research persistence
- dependency read verification
- final approval before implementation
- project snapshot and per-file checkpoint backups
- simplification/removal approval
- test-before-deploy
- response-obligation and implementation-dispatch checks

## Maintenance Mode

Maintenance mode is still the supported escape hatch for controller infrastructure work. It is not a silent bypass: the system keeps backup and completion protections active, and the session must return to normal mode when maintenance is done.

## Related

- [Getting Started](https://erebora.org/mantis/docs/getting-started) -- Installation and first run
- [Memory System](https://erebora.org/mantis/docs/memory-system) -- How memory recall works
- [FAQ](https://erebora.org/mantis/docs/faq) -- Common questions about gates
- [Live Documentation](https://erebora.org/mantis/) -- Full product page