AgentHub/docs/superpowers/specs/2026-09-29-codex-hooks-design.md

# Codex parity, part C2: Codex hooks

Issue: #40 part C. Date: 2026-09-29. Status: self-reviewed (the user asked for
autonomous work with a self-review per part). Builds on C1
(`2026-09-29-codex-usage-design.md`).

## Problem

C1 reads Codex sessions and tokens from the rollout journals, every 15 s. That
leaves out what only a live signal gives:
- a Codex session's tool calls in its timeline;
- "Codex is waiting for you" when it asks permission, on the lane card and as a notification;
- a Codex lane's running/idle without a 2-minute lag after a turn ends.

## What Codex offers (verified on 0.155.1, isolated `CODEX_HOME` + a fake model server)

- **Where hooks live:** `$CODEX_HOME/hooks.json`, in the same shape as Claude Code's `hooks` block:
  `{"hooks": {"<Event>": [{"matcher"?, "hooks": [{"type": "command", "command", "timeout"}]}]}}`.
  - Events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `Stop`, `SessionEnd`, and others.
  - Timeouts above 3 s are clamped (with a startup warning) for `SessionEnd`/`Interrupt`.
- **The stdin payload is Claude's shape:**
  - `session_id` equals the rollout's thread id, so it matches C1's session row.
  - Also: `transcript_path` (the rollout), `cwd`, `hook_event_name`, `model`, `permission_mode`, and `turn_id` on turn-scoped events.
  - Tool events carry `tool_name` (`Bash`), `tool_input` and `tool_use_id`. `PermissionRequest` carries `tool_input.command`/`.description`.
  - The hook inherits Codex's environment, including `AGENTHUB_LANE_ID`.
- **Trust:** a hook runs only once the user trusts its exact definition.
  - Codex asks at startup ("Hooks need review → Trust all and continue"), or the user runs `/hooks`.
  - Trust is stored in `$CODEX_HOME/config.toml` as `[hooks.state."<hooks.json path>:<event_snake>:<group>:<hook>"] trusted_hash = "sha256:…"`.
  - An untrusted hook is silently skipped by `codex exec`.
  - AgentHub never writes that trust and never passes `--dangerously-bypass-hook-trust`: skipping the user's review is not ours to do.

## Design

1. **A stable command:** `'<CODEX_HOME>/agenthub-hook.sh' <Event>`.
   - Trust is keyed on the definition, so the command must not change when AgentHub updates. A plugin install moves to a new cache directory on every update.
   - The script is AgentHub's own:
     - it runs this build's `scripts/hook-handler.js <Event> codex`, with the server's `node` (falling back to `node` on PATH, like the CLI launcher);
     - it sets the server's `CLAUDE_HOME`, so the handler finds the discovery file.
   - Every server start rewrites the script's content when it is installed and stale. Only the content changes, so the trusted definition stays valid.
   - Every value is single-quoted.
