@hayasaka7/haya-pet 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -1,12 +1,29 @@
 # Changelog
 
-All notable changes to Haya Pet are documented here. This project adheres to
+All notable changes to HAYA Pet are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/).
 
 > Note: some entries originally drafted under 0.2.0 actually landed *after* the
 > 0.2.0 npm publish; they are listed under 0.2.1, which is the first version that
 > ships them.
 
+## [0.2.6]
+
+### Fixed
+- **Codex "Approve for me" no longer shows a false *waiting for approval*.**
+  With `approvals_reviewer = auto_review` (the TUI's "Approve for me"; legacy
+  config alias `guardian_subagent`), Codex routes approval requests to a
+  guardian subagent and never prompts the user — but its `PermissionRequest`
+  hook still fires when the request is created, so the pet sat on *waiting for
+  approval* for the entire auto-review (and the approved command's run). A new
+  guardian-review watcher tails the guardian's own session rollout (the only
+  persisted trace of the review) and reports event-backed states instead:
+  *reviewing* while the guardian assesses, *running tools* on an `allow`
+  verdict, *thinking* on a `deny` (the rejection goes back to the model — no
+  human decision is pending). When the reviewer is the user (`approvals_reviewer
+  = "user"`, "Ask for approval"), nothing changes: *waiting for approval* still
+  shows until the user decides.
+
 ## [0.2.4]
 
 ### Fixed

package/README.md

@@ -1,294 +1,298 @@
 <div align="center">
 
-# 🐾 Haya Pet
+# HAYA Pet
 
-### One desktop companion for all your AI terminal agents
+### Let your Codex Desktop pets follow you into every AI terminal
 
-A transparent, draggable desktop pet that reflects what your AI CLIs are doing —
-Codex, Claude Code, Antigravity, Aider, or any command — through one shared
-runtime with client adapters.
+HAYA Pet is a local desktop companion for Codex, Claude Code, Antigravity,
+Aider, Gemini CLI, and almost any command-line AI client. It was inspired by
+Codex Desktop pets, but fixes the part that hurts: pets generated for Codex
+Desktop should not be trapped inside Codex Desktop.
 
-<!-- HERO SCREENSHOT: drop a wide shot at docs/screenshots/hero.png
-     (the pet on the desktop with a couple of session bubbles) -->
+Drop in a Codex-compatible pet, wrap your AI CLI with `haya-pet run`, and the
+same little character can watch all your agent sessions from one always-on-top
+overlay.
 
-![Haya Pet on the desktop](docs/screenshots/hero.png)
+![HAYA Pet on the desktop](docs/screenshots/hero.png)
 
 </div>
 
 ---
 
-## What is this?
+## Why HAYA Pet Exists
 
-Most "desktop pet for an AI tool" projects build one pet per tool. Haya Pet does
-the opposite: it is **one AI Terminal Pet Runtime** that many AI clients plug
-into through adapters.
+Codex Desktop made AI pets feel personal. The problem is portability: once a pet
+is generated there, it is useful only there.
 
-You might be running several agents at once:
+HAYA Pet turns those pet assets into a shared runtime for the AI tools you
+actually use day to day:
 
 ```text
-Codex CLI       → backend repo
-Claude Code     → frontend repo
-Antigravity CLI → infra repo
-Aider           → docs repo
+Codex CLI       -> backend work
+Claude Code     -> frontend work
+Antigravity     -> infra work
+Aider / Gemini  -> docs, scripts, experiments
+Any command     -> still gets a session bubble
 ```
 
