agent-tunnel: investigate in-session >share for Codex via Codex's Claude-compatible plugin hooks

[pchalasani]

Context

For Claude Code, publishing a session is done in-session by typing:

>share --dangerously-skip-permissions my-cool-session

This works because agent-tunnel ships a Claude Code UserPromptSubmit plugin hook (plugins/agent-tunnel/hooks/share_hook.py, registered via hooks.json). When you submit that prompt, the hook fires, receives session_id + cwd + transcript_path, writes the registry, and returns {"decision":"block","reason":"…"} so the prompt is intercepted (never reaches the model) and the handle is printed. That block-and-reply behavior is what makes >share feel like a slash command.

For Codex CLI, PR #102 publishes via the terminal instead: agent-tunnel share --agent codex <name>. There is no in-session >share today.

Why this is worth investigating (it may be achievable)

Codex actually has a Claude-compatible plugin/hook system. On this machine ~/.codex/config.toml contains, e.g.:

[hooks.state."ralph-loop@claude-plugins-official:hooks/hooks.json:stop:0:0"]
trusted_hash = "sha256:…"

i.e. codex loads Claude-plugin hooks.json files and keys them by event (stop here) + a per-invocation trust hash. codex plugin / codex features (hooks is a stable feature) manage this. So an in-session >share for codex is plausibly just a matter of wiring, not a hard "codex can't".

agent-tunnel's share_hook.py already defensively detects a codex-shaped transcript_path and labels the record agent=codex, so if the hook ever fires inside codex it does the right thing.

Open questions to answer

1. Does codex fire a UserPromptSubmit-equivalent hook event (or any pre-turn user-input event)?
2. Does codex honor the {"decision":"block","reason":…} protocol to suppress the prompt and surface a message? (Claude's >share needs this; without it, the >share text would still reach the model.)
3. Does the hook payload include session_id / cwd / codex rollout path (so the hook can register the right session)?
4. What's the install/trust path — publish agent-tunnel to a codex plugin marketplace, or a manual ~/.codex/config.toml hook entry + trust?

Outcome

If (1)–(3) hold, wire the existing share_hook.py into codex (register the plugin/hook, document the trust step) so codex users get the same >share --… my-cool-session in-session shortcut. If codex lacks block-decision support, document agent-tunnel share --agent codex as the permanent codex path.

Refs: PR #102, plugins/agent-tunnel/hooks/share_hook.py (_detect_agent), plugins/agent-tunnel/hooks/hooks.json.

[pchalasani]

Confirmed: codex reuses Claude's plugin/hook machinery — this is small

Inspected the installed native codex binary (@openai/codex-darwin-arm64 0.144.4):

• UserPromptSubmit is a supported hook event (it's a const in codex's hook-event enum, with UserPromptSubmitHookSpecificOutputWire), and codex honors the block/reason decision protocol ("decision", "block", "reason", hookSpecificOutput, additionalContext) — exactly what share_hook.py returns.
• Same env var: the binary references CLAUDE_PLUGIN_ROOT (+ PLUGIN_ROOT, CLAUDE_PLUGIN_DATA), so our hooks.json command ${CLAUDE_PLUGIN_ROOT}/hooks/share_hook.py resolves under codex unchanged.
• Same payload fields: codex's UserPromptSubmit hook input provides session_id, cwd, prompt, transcript_path (plus a codex-specific agent_transcript_path) — the fields share_hook.py already reads.
• Install path: codex plugin marketplace add <local-or-git> then codex plugin add agent-tunnel@<marketplace> (mirrors Claude's marketplace flow), with a per-hook trust hash recorded in ~/.codex/config.toml under [hooks.state].

Remaining work (small)

1. Plugin manifest for codex: codex reads .codex-plugin/plugin.json (Claude reads .claude-plugin/plugin.json). Add a .codex-plugin/plugin.json to plugins/agent-tunnel/ (same content) so codex recognizes it.
2. Payload robustness: verify whether codex populates the rollout path in transcript_path or agent_transcript_path; make share_hook.py's _detect_agent/_config_dir read agent_transcript_path as a fallback. (The defensive codex detection is already there; this just widens the field lookup.)
3. Docs: a "install the >share hook into codex" section (marketplace add + plugin add + trust), noting the same plugin serves both agents.
4. Live test: install into a real codex, type >share payments, confirm it publishes with agent=codex.

Net: the in-session >share is achievable with a .codex-plugin/plugin.json + a one-line payload-field fallback + install docs. No backend changes.

Refs: PR #102.

[pchalasani]

Implemented in PR #102 — and verified live

Turned out to be exactly as scoped, and it works end-to-end:

• Added plugins/agent-tunnel/.codex-plugin/plugin.json and registered the plugin in the codex marketplace (.agents/plugins/marketplace.json).
• share_hook.py now reads codex's agent_transcript_path payload field (that's where codex puts the rollout on UserPromptSubmit), so in-session detection records agent=codex.
• No backend change; the existing ${CLAUDE_PLUGIN_ROOT}/hooks/share_hook.py command runs unchanged under codex.

Live test (throwaway CODEX_HOME): codex plugin add agent-tunnel@cctools-codex-plugins, then >share codextest inside a codex exec session → codex printed hook: UserPromptSubmit Blocked (the prompt was intercepted, never reached the model — same as Claude) and the registry recorded the session with agent=codex and the correct cwd / config_dir / rollout path.

So >share --dangerously-skip-permissions my-cool-session typed inside codex now behaves just like Claude Code. Docs updated (Starlight page has both publish paths + codex install steps). Will close on merge.