pendingyou 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 0.17.0 (2026-10-05)
+
+- Herdr: an agent running in a Herdr pane (`HERDR_ENV=1` with `HERDR_BIN_PATH` and `HERDR_PANE_ID`) marks its pane with
+  what it's waiting on you for, as display-only metadata (`src/herdr.ts`): `"$HERDR_BIN_PATH" pane report-metadata
+  "$HERDR_PANE_ID" --source pendingyou` with `py_app`, `py_agent` (the name the session goes by with Pending You),
+  `py_waiting` (how many cards wait on you), `py_card` (the most pressing one's title, redacted as permission cards' words
+  are and cut to 80 characters), `py_cards` (their request ids, as many as fit in 80 characters), `py_urgency`
+  (`blocking`, else `now`, `today` or `whenever`) and `py_asked` (those also asked in the conversation), and the state
+  labels `idle` and `done` read "waiting on you" while something waits (`--agent` keeps them to the pane's own agent).
+  Cleared when nothing waits and as the session ends. Herdr's program is run with an argument list, given one second,
+  its outcome never thrown, and a hook only starts it in the background; `--seq` (the moment, in milliseconds) keeps a
+  late write from winning, and `--ttl-ms 900000` lets tokens nobody repeats expire. Herdr's limits are kept: one source,
+  7 tokens a report, its token names, 80 characters a value.
+  - Claude Code: init's copy of the wake mod writes them whenever they change and every 5 minutes, through the hooks'
+    script (`herdr report --app claude-code`, the session's cards on stdin), learning how pressing each card is from
+    post_request and update_request; the session-start hook names the session in the background (from its transcript);
+    the SessionEnd hook clears them in the background.
+  - Codex: its card hook (`posted`) marks the thread as the pane's and writes them in the background; the thread's
+    keeper writes them with each live (it now starts in Herdr even without a connection here, and keeps on for them when
+    Pending You won't take its presence) and clears them as Codex quits; the listener writes them once a card is
+    answered.
+  - OpenCode and Pi: through what their plugin and extension already run: `posted` after each card call, `presence
+    --state live` (the heartbeat) and `closed`, and the listener. A pane's badges are every session of the app marked
+    there: OpenCode runs several in one pane.
+  - `<app>-threads.json` remembers each card's urgency, whether it blocks and whether it was asked in the conversation,
+    and the Herdr pane each session runs in; `herdr.json` whether the badges are off here.
+- `pendingyou herdr <what>`: the Pending You plugin for Herdr's commands (`src/herdr/`), which its manifest runs through
+  the hooks' script. `next` focuses the next pane waiting on you (blocking first, then by urgency); `open` is the popup
+  that lists them (Enter opens the card in Pending You through a terminal hyperlink, `t` takes you to the pane; `--demo`
+  shows made-up cards); `popup <pane>` opens one of the plugin's popups; `setup` checks Herdr's toasts, offers the
+  sidebar row (`$py_card`) as a managed block in Herdr's `config.toml`, written only with a yes and checked with `herdr
+  config check`, and prints the keybindings to add yourself; `doctor` says what's set up (also by hand in a terminal);
+  `view` turns the plugin's Agents view on or off; `watch` is the watcher (one per Herdr server, held by a lease) that
+  raises Herdr's toast when a pane gains a card, never for the tab you're looking at, cards that arrive together in one,
+  a card also asked in the conversation after 3 minutes; `event` makes sure it runs; `unconfigure` stops it, takes the
+  badges off every pane and turns them off here, clears the view, and takes the block out. Read-only: nothing asks
+  Pending You anything. Herdr's socket API through `HERDR_SOCKET_PATH`.
+- Tests never reach a real Herdr: the test setup drops every `HERDR_*` variable from their environment.
+
+## 0.16.0 (2026-10-05)
+
+- A word on one of your own cards that's neither an answer nor your person's (guide 2.32): `/mcp/cli/answers` marks it
+  `notice` (`{ kind, from }`), and the hold, the pickup, the hooks and `watch` say what it is instead of “they wrote
+  back”:
+  - `follow_up`: the helper that answered it for your person followed up afterwards (“shipped in #231”): “Pending You:
+    pending-you-chief followed up on req_…, which it answered for your person.”, the question, its words, then “Act on
+    it if it needs anything, then call ack_answer … to mark it heard.” On an answer you haven't picked up yet, its
+    words come with the answer (“Also: …”).
+  - `handed_over`: your person handed your open cards to another assistant: “Pending You: your person handed your open
+    cards to pending-you-chief, req_… among them.” and “Stop working on them: pending-you-chief answers them and
+    follows up. Call ack_answer … to say you’ve stopped.”
+  `watch` gives both as `message_ready`. A command line before 0.16.0 hears the same words as a message from them.
+- Claude Code's permission prompts get a card in bypassPermissions mode too: a dangerous request from a background
+  agent there waited minutes for an OK with no card. Claude Code still asks for a few things in that mode (a dangerous
+  `rm`, an ask rule, a safety check it can't verify), but the PermissionRequest hook skipped bypassPermissions and
+  dontAsk mode outright. It also runs for a call Claude Code then denies by itself, showing
+  nothing, so in those two modes it now writes the prompt down quietly, and its card goes up only once a dialog is on
+  screen. A new Notification hook says so: `pendingyou-hook notify --app claude-code`, with the matcher
+  `permission_prompt`, so Claude Code runs it only for a dialog that has waited about six seconds with nobody typing,
+  and never for its other notifications. A call denied without a dialog never gets a card: its PostToolUseFailure, the
+  same agent's next call, your next message or the end of the turn settles it. In the other modes a card still goes up
+  after 10 seconds, or as soon as the Notification comes.
+- A dialog no PermissionRequest hook ran for (a sandboxed command's network request; one a Claude Code ran none for)
+  gets a card from its Notification alone: “Claude Code is waiting for your OK”, with Claude Code's own words, redacted,
+  in its summary (“It says: “Claude needs your permission”.”). Whose dialog it was isn't known, so only a turn that ends
+  with no subagent running, or the session's end, takes it down.
+- A background agent's prompt says so: “Claude Code is waiting for your OK: pnpm lint && git push (a background
+  agent)”, and its summary names the agent's type (“A background agent (general-purpose) of Claude Code
+  (billing-webhooks), in ~/… on work-mbp, is waiting for your OK to run a command.”). It stays on the session's one card,
+  and only that agent's own calls settle it, not the session's or another agent's.
+- `init` adds the Notification hook at the end of Claude Code's Notification hooks, after any of your own, and says so
+  on a computer set up before (“Added a Notification hook to the permission-prompt hooks: …”); `status` marks the
+  Permission prompts line missing without it; `uninstall` and `--no-permission-cards` take it out with the others.
+  Codex is unchanged: it has no hook that says a dialog is on screen (its `notify` runs only when a turn completes).
+
 ## 0.15.0 (2026-10-05)
 
 - Presence: Pending You hears which of your agents' sessions are open right now. Each app tells it with its own

package/README.md

@@ -246,6 +246,14 @@ a key are blanked (`curl -H "Authorization: …" https://api.example.com/items?t
 shown safely (several lines, inline code like `node -e`, one that takes a secret) shows only as “Bash: node …”. No card
 for `claude -p` or the Agent SDK, where nobody sees a prompt.
 
