Hook locations

Where you define a hook determines its scope:

Location	Scope	Shareable
~/.claude/settings.json	All your projects	No, local to your machine
.claude/settings.json	Single project	Yes, can be committed to the repo
.claude/settings.local.json	Single project	No, gitignored when Claude Code saves a setting to it
Managed policy settings	Organization-wide	Yes, admin-controlled
Plugin hooks/hooks.json	When plugin is enabled	Yes, bundled with the plugin
Skill frontmatter	The rest of the session once the skill is invoked. See Hooks in skills and agents	Yes, defined in the skill file
Subagent frontmatter	While that subagent is running	Yes, defined in the subagent file

Cloud sessions on Claude Code on the web don't read your local ~/.claude/settings.json; hooks there come from the repo and from your organization's server-managed settings. In a self-hosted environment, Claude Code also runs the hooks the operator seeded from the runner host's ~/.claude/, and it runs the hooks in the runner image's managed settings file when that file is among the managed sources Claude Code applies, which by default means only when neither server-managed settings nor an MDM-delivered Claude Code policy supplies the managed tier. See what carries over from your setup for which files reach a cloud session.

For details on settings file resolution, see settings.

Hooks from settings files, managed policy settings, and plugins also run inside subagents. When a subagent calls a tool, tool events such as PreToolUse and PostToolUse fire the same configured hooks as in the main conversation, and the input carries the agent_id and agent_type common input fields that identify the subagent.

Enterprise administrators can use allowManagedHooksOnly to restrict which hooks run:

• Your user, project, local, and plugin hooks are blocked. Hooks from plugins force-enabled in managed settings enabledPlugins are exempt
• Claude Code also narrows your statusLine, fileSuggestion, and subagentStatusLine settings to managed settings
• Claude Code also disables plugins with a command source, including plugins force-enabled in managed settings enabledPlugins, unless disableCommandPluginSources is explicitly set to false. command sources require Claude Code v2.1.229 or later
• Claude Code also blocks marketplace headersHelper commands unless disableCommandPluginSources is explicitly set to false, except for a marketplace that managed settings themselves declare

See what runs under allowManagedHooksOnly.

Hook entries merge across settings levels rather than replacing each other: user, project, and local settings add their own hooks without removing managed ones, and the disableAllHooks setting can't disable managed hooks from outside managed settings.

The HTTP hook allowlists apply to hooks from every source, including managed policy settings:

• allowedHttpHookUrls: when defined at any settings level, Claude Code runs an HTTP hook handler only if its URL matches the merged allowlist
• httpHookAllowedEnvVars: when defined, Claude Code interpolates only the environment variables on that list into hook headers