@hayasaka7/haya-pet 0.3.8 → 0.3.10

package/CHANGELOG.md

@@ -7,6 +7,41 @@ 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.3.10]
+
+### Fixed
+- **A running Claude Code subagent no longer drives the main session's status.**
+  With hooks enabled and a multi-agent run, once the main agent had stopped but a
+  subagent was still working, two things went wrong: the pet dropped to *idle*
+  (even though work was ongoing), and while the subagent ran its tool calls flipped
+  the pet between *running tools* / *editing files* / *thinking*. Fix, checked
+  **only at the main agent's `Stop`** (no timers, no persisted state): (1) Claude's
+  `Stop` payload carries a live `background_tasks` snapshot — when it still lists a
+  running **subagent**, the pet shows *running tools* with the message **"Subagent
+  running"**, and the follow-up `Stop` (empty `background_tasks`) clears it back to
+  *idle*; (2) every subagent-originated hook event carries an `agent_id`, so the
+  reporter now **drops any event with an `agent_id`**, and a subagent's activity can
+  no longer overwrite the main session's status. Background **shells** are
+  deliberately not surfaced (their completion isn't reliably observable). See
+  `docs/known-issues.md`.
+
+## [0.3.9]
+
+### Fixed
+- **The cross-session contamination fix now covers Codex too.** Codex had the same
+  flaw fixed for Claude in 0.3.8: its transcript watcher chose the rollout by
+  newest mtime + cwd, and the guardian-review watcher derived the main thread id
+  from the newest main rollout — so two Codex sessions in the same folder could
+  cross-report each other's `turn_aborted` (interrupt) or tool activity, with the
+  idle session showing the busy one's state. Codex's command-hook payload also
+  carries `transcript_path`, so the `haya-pet state` reporter's per-session
+  `session → transcript` link (already written for every client) now pins the Codex
+  transcript watcher to its own rollout, and the guardian watcher binds the main
+  thread id from the linked rollout's `payload.id` (and only follows a trunk whose
+  `parent_thread_id` matches it). Both fall back to the previous mtime+cwd heuristic
+  when no link is available (e.g. `transcript_path` null early), so there is no
+  regression. No timer involved.
+
 ## [0.3.8]
 
 ### Fixed
@@ -19,8 +54,8 @@ All notable changes to HAYA Pet are documented here. This project adheres to
   session's watcher now pins to its own transcript via the `transcript_path` Claude
   includes in every hook payload (recorded as a per-session link by the `haya-pet
   state` reporter) instead of guessing; until that link exists it idles rather than
-  locking onto another session's file. Codex shares the same discovery shape and is
-  tracked as a known issue.
+  locking onto another session's file. (Codex had the same discovery shape — fixed
+  in 0.3.9.)
 - **The pet no longer disappears when the display layout changes.** The overlay
   window's bounds were set once at creation to span one display's work area and
   never re-homed, so unplugging a monitor, changing resolution/DPI, docking or

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

@@ -5,7 +5,7 @@ import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runGenericCommand as defaultRunGenericCommand } from "../../../packages/cli-core/src/run-command.js";
-import { parseStateArgs, runStateCommand, readHookTranscriptPathFromStdin } from "../../../packages/cli-core/src/run-state.js";
+import { parseStateArgs, runStateCommand, readHookPayloadFromStdin } from "../../../packages/cli-core/src/run-state.js";
 import { removeSessionTranscriptLink } from "../../../packages/cli-core/src/session-transcript-link.js";
 import { injectClaudeHooks as defaultInjectClaudeHooks } from "../../../packages/cli-core/src/claude-hook-injection.js";
 import { injectCodexHooks as defaultInjectCodexHooks } from "../../../packages/cli-core/src/codex-hook-injection.js";
@@ -434,12 +434,20 @@ async function runRunCommand(parsed, dependencies) {
       };
       cleanup = injected.cleanup;
 