+In bypassPermissions mode (`--dangerously-skip-permissions`) Claude Code still asks for a few things: a dangerous `rm`,
+an ask rule of yours, a safety check it can't verify. Since 0.16.0 those get a card too, once Claude Code says the
+dialog has waited a few seconds with nobody typing (its Notification hook, which `init` adds for permission dialogs
+only): a call it denies by itself, showing you nothing, never gets one. The same hook puts up a card for a dialog no
+other hook sees (a sandboxed command asking for the network), in Claude Code's own words, and in the other modes puts
+a card up as soon as Claude Code says so, without waiting the full 10 seconds. A background agent's prompt says so:
+“Claude Code is waiting for your OK: pnpm lint && git push (a background agent)”.
+
 It needs Claude Code 2.1.119 or later, signing in through this computer's sign-in (not `--oauth`), and isn't on
 Windows yet. Don't want it? `npx pendingyou init --no-permission-cards` (later runs keep it off; `--permission-cards`
 turns it back on). `npx pendingyou status` says which.
@@ -276,6 +284,29 @@ It's never in your way: the hooks only start it in the background, each send giv
 You from before presence is taken quietly. A sign-in that only hears (`--oauth`) sends nothing. `npx pendingyou status`
 has a Presence line for each agent.
 
+## In Herdr
+
+Since 0.17.0, an agent running in a [Herdr](https://herdr.dev) pane marks its pane with what it's waiting on you for,
+so Herdr's sidebar and Agents panel can show it: display-only metadata Herdr keeps on this computer (`herdr agent list`
+shows it), written with Herdr's own command line:
+
+- `py_app` and `py_agent`: the app and the name the session goes by with Pending You;
+- `py_waiting`: how many of its cards wait on you; `py_card` the most pressing one's title (anything that looks like a
+  secret taken out, at most 80 characters); `py_cards` their request ids; `py_urgency` how pressing (`blocking`, `now`,
+  `today`, `whenever`); `py_asked` the ones it also asked you in its conversation;
+- and its state reads "waiting on you" instead of idle or done while something waits.
+
+Claude Code's wake mod writes them whenever they change, Codex's card hook and keeper, OpenCode's plugin and Pi's
+extension through the commands they already run; every 5 minutes again, and they're taken off when nothing waits and as
+the session ends. Herdr is given one second for each, never through a shell, and never waited on by a hook; it forgets
+them after 15 minutes unless told again.
+
+The Pending You plugin for Herdr puts them to use: the card on each waiting agent's row in the sidebar, a toast when a
+pane gains one, a key to the next pane waiting on you, a popup that lists them (Enter opens the card in Pending You), and
+an Agents view with them first. Its commands are this command line's: `npx pendingyou herdr doctor` says what's set
+up. Its `unconfigure` takes the badges off every pane and stops writing them on this computer; its setup turns them on
+again.
+
 ## How Claude Code hears your answer
 
 **Claude Code 2.1.287 or later: the wake mod.** There's nothing to run. In each session the mod learns the cards
