@hayasaka7/haya-pet 0.2.0 → 0.2.1

package/docs/architecture.md

@@ -49,17 +49,39 @@ as each client allows:
 |---|---|---|
 | L1 | Process wrapper (lifecycle only) | session exists / exit code |
 | L2 | PTY output observation (`--observe`, opt-in) | activity-based working/idle |
-| L3 | Client logs / state files | client-specific (future) |
-| L4 | Client hooks | richest — implemented for Claude Code |
+| L3 | Client logs / state files / process tree | transcript watchers (Claude denial, Codex tools) + approval-accept detection |
+| L4 | Client hooks | richest — implemented for Claude Code (full) and Codex (partial) |
 
 The **default** is native passthrough (`stdio: "inherit"`) for full terminal
 fidelity, with **L1 lifecycle** status for every client. Richer status is opt-in:
-**Claude Code** gains **L4 hooks** when enabled with `haya-pet hooks on`
-(persisted; or per-run via `HAYA_PET_HOOKS=1`) — injected via
-`claude --settings <stable-file>`, reporting in-session activity through the
-`haya-pet state` command — lifecycle still comes from the wrapper's exit code);
-any client gains **L2** with `--observe`. Hooks are opt-in because injecting them
-triggers Claude's one-time *review hooks* trust prompt.
+**Claude Code** and **Codex** gain **L4 hooks** when enabled with the global
+`haya-pet hooks on` (persisted; or per-run via `HAYA_PET_HOOKS=1`). Both report
+in-session activity through the shared, client-agnostic `haya-pet state` command
+(lifecycle still comes from the wrapper's exit code); any client gains **L2** with
+`--observe`. Hooks are opt-in because injecting them triggers the client's one-time
+*review hooks* trust prompt.
+
+The injection mechanism differs per client. **Claude Code** takes a stable
+`claude --settings <file>`. **Codex** has no per-invocation settings flag, so the
+wrapper writes a stable `$CODEX_HOME/haya-pet.config.toml` profile and prepends
+`-p haya-pet` to the codex args (a profile layers on top of the user's base config,
+leaving auth/model/MCP intact, and is inert otherwise). Codex allows only one
+profile, so if the user already passes `-p/--profile`, injection is skipped with a
+notice. Codex's hook command must be unquoted at the program position (it runs via
+`cmd /c`, which strips a leading quote) and its matchers can't use look-around
+(Rust regex) — see [known-issues.md](known-issues.md). Codex's L4 is **partial**:
+`PreToolUse`/`PermissionRequest` don't fire upstream yet, so only `thinking`/`idle`
+arrive today.
+
+Hooks alone can't see one moment: clients emit **no event when the user accepts a
+permission prompt** (denial and completion are observable; the accept click is
+not). The companion bridges it with **L3 process-tree observation**: while a
+session sits in `waiting_approval`, it polls the client's process subtree (the
+wrapper reported the pid at register), and when a new descendant process appears
+and persists across two polls — the approved command verifiably running — the
+session flips to `running_tool`. No timers: an unanswered prompt keeps warning
+until a real event resolves it (`approval-process-watcher.js`,
+`process-snapshot.js`; Windows/macOS/Linux listers).
 
 L2 is **activity-based**: any visible output → *working*; a short quiet window →
 *idle*; success/failure come from the real exit code, never from scraping output
@@ -95,8 +117,9 @@ packages/
   session-core/    registry, priority, summaries, bubble views, linger, pet-state
   task-core/       task status, events, store, approvals, replies, controls
   adapters/        client info, heuristics, capabilities, output observer, routing
-  daemon-core/     IPC server/transport, runtime bridge, singleton
-  platform-core/   platform, paths, capabilities
+  daemon-core/     IPC server/transport, runtime bridge, singleton,
+                   approval process watcher (waiting_approval -> running_tool)
+  platform-core/   platform, paths, capabilities, process snapshots (win/mac/linux)
 apps/
   cli/             haya-pet entrypoint + parser (run / start / stop / pets)
   companion/       Electron overlay app (main + renderer)

package/docs/cross-os-qa.md

