Codex Desktop Project Hooks Not Running? Review Hook Trust

If a project hook works only after you start Codex with --dangerously-bypass-hook-trust, do not keep the bypass flag as the fix. Codex uses two separate trust decisions for project hooks: the project .codex/ layer must be trusted, and each non-managed command hook must be reviewed and trusted in its exact current form.

A fresh Codex Desktop report shows the failure clearly. A project-local SessionStart hook was silently skipped even though the project was trusted. Opening the interactive Codex CLI in the same environment, entering /hooks, and trusting the exact hook definition made the hook run after Desktop restarted. OpenAI's hook documentation now confirms that changed hooks are skipped until their current hash is reviewed.

The safe repair is to inspect the hook source, review the command it will execute, approve that exact definition through /hooks, restart Desktop, and verify the expected behavior in a new task.

Separate Project Trust From Hook Trust

These checks protect different boundaries:

This distinction explains the confusing symptom: the project can look trusted while a changed SessionStart, PreToolUse, or other command hook remains pending review.

Codex discovers project hooks in either .codex/hooks.json or inline [hooks] tables in .codex/config.toml. If a layer contains both forms, Codex merges them and warns at startup. Prefer one representation per layer so the definition you review is easy to identify.

Confirm the Failure Before Changing Anything

Preserve a small, sanitized record:

1. Codex Desktop version and the bundled CLI version shown in the affected task metadata or diagnostics.

2. Operating system and architecture.

3. Hook event, such as SessionStart or PreToolUse.

4. Hook source path, without private usernames or repository details.

5. Whether /hooks marks the definition as trusted, pending review, disabled, or managed.

6. The expected observable result and whether it was absent.

Do not paste the complete hook command into a public issue if it contains local paths, secrets, private endpoints, or repository names. Never include tokens or captured prompt contents.

Before editing the hook, read it as code. A hook is not a passive preference. It is a command that Codex can launch during the agent lifecycle. Review the executable, arguments, matcher, working assumptions, input handling, and any network or filesystem access.

Open the Interactive CLI in the Same Environment

The /hooks command belongs inside an interactive Codex CLI session. It is not a Codex Desktop prompt and it is not a shell command such as codex /hooks.

First open a terminal in the affected repository. Check which Codex home is active.

On macOS or Linux:

printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"

On PowerShell:

if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }

Then start the normal interactive CLI from that repository:

codex

Inside the CLI, enter:

/hooks

If your Desktop setup and terminal use different CODEX_HOME values, an approval recorded by one surface may not affect the other. Do not copy trust state between homes blindly. Identify which home Desktop is actually using and review the hook there.

Review and Trust the Exact Definition

In /hooks, locate the pending hook and confirm:

• the source is the expected user or project configuration;

• the event and matcher are correct;

• the command points to the intended executable or script;

• the script content is the version you just reviewed;

• the command does not expose secrets or grant broader access than the task needs; and

• the hook is not an unfamiliar addition from an unreviewed repository or plugin.

Trust the hook only after those checks pass. Codex records trust against the definition's current hash. Changing the command, matcher, timeout, status message, or other definition data can create a new identity that requires another review.

If the source is unfamiliar, leave it untrusted. Trace where it came from before enabling it. The same habit applies when you audit an agent skill before installing it: executable automation deserves source review, not just a recognizable name.

Restart Desktop and Verify Without a Bypass

After trusting the exact definition:

1. Exit the interactive CLI.

2. Fully quit and reopen Codex Desktop.

3. Open the same project.

4. Create a new task so SessionStart hooks get a fresh lifecycle event.

5. Trigger only the normal event required by the hook.

6. Confirm the hook's expected, non-secret result.

For a SessionStart hook, success may be expected context or a harmless receipt the hook already produces. For a PreToolUse hook, use a bounded, read-only command that matches the hook. Do not invent a destructive canary merely to prove execution.

Do not use --dangerously-bypass-hook-trust for the final validation. OpenAI documents that flag for one-off automation that has already vetted hook sources outside Codex. It skips the persisted review boundary for that invocation, so it cannot prove that normal Desktop trust is repaired.

This app-versus-terminal distinction is also why it helps to understand the Codex App and CLI workflow boundary before comparing results across surfaces.

If the Hook Is Still Skipped

Keep the diagnosis narrow:

1. Reopen /hooks and confirm the exact definition is still trusted.

2. Check whether the hook changed after approval through a formatter, installer, generated path, or repository update.

3. Confirm Desktop and the interactive CLI are using the same project path and CODEX_HOME.

4. Check that the project .codex/ layer itself remains trusted.

5. Confirm the event actually occurs. A SessionStart hook needs a new session; editing an existing task may not retrigger it.

6. Review the hook's own exit behavior and timeout without adding an early catch that hides failures.

7. Compare the installed standalone CLI version with the runtime bundled in Desktop, but do not replace either installation until the mismatch is shown to matter.

If /hooks says the definition is trusted and a fresh Desktop task still skips it, preserve the sanitized version data, event, source location, trust state, expected result, UTC timestamp, and smallest reproduction. Add that evidence to the existing upstream issue instead of opening a duplicate.

Avoid These False Fixes

• Do not make --dangerously-bypass-hook-trust your normal launch command.

• Do not trust a hook without reading the exact command and source.

• Do not edit the hook repeatedly while testing; every definition change can invalidate approval.

• Do not assume project trust automatically approves executable hooks.

• Do not copy config.toml or trust hashes between unrelated Codex homes.

• Do not disable all hook security just because Desktop did not show an in-app review control.

• Do not expose private paths, prompts, or credentials in a public reproduction.

Hook trust is a code-execution boundary. Preserve it while fixing the missing review step.

Monitor the Upstream Fix With Aident Loadout

Aident Loadout can use a connected read-only GitHub issue Action without placing a provider token in your prompt. Give Codex the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then use this bounded prompt:

Check my Aident Loadout account and Vault status. Find a connected read-only GitHub issue Action, inspect its current schema, and preflight it. Return the state, updated time, maintainer-authored comments, linked fixes, and release references for openai/codex issue 37362. Do not create or edit issues, post comments, change labels, change files, or ask me for a provider key.

Success is measurable: one current issue record returns, no GitHub write occurs, and no credential appears in the output. Ready to track the hook trust fix safely? Set up Aident Loadout and run the read-only check.

Sources

• OpenAI Codex hooks documentation

• OpenAI Codex issue 37362: Desktop silently skips changed project hooks pending trust

• OpenAI Codex issue 21639: hooks no longer run after a Desktop update

Refresh this guide when issue 37362 changes state, Codex Desktop adds an in-app hook review path, the /hooks workflow changes, or OpenAI changes the trust behavior for new or edited hook definitions.