+      // Pin both Codex watchers to THIS session's rollout via the
+      // session->transcript link the `haya-pet state` reporter records from the
+      // hook payload's transcript_path, instead of guessing newest-by-mtime (which
+      // leaks a concurrent same-cwd session's activity/interrupts).
+      const sessionDir = resolveSessionDir(dependencies, env);
+
       const activeToolCalls = new Set();
       const watcher = watchCodexTranscript({
         homeDir: dependencies.homeDir,
         sessionsRoot: dependencies.codexSessionsRoot,
         cwd,
         startedAt: now(),
+        sessionId,
+        sessionDir,
         onToolEvent: (event) => {
           hookDebugLog(env, now, {
             source: "codex_transcript",
@@ -522,6 +530,8 @@ async function runRunCommand(parsed, dependencies) {
         sessionsRoot: dependencies.codexSessionsRoot,
         cwd,
         startedAt: now(),
+        sessionId,
+        sessionDir,
         onReviewEvent: (event) => {
           hookDebugLog(env, now, {
             source: "codex_guardian",
@@ -550,6 +560,7 @@ async function runRunCommand(parsed, dependencies) {
       stopWatcher = () => {
         guardianWatcher.stop();
         stopWithoutGuardian();
+        removeSessionTranscriptLink({ sessionDir, sessionId });
       };
     }
   }
@@ -958,20 +969,31 @@ if (isDirectRun(import.meta.url, process.argv[1])) {
 }
 
 // Real-process entry. For a `haya-pet state` invocation — which is ALWAYS a client
-// hook child — read the hook payload from stdin once to learn this session's real
-// transcript path, and hand it to the reporter so it can record the
-// session->transcript link. Done here (not inside main/runStateCommand) so unit
-// tests, and every other command that needs stdin passed through to its child
-// (e.g. `run`), never touch stdin.
+// hook child — read the hook payload from stdin once to learn: this session's real
+// transcript path (for the session->transcript link); the live background_tasks
+// snapshot (so a Stop with a still-running subagent keeps a working cue instead of
+// idle); and the agent_id (present only for subagent-originated events, which the
+// reporter drops so a subagent's activity never overwrites the main status). All
+// are handed to the reporter via dependencies. Done here (not inside
+// main/runStateCommand) so unit tests, and every other command that needs stdin
+// passed through to its child (e.g. `run`), never touch stdin.
 async function bootstrap() {
   const argv = process.argv.slice(2);
   const dependencies = {};
   if (argv[0] === "state") {
     try {
-      const transcriptPath = await readHookTranscriptPathFromStdin();
+      const { transcriptPath, backgroundTasks, agentId } = await readHookPayloadFromStdin();
       if (transcriptPath) {
         dependencies.transcriptPath = transcriptPath;
       }
+      if (Array.isArray(backgroundTasks) && backgroundTasks.length > 0) {
+        dependencies.backgroundTasks = backgroundTasks;
+      }
+      // Present only for subagent-originated events — the reporter drops those so a
+      // subagent's tool use never overwrites the main session's status.
+      if (agentId) {
+        dependencies.agentId = agentId;
+      }
     } catch {
       // a missing/garbled payload just means no binding this time — never fatal
     }

package/docs/known-issues.md

@@ -2,38 +2,34 @@
 
 Issues found in live use, with their current status.
 
-## 🔲 Open: cross-session status contamination on Codex
-
-- **Symptom (same class as the resolved Claude entry below):** interrupting one
-  Codex session can flip a **different, concurrent** Codex session's pet to
-  *interrupted* (and more generally mirror another session's tool/working
-  states). Most likely when two Codex sessions run in the **same folder** and one
-  is busy while the other is idle. Not yet fixed.
-- **Root cause:** `discoverCodexTranscript` (`codex-transcript-watcher.js`) picks
-  the rollout by **newest `.jsonl` by mtime**, filtered only by
-  `session_meta.cwd` / freshness — it does **not** bind to a specific session, so
-  an idle session's watcher can lock onto a busy session's rollout and then read
-  that session's `turn_aborted` (Codex's interrupt signal) as its own. The rollout
-  *does* identify itself (`session_meta.payload.id` = the Codex thread id, plus a
-  unique per-session filename), but (1) we never learn **which** thread id belongs
-  to the session our wrapper launched — the Codex hooks pass only
-  `HAYA_PET_SESSION_ID` via env and the reporter currently **discards Codex's hook
-  stdin** — and (2) the watcher matches on mtime+cwd, not on that id. The
-  `isFreshSession` branch even admits recently-started rollouts from **other
-  cwds**, so the exposure is slightly *wider* than Claude's (which is scoped to one
-  project dir). This is the residual same-session-folder case the earlier
-  "Codex pet looked busy immediately after startup" fix narrowed but did not
-  eliminate.
-- **Plan (handle later):** port the Claude binding to Codex. Verify against the
-  live Codex CLI whether the hook **stdin payload** carries the rollout path or
-  the thread id (`session_id`); if so, have the `haya-pet state` reporter record a
-  per-session session→rollout link (reusing `session-transcript-link.js`) and pin
-  the watcher to it — or, failing that, match `session_meta.payload.id` once we
-  can learn our session's id. Fall back to current behavior when no identifier is
-  available. No timer, consistent with the rest of the status model.
-- **Status:** unfixed. The binding fix shipped this session is **Claude-only** and
-  does not touch the Codex watcher or the guardian-review watcher (which shares the
-  same discovery shape and should be checked alongside it).
+## ✅ Resolved: cross-session status contamination on Codex
+
+- **Symptom (same class as the Claude entry below):** interrupting one Codex
+  session could flip a **different, concurrent** Codex session's pet to
+  *interrupted* (and more generally mirror another session's tool/working states).
+  Most likely when two Codex sessions ran in the **same folder** and one was busy
+  while the other was idle.
+- **Root cause:** `discoverCodexTranscript` (`codex-transcript-watcher.js`) picked
+  the rollout by **newest `.jsonl` by mtime**, filtered only by `session_meta.cwd`
+  / freshness — it did **not** bind to a specific session, so an idle session's
+  watcher could lock onto a busy session's rollout and read that session's
+  `turn_aborted` (Codex's interrupt signal) as its own. The `isFreshSession` branch
+  even admitted recently-started rollouts from **other cwds**, so the exposure was
+  slightly *wider* than Claude's (scoped to one project dir). The guardian-review
+  watcher had the same flaw: it derived the main thread id from the newest main
+  rollout by mtime, so a concurrent session's review status could be misattributed.
+- **Fix:** the same per-session binding used for Claude. Verified against the
+  OpenAI Codex docs that the command-hook stdin payload carries **`transcript_path`**
+  (and `session_id`, the conversation/rollout id — which I also confirmed on disk
+  equals `session_meta.payload.id` and the rollout filename uuid). The
+  `haya-pet state` reporter already records a per-session `session→transcript` link
+  from that `transcript_path` (the capture is client-agnostic), so the Codex
+  transcript watcher now pins to its own rollout via the link
+  (`session-transcript-link.js`) instead of guessing newest-by-mtime, and the
+  guardian watcher derives the main thread id from the **linked** rollout's
+  `payload.id` (and only considers a trunk whose `parent_thread_id` matches it).
+  Both fall back to the old heuristic when no link is available (e.g. `transcript_path`
+  null early), so there is no regression. No timer involved.
 
 ## ✅ Resolved: Claude interrupt/denial leaked into a concurrent idle session
 
@@ -154,19 +150,60 @@ Issues found in live use, with their current status.
   to *thinking* (the agent continues the turn) and the next real event refines it.
   Verified live on the manual path; auto uses the identical matcher mechanism.
 
-## ✅ Resolved: Claude Code subagent completion changed the main session status
-
-- **Symptom:** In Claude Code multi-agent runs, the main agent could already be
-  stopped while a subagent was still finishing. When that late subagent emitted
-  `SubagentStop`, the pet treated it as a main-session `idle` update and could
-  show a misleading working/done transition after the main agent had settled.
-- **Root cause:** The Claude hook table mapped `SubagentStop` to `idle`. That is
-  only safe if subagent completion is ordered before the main turn finishes, which
-  Claude Code does not guarantee.
-- **Fix:** Claude `SubagentStop` is now ignored. Main-session idle still comes
-  from Claude's real `Stop` hook, while late subagent completion cannot override
-  the current main-agent state. Codex keeps its separate behavior because Codex
-  uses `Stop` as the only idle signal and treats `SubagentStop` as mid-turn.
+## ✅ Resolved: subagent activity drove the main session status (Claude Code)
+
+- **Symptom:** With Claude Code hooks enabled and a multi-agent run, two things
+  went wrong once the **main agent had stopped but a subagent was still working**:
+  (1) the pet dropped to *idle* even though real work was ongoing in the
+  background; and (2) while the subagent ran, its own tool calls flipped the pet
+  between *running tools* / *editing files* / *thinking* — the subagent's activity
+  was driving the main session's status.
+- **Root cause:** Two gaps. (a) The hook table mapped `Stop` → *idle*
+  unconditionally, with no awareness that a backgrounded subagent can outlive the
+  main turn. (b) A backgrounded subagent's tool calls fire the **parent session's**
+  `PreToolUse` / `PostToolUse` hooks, which ran `haya-pet state running_tool`
+  (etc.) under the main session id and overwrote its status. (An earlier fix only
+  stopped `SubagentStop` from reporting *idle*; it addressed neither of these.)
+- **Fix — only ever decided at the main agent's `Stop`; no timers, no persisted
+  state:**
+  - **The "Subagent running" cue.** Claude's `Stop` payload carries an
+    (undocumented) **`background_tasks`** array: a live snapshot of work still
+    running at that instant. When `Stop` would report *idle* but `background_tasks`
+    still lists a running **subagent**, the reporter instead reports *running
+    tools* with the summary **"Subagent running"**
+    (`packages/cli-core/src/background-tasks.js`). When that subagent finishes,
+    Claude fires `Stop` **again** with an empty `background_tasks`, which clears the
+    cue back to *idle* — self-retracting, no timer. (Verified against live hook
+    traces: a backgrounded subagent appears in `Stop`'s `background_tasks` as
+    `type:"subagent", status:"running"`, and a second `Stop` arrives with `[]` once
+    it completes.)
+  - **Subagent events are dropped.** Every hook payload from a subagent context
+    carries an **`agent_id`** — the documented field that distinguishes subagent
+    hook calls from main-thread calls. The reporter now drops any event with an
+    `agent_id` (`extractAgentId` in `run-state.js`), so a subagent's tool use can
+    never overwrite the main session's status. Main-agent events have no `agent_id`
+    and report as before; the main `Stop` (also no `agent_id`) still carries the
+    `background_tasks` snapshot used for the cue above. `SubagentStop` is likewise
+    not wired.
+- **Known limitations (accepted):**
+  - **Only subagents, never background shells.** A `background_tasks` entry can
+    also be `type:"shell"` (e.g. a `sleep 120` the agent backgrounded). These are
+    deliberately **not** surfaced: their completion isn't reliably observable here,
+    and a "working" cue we can't retract is worse than showing *idle*. So a
+    backgrounded shell still running after the main agent stops shows *idle*.
+  - **The `agent_id` discriminator is documented but not yet captured live on
+    `PreToolUse` / `PostToolUse`.** The Claude hooks reference lists `agent_id` /
+    `agent_type` as optional fields delivered to all hooks to distinguish subagent
+    calls, and the observed flicker confirms subagent tool calls reach the parent
+    hooks — but a subagent `PreToolUse` payload hasn't been captured on disk to
+    100% confirm `agent_id` is present there. If a future Claude build omits it the
+    flicker could recur; the marker would then be widened to also match
+    `agent_type` / `agent_transcript_path`.
+- **How to diagnose if it recurs:** with `HAYA_PET_HOOK_DEBUG=<path>` set, the
+  reporter logs an `agentId` field on subagent-sourced events (which it then
+  drops). A subagent event logged with **no** `agentId` is the signal to widen the
+  marker. Codex keeps its separate behavior: it uses `Stop` as the only idle signal
+  and treats `SubagentStop` as mid-turn.
 
 ## ✅ Resolved: false "waiting for approval" while Codex auto-reviews an approval (Approve for me)
 
@@ -430,8 +467,12 @@ observation (`--observe`) or L1 lifecycle as the fallback. Current state:
   `Notification`/`PreCompact`/`PostCompact`/`Stop` events to `haya-pet state <state>`,
   reported to the daemon over the IPC pipe. `PostCompact` is split by its
   `manual`/`auto` trigger matcher (manual `/compact` → *idle*, auto compaction →
-  *thinking*) so the pet never sticks on *compacting*. `SubagentStop` is intentionally ignored because
-  it is not a main-turn idle signal. `PreToolUse` distinguishes
+  *thinking*) so the pet never sticks on *compacting*. Subagent-originated events
+  are **dropped** by the reporter (they carry an `agent_id`), so a subagent's tool
+  use never drives the main status, and `SubagentStop` is not wired; when `Stop`
+  fires while a subagent is still running, its `background_tasks` snapshot surfaces
+  as a *running tools* / "Subagent running" cue that the next (empty) `Stop` clears
+  — see the resolved subagent entry above. `PreToolUse` distinguishes
   file-editing tools (`Edit`/`Write`/`MultiEdit`/`NotebookEdit` → *editing files*)
   from other tools (→ *running tools*) via the hook `matcher`. **Why opt-in:**
   injecting hooks makes Claude show a one-time *review hooks* trust prompt; the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hayasaka7/haya-pet",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "type": "module",
   "description": "Generic AI CLI pet runtime foundation.",
   "keywords": [

package/packages/cli-core/src/background-tasks.js

@@ -0,0 +1,63 @@
+// Pure helpers for the Claude "subagent still running at Stop" cue.
+//
+// When the main Claude agent ends its turn it fires `Stop`, whose payload carries
+// a `background_tasks` array — a live snapshot of work still running at that
+// instant (the hooks docs omit this field; it was verified against live traces).
+// If a backgrounded *subagent* is still running, the main agent is paused but real
+// work continues, so the pet keeps a "working" cue with a message rather than
+// dropping to idle. When that subagent finishes, Claude fires `Stop` AGAIN with an
+// empty `background_tasks`, which naturally clears the cue — so this needs no
+// timers, no persisted state, and no subagent-event wiring. The only check is at
+// the main agent's Stop, exactly as scoped.
+//
+// Scoped to `type: "subagent"` ONLY. Background *shells* are intentionally
+// excluded: their completion isn't reliably observable here, and a status we
+// cannot retract is worse than none.
+
+// A single, fixed cue message. The user only wants to know that a subagent is
+// still working after the main agent paused — NOT which one or how many.
+const SUBAGENT_RUNNING_SUMMARY = "Subagent running";
+
+// Parse a Claude hook payload (JSON on stdin) and return its background_tasks
+// array. Defensive: any non-JSON / missing / wrong-typed input yields [].
+export function extractBackgroundTasks(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed?.background_tasks) ? parsed.background_tasks : [];
+  } catch {
+    return [];
+  }
+}
+
+// The still-running *subagent* tasks. Shells and finished tasks are dropped.
+export function runningSubagentTasks(tasks) {
+  if (!Array.isArray(tasks)) {
+    return [];
+  }
+  return tasks.filter((task) => task && task.type === "subagent" && task.status === "running");
+}
+
+// A fixed cue message when any subagent is still running, or undefined when none
+// are (the caller then leaves the reported state untouched). Intentionally not
+// detailed — just "a subagent is still working".
+export function summarizeSubagentTasks(tasks) {
+  return runningSubagentTasks(tasks).length > 0 ? SUBAGENT_RUNNING_SUMMARY : undefined;
+}
+
+// Decide the effective state/summary for a reported state given the Stop payload's
+// background_tasks. Only an `idle` report with a running subagent is upgraded to a
+// working cue; everything else passes through unchanged — including the follow-up
+// Stop whose background_tasks is empty, which is what retracts the cue.
+export function applySubagentBackgroundTasks({ state, summary, backgroundTasks }) {
+  if (state !== "idle") {
+    return { state, summary };
+  }
+  const message = summarizeSubagentTasks(backgroundTasks);
+  if (!message) {
+    return { state, summary };
+  }
+  return { state: "running_tool", summary: message };
+}

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

@@ -14,6 +14,7 @@ import {
   parseGuardianTranscriptLines
 } from "../../adapters/src/codex-guardian.js";
 import { listJsonlFiles, readFirstLine, readRange, safeMtime, safeSize } from "./codex-rollout-fs.js";
+import { readSessionTranscriptLink } from "./session-transcript-link.js";
 
 const DEFAULT_POLL_MS = 700;
 const MTIME_SKEW_MS = 2000;
@@ -26,6 +27,8 @@ export function watchCodexGuardianReviews(options = {}) {
     onReviewEvent = () => {},
     pollIntervalMs = DEFAULT_POLL_MS,
     sessionsRoot,
+    sessionId,
+    sessionDir,
     setInterval: setIntervalFn = setInterval,
     clearInterval: clearIntervalFn = clearInterval
   } = options;
@@ -66,7 +69,33 @@ export function watchCodexGuardianReviews(options = {}) {
     return meta;
   };
 
+  // Authoritative main thread id from the session->transcript link (the linked
+  // rollout's session_meta.payload.id). Lets the guardian bind to OUR main thread
+  // even when another session's main rollout has a newer mtime.
+  const resolveLinkedMainThreadId = () => {
+    if (!sessionId || !sessionDir) {
+      return undefined;
+    }
+    const linked = readSessionTranscriptLink({ sessionDir, sessionId });
+    if (!linked) {
+      return undefined;
+    }
+    const firstLine = readFirstLine(linked);
+    if (firstLine === undefined) {
+      return undefined;
+    }
+    const meta = classifyCodexSessionMeta(firstLine);
+    return meta?.kind === "main" ? meta.threadId : undefined;
+  };
+
   const discoverTrunk = () => {
+    // Prefer the linked main thread id; fall back to the newest main rollout by
+    // mtime only when no link is available (older behavior, unsafe across
+    // concurrent same-cwd sessions).
+    if (!mainThreadId) {
+      mainThreadId = resolveLinkedMainThreadId();
+    }
+
     let newestMain;
     let newestTrunk;
 
@@ -83,8 +112,12 @@ export function watchCodexGuardianReviews(options = {}) {
       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 };
+      if (meta.kind === "guardian" && meta.parentThreadId && (!newestTrunk || mtime > newestTrunk.mtime)) {
+        // Once our main thread id is known, only consider OUR trunk so a
+        // concurrent session's (or collab subagent's) newer trunk cannot win.
+        if (!mainThreadId || meta.parentThreadId === mainThreadId) {
+          newestTrunk = { file, parentThreadId: meta.parentThreadId, mtime };
+        }
       }
     }
 

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

@@ -5,6 +5,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { parseCodexTranscriptLines } from "../../adapters/src/codex-transcript.js";
 import { listJsonlFiles, readFirstLine, readRange, safeMtime, safeSize } from "./codex-rollout-fs.js";
+import { readSessionTranscriptLink } from "./session-transcript-link.js";
 
 const DEFAULT_POLL_MS = 700;
 const MTIME_SKEW_MS = 2000;
@@ -17,6 +18,8 @@ export function watchCodexTranscript(options = {}) {
     onToolEvent = () => {},
     pollIntervalMs = DEFAULT_POLL_MS,
     sessionsRoot,
+    sessionId,
+    sessionDir,
     transcriptPath: fixedPath,
     setInterval: setIntervalFn = setInterval,
     clearInterval: clearIntervalFn = clearInterval
@@ -25,6 +28,13 @@ export function watchCodexTranscript(options = {}) {
   const root = sessionsRoot ?? (homeDir ? join(homeDir, ".codex", "sessions") : undefined);
   const minMtime = startedAt > 0 ? startedAt - MTIME_SKEW_MS : 0;
 
+  // Preferred resolution: pin to the exact rollout this session's hook reported
+  // (Codex puts `transcript_path` in every hook payload; the `haya-pet state`
+  // reporter records it as a session->transcript link). Without that link (e.g.
+  // the path was null early), fall back to the newest-by-mtime heuristic — unsafe
+  // with concurrent same-cwd sessions, which is the bug the link avoids.
+  const useLink = Boolean(sessionId && sessionDir);
+
   let transcriptPath = fixedPath;
   let offset = 0;
   let carry = "";
@@ -32,7 +42,9 @@ export function watchCodexTranscript(options = {}) {
   const tick = () => {
     try {
       if (!transcriptPath) {
-        transcriptPath = discoverCodexTranscript(root, minMtime, { cwd });
+        transcriptPath = useLink
+          ? resolveLinkedRollout(sessionDir, sessionId)
+          : discoverCodexTranscript(root, minMtime, { cwd });
         if (!transcriptPath) {
           return;
         }
@@ -79,6 +91,18 @@ export function watchCodexTranscript(options = {}) {
   };
 }
 
+// Resolve the rollout this session's hook bound itself to (via the
+// session->transcript link). Returns undefined until the link exists and points
+// at a real file, so before the first hook the watcher idles rather than guessing
+// a rollout that may belong to another concurrent session.
+function resolveLinkedRollout(sessionDir, sessionId) {
+  const linked = readSessionTranscriptLink({ sessionDir, sessionId });
+  if (!linked || !existsSync(linked)) {
+    return undefined;
+  }
+  return linked;
+}
+
 export function discoverCodexTranscript(root, minMtime = 0, options = {}) {
   if (!root || !existsSync(root)) {
     return undefined;

package/packages/cli-core/src/run-state.js

@@ -7,6 +7,7 @@ import { getDefaultPaths } from "../../platform-core/src/paths.js";
 import { isAiClientState } from "../../protocol/src/messages.js";
 import { DEADLINE, raceDeadline } from "./deadline.js";
 import { writeSessionTranscriptLink } from "./session-transcript-link.js";
+import { applySubagentBackgroundTasks, extractBackgroundTasks } from "./background-tasks.js";
 
 // Hard ceiling on the whole connect→send→close interaction. The reporter is a
 // child process of the wrapped AI client, and the client may wait for its hook
@@ -60,8 +61,28 @@ export async function runStateCommand(parsed, dependencies = {}) {
   const env = dependencies.env ?? process.env;
   const now = dependencies.now ?? Date.now;
   const sessionId = parsed.session ?? env.HAYA_PET_SESSION_ID;
+  const agentId = dependencies.agentId;
 
-  debugLog(env, now, { state: parsed.state, sessionId, summary: parsed.summary });
+  debugLog(
+    env,
+    now,
+    agentId
+      ? { state: parsed.state, sessionId, summary: parsed.summary, agentId }
+      : { state: parsed.state, sessionId, summary: parsed.summary }
+  );
+
+  // A subagent's own activity must NEVER drive the main session's status. A
+  // backgrounded subagent's tool calls fire the PARENT session's PreToolUse/
+  // PostToolUse hooks, which would otherwise overwrite the main agent's status
+  // (and the "Subagent running" cue) with running_tool/thinking/editing_files as
+  // the subagent works. The payload's `agent_id` is the documented field that
+  // distinguishes subagent hook calls from main-thread calls — when it's present
+  // the event came from a subagent, so we drop it entirely. The ONE place a
+  // subagent surfaces is the main agent's own Stop (no agent_id), via
+  // background_tasks; see applySubagentBackgroundTasks below.
+  if (agentId) {
+    return { command: "state", ok: false, reason: "subagent-event" };
+  }
 
   if (!sessionId) {
     return { command: "state", ok: false, reason: "no-session" };
@@ -77,6 +98,17 @@ export async function runStateCommand(parsed, dependencies = {}) {
   // session's interrupt/denial. Best-effort and synchronous; never blocks the hook.
   recordTranscriptLink(sessionId, env, dependencies);
 
+  // When the main agent's Stop reports idle but its background_tasks (from the hook
+  // payload, passed in via dependencies) still lists a running subagent, keep a
+  // working cue with a message instead — the main agent is paused but real work
+  // continues. The follow-up Stop carries an empty list and clears it. Scoped to
+  // subagents only; see background-tasks.js.
+  const effective = applySubagentBackgroundTasks({
+    state: parsed.state,
+    summary: parsed.summary,
+    backgroundTasks: dependencies.backgroundTasks
+  });
+
   const createIpcClient = dependencies.createIpcClient ?? defaultCreateIpcClient;
   const deadlineMs = dependencies.reportDeadlineMs ?? REPORT_DEADLINE_MS;
 
@@ -93,8 +125,8 @@ export async function runStateCommand(parsed, dependencies = {}) {
         await client.send({
           type: "state",
           sessionId,
-          state: parsed.state,
-          summary: parsed.summary,
+          state: effective.state,
+          summary: effective.summary,
           confidence: 0.9,
           source: "official_plugin",
           updatedAt: now()
@@ -152,19 +184,50 @@ export function extractTranscriptPath(raw) {
   }
 }
 
-// Read the Claude hook payload from stdin and return its transcript_path. Used by
-// the real `haya-pet state` process (a Claude hook child) — NOT by internal
-// callers, so tests and other commands never touch stdin. Bounded and best-effort:
-// a TTY (manual invocation) or a slow/absent payload resolves to undefined rather
-// than ever hanging the host client's hook.
-export function readHookTranscriptPathFromStdin(options = {}) {
+// Pull `agent_id` out of a Claude hook payload (JSON on stdin). Present only for
+// subagent-originated events (the documented field distinguishing subagent hook
+// calls from main-thread calls); absent for main-agent events. Pure and
+// defensive: any non-JSON, missing-field, or wrong-type input yields undefined.
+export function extractAgentId(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const value = parsed?.agent_id;
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// Read the Claude hook payload from stdin and return everything the reporter
+// needs from it in one read (stdin can only be consumed once): the session's
+// transcript_path (for the watcher binding) and the live background_tasks snapshot
+// (for the subagent-at-Stop cue). Used by the real `haya-pet state` process (a
+// Claude hook child) — NOT by internal callers, so tests and other commands never
+// touch stdin. Bounded and best-effort: a TTY (manual invocation) or a
+// slow/absent payload resolves to empty results rather than ever hanging the host
+// client's hook.
+export async function readHookPayloadFromStdin(options = {}) {
+  const raw = await readHookPayloadRaw(options);
+  return {
+    transcriptPath: extractTranscriptPath(raw),
+    backgroundTasks: extractBackgroundTasks(raw),
+    agentId: extractAgentId(raw)
+  };
+}
+
+// Accumulate the raw payload string from stdin under a hard deadline and byte cap.
+// Always resolves (never rejects); an error or no payload yields "".
+function readHookPayloadRaw(options = {}) {
   const stdin = options.stdin ?? process.stdin;
   const timeoutMs = options.timeoutMs ?? 400;
   const maxBytes = options.maxBytes ?? 1_000_000;
 
   return new Promise((resolve) => {
     if (!stdin || stdin.isTTY) {
-      resolve(undefined);
+      resolve("");
       return;
     }
 
@@ -172,7 +235,7 @@ export function readHookTranscriptPathFromStdin(options = {}) {
     let settled = false;
     let timer;
 
-    const finish = (value) => {
+    const finish = () => {
       if (settled) {
         return;
       }
@@ -188,17 +251,20 @@ export function readHookTranscriptPathFromStdin(options = {}) {
       } catch {
         // detaching is best-effort
       }
-      resolve(value);
+      resolve(data);
     };
 
     const onData = (chunk) => {
       data += chunk;
       if (data.length > maxBytes) {
-        finish(extractTranscriptPath(data));
+        finish();
       }
     };
-    const onEnd = () => finish(extractTranscriptPath(data));
-    const onError = () => finish(undefined);
+    const onEnd = () => finish();
+    const onError = () => {
+      data = "";
+      finish();
+    };
 
     try {
       stdin.setEncoding("utf8");
@@ -206,12 +272,12 @@ export function readHookTranscriptPathFromStdin(options = {}) {
       stdin.on("end", onEnd);
       stdin.on("error", onError);
       stdin.resume();
-      timer = setTimeout(() => finish(extractTranscriptPath(data)), timeoutMs);
+      timer = setTimeout(finish, timeoutMs);
       if (timer && typeof timer.unref === "function") {
         timer.unref();
       }
     } catch {
-      finish(undefined);
+      finish();
     }
   });
 }

package/packages/cli-core/test/background-tasks.test.mjs

@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import {
+  applySubagentBackgroundTasks,
+  extractBackgroundTasks,
+  runningSubagentTasks,
+  summarizeSubagentTasks
+} from "../src/background-tasks.js";
+
+test("extractBackgroundTasks pulls the array out of a Claude Stop payload", () => {
+  const raw = JSON.stringify({
+    hook_event_name: "Stop",
+    background_tasks: [
+      { id: "x", type: "subagent", status: "running", description: "Survey repo structure" }
+    ]
+  });
+  assert.deepEqual(extractBackgroundTasks(raw), [
+    { id: "x", type: "subagent", status: "running", description: "Survey repo structure" }
+  ]);
+});
+
+test("extractBackgroundTasks is defensive about junk, missing field, and wrong types", () => {
+  assert.deepEqual(extractBackgroundTasks("{not json"), []);
+  assert.deepEqual(extractBackgroundTasks(JSON.stringify({ hook_event_name: "Stop" })), []);
+  assert.deepEqual(extractBackgroundTasks(JSON.stringify({ background_tasks: "nope" })), []);
+  assert.deepEqual(extractBackgroundTasks(""), []);
+  assert.deepEqual(extractBackgroundTasks(undefined), []);
+});
+
+test("runningSubagentTasks keeps only running subagents (drops shells and finished)", () => {
+  const tasks = [
+    { id: "a", type: "subagent", status: "running", description: "A" },
+    { id: "b", type: "subagent", status: "completed", description: "B" },
+    { id: "c", type: "shell", status: "running", command: "sleep 120" },
+    null,
+    { id: "d", type: "subagent", status: "running", description: "D" }
+  ];
+  assert.deepEqual(runningSubagentTasks(tasks).map((t) => t.id), ["a", "d"]);
+  assert.deepEqual(runningSubagentTasks(undefined), []);
+  assert.deepEqual(runningSubagentTasks("nope"), []);
+});
+
+test("summarizeSubagentTasks returns a fixed message when any subagent runs (no detail)", () => {
+  // Same generic message regardless of description, agent_type, or count.
+  assert.equal(
+    summarizeSubagentTasks([
+      { type: "subagent", status: "running", description: "Survey repo structure" }
+    ]),
+    "Subagent running"
+  );
+  assert.equal(
+    summarizeSubagentTasks([{ type: "subagent", status: "running", agent_type: "explore" }]),
+    "Subagent running"
+  );
+  assert.equal(
+    summarizeSubagentTasks([
+      { type: "subagent", status: "running", description: "A" },
+      { type: "subagent", status: "running", description: "B" }
+    ]),
+    "Subagent running"
+  );
+});
+
+test("summarizeSubagentTasks returns undefined when nothing is running", () => {
+  assert.equal(summarizeSubagentTasks([]), undefined);
+  assert.equal(summarizeSubagentTasks([{ type: "shell", status: "running" }]), undefined);
+  assert.equal(summarizeSubagentTasks([{ type: "subagent", status: "completed" }]), undefined);
+});
+
+test("applySubagentBackgroundTasks upgrades idle to a working cue when a subagent runs", () => {
+  assert.deepEqual(
+    applySubagentBackgroundTasks({
+      state: "idle",
+      summary: undefined,
+      backgroundTasks: [
+        { type: "subagent", status: "running", description: "Survey repo structure" }
+      ]
+    }),
+    { state: "running_tool", summary: "Subagent running" }
+  );
+});
+
+test("applySubagentBackgroundTasks leaves a non-idle state untouched", () => {
+  assert.deepEqual(
+    applySubagentBackgroundTasks({
+      state: "thinking",
+      summary: "hi",
+      backgroundTasks: [{ type: "subagent", status: "running", description: "A" }]
+    }),
+    { state: "thinking", summary: "hi" }
+  );
+});
+
+test("applySubagentBackgroundTasks passes idle through when nothing runs (the retraction case)", () => {
+  // The follow-up Stop carries an empty background_tasks — this is what clears the cue.
+  assert.deepEqual(
+    applySubagentBackgroundTasks({ state: "idle", summary: undefined, backgroundTasks: [] }),
+    { state: "idle", summary: undefined }
+  );
+  assert.deepEqual(
+    applySubagentBackgroundTasks({ state: "idle", summary: "idle", backgroundTasks: undefined }),
+    { state: "idle", summary: "idle" }
+  );
+});
+
+test("applySubagentBackgroundTasks ignores background shells (deliberately unsupported)", () => {
+  assert.deepEqual(
+    applySubagentBackgroundTasks({
+      state: "idle",
+      summary: undefined,
+      backgroundTasks: [{ type: "shell", status: "running", command: "sleep 120" }]
+    }),
+    { state: "idle", summary: undefined }
+  );
+});

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

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "../../../test/harness.mjs";
 import { watchCodexGuardianReviews } from "../src/codex-guardian-watcher.js";
+import { writeSessionTranscriptLink } from "../src/session-transcript-link.js";
 
 const noopTimers = { setInterval: () => ({}), clearInterval: () => {} };
 
@@ -262,6 +263,53 @@ test("watchCodexGuardianReviews ignores guardian trunks of other parents", () =>
   watcher.stop();
 });
 
+test("watchCodexGuardianReviews binds to the LINKED main thread, not the newest main", () => {
+  const { root, dir } = makeSessionsRoot();
+  const sessionDir = mkdtempSync(join(tmpdir(), "sess-"));
+
+  // Our main rollout, and a DIFFERENT concurrent session's main rollout written
+  // afterwards (so it has the newer mtime — what the old heuristic would pick).
+  const ourMain = join(dir, "rollout-main-ours.jsonl");
+  writeFileSync(ourMain, metaLine({ id: "main-ours", parent_thread_id: null, source: "cli", thread_source: "user" }));
+  writeFileSync(
+    join(dir, "rollout-main-other.jsonl"),
+    metaLine({ id: "main-other", parent_thread_id: null, source: "cli", thread_source: "user" })
+  );
+
+  // A guardian trunk for OUR main, plus a decoy trunk for the OTHER main that is
+  // newer and already has a review turn.
+  const ourTrunk = join(dir, "rollout-guardian-ours.jsonl");
+  writeFileSync(
+    ourTrunk,
+    metaLine({ id: "g-ours", parent_thread_id: "main-ours", source: { subagent: { other: "guardian" } } })
+  );
+  writeFileSync(
+    join(dir, "rollout-guardian-other.jsonl"),
+    metaLine({ id: "g-other", parent_thread_id: "main-other", source: { subagent: { other: "guardian" } } }) +
+      reviewStarted("decoy")
+  );
+
+  writeSessionTranscriptLink({ sessionDir, sessionId: "sess_a", transcriptPath: ourMain });
+
+  const events = [];
+  const watcher = watchCodexGuardianReviews({
+    sessionsRoot: root,
+    sessionId: "sess_a",
+    sessionDir,
+    onReviewEvent: (e) => events.push(e),
+    ...noopTimers
+  });
+
+  watcher._tick();
+  assert.deepEqual(events, [], "the newer decoy trunk (another session) is ignored");
+
+  appendFileSync(ourTrunk, reviewStarted());
+  watcher._tick();
+  assert.deepEqual(events, [{ type: "review_started" }], "our trunk is the one tailed");
+
+  watcher.stop();
+});
+
 test("watchCodexGuardianReviews picks up a trunk created after watching began", () => {
   const { root, dir } = makeSessionsRoot();
   writeFileSync(

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

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "../../../test/harness.mjs";
 import { discoverCodexTranscript, watchCodexTranscript } from "../src/codex-transcript-watcher.js";
+import { writeSessionTranscriptLink } from "../src/session-transcript-link.js";
 
 const noopTimers = { setInterval: () => ({}), clearInterval: () => {} };
 
@@ -60,6 +61,55 @@ test("discoverCodexTranscript skips files older than session start", () => {
   assert.equal(discoverCodexTranscript(root, Date.now() - 1000), undefined);
 });
 
+test("watchCodexTranscript pins to the session's linked rollout, not newest-by-mtime", () => {
+  // Two concurrent Codex sessions, each with its own rollout and its own link.
+  const root = mkdtempSync(join(tmpdir(), "codex-sessions-"));
+  const dir = join(root, "2026", "06", "12");
+  mkdirSync(dir, { recursive: true });
+  const sessionDir = mkdtempSync(join(tmpdir(), "sess-"));
+
+  const fileA = join(dir, "rollout-a.jsonl");
+  const fileB = join(dir, "rollout-b.jsonl");
+  writeFileSync(fileA, sessionMeta("2026-06-12T01:00:00.000Z", "thread-a"));
+  writeFileSync(fileB, sessionMeta("2026-06-12T01:00:00.000Z", "thread-b"));
+  writeSessionTranscriptLink({ sessionDir, sessionId: "sess_a", transcriptPath: fileA });
+  writeSessionTranscriptLink({ sessionDir, sessionId: "sess_b", transcriptPath: fileB });
+
+  const eventsA = [];
+  const eventsB = [];
+  const watcherA = watchCodexTranscript({
+    sessionId: "sess_a",
+    sessionDir,
+    onToolEvent: (e) => eventsA.push(e),
+    ...noopTimers
+  });
+  const watcherB = watchCodexTranscript({
+    sessionId: "sess_b",
+    sessionDir,
+    onToolEvent: (e) => eventsB.push(e),
+    ...noopTimers
+  });
+
+  // Both pin to their own rollout and consume the session_meta line.
+  watcherA._tick();
+  watcherB._tick();
+
+  // Session A is interrupted.
+  appendFileSync(fileA, turnAborted());
+  watcherA._tick();
+  watcherB._tick();
+
+  assert.deepEqual(
+    eventsA,
+    [{ type: "turn_aborted", reason: "interrupted" }],
+    "session A sees its own interrupt"
+  );
+  assert.deepEqual(eventsB, [], "session B is NOT contaminated by session A's interrupt");
+
+  watcherA.stop();
+  watcherB.stop();
+});
+
 test("watchCodexTranscript reports appended tool events", () => {
   const dir = mkdtempSync(join(tmpdir(), "codex-transcript-"));
   const path = join(dir, "session.jsonl");

package/packages/cli-core/test/run-state.test.mjs

@@ -3,7 +3,7 @@ import { mkdtempSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "../../../test/harness.mjs";
-import { extractTranscriptPath, parseStateArgs, runStateCommand } from "../src/run-state.js";
+import { extractAgentId, extractTranscriptPath, parseStateArgs, runStateCommand } from "../src/run-state.js";
 import { readSessionTranscriptLink } from "../src/session-transcript-link.js";
 
 test("runStateCommand appends a debug line when HAYA_PET_HOOK_DEBUG is set", async () => {
@@ -35,6 +35,40 @@ test("extractTranscriptPath pulls transcript_path out of a Claude hook payload",
   assert.equal(extractTranscriptPath(undefined), undefined);
 });
 
+test("extractAgentId pulls agent_id out of a subagent hook payload", () => {
+  assert.equal(
+    extractAgentId(JSON.stringify({ hook_event_name: "PreToolUse", agent_id: "a9a8317d", agent_type: "Explore" })),
+    "a9a8317d"
+  );
+  // Main-agent events carry no agent_id; junk and wrong types yield undefined.
+  assert.equal(extractAgentId(JSON.stringify({ hook_event_name: "Stop" })), undefined);
+  assert.equal(extractAgentId(JSON.stringify({ agent_id: 42 })), undefined);
+  assert.equal(extractAgentId(JSON.stringify({ agent_id: "" })), undefined);
+  assert.equal(extractAgentId("{not json"), undefined);
+  assert.equal(extractAgentId(undefined), undefined);
+});
+
+test("runStateCommand ignores subagent-originated events so they never drive main status", async () => {
+  let connected = false;
+  const sent = [];
+  const result = await runStateCommand(
+    { command: "state", state: "running_tool", summary: undefined, session: "sess_main" },
+    {
+      now: () => 9,
+      agentId: "a9a8317d3457d6364",
+      createIpcClient: async () => {
+        connected = true;
+        return { send: async (m) => sent.push(m), close: async () => {} };
+      }
+    }
+  );
+
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, "subagent-event");
+  assert.equal(connected, false);
+  assert.equal(sent.length, 0);
+});
+
 test("runStateCommand records the session->transcript link when given a transcript path", async () => {
   const sessionDir = mkdtempSync(join(tmpdir(), "sess-"));
   await runStateCommand(
@@ -112,6 +146,39 @@ test("runStateCommand sends one official_plugin state message", async () => {
   });
 });
 
+test("runStateCommand upgrades a Stop idle to a working cue when a subagent still runs", async () => {
+  const sent = [];
+  const result = await runStateCommand(
+    { command: "state", state: "idle", summary: undefined, session: "sess_bg" },
+    {
+      now: () => 42,
+      backgroundTasks: [
+        { id: "x", type: "subagent", status: "running", description: "Survey repo structure" }
+      ],
+      createIpcClient: async () => ({ send: async (m) => sent.push(m), close: async () => {} })
+    }
+  );
+
+  assert.equal(result.ok, true);
+  assert.equal(sent[0].state, "running_tool");
+  assert.equal(sent[0].summary, "Subagent running");
+});
+
+test("runStateCommand reports plain idle when the follow-up Stop has no running subagents", async () => {
+  const sent = [];
+  await runStateCommand(
+    { command: "state", state: "idle", summary: undefined, session: "sess_done" },
+    {
+      now: () => 43,
+      backgroundTasks: [],
+      createIpcClient: async () => ({ send: async (m) => sent.push(m), close: async () => {} })
+    }
+  );
+
+  assert.equal(sent[0].state, "idle");
+  assert.equal(sent[0].summary, undefined);
+});
+
 test("runStateCommand falls back to HAYA_PET_SESSION_ID", async () => {
   const sent = [];
   const result = await runStateCommand(