2. **Install / remove** (`server/lib/codex-hooks.js`), only on an explicit click in **Settings → Codex → AgentHub → Codex hooks**:
   - `install`:
     - Writes the script (0755).
     - Merges one group per event into `hooks.json`: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `Stop`, `Interrupt`, `SessionEnd`, each with `timeout: 3`.
     - Drops any earlier hook of ours first (matched by its exact command, never a group). Keeps every other entry.
     - Refuses a `hooks.json` that is not a JSON object (`EBADJSON`, the router's rule for `settings.local.json`).
     - Writes with temp + rename.
   - `remove`:
     - Takes our hooks out (a group left empty goes too) and deletes the script.
     - Deletes `hooks.json` when nothing else is left in it.
   - `status`:
     - Per event: whether our hook is present, and whether `config.toml` holds a trust entry for its position.
     - Whether the file is readable.
   - Win32 is refused (`EUNSUPPORTED`): the command is a POSIX shell script.
   - Routes: `GET/POST/DELETE /api/settings/codex-hooks`.
3. **Handler:** `scripts/hook-handler.js` sends `tool: "codex"` when its second argument is `codex`. The route reads `tool` through an allowlist (`codex`, else `claude`).
4. **Hook route, for `tool = codex`:**
   - **Sub-agent threads.** A hook from one would describe a child thread, not the user's session. We cannot see whether Codex fires hooks there, so this is guarded, not assumed.
     - When `transcript_path` is a rollout under `$CODEX_HOME/sessions` whose `session_meta.session_id` differs from its `id`, the hook is a sub-agent's.
     - Tool and permission events are attributed to the root session.
     - `SessionStart`/`SessionEnd`/`Stop`/`UserPromptSubmit` are dropped.
     - The meta read is cached per path.
   - **`PermissionRequest`** becomes the `Notification` Claude uses for a permission prompt, with the message `Codex needs your permission: <description or command>`. The awaiting flag, the lane's `needs_action`, the alert rules and the browser notification then work unchanged.
   - **`ensureSession`** creates the row with `tool = 'codex'`, named `Codex <8>` (C1 renames it from the prompt or thread name). It stores no `transcript_path`.
   - **The Claude transcript block** (tokens, titles, errors, compactions, turn durations), the SessionEnd transcript read, the sub-agent JSONL scan and the workflow ingest are skipped: they parse Claude's format, and C1 owns a Codex session's tokens.
   - **`touchLaneFromHook`** resolves the lane by `(cwd, tool)`, so a Codex hook reaches the Codex lane and never a Claude lane at the same directory. Stage detection runs for `claude` only: a non-claude lane carries no pipeline.
5. **Who owns a Codex session's status.**
   - A session that has hook events is **hook-fed**. While its hooks are current (see the whole-change review below), they own its status, `ended_at` and `updated_at`, as for Claude.
   - C1's poll still writes its tokens, model and name, and `settleActive` leaves it alone while its hooks are current.
   - A session with no events keeps C1's journal-activity status.
   - A hook-fed session whose Codex process dies without `SessionEnd` stays active until the stale sweep (`STALE_MINUTES`, 3 h). The liveness reap probes `claude` processes only.
6. **The lane mirror** (`codex-ingest.js`) skips a lane whose bound session got a hook event in the last 2 minutes: the hooks are current, and the mtime mirror would call a lane that just stopped "running" for up to 2 minutes.

## Found in the end-to-end check, fixed

- **Declining a permission (or Esc) ends the turn with `Interrupt`, not `Stop`.** The lane stayed `running` with a stale "needs your permission" until the next prompt. `Interrupt` is now installed and becomes `Stop`, since Codex is back at its prompt either way; a sub-agent thread's `Interrupt` is dropped. Adding it to an install the user already trusted made Codex ask about that one hook only, and the other seven kept their trust.
- In the TUI, `SessionStart` fires on the first prompt, when Codex creates the thread, not when the TUI opens.

## Found in the code review, fixed

- **Remove/Reinstall deleted a user's hook along with ours** when it sat in our group, or when its command merely contained `agenthub-hook.sh`. Ours is now matched by its exact command shape, one hook at a time, and a group is dropped only when that leaves it empty.
- **Install/remove had no `sameOriginGuard`.** Any web page could POST to install the hooks (Codex's trust prompt was the only stop). Both write routes now carry it.
- **A symlinked `CODEX_HOME`** could show "untrusted" forever and turn the sub-agent guard off, if Codex reports the resolved path. Trust and `threadOf` now accept the home as given or resolved (`codexHomes` in `codex-home.js`).
- **A session the journal poll imported first had no main agent**, so its agent-level state stayed empty. `ensureSession` now creates the missing `<id>-main` for a non-claude session.
- Minor:
  - `refreshScript` leaves a file that is not ours alone (`foreign`), restores a lost exec bit, and a failure is logged.
  - Writes go through a symlinked `hooks.json` to its target, and a failed write leaves no temp file behind.
  - The card has **Refresh**, shows Remove and the grid on a partial install, and gives each event screen-reader text.
- Left as is:
  - Trust is matched by position, so a stale entry at the same position reads as trusted.
  - The mirror takes over again after 2 minutes of hook silence during a long tool call.
  - A sub-agent hook that arrives before its rollout's first line creates its own session.
  - Whichever AgentHub server started last owns the forwarder.

## Found in the whole-change review, fixed

- **Hooks owned a session's status forever.** A session whose hooks were removed, or no longer trusted, stayed on its last hook-given status. Hooks now own it only while current (`hooksCurrent` in `codex-usage.js`: the newest event at or after the newest journal write minus 2 minutes); otherwise the journal decides again, in `settleActive` too.
- **A permission prompt could become a Compaction.** The Notification → `Compaction` tag matches `compact|compress|…` in the message, and a Codex `PermissionRequest` quoting a command such as `tar --compress` matched it. The tag now applies to `tool = 'claude'` only.
- **A sub-agent's tool call looked like the user resuming.** A child thread's `PreToolUse`/`PostToolUse`, folded onto the root session, is marked `_codexChild` and records work only: it no longer reactivates the session, clears its waiting flag, sets the main agent working, clears the lane's `needs_action` or moves the lane's status. Its own `Stop` is dropped, so anything it set would never be undone.
- **A forwarder path that is not a file of ours** — other content, an unreadable file, a directory (`scriptIsOurs`) — is never overwritten (install answers 400 `EFOREIGN`) or removed (remove skips it).
- **A rewritten `hooks.json` keeps the mode the user gave it**, and a symlinked one left with no hook is emptied through the link instead of being unlinked.
- The route's `tool` allowlist is now `codex`, `antigravity` (part D), else `claude`.

## Not changed

- Claude's hook path, apart from the parameter.
- Hook installs for Claude.
- `agenthub doctor`.
- The notification title, which still says "Claude needs your confirmation"; the body names Codex.
- No sub-agent rows for Codex.

## Tests

- **Server:**
  - `codex-hooks.js`: install into an empty home, and next to a user's own hooks (kept); reinstall replaces ours; remove leaves theirs and deletes a file of ours only; a non-JSON file refused; status with and without a trust entry; the script refreshed and its command unchanged.
  - Route: a codex hook creates a `tool = codex` session with no `transcript_path` and no Claude transcript read; `PermissionRequest` stamps awaiting and the codex lane's `needs_action` while the claude lane at the same cwd is untouched; no stage detection on a codex lane; a sub-agent thread's `Stop` dropped and its `PreToolUse` attributed to the root.
  - C1 does not overwrite a hook-fed session's status.
  - The mirror skips a lane with a fresh hook.
  - The handler sends `tool`.
- **Client:** the Codex hooks section (status, install, remove).
- **Browser:** the isolated server, a real `codex exec` against a fake model with the installed hooks trusted through the TUI prompt, then the session's timeline and a lane's `needs_action`.