Claude Code Hooks: Complete Guide to Automated Policies

Current policy: Hooks are optional automation, not a required policy layer. Claude World toolkits register no toolkit hooks unless a user deliberately enables a documented project integration. Existing project, user, plugin, or managed hooks remain effective until their owner removes them.

Hooks connect lifecycle events to commands or other supported handlers. That makes them powerful, but it also places code directly in the path of an interactive session. The best default is therefore simple: begin with no hooks and add only the smallest automation that cannot be expressed more clearly elsewhere.

Hooks, guidance, permissions, and CI are different tools

• Guidance describes the desired way of working while leaving room for judgment.
• Skills package reusable procedures that Claude or the user can select when relevant.
• Native permissions decide which tools and operations the runtime may use.
• CI validates repository outcomes at a clear delivery boundary.
• Hooks react automatically to lifecycle events.

Do not recreate permissions or CI inside hidden hook scripts. Do not turn every recommendation into an enforced event handler.

Decision sequence

Ask these questions in order:

1. Can a short instruction in CLAUDE.md communicate the intent?
2. Is this a reusable workflow that belongs in a Skill?
3. Can the user or CI run the command at an explicit checkpoint?
4. Does the action truly have to run automatically on a lifecycle event?
5. Is the added latency and failure mode acceptable to every project user?

Only the fourth answer points toward a hook.

Default operating profile

A low-interference setup has:

• zero toolkit hooks registered globally;
• no hidden deny rules;
• no automatic continuation loop;
• no automatic commit, push, deployment, or destructive action;
• explicit native permission profiles chosen by the user;
• optional project hooks documented next to the project.

Organization-managed policy and pre-existing user configuration may still affect the session. A toolkit must not claim to override those layers.

About stop events

Stop and subagent-stop events exist for lifecycle integration, but they should not be used as default “keep working” switches. A handler that repeatedly rejects completion can trap the agent, consume tokens, and conceal the real state of the task.

Use a visible, voluntary workflow or Skill when the user wants another iteration. Let the session stop normally when acceptance criteria are met or the user asks it to stop.

Project-scoped opt-in

If a hook is justified:

1. Keep its registration with the project that needs it.
2. Describe what data it reads and what command it runs.
3. Make enablement and removal explicit.
4. Bound runtime and output.
5. Prefer observation over mutation.
6. Verify the CLI still works normally with the hook disabled.

Keep toolkit and shared setup Hooks project-scoped. This guide does not install or recommend user-global Hooks. Treat any pre-existing personal registration as separate local configuration: audit it explicitly and remove it unless you intentionally still need it.

Diagnosing a slow or stuck session

Inventory effective hooks across managed, user, project, and local settings. Check for duplicate event registrations, missing scripts, network calls, recursive CLI launches, and handlers that can reject completion. Disable one registration at a time, start a fresh session, and measure the difference.

This audit is especially important when another compatible CLI can reuse Claude configuration: inspect the effective configuration, not just one product’s hook directory.

For supported events and current configuration syntax, read Session 15: Hooks System. For portable agents, skills, and session handoff without mandatory hooks, visit Director Mode Lite.