-Haya Pet watches all of them and presents one ambient interface:
-
-- **One global pet** — reflects the selected or most urgent AI session; clickable,
-  draggable, and position-persistent like a real desktop companion.
-- **Session bubbles** — one compact bubble per active session showing client,
-  project, the latest activity, and a status icon (a spinning *working* circle, a
-  green *done* check, a yellow *needs you*, or a red *failed* cross). Bubbles stack
-  by connect time — the newest session on top — so the stack never reshuffles while
-  work is in progress. A folder button beside the pet folds them away.
-
-## Features
-
-- 🪟 **Transparent, frameless, always-on-top overlay** that doesn't steal focus and
-  stays click-through outside the pet and bubbles.
-- 🖱️ **Click / double-click / drag** — click folds/unfolds the bubbles, double-click
-  expands them, drag moves the pet (position persists; bubbles stay on-screen).
-- 📏 **Resizable pet** — hover the pet and drag the corner grip to scale it
-  0.5×–2× for your screen; double-click the grip to reset. The size persists.
-- 🟢 **Live session bubbles** with per-session status icons and a folder toggle.
-- 🧠 **Normalized state model** — every client maps to a shared state vocabulary
-  (`thinking`, `running_tool`, `waiting_approval`, `reviewing`, `failed`, …).
-- 🧩 **Client adapters** with tiered support (process wrapper → PTY observer →
-  client hooks) so the daemon never bakes in client-specific logic. Default is
-  lifecycle status; richer status is opt-in (Claude Code / Codex hooks via
-  `haya-pet hooks on`, or PTY `--observe` for any client).
-- 🚀 **Zero-setup launch** — `haya-pet run …` auto-starts the overlay; no separate
-  daemon to manage.
-- 🖼️ **Codex-compatible pet assets** (1536×1872 sprite atlas, 9 actions).
-- 🔒 **Local-only & private** — no prompts, files, or screenshots leave your machine.
-- 🪟🍎🐧 **Cross-platform** core with per-OS adapters for IPC and windowing.
+Instead of one pet per app, you get **one pet for your whole AI workspace**. It
+reacts to the selected or most urgent session, while compact bubbles show what
+each running client is doing.
 
-## Screenshots
+## The Candy
 
-<!-- Drop each PNG into docs/screenshots/ with the filename shown (~800px wide).
-     Delete any row you don't have a shot for. -->
+- **Bring your Codex Desktop pets with you.** HAYA Pet scans `~/.codex/pets`, so
+  Codex-compatible pet folders can be reused without rebuilding the character.
+- **Use one pet across many AI clients.** Codex and Claude Code get richer
+  live-status hooks; everything else can connect through the generic wrapper.
+- **See all active agents at a glance.** Session bubbles show client, project,
+  latest activity, and status: working, done, needs attention, or failed.
+- **Keep your terminal native.** The default wrapper preserves normal terminal
+  input. No broken Shift+Tab just to make the pet move.
+- **Stay local.** HAYA Pet does not upload prompts, files, screenshots, or logs.
 
-| | |
-|---|---|
-| **The global pet** — reacting to the highest-priority session.<br>![Pet overlay](docs/screenshots/pet-overlay.png) | **Session bubbles** — one per active session, with status icons.<br>![Session bubbles](docs/screenshots/session-bubbles.png) |
-| **Folder collapsed** — bubbles tucked away beside the pet.<br>![Folder collapsed](docs/screenshots/folder-collapsed.png) | **Tray menu** — show/hide, pets, reset position, Quit.<br>![Tray menu](docs/screenshots/tray-menu.png) |
+## Quick Start
 
-## Documentation
+### 1. Install
 
-| Doc | What's in it |
-|---|---|
-| **This README** | Install + users' guide |
-| [docs/architecture.md](docs/architecture.md) | How it works, components, project structure, adapter tiers, platform matrix, native helpers, roadmap |
-| [docs/publishing.md](docs/publishing.md) | Releasing to npm (the tag → publish workflow) |
-| [docs/troubleshooting.md](docs/troubleshooting.md) | Common fixes, incl. repairing a broken Electron install |
-| [docs/known-issues.md](docs/known-issues.md) | Deferred issues with known root causes |
-| [docs/cross-os-qa.md](docs/cross-os-qa.md) | Cross-OS test matrix |
-| [apps/companion/README.md](apps/companion/README.md) | Companion (Electron) internals |
-| [PROGRESS.md](PROGRESS.md) | Detailed development log |
+From npm, when available:
 
----
+```bash
+npm install -g @hayasaka7/haya-pet
+```
 
-# Users' Guide
+From source:
 
-## Requirements
+```bash
+git clone <repo-url> haya-pet
+cd haya-pet
+npm install
+npm link
+```
 
-| Requirement | Why |
-|---|---|
-| **Node ≥ 18** | Runtime + companion (Electron) |
-| **npm** | Install + scripts |
+Prefer not to link globally? Use the CLI directly:
 
