pendingyou 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,11 +1,134 @@
 # Changelog
 
+## 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
+  connection here, `POST <origin>/mcp/cli/presence` with `{"source", "name", "sessionId", "cwd", "state"}` (`name` the
+  name the session goes by with Pending You, else null; `cwd` only as `~/…`, else null; `state` `live` or `closed`).
+  Pending You counts a session live for 15 minutes after its last `live`, so an open session says so every 5 minutes,
+  with no model involved:
+  - Claude Code: its session-start hook says live; the wake mod (Claude Code 2.1.287 or later) says live as the
+    session starts, after /clear or /resume, and every 5 minutes while it's open, by running the hooks' script; a new
+    SessionEnd hook, `presence`, through the same script, says closed. Without the wake mod, the next-message hook
+    says live again once the last was 4 minutes ago. Only `init`'s copy of the mod does it, never the plugin's.
+  - Codex: its session-start and next-message hooks start a keeper for the thread (`presence --keep`, detached, a lease
+    of its own), which says live every 5 minutes while the Codex process the hooks ran under is running (Codex CLI, or
+    the Codex app's own codex), and closed once it's gone. A new SessionEnd hook (Codex fires it when a conversation
+    is archived or deleted, when Codex closes, or after 30 idle minutes) says closed and stops the keeper; its timeout
+    is 3 seconds, the most Codex gives one. Where the Codex process can't be found, the hooks say live as they run.
+  - OpenCode's plugin and Pi's extension say live as a session starts (OpenCode: when it's created, or its first
+    message) and every 5 minutes while the app runs, and closed when OpenCode deletes the session or goes, or Pi shuts
+    the session down.
+  A hook only starts the send in the background; a send gives up after 3 seconds; a Pending You from before presence
+  answers 404, which is taken quietly. A sign-in that only hears (`--oauth`) sends nothing. Events are written down in
+  `~/.config/pendingyou/presence/<app>.json` (ids, states and times), so a late `live` never overrides a newer
+  `closed`, and a reload's `live` goes after its `closed`. `status` has a line for each app: “Presence: tells Pending
+  You when this session is open”.
+- Codex's permission prompts on a card, as Claude Code's since 0.13.0. `init` adds Codex's PermissionRequest hook (it
+  fires when Codex is about to ask for approval: a shell command that needs more than the sandbox gives, an
+  `apply_patch`, an MCP tool; `tool_name` Bash, apply_patch or the tool's, and `tool_input.description` when Codex has
+  a reason), through the shim with `--app codex`. Codex reads that hook's output as its decision, so it prints nothing
+  and exits 0: it declines, and Codex asks as before. Once a prompt has waited 10 seconds, the same detached worker
+  posts one card with Codex's own connection: “Codex is waiting for your OK: git push origin main”, “…: edit
+  src/app.ts and 1 more” for a patch (the files its `*** Update File:` lines name), “…: create_issue on github” for an
+  MCP tool, with Codex's reason (redacted) in the summary, under the name the thread went by on Pending You's card tools,
+  else “Codex”, and the same redaction. It's withdrawn when the call runs (a PostToolUse hook for every tool, which
+  also settles a prompt for the same tool when Codex gives the call that ran its input in another form), with your
+  next message, at the end of the turn, or when the thread ends (SessionEnd). `--no-permission-cards` leaves Codex's
+  out too. The Codex app's browser-use prompts run no PermissionRequest hook, so they get no card.
+- Presence keeps to Pending You's contract: the name trimmed to one line of at most 60 characters, a folder over 300
+  characters sent as null, a 401 tried once more after a refresh in the background, a 429 waited out once (its
+  `retry-after`, 60 seconds) by a send in its own process (never a hook), and 400, 403 and 404 taken quietly; Codex's
+  keeper stops once a send is refused, its sign-in is gone, or the server has no presence.
+- A question you handed an agent, when the assistant that asked answers what the helper asked it on the card (or you
+  write in to them both, guide 2.30), wakes the helper with those words, not the handed question again: “Pending You:
+  billing-webhooks replied on the question handed to you, “Which queue?” (req_…): “It's the jobs queue.”. Call
+  get_request (requestId req_…, name “infra”) to read what you've said to each other. If you know now,
+  answer_delegated …; 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 …” (“your person wrote to you both …” for yours). The same from the hooks, the
+  wake mod, OpenCode's plugin and Pi's extension; Codex's `codex queue` leaves the words out of its arguments, where any
+  program could read them, and get_request has them. The wake mod now wakes a session for such a reply after it read
+  the question itself (before, a question it had read never woke it again), and the Stop check and the hooks know a
+  turn such a wake started.
+- Switching an agent's own sign-in to this computer's says what becomes of the old one: once the agent shows up on this
+  computer's sign-in, Pending You moves the old sign-in's agents over, with their cards and the questions you delegated
+  to them, and signs it out. Where there's no browser (an SSH session) init says what it switched instead of switching
+  without a word.
+- Codex runs a hook only once you trust it, so the three new hooks (PermissionRequest, PostToolUse for every tool,
+  SessionEnd) need trusting once. They go at the end of their lists, so the ones you trusted stay trusted. `init` says
+  so when it adds them to a Codex set up before (“Codex has new Pending You hooks (session end and permission prompts),
+  which it skips until you trust them once: …”), and `status` has a line for each, with each hook's trust:
+  “Permission prompts: a card when Codex waits for your OK” and “Presence: …”. Neither keeps `status` from saying
+  Ready. Codex's record of its hooks (`codex.json`) now names each by its event and command.
+
+## 0.14.0 (2026-10-05)
+
+- Questions your person hands one of your agents from another assistant (Delegate: Pending You's card link, or D on the
+  desk). Once the delegation's 5-second hold is over, Pending You's `/mcp/cli/answers` brings such a question to the
+  app's sign-in, marked `delegated` (who asked, `freely` or `loop`, the person's note), under the name the helper
+  answers with (`sessionLabel`, the task the person picked) and in that task's folder (`cwd`). The hooks used to say
+  “Pending You: they wrote back on req_…”; now a session start or message says “Pending You: your person handed you
+  req_…, a question from billing-webhooks (answer freely: your answer goes straight to billing-webhooks).”, the
+  question, “Their note: “…””, and “Call get_request (requestId req_…, name “infra”) to read it. If you know,
+  answer_delegated with your answer and how you know; if not, hand_back with what you checked.” (“they’ll see your
+  answer first” when the person kept themselves in the loop). The header says “your person handed you a question from
+  another assistant” (or “answered, and handed you …”), never “your person answered”, and the line to tell the person
+  first is “You handed me a question from …”.
+- Which session hears one (`src/handed.ts`), the same for every app: a session that goes by its name in its folder
+  (the task the person picked; the most recent of several), else the session in that folder that used Pending You
+  most recently, never the one that asked it (a session that goes by the asking assistant's name), and never two: the
+  session that takes it claims it first in `state.json` (`claimHanded`), and gives it back if it couldn't be told. A
+  question with no folder (a task that never said one) goes to a session by its name anywhere, else the app's most
+  recent. A sign-in that only hears (`--oauth`) hears every computer's questions, so it leaves one whose `machine`
+  (the computer Pending You says it went to, as the Assistants page names it) is another computer than this one, by
+  its name or its hostname (the hostname, the names its code sign-ins were given, a Mac's own name, and, outside a
+  hook, Tailscale's); one with no `machine` goes by the folder. The hooks hand a session one at once when it goes by that name (or it's the session the listeners would
+  wake); another session in the folder only after 5 minutes, so the one it went to hears it first.
+- Claude Code's wake mod wakes the session it's for: while a session used Pending You in the last 12 hours (as long as
+  Pending You offers its task as running), it asks `list_pending` with the session's name every minute for the first
+  half hour, then every 3 minutes; reads each new one with `get_request` (who asked, how its answer travels, whether
+  there's a note); and starts one turn, “Pending You: your person handed you “…” (req_…), a question from … Call
+  get_request (requestId req_…, name “infra”) to read it and their note. If you know, answer_delegated …; if not,
+  hand_back …”, never with the note. It claims each in its store (`handed:<requestId>`), so another session by the same
+  name doesn't hear it too, and never wakes a session for one it read or answered itself. Among sessions by one name,
+  the one working in the folder of the task it went to (`list_pending`'s `cwd`: the folder the session started in, or
+  one it gave its own cards, `~/…` or full) takes it, one elsewhere never does, and one that can't tell its folder
+  waits 5 minutes. The hand-off hook that
+  runs for the mod's prompt claims it in `state.json` without saying it twice. `answer_delegated` and `hand_back` are
+  among the calls it reads. Regenerated into the plugin's builds too, which reach installed plugins with the next guide
+  release.
+- Codex: one listener for the app, `pendingyou listen --app codex --handed` (detached, a lease of its own), started by
+  the hooks while any thread may be handed a question, `codex queue`s each into the thread it's for, in the wake mod's
+  words, and gives it back (forgetting the thread) when Codex doesn't know the thread. Codex's hooks now remember each
+  thread's names and folder (`codex-threads.json`), and keep a thread for 12 hours after it last used the card tools,
+  with no card of its own waiting; a session start or message marks it active. A thread's own listener is never woken
+  for its own card while it's with another assistant.
+- OpenCode and Pi: a session's listener also wakes it for a question handed to it, and keeps listening for one for 12
+  hours after the session last used the card tools (`opencode-threads.json`, `pi-threads.json`), while the app is
+  open. OpenCode's plugin starts it with each message while the record says so, and passes the session's folder to
+  `posted`; Pi's extension starts it as before, now for that too. Both start a listener again when a card call asked for
+  one while the last was on its way out: a card posted just as a session's first listener stopped (finding nothing to
+  listen for) went unheard until the next message.
+- `watch` names a handed question's event `delegated_ready` (`PENDINGYOU_EVENT`), with `delegated` in the JSON on
+  stdin.
+- The Stop check never asks a helper to post the question as a card of its own. `answer_delegated` and `hand_back`
+  count as the turn's card calls (Claude Code's transcript, OpenCode's turn, Pi's extension); a turn a handed
+  question's wake started (its first message the wake's words: Claude Code's transcript, OpenCode's turn, Pi's extension
+  says `handed`, Codex's next-message hook records it when Codex gives the message) that left the person something in
+  chat without either is asked once: “Your person handed you that question to answer, not to ask them back:
+  answer_delegated if you know, or hand_back with what you checked, unless you already did. Never post it as a card of
+  your own.” Codex's PostToolUse hook is trusted by its exact matcher, which names only the four card tools, so it never
+  sees those two calls (a new matcher would have to be trusted again).
+- The package names no one, and carries only what runs. Its JavaScript is built without the source's comments, and so is
+  the wake mod's (`mod/hooks`); its examples and this changelog use made-up names (`--name build-01`); and the mod's
+  test, which only `claude plugin test` reads, stays out of the package. Nothing the command line does changes.
+
 ## 0.13.0 (2026-10-04)
 