@@ -0,0 +1,72 @@
+# Cross-OS QA Matrix
+
+Use this checklist before release candidates and after changes to IPC, windowing, display handling, terminal attachment, or CLI process wrapping.
+
+## Automated Gates
+
+- [ ] `npm test` passes on the target branch.
+- [ ] Generic command lifecycle emits register, running state, heartbeat, final state, and unregister.
+- [ ] Daemon accepts local IPC messages and updates the session registry.
+- [ ] CLI can run through daemon IPC without an injected sender.
+- [ ] Pet preview loads a Codex-compatible `1536x1872` spritesheet.
+- [ ] Pet manifest parsing and atlas/action validation pass (`pet-core`).
+- [ ] Generic regex heuristics map sample output to normalized states (`adapters`).
+- [ ] Task status mapping, event normalization, and control gating pass (`task-core`).
+- [ ] Session bubble view models build with status label, summary, action, and elapsed (`session-core`).
+- [ ] PTY output observer infers debounced `pty_output` states from sample client output (`adapters`).
+- [ ] Reply/approval routing dispatches to injectors and safely refuses unsupported adapters (`adapters`).
+
+## Manual Platform Matrix
+
+| Platform | Shell/Terminal | Display Setup | Required Checks |
+|---|---|---|---|
+| Windows 11 | PowerShell | 100% DPI | `haya-pet run --client generic -- node -e "setTimeout(() => process.exit(0), 1000)"`; daemon sees session exit; overlay opens without focus stealing. |
+| Windows 11 | Windows Terminal | 125% DPI | Pet drag/click/double-click; position persists after restart; terminal attachment helper reports best-effort capability. |
+| Windows 11 | Windows Terminal | 150% or mixed DPI | Saved offscreen position clamps to visible work area; session bubbles remain visible. |
+| macOS current stable | Terminal.app | Retina display | Unix socket IPC works; transparent overlay opens; click/drag behavior works; position persists. |
+| macOS current stable | iTerm2 | External display | Moving terminal across displays does not lose session bubble fallback; permission denial produces best-effort/fallback state. |
+| Ubuntu Linux X11 | GNOME Terminal | Single display | Unix socket IPC works; transparent overlay opens; X11 terminal strategy reports best-effort. |
+| Ubuntu or Fedora Linux Wayland | Default terminal | Single display | Overlay fallback mode works; terminal attachment reports manual fallback; global pet plus cluster/session bubbles remain usable. |
+
+## Release Acceptance Gates
+
+- [ ] No platform stores prompts, screenshots, or raw terminal logs by default.
+- [ ] Windows uses `\\.\pipe\haya-petd` for local IPC.
+- [ ] macOS/Linux use `~/.haya-pet/haya-petd.sock` for local IPC.
+- [ ] Windows state path is under `%LOCALAPPDATA%\haya-pet\state.json`.
+- [ ] macOS/Linux state path is under `~/.haya-pet/state.json`.
+- [ ] If transparent overlay fails, a normal companion window is available.
+- [ ] If terminal attachment fails, global pet plus manual/cluster bubbles remain available.
+- [ ] Wayland does not use unsupported global positioning assumptions.
+- [ ] Saved display IDs are validated; missing displays fall back to primary visible work area.
+- [ ] Task talk controls are hidden or disabled when adapter capability is unsupported.
+- [ ] Reply composer shows "Open terminal to reply" for wrapper-only adapters (no blind injection).
+- [ ] Approvals require explicit approve/deny and are never auto-approved.
+- [ ] Companion runs as a single instance; a second launch focuses the existing pet.
+- [ ] A stale daemon lock (dead PID) is reclaimed; a live one forwards.
+
+## Companion App Smoke Test (per OS)
+
+Run from `apps/companion` after `npm install`:
+
+- [ ] `npm start` opens the overlay; empty space stays click-through.
+- [ ] Single click → waving; double click → jumping; drag moves and persists.
+- [ ] Running `haya-pet run --client generic -- sleep 10` shows a session bubble.
+- [ ] Two concurrent sessions show two bubbles without renderer conflicts.
+- [ ] Selecting a bubble opens the task talk window (peek mode).
+- [ ] Tray menu can show/hide the pet and reset its position.
+
+## Current Implementation Status
+
+- Shared protocol/session/pet core: automated coverage exists.
+- Pet asset manifest + validation + frame animator: automated coverage exists.
+- Client adapters (info, generic/PTY heuristics, capabilities): automated coverage exists.
+- Task talk core (status, events, store, approvals, replies, controls): automated coverage exists.
+- Session summaries + bubble view models: automated coverage exists.
+- Daemon singleton decision logic + tray menu model + position state file: automated coverage exists.
+- Cross-OS platform paths and capabilities: automated coverage exists.
+- Test-mode IPC server/client: automated coverage exists.
+- Electron overlay app: implemented as glue (`apps/companion`) consuming the pure cores; requires `electron` install and manual run/QA per OS (not unit-tested).
+- Production OS endpoint behavior: needs manual validation on Windows, macOS, and Linux.
+- Terminal attachment: facade + documented IPC contract (`native/README.md`). Windows helper is implemented in .NET and compiles + runs; macOS/Linux helper binaries are still TODO. Node helper client (`terminal-helper-client.js`) is unit-tested.
+- PTY output observer + reply/approval routing: implemented and unit-tested as pure cores. Live wiring (real PTY via node-pty; bidirectional IPC + real injectors) is a later phase.

package/docs/known-issues.md

@@ -24,6 +24,44 @@ Issues found in live use, with their current status.
   `Notification` hook by type (`permission_prompt`→approval, `idle_prompt`→idle) so
   non-approval notifications no longer masquerade as approvals.
 