-> Default status is lifecycle-only and needs no extra modules. Opt-in Claude Code /
-> Codex hooks (`haya-pet hooks on`) also need none. The opt-in `--observe` PTY mode uses
-> `node-pty` (installed automatically when it can build; without it, `--observe`
-> degrades to lifecycle-only tracking).
+```bash
+node <repo>/apps/cli/src/haya-pet.js
+```
 
-## Install
+### 2. Add A Pet
 
-**From npm** *(once published — recommended for users):*
+Put a Codex-compatible pet folder in `~/.codex/pets` or `~/.haya-pet/pets`.
 
-```bash
-npm install -g @hayasaka7/haya-pet     # exposes the `haya-pet` command globally
+On Windows, HAYA Pet also checks `%USERPROFILE%\.codex\pets` and
+`%LOCALAPPDATA%\haya-pet\pets`.
+
+```text
+~/.codex/pets/my-pet/
+    pet.json
+    spritesheet.webp
 ```
 
-**From source** *(current):*
+Minimal `pet.json`:
+
+```json
+{
+  "id": "my-pet",
+  "name": "My Pet",
+  "spritesheet": "spritesheet.webp"
+}
+```
+
+The spritesheet format is the Codex-compatible atlas used by this project:
+1536 x 1872 pixels, 8 columns x 9 rows, 192 x 208 per frame.
+
+Choose the pet:
 
 ```bash
-git clone <repo-url> haya-pet
-cd haya-pet
-npm install
-npm link                  # makes `haya-pet` available everywhere
+haya-pet pets
+haya-pet pets use my-pet
 ```
 
-Prefer not to link globally? Call it directly anywhere you'd type `haya-pet`:
-`node <repo>/apps/cli/src/haya-pet.js`.
+You can also switch pets from the tray menu.
 
-## Run an AI session
+### 3. Run Your AI Client Through HAYA Pet
 
-Just wrap any command. **The first `haya-pet run` auto-starts the pet overlay** —
-there's nothing to launch first:
+The first `haya-pet run` starts the overlay automatically.
 
 ```bash
-haya-pet run --client codex        -- codex
-haya-pet run --client claude-code  -- claude
-haya-pet run --client generic      -- aider
-# Windows / PowerShell example:
-haya-pet run --client generic      -- powershell -Command "Start-Sleep 10"
+haya-pet run --client codex
+haya-pet run --client claude-code
+haya-pet run --client antigravity
+
+# Any other CLI:
+haya-pet run --client generic -- aider
+haya-pet run --client generic -- gemini
+haya-pet run --client generic -- your-ai-command --with --args
 ```
 
-A **session bubble** appears while the command runs (client · project · status),
-and the pet reflects the highest-priority session. On exit the bubble briefly
-shows success (a green check) or failure (a red cross), then fades.
+A bubble appears for the session. When the command exits, the bubble shows
+success or failure briefly, then fades.
+
+## What You Get On Screen
+
+| Surface | What it does |
+|---|---|
+| Global pet | Reacts to the highest-priority session and can be dragged anywhere. |
+| Session bubbles | One bubble per running AI session, ordered by connect time. |
+| Folder button | Folds the bubbles away when you want a cleaner desktop. |
+| Tray menu | Show/hide, display mode, installed pets, reset position, and quit. |
+| Resize grip | Hover the pet, drag the corner, and keep the size you like. |
+
+## Screenshots
+
+| | |
+|---|---|
+| **The global pet** - reacting to the highest-priority session.<br>![Pet overlay](docs/screenshots/pet-overlay.png) | **Session bubbles** - one per active session, with status icons.<br>![Session bubbles](docs/screenshots/session-bubbles.png) |
+| **Folder collapsed** - bubbles tucked away beside the pet.<br>![Folder collapsed](docs/screenshots/folder-collapsed.png) | **Tray menu** - show/hide, pets, reset position, quit.<br>![Tray menu](docs/screenshots/tray-menu.png) |
 
-> If the overlay can't be started (e.g. Electron is missing), your command still
-> runs normally and keeps its exit code — you just won't see the pet. Disable
-> auto-start with `HAYA_PET_NO_AUTOSTART=1`, or launch it yourself with `haya-pet start`.
+## Supported Clients
 
-### Live activity status
+HAYA Pet has two ideas of support:
 
-`haya-pet run` uses **native passthrough by default** — the CLI talks directly to
-your terminal, so every input mode (Shift+Tab, mouse wheel, word-edit) works
-exactly as it does without the wrapper. Out of the box, every client shows
-**lifecycle status** (a session bubble while it runs; success/failure from the
-real exit code, never from scraping "error" out of output).
+- **Connection support:** the client can be wrapped and shown as a session.
+- **Live-status support:** the pet can react to in-session states like thinking,
+  editing files, running tools, or waiting for approval.
 
-```bash
-haya-pet run --client claude-code -- claude   # full fidelity, lifecycle status
-haya-pet run --client codex       -- codex    # full fidelity, lifecycle status
-```
+| Client | Works today | Best mode |
+|---|---:|---|
+| Codex CLI | Yes | Wrapper + opt-in hooks, with transcript-based tool activity |
+| Claude Code | Yes | Wrapper + opt-in hooks |
+| Antigravity | Yes | Wrapper lifecycle |
+| Aider | Yes | Generic wrapper |
+| Gemini CLI | Yes | Generic wrapper |
+| Any other command | Yes | Generic wrapper, optional `--observe` |
 
-Two **opt-in** ways to get richer *in-session* status (thinking / running tools /
-editing files / waiting for approval):
+Default behavior is intentionally conservative: HAYA Pet shows lifecycle status
+without changing how the terminal behaves. Richer live status is opt-in.
+
+## Live Status
+
+For Codex and Claude Code, enable hooks once:
 
 ```bash
