One read of Claude Documentationclaude-docs-20261109T180709Z
2 pages moved out of 281 read.
Pages moved
2
significant first
Pages read
281
in this capture
Captured
18:07 UTC
Corpus hash
ab90780796f4
corpus-hash
What this read moved
1-2 of 2third-party/claude-desktop/extensions Changed · +47 / -3 lines
### Run a hook for every user ### Turn off user hooks
from line 472
472472
473473With [Unified Claude](https://claude.com/docs/third-party/claude-desktop/unified-claude.md) on, a Cowork session started from the home screen runs the same hooks as any other Cowork session.
474474
475A `UserPromptSubmit` hook that blocks a prompt stops that turn and shows the hook's reason to the user. When a conversation or session is created, Claude Desktop also sends its first message to your inference provider in a separate request, without tools, to generate the title shown in the sidebar. That request does not pass through plugin hooks, so a first message that a hook blocks still reaches your provider for titling.
475A `UserPromptSubmit` hook that blocks a prompt stops that turn and shows the hook's reason to the user. When a conversation or session is created, Claude Desktop also sends its first message to your inference provider in a separate request, without tools, to generate the title shown in the sidebar. That request does not pass through hooks, so a first message that a hook blocks still reaches your provider for titling.
476476
477Claude Code [managed settings](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) deployed on the device govern these hooks as they do in the Claude Code CLI: `disableAllHooks` turns them off, and `allowManagedHooksOnly` keeps only the hooks those managed settings define.
477Claude Code [managed settings](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) deployed on the device govern these hooks as they do in the Claude Code CLI: `disableAllHooks` turns them off, and `allowManagedHooksOnly` keeps only the hooks that those managed settings define and the hooks of plugins that they install and turn on. See [Turn off user hooks](#turn-off-user-hooks).
478478
479479> [!NOTE]
480480>
481481> To stop users' own [mods](https://code.claude.com/docs/en/plugins/mods/overview) from loading, see [Claude Code mods](https://claude.com/docs/third-party/claude-desktop/code.md#claude-code-mods).
482
483### Run a hook for every user
484
485You can deliver a hook that has to run for every user, such as one that logs each prompt, in a plugin or in Claude Code managed settings:
486
487* **In a plugin**: add the plugin's marketplace to [`allowedPluginMarketplaces`](#configure-the-marketplace) with `installationPreference` set to [`"required"`](#marketplace-installation-preferences). Once Claude Desktop has fetched the marketplace, the plugin's hooks run from the first message of each Cowork session, Chat conversation, and local Code session. In a local Code session, a user can turn them off with [`disableAllHooks`](https://code.claude.com/docs/en/settings-reference#disableallhooks) in their own or a project's Claude Code settings.
488* **In Claude Code managed settings**: write the hooks under the [`hooks`](https://code.claude.com/docs/en/settings-reference#hooks) key of the Claude Code [managed settings](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) on each device, and put any script that they call on the device too, where users can't change it. These hooks run in Cowork sessions, Chat conversations, and local Code sessions with no plugin to install, and a user's `disableAllHooks` doesn't stop them. If these are the device's first Claude Code managed settings, also set `parentSettingsBehavior` to `"merge"` in them, or Claude Code ignores the [managed policy](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy) values that Claude Desktop supplies.
489
490Neither way reaches an [SSH remote session](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#managed-configuration-on-the-remote-host). To run hooks there, deploy Claude Code managed settings [on the host](https://code.claude.com/docs/en/managed-settings#where-each-mechanism-stores-the-policy) in the same way. To turn off users' own hooks there too, deploy the example under [Turn off user hooks](#turn-off-user-hooks).
491
492### Turn off user hooks
493
494To stop users' own hooks, set [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly) to `true` in the Claude Code [managed settings](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) on each device. The setting also stops the hooks of the plugins that Claude Desktop delivers, including plugins from a `"required"` marketplace. Hooks under the managed settings' own `hooks` key keep running, and so do the hooks of a plugin that the same managed settings install and turn on, as this file does:
495
496```json managed-settings.json theme={null}
497{
498 "parentSettingsBehavior": "merge",
499 "allowManagedHooksOnly": true,
500 "extraKnownMarketplaces": {
501 "acme-internal": {
502 "source": { "source": "git", "url": "https://git.acme.example.com/claude-plugins.git" }
503 }
504 },
505 "enabledPlugins": {
506 "prompt-guard@acme-internal": true
507 },
508 "env": {
509 "CLAUDE_CODE_SYNC_PLUGIN_INSTALL": "1"
510 }
511}
512```
513
514Replace `acme-internal` with the `name` in your marketplace's `marketplace.json`, and `prompt-guard` with the plugin's name in that file. Keep the plugin's files in the marketplace repository, under a [relative `source` path](#create-the-marketplace-repository). For other marketplace source types, and for the git credentials that a private repository needs, see [Require a marketplace and its plugins](https://code.claude.com/docs/en/plugins/org#require-a-marketplace-and-its-plugins).
515
516* **Deploy the file to [Claude Code's policy locations](https://code.claude.com/docs/en/managed-settings#where-each-mechanism-stores-the-policy)**, not to [Claude Desktop's](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#where-claude-desktop-reads-configuration-on-a-device). If the device or host already has Claude Code managed settings, add the keys to them and leave their `parentSettingsBehavior` as it is.
517* **Keep `CLAUDE_CODE_SYNC_PLUGIN_INSTALL`.** It makes a session's first message wait until Claude Code has cloned the marketplace and installed the plugin. Without it, Claude Code installs from a git marketplace in the background, for a later session, and the plugin's hooks don't run in a user's first Code sessions or in any new Cowork session or Chat conversation. With it, each new Cowork session and Chat conversation clones the marketplace before its first reply, so keep the repository small.
518* **Keep `extraKnownMarketplaces` even if the marketplace is already in `allowedPluginMarketplaces`.** Claude Code [ignores the copy that Claude Desktop delivers](https://code.claude.com/docs/en/plugins/loading#name-conflicts) of a plugin named in `enabledPlugins`, so without the entry the plugin doesn't load. Claude Code's own clone follows a branch or tag, not the commit that you pinned for Claude Desktop.
519* **If [`userPluginMarketplacesEnabled`](#controlling-user-extensions) is `false`**, or the managed settings already have a `strictKnownMarketplaces` list, also add the same `source` object to [`strictKnownMarketplaces`](https://code.claude.com/docs/en/settings-reference#strictknownmarketplaces) in this file, or Claude Code refuses the marketplace. That list [replaces the one that Claude Desktop supplies](https://code.claude.com/docs/en/managed-settings#let-an-embedding-host-add-policy), which admits [skills-directory plugins](https://code.claude.com/docs/en/plugins/org#keep-skills-directory-plugins-loading).
520
521To confirm the setup, sign in to a device as a user who has never loaded the plugin. Send a first message in a new Cowork session and in a new Code session, and check that your hook ran each time.
522
523> [!WARNING]
524>
525> If Claude Code can't clone the marketplace, the session continues without the plugin and its hooks, and nothing in the conversation says so. A git server that never answers delays the first message by about two minutes, or less if you set [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`](https://code.claude.com/docs/en/env-vars). Put a hook that has to run even when the clone fails, or that users must not be able to change, under the managed settings' `hooks` key.
482526
483527### Hooks on Windows devices without Git for Windows
484528
third-party/claude-desktop/ssh-remote-sessions Changed · +1 / -1 lines
from line 228
228228* [`blockReadsOutsideWorkingDirectories`](https://claude.com/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories), evaluated on the host, so the working directories and the home directory it hides from shell commands are the SSH user's there. Hiding files from shell commands needs the host's sandbox dependencies (next item); on a host without them, or a Windows host, shell reads outside the working directories ask for approval instead, and the file-tool restriction applies regardless. Files a user attaches to a remote session stay readable, except on a Windows host, where the session's plugin files and attachments stay outside the file tools' reach under this key.
229229* `coworkEgressAllowedHosts`, as Claude Code managed settings. The network and filesystem sandbox it produces with `allowedWorkspaceFolders` depends on the host having Claude Code's sandbox dependencies installed (see [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing)). Without them, commands run unsandboxed. See [Sandbox status on the remote host](#sandbox-status-on-the-remote-host) for the message the session shows.
230230* `managedMcpServers`, as the Claude Code managed setting that keeps the session from loading MCP servers that users define in Claude Code's own configuration on the host. The managed servers themselves are reached from the device (see [Where MCP servers run in a remote session](#where-mcp-servers-run-in-a-remote-session)).
231* Plugins from your [allowed marketplaces](https://claude.com/docs/third-party/claude-desktop/extensions.md), copied to the host. A plugin's `hooks` directory is not copied, so its hooks do not run in a remote session, and a plugin whose manifest declares hooks elsewhere is not copied at all.
231* Plugins from your [allowed marketplaces](https://claude.com/docs/third-party/claude-desktop/extensions.md), copied to the host. A plugin's `hooks` directory is not copied, so its hooks do not run in a remote session, and a plugin whose manifest declares hooks elsewhere is not copied at all. To run your organization's hooks on the host, see [Run a hook for every user](https://claude.com/docs/third-party/claude-desktop/extensions.md#run-a-hook-for-every-user).
232232
233233If the host has its own Claude Code managed settings, those take precedence over the policy Claude Desktop supplies, as described under [Interaction with Claude Code's own managed settings](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) for local sessions.
234234