@hayasaka7/haya-pet 0.1.0 → 0.2.0

package/README.md

@@ -51,7 +51,9 @@ Haya Pet watches all of them and presents one ambient interface:
 - 🧠 **Normalized state model** — every client maps to a shared state vocabulary
   (`thinking`, `running_tool`, `waiting_approval`, `reviewing`, `failed`, …).
 - 🧩 **Client adapters** with tiered support (process wrapper → PTY observer →
-  log/state → official plugin) so the daemon never bakes in client-specific logic.
+  client hooks) so the daemon never bakes in client-specific logic. Default is
+  lifecycle status; richer status is opt-in (Claude Code hooks via `HAYA_PET_HOOKS=1`,
+  or PTY `--observe` for any client).
 - 🚀 **Zero-setup launch** — `haya-pet run …` auto-starts the overlay; no separate
   daemon to manage.
 - 🖼️ **Codex-compatible pet assets** (1536×1872 sprite atlas, 9 actions).
@@ -92,8 +94,10 @@ Haya Pet watches all of them and presents one ambient interface:
 | **Node ≥ 18** | Runtime + companion (Electron) |
 | **npm** | Install + scripts |
 
-> Live activity status uses the optional `node-pty` (installed automatically when
-> it can build; the pet degrades to lifecycle-only tracking without it).
+> Default status is lifecycle-only and needs no extra modules. Opt-in Claude Code
+> hooks (`HAYA_PET_HOOKS=1`) also need none. The opt-in `--observe` PTY mode uses
+> `node-pty` (installed automatically when it can build; without it, `--observe`
+> degrades to lifecycle-only tracking).
 
 ## Install
 
@@ -138,19 +142,41 @@ shows success (a green check) or failure (a red cross), then fades.
 
 ### Live activity status
 
-By default the wrapper runs the CLI through a pseudo-terminal and shows *working*
-while the AI produces output, returning to *idle* after a short quiet window.
-Success/failure come from the real exit code — never from scraping the word
-"error" out of output. Your terminal stays fully interactive.
+`haya-pet run` uses **native passthrough by default** — the CLI talks directly to
+your terminal, so every input mode (Shift+Tab, mouse wheel, word-edit) works
+exactly as it does without the wrapper. Out of the box, every client shows
+**lifecycle status** (a session bubble while it runs; success/failure from the
+real exit code, never from scraping "error" out of output).
 
 ```bash
-haya-pet run -- claude          # live status (default)
-haya-pet run --no-observe -- claude   # lifecycle only (opt out of PTY observation)
+haya-pet run --client claude-code -- claude   # full fidelity, lifecycle status
+haya-pet run --client codex       -- codex    # full fidelity, lifecycle status
 ```
 
-> ⚠️ Running a CLI through the default PTY observation currently affects terminal
-> scrolling and backspace in some setups — see
-> [docs/known-issues.md](docs/known-issues.md). `--no-observe` avoids it.
+Two **opt-in** ways to get richer *in-session* status (thinking / running tools /
+editing files / waiting for approval):
+
+```bash
+# Claude Code — live status via per-session hooks, NO terminal-fidelity tradeoff.
+# Enable once (persisted); the first run shows a one-time Claude "review hooks"
+# prompt you approve once.
+haya-pet hooks on
+haya-pet run --client claude-code -- claude
+#   (per-run override without persisting: HAYA_PET_HOOKS=1 …, or $env:HAYA_PET_HOOKS=1 in PowerShell)
+#   (turn back off: haya-pet hooks off   ·   check: haya-pet hooks status)
+
+# Any client — coarse live status by watching output through a PTY.
+haya-pet run --observe --client codex -- codex
+```
+
+> **Why opt-in?**
+> - **Hooks (Claude Code):** injecting hooks makes Claude show a one-time
+>   *review hooks* trust prompt. We don't disrupt your session by default; turn it
+>   on once with `haya-pet hooks on` when you're happy to approve the hooks.
+> - **`--observe` (any client):** PTY observation infers status from output, but on
+>   Windows it routes input through ConPTY, which can break **Shift+Tab**, mouse
+>   scroll, and word-edit. Use it only for non-interactive runs. See
+>   [docs/known-issues.md](docs/known-issues.md).
 
 ## Add and choose a pet
 
@@ -219,14 +245,14 @@ Full list (incl. repairing a broken Electron install): [docs/troubleshooting.md]
 
 | Client | Status | Support level |
 |---|---|---|