-# Claude Code AND Codex — live status via per-session hooks, NO terminal-fidelity
-# tradeoff. Enable once (persisted, global); the first run for each client shows a
-# one-time "review hooks" prompt you approve once.
 haya-pet hooks on
-haya-pet run --client claude-code -- claude
-haya-pet run --client codex       -- codex
-#   (per-run override without persisting: HAYA_PET_HOOKS=1 …, or $env:HAYA_PET_HOOKS=1 in PowerShell)
-#   (turn back off: haya-pet hooks off   ·   check: haya-pet hooks status)
-
-# Any client — coarse live status by watching output through a PTY.
-haya-pet run --observe --client codex -- codex
+haya-pet run --client codex
+haya-pet run --client claude-code
 ```
 
-> **Codex coverage.** Codex shows `thinking` (working) and `idle` (done) via hooks,
-> plus `running_tool` / `editing_files` via a session-transcript watcher.
-> *Waiting for approval* doesn't arrive yet because of an upstream gap where
-> Codex's `PermissionRequest` hook doesn't fire
-> ([openai/codex#16732](https://github.com/openai/codex/issues/16732)); it'll start
-> working automatically once Codex fixes it. Also: if you pass your own
-> `-p/--profile` to codex, haya-pet skips hook injection (Codex allows one
-> profile) and tells you. Claude Code has full coverage.
-
-> **Approval prompts resolve correctly** (Claude Code): deny → the pet returns to
-> idle the moment the denial lands in the session transcript; accept a command →
-> the pet flips to *working* a couple of seconds after the approved command
-> actually starts running (detected from the client's process tree — a real
-> event, never a timeout, so an unanswered prompt keeps warning until you decide).
-
-> **Why opt-in?**
-> - **Hooks (Claude Code / Codex):** injecting hooks makes the client show a
->   one-time *review hooks* trust prompt. We don't disrupt your session by default;
->   turn it on once with `haya-pet hooks on` when you're happy to approve the hooks.
-> - **`--observe` (any client):** PTY observation infers status from output, but on
->   Windows it routes input through ConPTY, which can break **Shift+Tab**, mouse
->   scroll, and word-edit. Use it only for non-interactive runs. See
->   [docs/known-issues.md](docs/known-issues.md).
-
-## Add and choose a pet
-
-A pet is a folder with `pet.json` and a 1536×1872 sprite atlas (8×9 cells of
-192×208). Drop it into a search path:
+Check or disable the setting:
 
-```text
-~/.codex/pets/my-pet/                     (Windows: %USERPROFILE%\.codex\pets\my-pet\)
-    pet.json          { "id": "my-pet", "name": "My Pet", "spritesheet": "spritesheet.webp" }
-    spritesheet.webp
+```bash
+haya-pet hooks status
+haya-pet hooks off
 ```
 
