Just want the answer? A PreToolUse hook is a command Claude Code runs before every tool call. It reads JSON on stdin and blocks the call with exit code 2 or with a JSON deny. It fires in every permission mode. One entry in ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{ "matcher": "Bash|Edit|Write|mcp__.*",
"hooks": [ { "type": "command", "command": "node ~/.acp/govern.mjs", "timeout": 10 } ] }
]
}
}
Install the ACP hook in one command → · what it writes → · free up to 5 agents
Claude Code's hook system is the widest control surface of any coding agent: every built-in tool and every MCP tool, allow, deny, ask, and input rewriting, in every permission mode. It's also the surface people describe wrong most often, usually in the same sentence: "the bypass flag turns hooks off." It doesn't. This is the reference for what hooks are, what they receive, what they can say back, and where they stop.
## Where hooks live
Hooks are declared in settings, and settings have scopes:
| Scope | File | Notes |
|---|---|---|
| User | `~/.claude/settings.json` | Applies to every project on the machine; where the ACP installer writes |
| Project | `.claude/settings.json` | Checked in, shared with the repo |
| Project (local) | `.claude/settings.local.json` | Per-machine overrides, not committed |
| Managed | Organization-deployed settings | Cannot be overridden by the scopes above |
| Plugin | `hooks/hooks.json` in the plugin | Ships with the plugin |
| Skill / subagent | Frontmatter | Scoped to that skill or subagent |
Two managed-settings switches matter for a fleet: `allowManagedHooksOnly` runs only the hooks in the managed scope and ignores the rest, and `disableAllHooks` turns every hook off along with the custom status line. Both are files on the endpoint. That is the honest limit of any client-side control: someone with write access to the config can remove it, which is why [a team rolls hooks out from managed settings](/blog/set-up-permissions-across-your-teams-coding-agents) and keeps the policy decision somewhere the endpoint can't edit.
## The events
Claude Code fires hooks on far more than tool calls. The current list: `SessionStart`, `Setup`, `UserPromptSubmit`, `UserPromptExpansion`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `Notification`, `MessageDisplay`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `DirectoryAdded`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `PreModelSwitch`, `PostModelSwitch`, `Elicitation`, `ElicitationResult`, `SessionEnd`.
For control, two of them do the work. `PreToolUse` runs before a tool executes and can stop it. `PostToolUse` runs after, sees the result, and is where output scanning lives. The rest are observation and lifecycle. `PermissionRequest` is worth knowing: it fires when Claude Code is about to show a permission prompt, which is a different moment from "about to run a tool."
## The PreToolUse contract
**Input**, as JSON on stdin:
```json
{
"hook_event_name": "PreToolUse",
"session_id": "…",
"tool_use_id": "…",
"tool_name": "Bash",
"tool_input": { "command": "git push --force origin main" },
"permission_mode": "default",
"cwd": "/Users/you/repo",
"transcript_path": "/Users/you/.claude/projects/…/session.jsonl"
}
```
`tool_input` is the tool's arguments as the model produced them: a `command` for Bash, a `file_path` and content for Edit and Write, the tool's own schema for MCP tools. `permission_mode` tells the hook what mode the session is in, including `bypassPermissions`, which is how you know hooks run there.
**Output**, by exit code or JSON:
| You return | Effect |
|---|---|
| Exit 0, no stdout | No decision; the normal permission flow applies |
| Exit 2, reason on stderr | Blocked; the reason goes back to the model |
| Exit 0 + JSON `permissionDecision: "deny"` | Blocked, with `permissionDecisionReason` shown to the model |
| Exit 0 + JSON `permissionDecision: "allow"` | Runs without a prompt |
| Exit 0 + JSON `permissionDecision: "ask"` | Forces a prompt, even for an allowed tool |
| Exit 0 + JSON `updatedInput: {…}` | The call runs with the rewritten arguments |
The JSON shape is `{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "…"}}`. A `systemMessage` at the top level is shown to the user. A fourth value, `defer`, exists for print mode under the Agent SDK. The older top-level `decision: block` form is not what the current docs describe; use `hookSpecificOutput`.
**Matchers** narrow which tools a hook sees. Plain names (`Bash`), alternation (`Edit|Write`), regex (`mcp__.*`). MCP tools are named `mcp__