-- Claude Code's permission prompts on a card (Darin, 2026-10-04: "Tell me: a card and a push, cleared once I answer in
-  the terminal"). A Claude Code agent kept asking to remove files and sat waiting until Darin happened to look. `init`
-  now adds Claude Code's PermissionRequest hook (https://code.claude.com/docs/en/hooks: it runs as Claude Code is about
-  to ask for permission to use a tool, with `tool_name` and `tool_input`), through the shim with `--app claude-code`.
+- Claude Code's permission prompts on a card: a card and a push, cleared once you answer in the terminal. A Claude Code
+  agent kept asking to remove files and sat waiting until its person happened to look. `init` now adds Claude Code's
+  PermissionRequest hook (https://code.claude.com/docs/en/hooks: it runs as Claude Code is about to ask for permission
+  to use a tool, with `tool_name` and `tool_input`), through the shim with `--app claude-code`.
   It never decides: it prints nothing, so the prompt shows exactly as before, and it's done in about a tenth of a
   second. It writes the prompt down (its card's redacted words, never the tool's input) in the session's own file,
   `~/.config/pendingyou/permission-cards/<session>.json`, and starts that session's one worker, detached (`pendingyou
@@ -67,8 +190,8 @@
   approve: 1. whoami with your name. If it says app.setUp is true, another session did this: stop. 2. report_setup with
   source codex, your name, skillSaved true, hears instant, and skillVersion set to whoami’s skill.latest. Its answer
   has a testAreaId. 3. post_request a short test question in that testAreaId, tell your person it’s on its way, and end