-| Generic CLI | ✅ | L1 process wrapper |
-| Codex | ✅ | L1 + L2 PTY observation |
-| Claude Code | ✅ | L1 + L2 PTY observation |
-| Antigravity | ✅ | L1 wrapper |
+| Generic CLI | ✅ | L1 process wrapper (+ L2 PTY via `--observe`) |
+| Codex | ✅ | L1 wrapper (+ L2 PTY via `--observe`) |
+| Claude Code | ✅ | L1 wrapper + **L4 live-status hooks** (opt-in `HAYA_PET_HOOKS=1`) |
+| Antigravity | ✅ | L1 wrapper (+ L2 PTY via `--observe`) |
 | Gemini CLI / Aider / others | 🔜 | via the generic adapter |
 
 (See [docs/architecture.md](docs/architecture.md) for the support tiers and the
-platform matrix.)
+platform matrix, and [CHANGELOG.md](CHANGELOG.md) for release notes.)
 
 ## Privacy
 

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

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
+import { realpathSync, appendFileSync } from "node:fs";
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { runGenericCommand as defaultRunGenericCommand } from "../../../packages/cli-core/src/run-command.js";
+import { parseStateArgs, runStateCommand } from "../../../packages/cli-core/src/run-state.js";
+import { injectClaudeHooks as defaultInjectClaudeHooks } from "../../../packages/cli-core/src/claude-hook-injection.js";
+import { watchClaudeTranscript as defaultWatchClaudeTranscript } from "../../../packages/cli-core/src/claude-transcript-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";
 import { discoverPets as defaultDiscoverPets } from "../../../packages/pet-core/src/discovery.js";
 import { createStateFile as defaultCreateStateFile } from "../../../packages/app-state/src/state-file.js";
-import { getSelectedPetId, setSelectedPet } from "../../../packages/app-state/src/state.js";
+import { getSelectedPetId, setSelectedPet, getClaudeHooksEnabled, setClaudeHooksEnabled } from "../../../packages/app-state/src/state.js";
 import { getAdapterInfo } from "../../../packages/adapters/src/adapter-info.js";
 
 const CLIENT_DISPLAY_NAMES = Object.freeze({
@@ -41,6 +45,14 @@ export function parseAiPetArgs(argv) {
     return { command: "stop" };
   }
 
+  if (command === "state") {
+    return parseStateArgs(rest);
+  }
+
+  if (command === "hooks") {
+    return parseHooksArgs(rest);
+  }
+
   throw new Error(`Unsupported haya-pet command: ${command}`);
 }
 
@@ -59,6 +71,14 @@ export async function runAiPet(argv, dependencies = {}) {
     return runStopCommand(parsed, dependencies);
   }
 
+  if (parsed.command === "state") {
+    return runStateCommand(parsed, dependencies);
+  }
+
+  if (parsed.command === "hooks") {
+    return runHooksCommand(parsed, dependencies);
+  }
+
   return runRunCommand(parsed, dependencies);
 }
 
