feat(plugin): ship Codex-native activity hooks

[worktrunk-bot]

What this does

This is the "support" counterpart to #3363. Where #3363 suppresses Codex's auto-discovery of the shared Claude hooks/hooks.json (setting hooks: {} so nothing loads), this PR ships Codex-native activity hooks so wt list shows 🤖/💬 for Codex sessions the same way it does for Claude Code, OpenCode, and Gemini. Meeting users where they are: #3362 (comment).

Both PRs fix the original bug (Claude-branded events surfacing in Codex sessions). They differ only in direction — a maintainer picks one.

How

The Codex manifest (.codex-plugin/plugin.json) now carries an inline hooks object — a Codex-tailored hooks file embedded directly in the manifest, rather than a path or an absent key:

"hooks": {
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set 🤖 || true" }] }],
    "PermissionRequest": [{ "matcher": "", "hooks": [{ "type": "command", "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set 💬 || true" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set 💬 || true" }] }]
  }
}

Two deliberate choices, both verified against Codex's source (98d28aab):

• Inline object, not a path or absent key. Claude and Codex share one payload dir. An absent hooks key makes Codex auto-discover hooks/hooks.json — the Claude file — and surface Claude events (the Codex plugin hooks should not rely on compatibility with Claude #3362 bug). An inline object takes Codex's Some(Inline) branch in resolve_manifest_hooks, which overrides discovery — so only these Codex-native events fire, and there's no second file to collide with the Claude one. (This is the same override mechanism fix(plugin): suppress Codex auto-discovery of Claude hooks #3363 uses with an empty inline object.)
• $PLUGIN_ROOT, not $CLAUDE_PLUGIN_ROOT. Codex exports both to hook commands (discovery.rs#L230-L232 — PLUGIN_ROOT native, CLAUDE_PLUGIN_ROOT an OOTB-compat alias). Using the native var keeps everything Claude-branded out of a Codex session, directly addressing the "poor UX to see anything about Claude while using Codex" concern.

The event set is Codex's HookEventsToml vocabulary: UserPromptSubmit → 🤖 (working), PermissionRequest/Stop → 💬 (waiting). Codex gained a Stop turn-end event after codex-cli 0.130.0 (the version whose lack of a turn-end event motivated the original removal in #2786), so 🤖 correctly returns to 💬 when a turn completes — the transition the old "no turn-end event" limitation lacked.

Known limitation (documented, not a regression)

Codex's HookEventsToml has no SessionEnd/session-exit event, so there's no hook to clear the marker when a Codex session exits. The resting state after a normal exit is 💬 (set by the last Stop), which lingers until the next session or a manual wt config state marker clear. This is the same class of limitation already documented for Claude ("Status persists after user interrupt"). If Codex later adds a session-exit event, wiring a marker clear handler is a one-line addition.

Files

• plugins/worktrunk/.codex-plugin/plugin.json — inline Codex-native hooks object
• plugins/worktrunk/CLAUDE.md — rewrote the "Codex ships no hooks" limitation into "Codex activity hooks", documenting the inline/$PLUGIN_ROOT rationale and the no-SessionEnd tradeoff
• src/commands/config/codex.rs — install now hints that markers appear in wt list
• src/cli/config.rs — Codex plugin --help no longer claims markers are Claude-only
• docs/content/claude-code.md (+ synced skill mirror) — capability table and prose updated
• tests/integration_tests/config_show.rs — asserts the inline hooks object exists, defines exactly the Codex-native events, and uses $PLUGIN_ROOT (never the Claude alias)

Testing

test_codex_plugin_metadata_is_valid_json, the test_help snapshots, and test_docs_are_in_sync pass locally; cargo fmt/clippy clean.

The hooks' end-to-end behavior depends on Codex runtime and isn't verifiable from CI — a maintainer should confirm against a live Codex session before merge (marker appears on prompt, returns to 💬 at turn end, persists after exit as documented).

Closes #3362 (as an alternative to #3363).

[ofek]

Is it possible for Claude to have a dedicated plugin subdirectory like Codex or does it lack interoperability/support for conventions like the AGENTS.md situation?

[worktrunk-bot]

Good question — the two tools aren't symmetric here, and it turns out a dedicated subdir wouldn't buy what you might expect.

Can Claude take a dedicated manifest subdir like .codex-plugin/? In this layout, no. We verified end-to-end against claude-cli 2.1.x that with the marketplace source pointing at ./plugins/worktrunk, Claude wants plugin.json at the plugin root — adding a .claude-plugin/ wrapper inside that dir makes it fail with "Plugin not found". Codex is the opposite: it requires its manifest in the .codex-plugin/ wrapper. So they pull in opposite directions, and the repo carries a per-tool pointer at the root for each (.claude-plugin/marketplace.json, .agents/plugins/marketplace.json, gemini-extension.json).

But — and this is the key point — a manifest subdir wouldn't isolate the payload anyway. Codex's .codex-plugin/ only relocates the manifest; both tools still share the same plugins/worktrunk/ payload (hooks/, skills/, the wt.sh shim). That shared payload is exactly the source of #3362: Codex auto-discovers the Claude hooks/hooks.json by convention and surfaces Claude-branded events. So the collision is a payload-sharing problem, not a manifest-location one — which is why the fix here lives in the manifest's hooks key (an inline object that overrides Codex's auto-discovery) rather than a directory split. Splitting manifests into per-tool subdirs wouldn't have separated the hooks/skills that actually collide.

On the AGENTS.md interoperability angle: yes, it's the same class of situation. There's no shared cross-tool convention — each tool hardcodes its own loader/manifest path with no fallback, and Claude reads CLAUDE.md rather than AGENTS.md. That lack of a common convention is precisely why the repo has to keep three separate root pointers and single-source the shared skills//wt.sh behind them (see plugins/worktrunk/CLAUDE.md for the full layout rationale).

If any of those tools grows real cross-tool interop (a shared manifest convention, or Codex payload isolation), the layout could collapse to fewer pointers — but today the three-pointer + shared-payload split is the minimal thing that works against all three real CLIs.

[ofek]

Could the structure of this repo be improved at all to make the Claude plugin config less "prominent" and isolate what is possible?

[worktrunk-bot]

Good instinct, and it splits cleanly into "forced by the CLIs" vs. "actually improvable."

What's forced (can't isolate):

• plugin.json at the plugin root. Claude hardcodes the manifest at the plugin root and rejects a .claude-plugin/ wrapper inside the source dir (verified against 2.1.x — you get "Plugin not found"). Codex is the mirror image: it requires its manifest under .codex-plugin/. So the visible asymmetry — Codex neatly tucked in a subdir, Claude bare at the root — is the two loaders pulling in opposite directions, not a repo choice. There's no arrangement that tucks both away.
• CLAUDE.md. Claude reads CLAUDE.md, not AGENTS.md, with no fallback — so that filename is fixed too.
• The shared payload (wt.sh, skills/). These are genuinely common to all three tools and single-sourced deliberately. Splitting them per-tool to make Claude "less prominent" would mean duplicating the shim and the skills, which trades a cosmetic win for real drift risk. That's the wrong direction.

What this PR actually unlocks (a real improvement):

Before this PR, plugins/worktrunk/hooks/hooks.json had to sit at that conventional path because it was the file everyone's auto-discovery would find — which is exactly the #3362 bug (Codex discovering the Claude file). Now that the Codex manifest carries inline hooks that override discovery, that hooks/hooks.json is consumed by Claude only (Gemini uses its own repo-root hooks/hooks.json).

Claude's hooks key is a path, not a convention lookup — "hooks": "./hooks/hooks.json". So post-#3364 you could rename/relocate it to something explicitly Claude-scoped (e.g. a claude-hooks.json, or a Claude-only subdir) and repoint that key. Two concrete wins:

1. It stops a future tool's convention-based auto-discovery from grabbing the file the way Codex did — the collision class that caused Codex plugin hooks should not rely on compatibility with Claude #3362 disappears structurally rather than being overridden per-tool.
2. It reads as "this file is Claude's," reducing the impression that the bare root config is a shared/default thing.

That's the one place isolation is genuinely available today, and it's a byproduct of the override this PR introduces. I'd keep it out of this PR (it's cleanly separable and this one's already scoped to the Codex hooks), but it's a good follow-up for a maintainer to take — the layout rationale lives in plugins/worktrunk/CLAUDE.md if anyone wants to pick it up.

The honest summary: the manifest prominence is fixed by the CLIs, but the hooks payload can now be Claude-scoped, and that's the meaningful isolation lever.

[ofek]

@worktrunk-bot Now that this has been merged, what follow-up items do you have in mind to implement?

[worktrunk-bot]

Three, in rough priority order — one actionable now, two gated on things outside this repo.

1. Claude-scope the shared hooks payload (actionable now, cleanly separable).
This is the isolation lever from the thread above. Before #3364, plugins/worktrunk/hooks/hooks.json had to sit at the conventional path because it was the file everyone's auto-discovery grabbed — the #3362 collision. Now that the Codex manifest carries inline hooks that override discovery, that file is consumed by Claude only (Gemini uses its own repo-root hooks/hooks.json with a BeforeAgent event; Codex no longer touches it). Claude's hooks key in plugin.json is a path ("./hooks/hooks.json"), not a convention lookup, so it can be renamed/relocated to something explicitly Claude-scoped and repointed. Two wins: a future tool's convention-based discovery can't grab it the way Codex did (the collision class disappears structurally instead of being overridden per-tool), and it stops reading as a shared/default config. I'd keep this its own small PR.

2. Confirm the Codex hooks against a live session, then close the loop (gated on a maintainer with Codex).
The end-to-end behavior isn't verifiable from CI — it depends on the Codex runtime. The pre-merge ask still stands post-merge: confirm the marker appears on prompt (🤖), returns to 💬 at turn end, and persists after exit as documented. If any of those don't match, that's a real bug to file rather than a follow-up feature.

3. Wire marker clear on Codex session-exit (gated on upstream).
The documented limitation: Codex's HookEventsToml has no SessionEnd/session-exit event, so the marker rests at 💬 after a normal exit until the next session or a manual wt config state marker clear. If Codex adds a session-exit event, wiring a marker clear handler into the inline manifest is a one-line addition. Nothing to do until upstream ships the event — worth a watch, not work.

The only one worth opening now is (1). Happy to take it if a maintainer wants it — otherwise the layout rationale in plugins/worktrunk/CLAUDE.md has the full context for whoever picks it up.

[ofek]

Go ahead and implement that now while I test this change myself tomorrow.

[worktrunk-bot]

Done — opened #3382.

It renames plugins/worktrunk/hooks/hooks.json → hooks/claude-hooks.json and repoints plugin.json's hooks key, so the file a future tool's convention-based discovery would grab (hooks/hooks.json) is now empty at the plugin root — the #3362 collision class is gone structurally rather than overridden per-tool. wt.sh stays put (Codex/Gemini reference it there), and the inline Codex hooks stay as the functional definition of Codex's markers. Scoped to just item (1); the plugin-layout tests are updated and green. (2) and (3) stay out — gated on the Codex runtime and an upstream session-exit event.

Enjoy testing tomorrow — if the markers don't behave as documented (🤖 on prompt, back to 💬 at turn end, persisting after exit), that's a bug to file rather than a follow-up.