-  your turn: you’re woken when they answer, so don’t ask them to type anything.” Pi's first setup on Darin's devbox
-  spent about 20,000 tokens on the words before: “whoami with your name and guide true” answered with the whole guide
+  your turn: you’re woken when they answer, so don’t ask them to type anything.” Pi's first live setup spent about
+  20,000 tokens on the words before: “whoami with your name and guide true” answered with the whole guide
   (87,000 characters), which Pi cut into a file the model then parsed, and “your test question in its testAreaId” sent
   it looking for testAreaId in whoami's answer, where it isn't (report_setup's has it). A setup that has reported gets
   the same calls without whoami's way out (its whoami says app.setUp is true); a test card answered says who picks it
@@ -144,7 +267,7 @@
 
 ## 0.11.0
 
-- One step for the coding agents on a computer (Darin, 2026-10-04): `npx -y pendingyou@latest init` finds Claude Code
+- One step for the coding agents on a computer: `npx -y pendingyou@latest init` finds Claude Code
   and Codex (`--app claude-code,codex` names some), says what it found and which it can't set up (an agent too old for
   it is named, with the version it needs), and sets each up with one approval. Then: restart the agent, and its first
   session finishes setting up by itself (whoami, report_setup, a test card). Asked for by name and not installed, or
@@ -222,10 +345,10 @@
 - The next-message hook looks for this folder's answers with every message, not only while a hold had left an entry
   behind: one request, as before, given up after 2 seconds, inside the hook's 3-second deadline. `state.json` no
   longer keeps holds' waits.
-- A computer with no browser (a devbox or server you SSH into): one code approved on your phone sets Claude Code up.
+- A computer with no browser (a server you SSH into): one code approved on your phone sets Claude Code up.
   `/mcp`'s Authenticate opened a browser on that machine, which nobody could reach, and `login --device` only signed
   this command in. Now `init` there (an SSH session, or Linux with no display; `--device` forces it, `--browser` the
-  browser) signs the machine in by code as a Claude Code connection of its own ("Claude Code on devbox" on your
+  browser) signs the machine in by code as a Claude Code connection of its own ("Claude Code on build-01" on your
   Assistants page, named by `--name`, else Tailscale's name for it, else its hostname; `login --name` with a new name
   renames the connection with one more approval, which `login` suggests for a cloud's own name like `ip-10-42-1-252`;
   QR code of the link at a terminal), then adds the MCP server with a `headersHelper` instead of OAuth
@@ -239,8 +362,8 @@
   PATH), each with the command that fixes it, `--origin` included off production. `uninstall` takes the helper out and
   says the connection stays on your Assistants page. Needs Pending You's Worker from the same release.
 - `login` over SSH signs in by code without `--device`. A sign-in by code names the computer, and the phone asks "Let
-  devbox hear your answers for the assistants running on it?"; in the browser, "Let this computer hear…". Neither offers
-  a choice of assistant any more (Darin, 2026-10-04): a computer hears for the assistants running on it. A sign-in
+  build-01 hear your answers for the assistants running on it?"; in the browser, "Let this computer hear…". Neither
+  offers a choice of assistant any more: a computer hears for the assistants running on it. A sign-in
   pointed at one assistant before then keeps hearing it, so `watch` for a Muse or another app can't be set up anew.
 - Routing by sender: the hooks and `hold` ask Pending You for Claude Code's cards only (`source=claude-code`), so a card
   Codex or another app posted from the same folder never reaches a Claude Code session, even with a sign-in pointed at

