@popoverinstall/cli 0.9.0 → 0.10.0

package/package.json

@@ -1,47 +1,47 @@
-{
-  "name": "@popoverinstall/cli",
-  "version": "0.9.0",
-  "description": "See your teammates' active Claude Code agents and ask them questions.",
-  "keywords": [
-    "claude",
-    "claude-code",
-    "agents",
-    "team",
-    "collaboration",
-    "cli"
-  ],
-  "type": "module",
-  "license": "MIT",
-  "homepage": "https://github.com/many-ideations/popover",
-  "bugs": "https://github.com/many-ideations/popover/issues",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/many-ideations/popover.git",
-    "directory": "packages/cli"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "main": "./dist/index.js",
-  "bin": {
-    "popover": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "plugin",
-    ".claude-plugin",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "build": "tsc -b",
-    "prepack": "node ../../scripts/stage-plugin.mjs && tsc -b"
-  },
-  "dependencies": {
-    "@popoverinstall/daemon": "0.9.0",
-    "@popoverinstall/shared": "0.9.0"
-  }
-}
+{
+  "name": "@popoverinstall/cli",
+  "version": "0.10.0",
+  "description": "See your teammates' active Claude Code agents and ask them questions.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agents",
+    "team",
+    "collaboration",
+    "cli"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/many-ideations/popover",
+  "bugs": "https://github.com/many-ideations/popover/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/many-ideations/popover.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "bin": {
+    "popover": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "plugin",
+    ".claude-plugin",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "prepack": "node ../../scripts/stage-plugin.mjs && tsc -b"
+  },
+  "dependencies": {
+    "@popoverinstall/daemon": "0.10.0",
+    "@popoverinstall/shared": "0.10.0"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -1,19 +1,19 @@
-{
-  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
-  "name": "popover",
-  "displayName": "Popover",
-  "description": "See your teammates' active Claude Code agents and ask them questions. A read-only fork answers from the agent's full context without interrupting your teammate.",
-  "version": "0.9.0",
-  "author": {
-    "name": "Quolabs"
-  },
-  "homepage": "https://github.com/many-ideations/popover",
-  "repository": "https://github.com/many-ideations/popover",
-  "license": "MIT",
-  "keywords": [
-    "team",
-    "collaboration",
-    "agents",
-    "mcp"
-  ]
-}
+{
+  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
+  "name": "popover",
+  "displayName": "Popover",
+  "description": "See your teammates' active Claude Code agents and ask them questions. A read-only fork answers from the agent's full context without interrupting your teammate.",
+  "version": "0.10.0",
+  "author": {
+    "name": "Quolabs"
+  },
+  "homepage": "https://github.com/many-ideations/popover",
+  "repository": "https://github.com/many-ideations/popover",
+  "license": "MIT",
+  "keywords": [
+    "team",
+    "collaboration",
+    "agents",
+    "mcp"
+  ]
+}

package/plugin/commands/ask.md

@@ -1,5 +1,5 @@
 ---
-description: Ask a teammate's agent a question and wait for the answer — it runs on their machine, at their cost
+description: Deprecated, use /popover:message — ask a teammate's agent a question and wait for the answer
 # Quoted because an unquoted value starting with `[` is parsed as a YAML flow sequence,
 # which fails and silently drops EVERY field here, allowed-tools included.
 argument-hint: "[agent-handle] <question>"
@@ -10,6 +10,14 @@ allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popov
 
 The user ran `/popover:ask`. Arguments, which may be empty: **$ARGUMENTS**
 
+> **Deprecated as of 0.10.0. `/popover:message` does this and more.** Everything below
+> still runs: the user typed this, so carry it out rather than answering with a
+> correction, and mention the newer command once at the end in a single line. It
+> supersedes this one because choosing between asking and telling was never the user's
+> decision to make — it turns on what the target agent is doing at that second, which the
+> daemon knows and the person typing does not (`docs/messages.md` §1). A message also
+> threads, so the answer can be replied to and replied to again, where an ask ends.
+
 Only agents working in **this repo** are reachable. A teammate running Claude Code in a
 different repository is neither listed nor askable, so "nobody to ask" means nobody else is
 working *here* — not that the team is idle. Say it that way if it comes up.
@@ -28,12 +36,13 @@ Stop there. Do not ask anything on the user's behalf.
 Call `mcp__plugin_popover_popover__team_ask` with:
 
 - `target`: the handle or name they used, exactly as typed
-- `question`: the rest of their message, as a **self-contained** question. The answering agent
-  has none of this conversation — it cannot see the file you are looking at or the error you
-  just read. Expand every pronoun and vague reference ("that bug" → "the token refresh bug in
-  the auth service"), name files by path, and say what the user is trying to do rather than
-  only what they want to know. One well-formed question, not three exploratory ones: you get
-  one round trip for the price.
+- `question`: the rest of their message, as a **self-contained** question. The answering
+  agent has none of this conversation: it cannot see the file you are looking at or the error
+  you just read. Expand every pronoun and vague reference ("that bug" → "the token refresh
+  bug in the auth service"), name files by path, and say what the user is trying to do rather
+  than only what they want to know. Then stop, at whatever length that took. You are not
+  spending your only round trip, so there is nothing to buy by padding it out — a follow-up
+  is available and cheaper than it looks.
 
 When the answer comes back, show it clearly attributed:
 
@@ -57,8 +66,8 @@ Call `mcp__plugin_popover_popover__team_list` first. Then:
   rather than guessing at another agent.
 - **One agent per question.** Never fan out across the roster to see who answers best.
 - An answer comes from a **read-only copy** of their session. Their live session is not
-  interrupted and cannot be modified by an ask. It costs the teammate tokens on their own
-  machine, and nothing else.
+  interrupted or modified while it answers, and is told afterwards what was asked. It costs
+  the teammate tokens on their own machine, and nothing else.
 - If the tool errors or times out, relay it plainly. Do not silently re-ask, and do not retry
   a different agent unless the user asks.
 - If the user is trying to hand a colleague *work* rather than get an answer, say plainly that

package/plugin/commands/message.md

@@ -0,0 +1,152 @@
+---
+description: Message a teammate's agent and carry on the thread — the system picks how it reaches them
+# Quoted because an unquoted value starting with `[` is parsed as a YAML flow sequence,
+# which fails and silently drops EVERY field here, allowed-tools included.
+argument-hint: "[agent-handle] <message>"
+allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popover__team_message, AskUserQuestion
+---
+
+# Message a teammate's agent
+
+The user ran `/popover:message`. Arguments, which may be empty: **$ARGUMENTS**
+
+This is the one verb for reaching another agent, and it replaces `/popover:ask` and
+`/popover:tell`. Those still work and are still carried out; they are deprecated because the
+difference between them was never the user's to decide. Whether a message is answered by the
+live session or by a read-only copy of it depends on what that agent is doing at this second
+— a fact the daemon holds and the person typing does not. See `docs/messages.md` §1.
+
+So **never say which transport will be used before you send.** The tool reports which one
+carried it afterwards, and that is the only honest moment to mention it.
+
+Only agents working in **this repo** are reachable. A teammate running Claude Code in a
+different repository is neither listed nor reachable, so "nobody to message" means nobody
+else is working *here* — not that the team is idle. Say it that way if it comes up.
+
+## No arguments
+
+Call `mcp__plugin_popover_popover__team_list`, print what it returns **verbatim** in a fenced
+block, and show the form:
+
+`/popover:message B1 is the repo_keys migration applied on prod?`
+
+Stop there. Do not message anyone on the user's behalf.
+
+## A handle and a message
+
+If this conversation has no open thread with that agent, **confirm before opening one — and
+say what opening it will cost.**
+
+Look first at what that agent is doing. `mcp__plugin_popover_popover__team_list` already
+returns it, so this needs no round trip and costs nothing; call it if you have not this turn.
+Their state decides how the first message travels, which is the one thing that turns this
+confirmation from a formality into a decision the user can actually make:
+
+- **working** — "B1 is working right now, so this will interrupt them mid-task."
+- **idle** — "B1 is idle; a read-only copy of their session will answer at their expense."
+- **waiting** — the same line as *idle*. Their agent is blocked asking its own human
+  something, so no turn is running and nothing gets interrupted. The name reads as though it
+  were the busy case and it is not (`docs/messages.md` §4).
+- **offline** — do not confirm anything. They are unreachable; say so and stop.
+
+Then call `AskUserQuestion` with exactly two options, so Esc cancels:
+
+- **Open the thread** — "<the state line above> They can reply, and you can reply to that,
+  without me asking you again."
+- **Don't** — "Leave it"
+
+Two things about that wording, and neither is decoration (`docs/messages.md` §2, §2.1):
+
+- **The consent is to the channel, not to one delivery.** The user is agreeing to a
+  conversation with that colleague, which is precisely why they are not asked again for the
+  second message — opening the channel is the deliberate act, and no human re-consents to a
+  conversation per sentence. Word it that way rather than as a one-off send, or the promise
+  not to ask again will read as something you took rather than something they gave.
+- **The state line is true of the first message and is not a promise about the thread.**
+  Routing is decided per message, so a thread opened against an idle agent may reach a
+  working one ten minutes later and spend the other kind of cost. Say what the first message
+  will do and stop there. Do not claim the whole conversation is priced, because it is not.
+
+On a yes, call `mcp__plugin_popover_popover__team_message` with:
+
+- `target`: the handle or name they used, exactly as typed
+- `body`: the rest of their message, made **self-contained**. The first message on a thread
+  arrives with none of this conversation attached: the recipient cannot see the file you are
+  looking at or the error you just read. Expand every pronoun and vague reference ("that
+  bug" → "the token refresh bug in the auth service"), name files by path, and say what the
+  user is trying to do rather than only what they want to know.
+
+Write it at whatever length it takes and stop there. There is no length to hit in either
+direction and none is prescribed — a message of six words is a good message when six words
+are the message, and a follow-up is available, so nothing is bought by padding.
+
+Then report what came back:
+
+- **An answer** — show it attributed, `> **B1** (Bob Chen, api-server): …answer…`, and say
+  how it bears on the work in hand, if it does.
+- **No answer on this call** — the message reached a live session mid-task. Say so in one
+  line and carry on. A reply, if they send one, arrives later rather than never: it comes
+  back through `team_receipts` as a `kind: "thread"` record, announced by a line your own
+  daemon prints (`docs/messages.md` §4.1). So do not wait on it and do not send the message
+  again — but do read it when you are told it is there, because that one may have somebody
+  waiting on the other end.
+
+Either way, keep the thread id the tool returned. It is how the conversation continues.
+
+## A message with no handle
+
+Call `mcp__plugin_popover_popover__team_list` first. Then:
+
+- If exactly one agent plausibly fits, name it in the confirmation above and say why you
+  picked it — the user still gets a yes or no, with the cost line, before anything is sent.
+- If several fit, call `AskUserQuestion` with up to 4 of them as options (label = the handle,
+  description = owner, repo, and whether messaging it interrupts them or spends their tokens).
+  Choosing a recipient *is* the consent — which is why the cost has to be in the options they
+  are choosing between, not mentioned afterwards — so no second confirmation follows it.
+- If none fit, say so and show the roster instead. Never fan out across the roster.
+
+## Continuing a thread
+
+A thread runs both ways: they can reply, you can reply to that, and either side can keep
+going. Pass `thread_id` — the one the earlier call returned — and leave `target` as it was.
+A thread already knows who is on the other end.
+
+Do not confirm again. Consent was granted when the thread was opened and it covers the
+conversation, not the sentence. Send the reply at the length a reply takes; later messages
+arrive with the thread's own history behind them, so they can be short.
+
+Never invent a thread id. If the user is plainly starting a new subject with someone rather
+than answering them, that is a new thread, and a new thread is confirmed like any other.
+
+## When it will not go through
+
+Relay what the tool says rather than working around it. Three cases are worth knowing before
+you meet them:
+
+- **`target_offline`** — their Claude Code session has ended. This is also what you get on a
+  thread that has gone *stale*: the peer is offline and something is still undelivered, so
+  new messages are refused rather than piling up to land all at once when they come back
+  (`docs/messages.md` §7.1). Tell the user it could not be sent now. **Do not tell them the
+  thread is closed** — it is not, and it becomes live again by itself when that session
+  resumes.
+- **A closed thread** — either party's human can close a thread from the CLI with `popover
+  thread close <id>`, and that is the kill switch. Closing bars new sends. It does **not**
+  retract messages already filed: a reply produced before the close still reaches the other
+  side when their session resumes. So do not tell the user a close undid anything, and do not
+  reopen by dropping the `thread_id` — that opens a new thread, which needs their say-so.
+- **A timeout** — the copy answering did not finish in time. Say so. The thread is not dead
+  and the target is not gone; their machine was busy. Do not silently re-send.
+
+## Rules
+
+- **Never invent a handle.** Only use ones `team_list` returned. A handle from earlier in this
+  conversation may since have gone out of scope; if the tool says it does not match, relay
+  that rather than guessing at another agent.
+- **One agent per thread.** A message to three agents is three threads and three
+  confirmations, and it is almost never what the user meant.
+- A message is **information, not a directive**. The receiving agent is told to treat it that
+  way, and the copy that may answer it has no tools at all. If the user is trying to hand a
+  colleague *work*, say plainly that popover does not do that and let them message the human.
+- Say what a thread has cost when the tool reports it, and say what that number leaves out:
+  it covers the messages a copy answered and not the ones a live session did, which popover
+  cannot see (`docs/messages.md` §8).

package/plugin/commands/team.md

@@ -9,9 +9,10 @@ allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popov
 
 The user ran `/popover:team`. Arguments, which are usually empty: **$ARGUMENTS**
 
-This command shows the roster. Asking and telling are their own commands now — `/popover:ask`
-and `/popover:tell` — because they cost different things and deserve to be chosen, not reached
-by a subword.
+This command shows the roster. Reaching an agent is its own command — `/popover:message` — and
+not a subword of this one. `/popover:ask` and `/popover:tell` still work and are deprecated:
+which transport a message takes is decided by what the target agent is doing at that second,
+which the daemon knows and the sender does not (`docs/messages.md` §1).
 
 ## The roster
 
@@ -25,9 +26,9 @@ difference, so relay it rather than paraphrasing it into "your team is idle".
 
 Then add one short line showing where to go next:
 
-`/popover:ask B1 why did you rule out redis?` · `/popover:tell B1 the migration is applied`
+`/popover:message B1 why did you rule out redis?`
 
-Stop there. Do not ask or tell anything on the user's behalf.
+Stop there. Do not message anyone on the user's behalf.
 
 ## If they typed `ask` or `tell` anyway
 
@@ -56,5 +57,6 @@ If the tool errors or times out, relay it plainly rather than retrying or trying
 - Asking costs the *teammate* money and runs on *their* machine. Telling costs their attention
   and notifies them. One agent per request either way.
 - An answer comes from a read-only copy of their session. Their live session is not interrupted
-  and cannot be modified by an ask. A tell **is** delivered into their live session, before its
-  next prompt — that is the one thing in popover that reaches a running agent.
+  or modified while it answers; it is told afterwards what was asked. A tell **is** delivered
+  into their live session, before its next prompt — and it is the only thing in popover a
+  teammate can aim *at* a running agent, which is why it is the one that asks first.

package/plugin/commands/tell.md

@@ -1,5 +1,5 @@
 ---
-description: Send a short heads-up into a teammate's live session — no answer comes back, and they are notified
+description: Deprecated, use /popover:message — send a short heads-up into a teammate's live session
 # Quoted because an unquoted value starting with `[` is parsed as a YAML flow sequence,
 # which fails and silently drops EVERY field here, allowed-tools included.
 argument-hint: "[agent-handle] <message>"
@@ -10,6 +10,14 @@ allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popov
 
 The user ran `/popover:tell`. Arguments, which may be empty: **$ARGUMENTS**
 
+> **Deprecated as of 0.10.0. Use `/popover:message`.** Everything below still runs — carry
+> out what the user asked for, then name the newer command once at the end. A tell was the
+> half of the surface that reached a *live* session, and which half you wanted was never a
+> question worth putting to a person: `/popover:message` routes there by itself when the
+> target is mid-turn (`docs/messages.md` §1, §4). Two things also change with it. Consent
+> is confirmed once when a thread is opened rather than for every sentence (§2), and a
+> message can be answered, where a tell is one-way by construction.
+
 A tell is the one thing in popover that reaches a **running** agent: it is delivered into a
 teammate's live session before its next prompt, and their user is notified. It costs a
 colleague's attention rather than their tokens, which is why it is its own command and why the
@@ -60,7 +68,8 @@ If none fit, show the roster instead. Never broadcast to several agents.
   give another agent a task, say so and offer `/popover:ask` instead — or suggest they message
   the human.
 - **Never invent a handle**, and do not fan out to several agents unless asked in as many words.
-- Rate limited to 10 messages an hour to any one agent, which is a hint about its intended
-  frequency. If the limit is hit, relay that rather than retrying.
+- **Nothing throttles this but you.** The bar for sending is the whole of the protection, so
+  carry it rather than expecting to be stopped at some number. If the tool refuses a message,
+  relay the refusal rather than retrying it.
 - If it is genuinely ambiguous whether the user meant to ask or tell, prefer **`/popover:ask`**
   — it interrupts nobody.

package/plugin/commands/vault.md

@@ -125,18 +125,37 @@ user would rather type them there.)
 
 ## Vaulting without being asked
 
-**You decide.** This is the one place in popover where you may act on your own judgement: you
-may create a vault because you concluded the conversation was worth keeping, and you do not
-need permission first. Say what you are doing and why, in a line — the user should never be
-surprised — but do not ask for a yes before you start.
-
-That is a deliberate departure from `/popover:fork`, where you may raise the idea and only
-the user may act on it, and it is taken with that rule in full view. A fork discloses one
+**You decide, and the default is yes.** This is the one place in popover where you act on your
+own judgement rather than asking: you create a vault because you concluded the conversation
+was worth keeping, and you do not need permission first. Say what you are doing and why, in a
+line — the user should never be surprised — but do not ask for a yes before you start.
+
+### The moment is task completion
+
+Not some time later, and not when it occurs to you. When you finish a task, vault before you
+report completion. You have just built the thing, your grasp of the work is as good as it is
+ever going to get, the user is about to move on to something else, and everything in this
+conversation that the diff does not record is about to be deleted along with it.
+
+`docs/vaults.md` §3 fixes that as the trigger and records why it beat the obvious
+alternative. Vaulting on compaction was carried as an idea for a release, on the reasoning that
+a session is largest, and about to lose most of itself, at the moment it compacts. What retired
+it was selection rather than principle: compaction fires on the longest sessions, and a session
+is usually long because it wandered, not because it concluded anything worth asking later.
+Compaction says "this is about to be lost", which is urgency. Completion says "nobody is ever
+going to understand this better than right now", which is quality — and quality is what
+makes an archive worth asking rather than merely large.
+
+So the burden runs the other way from every other proactive act in popover. Elsewhere you ask
+first, or you offer and wait. Here you vault unless the exception below applies, because nobody
+is going to interrupt an afternoon of debugging to say "this should be archived", and if it
+waits for a prompt it does not happen.
+
+That reversal is a deliberate departure from `/popover:fork`, where you may raise the idea and
+only the user may act on it, and it is taken with that rule in full view. A fork discloses one
 conversation to one named individual. A vault publishes to a team that already shares the
 repository and the work, so the disclosure is small — and the cost of missing the moment is
-high, because the moment for a vault is one you are usually far too deep in the work to
-notice. Nobody is going to interrupt an afternoon of debugging to say "this should be
-archived". If it waits for a prompt, it does not happen.
+high.
 
 Vault when the conversation worked something out that the diff will not record:
 
@@ -151,9 +170,11 @@ Do **not** vault a conversation that only did what its diff says, a session with
 concluded in it, or one carrying secrets or a customer's data — a vault is readable by the
 service and outlives everyone in the room.
 
-Two failure modes make this rule wrong, and you should be watching for both in yourself:
-vaulting everything, which produces an index nobody trusts, and vaulting nothing, which is
-the ask-first rule's own failure wearing a different hat.
+With the default reversed, that exception is carrying all the weight, so hold it honestly
+rather than as a formality. Two failure modes make this rule wrong and you should be watching
+for both in yourself: vaulting everything, which produces an index nobody trusts, and vaulting
+nothing, which is the ask-first habit wearing a different hat. Reversing the default is what
+makes the archive exist at all; the exception is what keeps it worth asking.
 
 ## Rules
 

package/plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Publishes this machine's Claude Code session activity to the popover daemon.",
+  "description": "Publishes this machine's Claude Code session activity to the popover daemon, and tells the agent when teammates arrive or a task has just landed.",
   "hooks": {
     "SessionStart": [
       {
@@ -10,6 +10,12 @@
             "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-daemon.mjs"],
             "async": true,
             "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/nudge-vault.mjs"],
+            "timeout": 5
           }
         ]
       }
@@ -67,6 +73,18 @@
         ]
       }
     ],
+    "PostToolBatch": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/inject-message.mjs"],
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "Notification": [
       {
         "matcher": "agent_needs_input",
@@ -90,6 +108,12 @@
             "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
             "async": true,
             "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/nudge-vault.mjs"],
+            "timeout": 5
           }
         ]
       }