# What is an agent hook?

Canonical: https://perched.fyi/glossary/agent-hook/
Updated: 2026-10-23

An agent hook is an integration point that runs when a coding agent emits a particular event. Perch uses local hooks to receive supported activity updates.

## An event instead of a screen scan

A hook can report that a session started, a tool ran or a turn finished. Perch turns supported events into session state and recent steps. It does not need to read the terminal display to learn that an event occurred.

The provider decides which events exist and what each hook can do. Cursor’s passive hooks do not expose awaiting-permission status, for example. A hook integration cannot reliably show an event it never receives.


## How Perch connects hooks

Perch shows the proposed agent settings change before connecting, makes a backup and adds its own entries. Remove takes those entries out. Start a new session after connecting so the integration can take effect.


[Connect your first session](https://perched.fyi/guides/getting-started/)

## Related reading
- [What to check when agent status is not updating](https://perched.fyi/guides/agent-status-not-updating/)
- [Perch compatibility: Claude Code, Codex and Cursor](https://perched.fyi/guides/agent-compatibility/)