[DOCS] `allowManagedHooksOnly` docs incorrectly say all plugin hooks are blocked

[coygeek]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

Hook loading behavior when allowManagedHooksOnly is enabled and plugins are force-enabled by managed settings

Current Documentation

The settings page currently defines allowManagedHooksOnly as:

allowManagedHooksOnly — (Managed settings only) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks.

It also lists this behavior:

Behavior when allowManagedHooksOnly is true:

• Managed hooks and SDK hooks are loaded
• User hooks, project hooks, and plugin hooks are blocked

The hooks page repeats the same rule:

Enterprise administrators can use allowManagedHooksOnly to block user, project, and plugin hooks.

At the same time, the plugins page already documents that marketplace plugins force-enabled by managed settings are a special managed case:

Marketplace plugins force-enabled by managed settings are the only exception and cannot be overridden.

What's Wrong or Missing?

Claude Code v2.1.101 changed allowManagedHooksOnly so plugin hooks from plugins force-enabled by managed settings still run.

The current docs are now incorrect because they say plugin hooks are categorically blocked. That misses the managed-plugin exception and makes it unclear which hooks enterprise admins should expect to execute.

This is especially confusing for organizations that use managed settings to force-enable approved plugins:

• the settings and hooks docs imply those plugin hooks will never run
• the plugins docs already describe force-enabled plugins as a managed exception
• there is no single place that explains how these rules combine

Suggested Improvement

Update the settings and hooks docs to clarify the exception, for example:

• user hooks and project hooks are blocked
• ordinary user-enabled plugins are blocked
• plugin hooks from plugins force-enabled by managed settings still run because they are part of the managed configuration

A short matrix or example would help administrators understand which hook sources remain active when allowManagedHooksOnly is true.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Context
https://code.claude.com/docs/en/settings	allowManagedHooksOnly definition and hook behavior list currently say plugin hooks are blocked
https://code.claude.com/docs/en/hooks	Repeats that allowManagedHooksOnly blocks plugin hooks
https://code.claude.com/docs/en/plugins	Already documents force-enabled marketplace plugins as a managed-settings exception

Total scope: 3 pages affected

Source: Claude Code v2.1.101 release notes

Improved plugin hooks from plugins force-enabled by managed settings to run when allowManagedHooksOnly is set

[coygeek]

Issue #46387 Verification

Title: [DOCS] allowManagedHooksOnly docs incorrectly say all plugin hooks are blocked
Issue Date: 2026-04-10
Verification Date: 2026-04-10
Status: RESOLVED
Submission Mode: Draft only (manual review required)

---

Issue Summary

This issue reports that the allowManagedHooksOnly documentation incorrectly stated that plugin hooks were categorically blocked, even though Claude Code v2.1.101 changed the behavior so hooks from plugins force-enabled by managed settings still run. The report identified the settings page, hooks page, and plugins page as needing consistent clarification.

---

Verification Results

Claim 1: The settings page definition for allowManagedHooksOnly still says plugin hooks are categorically blocked

Status: RESOLVED

At https://code.claude.com/docs/en/settings, line 173 now defines allowManagedHooksOnly as:

"Only managed hooks, SDK hooks, and hooks from plugins force-enabled in managed settings enabledPlugins are loaded. User, project, and all other plugin hooks are blocked."

Verdict: The settings reference no longer says all plugin hooks are blocked. It explicitly documents the managed-plugin exception.

---

Claim 2: The settings page behavior list still says plugin hooks are categorically blocked

Status: RESOLVED

At https://code.claude.com/docs/en/settings, lines 428-432 now document the full behavior of allowManagedHooksOnly = true:

• Managed hooks and SDK hooks are loaded
• Hooks from plugins force-enabled in managed settings enabledPlugins are loaded. This lets administrators distribute vetted hooks through an organization marketplace while blocking everything else.
• User hooks, project hooks, and all other plugin hooks are blocked

Verdict: The settings page now includes a combined rule summary that explains exactly which hook sources remain active and which are blocked.

---

Claim 3: The hooks page still repeats the outdated rule that plugin hooks are blocked without exception

Status: RESOLVED

At https://code.claude.com/docs/en/hooks, line 182 now states:

"Enterprise administrators can use allowManagedHooksOnly to block user, project, and plugin hooks. Hooks from plugins force-enabled in managed settings enabledPlugins are exempt, so administrators can distribute vetted hooks through an organization marketplace."

Verdict: The hooks page no longer repeats the outdated categorical statement. It now includes the same managed-plugin exception.

---

Claim 4: The plugins page documents force-enabled marketplace plugins as a managed-settings exception

Status: RESOLVED

At https://code.claude.com/docs/en/plugins, line 284 states:

"Marketplace plugins force-enabled by managed settings are the only exception and cannot be overridden."

Verdict: The plugins page still documents the managed-settings exception, and that wording is now consistent with the settings and hooks pages.

---

Claim 5: The v2.1.101 release notes confirm the behavior change that triggered this issue

Status: RESOLVED

At https://code.claude.com/docs/en/changelog, line 34 in the v2.1.101 entry states:

"Improved plugin hooks from plugins force-enabled by managed settings to run when allowManagedHooksOnly is set"

Verdict: The changelog confirms the reported behavior change, and the current documentation now matches it.

---

Current State

Claim	Status
Settings reference for allowManagedHooksOnly documents the managed-plugin exception	RESOLVED
Settings behavior list explains which hook sources are loaded vs blocked	RESOLVED
Hooks page includes the managed-plugin exception	RESOLVED
Plugins page documents the managed-settings exception	RESOLVED
Changelog confirms the v2.1.101 behavior change	RESOLVED

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/settings
  • Line 173: allowManagedHooksOnly definition includes hooks from plugins force-enabled in managed settings
  • Lines 428-432: Hook configuration section explains which hook sources are loaded and blocked when allowManagedHooksOnly is true
• URL: https://code.claude.com/docs/en/hooks
  • Line 182: Hooks page states that force-enabled managed plugins are exempt
• URL: https://code.claude.com/docs/en/plugins
  • Line 284: Plugins page documents that force-enabled marketplace plugins are the exception
• URL: https://code.claude.com/docs/en/changelog
  • Line 34: v2.1.101 release note documents the managed force-enabled plugin hook behavior

---

Conclusion & Recommendation

Primary Concern: The docs previously described allowManagedHooksOnly as blocking plugin hooks without clarifying the exception for plugins force-enabled by managed settings.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current settings, hooks, and plugins documentation consistently describe the managed-plugin exception, and the v2.1.101 changelog confirms that this is the intended behavior. The documentation issue reported in #46387 no longer exists in the current docs.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.