[DOCS] State whether project-scope hooks are workspace-trust-gated, and what happens to that gate under `--print`

What is unclear

The docs are explicit about two neighbouring things and silent about the one in between.

Documented — the trust dialog is skipped in -p (/docs/en/security, "Additional safeguards"):

Trust verification: First-time codebase runs and new MCP servers require trust verification * Note: Trust verification is disabled when running non-interactively with the -p flag

Documented — project allow-rules fail closed in that state
(/docs/en/permissions#project-allow-rules-and-workspace-trust):

permissions.allow rules and permissions.additionalDirectories entries in a project's .claude/settings.json grant capability, so Claude Code applies them only after you accept the workspace trust dialog for that workspace. Until then, Claude Code reads the rules but doesn't apply them… In non-interactive mode with -p, no dialog appears and the rules stay ignored.

**Undocumented — what happens to project-scope hooks.** The hooks reference page's "Security
considerations" section does not mention workspace trust or -p anywhere. Grepping the full page, the
word "trust" appears only in the footer's "Trust center" link. /docs/en/headless does not mention trust
either.

A hook is a strictly more powerful project-scope capability than an allow-rule — it runs a shell command
rather than widening an allowlist — so a reader who has just been told that allow-rules "stay ignored"
has no basis for guessing which way hooks go, and the page that should say is silent.

Why this is not already covered

• /docs/en/hooks-guide says frontmatter hooks in a project subagent are trust-gated as of v2.1.218,

and that "before v2.1.218, these hooks could run from folders you hadn't trusted". That is the only
place any hooks page mentions trust, and it is scoped to one hook source. It reads as though the
general case is settled somewhere, and it is not.

• #20253 asked for the -p/trust-verification note to be added to the CLI and headless docs. It was

closed by the stale bot on 2026-02-28 without a fix, and headless.md and cli-reference still do not
mention it. This issue is adjacent, not a duplicate: #20253 is about the note's absence from the
headless page; this is about the rule for hooks not existing on any page.

• #31242 proposed "skip project hooks entirely (safe default)" for headless mode, which implies the

author also could not determine the current rule from the docs. Also stale-closed, no maintainer reply.

• #59108 (open) asks for headless control-plane parity in general terms.

What would resolve it

On /docs/en/hooks (Security considerations) and /docs/en/permissions, one sentence each answering:

1. Are hooks declared in a project's .claude/settings.json gated on workspace trust, in the same sense

permissions.allow rules are?

1. If they are: what happens in -p, where no dialog can be shown — do they fail closed the way

allow-rules are documented to, or is the gate skipped?

1. If they are not gated: say so plainly on the hooks page, next to the existing warning that hooks "run

with your system user's full permissions". Someone automating claude -p over repositories they did
not author needs that sentence, and right now the only way to find the answer is to test it.

A note in /docs/en/headless pointing at whichever answer applies would close #20253's original request
at the same time.

Environment

claude 2.1.220, Linux. Docs pages fetched 2026-08-02.