Provide a supported way for local IDE/wrapper installers to request trust for installed hooks

What version of Codex CLI is running?

0.129.0

What platform is your computer?

Darwin 25.3.0 arm64 arm

What terminal emulator and version are you using (if applicable)?

Orca terminal, running Codex CLI inside Orca

What issue are you seeing?

I maintain a local IDE/wrapper integration that runs Codex CLI and installs Codex hooks into ~/.codex/hooks.json so the wrapper can observe session/tool/turn lifecycle events.

After hook trust enforcement was added, those wrapper-installed hooks do not run until the user manually opens /hooks and approves each hook entry. In our case this blocks wrapper integration entirely until the user reviews several hooks by hand. The same review wall returns whenever the wrapper updates its hook command (e.g. install path moves between dev/prod, or an upgrade changes the wrapper script).

The issue is not that the trust gate is wrong. The problem is that there does not appear to be a supported programmatic way for a non-privileged installer to request user-consented trust for hooks it has installed. The available auto-trusted paths require system/MDM-managed configuration, while the user-writable path ~/.codex/hooks.json always hits manual review.

This isn't theoretical: the trust hash is reproducible from the open-source implementation, so the practical alternative for integrators today is to write Codex's internal trust state directly with [hooks.state."<key>"] trusted_hash = "..." entries in ~/.codex/config.toml. A supported API would be better than having each integrator ship its own copy of that private logic.

Expected: Codex provides a supported CLI/API path for local wrappers to request or complete user-consented trust for an already-installed hook entry.

Actual: wrappers either require the user to manually approve every installed hook in /hooks, or they edit Codex's internal trust state directly.

What steps can reproduce the bug?

Thread id: not applicable.

1. Install or run Codex 0.129.0 or newer.
2. Add an unmanaged hook to ~/.codex/hooks.json.

Example:

``json
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "node /path/to/local-wrapper-hook.js SessionStart"
}
]
}
],
"PreToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "node /path/to/local-wrapper-hook.js PreToolUse"
}
]
}
]
}
}
``

1. Start Codex normally inside a local IDE/wrapper or terminal.
2. Trigger an event covered by the hook, such as starting a session or running a tool call.
3. Observe that the hook does not run because Codex requires manual approval through /hooks.
4. Open /hooks and approve the hook manually.
5. Trigger the same event again and observe that the hook now runs.
6. Change the hook command identity, for example by changing the script path or generated command.
7. Start Codex again and observe that the hook requires manual review again.

This is reproducible with any local wrapper that installs user-level hooks into ~/.codex/hooks.json. The important part is that the installer is user-level and cannot write to system-managed config such as /etc/codex/config.toml without requiring root.

What is the expected behavior?

Codex should provide a supported, stable way for a local installer to request user consent for a hook entry that already exists in Codex's discovered hook set.

For example, a CLI/API along these lines would solve the integrator case:

codex hooks trust request \
  --source ~/.codex/hooks.json \
  --event PreToolUse \
  --command 'node /path/to/wrapper-hook.js PreToolUse' \
  --json

Identifying entries by their content (event + command + optional matcher) rather than positional --group/--handler indices avoids fragility when other tools edit hooks.json between writes and shifts those indices.

Expected properties:

• Idempotent.
• Computes trust using Codex's own current normalization rules.
• Refuses to trust a hook that does not already exist in hooks.json.
• Produces machine-readable output for wrappers.
• Returns enough state for wrappers to surface "pending approval" clearly to users.

If maintainers want an approval command, it should still be user-consented, for example by opening the same Codex-owned confirmation path as /hooks:

codex hooks trust approve --interactive \
  --source ~/.codex/hooks.json \
  --event PreToolUse \
  --command 'node /path/to/wrapper-hook.js PreToolUse' \
  --json

That would avoid an unconditional auto-grant while still giving wrappers a supported path, instead of requiring each integrator to reproduce Codex's internal trust hash and edit ~/.codex/config.toml directly.

Additional information

This is not a request to remove or weaken hook trust enforcement. The trust gate is useful, and the current behavior makes sense for manually edited user config.

The gap is specifically for user-installed local tools that wrap Codex and need hooks as an integration surface. Those tools are not system administrators, so requiring /etc/codex or MDM-managed config is not a practical install path. At the same time, asking users to manually approve several generated hooks on every command/path change creates a poor setup and upgrade experience.

We have verified that reproducing Codex's current trust hash and writing to ~/.codex/config.toml works as a workaround, including for versions before 0.129.0 where the trust gate is absent. The concern is that this workaround depends on private implementation details and will likely be copied by multiple wrappers unless Codex exposes a supported trust/request API.

I'm happy to test or send a PR if maintainers are interested in a specific direction.