@@ -102,26 +122,127 @@ export async function runStartCommand(_parsed, dependencies = {}) {
 
 async function runRunCommand(parsed, dependencies) {
   const runGenericCommand = dependencies.runGenericCommand ?? defaultRunGenericCommand;
+  const injectClaudeHooks = dependencies.injectClaudeHooks ?? defaultInjectClaudeHooks;
+  const watchClaudeTranscript = dependencies.watchClaudeTranscript ?? defaultWatchClaudeTranscript;
+  const env = dependencies.env ?? process.env;
+  const now = dependencies.now ?? Date.now;
+  const cwd = dependencies.cwd ?? process.cwd();
   const messageSender = await createMessageSender(dependencies);
 
+  const sessionId = dependencies.sessionId ?? `sess_${randomUUID()}`;
+  let childArgs = parsed.childArgs;
+  let childEnv = env;
+  let cleanup = () => {};
+  let stopWatcher = () => {};
+
+  // Claude Code: native passthrough is always the default (full terminal fidelity).
+  // Live-status hooks are OPT-IN — persisted via `haya-pet hooks on`, or per-run via
+  // HAYA_PET_HOOKS=1 — because injecting hooks makes Claude show a one-time "review
+  // hooks" trust prompt; we never disrupt the user's session uninvited. When enabled,
+  // inject a stable settings file so Claude reports live status via `haya-pet state`
+  // (no PTY, so Shift+Tab works).
+  const claudeHooksOn =
+    parsed.clientId === "claude-code" && (await resolveClaudeHooksEnabled(env, dependencies));
+  if (claudeHooksOn) {
+    const injected = injectClaudeHooks();
+    childArgs = [...parsed.childArgs, "--settings", injected.settingsPath];
+    childEnv = { ...env, HAYA_PET_SESSION_ID: sessionId };
+    cleanup = injected.cleanup;
+
+    // Claude fires NO hook when the user manually denies a permission, so the
+    // pet would stay stuck on "waiting for approval". Tail the session transcript
+    // (ground truth) and clear to idle the moment a denial is recorded — never on
+    // a timer, so a genuinely-pending approval keeps alerting until it's resolved.
+    const watcher = watchClaudeTranscript({
+      cwd,
+      homeDir: dependencies.homeDir,
+      startedAt: now(),
+      onDenial: (event) => {
+        hookDebugLog(env, now, { source: "transcript", event: "denied", state: "idle", toolUseId: event?.toolUseId });
+        messageSender
+          .send({
+            type: "state",
+            sessionId,
+            state: "idle",
+            summary: "approval denied",
+            confidence: 0.9,
+            source: "client_log",
+            updatedAt: now()
+          })
+          .catch(() => {});
+      }
+    });
+    stopWatcher = watcher.stop;
+  }
+
   try {
     return await runGenericCommand({
       command: parsed.childCommand,
-      args: parsed.childArgs,
-      cwd: dependencies.cwd ?? process.cwd(),
+      args: childArgs,
+      cwd,
       clientId: parsed.clientId,
       clientDisplayName: CLIENT_DISPLAY_NAMES[parsed.clientId] ?? parsed.clientId,
       observe: parsed.observe,
+      sessionId,
+      env: childEnv,
       heartbeatIntervalMs: dependencies.heartbeatIntervalMs,
       now: dependencies.now,
       stdio: dependencies.stdio,
       send: messageSender.send
     });
   } finally {
+    stopWatcher();
+    cleanup();
     await messageSender.close();
   }
 }
 
+// Resolve whether Claude Code hooks should be injected for this run.
+// Precedence: HAYA_PET_NO_HOOKS forces off, HAYA_PET_HOOKS forces on (per-run
+// overrides), otherwise the persisted `haya-pet hooks on/off` preference.
+async function resolveClaudeHooksEnabled(env, dependencies) {
+  if (isTruthyFlag(env.HAYA_PET_NO_HOOKS)) {
+    return false;
+  }
+  if (isTruthyFlag(env.HAYA_PET_HOOKS)) {
+    return true;
+  }
+  try {
+    const state = await createConfigStateFile(dependencies).load();
+    return getClaudeHooksEnabled(state);
+  } catch {
+    return false;
+  }
+}
+
+function isTruthyFlag(value) {
+  return value === "1" || value === "true";
+}
+
+function createConfigStateFile(dependencies) {
+  const paths = getDefaultPaths({
+    platform: dependencies.platform,
+    env: dependencies.env,
+    homeDir: dependencies.homeDir
+  });
+  const createStateFile = dependencies.createStateFile ?? defaultCreateStateFile;
+  return createStateFile({ statePath: paths.statePath });
+}
+
+// Best-effort: mirror the reporter's HAYA_PET_HOOK_DEBUG log so transcript-driven
+// events (which don't go through `haya-pet state`) show up in the same trace.
+function hookDebugLog(env, now, entry) {
+  const target = env.HAYA_PET_HOOK_DEBUG;
+  if (!target) {
+    return;
+  }
+  try {
+    appendFileSync(target, `${JSON.stringify({ ts: now(), ...entry })}\n`);
+  } catch {
+    // diagnostics must never break the run
+  }
+}
+
 export async function runPetsCommand(parsed, dependencies = {}) {
   const paths = getDefaultPaths({
     platform: dependencies.platform,
@@ -181,6 +302,37 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   return result;
 }
 
+function parseHooksArgs(args) {
+  const [action = "status"] = args;
+  if (action === "on" || action === "off" || action === "status") {
+    return { command: "hooks", action };
+  }
+  throw new Error(`Unknown hooks action: ${action} (use on, off, or status)`);
+}
+
+// Persisted toggle for Claude Code live-status hooks (the convenient alternative
+// to setting HAYA_PET_HOOKS every shell).
+export async function runHooksCommand(parsed, dependencies = {}) {
+  const print = dependencies.print ?? defaultPrint;
+  const stateFile = createConfigStateFile(dependencies);
+  const state = await stateFile.load();
+
+  if (parsed.action === "status") {
+    const enabled = getClaudeHooksEnabled(state);
+    print(`Claude Code live-status hooks: ${enabled ? "on" : "off"}`);
+    return { command: "hooks", action: "status", enabled };
+  }
+
+  const enabled = parsed.action === "on";
+  await stateFile.save(setClaudeHooksEnabled(state, enabled));
+  print(
+    enabled
+      ? "Claude Code live-status hooks: on. The first `haya-pet run --client claude-code` asks Claude to review the hooks once — approve it."
+      : "Claude Code live-status hooks: off."
+  );
+  return { command: "hooks", action: parsed.action, enabled };
+}
+
 function parsePetsArgs(args) {
   if (args.length === 0) {
     return { command: "pets", action: "list" };
@@ -205,7 +357,7 @@ function parsePetsArgs(args) {
 
 function parseRunArgs(args) {
   let clientId = "generic";
-  let observe = true; // live PTY observation is on by default; --no-observe opts out
+  let observe = false; // native passthrough by default (full terminal fidelity); --observe opts in
   let childStart = -1;
 
   for (let index = 0; index < args.length; index += 1) {

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

@@ -17,12 +17,12 @@ test("parses generic run command arguments", () => {
   );
 });
 
-test("observation is on by default and --no-observe opts out", () => {
-  assert.equal(parseAiPetArgs(["run", "--client", "codex"]).observe, true);
-  assert.equal(parseAiPetArgs(["run", "--no-observe", "--client", "codex"]).observe, false);
+test("native passthrough is the default and --observe opts in", () => {
+  assert.equal(parseAiPetArgs(["run", "--client", "codex"]).observe, false);
+  assert.equal(parseAiPetArgs(["run", "--observe", "--client", "codex"]).observe, true);
 
   const parsedWithCommand = parseAiPetArgs(["run", "--", "claude", "--resume"]);
-  assert.equal(parsedWithCommand.observe, true);
+  assert.equal(parsedWithCommand.observe, false);
   assert.equal(parsedWithCommand.childCommand, "claude");
   assert.deepEqual(parsedWithCommand.childArgs, ["--resume"]);
 });
@@ -326,6 +326,167 @@ test("stop command is a no-op when nothing is running", async () => {
   assert.ok(lines.some((line) => line.includes("not running")));
 });
 
+test("parses the state command", () => {
+  assert.deepEqual(parseAiPetArgs(["state", "thinking", "--session", "sess_q"]), {
+    command: "state",
+    state: "thinking",
+    summary: undefined,
+    session: "sess_q"
+  });
+});
+
+const hooksStateFile = (claudeHooks) => () => ({
+  load: async () => ({ settings: { claudeHooks } }),
+  save: async (state) => state
+});
+
+test("claude-code does NOT inject hooks by default (safe out-of-box)", async () => {
+  const calls = [];
+  let injected = 0;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { USERPROFILE: "C:\\Users\\A" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    createStateFile: hooksStateFile(false),
+    injectClaudeHooks: () => { injected += 1; return { settingsPath: "x", cleanup: () => {} }; },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: "s", pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(injected, 0, "no hook injection unless opted in");
+  assert.deepEqual(calls[0].args, []);
+});
+
+test("persisted `hooks on` opts claude-code into injection without an env var", async () => {
+  const calls = [];
+  let injected = 0;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { USERPROFILE: "C:\\Users\\A" }, // no HAYA_PET_HOOKS
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    createStateFile: hooksStateFile(true), // persisted preference = on
+    injectClaudeHooks: () => { injected += 1; return { settingsPath: "/tmp/s.json", cleanup: () => {} }; },
+    watchClaudeTranscript: () => ({ stop: () => {} }),
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(injected, 1, "config preference enables hooks");
+  assert.deepEqual(calls[0].args, ["--settings", "/tmp/s.json"]);
+});
+
+test("HAYA_PET_NO_HOOKS=1 overrides a persisted `hooks on`", async () => {
+  const calls = [];
+  let injected = 0;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { HAYA_PET_NO_HOOKS: "1", USERPROFILE: "C:\\Users\\A" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    createStateFile: hooksStateFile(true),
+    injectClaudeHooks: () => { injected += 1; return { settingsPath: "x", cleanup: () => {} }; },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: "s", pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(injected, 0, "env override forces hooks off");
+  assert.deepEqual(calls[0].args, []);
+});
+
+test("hooks command parses and persists the toggle", async () => {
+  assert.deepEqual(parseAiPetArgs(["hooks"]), { command: "hooks", action: "status" });
+  assert.deepEqual(parseAiPetArgs(["hooks", "on"]), { command: "hooks", action: "on" });
+  assert.throws(() => parseAiPetArgs(["hooks", "bogus"]), /Unknown hooks action/);
+
+  let saved;
+  const lines = [];
+  const store = {
+    load: async () => ({ settings: { claudeHooks: false } }),
+    save: async (state) => { saved = state; return state; }
+  };
+  const result = await runAiPet(["hooks", "on"], {
+    homeDir: "C:\\Users\\A",
+    createStateFile: () => store,
+    print: (line) => lines.push(line)
+  });
+
+  assert.equal(result.enabled, true);
+  assert.equal(saved.settings.claudeHooks, true);
+  assert.ok(lines.some((l) => l.includes("on")));
+});
+
+test("HAYA_PET_HOOKS=1 opts claude-code into --settings + HAYA_PET_SESSION_ID", async () => {
+  const calls = [];
+  let watched = 0;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { HAYA_PET_HOOKS: "1", USERPROFILE: "C:\\Users\\A", HOME: "/home/a" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    injectClaudeHooks: () => ({ settingsPath: "/tmp/s.json", cleanup: () => {} }),
+    watchClaudeTranscript: () => { watched += 1; return { stop: () => {} }; },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].args, ["--settings", "/tmp/s.json"]);
+  assert.equal(calls[0].env.HAYA_PET_SESSION_ID, calls[0].sessionId);
+  assert.ok(calls[0].sessionId, "a session id was generated and shared via env");
+  assert.equal(watched, 1, "transcript watcher started for approval-denial recovery");
+});
+
+test("a transcript denial clears the stuck approval to idle", async () => {
+  const sent = [];
+  let fireDenial;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { HAYA_PET_HOOKS: "1", USERPROFILE: "C:\\Users\\A" },
+    now: () => 42,
+    heartbeatIntervalMs: 10,
+    send: async (message) => sent.push(message),
+    injectClaudeHooks: () => ({ settingsPath: "/tmp/s.json", cleanup: () => {} }),
+    watchClaudeTranscript: ({ onDenial }) => { fireDenial = onDenial; return { stop: () => {} }; },
+    runGenericCommand: async (options) => {
+      // Simulate the user denying a permission mid-session.
+      fireDenial({ type: "tool_denied", toolUseId: "toolu_1" });
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  const idle = sent.find((m) => m.type === "state" && m.source === "client_log");
+  assert.ok(idle, "a client_log state was sent on denial");
+  assert.equal(idle.state, "idle");
+  assert.equal(idle.summary, "approval denied");
+  assert.equal(idle.updatedAt, 42);
+});
+
+test("non-claude clients are never injected even with HAYA_PET_HOOKS=1", async () => {
+  const calls = [];
+  await runAiPet(["run", "--client", "codex", "--", "codex"], {
+    cwd: process.cwd(),
+    env: { HAYA_PET_HOOKS: "1", USERPROFILE: "C:\\Users\\A" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    injectClaudeHooks: () => { throw new Error("should not inject for codex"); },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: "s", pid: 1, exitCode: 0 };
+    }
+  });
+  assert.deepEqual(calls[0].args, []);
+});
+
 async function waitFor(predicate) {
   const startedAt = Date.now();
 

package/apps/companion/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haya-pet/companion",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "description": "Electron overlay companion app for the AI CLI pet runtime.",

package/apps/companion/test/position-store.test.mjs

@@ -17,7 +17,8 @@ test("creates default position state", () => {
     sessions: {},
     settings: {
       displayMode: "hybrid",
-      attachBubblesToTerminals: true
+      attachBubblesToTerminals: true,
+      claudeHooks: false
     }
   });
 });

package/docs/architecture.md

@@ -48,14 +48,24 @@ as each client allows:
 | Tier | Source | Fidelity |
 |---|---|---|
 | L1 | Process wrapper (lifecycle only) | session exists / exit code |
-| L2 | PTY output observation (`--observe`, default) | activity-based working/idle |
+| L2 | PTY output observation (`--observe`, opt-in) | activity-based working/idle |
 | L3 | Client logs / state files | client-specific (future) |
-| L4 | Official plugin/hooks | richest (future) |
+| L4 | Client hooks | richest — implemented for Claude Code |
+
+The **default** is native passthrough (`stdio: "inherit"`) for full terminal
+fidelity, with **L1 lifecycle** status for every client. Richer status is opt-in:
+**Claude Code** gains **L4 hooks** when enabled with `haya-pet hooks on`
+(persisted; or per-run via `HAYA_PET_HOOKS=1`) — injected via
+`claude --settings <stable-file>`, reporting in-session activity through the
+`haya-pet state` command — lifecycle still comes from the wrapper's exit code);
+any client gains **L2** with `--observe`. Hooks are opt-in because injecting them
+triggers Claude's one-time *review hooks* trust prompt.
 
 L2 is **activity-based**: any visible output → *working*; a short quiet window →
 *idle*; success/failure come from the real exit code, never from scraping output
-text. Keyword heuristics exist but are opt-in (unreliable on rich TUIs). See
-[known-issues.md](known-issues.md) for the current L2/PTY tradeoffs.
+text. It is opt-in because routing input through a PTY (ConPTY on Windows) breaks
+special keys like Shift+Tab — see [known-issues.md](known-issues.md) for the
+L2/PTY tradeoffs.
 
 ## Overlay model
 
@@ -141,4 +151,48 @@ helper. In progress:
 - Faithful PTY passthrough (see [known-issues.md](known-issues.md)).
 - Production overlay/IPC validation across all platforms.
 
+### Deferred: focus a session's terminal on bubble click
+
+Clicking a session bubble should raise/focus the terminal window running that
+session. Deferred because it can't be done as a clean cross-OS feature yet:
+
+- **Windows** — doable now: the helper already *locates* the window (HWND); add a
+  `focus` op that calls `SetForegroundWindow` (+ the usual `AllowSetForegroundWindow`
+  / attach-thread-input dance), then wire bubble click → IPC → helper.
+- **macOS** — needs an (unbuilt) Accessibility/window-list helper and a
+  user-granted Accessibility permission.
+- **Linux X11** — needs the (unbuilt) X11 helper (EWMH `_NET_ACTIVE_WINDOW`).
+- **Linux Wayland** — blocked by the compositor security model; no portable API to
+  focus another app's window.
+
+Implementation sketch when picked up: bubble `click` in `session-bubbles.js` →
+`haya-pet:focus-session` IPC with `sessionId` → main resolves `session.pid`
+(/`terminalPid`) → terminal helper `focus` op (per-OS), with a graceful no-op
+where unsupported.
+
+### Deferred: per-session token usage
+
+Show each session's token usage on its bubble. Feasible as an **L3 client-log
+adapter** (`source: "client_log"`) — and it's cross-OS, since only the log path
+differs by client, not by OS. There is no generic source: the process wrapper
+only sees terminal bytes, so usage must come from each client's own logs.
+
+- **Claude Code** — confirmed: per-turn `usage` (`input_tokens`, `output_tokens`,
+  `cache_creation_input_tokens`, `cache_read_input_tokens`) in
+  `~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl`. Clean JSONL to parse.
+- **Codex** — usage exists in its logs (`~/.codex/history.jsonl`, `sessions/`,
+  sqlite) but in a messier shape; needs a dedicated adapter + investigation.
+- **Generic / other clients** — no reliable source; the adapter should no-op.
+
+Implementation sketch when picked up: a per-client usage adapter tails the
+session's transcript (matched via the session's `cwd` → the newest `.jsonl` in
+that project dir), sums usage across turns, and emits an optional `usage` field
+(protocol addition) → `session-core` stores it → the bubble renders it
+(e.g. `↑ in / ↓ out`). Open questions: (1) which metric to surface — cache-read
+tokens are huge under prompt caching, so likely show output + input, with total
+context separate; (2) disambiguating multiple concurrent sessions in the same
+project dir (by start time / newest file). The JSONL parser is pure and
+TDD-friendly. Investigate non-Claude client adapters (Codex, etc.) as part of
+this.
+
 See [`../PROGRESS.md`](../PROGRESS.md) for the detailed log.