Research: find a repeatable path to Codex hook trust for Desktop/CLI users

[jsirish]

Context

Issue #47 closed 2026-08-25 with a "not wiring" decision: Codex hooks were found to
require a persisted trust grant with "no verified non-interactive path." That
conclusion turned out to be too pessimistic — later the same day, a real interactive
CLI session (codex -p qwen, answering Codex's ordinary "do you trust this
directory?" prompt) granted hook trust as a side effect, persisted as a
trusted_hash (content hash) in that profile's config layer
(~/.codex/qwen.config.toml's new [hooks.state] block). Verified: headless
codex --profile qwen exec then fired real hooks with zero special flags.

Since trust is a content hash, it's portable. Manually copying that same
[hooks.state] block into the base ~/.codex/config.toml — the file Codex
Desktop reads exclusively (no --profile mechanism) and bare codex (no -p flag)
also reads — made automatic capture work there too. Confirmed live, twice, in two
real projects (~/Sites/rocklineind mid-real-work, ~/Sites/dynamicagency-essentials
a clean isolated test): extensive PostToolUse/UserPromptSubmit capture, correct
redaction, no issues.

The problem

This fix only exists because one machine's specific state (a -p qwen profile
that happened to get trust-reviewed once) could be copied elsewhere. There's no
repeatable, documentable path yet for a new throughline user to get here:

1. Does a fresh install ever get an interactive hook-review prompt at all, or did
   this only happen because of something specific to how -p qwen was invoked?
   Several already-trusted base-config projects (predating this fix) show general
   directory trust with zero hook review ever bundled in — is that because
   throughline's hooks weren't available/installed yet at the time those grants
   happened, or because Desktop/base-config's trust flow genuinely never offers hook
   review the way the CLI-under-a-profile flow did?
2. plugin_hooks was set to true in the base config's [features] table as part
   of this fix, at the same time as the [hooks.state] copy — confounded.
   Neither ~/.codex/qwen.config.toml nor any other profile file ever had
   plugin_hooks set explicitly, yet the original interactive grant worked anyway —
   suggesting the flag may default to on for interactive/TUI use (only off for
   headless codex exec, per Wire and verify automatic capture hooks on Codex CLI (currently skills-only) #47's original finding). Isolate which of the two
   changes actually mattered for Desktop.
3. Is hand-writing [hooks.state] entries a safe, durable thing to rely on, or does
   it bypass an intended human-review step in a way that could be considered misuse,
   break silently on a future Codex update, or get invalidated by something we don't
   understand yet about how these hashes are validated?
4. If a genuinely fresh interactive session (never-before-opened project, base
   config, plugin_hooks on) does offer hook review on its own — what does that
   flow actually look like, and can it be turned into a documented one-time setup
   step for the README instead of a manual TOML edit?
5. If it does not — is there a legitimate, non-hacky way to request this from
   Codex (a real CLI subcommand, a documented config key), or is the manual copy
   genuinely the only lever available right now?

What to do

Research, not implementation yet. Needs controlled, isolated tests (change one
variable at a time, unlike this session's discovery) — probably in a scratch
CODEX_HOME to avoid repeatedly mutating the real machine config. Once the actual
mechanism is understood:

• Decide whether this becomes a documented manual setup step, a scripted one-time
  fix, or stays undocumented/unsupported
• Revisit Wire and verify automatic capture hooks on Codex CLI (currently skills-only) #47's "not wiring" framing in the README/promo site if a real, repeatable
  path is found
• If none of this is safe/durable enough to recommend, document that conclusion too
  so a future session doesn't have to re-derive it

References

• Issue Wire and verify automatic capture hooks on Codex CLI (currently skills-only) #47 (closed, original investigation): Wire and verify automatic capture hooks on Codex CLI (currently skills-only) #47
• reference_codex_plugin_gotchas and project_throughline_infrastructure memory
  files (this project's own memory store) have the full mechanism as understood so
  far

[jsirish]

Upstream research (2026-08-25)

Searched openai/codex's own issue tracker, source, and changelog. This is a
known, actively-discussed upstream gap, not something we discovered in
isolation:

• openai/codex#21615 — a
  wrapper-tool maintainer hit this exact problem and states directly: "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." This corroborates our manual [hooks.state] copy as
  the known stopgap technique, not a fragile hack. They're requesting a real
  codex hooks trust request subcommand - still open, unimplemented.
• #37362 /
  #35306 — confirm Desktop's
  trust flow has no hook-review UI at all, matching what we found empirically.
  Documented workarounds there: codex exec --dangerously-bypass-hook-trust once,
  or the in-TUI /hooks slash command to trust the exact definition, after
  which Desktop picks it up on restart. We never tried /hooks - worth testing, it
  may be a cleaner sanctioned path than raw config editing.
• #32491 (Windows, v0.144.1,
  still open) — persisted trust sometimes ignored by headless codex exec without
  the bypass flag regardless. Contradicts what we confirmed working on macOS
  0.149.0 - likely platform/version-specific, but a real caveat: our result isn't
  guaranteed universal.
• #21901 (closed, user error) -
  no evidence hand-writing [hooks.state] is inherently unsafe when the TOML is
  correct.
• v0.149.0's own changelog lists #39047 Skip plugin hook loading when hooks are disabled and #39296 Enable MCP tool hooks in Codex sessions - plugin-hook
  support is actively under construction in the exact version we tested, not
  stable. Anything we document should be version-pinned and flagged for
  re-verification on Codex updates.

No official docs exist anywhere for [hooks.state], plugin_hooks, or a supported
non-interactive trust grant.

Recommendation: document the manual [hooks.state] copy in the README as an
explicit advanced/unsupported step, version-pinned to Codex v0.149.0, rather than
inventing our own upstream issue - #21615 already is the exact ask. Test /hooks
first; it may replace the manual copy with something closer to sanctioned. Not
pursuing a PR against openai/codex ourselves - out of scope for throughline.

[jsirish]

Definitive finding (2026-08-25, later same day)

Full resolution. Ran genuinely clean tests: reverted the base ~/.codex/config.toml
to its pre-session state (no [hooks.state], no plugin_hooks, back to
gpt-5.6-terra/OpenAI), then tested two brand-new, never-before-seen project
directories from scratch - one via Codex CLI, one via Codex Desktop.

Codex CLI: opening a fresh project interactively (bare codex, no profile, no
special flags) shows a native "Hooks need review" dialog automatically - "5
hooks are new or changed. Hooks can run outside the sandbox after you trust them,"
with options to review individually, trust all, or continue without trusting.
Selecting "Trust all and continue" persisted a real [hooks.state] grant into the
base config and automatic capture started working immediately - confirmed via the
actual buffer file content (prompt + bash command entries, correct timestamps).

Codex Desktop: opening the same kind of fresh project and sending a real message
showed no dialog at all - trust was granted silently ([hooks.state] went from
0 to 5 entries, project added to the trusted list) and capture started working
immediately. Confirmed via real buffer content: the actual session's bash commands,
an MCP tool call, even Desktop's own internal "generate project suggestions" prompt

• captured automatically, zero manual steps.

Conclusion: automatic capture works out of the box on both platforms, with
throughline installed via the normal codex plugin marketplace add /
codex plugin add path. No manual config editing, no named profiles, no
workarounds ever needed. Every earlier "it doesn't work" result in this
investigation (sohnmanufacturing, the blank new-chat folder, the various headless
codex exec tests) was explained by stale/contaminated trust state accumulated from
this session's own manual edits, not any real platform limitation.

Codex CLI vs. Desktop do differ in one real way: CLI asks explicitly (a genuine
one-time interactive confirmation); Desktop grants trust silently with no user-facing
confirmation at all. Worth noting in docs as a real platform difference, not a bug.

Superseded: the "Advanced: enabling automatic capture (unsupported)" section
added in PR #53/#54 - it solved a problem that turned out not to exist on a
genuinely fresh setup. Rewriting the README now to reflect this. Also revisiting
#47's practical framing ("not wired" is still technically true of the manifest -
no hooks key declared - but the functional takeaway that Codex users don't get
automatic capture is now wrong).

Closing this issue - the research question is answered.

[jsirish]

Resolved - see the comment above with the definitive finding.