+## ✅ Resolved: pet stuck on "waiting for approval" after the user ACCEPTS
+
+- **Symptom:** The denial fix above covered "deny", but **accepting** a prompt
+  still left the pet on *waiting for approval* for the whole run of the approved
+  tool — often the user approves a command (build/test) and Claude immediately
+  starts working, with no further `PreToolUse`/`PostToolUse` until the tool
+  *finishes*. For a long command that was minutes of misleading "waiting"
+  (observed: 240 s in a `HAYA_PET_HOOK_DEBUG` trace).
+- **Root cause:** Claude Code emits **nothing at the moment of a manual accept** —
+  verified three ways: the official hooks lifecycle (`PreToolUse` → dialog →
+  `PermissionRequest` → … → `PostToolUse` only *after* the tool completes; there
+  is no "permission granted" event), a live hook trace, and the session
+  transcript (the `tool_use`/`tool_result`/hook records are flushed in one batch
+  at completion; nothing is written at approval time). So between *prompt shown*
+  and *tool finished*, outside observers get zero signal. Timers were rejected
+  again: flipping the state on a delay would hide a genuinely unanswered prompt.
+- **Fix:** **Process-tree observation** (`approval-process-watcher.js` +
+  `process-snapshot.js`). The wrapper already reports the client's `pid` on
+  register. While a session sits in `waiting_approval`, the companion polls the
+  client's process subtree (~1.5 s; only during the waiting window): when a
+  **new descendant process appears and is still alive on the next poll**, the
+  approved command is verifiably running → the session flips to `running_tool`
+  (summary `approved`, source `client_log`). The two-poll persistence filter
+  keeps short-lived blips (our own hook reporter, the user's hooks) from
+  triggering it; the subtree walk covers shim layers (`cmd.exe` → `claude.exe` →
+  command). Every transition is event-based: a real process appeared, the tool
+  finished (`PostToolUse`), or the user denied (transcript). If nothing happens,
+  the warning stays up — by design.
+- **Known limitations (accepted):** (1) In-process approvals (Edit/Write file
+  edits) spawn no OS process and aren't detected — but they complete in
+  milliseconds after approval, so `PostToolUse` resolves them near-instantly
+  anyway. (2) Detection lags the accept by ~2–3 s (two polls + snapshot cost).
+  (3) An unrelated *persistent* process spawned by the client mid-wait (e.g. an
+  MCP server starting) would read as an approval — considered acceptable since
+  the client is in fact actively doing something then. Cross-OS: Windows via a
+  PowerShell CIM snapshot, macOS via `ps`, Linux via `/proc` (macOS/Linux listers
+  are implemented but need live verification on real hardware).
+
 ## ✅ Resolved: Claude Code TUI accepted no keyboard input when hooks were injected
 
 - **Symptom:** With per-session hooks injected by default (`claude --settings
@@ -94,25 +132,70 @@ observation (`--observe`) or L1 lifecycle as the fallback. Current state:
   approving once (a volatile per-session argument would re-trigger it every
   launch — see the resolved note below). `--observe` is a separate PTY opt-in for
   non-interactive runs (terminal-fidelity tradeoff).
-- **Codex** — **not yet implemented** (no hook injection). Uses `--observe` PTY
-  observation or L1 lifecycle. A Codex hook adapter (temp `<cwd>/.codex/hooks.json`
-  + `--dangerously-bypass-hook-trust`) is a planned follow-up; note the open
-  upstream bug where hooks may not fire in interactive sessions
-  ([#17532](https://github.com/openai/codex/issues/17532)).
+- **Codex** — **implemented (partial).** Opt-in via the global `haya-pet hooks on`;
+  the wrapper injects `packages/adapters/src/codex-hooks.js` as a stable
+  `$CODEX_HOME/haya-pet.config.toml` profile and launches `codex -p haya-pet`
+  (`packages/cli-core/src/codex-hook-injection.js`). Falls back to `--observe` / L1
+  when not enabled. Findings (verified against `codex-cli` 0.137.0 on Windows):
+  - **Mechanism fits.** Codex has a lifecycle-hooks system (`[[hooks.<Event>]]` in
+    `config.toml` or a `hooks.json`), with the `hooks` feature flag `stable` and ON
+    by default. Command hooks receive a JSON payload on **stdin**
+    (`session_id`, `hook_event_name`, `tool_name`, `cwd`) and treat *exit 0 with no
+    output* as continue — so our existing client-agnostic `haya-pet state` reporter
+    works unchanged. The hooks.json shape is identical to Claude's settings block;
+    **only the hook table differs**, which is all `codex-hooks.js` adds.
+  - **Event vocabulary differs** from Claude: no `Notification` / `PermissionDenied`
+    / `*Failure`; adds `PostCompact` / `SubagentStart`. `Stop` is the *only* idle
+    signal (`SubagentStop` is mid-turn → stays *thinking*). `PermissionRequest`
+    exists, so the approval cue is reachable.
+  - **Injection differs** — Codex has no `claude --settings <file>` equivalent.
+    Candidate non-mutating paths: `codex -p haya-pet` layering a generated
+    `$CODEX_HOME/haya-pet.config.toml` profile on top of the user's base config, or a
+    `hooks.json` next to the active config layer. Codex has its own *review hooks*
+    trust prompt (bypass: `--dangerously-bypass-hook-trust`), so the same one-time
+    trust UX as Claude applies.
+  - **Windows command quoting (fixed in the adapter):** Codex runs a hook `command`
+    via `cmd /c "<cmd>"`, which strips a **leading** quote — so Claude's
+    `"<node>" "<cli>" …` form dies with *"hook exited with code 1"*. The Codex
+    builder leaves the **program unquoted** (`<node> "<cli>" …`); args may be quoted.
+    Caveat: an unquoted program breaks if `node`'s path contains spaces (fine for
+    fnm/scoop/nvm layouts; a `command_windows` / short-path fallback is a follow-up).
+  - **No look-around in matchers:** Codex compiles matchers with the Rust `regex`
+    crate, which rejects `(?!…)` — Claude's negative-lookahead catch-all is a hard
+    parse error. Matchers are **anchored full matches** against the tool name, so
+    they must name tools exactly (`apply_patch`, `shell_command`).
+  - **Verified end-to-end** against `codex-cli` 0.137.0 (interactive TUI, Windows,
+    real `haya-pet state` reporter, `HAYA_PET_HOOK_DEBUG`): **`UserPromptSubmit`→
+    thinking, `PostToolUse`→thinking, `Stop`→idle all fire**, the parent env is
+    forwarded to hooks (session via `HAYA_PET_SESSION_ID`), and the reporter exits 0
+    cleanly. Note `codex exec` can't be used to test this — it forces
+    `approval_policy=never` + `sandbox=read`, a posture that disables hooks entirely.
+  - **`PreToolUse` does not fire** in 0.137 for tool calls (the entries are kept as
+    harmless no-ops for when it's fixed —
+    [openai/codex#16732](https://github.com/openai/codex/issues/16732)). Tool
+    activity is covered by an L3 Codex transcript watcher that tails
+    `~/.codex/sessions` JSONL: normal tools report `running_tool`, `apply_patch`
+    reports `editing_files`, and Haya Pet returns to `thinking` after active tool
+    calls drain. `PermissionRequest` (the *waiting for approval* cue — the
+    highest-value state) is **unconfirmed**; it likely depends on an
+    approval-required flow and needs a dedicated test before the feature is worth
+    wiring in.
 - **Antigravity (`agy`)** — **not yet implemented** (no hook injection). Uses
   `--observe` or L1 lifecycle. A Gemini-schema hook adapter is a planned follow-up.
 - **Generic / unknown** — no hooks; PTY observation (`--observe`) or L1 lifecycle.
 
-A future **L3 client-log adapter** (tailing e.g. `~/.codex/sessions` or
-Antigravity's `transcript.jsonl`) could provide activity without a PTY or hooks
-for the clients that lack a hook adapter.
+The Codex **L3 client-log adapter** now covers tool activity without a PTY or
+working `PreToolUse` hook. A similar adapter for Antigravity's `transcript.jsonl`
+remains a possible follow-up.
 
 ## Status sources, by fidelity
 
 | Tier | Source | How |
 |---|---|---|
 | L1 | process wrapper | default; session lifecycle + exit code |
-| L4 | client hooks | opt-in via `HAYA_PET_HOOKS=1` (Claude Code); reports through `haya-pet state …` |
+| L4 | client hooks | opt-in via `haya-pet hooks on` (Claude Code full, Codex partial); reports through `haya-pet state …` |
+| L3 | client logs | Codex session JSONL watcher for tool activity; Claude denial recovery; future clients can add similar transcript adapters |
+| L3 | process tree | approval-accept detection: a `waiting_approval` session flips to `running_tool` when the approved command verifiably starts under the client's pid |
 | L2 | PTY output scraping | opt-in via `--observe` (terminal-fidelity tradeoff) |
 
 Native passthrough (L1) + opt-in hooks (L4) is the recommended setup for interactive

package/docs/troubleshooting.md

@@ -16,11 +16,13 @@ deferred problems with known root causes.
 | Terminal scroll / Shift+Tab / backspace odd while a CLI runs under `haya-pet run` | Fixed — `haya-pet run` now uses native passthrough by default (full fidelity). If you opted into `--observe`, drop it. See [known-issues.md](known-issues.md). |
 | Pet shows only **idle/lifecycle** while **Claude Code** works | Live in-session status is opt-in: run `haya-pet hooks on` once (persisted). The first `haya-pet run` afterward shows a one-time Claude *review hooks* prompt — approve it. Also make sure the companion is running (`haya-pet start`). Check the toggle with `haya-pet hooks status`. |
 | Typing doesn't work / **Claude Code** TUI frozen under `haya-pet run` | You have hooks enabled and Claude is showing its *review hooks* trust prompt (approve it once), or your Claude is too old for `--settings`. Run `haya-pet hooks off` (or set `HAYA_PET_NO_HOOKS=1`) for native passthrough with lifecycle-only status — typing and Shift+Tab work normally. |
-| Pet shows only **idle/lifecycle** while **Codex** works | Codex has no hook adapter yet — only Claude Code reports live status via hooks. Add `--observe` for coarse PTY activity (terminal-fidelity tradeoff), or accept lifecycle-only status. |
+| Pet shows only **idle/lifecycle** while **Codex** works | Live status is opt-in: run `haya-pet hooks on` once (persisted, global), then `haya-pet run --client codex -- codex`; approve Codex's one-time *review hooks* prompt. `thinking`/`idle` come from hooks and `running_tool`/`editing_files` from a transcript watcher; *waiting for approval* doesn't fire yet (upstream [openai/codex#16732](https://github.com/openai/codex/issues/16732)). |
+| **Codex** live status didn't turn on / you pass your own `-p`/`--profile` | Codex allows only one profile, so haya-pet skips hook injection when you supply your own and prints a notice. Drop your `-p` for that run to get live status, or accept lifecycle-only. |
 | Pet shows only **idle/lifecycle** while **Antigravity** (`agy`) works | Antigravity has no hook adapter yet. Add `--observe` for coarse PTY activity, or accept lifecycle-only status. |
 | Claude hooks fail with **"hook exited with code 1"** | The hook command must not bake an **fnm**/node-manager *per-shell* node path (`…\fnm_multishells\<pid>_…\node.exe`) that dies when the shell exits. haya-pet bakes the stable `realpath`-resolved node path into the temp settings instead. Update to the latest version. |
 | Pet shows only **idle** for a generic / unknown CLI | Expected without a hook adapter — add `--observe` for PTY observation, otherwise lifecycle only. |
 | Pet stayed on **waiting for approval** after I denied a tool | Fixed — Claude fires no hook on a manual denial, so the wrapper tails the session transcript and clears to **idle** when the denial is recorded. A genuinely-pending approval (you haven't decided yet) correctly keeps alerting — there's no timer. |
+| Pet stayed on **waiting for approval** after I *approved* a command | Fixed — Claude also fires no hook at the accept moment, so the companion watches the client's process tree while a session waits: when the approved command verifiably starts (a new persistent process under the client), the pet flips to **working**. Expect a ~2–3s lag after your click. File-edit approvals (no process) resolve at completion, which is near-instant. |
 | Want to see which status events fire | Set `HAYA_PET_HOOK_DEBUG=<file.jsonl>` before `haya-pet run`; each hook- and transcript-sourced status appends one JSON line (timestamp, state, and source/event). |
 | Pet stays **idle** after force-quitting a CLI | The wrapper marks the session stale ~15s after the heartbeat stops, then drops it. Exiting normally (incl. Ctrl+C) reports **exited** immediately. |
 | Ctrl+C doesn't exit the CLI cleanly under `haya-pet run` | Fixed — the wrapper no longer dies on Ctrl+C; the signal reaches the CLI, which exits, and the pet shows the result. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hayasaka7/haya-pet",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Generic AI CLI pet runtime foundation.",
   "license": "MIT",

package/packages/adapters/src/codex-hooks.js

@@ -0,0 +1,152 @@
+// Codex CLI hook adapter. Wired into `haya-pet run --client codex` (opt-in via
+// `haya-pet hooks on`); injected through codex-hook-injection.js as a profile.
+//
+// Mirrors claude-hooks.js: pure builders that map Codex lifecycle events onto the
+// shared pet-state vocabulary and emit a hooks config. No I/O here — callers
+// resolve paths and write the file. Each hook entry runs the SAME client-agnostic
+// `haya-pet state` reporter with a fixed state baked into the command; the session
+// id rides in via HAYA_PET_SESSION_ID (injected by the wrapper at spawn), so Codex
+// never needs to pass it on stdin for our purposes.
+//
+// Why a Codex hook adapter is feasible (verified against codex-cli 0.137.0):
+//  - Codex command hooks receive a JSON payload on stdin and treat `exit 0 with no
+//    output` as success/continue — so our reporter, which prints nothing, is safe.
+//  - The hooks.json / [hooks] shape is identical to Claude's settings.json hooks
+//    block (per-event matcher groups of { type:"command", command }).
+//  - Codex hooks are gated behind `features.hooks = true` and carry their own
+//    Claude-style hook-trust prompt (bypassable with --dangerously-bypass-hook-trust).
+//
+// Differences from Claude that this file encodes:
+//  - Event set: no Notification / PermissionDenied / *Failure; adds PostCompact /
+//    SubagentStart. Turn-end is `Stop` (the only idle signal); SubagentStop is
+//    mid-turn so it returns to `thinking`, not idle.
+//  - Tool names: Codex uses `apply_patch` for edits and `shell_command` for
+//    commands, not Claude's Edit|Write|Bash. Matchers are ANCHORED full matches
+//    (a bare `shell` did NOT match `shell_command`), and Codex's Rust regex crate
+//    rejects look-around — so no negative-lookahead catch-all.
+//
+// VERIFIED end-to-end against codex-cli 0.137.0 (interactive TUI, Windows), with
+// the real `haya-pet state` reporter and HAYA_PET_HOOK_DEBUG:
+//  - FIRING: UserPromptSubmit→thinking, PostToolUse→thinking, Stop→idle. Codex
+//    forwards the parent env to hooks, so the session rides in via
+//    HAYA_PET_SESSION_ID and the reporter exits 0 cleanly (no "hook exited 1").
+//  - NOT FIRING (0.137): PreToolUse — so `running_tool` / `editing_files` never
+//    arrive in practice yet (upstream coverage gap, openai/codex#16732). The
+//    entries are kept (harmless no-ops) so they light up once Codex fixes it.
+//  - UNTESTED: PermissionRequest / PreCompact / SubagentStart|Stop (no approval /
+//    compaction / subagent occurred in the probe).
+//
+// OPEN QUESTION (injection): unlike `claude --settings <file>`, Codex has no
+// per-invocation settings-file flag. Candidate non-mutating paths, best first:
+//   1. `codex -p haya-pet` + a generated `$CODEX_HOME/haya-pet.config.toml` profile
+//      that layers ON TOP of the user's base config (auth/config preserved).
+//   2. a `hooks.json` next to the active config layer ($CODEX_HOME/hooks.json) —
+//      simple but global to every codex session (harmless: the reporter no-ops
+//      without HAYA_PET_SESSION_ID).
+// Both still trip Codex's one-time hook-trust prompt, exactly like the Claude path.
+
+// Codex's file-editing tool(s) vs. its command tool.
+const EDIT_TOOLS = ["apply_patch"];
+const EDIT_TOOLS_MATCHER = EDIT_TOOLS.join("|");
+// IMPORTANT: Codex compiles matchers with the Rust `regex` crate, which does NOT
+// support look-around. Claude's negative-lookahead catch-all (`^(?!…).*`) is a
+// hard parse error in Codex ("look-around … is not supported"), so we match the
+// command tool EXPLICITLY instead of "everything that isn't an edit". Tools other
+// than the command/edit tools simply don't update state on PreToolUse —
+// acceptable, as PostToolUse resets to `thinking` right after.
+//
+// The matcher is an ANCHORED full match against the tool name (verified: a bare
+// `shell` did NOT match the real tool `shell_command`). So name the tool exactly.
+const COMMAND_TOOLS_MATCHER = "shell_command";
+
+// The hook table. Each entry → one Codex hook that reports a fixed pet state.
+// `matcher` (when present) filters PreToolUse by tool name. `summary` is an
+// optional short label shown in the bubble and in HAYA_PET_HOOK_DEBUG logs.
+const HOOK_TABLE = Object.freeze([
+  { event: "UserPromptSubmit", state: "thinking" },
+  { event: "PreToolUse", matcher: EDIT_TOOLS_MATCHER, state: "editing_files" },
+  { event: "PreToolUse", matcher: COMMAND_TOOLS_MATCHER, state: "running_tool" },
+  { event: "PostToolUse", state: "thinking" },
+  { event: "PermissionRequest", state: "waiting_approval" },
+  { event: "PreCompact", state: "compacting" },
+  { event: "PostCompact", state: "thinking", summary: "compacted" },
+  // A subagent finishing is mid-turn — the main agent keeps working, so this is
+  // NOT idle. Turn-end is the dedicated `Stop` event below.
+  { event: "SubagentStart", state: "running_tool", summary: "subagent" },
+  { event: "SubagentStop", state: "thinking", summary: "subagent-done" },
+  { event: "Stop", state: "idle" }
+]);
+
+// Resolve the pet state for a Codex event. `toolName` is the tool for PreToolUse.
+// Exposed for testing and to keep the mapping in one place.
+export function mapCodexEventToState(event, toolName) {
+  if (event === "PreToolUse") {
+    return EDIT_TOOLS.includes(toolName) ? "editing_files" : "running_tool";
+  }
+  const entry = HOOK_TABLE.find((row) => row.event === event && row.matcher === undefined);
+  return entry?.state;
+}
+
+// Build the hooks config object (hooks.json shape; also valid as the [hooks] table
+// once serialized to TOML). Same structure as buildClaudeHookSettings, with one
+// Windows-critical difference in command quoting (see below).
+//
+// CRITICAL (verified on Windows): Codex runs a hook `command` via `cmd /c "<cmd>"`,
+// which strips the first and last quote if the string STARTS with a quote. So the
+// Claude builder's `"<node>" "<cli>" …` form (leading quote on the program) gets
+// mangled and the hook dies with "exited with code 1". The program (first token)
+// must therefore be UNQUOTED; interior argument quotes are preserved fine.
+//
+// Caveat: an unquoted program breaks if nodePath itself contains spaces (e.g.
+// "C:\Program Files\nodejs\node.exe"). The wrapper bakes the realpath-resolved
+// node path, which is space-free for fnm/scoop/nvm layouts; a space-tolerant
+// path (short 8.3 name, or `command_windows`) is a follow-up before shipping.
+export function buildCodexHookSettings({ nodePath, cliPath }) {
+  const command = (state, summary) => {
+    // nodePath unquoted (must not lead with a quote); cliPath quoted for spaces.
+    const base = `${nodePath} ${quote(cliPath)} state ${state}`;
+    return summary ? `${base} --summary ${summary}` : base;
+  };
+
+  const hooks = {};
+  for (const row of HOOK_TABLE) {
+    const hookEntry = { hooks: [{ type: "command", command: command(row.state, row.summary) }] };
+    if (row.matcher !== undefined) {
+      hookEntry.matcher = row.matcher;
+    }
+    (hooks[row.event] ??= []).push(hookEntry);
+  }
+
+  return { hooks };
+}
+
+function quote(value) {
+  return `"${String(value).replace(/"/g, '\\"')}"`;
+}
+
+// Serialize a hook settings object (from buildCodexHookSettings) to the TOML form
+// Codex loads from a config layer: `[[hooks.<Event>]]` (with optional `matcher`)
+// each containing `[[hooks.<Event>.hooks]]` command entries. Pure (no I/O).
+export function serializeCodexHooksToml(settings, { header } = {}) {
+  let toml = header ? `# ${header}\n` : "";
+  for (const [event, entries] of Object.entries(settings.hooks ?? {})) {
+    for (const entry of entries) {
+      toml += `[[hooks.${event}]]\n`;
+      if (entry.matcher !== undefined) {
+        toml += `matcher = ${tomlString(entry.matcher)}\n`;
+      }
+      for (const hook of entry.hooks ?? []) {
+        toml += `[[hooks.${event}.hooks]]\n`;
+        toml += `type = ${tomlString(hook.type)}\n`;
+        toml += `command = ${tomlString(hook.command)}\n`;
+      }
+      toml += "\n";
+    }
+  }
+  return toml;
+}
+
+// TOML basic-string escaping: backslash and double-quote must be escaped.
+function tomlString(value) {
+  return `"${String(value).split("\\").join("\\\\").split('"').join('\\"')}"`;
+}

package/packages/adapters/src/codex-transcript.js

@@ -0,0 +1,73 @@
+// Pure parser for Codex session JSONL records. This is the L3 fallback for live
+// tool activity because Codex PreToolUse hooks may not fire in some builds, while
+// the session transcript still records every tool call and tool result.
+
+const EDIT_TOOLS = new Set(["apply_patch"]);
+
+export function parseCodexTranscriptLine(line, options = {}) {
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+
+  if (entry?.type !== "response_item") {
+    return undefined;
+  }
+
+  // Skip records from before the current session (used when replaying a
+  // freshly-discovered transcript so an earlier session's tool calls don't
+  // masquerade as live activity). Records without a parseable timestamp are
+  // kept — losing live events is worse than a rare stale one.
+  const minTimestampMs = options.minTimestampMs ?? 0;
+  if (minTimestampMs > 0 && typeof entry.timestamp === "string") {
+    const timestampMs = Date.parse(entry.timestamp);
+    if (Number.isFinite(timestampMs) && timestampMs < minTimestampMs) {
+      return undefined;
+    }
+  }
+
+  const payload = entry.payload;
+  if (!payload || typeof payload !== "object") {
+    return undefined;
+  }
+
+  if (payload.type === "function_call" || payload.type === "custom_tool_call") {
+    const toolName = typeof payload.name === "string" ? payload.name : undefined;
+    const toolCallId = typeof payload.call_id === "string" ? payload.call_id : undefined;
+    if (!toolName || !toolCallId) {
+      return undefined;
+    }
+    return {
+      type: "tool_started",
+      toolCallId,
+      toolName,
+      state: EDIT_TOOLS.has(toolName) ? "editing_files" : "running_tool"
+    };
+  }
+
+  if (payload.type === "function_call_output" || payload.type === "custom_tool_call_output") {
+    const toolCallId = typeof payload.call_id === "string" ? payload.call_id : undefined;
+    if (!toolCallId) {
+      return undefined;
+    }
+    return { type: "tool_finished", toolCallId };
+  }
+
+  return undefined;
+}
+
+export function parseCodexTranscriptLines(lines, options = {}) {
+  const events = [];
+  for (const line of lines) {
+    if (typeof line !== "string" || line.trim() === "") {
+      continue;
+    }
+    const event = parseCodexTranscriptLine(line, options);
+    if (event) {
+      events.push(event);
+    }
+  }
+  return events;
+}

package/packages/adapters/test/codex-hooks.test.mjs

@@ -0,0 +1,120 @@
+// SPIKE tests for the Codex hook adapter prototype.
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import {
+  buildCodexHookSettings,
+  mapCodexEventToState,
+  serializeCodexHooksToml
+} from "../src/codex-hooks.js";
+
+test("mapCodexEventToState covers activity events", () => {
+  assert.equal(mapCodexEventToState("UserPromptSubmit"), "thinking");
+  assert.equal(mapCodexEventToState("PostToolUse"), "thinking");
+  assert.equal(mapCodexEventToState("PermissionRequest"), "waiting_approval");
+  assert.equal(mapCodexEventToState("PreCompact"), "compacting");
+  assert.equal(mapCodexEventToState("PostCompact"), "thinking");
+  assert.equal(mapCodexEventToState("SubagentStart"), "running_tool");
+  assert.equal(mapCodexEventToState("SubagentStop"), "thinking");
+  assert.equal(mapCodexEventToState("Stop"), "idle");
+  assert.equal(mapCodexEventToState("Unknown"), undefined);
+});
+
+test("mapCodexEventToState branches PreToolUse on tool name (apply_patch vs command)", () => {
+  assert.equal(mapCodexEventToState("PreToolUse", "apply_patch"), "editing_files");
+  assert.equal(mapCodexEventToState("PreToolUse", "shell_command"), "running_tool");
+  assert.equal(mapCodexEventToState("PreToolUse", "read_file"), "running_tool");
+});
+
+test("Stop is the only idle signal — SubagentStop stays working", () => {
+  // Regression guard for the key Codex-vs-Claude difference: a subagent finishing
+  // mid-turn must NOT flip the pet to idle.
+  assert.notEqual(mapCodexEventToState("SubagentStop"), "idle");
+  assert.equal(mapCodexEventToState("Stop"), "idle");
+});
+
+test("buildCodexHookSettings bakes node + cli, no volatile session id", () => {
+  const settings = buildCodexHookSettings({
+    nodePath: "/usr/bin/node",
+    cliPath: "/app/haya-pet.js"
+  });
+
+  const cmd = settings.hooks.UserPromptSubmit[0].hooks[0].command;
+  assert.equal(settings.hooks.UserPromptSubmit[0].hooks[0].type, "command");
+  // Program (node) must be UNQUOTED and must not lead with a quote — cmd /c on
+  // Windows strips a leading quote and breaks the hook. The cli path is quoted.
+  assert.doesNotMatch(cmd, /^"/);
+  assert.match(cmd, /^\/usr\/bin\/node /);
+  assert.match(cmd, /"\/app\/haya-pet\.js"/);
+  assert.match(cmd, /state thinking$/);
+  assert.doesNotMatch(JSON.stringify(settings), /--session/);
+});
+
+test("buildCodexHookSettings is stable across calls (for hook-trust caching)", () => {
+  const a = buildCodexHookSettings({ nodePath: "n", cliPath: "c" });
+  const b = buildCodexHookSettings({ nodePath: "n", cliPath: "c" });
+  assert.deepEqual(a, b);
+});
+
+test("buildCodexHookSettings splits PreToolUse into edit + command matchers", () => {
+  const pre = buildCodexHookSettings({ nodePath: "n", cliPath: "c" }).hooks.PreToolUse;
+  assert.equal(pre.length, 2);
+  const edit = pre.find((e) => /editing_files/.test(e.hooks[0].command));
+  const other = pre.find((e) => /running_tool/.test(e.hooks[0].command));
+  assert.equal(edit.matcher, "apply_patch");
+  assert.equal(other.matcher, "shell_command");
+});
+
+test("no matcher uses look-around (Codex's Rust regex crate rejects it)", () => {
+  // Regression guard: a `(?!…)` / `(?=…)` matcher is a hard parse error in Codex
+  // and disables that hook. Keep all matchers look-around-free.
+  const settings = buildCodexHookSettings({ nodePath: "n", cliPath: "c" });
+  for (const entries of Object.values(settings.hooks)) {
+    for (const entry of entries) {
+      if (entry.matcher !== undefined) {
+        assert.doesNotMatch(entry.matcher, /\(\?[=!<]/, `look-around in matcher "${entry.matcher}"`);
+      }
+    }
+  }
+});
+
+test("serializeCodexHooksToml emits [[hooks.X]] tables with unquoted program", () => {
+  const settings = buildCodexHookSettings({
+    nodePath: "C:\\nodedir\\node.exe",
+    cliPath: "C:\\app\\haya-pet.js"
+  });
+  const toml = serializeCodexHooksToml(settings, { header: "test header" });
+
+  assert.match(toml, /^# test header\n/);
+  assert.match(toml, /\[\[hooks\.UserPromptSubmit\]\]/);
+  assert.match(toml, /\[\[hooks\.UserPromptSubmit\.hooks\]\]/);
+  assert.match(toml, /type = "command"/);
+  // matcher present for PreToolUse
+  assert.match(toml, /matcher = "apply_patch"/);
+  // The command value (a TOML basic string) must NOT start with an escaped quote
+  // right after the opening quote — i.e. the program is unquoted: command = "C:\\...
+  const cmdLine = toml.split("\n").find((l) => l.startsWith("command ="));
+  assert.doesNotMatch(cmdLine, /^command = "\\"/);
+  // Backslashes are TOML-escaped (doubled).
+  assert.match(toml, /C:\\\\nodedir\\\\node\.exe/);
+});
+
+test("serializeCodexHooksToml round-trips backslashes/quotes safely", () => {
+  const settings = { hooks: { Stop: [{ hooks: [{ type: "command", command: 'a\\b "c"' }] }] } };
+  const toml = serializeCodexHooksToml(settings);
+  // a\b "c"  ->  "a\\b \"c\""
+  assert.match(toml, /command = "a\\\\b \\"c\\""/);
+});
+
+test("buildCodexHookSettings includes Codex's event set (and omits Claude-only events)", () => {
+  const settings = buildCodexHookSettings({ nodePath: "n", cliPath: "c" });
+  for (const event of [
+    "UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest",
+    "PreCompact", "PostCompact", "SubagentStart", "SubagentStop", "Stop"
+  ]) {
+    assert.ok(settings.hooks[event], `missing hook event ${event}`);
+  }
+  // Claude-only events Codex does not emit must not be registered.
+  for (const event of ["Notification", "PermissionDenied", "PostToolUseFailure", "StopFailure"]) {
+    assert.equal(settings.hooks[event], undefined, `unexpected Claude-only event ${event}`);
+  }
+});