METAGROK
BUILD / trust-project-hooks-in-grok-build

Build

Trust project hooks in Grok Build

trust-project-hooks-in-grok-build

Grant trust so project-scoped hooks (and the project MCP and LSP servers that share the same decision) actually run the first time you open a repo that ships .grok/hooks/*.json. Official Hooks docs state that project hooks require trust before they run: grant it with /hooks-trust in the TUI or by launching with --trust, and the decision is stored in ~/.grok/trusted_folders.toml. That same trust record covers project MCP and LSP servers, which matches how MCP Servers describe project-scoped config that ships with the repo.

What you need

The Grok Build CLI installed, a repository that already contains project hooks under .grok/hooks/ (or vendor hook files Grok reads), and a reason to allow that tree to execute local shell or HTTP hooks — for example a shared PreToolUse safety check the team committed. Neighboring jobs include Use Grok Build hooks for lifecycle automation for writing the JSON, Add MCP servers in Grok Build when the same trust gate unblocks project MCP, and Inspect Grok Build config with grok inspect to confirm hooks and servers loaded after trust. Browse more Build jobs on the Build hub when you are wiring related CLI workflows.

Grant trust for this folder

  1. Open a terminal in the project root that contains the hooks you intend to allow, then confirm the CLI is available on your PATH:
cd /path/to/your-project
grok version
  1. Launch with trust when you want a one-shot headless or TUI session that immediately treats this folder as trusted, because the flag records the decision under ~/.grok/trusted_folders.toml:
grok --trust
  1. Or, if you already started a session and project hooks are waiting, grant trust from inside the TUI with the dedicated command, then reopen or refresh the hooks view so the session picks up the new trust state:
/hooks-trust

Inspect loaded hooks afterward in the /hooks tab of the extensions modal. Personal hooks under ~/.grok/hooks/*.json do not need this folder trust step; only project hooks (and the project MCP and LSP servers tied to the same decision) wait on it.

  1. Verify discovery after trust so you are not debugging a missing matcher that never loaded. From the same cwd, run inspect and confirm the project hook files appear alongside any project MCP servers:
grok inspect
# or
grok inspect --json

What trust covers

The stored folder decision unlocks project hooks and also project MCP and LSP servers for that tree, which matters when a teammate added grok mcp add --scope project servers that write .grok/config.toml in the repo. Revoking or editing trust means updating ~/.grok/trusted_folders.toml (or re-running the trust flow on a clean machine) rather than deleting the committed hook JSON. Hook processes still fail open on crashes and timeouts unless a PreToolUse hook returns an explicit deny, so trust is permission to run the project’s automation rather than a guarantee every script is safe.

Pitfalls

Running grok from a parent directory that is not the trusted folder can leave project .grok/hooks undiscovered or still blocked even though you trusted a sibling path, so always grant trust from the repo root you will work in. Committing hooks without documenting the /hooks-trust step for new clones makes it look like Grok ignores team safety checks. After you change hook JSON, refresh the /hooks tab or start a new session, because trust alone does not reload file contents that changed mid-session.