@hayasaka7/haya-pet 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -7,6 +7,23 @@ All notable changes to HAYA Pet are documented here. This project adheres to
 > 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

@@ -187,10 +187,14 @@ 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 support is useful but still partial. Hooks report `thinking` and `idle`,
-while a transcript watcher reports tool/file activity. Waiting-for-approval
-support depends on an upstream Codex hook gap:
-[openai/codex#16732](https://github.com/openai/codex/issues/16732).
+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:

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`

package/apps/cli/test/haya-pet.test.mjs

@@ -483,6 +483,47 @@ test("codex hooks also start a transcript watcher for tool activity", async () =
   assert.ok(sent.every((message) => message.updatedAt === undefined || message.updatedAt === 42));
 });
 
+test("codex hooks also start a guardian-review watcher that reports review states", async () => {
+  const sent = [];
+  let fireReviewEvent;
+  let stopped = false;
+
+  await runAiPet(["run", "--client", "codex", "--", "codex"], {
+    cwd: process.cwd(),
+    env: { USERPROFILE: "C:\\Users\\A" },
+    now: () => 42,
+    heartbeatIntervalMs: 10,
+    send: async (message) => sent.push(message),
+    createStateFile: hooksStateFile(true),
+    injectCodexHooks: () => ({ profileName: "haya-pet", cleanup: () => {} }),
+    watchCodexTranscript: () => ({ stop: () => {} }),
+    watchCodexGuardianReviews: ({ onReviewEvent }) => {
+      fireReviewEvent = onReviewEvent;
+      return { stop: () => { stopped = true; } };
+    },
+    runGenericCommand: async (options) => {
+      fireReviewEvent({ type: "review_started" });
+      fireReviewEvent({ type: "review_finished", outcome: "allow" });
+      fireReviewEvent({ type: "review_started" });
+      fireReviewEvent({ type: "review_finished", outcome: "deny" });
+      // An unreadable verdict must not change the state (leave the cue as-is).
+      fireReviewEvent({ type: "review_finished", outcome: undefined });
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.ok(stopped, "guardian watcher is stopped after the wrapped command exits");
+  const reviewStates = sent
+    .filter((message) => message.type === "state" && message.source === "client_log")
+    .map((message) => [message.state, message.summary]);
+  assert.deepEqual(reviewStates, [
+    ["reviewing", "agent reviewing approval"],
+    ["running_tool", "reviewer approved"],
+    ["reviewing", "agent reviewing approval"],
+    ["thinking", "reviewer denied"]
+  ]);
+});
+
 test("codex hooks are skipped (with a notice) when the user passes their own -p", async () => {
   const calls = [];
   let injected = 0;

package/docs/architecture.md

@@ -70,8 +70,14 @@ profile, so if the user already passes `-p/--profile`, injection is skipped with
 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.
+`PreToolUse` doesn't fire upstream yet, so tool activity comes from an L3
+transcript watcher tailing the session rollout. `PermissionRequest` fires, but
+once at approval-request creation — before Codex routes the request to either
+the user or its guardian auto-reviewer ("Approve for me"), which never prompts
+the user at all. An L3 **guardian-trunk watcher** tails the guardian's own
+rollout (`source: {subagent:{other:"guardian"}}`, parented to the main thread)
+and refines the state: review running → `reviewing`, verdict allow →
+`running_tool`, verdict deny → `thinking`.
 
 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

package/docs/known-issues.md

@@ -2,6 +2,52 @@
 
 Issues found in live use, with their current status.
 
+## ✅ Resolved: false "waiting for approval" while Codex auto-reviews an approval (Approve for me)
+
+- **Symptom:** Running Codex under the pet with the **"Approve for me"** preset
+  (`approvals_reviewer = auto_review`; the user's config had the legacy alias
+  `guardian_subagent`), the pet showed *waiting for approval* whenever an action
+  needed approval — even though Codex's guardian was reviewing it automatically
+  and the user was never asked anything. The false state lasted the whole review
+  (~8–30 s per request, up to Codex's 90 s review timeout) plus the approved
+  command's runtime.
+- **Root cause (verified against codex-rs 0.139.0 source + a live trunk
+  rollout):** Codex fires the `PermissionRequest` hook once, at approval-request
+  creation, **before** routing — and for guardian-routed requests the human
+  approval UI is *never* shown: a guardian `allow` lets the action proceed; a
+  guardian `deny` returns the rationale to the **model** as a rejected tool call
+  ("This action was rejected due to unacceptable risk. …"), so no human decision
+  is ever pending. Our Codex hook table mapped `PermissionRequest` →
+  `waiting_approval` unconditionally. No better hook exists: nothing fires on
+  guardian start/finish (the guardian session is `SubAgentSource::Other`, which
+  is excluded from Subagent hooks), and `GuardianAssessment` events are
+  explicitly not persisted to the main rollout (`rollout/src/policy.rs`).
+- **Fix:** an **L3 guardian-trunk watcher** (`codex-guardian-watcher.js` +
+  `adapters/codex-guardian.js`). The guardian runs as its own Codex session that
+  writes its own rollout under `~/.codex/sessions` — session_meta has
+  `source: {subagent: {other: "guardian"}}` and `parent_thread_id` = the main
+  thread; each review is one turn (`task_started` → `task_complete` with the
+  verdict JSON in `last_agent_message`, e.g. `{"outcome":"allow"}`). The watcher
+  binds the trunk to the wrapped session's main thread id and maps real events:
+  review turn starts → **reviewing**; verdict `allow` → **running_tool**
+  ("reviewer approved" — the action verifiably proceeds); verdict `deny` →
+  **thinking** ("reviewer denied" — the model received the rejection and keeps
+  working). An unreadable verdict reports nothing, so a pending cue is never
+  cleared on a guess. With `approvals_reviewer = "user"` ("Ask for approval")
+  there is no trunk and behavior is unchanged: `PermissionRequest` →
+  *waiting for approval* until the user decides (process-tree/denial detection
+  resolve it, as before).
+- **Known limitations (accepted):** (1) A ≤ ~1 s *waiting for approval* flicker
+  can precede *reviewing* (the hook fires immediately; the trunk poll is 700 ms).
+  (2) Reviews of a **collab subagent's** actions (multi-agent runs) have their
+  own trunks keyed to the subagent's thread and are not watched; a subagent's
+  `PermissionRequest` can still briefly show *waiting for approval* until the
+  next main-session event. (3) After a guardian deny the pet shows *thinking*,
+  not *waiting for approval* — by design: Codex resolves the request itself and
+  the model decides what to do next (it may ask the user in chat, which then
+  surfaces as turn-end *idle*). The TUI's passive `/approve` denial-override
+  picker is not a blocking prompt.
+
 ## ✅ Resolved: pet stuck on "waiting for approval" after a manual denial
 
 - **Symptom:** With Claude Code hooks enabled, denying a permission prompt left the
@@ -176,10 +222,16 @@ observation (`--observe`) or L1 lifecycle as the fallback. Current state:
     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.
+    calls drain.
+  - **`PermissionRequest` fires** (confirmed live on 0.139.0), but **once, at
+    approval-request creation, before routing** — under "Approve for me"
+    (`approvals_reviewer = auto_review` / legacy `guardian_subagent`) the user is
+    never actually prompted, so the hook alone over-reports *waiting for
+    approval*. An L3 **guardian-trunk watcher** tails the guardian reviewer's own
+    rollout (`source: {subagent:{other:"guardian"}}`, `parent_thread_id` = main
+    thread) and refines the state: review running → *reviewing*, verdict `allow`
+    → *running_tool*, verdict `deny` → *thinking*. See the resolved
+    false-waiting-for-approval entry above.
 - **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.
@@ -194,7 +246,7 @@ remains a possible follow-up.
 |---|---|---|
 | L1 | process wrapper | default; session lifecycle + exit code |
 | 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 | client logs | Codex session JSONL watcher for tool activity; Codex guardian-trunk watcher for auto-review status; 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) |
 

package/docs/troubleshooting.md

@@ -16,7 +16,8 @@ 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 | 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)). |
+| 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, `running_tool`/`editing_files` from a transcript watcher, and approval states from the `PermissionRequest` hook plus a guardian-review watcher. |
+| Pet showed **waiting for approval** while **Codex** auto-reviewed the request ("Approve for me") | Fixed — with `approvals_reviewer = auto_review` (legacy `guardian_subagent`) Codex's guardian decides without asking you; the pet now shows **reviewing** during the assessment, then **working** on an allow verdict or **thinking** on a deny. *Waiting for approval* still shows when Codex actually asks you (`approvals_reviewer = "user"`). |
 | **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. |

package/package.json

@@ -1,8 +1,30 @@
 {
   "name": "@hayasaka7/haya-pet",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "type": "module",
   "description": "Generic AI CLI pet runtime foundation.",
+  "keywords": [
+    "haya-pet",
+    "desktop-pet",
+    "virtual-pet",
+    "desktop-companion",
+    "ai",
+    "ai-agents",
+    "coding-agents",
+    "ai-cli",
+    "codex",
+    "codex-cli",
+    "claude-code",
+    "gemini-cli",
+    "aider",
+    "antigravity",
+    "electron",
+    "cli",
+    "terminal",
+    "developer-tools",
+    "local-first",
+    "productivity"
+  ],
   "license": "MIT",
   "author": "Ai Hayasaka",
   "repository": {

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

@@ -0,0 +1,131 @@
+// Pure parser for Codex guardian-review rollouts. When `approvals_reviewer` is
+// `auto_review` (legacy alias `guardian_subagent`, the TUI's "Approve for me"),
+// Codex routes approval requests to a guardian subagent instead of prompting the
+// user — the PermissionRequest hook still fires at request creation, but the
+// human approval UI never appears. The only persisted trace of the review is a
+// separate "guardian trunk" rollout under ~/.codex/sessions whose session_meta
+// carries source.subagent.other == "guardian" and parent_thread_id == the main
+// thread; each review is one turn there (task_started → task_complete with the
+// verdict JSON in last_agent_message). Verified against codex-cli 0.139.0
+// (codex-rs guardian/review_session.rs; rollout/src/policy.rs excludes the
+// GuardianAssessment events themselves from persistence).
+
+// Classify a rollout's first JSONL line (the session_meta record) so watchers
+// can tell main sessions, guardian review sessions, and other subagents apart.
+export function classifyCodexSessionMeta(line) {
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+
+  if (entry?.type !== "session_meta") {
+    return undefined;
+  }
+
+  const payload = entry.payload;
+  if (!payload || typeof payload !== "object") {
+    return undefined;
+  }
+
+  const threadId = typeof payload.id === "string" ? payload.id : undefined;
+  const parentThreadId =
+    typeof payload.parent_thread_id === "string" ? payload.parent_thread_id : undefined;
+
+  return { kind: resolveSessionKind(payload), threadId, parentThreadId };
+}
+
+function resolveSessionKind(payload) {
+  const subagentSource =
+    typeof payload.source === "object" && payload.source !== null
+      ? payload.source.subagent
+      : undefined;
+
+  if (typeof subagentSource === "object" && subagentSource !== null) {
+    if (subagentSource.other === "guardian") {
+      return "guardian";
+    }
+    return "subagent";
+  }
+
+  if (payload.thread_source === "subagent") {
+    return "subagent";
+  }
+
+  return "main";
+}
+
+// Parse one guardian-trunk JSONL line into a review lifecycle event. Each review
+// turn yields task_started (the guardian began assessing an approval request)
+// and task_complete (verdict in last_agent_message: `{"outcome":"allow"|"deny"}`,
+// optionally with risk_level/rationale). An unreadable verdict maps to
+// outcome: undefined so callers can leave the pet state untouched (safe: the
+// existing waiting cue stays up rather than being cleared on a guess).
+export function parseGuardianTranscriptLine(line, options = {}) {
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+
+  if (entry?.type !== "event_msg") {
+    return undefined;
+  }
+
+  // Same replay guard as the main transcript parser: skip records from before
+  // the current session, keep records without a parseable timestamp.
+  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 === "task_started") {
+    return { type: "review_started" };
+  }
+
+  if (payload.type === "task_complete") {
+    return { type: "review_finished", outcome: parseVerdictOutcome(payload.last_agent_message) };
+  }
+
+  return undefined;
+}
+
+function parseVerdictOutcome(lastAgentMessage) {
+  if (typeof lastAgentMessage !== "string") {
+    return undefined;
+  }
+
+  let verdict;
+  try {
+    verdict = JSON.parse(lastAgentMessage);
+  } catch {
+    return undefined;
+  }
+
+  const outcome = verdict?.outcome;
+  return outcome === "allow" || outcome === "deny" ? outcome : undefined;
+}
+
+export function parseGuardianTranscriptLines(lines, options = {}) {
+  const events = [];
+  for (const line of lines) {
+    if (typeof line !== "string" || line.trim() === "") {
+      continue;
+    }
+    const event = parseGuardianTranscriptLine(line, options);
+    if (event) {
+      events.push(event);
+    }
+  }
+  return events;
+}

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

@@ -33,8 +33,17 @@
 //  - 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).
+//  - PermissionRequest (verified live on 0.139.0, semantics from codex-rs
+//    source): fires ONCE at approval-request creation, BEFORE the request is
+//    routed to the guardian auto-reviewer or the user. Under "Approve for me"
+//    (approvals_reviewer=auto_review, legacy alias guardian_subagent) the user
+//    is never prompted at all, so waiting_approval from this hook over-reports;
+//    the wrapper's codex-guardian-watcher refines it to reviewing /
+//    running_tool / thinking from the guardian's own rollout. The guardian
+//    fires NO hooks itself (SubAgentSource::Other is excluded from Subagent
+//    hooks), so these entries can't see it.
+//  - UNTESTED: PreCompact / SubagentStart|Stop (no 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:

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

@@ -0,0 +1,174 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import {
+  classifyCodexSessionMeta,
+  parseGuardianTranscriptLine,
+  parseGuardianTranscriptLines
+} from "../src/codex-guardian.js";
+
+function metaLine(payload) {
+  return JSON.stringify({ timestamp: "2026-06-12T01:36:41.556Z", type: "session_meta", payload });
+}
+
+test("classifyCodexSessionMeta identifies a main session", () => {
+  const line = metaLine({
+    id: "main-1",
+    parent_thread_id: null,
+    originator: "codex-tui",
+    source: "cli",
+    thread_source: "user"
+  });
+
+  assert.deepEqual(classifyCodexSessionMeta(line), {
+    kind: "main",
+    threadId: "main-1",
+    parentThreadId: undefined
+  });
+});
+
+test("classifyCodexSessionMeta identifies a guardian review session", () => {
+  const line = metaLine({
+    id: "guardian-1",
+    parent_thread_id: "main-1",
+    source: { subagent: { other: "guardian" } },
+    thread_source: "subagent"
+  });
+
+  assert.deepEqual(classifyCodexSessionMeta(line), {
+    kind: "guardian",
+    threadId: "guardian-1",
+    parentThreadId: "main-1"
+  });
+});
+
+test("classifyCodexSessionMeta identifies non-guardian subagent sessions", () => {
+  const bySource = metaLine({
+    id: "agent-1",
+    parent_thread_id: "main-1",
+    source: { subagent: { other: "collab" } }
+  });
+  const byThreadSource = metaLine({
+    id: "agent-2",
+    parent_thread_id: "main-1",
+    source: "cli",
+    thread_source: "subagent"
+  });
+
+  assert.equal(classifyCodexSessionMeta(bySource).kind, "subagent");
+  assert.equal(classifyCodexSessionMeta(byThreadSource).kind, "subagent");
+});
+
+test("classifyCodexSessionMeta rejects non-meta and malformed lines", () => {
+  assert.equal(classifyCodexSessionMeta("not json"), undefined);
+  assert.equal(classifyCodexSessionMeta("{}"), undefined);
+  assert.equal(
+    classifyCodexSessionMeta(JSON.stringify({ type: "response_item", payload: { type: "message" } })),
+    undefined
+  );
+  assert.equal(classifyCodexSessionMeta(metaLine(null)), undefined);
+});
+
+test("parseGuardianTranscriptLine maps task_started to review_started", () => {
+  const line = JSON.stringify({
+    timestamp: "2026-06-12T01:36:41.557Z",
+    type: "event_msg",
+    payload: { type: "task_started", turn_id: "turn-1" }
+  });
+
+  assert.deepEqual(parseGuardianTranscriptLine(line), { type: "review_started" });
+});
+
+test("parseGuardianTranscriptLine extracts the verdict from task_complete", () => {
+  const allow = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_complete", turn_id: "turn-1", last_agent_message: '{"outcome":"allow"}' }
+  });
+  const deny = JSON.stringify({
+    type: "event_msg",
+    payload: {
+      type: "task_complete",
+      turn_id: "turn-2",
+      last_agent_message:
+        '{"risk_level":"high","user_authorization":"low","outcome":"deny","rationale":"too risky"}'
+    }
+  });
+
+  assert.deepEqual(parseGuardianTranscriptLine(allow), { type: "review_finished", outcome: "allow" });
+  assert.deepEqual(parseGuardianTranscriptLine(deny), { type: "review_finished", outcome: "deny" });
+});
+
+test("parseGuardianTranscriptLine reports an unknown outcome when the verdict is unreadable", () => {
+  const garbled = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_complete", turn_id: "turn-1", last_agent_message: "I think it is fine" }
+  });
+  const missing = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_complete", turn_id: "turn-1" }
+  });
+  const unexpected = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_complete", turn_id: "turn-1", last_agent_message: '{"outcome":"maybe"}' }
+  });
+
+  assert.deepEqual(parseGuardianTranscriptLine(garbled), { type: "review_finished", outcome: undefined });
+  assert.deepEqual(parseGuardianTranscriptLine(missing), { type: "review_finished", outcome: undefined });
+  assert.deepEqual(parseGuardianTranscriptLine(unexpected), { type: "review_finished", outcome: undefined });
+});
+
+test("parseGuardianTranscriptLine ignores unrelated and malformed records", () => {
+  assert.equal(parseGuardianTranscriptLine("not json"), undefined);
+  assert.equal(
+    parseGuardianTranscriptLine(
+      JSON.stringify({ type: "event_msg", payload: { type: "token_count" } })
+    ),
+    undefined
+  );
+  assert.equal(
+    parseGuardianTranscriptLine(
+      JSON.stringify({ type: "response_item", payload: { type: "message", role: "assistant" } })
+    ),
+    undefined
+  );
+});
+
+test("parseGuardianTranscriptLine skips records from before the session start", () => {
+  const old = JSON.stringify({
+    timestamp: "2026-06-12T01:00:00.000Z",
+    type: "event_msg",
+    payload: { type: "task_started", turn_id: "turn-0" }
+  });
+  const fresh = JSON.stringify({
+    timestamp: "2026-06-12T02:00:00.000Z",
+    type: "event_msg",
+    payload: { type: "task_started", turn_id: "turn-1" }
+  });
+  const untimestamped = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_started", turn_id: "turn-2" }
+  });
+  const minTimestampMs = Date.parse("2026-06-12T01:30:00.000Z");
+
+  assert.equal(parseGuardianTranscriptLine(old, { minTimestampMs }), undefined);
+  assert.deepEqual(parseGuardianTranscriptLine(fresh, { minTimestampMs }), { type: "review_started" });
+  assert.deepEqual(parseGuardianTranscriptLine(untimestamped, { minTimestampMs }), {
+    type: "review_started"
+  });
+});
+
+test("parseGuardianTranscriptLines collects events and skips blank lines", () => {
+  const lines = [
+    "",
+    JSON.stringify({ type: "event_msg", payload: { type: "task_started", turn_id: "t1" } }),
+    "   ",
+    JSON.stringify({
+      type: "event_msg",
+      payload: { type: "task_complete", turn_id: "t1", last_agent_message: '{"outcome":"allow"}' }
+    })
+  ];
+
+  assert.deepEqual(parseGuardianTranscriptLines(lines), [
+    { type: "review_started" },
+    { type: "review_finished", outcome: "allow" }
+  ]);
+});

package/packages/cli-core/src/codex-guardian-watcher.js

@@ -0,0 +1,136 @@
+// Tails the Codex guardian-review trunk rollout and reports review lifecycle
+// events. With `approvals_reviewer = auto_review` ("Approve for me"), Codex
+// never shows the human approval UI for guardian-routed requests — the
+// PermissionRequest hook fires at request creation, then a guardian subagent
+// decides. No hook fires when the review starts or finishes and the
+// GuardianAssessment events are not persisted to the main rollout, so the
+// guardian's own rollout (one trunk per parent thread, one turn per review) is
+// the only observable, event-backed signal. This watcher exists so the pet can
+// show "reviewing" during the auto-review instead of a false "waiting for
+// approval", without ever clearing a real pending approval on a guess.
+import { join } from "node:path";
+import {
+  classifyCodexSessionMeta,
+  parseGuardianTranscriptLines
+} from "../../adapters/src/codex-guardian.js";
+import { listJsonlFiles, readFirstLine, readRange, safeMtime, safeSize } from "./codex-rollout-fs.js";
+
+const DEFAULT_POLL_MS = 700;
+const MTIME_SKEW_MS = 2000;
+
+export function watchCodexGuardianReviews(options = {}) {
+  const {
+    homeDir = process.env.USERPROFILE || process.env.HOME,
+    startedAt = 0,
+    onReviewEvent = () => {},
+    pollIntervalMs = DEFAULT_POLL_MS,
+    sessionsRoot,
+    setInterval: setIntervalFn = setInterval,
+    clearInterval: clearIntervalFn = clearInterval
+  } = options;
+
+  const root = sessionsRoot ?? (homeDir ? join(homeDir, ".codex", "sessions") : undefined);
+  const minMtime = startedAt > 0 ? startedAt - MTIME_SKEW_MS : 0;
+
+  // session_meta classifications are immutable once written, so cache them by
+  // path. A file with no complete first line yet is NOT cached — it is retried
+  // on the next poll (the rollout may still be flushing).
+  const metaByPath = new Map();
+  let mainThreadId;
+  let trunkPath;
+  let offset = 0;
+  let carry = "";
+
+  const classify = (file) => {
+    if (metaByPath.has(file)) {
+      return metaByPath.get(file);
+    }
+    const firstLine = readFirstLine(file);
+    if (firstLine === undefined) {
+      return undefined;
+    }
+    const meta = classifyCodexSessionMeta(firstLine) ?? null;
+    metaByPath.set(file, meta);
+    return meta;
+  };
+
+  const discoverTrunk = () => {
+    let newestMain;
+    let newestTrunk;
+
+    for (const file of listJsonlFiles(root)) {
+      const mtime = safeMtime(file);
+      if (mtime < minMtime) {
+        continue;
+      }
+      const meta = classify(file);
+      if (!meta) {
+        continue;
+      }
+
+      if (meta.kind === "main" && meta.threadId && (!newestMain || mtime > newestMain.mtime)) {
+        newestMain = { threadId: meta.threadId, mtime };
+      }
+      if (meta.kind === "guardian" && (!newestTrunk || mtime > newestTrunk.mtime)) {
+        newestTrunk = { file, parentThreadId: meta.parentThreadId, mtime };
+      }
+    }
+
+    // The guardian trunk only appears at the first review, usually long after
+    // the main rollout — bind the main thread first, then match the trunk to
+    // it so another session's (or a collab subagent's) reviews are ignored.
+    mainThreadId = mainThreadId ?? newestMain?.threadId;
+    if (mainThreadId && newestTrunk?.parentThreadId === mainThreadId) {
+      // Replay the trunk from the start: the first review is usually still in
+      // progress when we find the file, and the per-record timestamp filter
+      // keeps an earlier session's reviews from replaying as live events.
+      trunkPath = newestTrunk.file;
+      offset = 0;
+      carry = "";
+    }
+  };
+
+  const tick = () => {
+    try {
+      if (!trunkPath) {
+        discoverTrunk();
+        if (!trunkPath) {
+          return;
+        }
+      }
+
+      const size = safeSize(trunkPath);
+      if (size <= offset) {
+        if (size < offset) {
+          offset = size;
+          carry = "";
+        }
+        return;
+      }
+
+      const chunk = readRange(trunkPath, offset, size);
+      offset = size;
+
+      const lines = (carry + chunk).split("\n");
+      carry = lines.pop() ?? "";
+
+      for (const event of parseGuardianTranscriptLines(lines, { minTimestampMs: startedAt })) {
+        onReviewEvent(event);
+      }
+    } catch {
+      // best-effort: rollout surprises must never crash the wrapper
+    }
+  };
+
+  const timer = setIntervalFn(tick, pollIntervalMs);
+  if (timer && typeof timer.unref === "function") {
+    timer.unref();
+  }
+
+  return {
+    stop() {
+      clearIntervalFn(timer);
+    },
+    _tick: tick
+  };
+}

package/packages/cli-core/src/codex-rollout-fs.js

@@ -0,0 +1,88 @@
+// Shared best-effort filesystem helpers for tailing Codex rollout JSONL files
+// (~/.codex/sessions/<y>/<m>/<d>/rollout-*.jsonl). Used by the main transcript
+// watcher and the guardian-review watcher. Every helper swallows fs errors —
+// rollout surprises must never crash the wrapper.
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+// A session_meta first line is normally a few KB, but guardian trunks embed the
+// reviewer's full base instructions (~10 KB observed); leave generous headroom.
+const FIRST_LINE_MAX_BYTES = 262_144;
+
+export function listJsonlFiles(root) {
+  const files = [];
+  if (!root || !existsSync(root)) {
+    return files;
+  }
+
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+        files.push(full);
+      }
+    }
+  }
+
+  return files;
+}
+
+export function safeSize(path) {
+  try {
+    return statSync(path).size;
+  } catch {
+    return 0;
+  }
+}
+
+export function safeMtime(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+export function readRange(path, start, end) {
+  const length = end - start;
+  if (length <= 0) {
+    return "";
+  }
+  const fd = openSync(path, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    const bytesRead = readSync(fd, buffer, 0, length, start);
+    return buffer.toString("utf8", 0, bytesRead);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// First newline-terminated line of a file, or undefined while none exists yet
+// (a rollout that was just created and not flushed). Callers must treat
+// undefined as "retry later", never as a final classification.
+export function readFirstLine(path, maxBytes = FIRST_LINE_MAX_BYTES) {
+  let chunk;
+  try {
+    chunk = readRange(path, 0, Math.min(safeSize(path), maxBytes));
+  } catch {
+    return undefined;
+  }
+
+  const newlineIndex = chunk.indexOf("\n");
+  if (newlineIndex === -1) {
+    return undefined;
+  }
+  return chunk.slice(0, newlineIndex);
+}

package/packages/cli-core/src/codex-transcript-watcher.js

@@ -1,16 +1,10 @@
 // Tails Codex session JSONL and reports tool start/finish activity. Codex hooks
 // cover turn lifecycle, but the transcript is the reliable source for tool use
 // when PreToolUse is unavailable.
-import {
-  closeSync,
-  existsSync,
-  openSync,
-  readdirSync,
-  readSync,
-  statSync
-} from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { parseCodexTranscriptLines } from "../../adapters/src/codex-transcript.js";
+import { listJsonlFiles, readRange, safeMtime, safeSize } from "./codex-rollout-fs.js";
 
 const DEFAULT_POLL_MS = 700;
 const MTIME_SKEW_MS = 2000;
@@ -101,60 +95,3 @@ export function discoverCodexTranscript(root, minMtime = 0) {
   }
   return newest?.file;
 }
-
-function listJsonlFiles(root) {
-  const files = [];
-  const stack = [root];
-
-  while (stack.length > 0) {
-    const dir = stack.pop();
-    let entries;
-    try {
-      entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      const full = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(full);
-      } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
-        files.push(full);
-      }
-    }
-  }
-
-  return files;
-}
-
-function safeSize(path) {
-  try {
-    return statSync(path).size;
-  } catch {
-    return 0;
-  }
-}
-
-function safeMtime(path) {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return 0;
-  }
-}
-
-function readRange(path, start, end) {
-  const length = end - start;
-  if (length <= 0) {
-    return "";
-  }
-  const fd = openSync(path, "r");
-  try {
-    const buffer = Buffer.alloc(length);
-    const bytesRead = readSync(fd, buffer, 0, length, start);
-    return buffer.toString("utf8", 0, bytesRead);
-  } finally {
-    closeSync(fd);
-  }
-}

package/packages/cli-core/test/codex-guardian-watcher.test.mjs

@@ -0,0 +1,217 @@
+import assert from "node:assert/strict";
+import { appendFileSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "../../../test/harness.mjs";
+import { watchCodexGuardianReviews } from "../src/codex-guardian-watcher.js";
+
+const noopTimers = { setInterval: () => ({}), clearInterval: () => {} };
+
+function metaLine(payload) {
+  return `${JSON.stringify({ type: "session_meta", payload })}\n`;
+}
+
+function reviewStarted(turnId = "turn-1", timestamp) {
+  return `${JSON.stringify({
+    ...(timestamp ? { timestamp } : {}),
+    type: "event_msg",
+    payload: { type: "task_started", turn_id: turnId }
+  })}\n`;
+}
+
+function reviewFinished(outcome, turnId = "turn-1") {
+  return `${JSON.stringify({
+    type: "event_msg",
+    payload: {
+      type: "task_complete",
+      turn_id: turnId,
+      last_agent_message: JSON.stringify({ outcome })
+    }
+  })}\n`;
+}
+
+function makeSessionsRoot() {
+  const root = mkdtempSync(join(tmpdir(), "codex-guardian-"));
+  const dir = join(root, "2026", "06", "12");
+  mkdirSync(dir, { recursive: true });
+  return { root, dir };
+}
+
+test("watchCodexGuardianReviews tails the guardian trunk of the main session", () => {
+  const { root, dir } = makeSessionsRoot();
+  writeFileSync(
+    join(dir, "rollout-main.jsonl"),
+    metaLine({ id: "main-1", parent_thread_id: null, source: "cli", thread_source: "user" })
+  );
+  // A non-guardian subagent of the same parent must not be tailed.
+  writeFileSync(
+    join(dir, "rollout-collab.jsonl"),
+    metaLine({ id: "agent-1", parent_thread_id: "main-1", source: { subagent: { other: "collab" } } }) +
+      reviewStarted("decoy")
+  );
+  const trunkPath = join(dir, "rollout-guardian.jsonl");
+  writeFileSync(
+    trunkPath,
+    metaLine({ id: "guardian-1", parent_thread_id: "main-1", source: { subagent: { other: "guardian" } } })
+  );
+
+  const events = [];
+  const watcher = watchCodexGuardianReviews({
+    sessionsRoot: root,
+    onReviewEvent: (event) => events.push(event),
+    ...noopTimers
+  });
+
+  watcher._tick();
+  assert.deepEqual(events, [], "no review turns yet");
+
+  appendFileSync(trunkPath, reviewStarted());
+  watcher._tick();
+  appendFileSync(trunkPath, reviewFinished("allow"));
+  watcher._tick();
+
+  assert.deepEqual(events, [
+    { type: "review_started" },
+    { type: "review_finished", outcome: "allow" }
+  ]);
+
+  watcher.stop();
+});
+
+test("watchCodexGuardianReviews replays a trunk discovered after the review began", () => {
+  const { root, dir } = makeSessionsRoot();
+  writeFileSync(
+    join(dir, "rollout-main.jsonl"),
+    metaLine({ id: "main-1", parent_thread_id: null, source: "cli", thread_source: "user" })
+  );
+  writeFileSync(
+    join(dir, "rollout-guardian.jsonl"),
+    metaLine({ id: "guardian-1", parent_thread_id: "main-1", source: { subagent: { other: "guardian" } } }) +
+      reviewStarted("turn-1") +
+      reviewFinished("deny", "turn-1")
+  );
+
+  const events = [];
+  const watcher = watchCodexGuardianReviews({
+    sessionsRoot: root,
+    onReviewEvent: (event) => events.push(event),
+    ...noopTimers
+  });
+
+  watcher._tick();
+
+  assert.deepEqual(events, [
+    { type: "review_started" },
+    { type: "review_finished", outcome: "deny" }
+  ]);
+
+  watcher.stop();
+});
+
+test("watchCodexGuardianReviews skips review records from before the session start", () => {
+  const { root, dir } = makeSessionsRoot();
+  writeFileSync(
+    join(dir, "rollout-main.jsonl"),
+    metaLine({ id: "main-1", parent_thread_id: null, source: "cli", thread_source: "user" })
+  );
+  writeFileSync(
+    join(dir, "rollout-guardian.jsonl"),
+    metaLine({ id: "guardian-1", parent_thread_id: "main-1", source: { subagent: { other: "guardian" } } }) +
+      reviewStarted("turn-old", "2026-06-12T00:00:00.000Z") +
+      reviewStarted("turn-new", "2026-06-12T02:00:00.000Z")
+  );
+
+  const events = [];
+  const watcher = watchCodexGuardianReviews({
+    sessionsRoot: root,
+    startedAt: Date.parse("2026-06-12T01:00:00.000Z"),
+    onReviewEvent: (event) => events.push(event),
+    ...noopTimers
+  });
+
+  watcher._tick();
+
+  assert.deepEqual(events, [{ type: "review_started" }]);
+
+  watcher.stop();
+});
+
+test("watchCodexGuardianReviews emits nothing without a classifiable main session", () => {
+  const { root, dir } = makeSessionsRoot();
+  // Guardian trunk exists but there is no main rollout to bind its parent to.
+  writeFileSync(
+    join(dir, "rollout-guardian.jsonl"),
+    metaLine({ id: "guardian-1", parent_thread_id: "main-1", source: { subagent: { other: "guardian" } } }) +
+      reviewStarted()
+  );
+
+  const events = [];
+  const watcher = watchCodexGuardianReviews({
+    sessionsRoot: root,
+    onReviewEvent: (event) => events.push(event),
+    ...noopTimers
+  });
+
+  watcher._tick();
+  watcher._tick();
+
+  assert.deepEqual(events, []);
+
+  watcher.stop();
+});
+
+test("watchCodexGuardianReviews ignores guardian trunks of other parents", () => {
+  const { root, dir } = makeSessionsRoot();
+  writeFileSync(
+    join(dir, "rollout-main.jsonl"),
+    metaLine({ id: "main-1", parent_thread_id: null, source: "cli", thread_source: "user" })
+  );
+  writeFileSync(
+    join(dir, "rollout-guardian-other.jsonl"),
+    metaLine({ id: "guardian-9", parent_thread_id: "someone-else", source: { subagent: { other: "guardian" } } }) +
+      reviewStarted()
+  );
+
+  const events = [];
+  const watcher = watchCodexGuardianReviews({
+    sessionsRoot: root,
+    onReviewEvent: (event) => events.push(event),
+    ...noopTimers
+  });
+
+  watcher._tick();
+
+  assert.deepEqual(events, []);
+
+  watcher.stop();
+});
+
+test("watchCodexGuardianReviews picks up a trunk created after watching began", () => {
+  const { root, dir } = makeSessionsRoot();
+  writeFileSync(
+    join(dir, "rollout-main.jsonl"),
+    metaLine({ id: "main-1", parent_thread_id: null, source: "cli", thread_source: "user" })
+  );
+
+  const events = [];
+  const watcher = watchCodexGuardianReviews({
+    sessionsRoot: root,
+    onReviewEvent: (event) => events.push(event),
+    ...noopTimers
+  });
+
+  watcher._tick();
+  assert.deepEqual(events, [], "no trunk yet");
+
+  const trunkPath = join(dir, "rollout-guardian.jsonl");
+  writeFileSync(
+    trunkPath,
+    metaLine({ id: "guardian-1", parent_thread_id: "main-1", source: { subagent: { other: "guardian" } } }) +
+      reviewStarted()
+  );
+  watcher._tick();
+
+  assert.deepEqual(events, [{ type: "review_started" }]);
+
+  watcher.stop();
+});