← All posts

Claude Code Hooks Org Policy for Platform Security

A Claude Code hooks org policy should answer one practical question first: which hooks are allowed to run for the organization, who owns them, and how can security prove they ran? Local hooks are useful, but they are not policy until they are centrally controlled, reviewed, monitored, and backed by repository controls.

For platform and security teams, the shift is from personal automation to enforceable control. Claude Code hooks can run at lifecycle events such as PreToolUse, PostToolUse, UserPromptSubmit, Stop, and ConfigChange. According to Anthropic's Claude Code hooks reference, hooks can be shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents. That makes them powerful enough to stop risky actions, but also powerful enough to create a new execution path that needs governance.

The useful mental model is simple: treat hooks as both enforcement and executable code. The same hook that blocks a dangerous command can also run with the user's permissions if it is a command hook. Anthropic warns that command hooks execute shell commands with full user permissions, including access to files the user can access. That means hook policy belongs in the same conversation as endpoint management, code review, telemetry, and supply-chain controls.

Personal hooks are not organization policy

Claude Code supports different settings locations, and the location changes the level of control. User settings are personal. Project settings are shared with a repo. Managed policy settings are controlled by the organization. The distinction matters because hooks from multiple settings levels merge, and managed hooks cannot be disabled by lower-level disableAllHooks, according to Anthropic's hooks documentation.

For an organization, managed settings are the policy layer. Anthropic's settings documentation states that managed settings have the highest precedence, and lower-level settings, including --settings, do not override the same managed key. Managed settings can be delivered through server-managed settings, MDM or OS policy, file-based managed-settings.json, or a Windows HKCU fallback.

That gives security teams a concrete path: define the hooks the organization requires, ship them through a managed channel, and monitor whether they are registered and executed. The managed-only control allowManagedHooksOnly is especially important because it restricts which hooks run. Without that kind of control, local and project hooks remain developer convenience, not organizational enforcement.

Related reading: Claude Code hooks and permission controls.

What should the policy cover?

A good Claude Code hooks org policy does not start with a pile of scripts. It starts with control ownership.

  • Hook source: which hooks are allowed from user, project, local, flag, policy, or plugin sources.
  • Hook type: whether a hook may run shell commands, call an HTTP endpoint, use MCP, call an LLM prompt, or dispatch a subagent.
  • Lifecycle event: which events may enforce hard blocks, especially PreToolUse, PermissionRequest, ConfigChange, and Stop.
  • Review path: who approves hook code, dependencies, endpoint destinations, and changes to deny logic.
  • Telemetry: what gets logged, where it goes, how long it is retained, and who reviews failures or bypass attempts.
  • Rollback: how a bad hook is disabled without leaving developers blocked during an incident.

In practice, PreToolUse is the event teams reach for when the rule must be enforced before damage can happen. The research brief notes practitioner patterns around blocking secrets, destructive commands, wrong package managers, risky paths, and production-impacting actions. Treat those examples as patterns, not vendor-backed controls. The specific rule still needs local threat modeling and testing.

Use the right policy layer for the surface

Device-managed settings are necessary, but they are not enough for every Claude Code surface. Anthropic's managed settings documentation says official file paths include macOS /Library/Application Support/ClaudeCode/managed-settings.json, Linux and WSL /etc/claude-code/managed-settings.json, and Windows C:\Program Files\ClaudeCode\managed-settings.json. Those paths help with managed laptops, workstations, and some development environments.

Cloud is different. Anthropic-hosted cloud and Cowork sessions do not read device MDM or file policy, according to the same managed settings documentation. If your developers use those surfaces, server-managed policy is required for coverage. If the control needs to inspect prompts, tool-call responses, or uploaded file text across Claude, Claude Code, Cowork, and other Enterprise products, the research brief points to inference hooks as a separate enterprise beta better suited to that layer.

Layer Best fit Main caveat
User or project hooks Developer automation and repo-local workflows Not sufficient for organization-wide enforcement
Managed settings Device and session policy controlled by the organization Rollout depends on endpoint or settings delivery
Server-managed settings Cloud and Cowork coverage where device policy is absent Some hook or env policy changes may need developer approval or next start
Inference hooks Prompt, tool-response, and uploaded-file inspection across enterprise products Separate beta surface, not a replacement for local execution controls
CI and repository controls Final guardrails for committed changes Too late for some local actions, but essential for shared code

Related reading: coding agent sandbox choices for Docker, microVMs, and devcontainers.

Telemetry turns hooks into auditable controls

A hook that blocks locally but leaves no audit trail is hard to defend as an enterprise control. Claude Code can export OpenTelemetry metrics, events, and logs, and Anthropic says admins can configure telemetry through managed settings.

The research brief highlights two important events. claude_code.hook_registered records configured hooks at session start and includes the hook source, such as user, project, local, flag, policy, or plugin. hook_execution_complete records execution results, blocking counts, duration, output sizes, managed_only, and source. Those fields are exactly the kind of evidence a platform team needs when moving from "we shipped a hook" to "we can see policy behavior across the fleet."

Telemetry should also shape hook design. Denial messages become part of the developer and model experience. The research brief notes an anecdotal community warning that verbose denial reasons can add recurring token and context cost. The safer pattern is concise denial text, a stable policy identifier, and a link to internal documentation.

Do not skip hook code review

The biggest mistake is treating hook policy as configuration only. Command hooks are executable code. HTTP hooks create network dependencies. MCP hooks extend the tool surface. LLM prompt hooks and subagents can alter behavior in ways that are harder to reason about than a shell denylist.

That changes the review bar. A hook bundle from a community repository may show useful demand for org-wide policy enforcement, but it is not automatically vetted security software. Before enterprise rollout, review provenance, pin versions, test failure modes, inspect dependencies, confirm telemetry, and document rollback.

Also verify behavior on the exact Claude Code version you deploy. The research brief notes a historical issue where lower-level disableAllHooks reportedly bypassed managed hooks, while current docs state lower-level settings cannot disable managed hooks. The lesson is not that the current docs are wrong. The lesson is that enforcement assumptions should be tested in the deployed version before security depends on them.

A practical policy checklist

Use this as a starting checklist for turning local hooks into enforceable organization policy.

  • Classify hooks by purpose: block, warn, log, enrich, or notify.
  • Keep hard stops in deterministic controls such as hooks or permissions, not only in advisory instructions.
  • Use managed settings for organization-owned Claude Code configuration.
  • Use allowManagedHooksOnly where the goal is to restrict hooks to managed sources.
  • Use server-managed settings for Anthropic-hosted cloud and Cowork coverage.
  • Consider inference hooks separately for enterprise prompt and content inspection use cases.
  • Require code review for command hooks, endpoint changes, MCP calls, dependencies, and deny logic.
  • Export telemetry and alert on hook registration gaps, execution failures, unexpected sources, and blocking spikes.
  • Backstop local enforcement with CI, branch protection, CODEOWNERS, SAST, and normal review workflows.
  • Write rollback steps before rollout, not during a broken developer session.

The answer is not to ban local creativity. Developers will keep writing useful hooks, and project teams will keep finding workflow-specific rules. The organization policy layer should make the boundary clear: personal hooks may improve workflow, but managed hooks define the minimum control plane. For platform and security teams, that is the line between helpful automation and enforceable policy.

Get started

Deploy your fleet.

Put a fleet of sandboxed agents to work on your own infrastructure, provisioned in seconds and watched live from one console.

Get started →

Admin-provisioned · Self-host in one command · Your data never leaves your VM