package/README.md

@@ -24,10 +24,12 @@ Run it once on each computer, in a terminal. It finds the agents on the computer
   Pi reads Codex's, else `~/.pi/agent/skills/pendingyou/SKILL.md`),
 - adds the hooks that hand it your answers: a new session picks up answers that arrived while nothing was running,
   your next message brings a waiting answer with it, and a check when it finishes a turn catches what it left you only
-  in chat ([below](#nothing-left-only-in-chat)); and, for Claude Code, a card when it waits for your OK to run something
-  ([below](#when-claude-code-waits-for-your-ok)),
+  in chat ([below](#nothing-left-only-in-chat)); for Claude Code and Codex, a card when it waits for your OK to run
+  something ([below](#when-claude-code-waits-for-your-ok)); and they tell Pending You which sessions are open
+  ([below](#which-sessions-are-open)),
 - and wakes it when you answer: Claude Code 2.1.287 or later through the wake mod, Codex through `codex queue`, OpenCode
-  through its plugin and Pi through its extension (which also do the hooks' work there).
+  through its plugin and Pi through its extension (which also do the hooks' work there); and when you hand it a
+  question from another of your assistants ([below](#when-you-hand-an-agent-a-question)).
 
 Then it says what to do next, and the one sentence to say if it's needed:
 
@@ -53,10 +55,11 @@ in each, every other byte as it was), and running it again changes nothing it do
 **A pendingyou server that's there already** is decided on before anyone signs in. One at another Pending You
 (staging, say) is named and replaced only once you say so (`--yes` replaces it without asking); keep it and that agent
 is left as it is. One at this Pending You that signs in by itself (Claude Code's `/mcp` → Authenticate, Codex's
-`codex mcp login`, or the Pending You plugin for Claude) is moved to this computer's sign-in: without asking where
-there's no browser (it can't finish there anyway), on Yes (the default) at a terminal, or with `--yes`; with nobody to
-ask it's kept, and `init` prints the command that switches it. The connection it had stays on your Assistants page for
-you to remove, and answers to the cards it asked through that one won't reach the agent by themselves. A kept plugin
+`codex mcp login`, or the Pending You plugin for Claude) is moved to this computer's sign-in: where there's no browser
+(it can't finish there anyway) without asking, saying what it switched; on Yes (the default) at a terminal; or with
+`--yes`; with nobody to ask it's kept, and `init` prints the command that switches it. Once the agent shows up on this
+computer's sign-in, Pending You moves the old sign-in's agents over to it, with their cards and the questions you
+delegated to them, and signs the old one out. A kept plugin
 carries the skill, so none is saved. `--oauth` keeps every agent signing in by itself, as before 0.11.0.
 
 The hooks run a copy of this version kept in `~/.config/pendingyou/cli/<version>/`, through a small script with a path
@@ -93,10 +96,13 @@ http_headers_helper = "/Users/ann/.config/pendingyou/bin/pendingyou-mcp-headers
 default_tools_approval_mode = "approve"
 ```
 
-and four hooks in `~/.codex/hooks.json`: a session start, each message, Pending You's card tools (so the Stop check
-knows a turn posted, and so the thread is woken), and the Stop check. **Codex runs a hook only once you trust it**: in
-Codex CLI, start `codex` and choose “Trust all and continue” (or trust them in `/hooks`); in the Codex app, click
-Review hooks › Allow all (or Settings › Hooks › Trust all). `status` says which are trusted. A `pendingyou` server or
+and hooks in `~/.codex/hooks.json`: a session start, each message, Pending You's card tools (so the Stop check knows a
+turn posted, and so the thread is woken), and the Stop check; and (0.15.0) Codex's permission prompt and every tool
+call that ran (a card when Codex waits for your OK, [below](#when-claude-code-waits-for-your-ok)) and the session's end
+([below](#which-sessions-are-open)). **Codex runs a hook only once you trust it**: in Codex CLI, start `codex` and
+choose “Trust all and continue” (or trust them in `/hooks`); in the Codex app, click Review hooks › Allow all (or
+Settings › Hooks › Trust all). `status` says which are trusted. Upgrading from 0.14.0 adds three hooks, which Codex
+skips until you trust them once; `init` says so, and the ones you trusted stay trusted. A `pendingyou` server or
 hooks Codex's `/import` copied from Claude Code (without its sign-in) are replaced.
 
 **The Codex app** (on a Mac, in the ChatGPT app) shares all of this with Codex CLI: the same `~/.codex`, server, hooks
@@ -111,7 +117,8 @@ it with `codex queue`: “Pending You: your person answered “…” (req_…).
 answer itself never goes in a command's arguments, where other programs could see it). Codex starts a turn at
 once when the thread is open and idle, after the current one when it's working, or when you next open it. In the Codex
 app, a chat it has open is woken while the app runs (one it let go, idle 3 hours or behind 10 newer idle chats, when
-you open it again).
+you open it again). One more listener, for the whole app, queues a question you hand a thread from another assistant
+([below](#when-you-hand-an-agent-a-question)).
 
 ## OpenCode
 
@@ -139,7 +146,8 @@ does in OpenCode what the hooks do elsewhere, through the same hooks' script: ea
 reminder and any answer waiting (hidden in OpenCode's view, read by the model), a session's first message also says
 what setup has left, a session that left you a question in chat is asked once to put it on a card (with a toast saying
 why), and when you answer a card a session posted, the plugin starts a turn in that session: “Pending You: your person
-answered “…” (req_…). Call get_request …” (never the answer itself). That works while OpenCode is open, idle or busy.
+answered “…” (req_…). Call get_request …” (never the answer itself). That works while OpenCode is open, idle or busy,
+and for a question you hand the session from another assistant too ([below](#when-you-hand-an-agent-a-question)).
 
 Then restart OpenCode (`/exit`, then `opencode --continue`): it finishes setting up the first time you write to it.
 
@@ -167,7 +175,9 @@ Pi has no hooks, so `init` gives it an extension: `~/.config/pendingyou/pi/pendi
 the same hooks' script as a session starts, with each message, after Pending You's card tools and as a run ends (a run
 that leaves you something only in chat goes on once), and when you answer a card a session posted it starts a turn in
 that session, idle or busy: “Pending You: your person answered “…” (req_…). Call get_request …” (never the answer
-itself). In Pi's terminal the first session finishes setting up by itself, once Pending You's tools are there.
+itself), and the same for a question you hand it from another assistant
+([below](#when-you-hand-an-agent-a-question)). In Pi's terminal the first session finishes setting up by itself, once
+Pending You's tools are there.
 
 Then run `/reload` in each Pi session that's open, or start `pi`. Pi's shell waits for a command to end, so in Pi
 `npx pendingyou hold` answers at once instead of waiting.
@@ -208,6 +218,13 @@ replied on a card comes from Codex's own hook for Pending You's tools in that tu
 action card titled “Confirm in Codex on <computer>: <step>” when it asked you to type something there. OpenCode's plugin
 and Pi's extension (0.12.0) do the same in theirs.
 
+A question you hand an agent from another assistant (0.14.0) is never asked to go on a card of its own: answering it
+(`answer_delegated`) or giving it back (`hand_back`) puts it in front of you, so it counts as the turn's card call. A
+turn that such a question started, and that left you something in chat without doing either, is asked once to answer
+it or hand it back instead (about 45 tokens). Codex's hook for Pending You's tools is trusted by its exact list of
+tools, which doesn't name those two, so there the check knows only that the turn started with one (when Codex gives the
+message to its next-message hook), and says “unless you already did”.
+
 **On 0.2.0 with another origin?** Its hooks blocked every message (`There's no "--origin" command`). Run
 `npx pendingyou@latest init --origin <url>` again to repair them; see [CHANGELOG.md](CHANGELOG.md).
 
@@ -233,6 +250,32 @@ It needs Claude Code 2.1.119 or later, signing in through this computer's sign-i
 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.
 
+**Codex** (0.15.0) gets the same: when Codex stops to ask for your approval (a command that needs more than its sandbox
+gives, a patch, an MCP tool) and you don't answer within 10 seconds, a card says “Codex is waiting for your OK: git push
+origin main” (“…: edit src/app.ts and 1 more” for a patch), with Codex's reason for asking, blanked like the rest. Its
+PermissionRequest hook prints nothing, so Codex asks exactly as before; the card goes once the call runs, you write to
+Codex, the turn ends or the thread closes. It needs Codex signing in through this computer's sign-in, and trusting the
+new hooks once. The Codex app's browser-use prompts don't run that hook, so they get no card.
+
+## Which sessions are open
+
+Since 0.15.0 Pending You hears which of your agents' sessions are open right now, so it can say so and offer an open
+one a question. Each app tells it with its own connection here: the session's id, the name it goes by with Pending You,
+its folder (under `~` only) and `live` or `closed`. Pending You counts a session open for 15 minutes after its last
+`live`, so an open session says so every 5 minutes, with no model involved:
+
+- **Claude Code**: as a session starts (its session-start hook, and the wake mod), then every 5 minutes from the wake
+  mod while it's open (without the mod, with your messages); closed as it ends (a SessionEnd hook).
+- **Codex**: as a thread starts or you write to it, a small process in the background says so every 5 minutes while
+  Codex (or the Codex app) runs, and closed once it's gone; its SessionEnd hook (a conversation archived or closed, or
+  idle 30 minutes) says closed.
+- **OpenCode and Pi**: the plugin and the extension, as a session starts and every 5 minutes while the app runs, and
+  closed as it goes.
+
+It's never in your way: the hooks only start it in the background, each send gives up after 3 seconds, and a Pending
+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.
+
 ## 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
@@ -269,10 +312,38 @@ allowed and the server has connected). When it isn't, it starts one turn once th
 Pending You: it’s connected here already.” and exactly what to do. Once per session, in at most three sessions, never
 two within ten minutes, and never again once Pending You says it's set up.
 
+## When you hand an agent a question
+
+In Pending You you can hand a card to another of your assistants, a coding task included (Delegate: the card's link,
+or D on the desk): it answers for you (“Answer freely”), or its answer comes back to you first (“Keep me in the loop”),
+or it hands the card back with what it checked. Since 0.14.0 the task you picked hears it the way it hears your
+answers, once the 5-second window to undo is over:
+
+- **Which session**: the one that goes by the task's name in its folder (the most recent, when several do); else the
+  session in that folder that used Pending You most recently; never the one that asked, and never two. A sign-in that
+  only hears (`--oauth`) hears every computer's, so it leaves one Pending You says went to another computer (by its
+  name or its hostname); one that names no computer goes by the folder.
+- **Claude Code**: the wake mod looks for questions handed to the session's name (`list_pending`, every minute while
+  the session used Pending You in the last half hour, then every 3 minutes, for 12 hours), reads each with
+  `get_request`, and starts a turn: “Pending You: your person handed you “Which AWS account for staging?” (req_…), a
+  question from billing-webhooks (answer freely: your answer goes straight to billing-webhooks). Call get_request
+  (requestId req_…, name “infra”) to read it and their note. If you know, answer_delegated with your answer and how you
+  know; if not, hand_back with what you checked.” Among sessions by one name, the one working in the task's folder
+  takes it (as `list_pending` gives it, `~/…` or a full path), one in another folder never does, and one that can't
+  tell its folder waits 5 minutes.
+- **Codex**: one listener for the app queues it into the thread it's for (`codex queue`, the same words).
+- **OpenCode and Pi**: the session's listener starts the turn through the plugin or extension; a session that used
+  Pending You's card tools keeps listening for 12 hours, while the app is open.
+- **Otherwise**: a session start or your next message in that folder brings it, with your note: at once in the
+  session that goes by the task's name, after 5 minutes in any other.
+
+Your note never goes in a program's arguments, where any other program on the computer could read it: the agent reads
+it with `get_request`.
+
 ## A computer with no browser
 
-On a devbox or server you reach over SSH, an agent's own sign-in opens a browser on that machine, which you can't
-reach. `init` signs in with a code there instead: SSH in, and at the prompt there run
+On a computer you reach over SSH (a build server, a machine in the cloud), an agent's own sign-in opens a browser on
+that machine, which you can't reach. `init` signs in with a code there instead: SSH in, and at the prompt there run
 
 ```sh
 npx -y pendingyou@latest init
@@ -289,15 +360,15 @@ hooks find Node anyway when the agents run without your shell's PATH (a systemd
 Remote Control): on PATH, nvm's default, the one `init` ran with, or where Node usually is.
 
 The machine is called by its Tailscale name when Tailscale is installed and running (as `tailscale status` shows it),
-else by its hostname, or by `--name devbox` on `init` or `login`; a Mac by its own name (Sharing in System Settings). A
-cloud's own hostname (AWS's `ip-10-42-1-252`) is kept when there's nothing better, and `login` says how to change it:
+else by its hostname, or by `--name build-01` on `init` or `login`; a Mac by its own name (Sharing in System Settings).
+A cloud's own hostname (AWS's `ip-10-42-1-252`) is kept when there's nothing better, and `login` says how to change it:
 `npx pendingyou login --name <name>` asks for one more approval and renames the connection, which stays the same one.
 If an agent's sign-in ends (30 days, or you remove it on your Assistants page), `npx pendingyou login` (`--app codex`
 for Codex's) approves a new code and keeps the same connection.
 
 Only want this command's own sign-in (for `watch`, below)? `npx pendingyou login --device` signs it in with a code,
-hearing answers only, and adds no connection. Your phone asks "Let devbox hear your answers for the assistants running
-on it?", with no choice of assistant.
+hearing answers only, and adds no connection. Your phone asks "Let build-01 hear your answers for the assistants
+running on it?", with no choice of assistant.
 
 ## Always-on scripts
 
@@ -309,10 +380,11 @@ npx pendingyou watch -- ./on-answer.sh
 
 It hears your Claude Code assistants' answers. Signing in asks no choice of assistant (since 2026-10-04: "Let pi hear
 your answers for the assistants running on it?"); a sign-in pointed at one assistant before then keeps hearing that
-one. The command runs without a shell, once per answer, message or fallback that comes due, oldest first. It
-gets the request as JSON on stdin, and `PENDINGYOU_REQUEST_ID`, `PENDINGYOU_EVENT` (`answer_ready`, `message_ready` or
-`fallback_due`), `PENDINGYOU_VERSION` and `PENDINGYOU_ORIGIN` in its environment. A failing command is tried twice
-more, then skipped. `--once` stops after the first.
+one. The command runs without a shell, once per answer, message or fallback that comes due, or (0.14.0) question you
+hand the assistant from another one, oldest first. It gets the request as JSON on stdin (a handed question with
+`delegated`: who asked, how its answer travels, your note), and `PENDINGYOU_REQUEST_ID`, `PENDINGYOU_EVENT`
+(`answer_ready`, `message_ready`, `fallback_due` or `delegated_ready`), `PENDINGYOU_VERSION` and `PENDINGYOU_ORIGIN` in
+its environment. A failing command is tried twice more, then skipped. `--once` stops after the first.
 
 ## Commands
 
@@ -345,24 +417,32 @@ Pending You (Claude Code says which server it's for; Codex's is the one `init` w
 sign-in each agent's connection used, so signing in again keeps it.
 
 `state.json` beside them remembers which answers were already handed over (ids only) and how many session starts
-reminded an unfinished setup, and when; `permission-cards/` each Claude Code session's prompts still waiting on your OK
-and its card (ids, hashes and the card's redacted words: never what the tool was given), gone once nothing waits;
+reminded an unfinished setup, and when; `permission-cards/` each Claude Code session's (and Codex thread's) prompts
+still waiting on your OK and its card (ids, hashes and the card's redacted words: never what the tool was given), gone once nothing waits;
+`presence/` the last presence each session said (ids, states and times), and Codex threads' keepers;
 `claude-code.json`, `codex.json`, `opencode.json` and `pi.json` what `init`
 added; `codex-threads.json`, `opencode-threads.json` and `pi-threads.json` which cards each Codex thread or OpenCode or
-Pi session waits on (ids, names and titles: never an answer); `pi/` Pi's extension; and `cli/` the hooks' copy of the
+Pi session waits on, and (0.14.0) the names it went by and its folder, kept 12 hours for a question you may hand it
+(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. For a permission prompt's card, the worker reads
+whether the agent has a `pendingyou` MCP server and where it points. 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
-get-url origin` in its folder (sent without any user name or password in it). Nothing is sent anywhere but Pending
-You. OpenCode's plugin reads its session's messages only when it goes idle, for the check that
+get-url origin` in its folder (sent without any user name or password in it). To tell when a Codex thread's Codex has quit, its
+keeper asks `ps` about the Codex process its hooks ran under (its id and program name, nothing else). Nothing is sent
+anywhere but Pending You. OpenCode's plugin reads its session's messages only when it goes idle, for the check that
 nothing was left in chat, and hands the hooks' script just that turn's words and tool names.
 
 The wake mod runs inside Claude Code and reaches Pending You only through the session's own connection, with
-`get_request` on the session's own cards (and, in `init`'s copy, `whoami` to see whether setup is finished). It keeps
-each session's cards (id, title, the agent's name, where each stands) in Claude Code's store for mods,
-`~/.claude/plugins/store/`, and forgets them once they close or after 7 days. It marks the copy acting for a session in
-that session's environment (`PENDINGYOU_WAKE_OWNER`).
+`get_request` on the session's own cards (and, in `init`'s copy, `whoami` to see whether setup is finished), and (0.14.0)
+`list_pending` with the session's name and `get_request` on a question you handed it. It keeps each session's cards (id,
+title, the agent's name, where each stands), and which handed questions a session was told of (ids and when), in Claude
+Code's store for mods, `~/.claude/plugins/store/`, and forgets them once they close or after 7 days. It marks the copy
+acting for a session in that session's environment (`PENDINGYOU_WAKE_OWNER`). `init`'s copy (0.15.0) also reads
+`~/.config/pendingyou/claude-code.json` for the Pending You it's for, and runs the hooks' script to say the session is
+open.
 
 ## Development
 

package/dist/api.js

@@ -1,32 +1,11 @@
-// Calls to Pending You with the command line's sign-in: a fresh access token (refreshed under the credentials lock,
-// so a hold and a hook never spend the same refresh token), one retry after a 401, and plain errors.
-//
-// Hooks never refresh in their own process. A hook has a hard deadline (main.ts), and a refresh cut off halfway can
-// end the sign-in: the server rotates the refresh token as it answers, and keeps exactly one earlier token valid
-// (@cloudflare/workers-oauth-provider's previousRefreshTokenId). A refresh abandoned before its answer arrives is
-// harmless on its own (the stored token is that earlier one, and still works), but if the server finishes it after a
-// later refresh has stored a newer token, that newer token stops working and the next refresh gets invalid_grant. So
-// a hook that needs a new token starts `pendingyou refresh` detached (background), which runs to the end under the
-// lock whatever happens to the hook, and waits for it only briefly; until it lands the hook uses the token it has, or
-// gives up and prints its plain fallback.
-//
-// Since 0.11.0 each app has its own sign-in (credentials.ts), and every call names the app it's for: its sign-in is
-// the one used, and a session's request names it as `source` (routing by sender, 2026-10-04), so Pending You returns
-// only that app's cards, never one Codex posted from the same folder to a Claude Code session there. `watch` names no
-// app: it hands answers to a script, not a session, with Claude Code's sign-in as before.
 import { DEFAULT_APP } from "./apps/ids.js";
 import { credentialsPath, readCredential, updateCredential, } from "./credentials.js";
 import { isLocked } from "./files.js";
 import { OAuthError, refresh } from "./oauth.js";
-/** Refresh this long before the access token runs out. */
 const EARLY_MS = 60_000;
-/** A hook starts a background refresh this long before the access token runs out, and goes on with the old one. */
 export const SOON_MS = 5 * 60_000;
-/** How long a hook waits for a background refresh when it has no working token. */
 export const REFRESH_WAIT_MS = 1200;
-/** An access token with less than this left isn't worth sending. */
 const USABLE_MS = 10_000;
-/** Not signed in on this computer (for this origin), or the sign-in ended: the person runs `pendingyou login`. */
 export class SignInNeeded extends Error {
     name = 'SignInNeeded';
     ended;
@@ -35,26 +14,19 @@ export class SignInNeeded extends Error {
         this.ended = ended;
     }
 }
-/** Pending You couldn't be reached, or had a problem: worth trying again later. */
 export class Unavailable extends Error {
     name = 'Unavailable';
-    /** Seconds the server asked to wait, when it said. */
     retryAfter;
     constructor(message, retryAfter) {
         super(message);
         this.retryAfter = retryAfter;
     }
 }
-/**
- * Refreshes the sign-in under the lock unless it no longer needs it: a token with more than `earlyMs` left (or, when
- * `force`d after a 401, a refresh token another process already replaced) is used as it is.
- */
 async function refreshStored(io, origin, stored, options, app) {
     let ended = false;
     const updated = await updateCredential(io, origin, async (current) => {
         if (!current)
             return null;
-        // Another process may have refreshed while this one waited for the lock.
         if (current.refreshToken !== stored.refreshToken && current.expiresAt - EARLY_MS > io.now())
             return current;
         if (!options.force && current.expiresAt - options.earlyMs > io.now())
@@ -84,7 +56,6 @@ async function freshToken(io, origin, force, app) {
         return stored.accessToken;
     return (await refreshStored(io, origin, stored, { force, earlyMs: EARLY_MS }, app)).accessToken;
 }
-/** What a process starts to refresh an app's sign-in in the background: `--app` only for an app but Claude Code. */
 export const refreshArgs = (origin, app, force = false) => [
     'refresh',
     '--origin',
@@ -92,10 +63,6 @@ export const refreshArgs = (origin, app, force = false) => [
     ...(app === DEFAULT_APP ? [] : ['--app', app]),
     ...(force ? ['--force'] : []),
 ];
-/**
- * `pendingyou refresh`, what a hook starts in the background: refreshes the sign-in when it runs out within SOON_MS
- * (or `force`, after a 401), under the lock, to the end. Quiet; true when there's a sign-in afterwards.
- */
 export async function refreshInBackground(io, origin, force, app = DEFAULT_APP) {
     const stored = await readCredential(io, origin, app);
     if (!stored)
@@ -105,7 +72,6 @@ export async function refreshInBackground(io, origin, force, app = DEFAULT_APP)
     await refreshStored(io, origin, stored, { force, earlyMs: SOON_MS }, app);
     return true;
 }
-/** A hook's token: never refreshed here (see the top of this file). */
 async function hookToken(io, origin, force, signal, app) {
     const stored = await readCredential(io, origin, app);
     if (!stored)
@@ -113,10 +79,8 @@ async function hookToken(io, origin, force, signal, app) {
     const left = stored.expiresAt - io.now();
     if (!force && left > SOON_MS)
         return stored.accessToken;
-    // One refresher at a time: a lock held now is a refresh (or a write) already under way.
     if (!(await isLocked(credentialsPath(io))))
         io.background(refreshArgs(origin, app, force));
-    // Still good for a few seconds: this request goes with it, the next one with the new token.
     if (!force && left > USABLE_MS)
         return stored.accessToken;
     const until = io.now() + REFRESH_WAIT_MS;
@@ -130,14 +94,6 @@ async function hookToken(io, origin, force, signal, app) {
     }
     throw new Unavailable('The sign-in is being refreshed in the background.');
 }
-/**
- * The token `pendingyou mcp-headers` hands an app's MCP server (remote.ts), and the stdio bridge sends with each
- * message (bridge.ts). The app runs the helper each time it connects and gives it 10 seconds, and the bridge may be
- * stopped at any moment, so, as for a hook, a refresh is never made in this process: within 5 minutes of expiry it
- * starts `pendingyou refresh` detached and waits for its token, up to `waitMs`, then uses the old one while it still
- * works. A token handed over has at least 10 seconds left; the app runs the helper again on a 401. `force` (the bridge,
- * after a 401) refreshes whatever the expiry says, and hands over only the new token.
- */
 export async function helperToken(io, origin, waitMs, app = DEFAULT_APP, force = false) {
     const stored = await readCredential(io, origin, app);
     if (!stored)
@@ -159,7 +115,6 @@ export async function helperToken(io, origin, waitMs, app = DEFAULT_APP, force =
         return stored.accessToken;
     throw new Unavailable('Pending You couldn’t be reached to refresh the sign-in.');
 }
-/** Aborts on `signal` or after `ms`, whichever comes first (AbortSignal.any needs Node 20.3). */
 function either(signal, ms) {
     const timeout = AbortSignal.timeout(ms);
     if (!signal)
@@ -172,11 +127,6 @@ function either(signal, ms) {
     timeout.addEventListener('abort', abort, { once: true });
     return controller.signal;
 }
-/**
- * GETs `path` on `origin` as the command line, with an app's sign-in (Claude Code's unless `app` says), and returns the
- * JSON body with its status. 401 after a refresh means the sign-in is over (revoked, or 30 days passed). Network
- * failures and 5xx are `Unavailable`.
- */
 export async function getJson(io, origin, path, timeoutMs, signal, options = {}) {
     const app = options.app ?? DEFAULT_APP;
     for (let attempt = 0;; attempt++) {
@@ -222,3 +172,30 @@ export async function getJson(io, origin, path, timeoutMs, signal, options = {})
         return { status: response.status, body };
     }
 }
+export async function postJson(io, origin, path, body, timeoutMs, options = {}) {
+    const app = options.app ?? DEFAULT_APP;
+    const token = await hookToken(io, origin, options.force === true, options.signal, app);
+    let response;
+    try {
+        response = await io.fetch(`${origin}${path}`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${token}`,
+                'content-type': 'application/json',
+                accept: 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: either(options.signal, timeoutMs),
+            redirect: 'manual',
+        });
+    }
+    catch {
+        throw new Unavailable('Pending You couldn’t be reached.');
+    }
+    await response.body?.cancel().catch(() => { });
+    const retry = Number(response.headers.get('retry-after'));
+    return {
+        status: response.status,
+        ...(Number.isFinite(retry) && retry > 0 ? { retryAfter: retry } : {}),
+    };
+}