-Pets are discovered from `~/.codex/pets` and `~/.haya-pet/pets`. Then choose one:
+Why opt in? Both clients show a one-time trust prompt when hooks are added. HAYA
+Pet lets you decide when to approve that instead of surprising you in the middle
+of work.
+
+Codex live status combines three sources: hooks report `thinking`/`idle` and
+approval requests, a transcript watcher reports tool/file activity, and a
+guardian-review watcher tracks Codex's **"Approve for me"** auto-reviewer — the
+pet shows *reviewing* while the guardian assesses a request and only shows
+*waiting for approval* when Codex actually asks you ("Ask for approval" mode).
+Per-tool `PreToolUse` hooks still depend on an upstream Codex gap
+([openai/codex#16732](https://github.com/openai/codex/issues/16732)); the
+transcript watcher covers that in the meantime.
+
+For any client, you can ask HAYA Pet to infer rough activity from terminal
+output:
 
 ```bash
-haya-pet pets               # list installed pets (* = selected)
-haya-pet pets use my-pet    # select; remembered on every launch
+haya-pet run --observe --client generic -- aider
 ```
 
-Your choice is stored and reused every time. You can also pick from the tray menu
-→ **Installed Pets**. Without a spritesheet, the pet renders labelled placeholder
-frames so everything still works.
+Use `--observe` only when you accept the PTY tradeoff. On Windows, ConPTY can
+break special input such as Shift+Tab, mouse scroll, and word-edit. The default
+non-observe mode keeps terminal input native.
 
-## Interact with the pet
+## Pet Controls
 
 | Action | Result |
 |---|---|
-| Single click | waves + folds/unfolds the session bubbles |
-| Double click | jumps + expands the bubbles |
-| Drag | moves the pet; position is saved (bubbles follow, always on-screen) |
-| Drag corner grip | resizes the pet 0.5×–2× (grip appears on hover); size is saved |
-| Double-click grip | resets the pet to its normal size |
-| Tray icon → menu | show/hide, display mode, sessions, pets, **reset position**, **Quit** |
+| Single click | Wave and fold or unfold session bubbles. |
+| Double click | Jump and expand session bubbles. |
+| Drag | Move the pet; position is saved. |
+| Drag corner grip | Resize from 0.5x to 2x; size is saved. |
+| Double-click grip | Reset to normal size. |
+| Tray icon | Open menu for display, sessions, pets, reset, and quit. |
 
-## Stop / exit the pet
+## Commands
 
 ```bash
-haya-pet stop      # ask the running overlay to quit
-```
+haya-pet run --client codex              # launch Codex with a pet session
+haya-pet run --client claude-code        # launch Claude Code with a pet session
+haya-pet run --client generic -- aider   # wrap any other command
 
-…or **right-click the tray icon → Quit**. `haya-pet stop` is a no-op if nothing is
-running, so it's always safe to call.
+haya-pet pets                            # list installed pets
+haya-pet pets use my-pet                 # select a pet
 
-## Manage the overlay
+haya-pet hooks on                        # enable live-status hooks where supported
+haya-pet hooks status
+haya-pet hooks off
 
-```bash
-haya-pet start     # start the overlay explicitly (usually unnecessary — run auto-starts it)
-haya-pet stop      # quit it
+haya-pet start                           # start the overlay explicitly
+haya-pet stop                            # stop the overlay
 ```
 
-## Troubleshooting
+If the overlay cannot start, the wrapped command still runs and keeps its real
+exit code. Disable auto-start with `HAYA_PET_NO_AUTOSTART=1`.
 
-Common fixes:
+## Requirements
 
-| Symptom | Fix |
+| Requirement | Why |
 |---|---|
-| `haya-pet: command not found` | Install globally, or `npm link` in a source checkout. |
-| Pet doesn't react to a session | Launch via `haya-pet run …`; check `HAYA_PET_NO_AUTOSTART` isn't set. |
-| Pet shows a blue placeholder box | No spritesheet — add a pet (above). |
-| Pet is off-screen | Tray menu → **Reset Position**. |
-| Can't exit | `haya-pet stop` or tray → **Quit**. |
+| Node 18 or newer | Runtime and Electron companion. |
+| npm | Install, link, and test scripts. |
+| Electron | Installed as a runtime dependency. |
+| node-pty | Optional; used only for `--observe`. |
 
-Full list (incl. repairing a broken Electron install): [docs/troubleshooting.md](docs/troubleshooting.md).
+## Troubleshooting
 
----
+| Symptom | Fix |
+|---|---|
+| `haya-pet: command not found` | Install globally, or run `npm link` from this repo. |
+| No pet appears for a session | Start the AI client through `haya-pet run ...`. |
+| Pet shows a placeholder | Add a pet folder with both `pet.json` and `spritesheet.webp`. |
+| Pet is off-screen | Use tray menu -> **Reset Position**. |
+| Overlay will not exit | Run `haya-pet stop` or tray menu -> **Quit**. |
 
-## Supported clients
+More fixes are in [docs/troubleshooting.md](docs/troubleshooting.md), including
+repairing a broken Electron install.
 
-| Client | Status | Support level |
-|---|---|---|
-| Generic CLI | ✅ | L1 process wrapper (+ L2 PTY via `--observe`) |
-| Codex | ✅ | L1 wrapper + **L4 live-status hooks** (opt-in `haya-pet hooks on`; partial — see note) |
-| Claude Code | ✅ | L1 wrapper + **L4 live-status hooks** (opt-in `haya-pet hooks on`) |
-| Antigravity | ✅ | L1 wrapper (+ L2 PTY via `--observe`) |
-| Gemini CLI / Aider / others | 🔜 | via the generic adapter |
+## Privacy
 
-(See [docs/architecture.md](docs/architecture.md) for the support tiers and the
-platform matrix, and [CHANGELOG.md](CHANGELOG.md) for release notes.)
+HAYA Pet is local-only by default. It does not upload prompts, files,
+screenshots, or session logs. The overlay stores only local state needed for
+pet selection, position, size, and short derived status summaries.
 
-## Privacy
+## Documentation
+
+| Doc | What it covers |
+|---|---|
+| [docs/architecture.md](docs/architecture.md) | Runtime design, adapter tiers, platform matrix, roadmap. |
+| [docs/publishing.md](docs/publishing.md) | Release and npm publishing flow. |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Common failures and repair steps. |
+| [docs/known-issues.md](docs/known-issues.md) | Current limitations and upstream gaps. |
+| [docs/cross-os-qa.md](docs/cross-os-qa.md) | Cross-OS QA checklist. |
+| [apps/companion/README.md](apps/companion/README.md) | Electron companion internals. |
+| [assets/fallback-pet/README.md](assets/fallback-pet/README.md) | Bundled fallback pet details. |
+| [PROGRESS.md](PROGRESS.md) | Development log. |
 
-Haya Pet is local-only by default. It does **not** upload prompts, files,
-screenshots, or session logs; it stores only short derived status summaries.
-Approvals always require explicit user action.
+## Contributing
 
-## Contributing & tests
+Run the full test suite:
 
 ```bash
-npm test     # runs the full suite (TDD; tests live in **/test/*.test.mjs)
+npm test
 ```
 
-See [docs/architecture.md](docs/architecture.md) to find your way around the code.
+The codebase is organized as one npm package with internal packages under
+`packages/` and apps under `apps/`. Start with
+[docs/architecture.md](docs/architecture.md) if you want to add a client adapter,
+touch the overlay, or work on pet rendering.
 
 ## License
 
-See [`LICENSE`](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/apps/cli/src/haya-pet.js

@@ -9,6 +9,7 @@ import { injectClaudeHooks as defaultInjectClaudeHooks } from "../../../packages
 import { injectCodexHooks as defaultInjectCodexHooks } from "../../../packages/cli-core/src/codex-hook-injection.js";
 import { watchClaudeTranscript as defaultWatchClaudeTranscript } from "../../../packages/cli-core/src/claude-transcript-watcher.js";
 import { watchCodexTranscript as defaultWatchCodexTranscript } from "../../../packages/cli-core/src/codex-transcript-watcher.js";
+import { watchCodexGuardianReviews as defaultWatchCodexGuardianReviews } from "../../../packages/cli-core/src/codex-guardian-watcher.js";
 import { ensureCompanionConnection } from "../../../packages/cli-core/src/companion-launcher.js";
 import { createIpcClient as defaultCreateIpcClient } from "../../../packages/daemon-core/src/ipc-server.js";
 import { getDefaultPaths } from "../../../packages/platform-core/src/paths.js";
@@ -128,6 +129,8 @@ async function runRunCommand(parsed, dependencies) {
   const injectCodexHooks = dependencies.injectCodexHooks ?? defaultInjectCodexHooks;
   const watchClaudeTranscript = dependencies.watchClaudeTranscript ?? defaultWatchClaudeTranscript;
   const watchCodexTranscript = dependencies.watchCodexTranscript ?? defaultWatchCodexTranscript;
+  const watchCodexGuardianReviews =
+    dependencies.watchCodexGuardianReviews ?? defaultWatchCodexGuardianReviews;
   const print = dependencies.print ?? defaultPrint;
   const env = dependencies.env ?? process.env;
   const now = dependencies.now ?? Date.now;
@@ -251,6 +254,50 @@ async function runRunCommand(parsed, dependencies) {
         watcher.stop();
         previousStopWatcher();
       };
+
+      // With "Approve for me" (approvals_reviewer=auto_review, legacy alias
+      // guardian_subagent), Codex routes approval requests to a guardian
+      // subagent and never shows the human approval UI — yet the
+      // PermissionRequest hook still fires at request creation, which used to
+      // pin the pet on a false "waiting for approval" for the whole review.
+      // The guardian's own rollout is the only observable record of the
+      // review, so tail it: a review turn starting proves the agent is
+      // reviewing; an "allow" verdict proves the action proceeds; a "deny"
+      // verdict goes back to the model, which keeps working. An unreadable
+      // verdict reports nothing — a pending cue is never cleared on a guess.
+      const guardianWatcher = watchCodexGuardianReviews({
+        homeDir: dependencies.homeDir,
+        sessionsRoot: dependencies.codexSessionsRoot,
+        startedAt: now(),
+        onReviewEvent: (event) => {
+          hookDebugLog(env, now, {
+            source: "codex_guardian",
+            event: event.type,
+            outcome: event.outcome
+          });
+
+          const report = resolveGuardianStateReport(event);
+          if (!report) {
+            return;
+          }
+          messageSender
+            .send({
+              type: "state",
+              sessionId,
+              state: report.state,
+              summary: report.summary,
+              confidence: 0.85,
+              source: "client_log",
+              updatedAt: now()
+            })
+            .catch(() => {});
+        }
+      });
+      const stopWithoutGuardian = stopWatcher;
+      stopWatcher = () => {
+        guardianWatcher.stop();
+        stopWithoutGuardian();
+      };
     }
   }
 
@@ -276,6 +323,23 @@ async function runRunCommand(parsed, dependencies) {
   }
 }
 
+// Map a guardian review event to the pet state it proves. waiting_approval is
+// deliberately NOT among these: with the guardian reviewing, the user is not
+// being asked anything, and after a deny the request is resolved (the model
+// receives the rejection and continues) — there is no pending human decision.
+function resolveGuardianStateReport(event) {
+  if (event.type === "review_started") {
+    return { state: "reviewing", summary: "agent reviewing approval" };
+  }
+  if (event.type === "review_finished" && event.outcome === "allow") {
+    return { state: "running_tool", summary: "reviewer approved" };
+  }
+  if (event.type === "review_finished" && event.outcome === "deny") {
+    return { state: "thinking", summary: "reviewer denied" };
+  }
+  return undefined;
+}
+
 // Resolve whether live-status hooks should be injected for this run (any
 // hook-capable client). Precedence: HAYA_PET_NO_HOOKS forces off, HAYA_PET_HOOKS
 // forces on (per-run overrides), otherwise the persisted `haya-pet hooks on/off`