@@ -399,6 +430,7 @@ its environment. A failing command is tried twice more, then skipped. `--once` s
 | `stopcheck` | The Stop hook: items for you left only in chat (`--app`) |
 | `uninstall` | Remove what `init` added, and sign out (`--app`) |
 | `mcp --app <app>` | The stdio bridge: a local MCP server for an agent that can't run a headers helper (OpenCode, Pi), which passes each message on to Pending You with that agent's own sign-in here (`--check`) |
+| `herdr doctor` | Pending You in Herdr: the badges, the plugin, its toasts and its sidebar row. The plugin runs `herdr next`, `open`, `setup`, `view` and `unconfigure`; the agents' writers `herdr report` |
 
 Every command takes `--origin` (default `https://www.pendingyou.com`, or `$PENDINGYOU_ORIGIN`). `--app` takes
 `claude-code`, `codex`, `opencode` or `pi` (several with commas where a command sets up or reports several); with none,
@@ -426,7 +458,10 @@ Pi session waits on, and (0.14.0) the names it went by and its folder, kept 12 h
 (ids, names, folders and titles: never an answer or a note); `pi/` Pi's extension; and `cli/` the hooks' copy of the
 command line. `init`, `status` and the hooks read `~/.claude.json` (and a folder's `.mcp.json`, and
 `~/.claude/settings.json`'s enabled plugins), `~/.codex/config.toml`, OpenCode's config and Pi's `mcp.json` only to see
-whether the agent has a `pendingyou` MCP server and where it points. With a sign-in that only hears, the hooks and
+whether the agent has a `pendingyou` MCP server and where it points. In a Herdr pane (0.17.0) the agents' writers hand
+Herdr's own command line, on this computer, the badges above: a card's title (redacted, 80 characters at most) and its
+request id, never an answer or a note; `<app>-threads.json` remembers the pane each session runs in, and `herdr.json`
+whether the badges are off. With a sign-in that only hears, the hooks and
 listeners tell this computer's handed questions from another's by its names: its hostname, the names its sign-ins by
 code were given, a Mac's own name (`scutil --get ComputerName`) and, outside a hook, Tailscale's (`tailscale status`). For a permission prompt's card, the worker reads
 the end of the Claude Code session's transcript only for the name the session gave Pending You, and `git remote

package/dist/apps/claude-code.js

@@ -199,8 +199,10 @@ export const claudeCode = {
 };
 function permissionLine(io, claude, manifest, helper, flag) {
     const label = 'Permission prompts:';
-    if (claude.permission)
+    if (claude.permission && claude.notify)
         return `  ok      ${label} a card when Claude Code waits for your OK`;
+    if (claude.permission)
+        return `  missing ${label} no card for a dialog in bypassPermissions mode, or one the other hooks don’t see; run npx pendingyou@latest init${flag}`;
     if (manifest?.permissionCards === false)
         return `          ${label} off, as you chose; for a card when Claude Code waits for your OK, run npx pendingyou init --permission-cards${flag}`;
     const blocker = claude.claude

package/dist/apps/codex-wake.js

@@ -5,8 +5,9 @@ import { getJson, SignInNeeded, Unavailable } from "../api.js";
 import { DEFAULT_ORIGIN } from "../args.js";
 import { connectionMachine, readCredential } from "../credentials.js";
 import { configDir, readJson, withLock, writeWhole } from "../files.js";
-import { clip, delegatedOf, isClosed } from "../format.js";
+import { clip, delegatedOf, isClosed, noticeOf } from "../format.js";
 import { chooseThread, goesBy, HANDED_FOR_MS, handedCard, handedMessage, namesAnotherComputer, } from "../handed.js";
+import { clearHerdr, herdrTarget, isUrgency, PANE_ID, reportCommand, writeHerdr, } from "../herdr.js";
 import { macName, tailscaleName } from "../remote.js";
 import { claimHanded, markHanded, momentOf, releaseHanded, wasHanded } from "../state.js";
 import { findCodex } from "./codex-app.js";
@@ -55,6 +56,7 @@ function threadOf(value) {
         at: value.at,
         ...(names.length ? { names: names.slice(-NAMES) } : {}),
         ...(typeof value.cwd === 'string' && value.cwd ? { cwd: value.cwd } : {}),
+        ...(typeof value.herdr === 'string' && PANE_ID.test(value.herdr) ? { herdr: value.herdr } : {}),
     };
 }
 async function load(io, app) {
@@ -155,6 +157,7 @@ export async function posted(io, options) {
         const requestId = [output?.requestId, args.requestId].find((id) => typeof id === 'string' && REQUEST_ID.test(id));
         const cwd = text(input.cwd, 1000);
         const now = io.now();
+        const pane = await herdrTarget(io);
         await change(io, app, (state) => {
             if (turn && call !== 'cancel_request') {
                 const record = state.turns[turn] ?? { at: now, cards: [] };
@@ -171,19 +174,29 @@ export async function posted(io, options) {
                     const before = waiting.cards[requestId];
                     const name = nameOf(args) ?? before?.name;
                     const title = text(args.title, 400) ?? text(reopen?.title, 400) ?? before?.title;
+                    const urgency = isUrgency(args.urgency) ? args.urgency : before?.urgency;
+                    const blocking = typeof args.blocking === 'boolean' ? args.blocking : before?.blocking;
+                    const askedFirst = call === 'post_request' ? askedIn(args) : before?.askedFirst;
                     waiting.cards[requestId] = {
                         ...(name ? { name } : {}),
                         ...(title ? { title } : {}),
                         at: now,
+                        ...(urgency ? { urgency } : {}),
+                        ...(blocking ? { blocking } : {}),
+                        ...(askedFirst ? { askedFirst } : {}),
                     };
                 }
             }
             if (cwd)
                 waiting.cwd = cwd;
+            if (pane)
+                waiting.herdr = pane.pane;
             waiting.origin = options.origin;
             waiting.at = now;
             state.threads[thread] = waiting;
         });
+        if (pane)
+            io.background(reportCommand(app, { session: thread, at: now }));
         if (app === 'codex')
             await keepListening(io, options.origin, thread);
         return 0;
@@ -192,6 +205,60 @@ export async function posted(io, options) {
         return 0;
     }
 }
+function askedIn(args) {
+    let asked = args.askedFirst;
+    if (typeof asked === 'string')
+        try {
+            asked = JSON.parse(asked);
+        }
+        catch {
+            return false;
+        }
+    return isObject(asked);
+}
+export async function reportThreads(io, app, options) {
+    try {
+        const pane = await herdrTarget(io);
+        if (!pane)
+            return 'off';
+        const session = options.session && THREAD.test(options.session) ? options.session : null;
+        let state = await load(io, app);
+        const known = session ? state.threads[session] : undefined;
+        if (session && known) {
+            const wanted = options.closed
+                ? known.herdr === pane.pane
+                    ? undefined
+                    : known.herdr
+                : pane.pane;
+            if (wanted !== known.herdr)
+                state = await change(io, app, (next) => {
+                    const thread = next.threads[session];
+                    if (!thread)
+                        return;
+                    if (wanted)
+                        thread.herdr = wanted;
+                    else
+                        delete thread.herdr;
+                });
+        }
+        const here = Object.values(state.threads).filter((thread) => thread.herdr === pane.pane);
+        if (here.length === 0 && options.closed)
+            return await clearHerdr(io, options.at, pane);
+        const newest = [...here].sort((a, b) => b.at - a.at)[0];
+        const cards = here.flatMap((thread) => Object.entries(thread.cards).map(([requestId, card]) => ({
+            requestId,
+            ...(typeof card.title === 'string' ? { title: card.title } : {}),
+            ...(isUrgency(card.urgency) ? { urgency: card.urgency } : {}),
+            ...(card.blocking === true ? { blocking: true } : {}),
+            ...(card.askedFirst === true ? { askedFirst: true } : {}),
+            at: typeof card.at === 'number' ? card.at : 0,
+        })));
+        return await writeHerdr(io, { app, agent: newest?.names?.at(-1) ?? null, cards, at: options.at }, pane);
+    }
+    catch {
+        return 'failed';
+    }
+}
 export async function touchThread(io, app, thread, cwd) {
     try {
         if (!THREAD.test(thread) || !(await load(io, app)).threads[thread])
@@ -310,6 +377,18 @@ function line(heard, card) {
         .replaceAll('”', '’')}” (${heard.requestId})`;
     const named = card.name ?? heard.sessionLabel;
     const get = `get_request (requestId ${heard.requestId}, ${named ? `name “${named}”` : 'your name'})`;
+    const notice = noticeOf(heard);
+    const from = notice ? clip(notice.from, 60).text : '';
+    if (notice?.kind === 'handed_over')
+        return [
+            `your person handed your open cards to ${from}, ${titled} among them`,
+            `stop working on them: ${from} answers them and follows up; ack_answer ${heard.requestId} with its version to say you’ve stopped`,
+        ];
+    if (notice?.kind === 'follow_up' && heard.status !== 'answered')
+        return [
+            `${from} followed up on ${titled}, which it answered for your person`,
+            `call ${get} to read it, act on it if it needs anything, then ack_answer with its version to mark it heard`,
+        ];
     switch (heard.status) {
         case 'expired':
             return [
@@ -339,7 +418,7 @@ export function wakeMessage(ready) {
     });
     if (lines.length === 0)
         return null;
-    const asked = lines.some(({ heard }) => heard.turn === 'agent' && heard.status !== 'expired');
+    const asked = lines.some(({ heard }) => heard.turn === 'agent' && heard.status !== 'expired' && !noticeOf(heard));
     const reopen = asked
         ? ' If they asked you something or you need more from them, reply_in_thread with reopen instead.'
         : '';
@@ -520,9 +599,12 @@ export async function listen(io, options) {
                 else
                     ready.push({ heard, card });
             }
-            const gone = () => change(io, app, (state) => {
-                delete state.threads[thread];
-            });
+            const gone = async () => {
+                await change(io, app, (state) => {
+                    delete state.threads[thread];
+                });
+                await reportThreads(io, app, { at: io.now() });
+            };
             const message = wakeMessage(ready);
             if (message) {
                 if (!(await deliver(message, ready.map(({ heard }) => heard.requestId)))) {
@@ -544,13 +626,15 @@ export async function listen(io, options) {
             for (const heard of requests)
                 if (cards[heard.requestId] && isClosed(heard) && !done.includes(heard.requestId))
                     done.push(heard.requestId);
-            if (done.length)
+            if (done.length) {
                 await change(io, app, (state) => {
                     const waiting = state.threads[thread];
                     if (waiting)
                         for (const id of done)
                             delete waiting.cards[id];
                 });
+                await reportThreads(io, app, { at: io.now() });
+            }
             if (io.now() - started > PATIENT_AFTER_MS)
                 await io.sleep(PATIENT_PAUSE_MS, signal);
         }

package/dist/args.js

@@ -1,7 +1,20 @@
-import { APP_IDS, APP_NAMES, isAppId } from "./apps/ids.js";
+import { APP_IDS, APP_NAMES, DEFAULT_APP, isAppId } from "./apps/ids.js";
 export const DEFAULT_ORIGIN = 'https://www.pendingyou.com';
 export const DEFAULT_TIMEOUT_MS = 4 * 60 * 60 * 1000;
 const MAX_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+export const HERDR_SUBS = [
+    'report',
+    'next',
+    'open',
+    'setup',
+    'doctor',
+    'unconfigure',
+    'watch',
+    'event',
+    'view',
+    'popup',
+];
+export const HERDR_POPUPS = ['cards', 'setup', 'doctor', 'demo'];
 export class UsageError extends Error {
     name = 'UsageError';
 }
@@ -63,8 +76,10 @@ const COMMANDS = new Set([
     'mcp',
     'permission',
     'permission-done',
+    'notify',
     'permission-card',
     'presence',
+    'herdr',
 ]);
 const FLAGS = {
     help: {},
@@ -88,6 +103,7 @@ const FLAGS = {
     listen: { origin: true, app: true, thread: true, handed: false },
     permission: { origin: true, app: true },
     'permission-done': { origin: true, app: true },
+    notify: { origin: true, app: true },
     'permission-card': { origin: true, session: true, worker: true },
     presence: {
         origin: true,
@@ -119,6 +135,19 @@ const FLAGS = {
     refresh: { origin: true, force: false, app: true },
     'mcp-headers': { origin: true, check: false, app: true },
     mcp: { origin: true, app: true, check: false },
+    herdr: {
+        origin: true,
+        app: true,
+        session: true,
+        transcript: true,
+        name: true,
+        state: true,
+        at: true,
+        demo: false,
+        yes: false,
+        wait: false,
+        ensure: false,
+    },
 };
 const VALUE_OPTIONS = new Set([
     'origin',
@@ -154,6 +183,7 @@ export const HOOK_COMMANDS = new Set([
     'posted',
     'permission',
     'permission-done',
+    'notify',
     'presence',
 ]);
 const THREAD = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/;
@@ -315,6 +345,7 @@ export function parseArgs(argv, env = {}) {
         }
         case 'permission':
         case 'permission-done':
+        case 'notify':
             none();
             return { name: first, origin, ...app() };
         case 'permission-card': {
@@ -377,6 +408,8 @@ export function parseArgs(argv, env = {}) {
         case 'mcp':
             none();
             return { name: 'mcp', origin, ...app(), check: flags.has('check') };
+        case 'herdr':
+            return herdrCommand(origin, positional, flags, app);
         case 'init':
             none();
             return {
@@ -411,6 +444,87 @@ export function parseArgs(argv, env = {}) {
     }
     throw new UsageError(`There’s no “${first}” command.`);
 }
+function herdrCommand(origin, positional, flags, app) {
+    const [sub, target, ...extra] = positional;
+    if (sub === undefined)
+        throw new UsageError('herdr needs what to do, like: pendingyou herdr doctor');
+    if (!HERDR_SUBS.includes(sub))
+        throw new UsageError(`herdr has no “${sub}”. Use ${HERDR_SUBS.join(', ')}.`);
+    const allowed = {
+        report: ['app', 'session', 'transcript', 'name', 'state', 'at'],
+        next: [],
+        open: ['demo'],
+        setup: ['yes'],
+        doctor: ['wait'],
+        unconfigure: [],
+        watch: ['ensure'],
+        event: [],
+        view: [],
+        popup: [],
+    };
+    for (const key of flags.keys())
+        if (key !== 'origin' && !allowed[sub].includes(key))
+            throw new UsageError(`herdr ${sub} has no --${key} option.`);
+    const command = { name: 'herdr', origin, sub: sub };
+    const takes = (choices) => {
+        if (extra.length || (target !== undefined && !choices?.includes(target)))
+            throw new UsageError(choices
+                ? `herdr ${sub} takes ${choices.join(' or ')}.`
+                : `herdr ${sub} takes no “${target ?? extra[0]}”.`);
+    };
+    const text = (key) => {
+        const value = flags.get(key);
+        return typeof value === 'string' ? value : undefined;
+    };
+    switch (command.sub) {
+        case 'report': {
+            takes(null);
+            const session = text('session');
+            if (session !== undefined && !THREAD.test(session))
+                throw new UsageError('herdr report needs a session id, like: --session 0199a1b2-…');
+            const state = text('state');
+            if (state !== undefined && state !== 'live' && state !== 'closed')
+                throw new UsageError('--state is live or closed.');
+            const at = text('at');
+            if (at !== undefined && !/^\d{1,16}$/.test(at))
+                throw new UsageError('--at needs a number.');
+            const transcript = text('transcript');
+            const agentName = text('name');
+            return {
+                ...command,
+                app: app().app ?? DEFAULT_APP,
+                ...(session ? { session } : {}),
+                ...(transcript ? { transcript } : {}),
+                ...(agentName ? { agentName } : {}),
+                closed: state === 'closed',
+                ...(at ? { at: Number(at) } : {}),
+            };
+        }
+        case 'popup':
+            if (target === undefined)
+                throw new UsageError(`herdr popup needs a pane: ${HERDR_POPUPS.join(', ')}.`);
+            takes(HERDR_POPUPS);
+            return { ...command, target };
+        case 'view':
+            takes(['on', 'off']);
+            return target ? { ...command, target } : command;
+        case 'open':
+            takes(null);
+            return { ...command, demo: flags.has('demo') };
+        case 'setup':
+            takes(null);
+            return { ...command, yes: flags.has('yes') };
+        case 'doctor':
+            takes(null);
+            return { ...command, wait: flags.has('wait') };
+        case 'watch':
+            takes(null);
+            return { ...command, ensure: flags.has('ensure') };
+        default:
+            takes(null);
+            return command;
+    }
+}
 export const USAGE = `pendingyou: Pending You for your coding agents (Claude Code, Codex, OpenCode and Pi)
 
   npx -y pendingyou@latest init
@@ -436,6 +550,9 @@ export const USAGE = `pendingyou: Pending You for your coding agents (Claude Cod
   npx pendingyou mcp --app <app>
                                A stdio MCP server for an agent that can't run a headers helper: it
                                passes each message on to Pending You with that agent's sign-in here
+  npx pendingyou herdr doctor  Pending You in Herdr: the badges on your agents' panes, the plugin, its
+                               toasts and its sidebar row. The plugin runs herdr next, open, setup,
+                               view and unconfigure
 
 Apps (for --app): ${APP_IDS.map((app) => `${app} (${APP_NAMES[app]})`).join(', ')}.
 

package/dist/claude.js

@@ -26,6 +26,7 @@ export const PERMISSION_HOOKS = [
     { event: 'PostToolUse', sub: 'permission-done' },
     { event: 'PostToolUseFailure', sub: 'permission-done' },
     { event: 'SessionEnd', sub: 'permission-done', timeout: null },
+    { event: 'Notification', sub: 'notify', matcher: 'permission_prompt' },
 ];
 export const PERMISSION_CLAUDE = '2.1.119';
 export const PERMISSIONS = ['Bash(npx pendingyou hold:*)', `mcp__${MCP_NAME}`];
@@ -337,7 +338,11 @@ export async function installClaude(io, origin, options) {
     const permissionLines = wanted && !blocker
         ? Object.fromEntries(PERMISSION_HOOKS.map((spec) => [spec.event, options.hookLine(spec.sub)]))
         : null;
-    const merged = mergeSettings(await readSettings(io), commands, permissionLines);
+    const settings = await readSettings(io);
+    const had = hooksOf(settings, 'Claude Code’s settings');
+    const upgrade = Boolean(findHook(had, 'PermissionRequest', 'permission')) &&
+        !findHook(had, 'Notification', 'notify');
+    const merged = mergeSettings(settings, commands, permissionLines);
     report({
         ok: true,
         text: merged.hooksChanged
@@ -349,7 +354,9 @@ export async function installClaude(io, origin, options) {
         ok: true,
         text: permissionLines
             ? merged.permissionChanged
-                ? 'Added the permission-prompt hooks: when Claude Code waits for your OK and you don’t answer within a few seconds, a card says so (a push only after your hand-off wait), and it goes once you answer in Claude Code.'
+                ? upgrade
+                    ? 'Added a Notification hook to the permission-prompt hooks: a dialog in bypassPermissions mode gets a card too, and so does one the other hooks don’t see, once Claude Code says it has waited a few seconds.'
+                    : 'Added the permission-prompt hooks: when Claude Code waits for your OK and you don’t answer within a few seconds, a card says so (a push only after your hand-off wait), and it goes once you answer in Claude Code.'
                 : 'The permission-prompt hooks were already installed.'
             : !wanted
                 ? `${merged.permissionChanged ? 'Took out the permission-prompt hooks' : 'Left out the permission-prompt hooks'}, as you asked: no card when Claude Code waits for your OK. To turn them on: npx pendingyou init --permission-cards${flag}`
@@ -470,6 +477,7 @@ export async function claudeState(io) {
     const skill = (await readText(skillPath(io))) !== null;
     let ours = (_event) => undefined;
     let permission = false;
+    let notify = false;
     const mod = { loads: false, dirs: [], present: false, plugin: false };
     const loads = claude ? claudeVersion(claude) : null;
     mod.loads = loads !== null && loadsMods(loads);
@@ -482,6 +490,7 @@ export async function claudeState(io) {
         const all = objectAt(settings, 'hooks') ?? {};
         ours = (event) => findHook(all, event, HOOKS[event]);
         permission = Boolean(findHook(all, 'PermissionRequest', 'permission'));
+        notify = Boolean(findHook(all, 'Notification', 'notify'));
     }
     catch { }
     const start = ours('SessionStart');
@@ -496,6 +505,7 @@ export async function claudeState(io) {
         hooks: Boolean(start && ours('UserPromptSubmit')),
         stopcheck: Boolean(ours('Stop')),
         permission,
+        notify,
         presence: Boolean(ours('SessionEnd')),
         form: form ? { ...form, runs: await hookRuns(form), shim } : null,
         mod,

package/dist/format.js

@@ -1,3 +1,12 @@
+export function noticeOf(heard) {
+    const given = heard.notice;
+    if (typeof given !== 'object' || given === null)
+        return null;
+    const { kind, from } = given;
+    if ((kind !== 'follow_up' && kind !== 'handed_over') || typeof from !== 'string')
+        return null;
+    return { kind, from };
+}
 export const HANDED_PREFIX = 'Pending You: your person handed you';
 export const HANDED_REPLY = 'on the question handed to you';
 export const HANDED_TALK_TODO = 'If you know now, answer_delegated with your answer and how you know; if you need more, reply_in_thread to “asker”; if it’s your person’s to decide, reply_in_thread with escalate true; if not, hand_back with what you checked.';
@@ -81,11 +90,37 @@ function describeHanded(heard, delegated) {
         ...(note?.cut ? [`(Cut short: get_request ${id} has all of it.)`] : []),
     ];
 }
+function describeNotice(heard, notice) {
+    const id = heard.requestId;
+    const from = clip(notice.from, MAX_NAME).text;
+    const ack = `ack_answer with requestId ${id}, name ${named(heard)} and expectedVersion ${heard.version}`;
+    if (notice.kind === 'handed_over')
+        return [
+            `Pending You: your person handed your open cards to ${from}, ${id} among them.`,
+            `Stop working on them: ${from} answers them and follows up. Call ${ack} to say you’ve stopped.`,
+        ];
+    let cut = false;
+    const wrote = heard.messages.map((message) => {
+        const said = quoted(message.body, MAX_MESSAGE);
+        cut ||= said.cut;
+        return said.line;
+    });
+    return [
+        `Pending You: ${from} followed up on ${id}, which it answered for your person.`,
+        `Question: ${clip(heard.title, MAX_TITLE).text}`,
+        ...wrote,
+        `Act on it if it needs anything, then call ${ack} to mark it heard.`,
+        ...(cut ? [`(Cut short: get_request ${id} has all of it.)`] : []),
+    ];
+}
 export function describe(heard, again) {
     const id = heard.requestId;
     const delegated = delegatedOf(heard);
     if (delegated)
         return describeHanded(heard, delegated);
+    const notice = noticeOf(heard);
+    if (notice && heard.status !== 'answered')
+        return describeNotice(heard, notice);
     const question = `Question: ${clip(heard.title, MAX_TITLE).text}`;
     let cut = false;
     const wrote = heard.messages.map((message) => {
@@ -111,7 +146,7 @@ export function describe(heard, again) {
                 lines.push(`Pending You: ${id} is answered.`, question, `Answer: ${answer.text}`);
             }
             if (wrote.length)
-                lines.push(`They also wrote: ${wrote.join(' ')}`);
+                lines.push(`${noticeOf(heard) ? 'Also' : 'They also wrote'}: ${wrote.join(' ')}`);
             lines.push(`Act on it, then call ack_answer with requestId ${id}, name ${named(heard)}, expectedVersion ${heard.version} and a one-line outcome.`);
             break;
         }